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

package/dist/llms-full.txt

@@ -27026,7 +27026,7 @@ needs is declared here, not in markup:
   `(content, key, item) => Classes` for state-dependent styling. Table-level
   `thClass` / `tdClass` / `rowClass` / `headerRowClass` apply everywhere; a
   row's classes accumulate the table `rowClass` plus every column's.
-- **`snap`** maps a nested table's column onto its parent's tracks — see
+- **`snap`** names the parent column a nested table's column sits under — see
   Nested tables.
 
 **Columns, formatters and a per-row class**
@@ -27155,11 +27155,11 @@ pre-mapping your items:
 ```
 
 **`actions` and `select` are not columns.** Both are rendered by the table
-itself, from the `actions` and `selectable` props. Putting
-`{ key: 'actions' }` in `columns` adds an ordinary data column that reads
-`item.actions`, so you get a stray empty cell _and_ the `#actions` slot never
-renders — which looks like a broken slot and is really a bad column list. Dev
-builds warn.
+itself: the selection column from the `selectable` prop, the actions column
+from the `#actions` slot — providing the slot is what creates the column,
+there is no prop. Putting `{ key: 'actions' }` in `columns` adds an ordinary
+data column that reads `item.actions`, so you get a stray empty cell next to
+the real one. Dev builds warn.
 
 ### Custom cells and headers
 
@@ -27182,7 +27182,8 @@ Body cell scope: `content` (the formatted value), `item` (raw row), `value`
 one-way state; the `toggle*` callbacks are the write path.
 
 Header scope: `label`, `items` (the full list — handy for counts), `sortable`,
