bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/BbTable.md

@@ -1,2515 +1,2146 @@
 # BbTable
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Data Display**
+- Description: Displays tabular data, configurable columns and data mapper.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbTable.md](./source/BbTable.md)
+
+## Usage & Guidelines
+
+### When to use
+
+Reach for `BbTable` to present **rows of records with columns** — an invoices
+listing, a members admin, an audit log. It owns extraction, formatting, loading
+skeletons, empty states, selection, sorting indicators, row expansion and
+keyboard navigation, so your markup stays a column definition plus a few slots.
+
+- For a **single-select or multi-select list of options** in a form, use
+  `BbSelect` / `BbCheckboxGroup` / `BbRadioGroup` — not a selectable table.
+- For **hierarchical, expandable nodes** (a file tree, nested categories), use
+  `BbTree`. Flat rows with one level of detail stay in `BbTable` (`#expand`).
+- `BbTable` is items-driven: read the Options/Items and Fetch playbooks. Pass
+  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
+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.
+
+### Columns: the full grammar
+
+A column is `{ key, label }` plus optional presentation — everything a cell
+needs is declared here, not in markup:
+
+- **`key`** extracts the cell from the item; dot paths reach nested fields
+  (`'customer.address.city'`). Keys autocomplete from the item type (up to 3
+  levels deep), but any string is accepted — that is how virtual columns work.
+- **`formatter(content, key, item)`** transforms the extracted value. It runs
+  even when the value is nullish, so a virtual column whose `key` matches no
+  field can still compute from `item`; set `formatOnNull: false` when a
+  formatter must only see real values.
+- **`placeholder`** fills the cell when the pipeline still ends nullish.
+- **`align`** (`'left' | 'center' | 'right'`) per column; the table-level
+  `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.
+- **`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
+  `(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
+  Nested tables.
+
+**Columns, formatters and a per-row class**
 
 ```vue
 <template>
-	<component
-		:is="containerTag"
-		:id="id"
-		ref="containerRef"
-		:aria-busy="loading"
-		:aria-rowcount="hasProvidedAccessibilityData ? props.totalItems : undefined"
-		:class="containerClass"
-		:data-bb-table-id="tableId"
-		:inert="disabled"
-		:style="containerStyle"
+	<div
+		class="max-w-2xl overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
 	>
-		<legend v-if="selectable" class="sr-only">{{ legend }}</legend>
-		<table ref="tableRef">
-			<caption
-				v-if="caption"
-				:class="{
-					'bb-table-caption': true,
-					'sr-only': !displayCaption,
-				}"
-			>
-				{{
-					caption
-				}}
-			</caption>
-			<colgroup>
-				<col
-					v-for="track in columnTracks"
-					:key="track.key"
-					:style="{ width: track.width }"
-				/>
-			</colgroup>
-			<thead>
-				<!-- @vue-ignore -->
-				<slot name="thead">
-					<tr
-						:aria-rowindex="hasProvidedAccessibilityData ? 1 : undefined"
-						class="bb-table-header-row"
-					>
-						<th
-							v-if="selectable"
-							class="bb-table-header bb-table-header--select"
-							:class="thClass"
-							scope="col"
-						>
-							<!-- @vue-ignore -->
-							<slot
-								:multiple="multiple"
-								:name="'header:select'"
-								:select-all="!!selectAll"
-								:text="selectText || t('table.selectText').value"
-							>
-								<span class="bb-table-header__content">
-									<label
-										v-if="allowSelectAll && multiple"
-										class="bb-table-check__label"
-										:class="{
-											'bb-table-check__label--disabled': disabled,
-										}"
-									>
-										<BaseCheckbox
-											:key="indeterminate.toString()"
-											v-model="selectAll"
-											class="bb-table-check"
-											:disabled="disabled"
-											:indeterminate="indeterminate"
-											:name="`select_all_${name || ''}`"
-											:readonly="readonly"
-										/>
-										<span class="bb-table-check__label-text sr-only"
-											>{{ selectAllLabel || t('table.selectAllLabel').value }}
-										</span>
-									</label>
-									<span
-										v-else-if="!multiple"
-										class="bb-table-radio__label-text sr-only"
-										>{{ selectText || t('table.selectText').value }}</span
-									>
-								</span>
-							</slot>
-						</th>
-						<th
-							v-for="(header, index) in mappedHeaders"
-							:key="header.key"
-							:aria-sort="header.sortDirection"
-							class="bb-table-header"
-							:class="[
-								header.classes,
-								{
-									'bb-table-header--edge-start': index === 0,
-									'bb-table-header--edge-end':
-										index === mappedHeaders.length - 1,
-								},
-							]"
-							scope="col"
-						>
-							<!-- @vue-ignore -->
-							<slot
-								:classes="header.classes"
-								:items="internalItems"
-								:label="header.label"
-								:name="header.slotName"
-								><span class="bb-table-header__content">{{
-									header.label
-								}}</span></slot
-							>
-						</th>
-						<th
-							v-if="actions"
-							class="bb-table-header bb-table-header--actions"
-							:class="thClass"
-							scope="col"
-						>
-							<!-- @vue-ignore -->
-							<slot name="header:actions" :text="actionsText">
-								<span class="bb-table-header__content sr-only">
-									{{ actionsText }}
-								</span>
-							</slot>
-						</th>
-					</tr>
-				</slot>
-			</thead>
-			<tbody>
-				<slot v-if="loading" :items="internalItems" name="loading">
-					<template v-for="(_, rowIndex) in skeletonLength" :key="rowIndex">
-						<tr
-							:aria-rowindex="
-								hasProvidedAccessibilityData ? rowIndex + 2 : undefined
-							"
-							class="bb-table-skeleton__row"
-						>
-							<td
-								v-if="selectable"
-								class="bb-table-skeleton__cell bb-table-skeleton__cell--select"
-							>
-								<div class="bb-table-skeleton__placeholder" />
-							</td>
-							<td
-								v-for="(col, colIndex) in props.columns"
-								:key="col.key"
-								:class="[
-									'bb-table-skeleton__cell',
-									`bb-table-skeleton__cell--${col.skeleton ?? 'text'}`,
-								]"
-							>
-								<!-- text: 2 lines with dynamic widths -->
-								<template v-if="!col.skeleton || col.skeleton === 'text'">
-									<div class="bb-table-skeleton__cell-content">
-										<div
-											class="bb-table-skeleton__line"
-											:style="{
-												width: `${skeletonLineWidths[(rowIndex + colIndex) % 4]}%`,
-											}"
-										/>
-										<div
-											class="bb-table-skeleton__line"
-											:style="{
-												width: `${skeletonLineWidths[(rowIndex + colIndex + 2) % 4]}%`,
-											}"
-										/>
-									</div>
-								</template>
-								<!-- avatar: circle only -->
-								<div
-									v-else-if="col.skeleton === 'avatar'"
-									class="bb-table-skeleton__avatar"
-								/>
-								<!-- avatar-text: avatar + 2 lines -->
-								<div
-									v-else-if="col.skeleton === 'avatar-text'"
-									class="bb-table-skeleton__avatar-text"
-								>
-									<div class="bb-table-skeleton__avatar" />
-									<div class="bb-table-skeleton__cell-content">
-										<div
-											class="bb-table-skeleton__line"
-											:style="{
-												width: `${skeletonLineWidths[(rowIndex + colIndex) % 4]}%`,
-											}"
-										/>
-										<div
-											class="bb-table-skeleton__line"
-											:style="{
-												width: `${skeletonLineWidths[(rowIndex + colIndex + 2) % 4]}%`,
-											}"
-										/>
-									</div>
-								</div>
-								<!-- image: rounded rect -->
-								<div
-									v-else-if="col.skeleton === 'image'"
-									class="bb-table-skeleton__image"
-								/>
-								<!-- badge: small pill -->
-								<div
-									v-else-if="col.skeleton === 'badge'"
-									class="bb-table-skeleton__badge"
-								/>
-							</td>
-							<td
-								v-if="actions"
-								class="bb-table-skeleton__cell bb-table-skeleton__cell--actions"
-							>
-								<div class="bb-table-skeleton__placeholder" />
-							</td>
-						</tr>
-					</template>
-					<tr
-						:aria-rowindex="
-							hasProvidedAccessibilityData ? skeletonLength + 2 : undefined
-						"
-						class="bb-table-loading__row bb-table-loading__row--sr-only"
-					>
-						<td
-							:colspan="replacementContentSpan"
-							class="bb-table-loading__cell"
-							aria-live="polite"
-							role="status"
-						>
-							<span class="bb-table-loading__text sr-only">{{
-								loadingText
-							}}</span>
-						</td>
-					</tr>
-				</slot>
-				<slot v-else-if="!options.length" :name="'no-data'">
-					<tr
-						:aria-rowindex="hasProvidedAccessibilityData ? 2 : undefined"
-						class="bb-table-no-data__row"
-					>
-						<td
-							class="bb-table-no-data__cell"
-							:colspan="replacementContentSpan"
-						>
-							<span class="bb-table-no-data__text">{{
-								noDataText || t('table.noDataText').value
-							}}</span>
-						</td>
-					</tr>
-				</slot>
-				<slot v-else name="tbody">
-					<template v-for="item in mappedItems" :key="item.valueHash">
-						<tr
-							:aria-rowindex="
-								hasProvidedAccessibilityData && item.rowIndex
-									? item.rowIndex
-									: undefined
-							"
-							class="bb-table-data__row"
-							@click="item.onRowClick"
-							@contextmenu="item.onRowContextMenu"
-							@dblclick="item.onRowDblClick"
-						>
-							<td
-								v-if="selectable"
-								class="bb-table-data__cell bb-table-data__cell--select"
-								:class="tdClass"
-							>
-								<!-- @vue-ignore -->
-								<slot
-									:checked="isSelected(item)"
-									:disabled="!!item.disabled"
-									:input-name="randomName"
-									:item="item.item"
-									:name="'select'"
-									:readonly="!!readonly"
-									:value="item.value"
-								>
-									<!-- We use temp names for these inputs because we don't submit them -->
-									<label
-										v-if="multiple"
-										class="bb-table-check__label"
-										:class="{
-											'bb-table-check__label--disabled': item.disabled,
-										}"
-									>
-										<BaseCheckbox
-											:checked="isSelected(item)"
-											class="bb-table-check"
-											:disabled="item.disabled"
-											:readonly="readonly"
-											@change="() => onInputChange(item)"
-										/>
-										<span class="bb-table-check__label-text sr-only">{{
-											item.accessibleLabel
-										}}</span>
-									</label>
-
-									<label
-										v-else
-										class="bb-table-radio__label"
-										:class="{
-											'bb-table-radio__label--disabled': item.disabled,
-										}"
-									>
-										<BaseRadio
-											:checked="item.selected"
-											class="bb-table-radio"
-											:disabled="item.disabled"
-											:name="randomName"
-											:readonly="readonly"
-											:value="item.value"
-											@change="() => onInputChange(item)"
-										/>
-										<span class="bb-table-radio__label-text sr-only">{{
-											item.accessibleLabel
-										}}</span>
-									</label>
-								</slot>
-							</td>
-							<td
-								v-for="(col, colIndex) in item.cols"
-								:key="col.key"
-								class="bb-table-data__cell"
-								:class="[
-									col.classes,
-									{
-										'bb-table-data__cell--edge-start': colIndex === 0,
-										'bb-table-data__cell--edge-end':
-											colIndex === item.cols.length - 1,
-									},
-								]"
-							>
-								<!-- @vue-ignore -->
-								<slot
-									:classes="col.classes"
-									:content="col.content"
-									:expanded="item.expanded"
-									:item="item.item"
-									:name="col.slotName"
-									:expand-props="getExpandControllerProps(item)"
-									:toggle-expanded="() => toggleExpandedFor(item.valueHash)"
-									:value="item.value"
-									>{{ col.content }}</slot
-								>
-							</td>
-							<td
-								v-if="actions"
-								class="bb-table__cell bb-table__cell--actions"
-								:class="tdClass"
-							>
-								<!-- @vue-ignore -->
-								<slot
-									:expanded="item.expanded"
-									:item="item.item"
-									:name="'actions'"
-									:expand-props="getExpandControllerProps(item)"
-									:toggle-expanded="() => toggleExpandedFor(item.valueHash)"
-									:value="item.value"
-								></slot>
-							</td>
-						</tr>
-						<tr
-							v-if="item.expanded"
-							:aria-rowindex="
-								hasProvidedAccessibilityData && item.rowIndex
-									? item.rowIndex + 1
-									: undefined
-							"
-							:id="`expanded_${item.valueHash}`"
-							class="bb-table-expand__row"
-						>
-							<td
-								:colspan="replacementContentSpan"
-								class="bb-table-expand__cell"
-							>
-								<!-- @vue-ignore -->
-								<slot
-									:expanded="item.expanded"
-									:item="item.item"
-									:name="'expand'"
-									:expand-props="getExpandControllerProps(item)"
-									:toggle-expanded="() => toggleExpandedFor(item.valueHash)"
-									:value="item.value"
-								></slot>
-							</td>
-						</tr>
-					</template>
-				</slot>
-			</tbody>
-			<tfoot>
-				<!-- @vue-ignore -->
-				<slot name="tfoot"></slot>
-			</tfoot>
-		</table>
-		<input v-for="input in hiddenInputs" :key="input.value" v-bind="input" />
-	</component>
+		<BbTable
+			caption="Recent invoices"
+			:columns="columns"
+			compact
+			item-value="id"
+			:items="invoices"
+			:row-class="rowClass"
+		/>
+	</div>
 </template>
