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

package/dist/ai/BbTable.md

@@ -69,7 +69,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**
@@ -198,11 +198,11 @@ pre-mapping your items:
 ```
 
 **`actions` and `select` are not columns.** Both are rendered by the table
-itself, from the `actions` and `selectable` props. Putting
-`{ key: 'actions' }` in `columns` adds an ordinary data column that reads
-`item.actions`, so you get a stray empty cell _and_ the `#actions` slot never
-renders — which looks like a broken slot and is really a bad column list. Dev
-builds warn.
+itself: the selection column from the `selectable` prop, the actions column
+from the `#actions` slot — providing the slot is what creates the column,
+there is no prop. Putting `{ key: 'actions' }` in `columns` adds an ordinary
+data column that reads `item.actions`, so you get a stray empty cell next to
+the real one. Dev builds warn.
 
 ### Custom cells and headers
 
@@ -225,7 +225,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
@@ -837,12 +838,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`.
 
@@ -853,8 +856,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)]"
@@ -867,7 +871,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`"
@@ -893,15 +897,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>
@@ -923,8 +942,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 },
@@ -968,33 +987,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;
@@ -1005,22 +1032,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
@@ -1392,7 +1447,7 @@ fields.
 Track open rows with `v-model:expanded-items` (an array of row values — set
 `item-value` so expansion is stable across refetches) and render their detail
 through the `#expand` slot, a full-width row below the main one. Trigger it
-from the `#actions` slot (enable the column with `actions`, label it with
+from the `#actions` slot (the slot creates the actions column; label it with
 `actions-text`): the scope hands you `toggleExpanded` — a **callback** — plus
 the read-only `expanded` flag. Drive open/close through the callback; the
 `expanded` prop is one-way state, not something to mutate.
@@ -1409,7 +1464,6 @@ the read-only `expanded` flag. Drive open/close through the callback; the
 	>
 		<BbTable
 			v-model:expanded-items="expanded"
-			actions
 			actions-text="Details"
 			caption="Invoices"
 			:columns="columns"
@@ -1633,11 +1687,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,
@@ -1645,15 +1707,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/
@@ -1685,7 +1748,6 @@ above it. The mechanics:
 	>
 		<BbTable
 			v-model:expanded-items="expanded"
-			actions
 			actions-text="Line items"
 			caption="Invoices"
 			:columns="columns"
@@ -1783,27 +1845,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>
 ```
@@ -1812,9 +1876,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
@@ -2102,7 +2167,6 @@ open-in-new-tab for free.
 		class="max-w-2xl overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
 	>
 		<BbTable
-			actions
 			actions-text="Actions"
 			caption="Invoices"
 			:columns="columns"
@@ -2438,10 +2502,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
@@ -2492,13 +2554,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`
@@ -2556,7 +2656,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
@@ -2576,7 +2675,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' },
@@ -2601,14 +2700,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.
@@ -2622,7 +2721,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:
@@ -2769,8 +2868,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.
@@ -2796,10 +2896,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`.
@@ -2877,7 +2984,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. |
@@ -2891,8 +2997,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. |
@@ -2933,6 +3040,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.
@@ -2946,7 +3054,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…

package/dist/ai/changelog.json

@@ -1,12 +1,12 @@
 {
 	"schemaVersion": 1,
 	"library": "bitboss-ui",
-	"version": "3.0.0-beta.20",
+	"version": "3.0.0-beta.21",
 	"upgrade": "v2-to-v3",
 	"guide": "ai/guides/migration/v2-to-v3.md",
 	"summary": {
 		"renames": 9,
-		"behaviourBreaks": 47
+		"behaviourBreaks": 50
 	},
 	"breaking": [
 		{
@@ -306,10 +306,28 @@
 		},
 		{
 			"kind": "behaviour",
-			"description": "BbTable: hiding a column with thClass/tdClass + display: none (the v2/early-v3 narrow-screen recipe) no longer works — a hidden grid item keeps its track and shifts the following cells; remove the column from columns instead",
+			"description": "BbTable: hiding a column with thClass/tdClass + display: none (the v2/early-v3 narrow-screen recipe) no longer works — a hidden grid item keeps its track and shifts the following cells; set hidden: true on the column instead (filtering it out of columns was the beta.20 doctrine and lost the key from a partial order — DECISIONS § Column visibility, 2026-09-07)",
 			"ruling": "grid substrate, plans/BBTABLE-GRID.md",
 			"guide": "components/bb-table.md § Do not override; guide § Narrow screens"
 		},
+		{
+			"kind": "behaviour",
+			"description": "BbTable actions prop removed — the #actions slot creates the column (a prop without the slot rendered an empty column; now it renders nothing)",
+			"ruling": "DECISIONS § Column pins, 2026-09-07",
+			"guide": "components/bb-table.md § The #actions slot creates the actions column"
+		},
+		{
+			"kind": "behaviour",
+			"description": "BbTable fixedColumns (rendered-slot indices) removed — fixed: 'left' \\",
+			"ruling": "'right' on the column definition + fixed-select / fixed-actions; pins follow the column through a reorder, sticky in place as before",
+			"guide": "DECISIONS § Column pins, 2026-09-07"
+		},
+		{
+			"kind": "behaviour",
+			"description": "BbTable column snap takes the PARENT's column key ('select' / 'actions' by name, inclusive pairs, 'key.5' fractions) instead of a gridline index; --table-{id}-track-{index} became --table-{id}-track-{key} (slot-name spelling). Numeric snaps are ignored at runtime",
+			"ruling": "DECISIONS § Keyed snap, 2026-09-07",
+			"guide": "components/bb-table.md § snap names the parent column"
+		},
 		{
 			"kind": "behaviour",
 			"description": "BbTable highlight is opt-in: with highlighted unbound (or bound as undefined) clicking a row no longer applies bb-table-data__row--highlighted / aria-current — the table used to drive defineModel's local fallback, an unreadable state the app could not clear. Bind ref(null), not ref(); a context seed counts. click:row is unaffected",