-`sortOrder`, `toggleSort`, `classes`.
+`sortOrder`, `toggleSort`, `hideColumn` (hides the column, see "Column
+visibility"), `classes`.
 
 **Add beside a header instead of replacing it** with
 `#header:<key>:prepend` / `#header:<key>:append` — rendered before / after the
@@ -27794,12 +27795,14 @@ The model's contract is what makes a column panel trivial:
 
 - Keys listed first render first; declared columns the array omits follow, in
   declaration order (a column added to `columns` later renders last).
-- Keys that match no declared column render nothing but are **preserved in
-  place**. So hide a column by filtering it out of `columns` — never out of
-  the order — and it comes back exactly where it was.
+- A `hidden` column (next section) keeps its slot without rendering, and keys
+  that match no declared column render nothing but are **preserved in
+  place** — a column that exists only for some users comes back exactly where
+  it was.
 - A user move relocates **exactly one key**; everything else, hidden keys
   included, keeps its relative order. The first move on a partial (or empty)
-  model emits the completed array — persist that.
+  model emits the completed array — every declared key, hidden ones included
+  — so persist that and the model is complete from then on.
 - A drop that changes nothing emits nothing; unbound, the table keeps the
   order as per-mount state like `sort`.
 
@@ -27810,8 +27813,9 @@ The model's contract is what makes a column panel trivial:
 	<div class="flex max-w-2xl flex-col gap-3">
 		<!-- ONE order, two writers: the panel's buttons and the table's own
 		     header drag / keyboard handles both write `v-model:order`.
-		     Hiding a column only filters `columns` — its key stays in the order,
-		     so it comes back where it was. -->
+		     Visibility is a flag ON the definition (`hidden`), so a hidden
+		     column stays declared, keeps its slot in the order, and comes back
+		     where it was. -->
 		<ul
 			aria-label="Columns"
 			class="flex flex-wrap gap-2 text-xs text-[color:var(--bb-text-muted)]"
@@ -27824,7 +27828,7 @@ The model's contract is what makes a column panel trivial:
 				<BbCheckbox
 					:label="column.label"
 					:model-value="!hidden.has(column.key)"
-					@update:model-value="toggleVisible(column.key)"
+					@update:model-value="setHidden(column.key, !$event)"
 				/>
 				<BbButton
 					:aria-label="`Move ${column.label} left`"
@@ -27850,15 +27854,30 @@ The model's contract is what makes a column panel trivial:
 			<BbTable
 				v-model:order="order"
 				caption="Invoices"
-				:columns="visibleColumns"
+				:columns="columns"
 				compact
 				item-value="id"
 				:items="invoices"
 				reorderable
-			/>
+				@hide:column="(key) => setHidden(key, true)"
+			>
+				<!-- A "hide" control beside every header: the slot's `hideColumn()` is
+				     one-way (a hidden column has no header), so the panel above
+				     is what brings a column back. -->
+				<template #header:append="{ hideColumn, label }">
+					<BbButton
+						:aria-label="`Hide ${label}`"
+						icon="lucide:eye-off"
+						size="xs"
+						variant="ghost"
+						@click="hideColumn"
+					/>
+				</template>
+			</BbTable>
 		</div>
 		<p class="text-xs text-[color:var(--bb-text-muted)]">
-			Order model: <code>{{ JSON.stringify(order) }}</code>
+			Order model: <code>{{ JSON.stringify(order) }}</code> · hidden:
+			<code>{{ JSON.stringify([...hidden]) }}</code>
 		</p>
 	</div>
 </template>
@@ -27880,8 +27899,8 @@ const euro = new Intl.NumberFormat('en-IE', {
 	currency: 'EUR',
 });
 
-// The declaration: what a column IS. Never reordered.
-const columns: Array<BbTableColumn<Invoice>> = [
+// The declaration: what a column IS. Never reordered, never filtered.
+const definitions: Array<BbTableColumn<Invoice>> = [
 	{ key: 'number', label: 'Invoice', width: 110 },
 	{ key: 'client', label: 'Client' },
 	{ key: 'issued', label: 'Issued', width: 110 },
@@ -27925,33 +27944,41 @@ const invoices: Invoice[] = [
 	},
 ];
 
-// The state: render order (keys). Persist THIS. Seed it with the full key
-// list — it also completes itself on the first move.
-const order = ref<string[]>(columns.map((column) => column.key));
+// The state, both persistable as-is: render order (keys) and the hidden set.
+// A partial or empty order is fine — the first move writes back the
+// complete array, hidden keys in their slots, because every column stays
+// declared below.
+const order = ref<string[]>([]);
 const hidden = ref(new Set<string>());
 
-// Visibility is just filtering the declaration; the hidden key keeps its
-// slot in `order`.
-const visibleColumns = computed(() =>
-	columns.filter((column) => !hidden.value.has(column.key))
+// The definitions, with the persisted visibility mapped in. Same shape you
+// would use for persisted widths (`width`) — the definition is the truth.
+const columns = computed(() =>
+	definitions.map((column) => ({
+		...column,
+		hidden: hidden.value.has(column.key),
+	}))
 );
 
-// The panel lists every declared column in the order the model has them.
-const panelColumns = computed(() =>
-	[...columns].sort(
-		(a, b) => order.value.indexOf(a.key) - order.value.indexOf(b.key)
-	)
-);
+// The panel lists every declared column in the order the model has them
+// (omitted keys follow in declaration order, exactly as the table renders).
+const panelColumns = computed(() => {
+	const rank = (key: string) => {
+		const index = order.value.indexOf(key);
+		return index < 0 ? order.value.length : index;
+	};
+	return [...definitions].sort((a, b) => rank(a.key) - rank(b.key));
+});
 
-const toggleVisible = (key: string) => {
+const setHidden = (key: string, value: boolean) => {
 	const next = new Set(hidden.value);
-	if (next.has(key)) next.delete(key);
-	else next.add(key);
+	if (value) next.add(key);
+	else next.delete(key);
 	hidden.value = next;
 };
 
 const move = (key: string, delta: 1 | -1) => {
-	const next = [...order.value];
+	const next = panelColumns.value.map((column) => column.key);
 	const from = next.indexOf(key);
 	const to = from + delta;
 	if (from < 0 || to < 0 || to >= next.length) return;
@@ -27962,22 +27989,50 @@ const move = (key: string, delta: 1 | -1) => {
 </script>
 ```
 
-**Pinned slots are positions, not columns.** `fixed-columns` indexes rendered
-slots like a spreadsheet's freeze panes (a selection column is slot 0). With
-column order the slot holds: whichever column lands in it is pinned, and
-dragging the identity column out of its pinned slot (slot 1 when
-`selectable`, slot 0 otherwise) unpins it (AG Grid pins columns; BbTable
-pins positions). Keep the reorder + pin combination for slots that
-never move — `select`, `actions`, or a first column you also lock by
-normalizing the model in your `@update:order` handler.
-
-**Nested tables.** An inheriting child aligns to the parent's rails by
-**position**, so a reordered parent re-pairs the child's columns unless the
-child follows. Give both tables the same `v-model:order` when they
-share keys (and the child declares no `snap`) and they stay paired by key.
-`snap` points are positional in the parent's rendered order: reorder the
-parent and a snap-mapped child follows its slots, but never reorder (or share
-the order with) the snap-mapped child itself — dev builds warn.
+### Column visibility
+
+`hidden: true` on a column definition hides it: no header, no cells, no grid
+track. The column stays **declared**, and that is the whole point — the order
+model is completed against every declared key, so a hidden column keeps its
+slot through any number of header drags, and it returns to that slot the
+moment the flag clears. Two rules follow:
+
+- **Hidden means "exists, not shown".** A column panel, a persisted
+  preference, a narrow-screen breakpoint all write `hidden` into the
+  definition (a `computed` over your persisted set — the example above does
+  exactly that). Filter `columns` only for a column that does **not exist**
+  for this user (a custom field they don't have); its key, if a saved order
+  still lists it, is preserved in place like any unknown key.
+- **There is no visibility model, on purpose** — the `width` shape, not the
+  `sort` one. The definition is the single declared truth. Header slots
+  (`#header:<key>`, `#header:<key>:append`, the table-wide `#header:append`)
+  receive a `hideColumn()` callback for a "Hide column" control of your own; calling
+  it hides the column for the mount and fires `@hide:column="(key) => …"`
+  once. Persist by writing `hidden: true` back into the definition — the
+  override matches it and stays; write `hidden: false` (the panel showing the
+  column again) and the definition wins. Unbound, the hide lives for the
+  mount, like an unbound resize. A hidden column has no header, so `hideColumn()`
+  is one-way by nature: if you offer it, own the persistence and give the
+  user a panel that shows columns again.
+
+A nested table that shares its parent's keys shares its `hidden` flags too,
+the same way it shares `order` — a hidden parent column has no track for a
+child cell to land on.
+
+**Pins travel with the column.** `fixed` is a field on the column
+definition (see "Pinned columns"), so a reorder moves the pin with the cell:
+drag the identity column to slot 3 and it is still sticky, now at slot 3.
+The offset is still positional — the pinned columns before it on the same
+side — so a pinned column dragged away from the edge sticks at `left: 0` and
+slides over the columns before it. Lock the pinned columns in place by
+normalizing the model in your `@update:order` handler when that matters.
+
+**Nested tables.** A parent that uses `order` or `reorderable` is inherited
+by **position**: its columns can move, so the child's `snap` targets and
+same-key pairing are ignored there (dev builds warn) and the child aligns to
+the parent's rails slot by slot. Give both tables the same `v-model:order`
+when they share keys and they stay paired. Never reorder (or share the order
+with) a snapped child itself — dev builds warn.
 
 Apply the model synchronously in your handler and persist afterwards: an
 `await` before the write moves the cell in a later flush, after the table
@@ -28349,7 +28404,7 @@ fields.
 Track open rows with `v-model:expanded-items` (an array of row values — set
 `item-value` so expansion is stable across refetches) and render their detail
 through the `#expand` slot, a full-width row below the main one. Trigger it
-from the `#actions` slot (enable the column with `actions`, label it with
+from the `#actions` slot (the slot creates the actions column; label it with
 `actions-text`): the scope hands you `toggleExpanded` — a **callback** — plus
 the read-only `expanded` flag. Drive open/close through the callback; the
 `expanded` prop is one-way state, not something to mutate.
@@ -28366,7 +28421,6 @@ the read-only `expanded` flag. Drive open/close through the callback; the
 	>
 		<BbTable
 			v-model:expanded-items="expanded"
-			actions
 			actions-text="Details"
 			caption="Invoices"
 			:columns="columns"
@@ -28590,11 +28644,19 @@ above it. The mechanics:
 - `inherit-column-widths` — `true` inherits from the nearest ancestor table;
   a string targets a specific ancestor's `id` (useful when an intermediate
   table has a different column count).
-- By default child columns map one-to-one onto the parent's data columns. A
-  column's `snap` remaps it: a number is a start track (`2` occupies the
-  parent's third data region), `[start, end]` spans a range (fractions
-  allowed; `end: -1` runs to the end of the data region). Structural columns
-  (`select`, actions) are accounted for automatically.
+- By default a child column pairs with the parent column of the **same key**,
+  and a column the parent lacks flows into the next parent track no other
+  column claimed. A column's `snap` names the parent column instead:
+  `snap: 'client'` takes that track, `['client', 'amount']` spans from the
+  start of one through the end of the other, and the parent's structural
+  columns are targets by name (`'select'`, `'actions'` — `['name',
+'actions']` runs a column across the parent's actions cell too). A
+  trailing `.digits` on a key in a pair is a fraction of that track
+  (`['a', 'b.5']` = all of `a` plus half of `b`). Snaps and keys resolve
+  against the parent's **rendered** columns: a target the parent hides (or
+  never had) makes the column flow like an unsnapped one; a snap that lands
+  before the previous column's cannot tile and flows too (dev builds warn);
+  under a parent that reorders, snaps are ignored (see Column order).
 - A child with **more** columns than the parent content-sizes the extras and
   overflows into the parent's scroll (see below); with **fewer**, the leading
   columns stay 1:1, the actions column inherits the parent's actions width,
@@ -28602,15 +28664,16 @@ above it. The mechanics:
   both tables end flush (a right-aligned total lands under the parent's last
   column). Give that last column a `width` or an explicit `[start, end]`
   snap only if you want it to stop short — the leftover then joins the
-  actions region instead.
+  actions region instead. A column with nothing free left to flow into is an
+  overflow column too.
 - **An inheriting child does not scroll on its own — the parent's scrollport
   is the only one.** That is what keeps the two grids locked together: a child
   with its own scroll position would fall out of alignment the moment either
   one moved, which is the whole thing `inherit-column-widths` exists to
   prevent. One scrollbar moves both.
 - **The parent's `selectable`/`actions` columns are handled for you** — the
-  child's content columns map to the parent's content columns 1:1 (no `snap`
-  needed for that), and the parent's select/actions _regions_ are reserved on
+  child's content columns pair with the parent's content columns by key (no
+  `snap` needed for that), and the parent's select/actions _regions_ are reserved on
   each side: a child with its own select or actions column widens that cell
   to the parent's (two equal cells, controls at the row's end, so the ⌃ sits
   under the parent's); a child without one folds the region into its first/
@@ -28642,7 +28705,6 @@ above it. The mechanics:
 	>
 		<BbTable
 			v-model:expanded-items="expanded"
-			actions
 			actions-text="Line items"
 			caption="Invoices"
 			:columns="columns"
@@ -28740,27 +28802,29 @@ const expanded = ref<string[]>([]);
 
 #### Affixed actions on both tables
 
-A nested table can carry its own `fixed-columns` — child rows usually need
-their own row actions — and both action columns pin to the same visible edge:
+A nested table can pin its own actions column with `fixed-actions` — child
+rows usually need their own row actions — and both action columns pin to the
+same visible edge:
 
 ```vue
 <BbTable
 	id="programmes"
-	actions
 	:columns="columns"
-	:fixed-columns="[{ index: columns.length, position: 'right' }]"
+	fixed-actions
 	:items="rows"
 	item-value="id"
 >
+	<template #actions="{ item }">…</template>
 	<template #expand="{ item }">
 		<BbTable
-			actions
 			:columns="childColumns"
-			:fixed-columns="[{ index: childColumns.length, position: 'right' }]"
+			fixed-actions
 			inherit-column-widths="programmes"
 			:items="item.children"
 			item-value="id"
-		/>
+		>
+			<template #actions="{ item }">…</template>
+		</BbTable>
 	</template>
 </BbTable>
 ```
@@ -28769,9 +28833,10 @@ This works because the child shares the parent's scrollport. `position: sticky`
 resolves against the nearest scrolling ancestor, and the child's own box is as
 wide as the parent's **content** — so if it opened a scrollport of its own, the
 child's actions would affix to an edge sitting out in the overflow, hundreds of
-pixels past what anyone can see, while the parent's pinned correctly. Snap the
-child's actions column onto the parent's actions track (see the snapping rule
-above) so the two columns line up rather than merely both being pinned.
+pixels past what anyone can see, while the parent's pinned correctly. The
+child's actions column inherits the parent's actions region by itself (the
+structural rule above), so the two columns line up rather than merely both
+being pinned.
 
 A pinned cell is opaque — it paints the table's `--bg` surface because it
 slides over its siblings — so a nested table sitting on a tinted expand row
@@ -29059,7 +29124,6 @@ open-in-new-tab for free.
 		class="max-w-2xl overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
 	>
 		<BbTable
-			actions
 			actions-text="Actions"
 			caption="Invoices"
 			:columns="columns"
@@ -29395,10 +29459,8 @@ canonical palette lives in the
 
 `compact` tightens row padding. `fixed-headers` makes the header stick to the
 top of the nearest scroll container. `fixed` switches to an equal-width fixed
-layout. `fixed-columns` pins columns while the rest scroll horizontally: an
-array of column indices (left-pinned) or `{ index, position: 'left'|'right' }`
-objects; indices count rendered columns (a selection column is index 0), and
-an out-of-range index logs a console error and is skipped. When content can't
+layout. Pinned columns (next section) stick while the rest scroll
+horizontally. When content can't
 fit, the table keeps every column at its measured minimum — its header label
 included — and overflows its container instead of clipping; this is by
 design, not a bug to work around. Note that truncating cells yourself
@@ -29449,13 +29511,51 @@ your wrapper actually sits on before sprinkling `min-width: 0` everywhere.)
 </div>
 ```
 
+### Pinned columns
+
+`fixed: 'left' | 'right'` on a column definition makes its cells
+`position: sticky` on that side — in place, at the column's own render
+position, like a spreadsheet's freeze panes. Pin a contiguous run from the
+edge and the offsets accumulate (the second left-pinned column sticks right
+after the first). The two structural columns have no definition to carry the
+field, so they pin through the table: `fixed-select` for the selection
+column and `fixed-actions` for the actions column (each has one sensible
+side, so both are booleans).
+
+```vue
+<BbTable :columns="columns" fixed-actions fixed-select :items="rows" selectable>
+	<template #actions="{ item }">…</template>
+</BbTable>
+```
+
+```ts
+const columns = [
+	{ key: 'name', label: 'Name', fixed: 'left' },
+	{ key: 'region', label: 'Region' },
+	{ key: 'amount', label: 'Amount', align: 'right' },
+];
+```
+
+Three rules:
+
+- **The pin is the column's.** Under `order` / `reorderable` it travels with
+  the cell, and a `hidden` pinned column pins nothing. The offset is still
+  positional, so a lone left-pinned column dragged to the middle sticks at
+  `left: 0` and slides over the columns before it — by design; lock the
+  pinned columns in place by normalizing `@update:order` if you need to.
+- **Pinned cells are opaque** — they paint the table's `--bg` (see Styling
+  hooks), so a table on a tinted surface needs `--bg` set once.
+- **Nested tables pin against the ancestor scrollport.** A child that
+  inherits the parent's tracks has no scrollport of its own, so both tables'
+  pins land on the same visible edge (see Nested tables).
+
 ### Virtual rows
 
 `virtual` windows the body: only the rows in the vertical scrollport (plus a
 few on each side) are mounted, and two spacer rows hold the scrollport at the
 full list height, so 5,000 or 50,000 rows scroll at the cost of a few dozen.
 Everything else is the same table — the rows stay in flow in the grid, so the
-stuck header, `fixed-columns`, nested tables, selection, highlight and the
+stuck header, pinned columns, nested tables, selection, highlight and the
 keyboard grammar work untouched. One prop, no knobs.
 
 - **Give it a scroller.** Bound the table's height (`max-height` / `height`
@@ -29513,7 +29613,6 @@ keyboard grammar work untouched. One prop, no knobs.
 			class="max-h-80"
 			:columns="columns"
 			compact
-			:fixed-columns="[0]"
 			item-value="id"
 			:items="rows"
 			virtual
@@ -29533,7 +29632,7 @@ type Entry = {
 };
 
 const columns: Array<BbTableColumn<Entry>> = [
-	{ key: 'number', label: 'Invoice' },
+	{ key: 'number', label: 'Invoice', fixed: 'left' },
 	{ key: 'client', label: 'Client' },
 	{ key: 'issued', label: 'Issued' },
 	{ key: 'amount', label: 'Amount', align: 'right' },
@@ -29558,14 +29657,14 @@ leave the screen. Collapse instead of scroll:
 
 - **Rank the columns.** Identity + status + the one number that matters stay;
   everything else is secondary.
-- **Drop the secondary ones from `columns` at the breakpoint** — a `computed`
-  over `useMobile()` (or your own `matchMedia`) that filters the secondary keys
-  out. Removing the column removes its grid track. Do **not** hide cells with
-  `thClass`/`tdClass` + `display: none`: the table is a grid, a hidden cell
-  leaves its track in place and every following cell shifts one track over.
-  A dropped key keeps its slot in `order` (the write-back never drops
-  unknown keys), so the column returns where it was — never filter the
-  order array.
+- **Flag the secondary ones `hidden` at the breakpoint** — a `computed`
+  over `useMobile()` (or your own `matchMedia`) that maps the definitions
+  with `hidden: isMobile && secondary.has(key)`. A hidden column has no grid
+  track. Do **not** hide cells with `thClass`/`tdClass` + `display: none`:
+  the table is a grid, a hidden cell leaves its track in place and every
+  following cell shifts one track over. The hidden column stays declared, so
+  it keeps its slot in `order` and returns where it was when the screen
+  widens — never filter the order array.
 - **Stack what survives into the primary cell.** The identity slot renders the
   name plus the hidden facts under it, at `--bb-text-muted`, so nothing is
   actually lost.
@@ -29579,7 +29678,7 @@ records list.
 **The table's surface is `--bg`** (default `var(--bb-panel)`), a local on
 `.bb-table`. Cells are transparent at rest so the row can tint them, but
 anything that slides over scrolled content — the stuck header band with
-`fixed-headers`, and `fixed-columns` cells — is opaque and paints `--bg` (a
+`fixed-headers`, and pinned (`fixed`) cells — is opaque and paints `--bg` (a
 pinned cell also picks up its row's hover/highlight tint, so it never reads
 as a hole). When a table sits on a surface that is not the panel colour, set
 the one knob and everything pinned follows:
@@ -29726,8 +29825,9 @@ reader.
 - `BbPagination` — shared page ref, or zero-wiring via `id` + `table-id`.
 - `useBbTableContext` (`./composables/useBbTableContext.md`) — bulk-action
   toolbars, detail panels, "reset sort" buttons living outside the table.
-  (Column order is not mirrored there: a column panel needs `columns` too,
-  so it lives where `v-model:order` is bound.)
+  (Column order and visibility are not mirrored there: a column panel writes
+  `v-model:order` and the `hidden` flags, so it lives where `columns` is
+  built.)
 - `BbButton` — per-row links (`href`/`to`) in cells or `#actions`;
   `BbDropdown` for an overflow menu of row actions.
 - `BbBadge` / `BbAvatar` — status and identity cells via slots.
@@ -29753,10 +29853,17 @@ reader.
   `(columns, item)` with the mapped cells (in **render** order — look them up
   by `key`, never by position) and the raw record, and whatever it returns
   becomes the checkbox's label.
-- `fixed-columns` pins **slots**, not columns: under `order` the
-  column that lands in a pinned slot is the pinned one (see Column order).
+- A pin (`column.fixed`) travels with its column under `order`, but its
+  offset is positional: dragged away from the edge, a pinned column sticks
+  at `left: 0` and slides over the columns before it (see Pinned columns).
+- The actions column has no prop: the `#actions` slot creates it. A
+  conditional slot (`<template v-if="…" #actions>`) adds and removes the
+  column live.
 - A column panel that holds a partial `order` receives the completed
-  array on the user's first move — its persisted list grows to every key.
+  array on the user's first move — its persisted list grows to every declared
+  key, `hidden` ones included. Hide with the flag, not by filtering
+  `columns`: a filtered column is undeclared, so a partial model completes
+  without it and the key is gone from the persisted order.
 - Enabling select-all does not re-emit an empty `modelValue` (see the
   select-all section) — in all-mode, read `select-all` +
   `unselected-items`, not `modelValue`.
@@ -29834,7 +29941,6 @@ reader.
 | 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. The cells arrive in RENDER order (they follow `order`, so the label reads like the row) — look a cell up by `key`… |
-| `actions` | `boolean \| undefined` | `false` |  | Displays the actions column. |
 | `actionsText` | `string \| undefined` |  |  | Label used in the header of the actions column. |
 | `align` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Text alignment of the columns. |
 | `caption` | `string \| undefined` |  |  | Caption that describes the content of the table. Used for accessibility purposes. |
@@ -29848,8 +29954,9 @@ reader.
 | `enforceCoherence` | `boolean \| undefined` | `false` |  | After every load (initial, `dependencies` refetch or a change of the `items` array) prunes the row-keyed models of values whose row is no longer in the result set: `modelValue`, `unselected-items`, `highlighted` and `expanded-items`. Values… |
 | `expandedItems` | `any[] \| undefined` | `[]` |  | Used by `v-model:expandedItems`. Array of the currently expanded items — toggled by the row expand control and by external writes (mirrors the `highlighted`/`sort` v-model surfaces). Drives the `#expand` slot rows and their `aria-expanded`/… |
 | `fixed` | `boolean \| undefined` | `false` |  | Splits the width equally among the columns that declare no `width` (each undeclared column becomes a `minmax(0, 1fr)` track) making each column take up the same amount of space. |
-| `fixedColumns` | `(number \| { index: number; position: "left" \| "right"; })[] \| undefined` | `[]` |  | Definition for which column should be fixed. It can be an array of index of the column to fix on the left side of the table or an array of objects indicating the index and the position `left` or `right` where to affix the columns. Indices a… |
+| `fixedActions` | `boolean \| undefined` | `false` |  | Pins the actions column (the one the `#actions` slot creates) to the right edge, `position: sticky`, in place. Data columns pin through `column.fixed`; this is the same feature for the structural column that has no definition to carry it. N… |
 | `fixedHeaders` | `boolean \| undefined` | `false` |  | Boolean that sets the headers as sticky to the top of the table. |
+| `fixedSelect` | `boolean \| undefined` | `false` |  | Pins the selection column to the left edge, `position: sticky`, in place. Data columns pin through `column.fixed`; this is the same feature for the structural column that has no definition to carry it. No effect unless the table is `selecta… |
 | `headerRowClass` | `Classes \| undefined` |  |  | Defines the classes to be passed to the header row. |
 | `highlighted` | `any` | `undefined` |  | Used by `v-model:highlighted`. A parallel, UI-intent state to selection — typically "the row whose details are open". A single item value (or `null`) — highlight is single by design. **Opt-in, and `undefined` is the opt-out.** Leave it unbo… |
 | `id` | `string \| undefined` |  |  | Stable id for this table's width context. When omitted a unique id is generated. Nested tables use the nearest ancestor id to inherit widths. |
@@ -29890,6 +29997,7 @@ reader.
 - `click:row` — `(e: "click:row", event: MouseEvent, item: any): void`
 - `contextmenu:row` — `(e: "contextmenu:row", event: MouseEvent, item: any): void`
 - `dblclick:row` — `(e: "dblclick:row", event: MouseEvent, item: any): void`
+- `hide:column` — `(e: "hide:column", key: string): void` — A column was hidden from its header (a `#header:<key>` / `#header:<key>:append` control calling the slot's `hideColumn()`). Fired once; the table keeps the column hidden for the mount, or until the column's `hidden` flag changes — write `hi…
 - `item:selected` — `(e: "item:selected", value: any): void`
 - `item:unselected` — `(e: "item:unselected", value: any): void`
 - `resize:column` — `(e: "resize:column", key: string, width: number \| null): void` — A column was resized by the user (`resizable`): the new width in px, or `null` when the handle was double-clicked to reset the column to its declared width.
@@ -29903,7 +30011,7 @@ reader.
 
 ## Slots
 
-- `actions` — scope: `{ expanded?: boolean \| undefined; expandProps?: ExpandControllerProps \| undefined; toggleExpanded?: (() => void) \| undefined; highlighted?: boolean \| undefi…` — Content rendered in the actions cell for each row.
+- `actions` — scope: `{ expanded?: boolean \| undefined; expandProps?: ExpandControllerProps \| undefined; toggleExpanded?: (() => void) \| undefined; highlighted?: boolean \| undefi…` — Content rendered in the actions cell for each row. Providing this slot is what CREATES the actions column (there is no prop): the header cell (labelled by `actions-text`, replaceable through `#header:actions`) and one cell per row appear wi…
 - `expand` — scope: `{ expanded: boolean; expandProps?: ExpandControllerProps \| undefined; toggleExpanded: () => void; highlighted?: boolean \| undefined; toggleHighlighted?: (() =…` — Full-width expandable content row rendered below each main row when expanded.
 - `header:actions` — scope: `{ text: string; }` — Replaces the default actions header cell content.
 - `header:append` — scope: `BbTableHeaderAffixSlotProps<Item>` — Content rendered after every data column's header cell content — the label + sort control, or the column's own `header:<key>` replacement. A column's `header:<key>:append` slot wins over this one for that column; they never stack. Branch on…
@@ -39250,24 +39358,24 @@ a composable you want is not in this corpus's `composables/` folder — it is no
 here.** Check this list before inventing a name; if the need is genuinely absent,
 compose it or write it yourself.
 
-| Assumed component or composable                                | Reality                                                                                                                                                                                                                                                                                                                                   |
-| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `BbColumnManager` — show/hide/reorder columns                  | Does not exist as a component. Order is `v-model:order` on `BbTable` (an array of keys any panel can write; `reorderable` adds the built-in header drag + keyboard handle); visibility is still filtering `columns` — the hidden key keeps its slot in the order. Compose the panel from `BbPopover` + `BbCheckbox`.                      |
-| `BbKanban` / drag-and-drop board                               | Does not exist. There is no reusable DnD primitive in the library (`BbTable`'s header drag is internal to the table) — compose the board from `BbTable` (a table/list view of the same data) or hand-roll the drag-and-drop interaction yourself.                                                                                         |
-| `BbModal`                                                      | It is [BbDialog](../BbDialog.md).                                                                                                                                                                                                                                                                                                         |
-| `BbDrawer` / `BbSheet`                                         | It is [BbOffCanvas](../BbOffCanvas.md).                                                                                                                                                                                                                                                                                                   |
-| `BbCombobox` / `BbAutocomplete`                                | It is [BbSelect](../BbSelect.md) / [BbSelectPopover](../BbSelectPopover.md) — search is built in, see `disable-writing`.                                                                                                                                                                                                                  |
-| `BbToggle` / `BbToggleGroup`                                   | It is [BbButton](../BbButton.md) with `v-model` (+ `true-value` / `false-value`), which owns `aria-pressed` and the active class.                                                                                                                                                                                                         |
-| `TagChip` / colored, read-only tag chip                        | It is [BbBadge](../BbBadge.md) — [BbTag](../BbTag.md) is a tags-_input_ only, not a display component. Use `BbBadge` with a registered `soft-*` variant for a fixed palette, or a one-off `--bg`/`--color` override per row for arbitrary/data-driven colors (BbBadge.md § One-off colors) — not a registered variant per distinct color. |
-| `BbTab` (singular)                                             | The consumer API is [BbTabs](../BbTabs.md) / `BbTabsRoot`. `BbTab` appears only as the **v2 "before" side** of the migration diffs.                                                                                                                                                                                                       |
-| `BbCard`                                                       | Does not exist — a card is a `<div>` with tokens. See [design-language](./design-language.md).                                                                                                                                                                                                                                            |
-| `BbList` / `BbListItem` / `BbDescriptionList`                  | Do not exist — a list row is an `<li>` with tokens, and [BbBaseButton](../BbBaseButton.md) makes the whole row navigable. See the note under Data Display.                                                                                                                                                                                |
-| `useLiveFeed` / any polling or cross-tab feed helper           | Does not exist, and neither does a cross-tab helper — `useBroadcastChannelInstance` was removed (cross-tab messaging is not a UI concern). Use `useBroadcastChannel` from `@vueuse/core`; the polling and the merge are yours.                                                                                                            |
-| `BbStepper` / `BbWizard`                                       | Does not exist as a component; the wizard-form recipe composes one.                                                                                                                                                                                                                                                                       |
-| `BbSkeleton` (standalone)                                      | Only `BbTable` ships skeletons, via the column `skeleton` field.                                                                                                                                                                                                                                                                          |
-| `BbCommand` / command palette                                  | Does not exist. Compose `BbDialog` + `BbSelectPopover`.                                                                                                                                                                                                                                                                                   |
-| `BbCalendar` (month / scheduling view)                         | Does not exist. [BbDatePicker](../BbDatePicker.md) is a picker, not a calendar surface.                                                                                                                                                                                                                                                   |
-| `BbChart` / `BbGraph`, `BbCarousel`, `BbTimeline`, `BbDivider` | Do not exist. No charting, carousel or timeline primitive ships here.                                                                                                                                                                                                                                                                     |
+| Assumed component or composable                                | Reality                                                                                                                                                                                                                                                                                                                                                                                                       |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BbColumnManager` — show/hide/reorder columns                  | Does not exist as a component. Order is `v-model:order` on `BbTable` (an array of keys any panel can write; `reorderable` adds the built-in header drag + keyboard handle); visibility is `hidden: true` on the column definition (the column stays declared and keeps its slot in the order; header slots get a `hideColumn()` that fires `hide:column`). Compose the panel from `BbPopover` + `BbCheckbox`. |
+| `BbKanban` / drag-and-drop board                               | Does not exist. There is no reusable DnD primitive in the library (`BbTable`'s header drag is internal to the table) — compose the board from `BbTable` (a table/list view of the same data) or hand-roll the drag-and-drop interaction yourself.                                                                                                                                                             |
+| `BbModal`                                                      | It is [BbDialog](../BbDialog.md).                                                                                                                                                                                                                                                                                                                                                                             |
+| `BbDrawer` / `BbSheet`                                         | It is [BbOffCanvas](../BbOffCanvas.md).                                                                                                                                                                                                                                                                                                                                                                       |
+| `BbCombobox` / `BbAutocomplete`                                | It is [BbSelect](../BbSelect.md) / [BbSelectPopover](../BbSelectPopover.md) — search is built in, see `disable-writing`.                                                                                                                                                                                                                                                                                      |
+| `BbToggle` / `BbToggleGroup`                                   | It is [BbButton](../BbButton.md) with `v-model` (+ `true-value` / `false-value`), which owns `aria-pressed` and the active class.                                                                                                                                                                                                                                                                             |
+| `TagChip` / colored, read-only tag chip                        | It is [BbBadge](../BbBadge.md) — [BbTag](../BbTag.md) is a tags-_input_ only, not a display component. Use `BbBadge` with a registered `soft-*` variant for a fixed palette, or a one-off `--bg`/`--color` override per row for arbitrary/data-driven colors (BbBadge.md § One-off colors) — not a registered variant per distinct color.                                                                     |
+| `BbTab` (singular)                                             | The consumer API is [BbTabs](../BbTabs.md) / `BbTabsRoot`. `BbTab` appears only as the **v2 "before" side** of the migration diffs.                                                                                                                                                                                                                                                                           |
+| `BbCard`                                                       | Does not exist — a card is a `<div>` with tokens. See [design-language](./design-language.md).                                                                                                                                                                                                                                                                                                                |
+| `BbList` / `BbListItem` / `BbDescriptionList`                  | Do not exist — a list row is an `<li>` with tokens, and [BbBaseButton](../BbBaseButton.md) makes the whole row navigable. See the note under Data Display.                                                                                                                                                                                                                                                    |
+| `useLiveFeed` / any polling or cross-tab feed helper           | Does not exist, and neither does a cross-tab helper — `useBroadcastChannelInstance` was removed (cross-tab messaging is not a UI concern). Use `useBroadcastChannel` from `@vueuse/core`; the polling and the merge are yours.                                                                                                                                                                                |
+| `BbStepper` / `BbWizard`                                       | Does not exist as a component; the wizard-form recipe composes one.                                                                                                                                                                                                                                                                                                                                           |
+| `BbSkeleton` (standalone)                                      | Only `BbTable` ships skeletons, via the column `skeleton` field.                                                                                                                                                                                                                                                                                                                                              |
+| `BbCommand` / command palette                                  | Does not exist. Compose `BbDialog` + `BbSelectPopover`.                                                                                                                                                                                                                                                                                                                                                       |
+| `BbCalendar` (month / scheduling view)                         | Does not exist. [BbDatePicker](../BbDatePicker.md) is a picker, not a calendar surface.                                                                                                                                                                                                                                                                                                                       |
+| `BbChart` / `BbGraph`, `BbCarousel`, `BbTimeline`, `BbDivider` | Do not exist. No charting, carousel or timeline primitive ships here.                                                                                                                                                                                                                                                                                                                                         |
 
 App chrome — an app shell, sidebar, page header, selection dock — is
 deliberately **not** a component: it is yours to own. The per-platform
@@ -40885,9 +40993,13 @@ The `bitbossUi` Vite plugin (`iconDir` option) — or the Nuxt module (config ke
   `lucide:<name>` available; removing it makes them all errors. Nothing to
   configure.
 - **Dev**: all icons of installed sets are registered. Referencing an
-  uninstalled prefix or a non-existent name fails loudly with an actionable
-  message (`"lucide:fo" requires "@iconify-json/lucide" — run: npm install -D …`
-  or `icon "x" does not exist in the lucide icon set`).
+  uninstalled prefix or a non-existent name fails loudly in the Vite error
+  overlay with an actionable message. A typo inside an installed set reads
+  "does not exist in the lucide icon set — did you mean `lucide:…`?"; a set
+  that is not installed reads "no installed icon set has the prefix `mdi`
+  (installed sets: lucide) … run: `npm install -D @iconify-json/mdi`". Read
+  the message: a typo wants a different name, a missing set wants an install,
+  never a guess.
 - **Build**: source files (`.vue`/`.ts`/`.js`/`.tsx`/`.jsx`; tests and stories
   excluded) are scanned for static `provider:name` literals; each referenced
   icon is emitted as its own lazy chunk. This is why rule 4 exists — and why an
@@ -43102,19 +43214,16 @@ goes stable, so never reach for it here.
 
 Peer dependency: `vue ^3.5.12` — the only required one. `@inertiajs/vue3` is an **optional** peer, needed only in Inertia apps.
 
-`@iconify/collections` is an **optional** peer too, and npm never installs
-optional peers automatically — install it yourself if you want the dev-time
-provider-icon diagnostics:
-
-```bash
-npm install -D @iconify/collections
-```
-
-Without it the plugin has no list of valid Iconify prefixes, so the dev-overlay
-errors below (the "install `@iconify-json/<prefix>`" hint and the "did you
-mean …?" suggestion for a mistyped icon name) never fire — a wrong provider
-icon then surfaces only as `BbIcon`'s generic runtime `Icon "…" does not exist.`
-Nothing else changes: icons that resolve still render, in dev and in production.
+You do **not** need `@iconify/collections`. It is declared as an optional peer
+for one reason only: when it happens to be installed, the dev-overlay message
+for an unknown icon prefix can say for certain whether that prefix is a real
+Iconify set ("requires `@iconify-json/mdi`, run …") or not ("neither an
+installed set nor a known Iconify prefix"). Without it the same overlay fires
+with a hedged wording ("no installed icon set has the prefix `mdi`; if it is an
+Iconify set, run …"). A mistyped name inside a set you **have** installed
+(`lucide:eye-misspelled`) is diagnosed from the set's own data in both cases,
+with a "did you mean …?" suggestion. Nothing else changes: icons that resolve
+still render, in dev and in production.
 
 **Known-good toolchain:** TypeScript **5.x or 6.x** if your build gate runs
 `vue-tsc`. Both type-check cleanly against the shipped `.d.ts`; the library
@@ -43379,7 +43488,7 @@ utilities. (Same trap as the scoped-`<style>` case above, one level up.)
 ## 6) Icons
 
 - `iconDir` (required) is scanned recursively for `.svg` files; each file becomes `local:<basename>`.
-- Provider icons (`lucide:pencil`, `mdi:home`, …) require the matching `@iconify-json/<prefix>` package installed in the consumer app. Missing packages/icons produce actionable dev-overlay errors **only when the optional `@iconify/collections` peer is installed** (see [Install](#1-install)); otherwise you get `BbIcon`'s generic runtime error instead. Production builds report neither — this is a dev-time aid.
+- Provider icons (`lucide:pencil`, `mdi:home`, …) require the matching `@iconify-json/<prefix>` package installed in the consumer app. In dev, every `prefix:name` the registry does not know produces a Vite error overlay with the fix: a mistyped name inside an installed set gets a "did you mean …?" hint, and an uninstalled prefix gets the list of installed sets plus the `npm install -D @iconify-json/<prefix>` command (the optional `@iconify/collections` peer only sharpens that wording, see [Install](#1-install)). A missing `local:` icon is a missing file in `iconDir` and surfaces as `BbIcon`'s runtime error naming it. Production builds report none of this — the scan simply drops what does not resolve, so a wrong name fails at runtime there.
 - Production builds bundle **only statically referenced** provider icons — write icon names as literal strings (`icon="lucide:trash-2"`), never assemble them dynamically.
 - The plugin also writes `node_modules/.bitboss-ui/local-icons.json` and (in dev, unless `vscodeSettings: false`) wires `.vscode/settings.json` so the Iconify editor extension previews local icons.
 
@@ -45658,20 +45767,24 @@ have made the spinner invisible and removed the page's only busy signal.
 
 ## Changes
 
-| v2                                                                                                                    | v3                                                                                                                                                                                                                                           | Kind                                                                                                    |
-| --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `allowSelectAll?: boolean` (default `true`)                                                                           | `disableSelectAll?: boolean` (default `false`)                                                                                                                                                                                               | rename, polarity inverted                                                                               |
-| refetch with rows → skeleton                                                                                          | refetch keeps rows visible (dimmed + progress bar)                                                                                                                                                                                           | **behavior** — the skeleton only shows when there is nothing to display                                 |
-| rows interactive while loading                                                                                        | header + rows go `inert` while loading                                                                                                                                                                                                       | **behavior** — opt out with `interactive-while-loading`                                                 |
-| `#loading` slot fired on every load                                                                                   | fires on the **first load only** (it replaces the skeleton, so it follows the skeleton's rule)                                                                                                                                               | **⚠ silent** for anyone styling refetches through it                                                    |
-| `#no-data` replaced the empty-state `<tr>`                                                                            | fills the table's own full-width cell (`aria-colspan` counted, centred)                                                                                                                                                                      | **behavior** — pass content, not a row                                                                  |
-| `<table>` / `<thead>` / `<tbody>` / `<tr>` / `<th>` / `<td>` markup _(v2 and v3 ≤ beta.5)_                            | a CSS grid of `<div>`s carrying `role="table\|rowgroup\|row\|columnheader\|cell"`; `.bb-table__table` / `__head` / `__body` / `__foot` are the new containers, every `.bb-table*` class survives                                             | **⚠ silent** for element selectors, `#thead`/`#tbody`/`#tfoot` markup, copy/paste and print — see below |
-| `--fill` / `--natural-width` published on `.bb-table` _(v3 ≤ beta.5)_                                                 | **removed** — nothing publishes them                                                                                                                                                                                                         | **⚠ silent** — see below                                                                                |
-| —                                                                                                                     | props `enforceCoherence` (prunes row-keyed models after each load; incompatible with pagination-via-`dependencies`), `expandedItems` + `#expand`, `sort`, `keyboardNavigation`, `highlighted`, `rowClass`, `order` (v-model) + `reorderable` | additive                                                                                                |
-| —                                                                                                                     | **column** fields `sortable?: boolean`, `rowClass?: ColumnClasses`                                                                                                                                                                           | additive, **collides** — see below                                                                      |
-| `useBbTableContext(id).total` _(v3 alphas ≤ 4)_                                                                       | `useBbTableContext(id).totalItems`                                                                                                                                                                                                           | **hard rename** on the composable handle — see below                                                    |
-| `@click:row` / `@contextmenu:row` / `@dblclick:row` handlers receive `(event, item, selected)` _(v2 and v3 ≤ beta.5)_ | `(event, item)` — `item` is now your raw record (was the internal row wrapper, record at `row.item`); the trailing `selected` boolean is gone                                                                                                | **payload slimmed** — see below                                                                         |
-| `--bb-table-*` custom properties                                                                                      | same names without the `bb-` prefix                                                                                                                                                                                                          | **⚠ silent** for nested-table layouts — see below                                                       |
+| v2                                                                                                                                                            | v3                                                                                                                                                                                                                                                                                                                                                      | Kind                                                                                                    |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `allowSelectAll?: boolean` (default `true`)                                                                                                                   | `disableSelectAll?: boolean` (default `false`)                                                                                                                                                                                                                                                                                                          | rename, polarity inverted                                                                               |
+| refetch with rows → skeleton                                                                                                                                  | refetch keeps rows visible (dimmed + progress bar)                                                                                                                                                                                                                                                                                                      | **behavior** — the skeleton only shows when there is nothing to display                                 |
+| rows interactive while loading                                                                                                                                | header + rows go `inert` while loading                                                                                                                                                                                                                                                                                                                  | **behavior** — opt out with `interactive-while-loading`                                                 |
+| `#loading` slot fired on every load                                                                                                                           | fires on the **first load only** (it replaces the skeleton, so it follows the skeleton's rule)                                                                                                                                                                                                                                                          | **⚠ silent** for anyone styling refetches through it                                                    |
+| `#no-data` replaced the empty-state `<tr>`                                                                                                                    | fills the table's own full-width cell (`aria-colspan` counted, centred)                                                                                                                                                                                                                                                                                 | **behavior** — pass content, not a row                                                                  |
+| `<table>` / `<thead>` / `<tbody>` / `<tr>` / `<th>` / `<td>` markup _(v2 and v3 ≤ beta.5)_                                                                    | a CSS grid of `<div>`s carrying `role="table\|rowgroup\|row\|columnheader\|cell"`; `.bb-table__table` / `__head` / `__body` / `__foot` are the new containers, every `.bb-table*` class survives                                                                                                                                                        | **⚠ silent** for element selectors, `#thead`/`#tbody`/`#tfoot` markup, copy/paste and print — see below |
+| `--fill` / `--natural-width` published on `.bb-table` _(v3 ≤ beta.5)_                                                                                         | **removed** — nothing publishes them                                                                                                                                                                                                                                                                                                                    | **⚠ silent** — see below                                                                                |
+| —                                                                                                                                                             | props `enforceCoherence` (prunes row-keyed models after each load; incompatible with pagination-via-`dependencies`), `expandedItems` + `#expand`, `sort`, `keyboardNavigation`, `highlighted`, `rowClass`, `order` (v-model) + `reorderable`, `resizable` + `resize:column`, header-slot `hideColumn()` + `hide:column`, `fixedSelect` / `fixedActions` | additive                                                                                                |
+| —                                                                                                                                                             | **column** fields `sortable?: boolean`, `rowClass?: ColumnClasses`, `hidden?: boolean` (the column stays declared — the way to hide, see § Do not override), `fixed?: 'left' \| 'right'` (replaces `fixedColumns`, see below)                                                                                                                           | additive, **collides** — see below                                                                      |
+| `actions?: boolean` prop _(v2 and v3 ≤ beta.20)_                                                                                                              | **removed** — the `#actions` slot creates the column by itself                                                                                                                                                                                                                                                                                          | **⚠ silent** if you passed the prop without the slot — see below                                        |
+| `fixedColumns` prop (rendered-slot indices, `[0, { index, position }]`) _(v2 and v3 ≤ beta.20)_                                                               | **removed** — `fixed: 'left' \| 'right'` on the column definition, `fixed-select` / `fixed-actions` for the structural columns                                                                                                                                                                                                                          | **⚠ silent** — see below                                                                                |
+| column `snap?: number \| [number, number]` — gridline indices into the parent's rendered columns (`select` at 0, fractions, `-1` = data end) _(v3 ≤ beta.20)_ | `snap?: string \| [string, string]` — the PARENT's column key, or `'select'` / `'actions'`; a pair is inclusive; `'amount.5'` is a fraction. Same-key columns pair by default. Ignored (dev warning) under a parent that uses `order` / `reorderable`                                                                                                   | **⚠ silent** — see below                                                                                |
+| `--table-{id}-track-{index}` published per data column _(v3 ≤ beta.20)_                                                                                       | `--table-{id}-track-{key}` — the column key in its slot-name spelling (`address_city`); `select` / `actions` unchanged                                                                                                                                                                                                                                  | **⚠ silent** for CSS that read the vars by index — see below                                            |
+| `useBbTableContext(id).total` _(v3 alphas ≤ 4)_                                                                                                               | `useBbTableContext(id).totalItems`                                                                                                                                                                                                                                                                                                                      | **hard rename** on the composable handle — see below                                                    |
+| `@click:row` / `@contextmenu:row` / `@dblclick:row` handlers receive `(event, item, selected)` _(v2 and v3 ≤ beta.5)_                                         | `(event, item)` — `item` is now your raw record (was the internal row wrapper, record at `row.item`); the trailing `selected` boolean is gone                                                                                                                                                                                                           | **payload slimmed** — see below                                                                         |
+| `--bb-table-*` custom properties                                                                                                                              | same names without the `bb-` prefix                                                                                                                                                                                                                                                                                                                     | **⚠ silent** for nested-table layouts — see below                                                       |
 
 ## Columns gained `sortable` and `rowClass` — check yours first
 
@@ -45778,6 +45891,113 @@ If you used `#loading` to show a custom refetch treatment, that role is gone —
 the built-in dim + progress bar covers refetches; `#loading` is now only the
 first-paint placeholder.
 
+### The `#actions` slot creates the actions column — the prop is gone (v3 beta, 2026-09-07)
+
+`actions` used to be a boolean prop that rendered the column, with the
+`#actions` slot filling it. The prop carried no information the slot did
+not, and it had a footgun: a consumer who declared `{ key: 'actions' }` in
+`columns` instead of setting the prop got a stray empty data cell and a slot
+that never rendered. Now the slot alone creates the column — header cell
+(labelled by `actions-text`, replaceable through `#header:actions`), one
+cell per row, and the `actions` track for nested tables — and removing the
+slot (or gating it with `v-if`) removes the column live.
+
+```diff
+- <BbTable actions :columns="columns" :items="rows">
++ <BbTable :columns="columns" :items="rows">
+    <template #actions="{ item }">…</template>
+  </BbTable>
+```
+
+Delete the attribute. The removed-prop warner flags it in dev, the ESLint rule
+flags it in-editor. The only silent case is a table that set `actions`
+without ever providing the slot: it had an empty column, and now it does not.
+
+### `fixedColumns` → `fixed` on the column, `fixed-select` / `fixed-actions` (v3 beta, 2026-09-07)
+
+Pins used to be **slot indices** into the rendered column list (a selection
+column was index 0), like spreadsheet freeze panes: with `order` and
+`reorderable` the pinned _slot_ held and whichever column landed in it was
+pinned, which is fragile once users drag headers and hide columns. Pins are
+now a property of the column, the way `width` and `hidden` are, and follow
+it through reorders. The sticky behaviour itself is unchanged: in place, at
+the column's own render position, offset by the pinned columns before it on
+the same side.
+
+```diff
+- <BbTable
+-   :columns="columns"
+-   :fixed-columns="[0, { index: columns.length + 1, position: 'right' }]"
+-   selectable
+- >
++ <BbTable :columns="columns" fixed-select fixed-actions selectable>
+    <template #actions="{ item }">…</template>
+  </BbTable>
+```
+
+```diff
+  const columns = [
+-   { key: 'name', label: 'Name' },
++   { key: 'name', label: 'Name', fixed: 'left' },
+    { key: 'amount', label: 'Amount', align: 'right' },
+  ];
+```
+
+Translate each index to the column that sat there: data columns get
+`fixed: 'left' | 'right'` on their definition, the selection column becomes
+`fixed-select`, the actions column `fixed-actions` (each has one sensible
+side, so they are booleans). A nested table that pinned its own actions with
+`{ index: childColumns.length, position: 'right' }` now says
+`fixed-actions`. Silent on upgrade: the old prop is ignored (the warner and
+the ESLint rule flag it), so a table that pinned columns stops pinning until
+you move the pins onto the definitions.
+
+### `snap` names the parent column, not a gridline (v3 beta, 2026-09-07)
+
+A nested table's `snap` was a number: a gridline index into the parent's
+rendered columns, with the selection column at `0`, fractions for partial
+tracks and `-1` for the end of the data region. Index `k` was whatever column
+happened to render there, so a reorder or a hidden column on the parent
+moved every snap. The parent now publishes its tracks under **column keys**,
+and `snap` names the parent column:
+
+```diff
+  const holdings = [
+-   { key: 'name', label: 'Resource', snap: 1 },
+-   { key: 'kind', label: 'Type', snap: 2 },
+-   { key: 'monthlyCost', label: '$ / mo', align: 'right', snap: [3, 4.5] },
++   { key: 'name', label: 'Resource', snap: 'name' },
++   { key: 'kind', label: 'Type', snap: 'team' },
++   { key: 'monthlyCost', label: '$ / mo', align: 'right', snap: ['region', 'monthly.5'] },
+  ];
+```
+
+- Translate each index to the parent column that rendered there. The
+  selection column is `'select'`, the actions column `'actions'` — both are
+  targets by name, so `['name', 'actions']` runs a child column across the
+  parent's actions cell.
+- A pair is **inclusive**: `['client', 'amount']` spans from the start of
+  `client` through the end of `amount` (the old `[a, b]` ended at the start
+  of `b`). A trailing `.digits` on a key is a fraction of that track. `-1`
+  is gone: the last column already runs to the end of the data region unless
+  it declares a `width` or a pair.
+- A child column with no `snap` now pairs with the parent column of the
+  **same key** when there is one, so most children need no snaps at all; a
+  column the parent lacks (or hides) flows into the next free parent track.
+- Under a parent that uses `order` or `reorderable`, snaps and key pairing
+  are ignored (dev builds warn) and the child inherits by position, as it
+  always did — a moving parent can only be followed slot by slot.
+
+Silent on upgrade: a numeric `snap` fails the type check but is ignored at
+runtime, so the child falls back to key pairing and flow, which for a child
+sharing the parent's keys is the same alignment as before.
+
+**The published track variables changed name with it.** `--table-{id}-track-{k}`
+per data column became `--table-{id}-track-{key}`, the key in its slot-name
+spelling (`address.city` → `address_city`); `select` and `actions` are
+unchanged. Consumer CSS that read the numbered variables directly has to
+switch to the keys. Nothing else about the bridge moved.
+
 ### `#no-data` is content, not a row
 
 v2 handed the slot the whole empty-state `<tr>`, so anything that was not a
@@ -46198,8 +46418,11 @@ grid actually raises is Chrome/Edge, 114 → 117 (123 for centred cells).
 - **Do not hide cells with `display: none`** (a `thClass`/`tdClass` of
   `hidden`, the v2/early-v3 narrow-screen recipe). A hidden grid item leaves
   its track in place: every following cell shifts one track over and the last
-  track collapses. Hide a column by removing it from `columns` at the
-  breakpoint, which removes the track.
+  track collapses. Hide a column with `hidden: true` on its definition at the
+  breakpoint, which removes the track while the column stays declared (so
+  its slot in `order` survives). Filtering it out of `columns` was the
+  interim advice and is now reserved for a column that does not exist for
+  this user at all.
 - **`contain: inline-size` on `.bb-table-expand__cell`,
   `.bb-table-no-data__cell` and `.bb-table-loading__cell`.** It is the only
   thing keeping a full-width cell's content from resizing the column tracks —
@@ -46220,7 +46443,7 @@ grid actually raises is Chrome/Edge, 114 → 117 (123 for centred cells).
 
 ### Small semantic and visual changes
 
-- **Pinned cells and the stuck header are opaque.** `fixed-columns` cells and
+- **Pinned cells and the stuck header are opaque.** Pinned (`column.fixed`) cells and
   the `fixed-headers` band used to be transparent, so scrolled content showed
   through them. They now paint the table's surface local `--bg` (default
   `var(--bb-panel)`); a pinned cell also paints its row's hover/highlight
@@ -50070,7 +50293,6 @@ export function useApprovalsInbox(): ApprovalsInboxContext {
 				v-model:highlighted="ctx.highlighted.value"
 				v-model:select-all="ctx.table.all.value"
 				v-model:unselected-items="ctx.table.unselected.value"
-				actions
 				caption="Expense approvals"
 				:columns="columns"
 				compact
@@ -52264,7 +52486,6 @@ export function useBacklogWorkspace(): BacklogWorkspaceContext {
 				v-model:highlighted="highlightedIssue"
 				v-model:select-all="ctx.table.all.value"
 				v-model:unselected-items="ctx.table.unselected.value"
-				actions
 				caption="Sprint 24 backlog"
 				:columns="columns"
 				compact
@@ -55847,10 +56068,10 @@ OwnerPaginator::make(...), 'tabCounts' => [...], 'ownerOptions' => [...]])` —
   the page.
 - **The expand row is a real nested `BbTable` that inherits the parent's
   column tracks.** `inherit-column-widths` snaps the holdings table onto the
-  owners table's grid; because the parent is `selectable`, every child
-  column carries an explicit `snap` starting at `1` (`snap: 1…4`), so
-  Resource sits exactly under Owner and the right-aligned $/mo columns share
-  one edge. This is the recipe's signature move — the full defense is in
+  owners table's grid; every child column carries an explicit `snap` naming
+  the parent column it sits under (`snap: 'name'` … `'monthly'` — the
+  parent's `select` column is accounted for by name), so Resource sits
+  exactly under Owner and the right-aligned $/mo columns share one edge. This is the recipe's signature move — the full defense is in
   "Why it is built this way" and in the
   [BbTable guide](../../BbTable.md) ("Nested tables that align with the
   parent").
@@ -56355,7 +56576,6 @@ export function useOwnershipAtlas(): OwnershipAtlasContext {
 				v-model:highlighted="highlightedOwner"
 				v-model:select-all="ctx.table.all.value"
 				v-model:unselected-items="ctx.table.unselected.value"
-				actions
 				actions-text="Holdings"
 				caption="Resource owners"
 				class="table-flush"
@@ -56686,10 +56906,10 @@ defineProps<{ owner: Owner }>();
  * the parent's first data column, and that inset is what reads as hierarchy.
  */
 const columns: Array<BbTableColumn<Holding>> = [
-	{ key: 'name', label: 'Resource', snap: 1 },
-	{ key: 'kind', label: 'Type', snap: 2 },
-	{ key: 'status', label: 'Status', snap: 3 },
-	{ key: 'monthlyCost', label: '$ / mo', align: 'right', snap: 4 },
+	{ key: 'name', label: 'Resource', snap: 'name' },
+	{ key: 'kind', label: 'Type', snap: 'team' },
+	{ key: 'status', label: 'Status', snap: 'region' },
+	{ key: 'monthlyCost', label: '$ / mo', align: 'right', snap: 'monthly' },
 ];
 
 const money = (value: number) =>
@@ -58012,7 +58232,6 @@ const ctx = useInvoiceForm();
 		<!-- Inline-editing table (§6.3): every editable cell type is its own
 		     leaf. The amount column is virtual — computed from the row. -->
 		<BbTable
-			actions
 			caption="Invoice line items"
 			:columns="columns"
 			compact
@@ -59216,7 +59435,6 @@ export function useInvoicesWorkspace(): InvoicesWorkspaceContext {
 				v-model="ctx.table.selected.value"
 				v-model:select-all="ctx.table.all.value"
 				v-model:unselected-items="ctx.table.unselected.value"
-				actions
 				caption="Invoices"
 				:columns="columns"
 				compact
@@ -61034,7 +61252,6 @@ export function useUploadCenter(): UploadCenterContext {
 				v-model="ctx.table.selected.value"
 				v-model:select-all="ctx.table.all.value"
 				v-model:unselected-items="ctx.table.unselected.value"
-				actions
 				caption="Expense receipts"
 				:columns="columns"
 				compact
@@ -64427,7 +64644,6 @@ export function useApprovalsInbox(): ApprovalsInboxContext {
 
 			<BbTable
 				id="approvals-table"
-				actions
 				caption="Expense approvals"
 				:columns="columns"
 				compact
@@ -66554,7 +66770,6 @@ export function useBacklogWorkspace(): BacklogWorkspaceContext {
 			<BbTable
 				id="backlog-table"
 				v-model:highlighted="highlightedIssue"
-				actions
 				caption="Sprint 24 backlog"
 				:columns="columns"
 				compact
@@ -70817,7 +71032,6 @@ const ctx = useInvoiceForm();
 		<!-- Inline-editing table (§6.3): every editable cell type is its own
 		     leaf. The amount column is virtual — computed from the row. -->
 		<BbTable
-			actions
 			caption="Invoice line items"
 			:columns="columns"
 			compact
@@ -72008,7 +72222,6 @@ export function useInvoicesWorkspace(): InvoicesWorkspaceContext {
 
 			<BbTable
 				id="invoices-table"
-				actions
 				caption="Invoices"
 				:columns="columns"
 				compact
@@ -73718,7 +73931,6 @@ export function useUploadCenter(): UploadCenterContext {
 
 			<BbTable
 				id="receipts-table"
-				actions
 				caption="Expense receipts"
 				:columns="columns"
 				compact
@@ -76961,7 +77173,6 @@ export function useApprovalsInbox(): ApprovalsInboxContext {
 
 			<BbTable
 				id="approvals-table"
-				actions
 				caption="Expense approvals"
 				:columns="columns"
 				compact
@@ -78970,7 +79181,6 @@ export function useBacklogWorkspace(): BacklogWorkspaceContext {
 			<BbTable
 				id="backlog-table"
 				v-model:highlighted="highlightedIssue"
-				actions
 				caption="Sprint 24 backlog"
 				:columns="columns"
 				compact
@@ -84380,7 +84590,6 @@ export function useInvoicesWorkspace(): InvoicesWorkspaceContext {
 
 			<BbTable
 				id="invoices-table"
-				actions
 				caption="Invoices"
 				:columns="columns"
 				compact
@@ -86018,7 +86227,6 @@ export function useUploadCenter(): UploadCenterContext {
 
 			<BbTable
 				id="receipts-table"
-				actions
 				caption="Expense receipts"
 				:columns="columns"
 				compact