-
-<script
-	setup
-	lang="ts"
-	generic="Item = any, T extends ItemKey<Item> = string & {}"
->
-import {
-	computed,
-	nextTick,
-	onBeforeUnmount,
-	onMounted,
-	reactive,
-	ref,
-	toRef,
-	watch,
-} from 'vue';
-import { clamp } from '@/utilities/functions/clamp';
-import { hash } from '@/utilities/functions/hash';
-import { isNil } from '@/utilities/functions/isNil';
-import { when } from '@/utilities/functions/when';
-import { useId } from '@/composables/useId';
-import { useItemValue } from '@/composables/useItemValue';
-import { useItemsGetter } from '@/composables/useItemsGetter';
-import { usePrefill } from '@/composables/usePrefill';
-import { useIndexById } from '@/composables/useIndexById';
-import { useBaseOptions } from '@/composables/useBaseOptions';
-import { useHashedWatcher } from '@/composables/useHashedWatcher';
-import { useTableWidthContext } from '@/composables/useTableWidthContext';
-import { useLocale } from '@/composables/useLocale';
-import BaseCheckbox from '../BaseCheckbox/BaseCheckbox.vue';
-import BaseRadio from '../BaseRadio/BaseRadio.vue';
-import type { Option as BaseOption } from '@/types/Option';
-import type { Classes } from '@/types/Classes';
-import type { ColumnName } from '@/types/ColumnName';
-import type { PrefixWith } from '@/types/PrefixWith';
-import type {
-	BbTableColumn,
-	BbTableEvents,
-	BbTableProps,
-	BbTableSlots,
-	ExpandControllerProps,
-	ItemKey,
-	MappedCell,
-	MappedHeader,
-	MappedItem,
-} from './types';
-import {
-	applyFixedTableColumns,
-	columnKeyToSlotName,
-	mergeCellClasses,
-	mergeHeaderClasses,
-} from './utils';
-import { useLogger } from '@/composables/useLogger';
-import { isEmpty } from '@/utilities/functions/empty';
-
-const { getItemValue } = useItemValue();
-
-/** Temporary name for selection inputs; hidden inputs handle real submission. */
-const randomName = useId().id.value;
-
-type InternalColumn<K extends string> = Omit<BbTableColumn<Item>, 'key'> & {
-	key: K;
-};
-
-type InternalProps<K extends string> = Omit<BbTableProps<Item>, 'columns'> & {
-	columns: InternalColumn<K>[];
+<script setup lang="ts">
+import { BbTable } from 'bitboss-ui';
+import type { BbTableColumn } from 'bitboss-ui';
+
+type Invoice = {
+	id: string;
+	number: string;
+	client: string;
+	issuedAt: string;
+	note: string | null;
+	amount: number;
+	status: 'paid' | 'pending' | 'overdue';
 };
 
-const props = withDefaults(defineProps<InternalProps<T>>(), {
-	align: 'left',
-	actionsText: 'Azioni',
-	allowSelectAll: true,
-	columns: () => [],
-	dependencies: () => [],
-	depsDebounceTime: 0,
-	fixedColumns: () => [],
-	items: () => [],
-	max: Infinity,
-	multiple: true,
-	modelValue: () => [],
-	unselectedItems: () => [],
+const euro = new Intl.NumberFormat('en-IE', {
+	style: 'currency',
+	currency: 'EUR',
 });
 
-const emit = defineEmits<BbTableEvents>();
-
-type InferredBodySlots = ColumnName<T>;
-type InferredHeaderSlots = PrefixWith<ColumnName<T>, 'header:'>;
-
-defineSlots<
-	BbTableSlots<Item> & {
-		[K in InferredBodySlots]?: (props: {
-			classes?: Classes;
-			content?: any;
-			expanded?: boolean;
-			expandProps?: ExpandControllerProps;
-			toggleExpanded?: () => void;
-			item: Item;
-			value?: any;
-		}) => any;
-	} & {
-		[K in InferredHeaderSlots]?: (props: {
-			classes?: Classes;
-			content?: any;
-			items?: Item[];
-			label?: string;
-		}) => any;
-	}
->();
-
-if (props.multiple && !Array.isArray(props.modelValue)) {
-	const logger = useLogger();
-	logger.throw(
-		'BbTable is set for multiple selection but modelValue is not an array.'
-	);
-}
-
-const { t } = useLocale();
-
-const tableRef = ref<HTMLTableElement>();
-const containerRef = ref<HTMLElement>();
-
-const {
-	id: tableId,
-	parentId,
-	parentNode,
-	cssVars,
-	parentVar,
-	setTracks,
-} = useTableWidthContext({
-	id: () => props.id,
-	container: () => containerRef.value,
-	inheritFrom: () =>
-		typeof props.inheritColumnWidths === 'string'
-			? props.inheritColumnWidths
-			: undefined,
-});
+// Columns declare extraction (`key`), formatting (`formatter`), alignment and a
+// fixed `width`. `placeholder` fills in when a cell resolves to nullish.
+const columns: Array<BbTableColumn<Invoice>> = [
+	{ key: 'number', label: 'Invoice', width: 110 },
+	{ key: 'client', label: 'Client' },
+	{
+		key: 'issuedAt',
+		label: 'Issued',
+		width: 100,
+		formatter: (value: string) => new Date(value).toLocaleDateString('en-GB'),
+	},
+	{ key: 'note', label: 'Note', placeholder: '—' },
+	{
+		key: 'amount',
+		label: 'Amount',
+		align: 'right',
+		width: 110,
+		formatter: euro.format,
+	},
+];
 
-/** Any column pinned to a parent track range — a per-column inherit signal. */
-const hasSnap = computed(() => props.columns.some((c) => c.snap != null));
+const invoices: Invoice[] = [
+	{
+		id: 'inv-1041',
+		number: 'INV-1041',
+		client: 'Northwind Traders',
+		issuedAt: '2026-06-02',
+		note: 'Retainer',
+		amount: 4200,
+		status: 'paid',
+	},
+	{
+		id: 'inv-1042',
+		number: 'INV-1042',
+		client: 'Globex',
+		issuedAt: '2026-06-11',
+		note: null,
+		amount: 980.5,
+		status: 'pending',
+	},
+	{
+		id: 'inv-1043',
+		number: 'INV-1043',
+		client: 'Initech',
+		issuedAt: '2026-05-19',
+		note: 'Overage',
+		amount: 15600,
+		status: 'overdue',
+	},
+];
+
+// `row-class` is applied to each `<tr>`; 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'
+		? 'bg-[color:color-mix(in_oklab,#d97706_8%,var(--bb-panel))]'
+		: '';
+</script>
+```
 
-// Opt-in: inherit when explicitly enabled (`true`, or an ancestor id string),
-// or implicitly when any column carries a `snap` — a snap only resolves against
-// a parent's tracks, so asking for one is asking to inherit. An absent prop with
-// no snaps does not inherit, so a plain nested table stays independent. An
-// explicit `false` is authoritative and overrides the implicit snap signal.
-const inheritColumnWidths = computed(
-	() => !!props.inheritColumnWidths || hasSnap.value
-);
+A virtual column has a `key` that matches nothing and derives its content in
+the formatter — use it for computed cells (totals, ratios) instead of
+pre-mapping your items:
 
-/**
- * Assigned column widths (frozen, snapped, or inherited) are only authoritative
- * under `table-layout: fixed`; in auto layout they behave like a minimum. So a
- * table that drives widths — explicitly `fixed`, inheriting from a parent, or
- * with a column carrying a `width` or `snap` — uses fixed layout even when
- * `fixed` was not set. (`snap` is a width definition: the parent track range.)
- */
-const fixedLayout = computed(
-	() =>
-		props.fixed ||
-		hasSnap.value ||
-		props.columns.some((column) => column.width != null) ||
-		(inheritColumnWidths.value && !!parentId.value)
-);
+**A virtual total column computed from the row**
 
-/**
- * A nested table inheriting its parent's widths must size itself to the sum of
- * those columns rather than stretching to fill its container — otherwise fixed
- * layout would distribute the slack and the columns would no longer match the
- * parent. Tables with the same column count already sum to the full width, so
- * this is a no-op for them and only narrows tables with fewer columns.
- */
-/** True for a nested table that inherits its column widths from a parent. */
-const isInheriting = computed(
-	() => inheritColumnWidths.value && !!parentId.value
-);
+```vue
+<BbTable
+	caption="Order lines"
+	:columns="[
+		{ key: 'sku', label: 'SKU' },
+		{ key: 'qty', label: 'Qty', align: 'right' },
+		{ key: 'unitPrice', label: 'Unit €', align: 'right' },
+		{
+			key: 'total',
+			label: 'Total €',
+			align: 'right',
+			formatter: (_, __, item) =>
+				(item.qty * item.unitPrice).toLocaleString('en-IE'),
+		},
+	]"
+	:items="[
+		{ sku: 'CHAIR-OAK', qty: 4, unitPrice: 189 },
+		{ sku: 'DESK-140', qty: 2, unitPrice: 420 },
+		{ sku: 'LAMP-LED', qty: 6, unitPrice: 39 },
+	]"
+/>
+```
 
-const sizeToColumns = isInheriting;
+**`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.
+
+### Custom cells and headers
+
+Override any column's body with a `#<key>` slot and its header with a
+`#header:<key>` slot. The slot name is the key with every run of non-word
+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`
+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`
+(resolved via `item-value`), `classes`, plus the row's interaction surface —
+`selected` / `toggleSelected`, `highlighted` / `toggleHighlighted`,
+`expanded` / `toggleExpanded` / `expandProps`, and `sortOrder`. The flags are
+one-way state; the `toggle*` callbacks are the write path.
+
+Header scope: `label`, `items` (the full list — handy for counts), `sortable`,
+`sortOrder`, `toggleSort`, `classes`.
+
+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) —
+never a template-composed `` `local:${status}` ``. Colours use the registered
+`soft-*` badge variants (design-language palette); the companion carries their
+CSS in a non-scoped style block.
+
+**Status badges and an annotated header**
 
-/** Numbers and bare numeric strings (e.g. `400`, `'400'`) default to px; values
- * that already carry a unit/keyword (`'50%'`, `'10rem'`, `'auto'`) pass through. */
-const toLength = (width: number | string) => {
-	if (typeof width === 'number') return `${width}px`;
-	const trimmed = width.trim();
-	return /^-?\d*\.?\d+$/.test(trimmed) ? `${trimmed}px` : trimmed;
+```vue
+<template>
+	<div
+		class="max-w-2xl overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+	>
+		<BbTable
+			caption="Invoice status"
+			:columns="columns"
+			compact
+			item-value="id"
+			:items="invoices"
+		>
+			<!-- Cell slot: name = the column key (dots/non-word chars become `_`,
+			     dashes are kept).
+			     The glyphs are brand assets from the app's `iconDir`, referenced as
+			     `local:*` names — mapped to full literals, never template-composed. -->
+			<template #status="{ content }">
+				<BbBadge
+					:prepend:icon="glyphs[content as Status]"
+					size="sm"
+					:variant="variants[content as Status]"
+					>{{ labels[content as Status] }}</BbBadge
+				>
+			</template>
+
+			<!-- Header slot: `header:` + the column key. `label` comes from the scope. -->
+			<template #header:amount="{ label }">
+				<span class="inline-flex items-center gap-1">
+					{{ label }}
+					<span class="text-xs font-normal text-[color:var(--bb-text-muted)]"
+						>EUR</span
+					>
+				</span>
+			</template>
+		</BbTable>
+	</div>
+</template>
+<script setup lang="ts">
+import { BbBadge, BbTable } from 'bitboss-ui';
+import type { BadgeVariantType, BbTableColumn, IconType } from 'bitboss-ui';
+
+type Status = 'paid' | 'pending' | 'overdue';
+type Invoice = {
+	id: string;
+	number: string;
+	client: string;
+	status: Status;
+	amount: string;
 };
 
-/** Number of data columns the parent renders (numeric track keys). */
-const parentDataColumns = computed(() => {
-	const tracks = parentNode.value?.tracks;
-	return tracks
-		? Object.keys(tracks).filter((key) => /^\d+$/.test(key)).length
-		: 0;
-});
-
-/**
- * The parent's rendered columns in order — `select` (if any), data columns
- * `0…N-1`, then `actions` (if any) — form a gridline coordinate, one cell per
- * column. Cell `c` is the range `[c, c + 1]`. So a no-select parent starts its
- * data at cell 0, while a selectable parent starts it at cell 1.
- */
-const parentColumnKeys = computed(() => {
-	const tracks = parentNode.value?.tracks ?? {};
-	const keys: string[] = [];
-	if ('select' in tracks) keys.push('select');
-	for (let k = 0; k < parentDataColumns.value; k++) keys.push(String(k));
-	if ('actions' in tracks) keys.push('actions');
-	return keys;
-});
-
-/** Gridline cells where the parent's data region begins/ends and the table ends. */
-const firstDataCell = computed(() =>
-	'select' in (parentNode.value?.tracks ?? {}) ? 1 : 0
-);
-const dataEndCell = computed(
-	() => firstDataCell.value + parentDataColumns.value
-);
-const tableEndCell = computed(() => parentColumnKeys.value.length);
-
-/** Parent track custom property for the integer cell `[cell, cell + 1]`. */
-const cellTrackVar = (cell: number) => {
-	const key = parentColumnKeys.value[cell];
-	return key ? parentVar(key, '0px') : '0px';
+const columns: Array<BbTableColumn<Invoice>> = [
+	{ key: 'number', label: 'Invoice', width: 110 },
+	{ key: 'client', label: 'Client' },
+	{ key: 'status', label: 'Status', width: 120 },
+	{ key: 'amount', label: 'Amount', align: 'right', width: 110 },
+];
+
+const labels: Record<Status, string> = {
+	paid: 'Paid',
+	pending: 'Pending',
+	overdue: 'Overdue',
 };
 
-/** CSS length summing the parent tracks across the gridline range `[a, b]`. */
-const gridRangeWidth = (a: number, b: number): string | null => {
-	if (!parentId.value || b - a <= 1e-6) return null;
-	const parts: string[] = [];
-	for (let cell = Math.floor(a); cell < Math.ceil(b - 1e-6); cell++) {
-		const fraction = Math.min(b, cell + 1) - Math.max(a, cell);
-		if (fraction <= 1e-6) continue;
-		const track = cellTrackVar(cell);
-		parts.push(
-			fraction >= 1 - 1e-6 ? track : `${Number(fraction.toFixed(4))} * ${track}`
-		);
-	}
-	if (!parts.length) return null;
-	// A bare `var()` can stand alone, but a single fractional term still needs a
-	// `calc()` wrapper for the multiplication to be valid CSS.
-	if (parts.length === 1 && !parts[0].includes('*')) return parts[0];
-	return `calc(${parts.join(' + ')})`;
+// Status → full-name literals (icons policy: no `local:${status}` templates).
+const glyphs: Record<Status, IconType> = {
+	paid: 'local:check_circle',
+	pending: 'local:clock',
+	overdue: 'local:alert_circle',
 };
 
-/**
- * Resolved parent snap interval for each data column.
- * - A number snaps to that start point; the column then runs up to the next
- *   column's snap point (or one whole track if the next is unset). So a single
- *   snap that skips ahead widens this column to cover the gap — `snap: 4` on the
- *   second column makes the first effectively `[start, 4]`.
- * - A `[start, end]` pair is taken verbatim (`end` of `-1` runs to the end of
- *   the data region).
- * - Omitted, the column chains from the previous column's end.
- */
-const columnIntervals = computed(() => {
-	const cols = props.columns;
-	// Explicit start points; a later column's snap sets the previous column's end.
-	const starts = cols.map((column) =>
-		typeof column.snap === 'number'
-			? column.snap
-			: Array.isArray(column.snap)
-				? column.snap[0]
-				: null
-	);
-	let cursor = firstDataCell.value;
-	return cols.map((column, i) => {
-		const start = starts[i] ?? cursor;
-		let end: number;
-		if (Array.isArray(column.snap)) {
-			end = column.snap[1] === -1 ? dataEndCell.value : column.snap[1];
-		} else {
-			const next = starts[i + 1];
-			end = next != null && next > start ? next : Math.floor(start) + 1;
-		}
-		cursor = end;
-		return { start, end };
-	});
-});
-
-/**
- * A column whose interval begins at or beyond the parent's last data cell has no
- * matching parent column to inherit from — the table has more columns than its
- * parent. Such columns are sized to their own measured content and scroll within
- * the expand row instead of inheriting a track.
- */
-const isOverflowColumn = (interval: { start: number }) =>
-	isInheriting.value && interval.start >= dataEndCell.value;
-
-/** True when any column overflows the parent (more columns than the parent). */
-const overflowsParent = computed(() =>
-	columnIntervals.value.some(isOverflowColumn)
-);
-
-/**
- * A "flex" column shares a root table's leftover space (min-content floor)
- * proportionally via the probe. Only root tables flex this way; an inheriting
- * table instead snaps its in-range columns to the parent, content-sizes its
- * overflow columns, and lets a single fill column take up any slack.
- */
-const isFlexColumn = (index: number) =>
-	props.columns[index]?.width == null && !isInheriting.value;
-
-/**
- * The last column of an inheriting table whose width is left undefined — neither
- * a `width` nor a `snap` (a `snap` *is* a width definition: the track range it
- * spans). That column absorbs the leftover space so the table fills its parent
- * when a frozen/snapped column narrower than the parent's would otherwise leave a
- * gap. `-1` for a root table, or when every column defines its own width.
- */
-const fillColumnIndex = computed(() => {
-	if (!isInheriting.value) return -1;
-	for (let i = props.columns.length - 1; i >= 0; i--) {
-		const column = props.columns[i];
-		if (column.width == null && column.snap == null) return i;
-	}
-	return -1;
-});
-
-// Parent columns left of the first column (e.g. a select this table doesn't
-// render, or columns skipped by the first snap) and those right of the last are
-// folded into the edge columns as the structural offset, keeping the table
-// aligned to the parent. `offsetStartValue` becomes the first column's padding.
-const offsetStartValue = computed(() => {
-	const first = columnIntervals.value[0];
-	// No parent to align to (a root table) means no offset at all — without this
-	// the structural reclaim below would still fold a negative `-ownSelect` in.
-	if (!inheritColumnWidths.value || !parentId.value || !first) return null;
-	// The fill runs from the parent's left edge to this table's first data
-	// column — the parent's select cell, if any, plus any skipped data columns.
-	const head = gridRangeWidth(0, first.start);
-	// This table's own select column sits flush at the left edge and takes its
-	// measured width, so reclaim it from the fill (mirror of the actions side):
-	// the first data column then lines the *next* column up flush with the
-	// parent. When the parent has a select cell it is part of `head`, so only the
-	// surplus over it is reclaimed; when the parent has none the whole select
-	// width comes out of the first column, which shrinks to make room for it.
-	const ownSelect = props.selectable ? structuralFit.select : null;
-	if (!ownSelect) return head;
-	return `calc(${head ?? '0px'} - ${ownSelect})`;
-});
-const offsetEndValue = computed(() => {
-	const intervals = columnIntervals.value;
-	const last = intervals[intervals.length - 1];
-	// No parent to align to (a root table) means no offset at all — without this
-	// the structural reclaim below would still fold a negative `-ownActions` in.
-	if (!inheritColumnWidths.value || !parentId.value || !last) return null;
-	// With more columns than the parent, the table runs past the parent's right
-	// edge: there is no trailing parent region to fold, and the last column is a
-	// content-sized overflow column, so there is no end fill.
-	if (overflowsParent.value) return null;
-	// When the last column is the (auto) fill column it already absorbs the whole
-	// trailing region via fixed layout, so folding the offset in too would double
-	// it — and skew its right-aligned content inward.
-	if (fillColumnIndex.value === props.columns.length - 1) return null;
-	// The fill runs from the last data column's end all the way to the parent's
-	// right edge — any unmapped data columns plus the parent's actions cell, if
-	// it has one.
-	const tail = gridRangeWidth(last.end, tableEndCell.value);
-	// This table's own actions column sits flush against that right edge and
-	// takes its measured content width, so reclaim it from the fill: the table
-	// then ends exactly at the parent's edge instead of overflowing by the
-	// actions width. When the parent has an actions cell it is part of `tail`, so
-	// only the surplus over it is effectively reclaimed; when the parent has none
-	// the whole actions width comes out of the data fill. The result may be
-	// negative — the last data column then shrinks to make room for the actions.
-	const ownActions = props.actions ? structuralFit.actions : null;
-	if (!ownActions) return tail;
-	return `calc(${tail ?? '0px'} - ${ownActions})`;
-});
-const offsetStartActive = computed(() => offsetStartValue.value !== null);
-const offsetEndActive = computed(() => offsetEndValue.value !== null);
-
-/**
- * Measured intrinsic content widths of the structural columns. In a fixed table
- * these pin `select`/`actions` to their content so the remaining space is shared
- * among the data columns; `null` falls back to the regular auto behavior.
- */
-const structuralFit = reactive<{
-	select: string | null;
-	actions: string | null;
-}>({ select: null, actions: null });
-
-/**
- * Rendered columns in DOM order, each with the track key it publishes/inherits
- * and the width to apply via `<colgroup>`. A frozen column width wins; otherwise
- * an unfrozen column syncs to the parent's matching track (or `auto` at root).
- * The first/last column additionally absorbs the structural edge offset.
- */
-const columnTracks = computed(() => {
-	const sync = (key: string) =>
-		inheritColumnWidths.value ? parentVar(key) : 'auto';
-	// In fixed layout `auto` columns share width equally, so pin the structural
-	// columns to their measured content width and let the data columns share.
-	const structural = (key: 'select' | 'actions') =>
-		fixedLayout.value && structuralFit[key]
-			? (structuralFit[key] as string)
-			: sync(key);
-	const tracks: { key: string; width: string }[] = [];
-
-	if (props.selectable) {
-		tracks.push({ key: 'select', width: structural('select') });
-	}
+const variants: Record<Status, BadgeVariantType> = {
+	paid: 'soft-green',
+	pending: 'soft-amber',
+	overdue: 'soft-red',
+};
 
-	const lastIndex = props.columns.length - 1;
-	props.columns.forEach((column, index) => {
-		const key = String(index);
-		const frozen = column.width != null ? toLength(column.width) : null;
-		const interval = columnIntervals.value[index];
-
-		// The fill column is left `auto` so fixed layout (the inheriting table has
-		// a definite `width: 100%`) hands it the leftover space — its own inherited
-		// track plus the folded edge region plus any deficit. Skipped when the
-		// table overflows: there is no leftover then, and it must content-size.
-		if (index === fillColumnIndex.value && !overflowsParent.value) {
-			tracks.push({ key, width: 'auto' });
-			return;
-		}
+const invoices: Invoice[] = [
+	{
+		id: 'inv-1041',
+		number: 'INV-1041',
+		client: 'Northwind Traders',
+		status: 'paid',
+		amount: '€4,200.00',
+	},
+	{
+		id: 'inv-1042',
+		number: 'INV-1042',
+		client: 'Globex',
+		status: 'pending',
+		amount: '€980.50',
+	},
+	{
+		id: 'inv-1043',
+		number: 'INV-1043',
+		client: 'Initech',
+		status: 'overdue',
+		amount: '€15,600.00',
+	},
+	{
+		id: 'inv-1044',
+		number: 'INV-1044',
+		client: 'Umbrella',
+		status: 'pending',
+		amount: '€2,750.00',
+	},
+];
+</script>
 
-		let span: string | null;
-		if (frozen != null) {
-			span = frozen;
-		} else if (isFlexColumn(index)) {
-			// Root table auto column: a precise share of the leftover space from the
-			// proportional probe rather than fixed layout's equal split. `auto` is
-			// the fallback before the probe runs.
-			span = (fixedLayout.value && probeColWidths.value[index]) || null;
-		} else if (isOverflowColumn(interval)) {
-			// Inheriting table, past the parent's last column: no track to snap to,
-			// so size to its own content and let the table overflow (and scroll).
-			span = columnMinWidths.value[index] ?? null;
-		} else {
-			// In range: snap to the parent's matching column.
-			span = gridRangeWidth(interval.start, interval.end);
-		}
+<!-- Soft status palette — canonical source: ai/guides/design-language.md § Using color.
+     Non-scoped so variant classes on the child badge receive the accents. -->
+<style>
+.bb-badge.bb-badge--soft-green {
+	--accent: #16a34a;
+}
+.bb-badge.bb-badge--soft-amber {
+	--accent: #d97706;
+}
+.bb-badge.bb-badge--soft-red {
+	--accent: #dc2626;
+}
+.bb-badge.bb-badge--soft-green,
+.bb-badge.bb-badge--soft-amber,
+.bb-badge.bb-badge--soft-red {
+	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
+	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
+	--border-width: 1px;
+	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
+	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
+}
+</style>
+```
 
-		const offsets: string[] = [];
-		if (index === 0 && offsetStartActive.value) {
-			offsets.push('var(--bb-table-offset-internal-start)');
-		}
-		if (index === lastIndex && offsetEndActive.value) {
-			offsets.push('var(--bb-table-offset-internal-end)');
-		}
+Beyond per-column slots, the structural slots cover every other region:
+`#header:select` (the select-all cell content), `#header:actions`, `#select`
+(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).
+
+### Loading and empty states
+
+`loading` means two different things and the table tells them apart for you:
+
+- **Nothing to show yet** (first load, or a filter that emptied the table) →
+  **skeleton rows**, whose shape you tune per column with `skeleton` (`text`,
+  `avatar`, `avatar-text`, `image`, `badge`). Between 4 and 10 rows, matching the
+  current row count when it has one.
+- **Already showing rows** (a refetch: a `dependencies` change, a poll, a
+  save-then-reload) → **the rows stay put**, dimmed, with an indeterminate bar
+  along the header. Blanking a populated table to skeleton on every refetch loses
+  the user's place and flashes — so it doesn't.
+
+A function `items` source triggers this automatically while it resolves; so does
+the `loading` prop. `aria-busy` is set on the table in both cases, and the
+`loading-text` announcement fires in both.
+
+**While loading, the header and the rows are `inert`** — a refetch is about to
+replace the rows, so editing, selecting or sorting them races the incoming data.
+Same shape as `BbButton`: blocked by default, with `interactive-while-loading` as the
+escape hatch for tables that must stay usable during a background refresh (a poll
+that must not interrupt an open editor, say). The loading announcement is never
+inert, so the busy state is always conveyed.
+
+The `#loading` slot replaces the **skeleton**, so it follows the skeleton's rule:
+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.
+
+Always set `loading-text`: it is the loading row's `aria-live` announcement
+and — unlike `no-data-text` — it has **no built-in default**; omitting it
+announces an empty string.
+
+**Skeletons and a custom empty state**
 
-		// When folding an offset, use a calc-safe length base (no `auto`) so the
-		// column width = offset(s) + the column's own span.
-		const width = offsets.length
-			? `calc(${[...offsets, span ?? '0px'].join(' + ')})`
-			: (span ?? 'auto');
+```vue
+<template>
+	<div class="flex max-w-2xl flex-col gap-2">
+		<div class="flex gap-1.5">
+			<BbButton size="sm" variant="outline" @click="loading = !loading">
+				Toggle loading
+			</BbButton>
+			<BbButton size="sm" variant="ghost" @click="empty = !empty">
+				Toggle empty
+			</BbButton>
+		</div>
+
+		<div
+			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		>
+			<BbTable
+				caption="Team members"
+				:columns="columns"
+				compact
+				item-value="id"
+				:items="empty ? [] : members"
+				:loading="loading"
+				loading-text="Loading members…"
+			>
+				<template #no-data>
+					<p class="p-3 text-center text-sm text-[color:var(--bb-text-muted)]">
+						No members match your filters yet.
+					</p>
+				</template>
+			</BbTable>
+		</div>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbTable } from 'bitboss-ui';
+import type { BbTableColumn } from 'bitboss-ui';
+
+type Member = { id: string; name: string; email: string; role: string };
+
+// `skeleton` shapes each column's placeholder while `loading` is true so the
+// skeleton mirrors the real content (avatar + text, a badge, plain text).
+const columns: Array<BbTableColumn<Member>> = [
+	{ key: 'name', label: 'Name', skeleton: 'avatar-text' },
+	{ key: 'email', label: 'Email' },
+	{ key: 'role', label: 'Role', skeleton: 'badge', width: 90 },
+];
+
+const members: Member[] = [
+	{ id: 'u1', name: 'Ada Lovelace', email: 'ada@acme.io', role: 'Admin' },
+	{ id: 'u2', name: 'Grace Hopper', email: 'grace@acme.io', role: 'Editor' },
+	{ id: 'u3', name: 'Ken Thompson', email: 'ken@acme.io', role: 'Viewer' },
+];
+
+const loading = ref(false);
+const empty = ref(false);
+</script>
+```
 
-		tracks.push({ key, width });
-	});
+### Async items and filters
 
-	if (props.actions) {
-		tracks.push({ key: 'actions', width: structural('actions') });
-	}
+Set `items` to a provider function and the table runs it, tracking loading
+itself:
 
-	return tracks;
-});
+```ts
+type ItemsProvider<T> = (
+	prefill: boolean,
+	selected?: any // the current selection (v-model)
+) => T[] | Promise<T[]>;
+```
 
-/**
- * Standalone edge-offset custom properties consumed by the first/last cell
- * padding and the first/last column width. Set only when an offset is active;
- * otherwise the CSS default of `0px` makes both calcs collapse to their base.
- */
-const structuralOffset = computed<Record<string, string>>(() => {
-	const style: Record<string, string> = {};
-	if (offsetStartValue.value) {
-		style['--bb-table-offset-start'] = offsetStartValue.value;
-	}
-	if (offsetEndValue.value) {
-		style['--bb-table-offset-end'] = offsetEndValue.value;
-	}
-	return style;
-});
+- On mount it is called `(true, selection)`; when `dependencies` (or the
+  `items` prop itself) change it is called `(false, selection)`, debounced by
+  `deps-debounce-time`.
+- `dependencies` are compared **by value** (hashed), so `[filters]` refetches
+  only when content actually changes. Never wire a manual
+  `watch(filter, refetch)` — that is exactly what `dependencies` replaces.
+- Out-of-order responses are discarded (only the latest request writes rows);
+  a rejected provider is logged via `console.error` and the previous rows are
+  kept — surface failures yourself (e.g. `useToast`) if the user must know.
+- A plain array bypasses the provider machinery entirely.
 
-const containerStyle = computed(() => {
-	const vars: Record<string, string> = {
-		...cssVars.value,
-		...structuralOffset.value,
-	};
+**Debounced search through the items function**
 
-	if (naturalTotalWidth.value) {
-		vars['--bb-table-natural-width'] = naturalTotalWidth.value;
-	}
+```vue
+<template>
+	<div class="flex max-w-2xl flex-col gap-2">
+		<BbTextInput
+			v-model="search"
+			clearable
+			compact
+			label="Search invoices"
+			label-mode="outside"
+			placeholder="Client or number…"
+		/>
+
+		<!-- `items` is an async function; the table re-runs it (debounced) whenever
+		     an entry in `dependencies` changes, showing skeletons while it awaits. -->
+		<div
+			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		>
+			<BbTable
+				caption="Invoices"
+				:columns="columns"
+				compact
+				:dependencies="[search]"
+				:deps-debounce-time="300"
+				item-value="id"
+				:items="fetchInvoices"
+				loading-text="Searching…"
+			/>
+		</div>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbTable, BbTextInput } from 'bitboss-ui';
+import type { BbTableColumn } from 'bitboss-ui';
 
-	if (fillValue.value > 0) {
-		vars['--bb-table-fill'] = `${fillValue.value}px`;
-	}
+type Invoice = { id: string; number: string; client: string; amount: string };
 
-	return vars;
-});
+const columns: Array<BbTableColumn<Invoice>> = [
+	{ key: 'number', label: 'Invoice', width: 110 },
+	{ key: 'client', label: 'Client' },
+	{ key: 'amount', label: 'Amount', align: 'right', width: 100 },
+];
 
-/** Reads the header cells in render order: [select?, ...data, actions?]. */
-const headerCells = () =>
-	Array.from(
-		tableRef.value?.querySelectorAll<HTMLElement>(
-			':scope > thead > tr.bb-table-header-row > th'
-		) ?? []
+const catalogue: Invoice[] = [
+	{
+		id: '1',
+		number: 'INV-1041',
+		client: 'Northwind Traders',
+		amount: '€4,200',
+	},
+	{ id: '2', number: 'INV-1042', client: 'Globex', amount: '€980' },
+	{ id: '3', number: 'INV-1043', client: 'Initech', amount: '€15,600' },
+	{ id: '4', number: 'INV-1044', client: 'Umbrella', amount: '€2,750' },
+];
+
+const search = ref('');
+
+// Real apps forward the query to the backend; here we filter a local catalogue
+// after a short simulated round-trip.
+const fetchInvoices = async (): Promise<Invoice[]> => {
+	await new Promise((resolve) => setTimeout(resolve, 250));
+	const term = search.value.trim().toLowerCase();
+	if (!term) return catalogue;
+	return catalogue.filter(
+		(invoice) =>
+			invoice.client.toLowerCase().includes(term) ||
+			invoice.number.toLowerCase().includes(term)
 	);
-
-/** Measures the rendered columns and publishes them as this table's tracks. */
-const measureTracks = () => {
-	const keys = columnTracks.value.map((track) => track.key);
-	const tracks: Record<string, string> = {};
-	headerCells().forEach((cell, index) => {
-		const key = keys[index];
-		if (key != null) tracks[key] = `${cell.getBoundingClientRect().width}px`;
-	});
-	setTracks(tracks);
-};
-
-/**
- * Measures the intrinsic content width of the structural columns across header
- * and body. Fixed layout sizes columns from the header row only, so the body is
- * required here: the actions header is `sr-only`, while the real control lives
- * in the body. The measured child width is independent of the column width, so
- * pinning the column to it converges instead of oscillating.
- */
-const measureStructuralFit = () => {
-	const table = tableRef.value;
-	if (!table) return;
-
-	const fit = (selector: string) => {
-		let max = 0;
-		table.querySelectorAll<HTMLElement>(selector).forEach((cell) => {
-			// Sum each child's own intrinsic width (plus horizontal margins) — an
-			// actions cell holds several side-by-side controls and the column must
-			// fit them all. Crucially this is *not* their shared extent: the extent
-			// depends on how the cell spreads them across its width, which feeds the
-			// column width back into its own measurement and runs away into the
-			// thousands. A child's own width does not depend on the cell, so this
-			// converges. Out-of-flow children (e.g. an `sr-only` label parked far
-			// off-screen) are skipped so they cannot inflate the result.
-			let content = 0;
-			cell.querySelectorAll<HTMLElement>(':scope > *').forEach((child) => {
-				const childStyle = getComputedStyle(child);
-				if (
-					childStyle.position === 'absolute' ||
-					childStyle.position === 'fixed'
-				)
-					return;
-				const margin =
-					parseFloat(childStyle.marginLeft) +
-					parseFloat(childStyle.marginRight);
-				content += child.getBoundingClientRect().width + (margin || 0);
-			});
-			const style = getComputedStyle(cell);
-			const padding =
-				parseFloat(style.paddingLeft) + parseFloat(style.paddingRight);
-			max = Math.max(max, content + padding);
-		});
-		return max > 0 ? `${Math.ceil(max)}px` : null;
-	};
-
-	// Scoped to this table's own header/body rows: an unscoped descendant query
-	// would also match the structural cells of a nested table living in an expand
-	// row, letting a child's actions/select width hijack this table's column.
-	structuralFit.select = props.selectable
-		? fit(
-				':scope > thead > tr > th.bb-table-header--select, :scope > tbody > tr > td.bb-table-data__cell--select'
-			)
-		: null;
-	structuralFit.actions = props.actions
-		? fit(
-				':scope > thead > tr > th.bb-table-header--actions, :scope > tbody > tr > td.bb-table__cell--actions'
-			)
-		: null;
 };
+</script>
+```
 
-const measure = () => {
-	measureStructuralFit();
-	measureTracks();
-};
-
-/**
- * Proportional `<col>` widths derived from an auto-layout probe, one entry per
- * data column (`null` for frozen columns — they keep their declared width).
- *
- * For each auto column the formula is:
- *   width = max(minimum, available × (minimum / minimumTotal))
- *
- * where `minimum` is the column's `min-content` width (what it shrinks to in a
- * very narrow container, i.e. the floor below which content would be clipped),
- * `available` = containerWidth − frozenColumnWidths − structuralColumnWidths
- * and `minimumTotal` = sum of the auto columns' minimums.
- *
- * So when the container has room (`available ≥ minimumTotal`) the slack is shared
- * out proportionally to each column's minimum, scaling them up together; when it
- * does not, every column drops to its minimum and the table-level `min-width`
- * lets it overflow (the container scrolls) rather than squashing content further.
- *
- * Re-measured after any DOM mutation (debounced 200 ms) and after any container
- * resize (via a dedicated ResizeObserver on the container element).
- */
-const probeColWidths = ref<(string | null)[]>([]);
-
-/**
- * Each unfrozen column's measured `min-content` width (`null` for frozen). Used
- * to content-size the overflow columns of an inheriting table — those past the
- * parent's last column, with no track to snap to.
- */
-const columnMinWidths = ref<(string | null)[]>([]);
-
-/**
- * Leftover px the inheriting fill column adds so the table reaches its parent's
- * width. Published as `--bb-table-fill`; `0` when the table already fills or
- * overflows. Derived self-correctingly from the live total (see the probe).
- */
-const fillValue = ref(0);
+On a server-paginated screen the provider forwards filters, sort and page to
+the backend and returns the current slice:
 
-/**
- * Total minimum width of the table (all columns at their `min-content`, plus the
- * structural columns). Published as `--bb-table-natural-width` and used as
- * `min-width` on the `<table>` so the table scrolls horizontally only once the
- * container is narrower than this true minimum.
- */
-const naturalTotalWidth = ref<string | null>(null);
-
-const runNaturalWidthProbe = () => {
-	const container = containerRef.value;
-	if (!container || !fixedLayout.value) return;
-	// Runs for a frozen-column table (to share space), or any inheriting table
-	// (to content-size overflow columns and drive the fill column's slack).
-	if (
-		!props.columns.some((col) => col.width != null) &&
-		!overflowsParent.value &&
-		fillColumnIndex.value < 0
-	)
-		return;
-
-	const containerWidth = container.offsetWidth;
-	const dataOffset = props.selectable ? 1 : 0;
-
-	// ── Real-table measurements ────────────────────────────────────────────
-	// Structural column widths come from measureStructuralFit (already run).
-	const selectWidth = structuralFit.select
-		? parseFloat(structuralFit.select)
-		: 0;
-	const actionsWidth = structuralFit.actions
-		? parseFloat(structuralFit.actions)
-		: 0;
-
-	// Live rendered widths from the fixed-layout table. `frozenTotal` (declared
-	// widths) feeds the stable min-width floor; `nonFlexTotal` (frozen + inherited)
-	// is what the flex columns share the remainder of. The inherited part is only
-	// used for that `available` figure — never fed back into min-width, since those
-	// widths stretch with the table and would otherwise lock min-width above
-	// max-content and force a spurious uniform stretch on every column.
-	const realThs = headerCells();
-	let frozenTotal = 0;
-	let nonFlexTotal = 0;
-	props.columns.forEach((col, i) => {
-		const width = realThs[dataOffset + i]?.getBoundingClientRect().width ?? 0;
-		if (col.width != null) frozenTotal += width;
-		if (!isFlexColumn(i)) nonFlexTotal += width;
-	});
-
-	// ── Offscreen probe for the auto columns' minimum (min-content) widths ──
-	// The clone's inner table is forced to `width: min-content` and the auto <col>
-	// hints are stripped so each <th> reports the narrowest width it can take
-	// before content would be clipped, independent of the container size or
-	// previous probe cycles.
-	const probe = document.createElement('div');
-	probe.style.cssText = [
-		'position:absolute',
-		'top:-9999px',
-		'left:-9999px',
-		'visibility:hidden',
-		'pointer-events:none',
-		`width:${containerWidth}px`,
-		`height:${container.offsetHeight}px`,
-		'overflow:visible',
-	].join(';');
-
-	const clone = container.cloneNode(true) as HTMLElement;
-	clone.classList.remove('bb-table--fixed');
-
-	// Expand rows are full-width (colspan) and hold nested tables; under the
-	// auto-layout probe their content would back-pressure this table's own
-	// columns, so drop them and measure this table's columns in isolation.
-	clone
-		.querySelectorAll('.bb-table-expand__row')
-		.forEach((row) => row.remove());
-
-	// Auto <col> hints are cleared so a previous cycle's computed width cannot
-	// act as a minimum and inflate the measurement; frozen hints are left intact
-	// since their declared width is a genuine floor for that column.
-	const probeColEls = Array.from(clone.querySelectorAll<HTMLElement>('col'));
-	props.columns.forEach((col, i) => {
-		if (col.width == null) {
-			const probeCol = probeColEls[dataOffset + i];
-			if (probeCol) probeCol.style.width = '';
-		}
+```ts
+const fetchInvoices = async (): Promise<Invoice[]> => {
+	const res = await api.invoices.list({
+		search: search.value,
+		status: status.value,
+		orderBy: sort.value, // the v-model:sort array, forwarded as-is
+		page: page.value,
+		perPage,
 	});
+	totalItems.value = res.total;
+	return res.data;
+};
+// dependencies: [search, status, sort]
+// page is NOT listed: a provider table already refetches when the shared
+// (table-id) page moves — list only your own filters and sort here.
+```
 
-	const innerTable = clone.querySelector<HTMLElement>('table');
-	if (innerTable) {
-		innerTable.style.width = 'min-content';
-		innerTable.style.minWidth = '0';
-	}
+This is the shape of every server-driven listing — the full assembly (filters,
+pagination, confirm-delete, toasts) is the records workspace recipe
+(`./recipes/vue/records-workspace.md`), which works unchanged under Inertia or
+Nuxt since the table itself never touches the router.
 
-	probe.appendChild(clone);
-	document.body.appendChild(probe);
+### Pagination
 
-	const headerRow = probe.querySelector<HTMLElement>(
-		'table thead tr.bb-table-header-row'
-	);
-	const ths = headerRow
-		? Array.from(headerRow.querySelectorAll<HTMLElement>(':scope > th'))
-		: [];
-
-	// Min-content of every unfrozen column (0 for frozen). Independent of the live
-	// table's width, so it is a stable basis for both the flex share and the
-	// min-width floor — unlike the rendered inherited widths.
-	const minContents = props.columns.map((col, i) => {
-		if (col.width != null) return 0;
-		const th = ths[dataOffset + i];
-		return th ? th.getBoundingClientRect().width : 0;
-	});
+`BbTable` never slices its own data — you do, or the server does. Feed it the
+current slice as `items` and pass `page` / `per-page` / `total-items` so it
+can announce `aria-rowcount` and per-row absolute indices (when `items` is an
+array, `per-page` and `total-items` default to its length — so a one-page
+table is accessible with just `page`). Pair it with `BbPagination` bound to
+the same page ref.
 
-	document.body.removeChild(probe);
+**BbPagination alongside the table**
 
-	// ── Proportional <col> widths ──────────────────────────────────────────
-	// Only the flex columns share `available`; the inherited columns are already
-	// laid out and excluded via `nonFlexTotal`.
-	const flexMinTotal = props.columns.reduce(
-		(s, _, i) => s + (isFlexColumn(i) ? minContents[i] : 0),
-		0
-	);
-	const available = containerWidth - nonFlexTotal - selectWidth - actionsWidth;
-
-	// Share the available space proportionally to each flex column's minimum, but
-	// never drop below that minimum — when space runs out the table overflows
-	// (and the container scrolls) instead of clipping content.
-	//
-	// Widths are kept sub-pixel (not rounded up): the raw shares sum to exactly
-	// `available`, whereas ceiling each column would over-allocate by up to a
-	// pixel apiece and, under `table-layout: fixed`, push the table a few px past
-	// the container and trip the horizontal scrollbar. `toFixed` only trims the
-	// float tail, well below the 1px a scrollbar needs.
-	const px = (n: number) => `${Number(n.toFixed(3))}px`;
-	probeColWidths.value = props.columns.map((_, i) => {
-		if (!isFlexColumn(i)) return null;
-		const minimum = minContents[i];
-		if (flexMinTotal <= 0) return px(minimum);
-		const share = available > 0 ? available * (minimum / flexMinTotal) : 0;
-		return px(Math.max(minimum, share));
-	});
+```vue
+<template>
+	<div class="flex max-w-2xl flex-col gap-2">
+		<!-- `page` / `per-page` / `total-items` power the table's accessibility
+		     announcements (aria-rowcount / aria-rowindex); the actual slicing is
+		     yours (or the server's). -->
+		<div
+			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		>
+			<BbTable
+				caption="Invoices"
+				:columns="columns"
+				compact
+				item-value="id"
+				:items="pageRows"
+				:page="page"
+				:per-page="perPage"
+				:total-items="invoices.length"
+			/>
+		</div>
+		<div class="flex items-center justify-between gap-2">
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				{{ rangeStart }}–{{ rangeEnd }} of {{ invoices.length }}
+			</p>
+			<BbPagination v-model="page" :total-pages="totalPages" />
+		</div>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbPagination, BbTable } from 'bitboss-ui';
+import type { BbTableColumn } from 'bitboss-ui';
+
+type Invoice = { id: string; number: string; client: string; amount: string };
+
+const columns: Array<BbTableColumn<Invoice>> = [
+	{ key: 'number', label: 'Invoice', width: 110 },
+	{ key: 'client', label: 'Client' },
+	{ key: 'amount', label: 'Amount', align: 'right', width: 100 },
+];
+
+const invoices: Invoice[] = Array.from({ length: 13 }, (_, index) => ({
+	id: String(index + 1),
+	number: `INV-${1041 + index}`,
+	client: ['Northwind Traders', 'Globex', 'Initech', 'Umbrella'][index % 4],
+	amount: `€${((index + 1) * 640).toLocaleString('en-IE')}`,
+}));
 
-	// Min-content per unfrozen column, for content-sizing an inheriting table's
-	// overflow columns (no parent track to snap to).
-	columnMinWidths.value = minContents.map((w) => (w > 0 ? px(w) : null));
-
-	// Leftover the inheriting fill column must absorb to reach the parent's width.
-	// `parentTotal` is the parent table's full width (the expand cell this table
-	// sits in); the container itself shrink-wraps to the table, so it can't be the
-	// reference. Self-correcting: the live total already includes last cycle's
-	// fill, so adding it back recovers the intrinsic total and the result is the
-	// same once the table fills (0 when it already fills or overflows).
-	if (fillColumnIndex.value >= 0) {
-		const parentTotal = Object.values(parentNode.value?.tracks ?? {}).reduce(
-			(s, w) => s + (parseFloat(w) || 0),
-			0
-		);
-		const liveTotal = realThs.reduce(
-			(s, th) => s + th.getBoundingClientRect().width,
-			0
-		);
-		fillValue.value = Math.max(0, parentTotal - liveTotal + fillValue.value);
-	} else {
-		fillValue.value = 0;
-	}
+const perPage = 5;
+const page = ref(1);
+const totalPages = computed(() => Math.ceil(invoices.length / perPage));
+const rangeStart = computed(() => (page.value - 1) * perPage + 1);
+const rangeEnd = computed(() =>
+	Math.min(page.value * perPage, invoices.length)
+);
 
-	// Table min-width = frozen (declared) widths + every unfrozen column's
-	// min-content + structural. Built only from values that do not depend on the
-	// table's own width, so it can never exceed max-content and force a stretch.
-	const minContentTotal = minContents.reduce((s, w) => s + w, 0);
-	const naturalTotal =
-		frozenTotal + minContentTotal + selectWidth + actionsWidth;
-	naturalTotalWidth.value =
-		naturalTotal > 0 ? `${Math.ceil(naturalTotal)}px` : null;
-};
+const pageRows = computed(() =>
+	invoices.slice((page.value - 1) * perPage, page.value * perPage)
+);
+</script>
+```
 
-let naturalWidthDebounceTimer: ReturnType<typeof setTimeout> | null = null;
-let mutationObserver: MutationObserver | undefined;
-
-/** Invalidates the cached natural width and schedules a fresh probe. */
-const scheduleNaturalWidthProbe = () => {
-	if (naturalWidthDebounceTimer !== null)
-		clearTimeout(naturalWidthDebounceTimer);
-	naturalWidthDebounceTimer = setTimeout(() => {
-		naturalWidthDebounceTimer = null;
-		runNaturalWidthProbe();
-	}, 200);
-};
+For no-prop-drilling wiring, give the table an `id` and the pagination a
+matching `table-id`: both join the same table context and stay in sync without
+a shared ref. The pagination props are symmetric across the pair — `page` /
+`per-page` / `total-items` / `total-pages` are accepted by both components and
+publish into the same context, so the server's fields go to whichever one is
+convenient. `total-pages` is a seed for when no row count is known (an
+externally paged array table, or a server that only reports a page count): a
+count derived from a real `total-items` always wins over it. Add `navigation`
+to `BbPagination` to mirror the page in the URL query. The same context is
+scriptable from anywhere via `useBbTableContext`
+(`./composables/useBbTableContext.md`).
+
+### 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
+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`.
+
+**Sortable headers driving a client-side sort**
 
-let resizeObserver: ResizeObserver | undefined;
-/** Observes the container element specifically for size changes so the
- *  proportional <col> widths are recomputed whenever the container grows or
- *  shrinks — separately from the header-cell observer that drives measureTracks. */
-let containerResizeObserver: ResizeObserver | undefined;
-
-const observeColumns = () => {
-	if (!resizeObserver) return;
-	resizeObserver.disconnect();
-	headerCells().forEach((cell) => resizeObserver?.observe(cell));
-	measure();
-};
+```vue
+<template>
+	<div class="flex max-w-2xl flex-col gap-1.5">
+		<!-- Mark columns `sortable` and bind `v-model:sort`. The header buttons
+		     cycle asc → desc → off; the table only REPORTS the model — you sort
+		     the data. -->
+		<div
+			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		>
+			<BbTable
+				v-model:sort="sort"
+				caption="Invoices"
+				:columns="columns"
+				compact
+				item-value="id"
+				:items="sortedInvoices"
+			/>
+		</div>
+		<p class="text-xs text-[color:var(--bb-text-muted)]">
+			Sort model: <code>{{ JSON.stringify(sort) }}</code>
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbTable } from 'bitboss-ui';
+import type { BbTableColumn, BbTableSortEntry } from 'bitboss-ui';
 
-onMounted(() => {
-	resizeObserver = new ResizeObserver(() => measure());
-	observeColumns();
-
-	// Initial probe runs after the first render so all cells have content.
-	nextTick(runNaturalWidthProbe);
-
-	// Invalidate the cache whenever rows or cell content change.
-	if (tableRef.value) {
-		mutationObserver = new MutationObserver(scheduleNaturalWidthProbe);
-		mutationObserver.observe(tableRef.value, {
-			childList: true,
-			subtree: true,
-			characterData: true,
-		});
-	}
+type Invoice = { id: string; number: string; client: string; amount: number };
 
-	// Re-probe whenever the container itself is resized so that proportional
-	// <col> widths stay accurate as the available space changes.
-	if (containerRef.value) {
-		containerResizeObserver = new ResizeObserver(scheduleNaturalWidthProbe);
-		containerResizeObserver.observe(containerRef.value);
-	}
+const euro = new Intl.NumberFormat('en-IE', {
+	style: 'currency',
+	currency: 'EUR',
 });
 
-onBeforeUnmount(() => {
-	resizeObserver?.disconnect();
-	containerResizeObserver?.disconnect();
-	mutationObserver?.disconnect();
-	if (naturalWidthDebounceTimer !== null)
-		clearTimeout(naturalWidthDebounceTimer);
+const columns: Array<BbTableColumn<Invoice>> = [
+	{ key: 'number', label: 'Invoice', sortable: true, width: 110 },
+	{ key: 'client', label: 'Client', sortable: true },
+	{
+		key: 'amount',
+		label: 'Amount',
+		align: 'right',
+		sortable: true,
+		width: 110,
+		formatter: euro.format,
+	},
+];
+
+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 },
+	{ id: '4', number: 'INV-1044', client: 'Umbrella', amount: 2750 },
+];
+
+const sort = ref<BbTableSortEntry[]>([['amount', 'desc']]);
+
+// Apply the ordered sort model to the data — first entry wins ties first.
+const sortedInvoices = computed(() => {
+	if (!sort.value.length) return invoices;
+	return [...invoices].sort((a, b) => {
+		for (const [key, direction] of sort.value) {
+			const left = a[key as keyof Invoice];
+			const right = b[key as keyof Invoice];
+			const compared =
+				typeof left === 'number' && typeof right === 'number'
+					? left - right
+					: String(left).localeCompare(String(right));
+			if (compared !== 0) return direction === 'asc' ? compared : -compared;
+		}
+		return 0;
+	});
 });
+</script>
+```
 
-watch(columnTracks, () => nextTick(observeColumns), { flush: 'post' });
-
-/** Builds accessible label for selection controls from row content. */
-const getAccessibleLabel = (columns: MappedCell[]) =>
-	[t('table.select').value, ...columns.map((col) => col.content)].join(' ');
-
-const containerTag = computed(() => (props.selectable ? 'fieldset' : 'div'));
-
-const loading = computed(() => props.loading || innerLoading.value);
+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`
+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).
 
-const hasProvidedAccessibilityData = computed(
-	() => !isNil(props.page) && !isNil(props.perPage) && !isNil(props.totalItems)
-);
+### Selection and bulk actions
 
-const containerClass = computed(() => ({
-	'bb-table': true,
-	[`bb-table--align-${props.align}`]: true,
-	'bb-table--compact': props.compact,
-	'bb-table--fixed': fixedLayout.value,
-	'bb-table--inherit-widths': sizeToColumns.value,
-	'bb-table--fixed-header': props.fixedHeaders,
-	'bb-table--loading': loading.value,
-	'bb-table--empty': !options.value.length,
-	'bb-table--selectable': !!props.selectable,
-	'scrollbar-border': true,
-}));
+Add `selectable` for multi-select (`multiple` is the default) bound with
+`v-model` — the model **must** be an array in multiple mode (the table throws
+otherwise). With `item-value` set, the model holds ids rather than whole rows.
+Pass `selectable` a predicate (`(item) => boolean`) to gate specific rows: the
+excluded rows' controls disable and `toggleSelected` refuses them too.
 
-const replacementContentSpan = computed(
-	() =>
-		props.columns.length + Number(!!props.selectable) + Number(!!props.actions)
-);
+To drive a toolbar that lives **outside** the table subtree, give the table an
+`id` and read `useBbTableContext(id).selected` — the handle mirrors the
+table's selection both ways, so a bulk-action bar needs no prop drilling. As
+everywhere in the library, the destructive bulk action is gated by
+`useConfirm` before it touches the data.
 
-const slotNamesByKey = computed(() =>
-	Object.fromEntries(
-		props.columns.map((col) => [col.key, columnKeyToSlotName(col.key)])
-	)
-);
-const {
-	getter,
-	items: internalItems,
-	loading: innerLoading,
-} = useItemsGetter({
-	items: toRef(props, 'items'),
-});
+**Multi-select with a context-driven bulk bar**
 
-const { hasPrefilled } = usePrefill({
-	trigger: true,
-	fn: async (isPrefill) => {
-		await getter(isPrefill, props.modelValue);
+```vue
+<template>
+	<div class="flex max-w-2xl flex-col gap-2">
+		<!-- Bulk-action bar lives OUTSIDE the table and reads the selection through
+		     the shared context by id — no prop drilling. The destructive action is
+		     gated by `useConfirm`. -->
+		<div
+			v-if="selectedCount"
+			class="flex items-center gap-2 rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] bg-[color:var(--bb-muted)] px-2.5 py-1.5"
+		>
+			<span class="text-sm">{{ selectedCount }} selected</span>
+			<BbButton
+				prepend:icon="lucide:trash-2"
+				size="sm"
+				variant="destructive"
+				@click="removeSelected"
+			>
+				Delete
+			</BbButton>
+			<BbButton size="sm" variant="ghost" @click="clear">Clear</BbButton>
+		</div>
+
+		<div
+			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		>
+			<BbTable
+				id="member-selection"
+				v-model="selected"
+				caption="Team members"
+				:columns="columns"
+				compact
+				item-value="id"
+				:items="members"
+				legend="Select team members"
+				name="members"
+				selectable
+			/>
+		</div>
+
+		<!--
+			Standalone example: it mounts its own host because it has no app root.
+			A real app mounts exactly one <BbConfirm /> at the app root, and pages
+			mount none. See ai/guides/agent-contract.md § Global Host Rule.
+		-->
+		<BbConfirm />
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import {
+	BbButton,
+	BbConfirm,
+	BbTable,
+	useBbTableContext,
+	useConfirm,
+} from 'bitboss-ui';
+import type { BbTableColumn } from 'bitboss-ui';
+
+type Member = { id: string; name: string; email: string; role: string };
+
+const columns: Array<BbTableColumn<Member>> = [
+	{ key: 'name', label: 'Name' },
+	{ key: 'email', label: 'Email' },
+	{ key: 'role', label: 'Role', width: 90 },
+];
+
+const members = ref<Member[]>([
+	{ id: 'u1', name: 'Ada Lovelace', email: 'ada@acme.io', role: 'Admin' },
+	{ id: 'u2', name: 'Grace Hopper', email: 'grace@acme.io', role: 'Editor' },
+	{
+		id: 'u3',
+		name: 'Margaret Hamilton',
+		email: 'maggie@acme.io',
+		role: 'Viewer',
 	},
-});
-
-const { data: modelValueIndexedByHash } = useIndexById({
-	items: toRef(props, 'modelValue'),
-});
-
-const { options } = useBaseOptions({
-	disabled: toRef(props, 'disabled'),
-	items: internalItems,
-	itemText: undefined,
-	itemValue: props.itemValue,
-	max: props.max,
-	selectable: true,
-	selectedIndexedByHash: modelValueIndexedByHash,
-});
-
-const onOptionSelected = async (option: BaseOption) => {
-	if (props.multiple) {
-		emit('update:modelValue', props.modelValue.concat(option.value));
-	} else {
-		emit('update:modelValue', option.value);
-	}
+	{ id: 'u4', name: 'Ken Thompson', email: 'ken@acme.io', role: 'Editor' },
+]);
+
+// `item-value="id"` gives rows a stable identity, so `selected` holds ids.
+const selected = ref<string[]>([]);
+
+// Same id as the table — the handle mirrors the table's selection both ways.
+const ctx = useBbTableContext('member-selection', { selected: [] });
+const selectedCount = computed(() => ctx.selected.value?.length ?? 0);
+const clear = () => (ctx.selected.value = []);
+
+const { confirm } = useConfirm();
+
+// Destructive bulk action: `await` the decision, act only on a yes.
+const removeSelected = async () => {
+	const ids: string[] = ctx.selected.value ?? [];
+	const ok = await confirm({
+		title: `Delete ${ids.length} ${ids.length === 1 ? 'member' : 'members'}?`,
+		text: 'They will lose access to this workspace immediately.',
+		variant: 'destructive',
+		yes: { text: 'Delete', 'prepend:icon': 'lucide:trash-2' },
+		no: 'Cancel',
+	});
+	if (!ok) return;
+	members.value = members.value.filter((member) => !ids.includes(member.id));
+	clear();
 };
+</script>
+```
 
-const onOptionUnselected = async (option: BaseOption) => {
-	if (props.multiple) {
-		const copy = { ...modelValueIndexedByHash.value };
-		delete copy[option.valueHash];
-		emit('update:modelValue', Object.values(copy));
-	} else {
-		emit('update:modelValue', null);
-	}
-};
+More selection surface, all verified behavior:
+
+- Every body slot exposes `toggleSelected`, so a bespoke control (a whole-row
+  button, a status chip) drives selection through the same path as the
+  checkbox — it even works without `selectable` (that prop only governs the
+  built-in selection column); explicit blocks (`disabled`, `readonly`, a
+  predicate exclusion) still apply.
+- `item:selected` / `item:unselected` fire with the toggled row's value on
+  every user toggle — use them for per-row side effects; keep `v-model` as
+  the state.
+- A selectable table renders as a `<fieldset>`; give it a `legend`. With
+  `name` set, each selected value renders a hidden input (objects are
+  JSON-stringified), so the table submits inside a plain HTML form.
+- `disabled` makes the whole table inert; `readonly` leaves controls focusable
+  but ignores changes.
+
+#### Selection across refetches
+
+By default a `dependencies`-driven refetch replaces the rows but leaves
+`v-model` untouched, so ids that just left the result set silently stay
+selected. Set **`enforce-coherence`** — the same prop, same meaning as on the
+selects and option groups — and after every load the table prunes its
+row-keyed models of values whose row is gone: `v-model`,
+`v-model:unselected-items`, `v-model:highlighted` and
+`v-model:expanded-items`. Values whose rows survive the refetch stay put;
+single-value models (`:multiple="false"`, single highlight) reset to `null`.
+Set `item-value` so the match runs on stable identity.
+
+One hard exclusion: **never combine it with pagination fed through
+`dependencies`**. Every page turn is a refetch, so state held on rows of other
+pages — cross-page selections, the whole `select-all` + `unselected-items`
+pattern — would be pruned away. For paginated tables (or any custom rule),
+reconcile in the provider instead: the table calls it `(prefill, selected)`
+with the current selection, which is exactly where the new rows are known.
+
+**Provider-side reconciliation, for when enforce-coherence doesn't fit**
 
-useHashedWatcher(
-	() => [props.dependencies, props.items],
-	async () => {
-		if (!hasPrefilled.value) {
-			return;
-		}
-		await getter(false, props.modelValue);
-	},
+```vue
+<template>
+	<div class="flex max-w-2xl flex-col gap-2">
+		<div class="flex items-center gap-1.5">
+			<!-- Mirrored `false-value`: one role filter is always active. -->
+			<BbButton
+				v-for="filter in roleFilters"
+				:key="filter.value"
+				v-model="role"
+				:false-value="filter.value"
+				group
+				size="xs"
+				:true-value="filter.value"
+				variant="outline"
+			>
+				{{ filter.label }}
+			</BbButton>
+			<span class="ml-auto text-xs text-[color:var(--bb-text-muted)]">
+				{{ selected.length }} selected
+			</span>
+		</div>
+
+		<!-- The role change refetches via `dependencies`. `enforce-coherence`
+		     would prune `v-model` for free here — this example keeps it off to
+		     show the provider-side reconcile, the pattern paginated tables
+		     (where the prop must stay off) still need. -->
+		<div
+			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		>
+			<BbTable
+				v-model="selected"
+				caption="Workspace members"
+				:columns="columns"
+				compact
+				:dependencies="[role]"
+				:deps-debounce-time="100"
+				item-value="id"
+				:items="fetchMembers"
+				legend="Select members"
+				loading-text="Loading members…"
+				selectable
+			/>
+		</div>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbTable } from 'bitboss-ui';
+import type { BbTableColumn } from 'bitboss-ui';
+
+type Role = 'Admin' | 'Editor' | 'Viewer';
+type RoleFilter = 'all' | Role;
+type Member = { id: string; name: string; email: string; role: Role };
+
+const roleFilters: Array<{ label: string; value: RoleFilter }> = [
+	{ label: 'All', value: 'all' },
+	{ label: 'Admins', value: 'Admin' },
+	{ label: 'Editors', value: 'Editor' },
+];
+
+const columns: Array<BbTableColumn<Member>> = [
+	{ key: 'name', label: 'Name' },
+	{ key: 'email', label: 'Email' },
+	{ key: 'role', label: 'Role', width: 90 },
+];
+
+const directory: Member[] = [
+	{ id: 'u1', name: 'Ada Lovelace', email: 'ada@acme.io', role: 'Admin' },
+	{ id: 'u2', name: 'Grace Hopper', email: 'grace@acme.io', role: 'Editor' },
 	{
-		debounce: props.depsDebounceTime,
+		id: 'u3',
+		name: 'Margaret Hamilton',
+		email: 'maggie@acme.io',
+		role: 'Editor',
+	},
+	{ id: 'u4', name: 'Ken Thompson', email: 'ken@acme.io', role: 'Viewer' },
+	{ id: 'u5', name: 'Barbara Liskov', email: 'barbara@acme.io', role: 'Admin' },
+];
+
+const role = ref<RoleFilter>('all');
+const selected = ref<string[]>([]);
+
+// Without `enforce-coherence` a refetch replaces the rows but leaves the
+// selection untouched. The table calls the provider `(prefill, selected)`,
+// so the provider is the one spot where both the current selection and the new
+// rows are known — drop the ids that left the result set. Reconcile on every
+// call, not just refetches: `prefill` is `true` for every fetch a component
+// starts itself, so it can't tell an initial load from a `dependencies` refetch
+// (only a user-typed query reads `false`, and a table has no search field).
+const fetchMembers = async (
+	_prefill: boolean,
+	selectedIds?: string[]
+): Promise<Member[]> => {
+	await new Promise((resolve) => setTimeout(resolve, 200));
+	const rows =
+		role.value === 'all'
+			? directory
+			: directory.filter((member) => member.role === role.value);
+	if (selectedIds?.length) {
+		selected.value = selectedIds.filter((id) =>
+			rows.some((member) => member.id === id)
+		);
 	}
-);
+	return rows;
+};
+</script>
+```
 
-const mapColumnToCell = (
-	column: BbTableColumn<Item>,
-	item: BaseOption
-): MappedCell => {
-	const slotName = slotNamesByKey.value[column.key];
-	const align = column.align ?? 'left';
-	let content = getItemValue(item.item, column.key);
+### Single select, select-all and limits
 
-	if (column.formatter && (!isNil(content) || column.formatOnNull !== false)) {
-		content = column.formatter(content, column.key, item.item);
-	}
-	if (column.placeholder && isNil(content)) {
-		content = column.placeholder;
-	}
+`:multiple="false"` renders radios and the model becomes one value (or
+`null`). Label the radio column with `select-text` (visually hidden).
 
-	return {
-		align,
-		classes: mergeCellClasses(
-			[`bb-table-data__cell--${align}`],
-			props.tdClass,
-			column.tdClass,
-			content,
-			column.key,
-			item.item
-		),
-		content,
-		key: column.key,
-		label: column.label,
-		slotName,
-	};
-};
+**Pick one plan via radio rows**
 
-const mappedHeaders = computed(() =>
-	props.columns.map((column: BbTableColumn<Item>): MappedHeader => {
-		const align = column.align ?? 'left';
-		const slotName = `header:${slotNamesByKey.value[column.key]}`;
-		const sortDirection = column.sorted
-			? column.sorted === 'asc'
-				? 'ascending'
-				: 'descending'
-			: undefined;
-
-		return {
-			align,
-			key: column.key,
-			label: column.label,
-			slotName,
-			classes: mergeHeaderClasses(
-				[`bb-table-header--${align}`],
-				props.thClass,
-				column.thClass
-			),
-			sortDirection,
-		};
-	})
-);
+```vue
+<template>
+	<div class="flex max-w-xl flex-col gap-1.5">
+		<!-- `:multiple="false"` renders radios and the model is ONE value (or
+		     null) — not an array. `select-text` labels the radio column for
+		     screen readers. -->
+		<div
+			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		>
+			<BbTable
+				v-model="planId"
+				caption="Available plans"
+				:columns="columns"
+				compact
+				item-value="id"
+				:items="plans"
+				legend="Choose a plan"
+				:multiple="false"
+				name="plan"
+				select-text="Choose a plan"
+				selectable
+			/>
+		</div>
+		<p class="text-sm text-[color:var(--bb-text-muted)]">
+			Chosen plan:
+			<span class="font-medium text-[color:var(--bb-text)]">{{
+				chosen ? chosen.name : 'none yet'
+			}}</span>
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbTable } from 'bitboss-ui';
+import type { BbTableColumn } from 'bitboss-ui';
 
-const mappedItems = computed<MappedItem[]>(() => {
-	let expandedRows = 0;
-	return options.value.map((item: BaseOption, index: number): MappedItem => {
-		const disabled =
-			!props.selectable ||
-			(typeof props.selectable === 'function' &&
-				!props.selectable(item.item)) ||
-			!!item.disabled;
-
-		// How many rows have passed
-		const indexPageOffset = (props.page ?? 0 - 1) * (props.perPage ?? 0);
-		const headRowOffset = 1;
-		const increment = index + 1;
-		const rowIndex = indexPageOffset + headRowOffset + increment + expandedRows;
-
-		// Create a projection of the columns and run all formatter logic so
-		// we just display content in the template
-		const cols: MappedCell[] = props.columns.map((column) =>
-			mapColumnToCell(column, item)
-		);
-		const expanded = expandedItemsIndexedByHash.value[item.valueHash] ?? false;
-		if (expanded) {
-			expandedRows++;
-		}
-		const res = {
-			accessibleLabel: getAccessibleLabel(cols),
-			cols,
-			expanded,
-			onRowClick: (event: MouseEvent) =>
-				emit('click:row', event, item, !!item.selected),
-			onRowContextMenu: (event: MouseEvent) =>
-				emit('contextmenu:row', event, item, !!item.selected),
-			onRowDblClick: (event: MouseEvent) =>
-				emit('dblclick:row', event, item, !!item.selected),
-			item: item.item,
-			text: item.text,
-			rowIndex,
-			valueHash: item.valueHash,
-			value: item.value,
-			selected: item.selected,
-			disabled,
-		};
-		return res;
-	});
-});
+type Plan = { id: string; name: string; seats: string; price: string };
 
-const selectAll = defineModel<boolean>('selectAll', {
-	required: false,
-	default: false,
-});
+const columns: Array<BbTableColumn<Plan>> = [
+	{ key: 'name', label: 'Plan' },
+	{ key: 'seats', label: 'Seats', width: 110 },
+	{ key: 'price', label: 'Price / month', align: 'right', width: 120 },
+];
 
-const expandedItems = defineModel<any[]>('expandedItems', {
-	required: false,
-	default: () => [],
-});
+const plans: Plan[] = [
+	{ id: 'starter', name: 'Starter', seats: 'Up to 3', price: '€0' },
+	{ id: 'growth', name: 'Growth', seats: 'Up to 25', price: '€49' },
+	{ id: 'scale', name: 'Scale', seats: 'Unlimited', price: '€199' },
+];
 
-const { data: expandedItemsIndexedByHash } = useIndexById({
-	items: expandedItems,
-});
+// Single-select model: one id (via `item-value`) or null.
+const planId = ref<string | null>(null);
 
-const onExpandControllerKeydown = (event: KeyboardEvent, valueHash: string) => {
-	if (!(event.target instanceof HTMLElement)) return;
-	if (event.target instanceof HTMLButtonElement) return;
-	if (event.key !== 'Enter' && event.key !== ' ') return;
-	event.preventDefault();
-	toggleExpandedFor(valueHash);
-};
+const chosen = computed(() => plans.find((plan) => plan.id === planId.value));
+</script>
+```
 
-const getExpandControllerProps = (item: MappedItem) => ({
-	'aria-controls': isNil(expandedItemsIndexedByHash.value[item.valueHash])
-		? undefined
-		: `expanded_${item.valueHash}`,
-	'aria-expanded': item.expanded ? 'true' : 'false',
-	onClick: (event: MouseEvent) => {
-		event.stopPropagation();
-		toggleExpandedFor(item.valueHash);
-	},
-	onKeydown: (event: KeyboardEvent) =>
-		onExpandControllerKeydown(event, item.valueHash),
-});
+`max` caps a multi-select: once reached, every unselected row's checkbox
+disables until something is deselected.
+
+Multi-select tables show a **select-all** checkbox in the header
+(`v-model:select-all`; hide it with `disable-select-all`, relabel with
+`select-all-label`). Select-all is designed for the server-side "all across
+pages" pattern: when it is on, every row reads as selected and unchecking a
+row adds its value to `v-model:unselected-items` — so your bulk endpoint
+receives `{ all: true, except: unselectedItems }` instead of thousands of ids.
+Toggling select-all clears both `modelValue` and `unselected-items`; the
+header checkbox shows an indeterminate state for partial selections.
+
+Two real constraints to design around (bugs documented from the test suite):
+
+- The select-all header checkbox **never renders its checked state** — it
+  emits and drives row state correctly, but stays visually unchecked; the
+  indeterminate dash is what users see for select-all with exclusions.
+- Turning select-all on does **not** re-emit `update:modelValue` when the
+  model is already empty. Treat `select-all` + `unselected-items` as the
+  source of truth in all-mode; don't infer "everything selected" from
+  `modelValue`.
+
+**Native `<form>` submission + select-all:** the table renders one hidden
+input per value in `modelValue`, so a plain form POST works for explicit
+selections. It does **not** serialize the select-all/exclusion pattern — in
+all-mode `modelValue` is empty, so the form posts nothing even though every
+row appears selected. For "all across pages", submit via a handler that reads
+`{ all, except: unselectedItems }` from the v-models, not via native form
+fields.
+
+### Row expansion
+
+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
+`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.
+
+**Expandable detail rows**
 
-const toggleExpandedFor = (valueHash: string) => {
-	const linkedOption = options.value.find((o) => o.valueHash === valueHash);
-	if (!linkedOption) return;
-	if (valueHash in expandedItemsIndexedByHash.value) {
-		expandedItems.value = expandedItems.value.filter(
-			(o) => hash(o) !== valueHash
-		);
-	} else {
-		expandedItems.value = [...expandedItems.value, linkedOption.value];
-	}
+```vue
+<template>
+	<!-- Track open rows with `v-model:expanded-items`. The `#actions` scope hands
+	     you `toggleExpanded` (a callback) and `expanded` (read-only) — drive the
+	     toggle through the callback, never by mutating the slot prop. -->
+	<div
+		class="max-w-2xl overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+	>
+		<BbTable
+			v-model:expanded-items="expanded"
+			actions
+			actions-text="Details"
+			caption="Invoices"
+			:columns="columns"
+			compact
+			item-value="id"
+			:items="invoices"
+		>
+			<template #actions="{ expanded: isOpen, toggleExpanded }">
+				<BbButton size="xs" variant="ghost" @click="toggleExpanded">
+					{{ isOpen ? 'Hide' : 'Details' }}
+				</BbButton>
+			</template>
+
+			<template #expand="{ item }">
+				<div class="bg-[color:var(--bb-muted)] px-3 py-2.5 text-sm">
+					<p class="font-medium">{{ item.client }} · {{ item.number }}</p>
+					<p class="text-xs text-[color:var(--bb-text-muted)]">
+						Issued {{ item.issuedAt }} · net 30 · {{ item.lines }} line items
+					</p>
+				</div>
+			</template>
+		</BbTable>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbTable } from 'bitboss-ui';
+import type { BbTableColumn } from 'bitboss-ui';
+
+type Invoice = {
+	id: string;
+	number: string;
+	client: string;
+	issuedAt: string;
+	amount: string;
+	lines: number;
 };
 
-watch(selectAll, () => {
-	unselectedItems.clear();
-	emit('update:unselectedItems', []);
-	emit('update:modelValue', []);
-});
+const columns: Array<BbTableColumn<Invoice>> = [
+	{ key: 'number', label: 'Invoice', width: 110 },
+	{ key: 'client', label: 'Client' },
+	{ key: 'amount', label: 'Amount', align: 'right', width: 100 },
+];
 
-const indeterminate = computed(() => {
-	if (props.multiple && props.modelValue.length > 0 && !props.selectAll) {
-		return true;
-	}
-	if (selectAll.value && unselectedItems.size > 0) {
-		return true;
-	}
-	return false;
-});
+const invoices: Invoice[] = [
+	{
+		id: '1',
+		number: 'INV-1041',
+		client: 'Northwind Traders',
+		issuedAt: '02/06/2026',
+		amount: '€4,200',
+		lines: 6,
+	},
+	{
+		id: '2',
+		number: 'INV-1042',
+		client: 'Globex',
+		issuedAt: '11/06/2026',
+		amount: '€980',
+		lines: 2,
+	},
+	{
+		id: '3',
+		number: 'INV-1043',
+		client: 'Initech',
+		issuedAt: '19/05/2026',
+		amount: '€15,600',
+		lines: 11,
+	},
+];
 
-const unselectedItems = reactive(new Set<string>());
-watch(
-	() => props.unselectedItems,
-	() => {
-		unselectedItems.clear();
-		props.unselectedItems.forEach((i) => {
-			unselectedItems.add(hash(i));
-		});
-	}
-);
+// Holds the expanded rows' values (ids, via `item-value`).
+const expanded = ref<string[]>([]);
+</script>
+```
 
-const onInputChange = (item: BaseOption) => {
-	if (isSelected(item)) {
-		onOptionUnselected(item);
-		emit('item:unselected', item.value);
-		unselectedItems.add(item.valueHash);
-		emit('update:unselectedItems', [...props.unselectedItems, item.value]);
-		return;
-	}
-	if (!selectAll.value) {
-		onOptionSelected(item);
-	}
-	emit('item:selected', item.value);
-	unselectedItems.delete(item.valueHash);
-	emit(
-		'update:unselectedItems',
-		props.unselectedItems.filter((i) => hash(i) !== hash(item.value))
-	);
-};
+For a custom toggle control, `v-bind` the scope's `expandProps` onto it: you
+get `aria-expanded`/`aria-controls` kept in sync, a click handler that stops
+propagation (so the row click underneath doesn't also toggle highlight), and
+Enter/Space handling for non-button elements. The nested-table example below
+uses it.
+
+### 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:
+
+- `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.
+- 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).
+- **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.
+
+**Invoice lines aligned under the invoice columns**
 
-const isSelected = (item: BaseOption): boolean => {
-	if (unselectedItems.has(item.valueHash)) return false;
-	return item.selected || selectAll.value;
+```vue
+<template>
+	<!-- The nested table opts into `inherit-column-widths`: its columns snap to
+	     the parent's tracks, so line items line up under the invoice columns.
+	     The toggle binds the scope's `expandProps` for wired-up aria state. -->
+	<div
+		class="max-w-2xl overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+	>
+		<BbTable
+			v-model:expanded-items="expanded"
+			actions
+			actions-text="Line items"
+			caption="Invoices"
+			:columns="columns"
+			compact
+			item-value="id"
+			:items="invoices"
+		>
+			<template #actions="{ expanded: isOpen, expandProps }">
+				<BbButton
+					v-bind="expandProps"
+					:append:icon="isOpen ? 'lucide:chevron-up' : 'lucide:chevron-down'"
+					size="xs"
+					variant="ghost"
+				>
+					Lines
+				</BbButton>
+			</template>
+
+			<template #expand="{ item }">
+				<div class="bg-[color:var(--bb-muted)] px-1 py-1">
+					<BbTable
+						:caption="`Line items of ${item.number}`"
+						:columns="lineColumns"
+						compact
+						inherit-column-widths
+						item-value="id"
+						:items="item.lines"
+					/>
+				</div>
+			</template>
+		</BbTable>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbTable } from 'bitboss-ui';
+import type { BbTableColumn } from 'bitboss-ui';
+
+type Line = { id: string; description: string; qty: number; amount: string };
+type Invoice = {
+	id: string;
+	number: string;
+	client: string;
+	amount: string;
+	lines: Line[];
 };
 
-/**
- * When using this component for submission we add a bunch of hidden inputs
- * so the submitted inputs is on par with v-model
- */
-
-/**
- * This is used to keep the value compatible to common html expected values.
- * Convert to string everything that's not but do not double encode strings
- */
-const makeInputValue = when(
-	(item: unknown) => typeof item !== 'string',
-	JSON.stringify
-);
-const hiddenInputs = computed(() =>
-	[].concat(props.modelValue ?? []).map((current: unknown) => ({
-		disabled: props.disabled,
-		name: props.name,
-		type: 'hidden' as const,
-		value: makeInputValue(current),
-	}))
-);
-
-/** Varied line widths for skeleton (percent) to avoid a mechanical look */
-const skeletonLineWidths = [70, 45, 85, 55];
+const columns: Array<BbTableColumn<Invoice>> = [
+	{ key: 'number', label: 'Invoice', width: 110 },
+	{ key: 'client', label: 'Client' },
+	{ key: 'amount', label: 'Amount', align: 'right', width: 100 },
+];
 
-const skeletonLength = computed(() =>
-	clamp(options.value.length || props.columns.length || 1, 4, 10)
-);
+const lineColumns: Array<BbTableColumn<Line>> = [
+	{ key: 'description', label: 'Description' },
+	{ key: 'qty', label: 'Qty', width: 60 },
+	{ key: 'amount', label: 'Amount', align: 'right', width: 100 },
+];
 
-watch(
-	() => [mappedItems.value, props.fixedColumns],
-	() => {
-		if (tableRef.value && props.fixedColumns?.length) {
-			applyFixedTableColumns(tableRef.value, props.fixedColumns);
-		}
+const invoices: Invoice[] = [
+	{
+		id: '1',
+		number: 'INV-1041',
+		client: 'Northwind Traders',
+		amount: '€4,200',
+		lines: [
+			{
+				id: '1a',
+				description: 'Design retainer — June',
+				qty: 1,
+				amount: '€3,000',
+			},
+			{
+				id: '1b',
+				description: 'Icon set extension',
+				qty: 24,
+				amount: '€1,200',
+			},
+		],
 	},
-	{ flush: 'post' }
-);
-</script>
+	{
+		id: '2',
+		number: 'INV-1042',
+		client: 'Globex',
+		amount: '€980',
+		lines: [
+			{ id: '2a', description: 'Accessibility audit', qty: 1, amount: '€980' },
+		],
+	},
+];
 
-<style lang="postcss">
-@import './index.css';
-</style>
+const expanded = ref<string[]>([]);
+</script>
 ```
 
-## Types
+### Row highlight (master–detail)
 
-```ts
-import type { Classes } from '@/types/Classes';
-import type { Option } from '@/types/Option';
-import type { InputHTMLAttributes } from 'vue';
+`v-model:highlighted` is a parallel, UI-intent state — "the record whose
+details are open" — independent of selection. Clicking anywhere on a row
+toggles it: in single mode a new click replaces the previous highlight and
+clicking the highlighted row clears it back to `null`; `highlight-multiple`
+turns the model into an array (a non-array value then throws). Two kinds of
+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).
 
-/**
- * Recursively builds dot-notation paths from a type's keys.
- * Depth-limited to 3 levels to avoid compiler performance issues.
- */
-type NestedPaths<T, Depth extends unknown[] = []> = Depth['length'] extends 3
-	? never
-	: 0 extends 1 & T
-		? string
-		: T extends object
-			? T extends any[] | Date | Function | RegExp | Map<any, any> | Set<any>
-				? never
-				: {
-						[K in Extract<keyof T, string>]:
-							| K
-							| `${K}.${NestedPaths<NonNullable<T[K]>, [...Depth, unknown]>}`;
-					}[Extract<keyof T, string>]
-			: never;
+Highlight ships **unstyled**: the row only gets `aria-current="true"` and the
+`bb-table-data__row--highlighted` class. Paint the active row yourself —
+idiomatically through the public `row-class` API against the highlighted
+value, as here.
 
-/**
- * Suggested keys for a column derived from an Item type.
- * Provides autocomplete for nested dot-notation paths (up to 3 levels)
- * while still allowing arbitrary string keys for virtual columns.
- */
-export type ItemKey<Item = any> = NestedPaths<Item> | (string & {});
+**Click a row to preview it**
 
-/**
- * Skeleton placeholder style for the loading state.
- * Matches the expected content type for a better loading experience.
- */
-export type SkeletonType =
-	| 'text'
-	| 'avatar'
-	| 'avatar-text'
-	| 'image'
-	| 'badge';
-
-export type BaseColumn<Item = any> = {
-	/**
-	 * When set to false the formatter will not run on nullish values.
-	 * By default is true so you can create virtual columns with keys that do not
-	 * reference a prop in the `item` and still extract data from the other
-	 * arguments in the formatting function.
-	 */
-	formatOnNull?: boolean;
-
-	/**
-	 * Formatting function used to generate enhanced content.
-	 * @param content The content generated by the extraction of `Item[key]`
-	 * @param key Key of the column taken from the column definition.
-	 * @param item Item of the row.
-	 */
-	formatter?: (content: any, key: string, item: Item) => any;
-
-	/**
-	 * Key identifying the column.
-	 */
-	key: ItemKey<Item>;
-
-	/**
-	 * Text used in the header for this column.
-	 */
-	label: string;
-
-	/**
-	 * Placeholder used when the pipeline returns null content.
-	 */
-	placeholder?: string;
-};
-
-/**
- * Column definition for BbTable. Controls data extraction, formatting, alignment, and styling.
- */
-export type BbTableColumn<Item = any> = BaseColumn<Item> & {
-	/**
-	 * Text alignment of the column.
-	 */
-	align?: 'left' | 'right' | 'center';
-
-	/**
-	 * Skeleton placeholder style shown during loading. Defaults to `'text'`.
-	 */
-	skeleton?: SkeletonType;
-
-	/**
-	 * Defines the sorting direction of the column.
-	 */
-	sorted?: 'asc' | 'desc';
-
-	/**
-	 * Defines the classes to be passed to the `<td>` elements. Can also be a function for dynamic values.
-	 */
-	tdClass?: ColumnClasses<Item>;
-
-	/**
-	 * Defines the classes to be passed to the `<th>`.
-	 */
-	thClass?: Classes;
-
-	/**
-	 * Freezes the column to a fixed width (numbers are treated as px). When
-	 * omitted the column syncs its width to the parent table's matching track.
-	 */
-	width?: number | string;
-
-	/**
-	 * For a nested table, where this column snaps onto the parent's grid. The
-	 * parent's columns form snap points where `select` occupies `[0, 1]`, data
-	 * column `k` occupies `[k + 1, k + 2]` and `actions` occupies `[N + 1, N + 2]`.
-	 *
-	 * - A single number is a start snap point that takes one parent track, e.g.
-	 *   `2` → `[2, 3]`. It may skip ahead (`5` jumps straight to the sixth track),
-	 *   and the next column resumes from where it ends.
-	 * - A `[start, end]` pair snaps between two points; the width is the sum of
-	 *   the fractional parent tracks it covers, so `[3, 4.5]` is the full fourth
-	 *   track plus half of the fifth. `end` of `-1` runs to the end of the data
-	 *   region.
-	 *
-	 * When omitted the column chains from the previous column's end to the next
-	 * whole snap point (a one-to-one inheritance by index).
-	 */
-	snap?: number | [start: number, end: number];
-};
+```vue
+<template>
+	<div class="flex max-w-3xl flex-col gap-3 sm:flex-row sm:gap-3">
+		<!-- Clicking a row toggles `v-model:highlighted` (the "open record" state,
+		     separate from selection). Highlight ships unstyled, so we paint the
+		     active row ourselves through the public `row-class` API. -->
+		<div
+			class="min-w-0 flex-1 overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		>
+			<BbTable
+				v-model:highlighted="highlighted"
+				caption="Invoices"
+				:columns="columns"
+				compact
+				item-value="id"
+				:items="invoices"
+				:row-class="rowClass"
+			/>
+		</div>
+
+		<aside
+			class="w-full shrink-0 rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3 text-sm sm:w-52"
+		>
+			<template v-if="active">
+				<p class="font-medium">{{ active.client }}</p>
+				<p class="mt-0.5 text-xs text-[color:var(--bb-text-muted)]">
+					{{ active.number }} · {{ active.amount }}
+				</p>
+			</template>
+			<p v-else class="text-xs text-[color:var(--bb-text-muted)]">
+				Select an invoice to preview it.
+			</p>
+		</aside>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbTable } from 'bitboss-ui';
+import type { BbTableColumn } from 'bitboss-ui';
 
-export type BbTableProps<Item = any> = {
-	/**
-	 * Function that accepts the columns and the current item as
-	 * arguments and returns a label to be used for accessibility purposes.
-	 */
-	accessibleLabel?: (columns: MappedCell[], item: any) => string;
-
-	/**
-	 * Displays the actions column.
-	 */
-	actions?: boolean;
-
-	/**
-	 * Label used in the header of the actions column.
-	 */
-	actionsText?: string;
-
-	/**
-	 * Text alignment of the columns.
-	 */
-	align?: 'left' | 'center' | 'right';
-
-	/**
-	 * 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.
-	 */
-	id?: string;
-
-	/**
-	 * 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 independently unless you ask for alignment.
-	 * - `false` (the default): do not inherit; size independently.
-	 * - `true`: inherit from the nearest ancestor table.
-	 * - a table id (string): inherit from the specific ancestor in the chain with
-	 *   that id rather than the immediate parent. Use this when an intermediate
-	 *   table has a different column count, so the extra columns would otherwise
-	 *   misalign against it.
-	 */
-	inheritColumnWidths?: boolean | string;
-
-	/**
-	 * Boolean that defines whether to display a "Select all" checkbox.
-	 */
-	allowSelectAll?: boolean;
-
-	/**
-	 * Caption that describes the content of the table. Used for accessibility purposes.
-	 */
-	caption?: string;
-
-	/**
-	 * Array of definitions of how the columns should be rendered.
-	 *
-	 */
-	columns: BbTableColumn<Item>[];
-
-	/**
-	 * Adds a CSS class that applies a compact style to the component.
-	 */
-	compact?: boolean;
-
-	/**
-	 * Defines an array of dependencies that will trigger actions in the component upon change.
-	 */
-	dependencies?: any[];
-
-	/**
-	 * Timeout used to debounce response to changes to dependencies.
-	 */
-	depsDebounceTime?: number;
-
-	/**
-	 * Disables the component
-	 */
-	disabled?: boolean;
-
-	/**
-	 * Boolean that defines whether to display or hide the caption.
-	 * By default is true and the caption is hidden.
-	 */
-	displayCaption?: boolean;
-
-	/**
-	 * Defines the table layout as fixed
-	 * making each column take up the same amount of space.
-	 */
-	fixed?: boolean;
-
-	/**
-	 * 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.
-	 */
-	fixedColumns?: (number | { index: number; position: 'left' | 'right' })[];
-
-	/**
-	 * Boolean that sets the headers as sticky to the top of the table.
-	 */
-	fixedHeaders?: boolean;
-
-	items:
-		| Item[]
-		| ((prefill: boolean, modelValue?: any[]) => Promise<Item[]>)
-		| ((prefill: boolean, modelValue?: any[]) => Item[]);
-
-	itemValue?: string | ((item: Item) => any);
-
-	/**
-	 * Text content of the legend.
-	 */
-	legend?: string;
-
-	/**
-	 * Sets the component in a loading state, usually triggering some visual styles.
-	 */
-	loading?: boolean;
-
-	/**
-	 * String displayed while items are being loaded.
-	 */
-	loadingText?: string;
-
-	/**
-	 * Maximum number of items that can be selected.
-	 */
-	max?: number;
-
-	/**
-	 * Used by v-model. Can be any serializable type.
-	 */
-	modelValue?: any;
-
-	/**
-	 * Allows the selection of multiple items.
-	 */
-	multiple?: boolean;
-
-	/**
-	 * Defines the name of the input.
-	 */
-	name?: InputHTMLAttributes['name'];
-
-	/**
-	 * String displayed when there are no items to display.
-	 */
-	noDataText?: string;
-
-	/**
-	 * Current page number starting from 1, used for accessibility purposes.
-	 */
-	page?: number;
-
-	/**
-	 * Number of items per page, used for accessibility purposes.
-	 */
-	perPage?: number;
-
-	/**
-	 * Sets the input in a readonly state.
-	 */
-	readonly?: boolean;
-
-	/**
-	 * Defines whether the "Select all" checkbox is checked.
-	 */
-	selectAll?: boolean;
-
-	/**
-	 * 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.
-	 */
-	selectable?: boolean | ((item: Item) => boolean);
-
-	/**
-	 * Text of the label used by the "Select all" boolean.
-	 */
-	selectAllLabel?: string;
-
-	/**
-	 * Text of the header used for the radio inputs when the table is not `multiple`.
-	 */
-	selectText?: string;
-
-	/**
-	 * Defines the classes to be passed to the `<td>` elements. Can also be a function for dynamic values.
-	 */
-	tdClass?: ColumnClasses<Item>;
-
-	/**
-	 * Defines the classes to be passed to the `<th>`.
-	 */
-	thClass?: Classes;
-
-	/**
-	 * Total number of items there is.
-	 */
-	totalItems?: number;
-
-	/**
-	 * Items that are not selected.
-	 */
-	unselectedItems?: any[];
-};
+type Invoice = { id: string; number: string; client: string; amount: string };
 
-/**
- * We allow table data classes to be a function so it can depend on the item
- */
-export type ColumnClasses<Item = any> =
-	| Classes
-	| ((content: any, key: string, item: Item) => Classes);
+const columns: Array<BbTableColumn<Invoice>> = [
+	{ key: 'number', label: 'Invoice', width: 110 },
+	{ key: 'client', label: 'Client' },
+	{ key: 'amount', label: 'Amount', align: 'right', width: 100 },
+];
 
-/**
- * Projection that represents a row of cells with flags
- * linked to the state of the item
- */
-export type MappedItem = Option & {
-	accessibleLabel: string;
-	cols: MappedCell[];
-	expanded: boolean;
-	onRowClick: (event: MouseEvent) => void;
-	onRowContextMenu: (event: MouseEvent) => void;
-	onRowDblClick: (event: MouseEvent) => void;
-	rowIndex: number | undefined;
-};
-
-/**
- * Projection that represents a header
- */
-export type MappedHeader = {
-	align: HTMLTableCellElement['align'];
-	classes?: Classes;
-	key: string;
-	label: string;
-	slotName: string;
-	sortDirection?: 'ascending' | 'descending';
-};
-
-/**
- * Projection that represents a cell of data for display.
- */
-export type MappedCell = {
-	align: string;
-	classes: Classes;
-	content: any;
-	key: string;
-	label: string;
-	slotName: string;
-};
+const invoices: Invoice[] = [
+	{
+		id: '1',
+		number: 'INV-1041',
+		client: 'Northwind Traders',
+		amount: '€4,200',
+	},
+	{ id: '2', number: 'INV-1042', client: 'Globex', amount: '€980' },
+	{ id: '3', number: 'INV-1043', client: 'Initech', amount: '€15,600' },
+];
 
-export type ExpandControllerProps = {
-	'aria-controls'?: string;
-	'aria-expanded': 'true' | 'false';
-	onClick: () => void;
-	onKeydown: (event: KeyboardEvent) => void;
-};
+// `item-value="id"` means `highlighted` is the row's id.
+const highlighted = ref<string | null>(null);
 
-export type BbTableEvents = {
-	(e: 'click:row', event: MouseEvent, item: any, selected: boolean): void;
-	(e: 'contextmenu:row', event: MouseEvent, item: any, selected: boolean): void;
-	(e: 'dblclick:row', event: MouseEvent, item: any, selected: boolean): void;
-	(e: 'update:modelValue', value: any): void;
-	(e: 'update:selectAll', value: boolean): void;
-	(e: 'update:expandedItems', value: any[]): void;
-	(e: 'update:unselectedItems', value: any[]): void;
-	(e: 'item:selected', value: any): void;
-	(e: 'item:unselected', value: any): void;
-};
+const active = computed(() =>
+	invoices.find((invoice) => invoice.id === highlighted.value)
+);
 
-export type BbTableSlots<Item = any> = {
-	/**
-	 * Replaces the entire `<thead>` element. Use when you need full control over the header markup.
-	 */
-	thead?: (props: object) => any;
-	/**
-	 * Replaces the entire `<tbody>` element. Use when you need full control over the body markup.
-	 */
-	tbody?: (props: object) => any;
-	/**
-	 * Replaces the entire `<tfoot>` element. Use when you need full control over the footer markup.
-	 */
-	tfoot?: (props: object) => any;
-	/**
-	 * Replaces the default selection header cell content (checkbox or radio label).
-	 * @param multiple - Whether the table allows multiple selection.
-	 * @param selectAll - Whether the "select all" checkbox is currently checked.
-	 * @param text - The accessible label text for the select-all control.
-	 */
-	'header:select'?: (props: {
-		multiple: boolean;
-		selectAll: boolean;
-		text: string;
-	}) => any;
-	/**
-	 * Replaces the default actions header cell content.
-	 * @param text - The accessible label text for the actions column header.
-	 */
-	'header:actions'?: (props: { text: string }) => any;
-	/**
-	 * Content shown while table rows are loading (replaces the skeleton rows).
-	 * @param items - The current (possibly stale) list of items, useful to match the previous row count.
-	 */
-	loading?: (props: { items: Item[] }) => any;
-	/**
-	 * Content shown when the items list is empty and not loading.
-	 */
-	'no-data'?: (props: object) => any;
-	/**
-	 * Content rendered in the actions cell for each row.
-	 * @param expanded - Whether this row is currently expanded.
-	 * @param expandProps - Bind these onto an expand-toggle button to wire up aria attributes and keyboard handling.
-	 * @param toggleExpanded - Toggles the expanded state for this row.
-	 * @param item - The raw item for this row.
-	 * @param value - The resolved value for this row.
-	 */
-	actions?: (props: {
-		expanded?: boolean;
-		expandProps?: ExpandControllerProps;
-		toggleExpanded?: () => void;
-		item: Item;
-		value: any;
-	}) => any;
-	/**
-	 * Full-width expandable content row rendered below each main row when expanded.
-	 * @param expanded - Whether this row is currently expanded.
-	 * @param expandProps - Bind these onto an expand-toggle button to wire up aria attributes and keyboard handling.
-	 * @param toggleExpanded - Toggles the expanded state for this row.
-	 * @param item - The raw item for this row.
-	 * @param value - The resolved value for this row.
-	 */
-	expand?: (props: {
-		expanded: boolean;
-		expandProps?: ExpandControllerProps;
-		toggleExpanded: () => void;
-		item: Item;
-		value: any;
-	}) => any;
-	/**
-	 * Replaces the default checkbox/radio in the selection cell for each row.
-	 * @param item - The raw item for this row.
-	 * @param value - The resolved value for this row.
-	 * @param checked - Whether this row is currently selected.
-	 * @param disabled - Whether this row's selection control is disabled.
-	 * @param inputName - The `name` attribute for the selection input.
-	 * @param readonly - Whether the selection control is read-only.
-	 */
-	select?: (props: {
-		item: Item;
-		value: any;
-		checked: boolean;
-		disabled: boolean;
-		inputName: string;
-		readonly: boolean;
-	}) => any;
-} & {
-	/**
-	 * Named slot for a specific column cell (`col-key`) or column header (`header:col-key`).
-	 * @param classes - CSS classes computed for the cell.
-	 * @param content - The formatted cell content.
-	 * @param expanded - Whether this row is currently expanded (body slots only).
-	 * @param expandProps - Bind these onto an expand-toggle button (body slots only).
-	 * @param toggleExpanded - Toggles the expanded state for this row (body slots only).
-	 * @param item - The raw item for this row (body slots only).
-	 * @param value - The resolved row value (body slots only).
-	 * @param items - The full items list (header slots only).
-	 * @param label - The column label (header slots only).
-	 */
-	[key: string]: (props: {
-		classes?: Classes[];
-		content?: any;
-		expanded?: boolean;
-		expandProps?: ExpandControllerProps;
-		toggleExpanded?: () => void;
-		item: Item;
-		value?: any;
-		items?: Item[];
-		label?: string;
-	}) => any;
-};
+// Primary tint for the open row — selection chrome stays on content, not hover.
+const rowClass = (invoice: Invoice) =>
+	invoice.id === highlighted.value
+		? 'cursor-pointer bg-[color:color-mix(in_oklab,var(--bb-primary)_8%,var(--bb-panel))]'
+		: 'cursor-pointer';
+</script>
 ```
 
-## Styles
-
-```css
-.bb-table {
-	--padding-x: 16px;
-	--padding-y: 8px;
-	--actions-spacing: 8px;
-	/* Raw structural edge offset measured by the component (the parent's
-	   select/actions track width). Default 0 keeps every calc at its base. */
-	--bb-table-offset-start: 0px;
-	--bb-table-offset-end: 0px;
-	/* Routing of that offset. By default it is "internal": added to the
-	   first/last cell padding and folded into the first/last column width.
-	   Swap internal↔external (set internal to 0 and external to the raw offset)
-	   to pad the whole table instead of the edge cells. */
-	--bb-table-offset-internal-start: var(--bb-table-offset-start);
-	--bb-table-offset-internal-end: var(--bb-table-offset-end);
-	--bb-table-offset-external-start: 0px;
-	--bb-table-offset-external-end: 0px;
-	/* Slack the fill column adds to reach the parent's width. Reset per table so a
-	   nested table never inherits an ancestor's value through the cascade. */
-	--bb-table-fill: 0px;
-	border-collapse: separate;
-	border-spacing: 0;
-	display: grid;
-	/* Override the UA `min-inline-size: min-content` that a <fieldset> container
-	   (rendered for selectable tables) carries — without this the container can't
-	   shrink below the table's content width, so it overflows its parent and
-	   pushes the page instead of scrolling inside its own `overflow-x: auto`. */
-	min-width: 0;
-	overflow-x: auto;
-	padding-inline-end: var(--bb-table-offset-external-end);
-	padding-inline-start: var(--bb-table-offset-external-start);
-
-	position: relative;
-
-	&--align {
-		&-left {
-			text-align: left;
-		}
-		&-center {
-			text-align: center;
-		}
-		&-right {
-			text-align: right;
-		}
-	}
-
-	&--compact {
-		--padding-x: 8px;
-		--padding-y: 4px;
-	}
-
-	&--fixed {
-		> table {
-			table-layout: fixed;
-			width: 100%;
+### Keyboard navigation and row events
 
-			thead {
-				.bb-table-header--actions {
-					width: auto;
-				}
-			}
-		}
-	}
+Add `keyboard-navigation` to make the body a single tab stop with a roving
+tabindex: ArrowUp/ArrowDown move the focused row (PageUp/PageDown stride ten
+rows, Home/End jump), and
+Enter/Space activate it through the same path as a mouse click — highlight
+toggle plus `click:row`. Focus and highlight stay independent: arrowing over
+rows opens nothing until the user commits. A mouse click re-anchors arrow
+navigation, focused rows show the standard focus ring, and keys pressed inside
+interactive descendants (or a nested table) keep their own semantics.
 
-	&--fixed-header {
-		table {
-			thead {
-				th {
-					position: sticky;
-					top: 0;
-					z-index: 1;
-				}
-				th[style*='sticky'] {
-					position: sticky;
-					top: 0;
-					z-index: 2;
-				}
-			}
-		}
-	}
-
-	&--loading {
-	}
+**Arrow through the audit log, Enter opens**
 
-	&--empty {
-	}
+```vue
+<template>
+	<div class="flex max-w-2xl flex-col gap-1.5">
+		<!-- `keyboard-navigation` makes the body one tab stop: ↑/↓ move the
+		     focused row, Home/End jump, Enter/Space open it (same path as a
+		     click, so it toggles `highlighted` and emits `click:row`). -->
+		<div
+			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		>
+			<BbTable
+				v-model:highlighted="openEventId"
+				caption="Audit log"
+				:columns="columns"
+				compact
+				item-value="id"
+				:items="events"
+				keyboard-navigation
+				:row-class="rowClass"
+			/>
+		</div>
+		<p class="text-xs text-[color:var(--bb-text-muted)]">
+			Tab into the table, move with the arrow keys, press Enter to open a row.
+			Open event:
+			<span class="font-medium text-[color:var(--bb-text)]">{{
+				openEvent ? `${openEvent.actor} — ${openEvent.action}` : 'none'
+			}}</span>
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbTable } from 'bitboss-ui';
+import type { BbTableColumn } from 'bitboss-ui';
 
-	&--selectable {
-		tr {
-			> .bb-table-data__cell--select {
-				text-align: center;
-				width: 0px;
-			}
-		}
-	}
+type AuditEvent = { id: string; time: string; actor: string; action: string };
 
-	legend {
-	}
+const columns: Array<BbTableColumn<AuditEvent>> = [
+	{ key: 'time', label: 'Time', width: 70 },
+	{ key: 'actor', label: 'Actor' },
+	{ key: 'action', label: 'Action' },
+];
 
-	table {
-		min-width: 100%;
-	}
+const events: AuditEvent[] = [
+	{ id: 'e1', time: '09:12', actor: 'ada@acme.io', action: 'Created API key' },
+	{
+		id: 'e2',
+		time: '09:47',
+		actor: 'grace@acme.io',
+		action: 'Changed billing plan',
+	},
+	{
+		id: 'e3',
+		time: '10:03',
+		actor: 'ken@acme.io',
+		action: 'Invited 2 members',
+	},
+	{ id: 'e4', time: '10:31', actor: 'ada@acme.io', action: 'Rotated secrets' },
+];
 
-	/* A nested table inheriting its parent's widths sizes to the sum of its
-	   columns instead of filling its container, so fixed layout cannot stretch
-	   them out of alignment. Declared after `--fixed` and the base table rule so
-	   it overrides their width/min-width at equal specificity. */
-	&--inherit-widths {
-		/* Never grow past the parent's expand cell: a child with more columns
-		   than the parent overflows the cell, so cap the container here and let its
-		   own `overflow-x: auto` scroll the surplus columns inside the expand row
-		   rather than stretching the ancestor. */
-		max-width: 100%;
-		min-width: 0;
-
-		table {
-			min-width: 0;
-			/* A *definite* width (not `max-content`) so `table-layout: fixed` stays
-			   content-independent: inherited columns keep their colgroup widths and
-			   align with the parent instead of growing to fit content. The fill
-			   column is `auto`, so fixed layout hands it the leftover; when columns
-			   overflow, the table grows past 100% and scrolls. */
-			width: 100%;
-		}
-	}
+const openEventId = ref<string | null>(null);
 
-	/* Declared after the base `table { min-width: 100% }` rule so it wins the
-	   cascade at equal specificity. The probe publishes the natural content width
-	   of all columns; the table fills its container freely but never compresses
-	   below that floor — the container's `overflow-x: auto` then shows a
-	   scrollbar instead of squishing content. */
-	&--fixed {
-		table {
-			min-width: var(--bb-table-natural-width, 0px);
-		}
-	}
+const openEvent = computed(() =>
+	events.find((event) => event.id === openEventId.value)
+);
 
-	.bb-table-caption {
-	}
+// Highlight ships unstyled — paint the open row through the public row-class API.
+const rowClass = (event: AuditEvent) =>
+	event.id === openEventId.value
+		? 'bg-[color:color-mix(in_oklab,var(--bb-primary)_8%,var(--bb-panel))]'
+		: '';
+</script>
+```
 
-	&-header-row {
-	}
+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 —
+logging, opening a drawer (though `v-model:highlighted` usually covers that
+without any handler).
 
-	&-header {
-		border-bottom: 1px solid var(--bb-border);
-		color: color-mix(in srgb, var(--bb-text), transparent 40%);
-		font-size: 14px;
-		font-weight: 500;
-		padding: var(--padding-y) var(--padding-x);
+### Opening a record
 
-		&--center {
-			text-align: center;
-		}
+Row navigation goes through a real link component, never a row `@click`
+handler. Render a `BbButton` in a cell or the actions column with `href` (or
+`to` in a router app): the user gets a proper anchor, middle-click and
+open-in-new-tab for free.
 
-		&--right {
-			text-align: right;
-		}
+**A per-row link via BbButton**
 
-		&--select {
-		}
+```vue
+<template>
+	<!-- Row-level navigation is offloaded to BbButton: `href` (or `to` in a
+	     router app) makes it a real link, not a JS click handler. -->
+	<div
+		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"
+			compact
+			item-value="id"
+			:items="invoices"
+		>
+			<template #actions="{ item }">
+				<BbButton
+					append:icon="lucide:arrow-right"
+					:href="`#invoice-${item.id}`"
+					size="xs"
+					variant="outline"
+				>
+					Open
+				</BbButton>
+			</template>
+		</BbTable>
+	</div>
+</template>
+<script setup lang="ts">
+import { BbButton, BbTable } from 'bitboss-ui';
+import type { BbTableColumn } from 'bitboss-ui';
 
-		&--actions {
-			width: 0;
+type Invoice = { id: string; number: string; client: string; amount: string };
 
-			.bb-table-header__content {
-			}
-		}
+const columns: Array<BbTableColumn<Invoice>> = [
+	{ key: 'number', label: 'Invoice', width: 110 },
+	{ key: 'client', label: 'Client' },
+	{ key: 'amount', label: 'Amount', align: 'right', width: 100 },
+];
 
-		&__content {
-		}
-	}
+const invoices: Invoice[] = [
+	{
+		id: '1041',
+		number: 'INV-1041',
+		client: 'Northwind Traders',
+		amount: '€4,200',
+	},
+	{ id: '1042', number: 'INV-1042', client: 'Globex', amount: '€980' },
+	{ id: '1043', number: 'INV-1043', client: 'Initech', amount: '€15,600' },
+];
+</script>
+```
 
-	tbody {
-		tr {
-			&:not(:last-child) {
-				border-bottom: 1px solid var(--bb-border);
-			}
-			td {
-				color: var(--bb-text);
-				font-size: 14px;
-				font-weight: 400;
-				height: var(--bb-table-cell-h);
-				padding: var(--padding-y) var(--padding-x);
-			}
-
-			td.bb-table-expand__cell {
-				/* Collapse to the content's height instead of inheriting the data-row
-				   cell height, so an expand row with no slot content takes no space. */
-				height: auto;
-				padding: 0;
-
-				&:empty {
-					display: none;
-				}
-			}
-		}
-	}
+In a router or Inertia app the same button carries the platform's navigation
+instead of an inert `href`:
 
-	/* Apply the structural edge offsets to the first/last *data* column. They
-	   must land on the data cells, not the absolute first/last child: a select
-	   or actions column would otherwise absorb the fill and leave the data
-	   columns misaligned with the parent (and bloat the actions cell).
-
-	   The offset is clamped at 0 here: a positive fill widens the cell and is
-	   reserved as extra edge padding, but a *negative* offset (a select/actions
-	   column reclaimed from this column's width) must not eat into the normal
-	   `--padding-x` — that only shrinks the column width, not its inner padding. */
-	thead tr > th.bb-table-header--edge-start,
-	tbody tr > td.bb-table-data__cell--edge-start {
-		padding-inline-start: calc(
-			var(--padding-x) + max(0px, var(--bb-table-offset-internal-start))
-		);
-	}
+```vue
+<!-- vue-router / Nuxt -->
+<template #actions="{ item }">
+	<BbButton :to="{ name: 'invoices.show', params: { id: item.id } }" size="xs">
+		Open
+	</BbButton>
+</template>
+```
 
-	thead tr > th.bb-table-header--edge-end,
-	tbody tr > td.bb-table-data__cell--edge-end {
-		padding-inline-end: calc(
-			var(--padding-x) + max(0px, var(--bb-table-offset-internal-end))
-		);
-	}
+```vue
+<!-- Inertia -->
+<template #actions="{ item }">
+	<BbButton :href="`/invoices/${item.id}`" size="xs">Open</BbButton>
+</template>
+```
 
-	&.bb-table--loading {
-		.bb-table-loading__row {
-			.bb-table-loading__cell {
-				padding: 0 var(--padding-x) !important;
-				vertical-align: top;
-			}
-		}
+### Inline editing
 
-		.bb-table-loading__row--sr-only {
-			.bb-table-loading__cell {
-				padding: 0 !important;
-				border: none;
-				height: 0;
-				overflow: hidden;
-			}
-		}
-	}
+Cells can edit in place — no edit page, no modal. Two commit grammars, one
+per control kind:
 
-	&-skeleton {
-		&__row {
-		}
+- **Typed cells** (text, number) bind `:model-value` down and commit on
+  `@change` (blur/Enter) — never `v-model`, which fires per keystroke and
+  turns an autosave into one request per character.
+- **Option-backed cells** are a badge acting as the trigger of a
+  `BbSelectPopover`: the pick IS the commit. The options resolve once at page
+  level as an array (never a per-row provider — see the BbSelectPopover
+  guide's table section), the badge carries an internal trailing chevron, and
+  while the save runs the badge's `loading` prop swaps the spinner into the
+  chevron's place — same size, nothing shifts.
 
-		&__cell {
-			height: var(--bb-table-cell-h);
-			overflow: hidden;
-			padding: var(--padding-y) var(--padding-x);
-			vertical-align: middle;
-
-			&--select,
-			&--actions {
-				text-align: center;
-				width: 0;
-			}
-		}
+The deeper question — who owns the uncommitted value (a draft map with an
+explicit Save, or an optimistic autosave overlay, or the rows themselves —
+never) — is the [Inline Edit Playbook](./guides/inline-edit-playbook.md).
+This example uses the autosave grammar: per-field optimistic overlay,
+rollback on failure, and overlay retirement inside the items function.
 
-		&__cell-content {
-			display: flex;
-			flex-direction: column;
-			gap: 6px;
-			justify-content: center;
-			max-height: calc(var(--bb-table-cell-h) - var(--padding-y) * 2);
-			min-width: 96px;
-		}
+**Autosave cells: commit on blur, spinner in the chevron**
 
-		&__line {
-			background: linear-gradient(
-				90deg,
-				var(--bb-border) 0%,
-				var(--bb-border) 35%,
-				color-mix(in srgb, var(--bb-border) 60%, white) 50%,
-				var(--bb-border) 65%,
-				var(--bb-border) 100%
-			);
-			background-size: 200% 100%;
-			border-radius: 6px;
-			flex-shrink: 0;
-			height: 10px;
-			animation: bb-table-skeleton-shimmer 1.8s ease-in-out infinite;
-		}
+```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="Sprint tasks — every cell saves itself"
+				:columns="columns"
+				compact
+				:dependencies="[rev]"
+				item-value="id"
+				:items="loadTasks"
+			>
+				<!-- Typed cell: bind down, commit on @change (blur/Enter) — never
+				     v-model, which fires per keystroke (one request per character). -->
+				<template #title="{ item }">
+					<BbTextInput
+						compact
+						hide-label
+						label="Title"
+						:model-value="valueOf(item, 'title')"
+						@change="onTitleChange(item, $event)"
+					/>
+				</template>
+
+				<!-- Option cell: the badge IS the trigger; the pick IS the commit.
+				     One page-level `statuses` array shared by every row (never a
+				     per-row provider). While the save runs, `loading` swaps the
+				     spinner into the chevron's place. -->
+				<template #status="{ item }">
+					<BbSelectPopover
+						compact
+						disable-writing
+						item-text="label"
+						item-value="value"
+						:items="statuses"
+						:model-value="valueOf(item, 'status')"
+						width="170px"
+						@update:model-value="persist(item, 'status', $event as Status)"
+					>
+						<template #activator="{ props }">
+							<BbBadge
+								append:icon="lucide:chevron-down"
+								:loading="pending[item.id]?.status !== undefined"
+								size="lg"
+								:variant="VARIANT[valueOf(item, 'status')]"
+							>
+								<BbBadgeButton v-bind="props">{{
+									labelFor(valueOf(item, 'status'))
+								}}</BbBadgeButton>
+							</BbBadge>
+						</template>
+					</BbSelectPopover>
+				</template>
+			</BbTable>
+		</div>
+
+		<p v-if="lastFailure" class="text-xs text-[color:var(--bb-danger)]">
+			{{ lastFailure }}
+		</p>
+		<p class="text-xs text-[color:var(--bb-text-muted)]">
+			No Save button anywhere — edits persist per field, optimistically.
+			BB-121's save always fails and rolls back.
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { reactive, ref } from 'vue';
+import {
+	BbBadge,
+	BbBadgeButton,
+	BbSelectPopover,
+	BbTable,
+	BbTextInput,
+} from 'bitboss-ui';
+import type { BadgeVariantType, BbTableColumn } from 'bitboss-ui';
+
+type Status = 'open' | 'in-progress' | 'blocked' | 'done';
+type Task = { id: string; ref: string; title: string; status: Status };
+type EditableKey = 'title' | 'status';
+type Patch = Partial<Pick<Task, EditableKey>>;
+
+const statuses: Array<{ value: Status; label: string }> = [
+	{ value: 'open', label: 'Open' },
+	{ value: 'in-progress', label: 'In progress' },
+	{ value: 'blocked', label: 'Blocked' },
+	{ value: 'done', label: 'Done' },
+];
+
+const VARIANT: Record<Status, BadgeVariantType> = {
+	open: 'soft-gray',
+	'in-progress': 'soft-blue',
+	blocked: 'soft-red',
+	done: 'soft-green',
+};
 
-		@media (prefers-reduced-motion: reduce) {
-			&__line {
-				animation: none;
-				background: var(--bb-border);
-			}
-		}
+const columns: Array<BbTableColumn<Task>> = [
+	{ key: 'ref', label: 'Ref', width: 90 },
+	{ key: 'title', label: 'Title' },
+	{ key: 'status', label: 'Status', width: 140 },
+];
 
-		&__placeholder {
-			background-color: var(--bb-border);
-			border-radius: 6px;
-			flex-shrink: 0;
-			height: 22px;
-			margin: 0 auto;
-			min-width: 22px;
-			width: 22px;
-		}
+/* ---- Fake server (deterministic: BB-121 always rejects) ---------------- */
 
-		&__avatar {
-			aspect-ratio: 1;
-			background-color: var(--bb-border);
-			border-radius: 50%;
-			flex-shrink: 0;
-			height: calc(var(--bb-table-cell-h) - var(--padding-y) * 2);
-			min-width: calc(var(--bb-table-cell-h) - var(--padding-y) * 2);
-			width: calc(var(--bb-table-cell-h) - var(--padding-y) * 2);
-		}
+let server: Task[] = [
+	{
+		id: 't-1',
+		ref: 'BB-104',
+		title: 'Popover drops focus on Esc',
+		status: 'open',
+	},
+	{
+		id: 't-2',
+		ref: 'BB-118',
+		title: 'Header misaligns at 320px',
+		status: 'in-progress',
+	},
+	{
+		id: 't-3',
+		ref: 'BB-121',
+		title: 'Token audit for dark mode',
+		status: 'blocked',
+	},
+	{
+		id: 't-4',
+		ref: 'BB-130',
+		title: 'Ship the migration guide',
+		status: 'done',
+	},
+];
 
-		&__avatar-text {
-			align-items: center;
-			display: flex;
-			gap: 12px;
-			max-height: calc(var(--bb-table-cell-h) - var(--padding-y) * 2);
-			min-width: 140px;
-		}
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 
-		&__avatar-text .bb-table-skeleton__avatar {
-			width: calc(var(--bb-table-cell-h) - var(--padding-y) * 2);
-		}
+const api = {
+	list: async (): Promise<Task[]> => {
+		await wait(150);
+		return server.map((task) => ({ ...task }));
+	},
+	patch: async (id: string, patch: Patch): Promise<void> => {
+		await wait(400);
+		const row = server.find((task) => task.id === id);
+		if (!row) return;
+		if (row.ref === 'BB-121') throw new Error('save rejected');
+		server = server.map((task) =>
+			task.id === id ? { ...task, ...patch } : task
+		);
+	},
+};
 
-		&__avatar-text .bb-table-skeleton__cell-content {
-			flex: 1;
-			min-width: 0;
-		}
+/* ---- Autosave state (the Inline Edit Playbook's flagship pattern) ------ */
 
-		&__image {
-			aspect-ratio: 4 / 3;
-			background-color: var(--bb-border);
-			border-radius: 8px;
-			height: calc(var(--bb-table-cell-h) - var(--padding-y) * 2);
-			min-width: 64px;
-			width: auto;
-		}
+const rev = ref(0);
+/** Optimistic values, per row per field — two fields can be in flight independently. */
+const pending = reactive<Record<string, Patch>>({});
+const lastFailure = ref('');
 
-		&__badge {
-			background-color: var(--bb-border);
-			border-radius: 999px;
-			flex-shrink: 0;
-			height: 26px;
-			min-width: 72px;
-			width: 88px;
-		}
-	}
+// `key in` rather than `??` so an overlay holding a committed empty/null
+// value still wins over the row (matters once a field is clearable).
+const valueOf = <K extends EditableKey>(item: Task, key: K): Task[K] => {
+	const patch = pending[item.id];
+	return patch && key in patch ? (patch[key] as Task[K]) : item[key];
+};
 
-	@keyframes bb-table-skeleton-shimmer {
-		0% {
-			background-position: 200% 0;
-		}
-		100% {
-			background-position: -200% 0;
+/**
+ * The overlay is retired HERE, in the fetch, and only for fields the response
+ * confirms — never when the save resolves. Between the save landing and the
+ * reload arriving the table still holds the OLD row; clearing early would
+ * flash the cell new → old → new for the whole reload.
+ */
+const loadTasks = async (): Promise<Task[]> => {
+	const rows = await api.list();
+	for (const row of rows) {
+		const patch = pending[row.id];
+		if (!patch) continue;
+		for (const key of Object.keys(patch) as EditableKey[]) {
+			if (patch[key] === row[key]) delete patch[key];
 		}
+		if (!Object.keys(patch).length) delete pending[row.id];
 	}
+	return rows;
+};
 
-	&-no-data {
-		&__row {
-		}
-		&__cell {
-		}
-		&__text {
+const persist = async <K extends EditableKey>(
+	item: Task,
+	key: K,
+	next: Task[K]
+) => {
+	if (next === item[key]) return; // no-op commit
+	(pending[item.id] ??= {})[key] = next; // optimistic: the UI moves now
+	try {
+		await api.patch(item.id, { [key]: next });
+		rev.value += 1; // reload; loadTasks retires the overlay once it can
+	} catch {
+		// Rollback: drop just this field — the cell reverts to the row's value.
+		delete pending[item.id]?.[key];
+		if (pending[item.id] && !Object.keys(pending[item.id]).length) {
+			delete pending[item.id];
 		}
+		lastFailure.value = `${item.ref}: ${key} save failed — rolled back.`;
 	}
+};
 
-	&-data {
-		&__row {
-		}
-		&__cell {
-			&--center {
-				text-align: center;
-			}
-
-			&--right {
-				text-align: right;
-			}
-
-			&--select {
-			}
-		}
-	}
+const onTitleChange = (item: Task, event: Event) =>
+	persist(item, 'title', (event.target as HTMLInputElement).value);
 
-	&-data-row {
-	}
+const labelFor = (status: Status) =>
+	statuses.find((option) => option.value === status)?.label ?? '—';
+</script>
 
-	&__cell {
-		&--select {
-		}
+<!-- Soft status palette — canonical source: ai/guides/design-language.md § Using color.
+     Non-scoped so variant classes on the child badge receive the accents. -->
+<style>
+.bb-badge.bb-badge--soft-gray {
+	--accent: #64748b;
+}
+.bb-badge.bb-badge--soft-blue {
+	--accent: #2563eb;
+}
+.bb-badge.bb-badge--soft-green {
+	--accent: #16a34a;
+}
+.bb-badge.bb-badge--soft-red {
+	--accent: #dc2626;
+}
+.bb-badge.bb-badge--soft-gray,
+.bb-badge.bb-badge--soft-blue,
+.bb-badge.bb-badge--soft-green,
+.bb-badge.bb-badge--soft-red {
+	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
+	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
+	--border-width: 1px;
+	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
+	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
+}
+</style>
+```
 
-		&--actions {
-			white-space: nowrap;
-			> *:not(:first-child) {
-				margin-left: var(--actions-spacing);
-			}
-		}
-	}
+The status colors are the registered `soft-*` badge variants: the plugin's
+`badgeVariants` option makes the names type-check, and the example carries
+their CSS in its own style block — the sanctioned consumer path. The
+canonical palette lives in the
+[design language guide](./guides/design-language.md).
+
+### Dense and wide tables
+
+`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.
+
+**The consumer overflow contract has two parts.** Wrap the table in an
+`overflow-x: auto` element (below), **and** make sure that wrapper is actually
+free to shrink below the table's content width. Inside a flex or grid layout,
+an item's automatic minimum size defaults to its own content's size along the
+container's main axis — so a `BbTable` inside an unconstrained flex row (a
+page shell's content column, a flex-direction: row split view) pushes that
+whole row wider instead of scrolling, even with `overflow-x: auto` already on
+the wrapper. Give that ancestor `min-width: 0` explicitly to let it shrink and
+hand scrolling to the table's own wrapper. (This only bites the flex **row**
+axis: a wrapper that is a cross-axis child of a `flex-direction: column`
+parent already has a definite width and doesn't need it — check which axis
+your wrapper actually sits on before sprinkling `min-width: 0` everywhere.)
+
+**Compact rows with a sticky header**
 
-	&-check,
-	&-radio {
-		&__label {
-			cursor: pointer;
-			display: inline-block;
-			transform: translateY(2px);
-			user-select: none;
-
-			&.bb-table {
-				&-check,
-				&-radio {
-					&__label--disabled {
-						cursor: default;
-						visibility: hidden;
-					}
-				}
-			}
-
-			&.bb-table-radio__label--disabled {
-				cursor: default;
-			}
-
-			&-text {
-			}
-		}
-	}
-}
+```vue
+<div
+	class="max-h-52 max-w-2xl overflow-auto rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+>
+	<BbTable
+		caption="Server fleet"
+		compact
+		fixed-headers
+		:columns="[
+			{ key: 'host', label: 'Host' },
+			{ key: 'region', label: 'Region' },
+			{ key: 'cpu', label: 'CPU', align: 'right' },
+			{ key: 'memory', label: 'Memory', align: 'right' },
+			{ key: 'status', label: 'Status' },
+		]"
+		:items="[
+			{ host: 'web-01', region: 'eu-west-1', cpu: '38%', memory: '61%', status: 'Healthy' },
+			{ host: 'web-02', region: 'eu-west-1', cpu: '52%', memory: '70%', status: 'Healthy' },
+			{ host: 'api-01', region: 'us-east-2', cpu: '74%', memory: '80%', status: 'Healthy' },
+			{ host: 'db-01', region: 'us-east-2', cpu: '81%', memory: '88%', status: 'Degraded' },
+			{ host: 'cache-01', region: 'ap-south-1', cpu: '22%', memory: '35%', status: 'Healthy' },
+		]"
+	/>
+</div>
 ```
+
+### Config and platform
+
+- **Locale.** The plugin's `locale` (`it`/`en`) drives the built-in strings:
+  the no-data text, the select-all label, the single-select header text, and
+  the "Select" prefix of each row's accessible selection label. Override any
+  of them per table via `no-data-text` / `select-all-label` / `select-text`.
+- **`actions-text` is localized** like the other built-in strings (`it` →
+  `Azioni`, `en` → `Actions`). Seeing `Azioni` in an English app means the
+  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.
+- **Forms.** With `name`, the selection submits as hidden inputs — no JS
+  needed between the table and a plain `<form>` POST (Inertia included).
+
+### Works well with
+
+- `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.
+- `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.
+- `BbTextInput` / `BbSelect` filters feeding `dependencies`.
+- `useConfirm` + `useToast` — destructive row actions with feedback; the full
+  assembly is the records workspace recipe
+  (`./recipes/vue/records-workspace.md`).
+- Inline editing — the ownership patterns are the
+  [Inline Edit Playbook](./guides/inline-edit-playbook.md); the full autosave
+  page is the inline-edit workspace recipe
+  (`./recipes/vue/inline-edit-workspace.md`).
+- `BbTree` — when the data is genuinely recursive rather than rows + detail.
+
+### Gotchas and constraints
+
+- Slot names are **lowercased**: a camelCase key like `issuedAt` yields
+  `#issuedat`. Prefer snake_case keys.
+- `loading-text` has no default — an unset value announces nothing.
+- The `accessibleLabel` prop is currently ignored: row selection labels are
+  always built from every cell's content. Rely on the default; don't expect a
+  custom function to apply.
+- The select-all checkbox never renders checked, and enabling it 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`.
+- 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 and with
+  `highlight-multiple`, `highlighted` must be one — both throw otherwise.
+
+### Anti-patterns
+
+- Watching filters and refetching manually — list them in `dependencies`.
+- Expecting the table to sort, slice or fetch: it reports state; you apply it.
+- Hand-rolling selection pruning after a refetch — that's `enforce-coherence`
+  (see Selection across refetches); reserve provider-side reconciliation for
+  paginated tables, where the prop must stay off.
+- Pre-mapping items into `{ label, value }` — pass domain objects +
+  `item-value`.
+- `@click:row` + `router.push` for navigation — render a real `BbButton` link.
+- Rebuilding selection controls in a cell slot — use `selectable`, the
+  `#select` slot, or the scope's `toggleSelected`.
+- Mutating slot-scope flags (`expanded`, `selected`, `highlighted`) — they are
+  one-way; call the paired `toggle*` callback.
+- Omitting `item-value` on tables with selection/expansion/highlight —
+  object-identity matching breaks across refetches.
+
+### Accessibility
+
+- Always give the table a `caption` describing its content. It is visually
+  hidden by default (available to screen readers); set `display-caption` to
+  show it as a visible title.
+- A selectable table is a `<fieldset>` — pass `legend`. Each selection control
+  carries a visually-hidden label built from the row's cell contents.
+- Set `item-value` so selection, expansion and highlight track rows by stable
+  identity rather than object reference.
+- Sortable headers set `aria-sort` and render real buttons; custom header
+  slots should keep a button calling `toggleSort`.
+- 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.
+- The loading row is an `aria-live` status — always set `loading-text`.
+- The highlighted row carries `aria-current="true"`; add `keyboard-navigation`
+  so row-level interaction is reachable without a mouse (roving tabindex,
+  Arrow/PageUp/PageDown/Home/End, Enter/Space).
+- Keep row-level navigation in real `BbButton` links (`href` / `to`), never a
+  bare `@click:row` — links are focusable and announced as links.
+
+## v-model
+
+- `v-model:expandedItems` — type: `any[] \| undefined`
+- `v-model:highlighted` — type: `any`
+- `v-model` — type: `any`
+- `v-model:selectAll` — type: `boolean \| undefined`
+- `v-model:sort` — type: `BbTableSortEntry[] \| undefined`
+- `v-model:unselectedItems` — type: `any[] \| undefined`
+
+## Props
+
+| 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. |
+| `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. |
+| `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… |
+| `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`) by default; an array of values with `highlightMultiple`. Purely mechanical: highlighted ro… |
+| `highlightMultiple` | `boolean \| undefined` |  |  | Allows highlighting multiple rows: `highlighted` becomes an array of item values instead of a single value. |
+| `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 … |
+| `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 … |
+| `legend` | `string \| undefined` |  |  | Text content of the legend. |
+| `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` |  |  | String displayed while items are being loaded. |
+| `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. |
+| `page` | `number \| undefined` |  |  | Current page number starting from 1, used for accessibility purposes. |
+| `perPage` | `number \| undefined` |  |  | Number of items per page, used for accessibility purposes. |
+| `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. |
+| `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>`. |
+| `totalItems` | `number \| undefined` |  |  | Total number of items there is. |
+| `totalPages` | `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. |
+
+## 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`
+- `item:selected` — `(e: "item:selected", value: any): void`
+- `item:unselected` — `(e: "item:unselected", value: any): void`
+- `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: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.
+- `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: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…
+- `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.
+
+## See Also
+
+- [BbTree](./BbTree.md) — Renders hierarchical expandable tree structures.
+- [BbPagination](./BbPagination.md) — Navigates paginated data sets by page index.