bitboss-ui 3.0.0-beta.8 → 3.0.0-beta.9

package/dist/ai/BbTable.md

@@ -25,8 +25,8 @@ keyboard navigation, so your markup stays a column definition plus a few slots.
   domain objects straight to `items` and set `item-value` for stable row
   identity — never pre-map rows into `{ label, value }` shapes.
 
-The table **reports** state (sort, selection, page, expansion, highlight)
-through v-models; it never reorders, slices, or fetches on its own. You apply
+The table **reports** state (sort, column order, selection, page, expansion,
+highlight) through v-models; it never sorts, slices, or fetches on its own. You apply
 that state to your data source (client-side or via `dependencies`-driven
 refetch). This keeps it equally at home in a client-only screen and a
 server-paginated one.
@@ -711,8 +711,10 @@ scriptable from anywhere via `useBbTableContext`
 ### Sorting
 
 Mark columns `sortable` and bind `v-model:sort` — an ordered
-`BbTableSortEntry[]` (`[columnKey, 'asc' | 'desc']`). Header buttons cycle a
-column unsorted → asc → desc → removed; a direction flip updates the entry in
+`BbTableSortEntry[]` (`[columnKey, 'asc' | 'desc']`). A click anywhere on a
+sortable header (its whitespace included — AG Grid parity; the built-in
+button is the keyboard/AT control) cycles the column unsorted → asc → desc →
+removed; a direction flip updates the entry in
 place, so the column keeps its priority in a multi-column sort and other
 entries are never touched. The array order **is** the priority: first entry
 sorts first. The table only reports the model; **apply it to your data**
@@ -812,6 +814,217 @@ field only seeds the header's `aria-sort` when no live model entry exists — it
 does not move the visual indicator; to start pre-sorted, seed `v-model:sort`
 instead (as the example does).
 
+### Column order
+
+`columns` declares what a column **is**; `v-model:order` is the order
+it **renders** in — an array of column keys, the same split as `sortable` +
+`v-model:sort`. Two things write it:
+
+- **Your own control** — a column panel, a settings drawer, a persisted
+  preference. Bind the model and write the array; the table follows. No flag
+  needed for this.
+- **The user, on the table** — with `reorderable`, every data header
+  is a grab surface: drag it and the column moves live under the pointer (AG
+  Grid style, a chip with the label follows), release to commit. The same
+  header row is also one keyboard tab stop (the AG Grid grammar): ←/→ move
+  focus between headers, **Shift+←/→** move the column one slot
+  (Shift+Home/End to the ends), Enter sorts a sortable header.
+  Each committed move writes the model once and is announced.
+
+The model's contract is what makes a column panel trivial:
+
+- Keys listed first render first; declared columns the array omits follow, in
+  declaration order (a column added to `columns` later renders last).
+- Keys that match no declared column render nothing but are **preserved in
+  place**. So hide a column by filtering it out of `columns` — never out of
+  the order — and it comes back exactly where it was.
+- A user move relocates **exactly one key**; everything else, hidden keys
+  included, keeps its relative order. The first move on a partial (or empty)
+  model emits the completed array — persist that.
+- A drop that changes nothing emits nothing; unbound, the table keeps the
+  order as per-mount state like `sort`.
+
+**A column panel and the header drag sharing one order**
+
+```vue
+<template>
+	<div class="flex max-w-2xl flex-col gap-3">
+		<!-- ONE order, two writers: the panel's buttons and the table's own
+		     header drag / keyboard handles both write `v-model:order`.
+		     Hiding a column only filters `columns` — its key stays in the order,
+		     so it comes back where it was. -->
+		<ul
+			aria-label="Columns"
+			class="flex flex-wrap gap-2 text-xs text-[color:var(--bb-text-muted)]"
+		>
+			<li
+				v-for="(column, index) in panelColumns"
+				:key="column.key"
+				class="flex items-center gap-1 rounded-[var(--bb-radius-sm)] border border-[color:var(--bb-border)] py-0.5 pl-2 pr-1"
+			>
+				<BbCheckbox
+					:label="column.label"
+					:model-value="!hidden.has(column.key)"
+					@update:model-value="toggleVisible(column.key)"
+				/>
+				<BbButton
+					:aria-label="`Move ${column.label} left`"
+					:disabled="index === 0"
+					icon="lucide:chevron-left"
+					size="xs"
+					variant="ghost"
+					@click="move(column.key, -1)"
+				/>
+				<BbButton
+					:aria-label="`Move ${column.label} right`"
+					:disabled="index === panelColumns.length - 1"
+					icon="lucide:chevron-right"
+					size="xs"
+					variant="ghost"
+					@click="move(column.key, 1)"
+				/>
+			</li>
+		</ul>
+		<div
+			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		>
+			<BbTable
+				v-model:order="order"
+				caption="Invoices"
+				:columns="visibleColumns"
+				compact
+				item-value="id"
+				:items="invoices"
+				reorderable
+			/>
+		</div>
+		<p class="text-xs text-[color:var(--bb-text-muted)]">
+			Order model: <code>{{ JSON.stringify(order) }}</code>
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbButton, BbCheckbox, BbTable } from 'bitboss-ui';
+import type { BbTableColumn } from 'bitboss-ui';
+
+type Invoice = {
+	id: string;
+	number: string;
+	client: string;
+	issued: string;
+	amount: number;
+};
+
+const euro = new Intl.NumberFormat('en-IE', {
+	style: 'currency',
+	currency: 'EUR',
+});
+
+// The declaration: what a column IS. Never reordered.
+const columns: Array<BbTableColumn<Invoice>> = [
+	{ key: 'number', label: 'Invoice', width: 110 },
+	{ key: 'client', label: 'Client' },
+	{ key: 'issued', label: 'Issued', width: 110 },
+	{
+		key: 'amount',
+		label: 'Amount',
+		align: 'right',
+		width: 110,
+		formatter: euro.format,
+	},
+];
+
+const invoices: Invoice[] = [
+	{
+		id: '1',
+		number: 'INV-1041',
+		client: 'Northwind Traders',
+		issued: '2026-08-02',
+		amount: 4200,
+	},
+	{
+		id: '2',
+		number: 'INV-1042',
+		client: 'Globex',
+		issued: '2026-08-05',
+		amount: 980,
+	},
+	{
+		id: '3',
+		number: 'INV-1043',
+		client: 'Initech',
+		issued: '2026-08-11',
+		amount: 15600,
+	},
+	{
+		id: '4',
+		number: 'INV-1044',
+		client: 'Umbrella',
+		issued: '2026-08-19',
+		amount: 2750,
+	},
+];
+
+// The state: render order (keys). Persist THIS. Seed it with the full key
+// list — it also completes itself on the first move.
+const order = ref<string[]>(columns.map((column) => column.key));
+const hidden = ref(new Set<string>());
+
+// Visibility is just filtering the declaration; the hidden key keeps its
+// slot in `order`.
+const visibleColumns = computed(() =>
+	columns.filter((column) => !hidden.value.has(column.key))
+);
+
+// The panel lists every declared column in the order the model has them.
+const panelColumns = computed(() =>
+	[...columns].sort(
+		(a, b) => order.value.indexOf(a.key) - order.value.indexOf(b.key)
+	)
+);
+
+const toggleVisible = (key: string) => {
+	const next = new Set(hidden.value);
+	if (next.has(key)) next.delete(key);
+	else next.add(key);
+	hidden.value = next;
+};
+
+const move = (key: string, delta: 1 | -1) => {
+	const next = [...order.value];
+	const from = next.indexOf(key);
+	const to = from + delta;
+	if (from < 0 || to < 0 || to >= next.length) return;
+	next.splice(from, 1);
+	next.splice(to, 0, key);
+	order.value = next;
+};
+</script>
+```
+
+**Pinned slots are positions, not columns.** `fixed-columns` indexes rendered
+slots like a spreadsheet's freeze panes (a selection column is slot 0). With
+column order the slot holds: whichever column lands in it is pinned, and
+dragging the identity column out of its pinned slot (slot 1 when
+`selectable`, slot 0 otherwise) unpins it (AG Grid pins columns; BbTable
+pins positions). Keep the reorder + pin combination for slots that
+never move — `select`, `actions`, or a first column you also lock by
+normalizing the model in your `@update:order` handler.
+
+**Nested tables.** An inheriting child aligns to the parent's rails by
+**position**, so a reordered parent re-pairs the child's columns unless the
+child follows. Give both tables the same `v-model:order` when they
+share keys (and the child declares no `snap`) and they stay paired by key.
+`snap` points are positional in the parent's rendered order: reorder the
+parent and a snap-mapped child follows its slots, but never reorder (or share
+the order with) the snap-mapped child itself — dev builds warn.
+
+Apply the model synchronously in your handler and persist afterwards: an
+`await` before the write moves the cell in a later flush, after the table
+has re-focused the handle, and keyboard focus is usually lost (whether it
+survives depends on which cell Vue's keyed patch detaches).
+
 ### Selection and bulk actions
 
 Add `selectable` for multi-select (`multiple` is the default) bound with
@@ -1311,6 +1524,99 @@ fixed first track).
 The actions-column toggle remains valid — prefer it when expansion reveals
 _detail about the row_ rather than _children of it_.
 
+### Column resize
+
+`resizable` puts a handle on the trailing edge of every data header:
+drag it and the column follows live, release to commit; double-click it to go
+back to the declared width. From the keyboard, **Alt+←/→** resizes the
+focused header in 10px steps (the header row is a tab stop whenever columns
+are resizable or reorderable).
+
+There is no width model on purpose. `width` on the column definition stays
+the single declared truth, and a user resize is an **override** the table
+keeps until that column's `width` changes:
+
+- Each commit fires `@resize:column="(key, width) => …"` **once** with the new width
+  in px — or `null` after a double-click reset.
+- To persist, write the reported width back into your column definition (a
+  `computed` over your persisted widths). The definition wins whenever it
+  changes, so a programmatic `width` change always takes effect.
+- Unbound, the override lives for the mount, like an unbound `sort`.
+- A resized width is always px; `width` still accepts `'20%'` / `'12rem'`
+  for what you declare yourself.
+
+Headers never wrap and never floor their column: squeezed, a header label
+ellipsizes and the sort arrow stays; at the narrowest only the arrow (and
+the handle) survive, and the column is still resizable. The data cells of a
+resized column clip with an ellipsis instead of spilling into the neighbour
+(a squeezed track cannot wrap a single word); every other cell keeps
+wrapping. While a resize runs the whole page shows the resize cursor.
+
+A resized column becomes an **exact** track; the other columns keep doing
+what they did — unfrozen ones share the surplus, and a table whose columns
+are all declared with a `width` keeps sharing it among the un-resized ones —
+so a filling table stays filled and nothing collapses. **Shift+drag** moves
+the border instead: the right neighbour absorbs the delta, the total stays
+put, and both columns are reported. A table that inherits its widths from a
+parent (`inherit-column-widths`) renders no handles — its tracks are the
+parent's.
+
+**Resizable columns reporting widths back into the definition**
+
+```vue
+<template>
+	<div class="flex max-w-2xl flex-col gap-1.5">
+		<div
+			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		>
+			<BbTable
+				caption="Invoices"
+				:columns="columns"
+				compact
+				item-value="id"
+				:items="invoices"
+				resizable
+				@resize="onResize"
+			/>
+		</div>
+		<p class="text-xs text-[color:var(--bb-text-muted)]">
+			Widths: <code>{{ JSON.stringify(widths) }}</code>
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbTable } from 'bitboss-ui';
+import type { BbTableColumn } from 'bitboss-ui';
+
+type Invoice = { id: string; number: string; client: string; amount: number };
+
+const base: Array<BbTableColumn<Invoice>> = [
+	{ key: 'number', label: 'Invoice' },
+	{ key: 'client', label: 'Client' },
+	{ key: 'amount', label: 'Amount', align: 'right' },
+];
+// Persist THIS (localStorage, a user preference…): key → px.
+const widths = ref<Record<string, number>>({});
+// The definition carries the persisted widths; the table treats them as the
+// declared truth, so nothing jumps after a reload.
+const columns = computed(() =>
+	base.map((column) => ({ ...column, width: widths.value[column.key] }))
+);
+const onResize = (key: string, width: number | null) => {
+	const next = { ...widths.value };
+	if (width === null) delete next[key];
+	else next[key] = width;
+	widths.value = next;
+};
+const invoices: Invoice[] = [
+	{ id: '1', number: 'INV-1041', client: 'Northwind Traders', amount: 4200 },
+	{ id: '2', number: 'INV-1042', client: 'Globex', amount: 980 },
+	{ id: '3', number: 'INV-1043', client: 'Initech', amount: 15600 },
+];
+</script>
+```
+
 ### Nested tables that align with the parent
 
 A `BbTable` rendered inside another's `#expand` slot is independent by
@@ -1528,11 +1834,42 @@ clicks are ignored on purpose: those inside interactive elements (links,
 buttons, inputs, labels keep their own semantics) and those ending a text
 selection (dragging to copy a cell must not mutate state).
 
+**Highlight is opt-in, and the model's value is the switch.** Bind nothing and
+the mechanic is entirely off — a row click emits `click:row` and does nothing
+else: no class, no `aria-current`, no state. That matters because the table has
+nowhere to put a highlight it invents; a table that highlighted itself would
+drive a cursor the app can neither read nor clear.
+
+The switch reads the value, not the binding: **`undefined` means "never
+initialised" and keeps highlight off; `null` means "initialised and currently
+empty" and turns it on.** So initialise the model:
+
+```ts
+const highlighted = ref(null); // ✅ connected
+const highlighted = ref(); // ❌ undefined — highlight stays off (warns in dev)
+```
+
+A value seeded through the shared context counts exactly the same, and binds
+two ways just like the prop:
+
+```ts
+const highlighted = ref(null);
+useBbTableContext('invoices-table', { highlighted });
+```
+
+`click:row` is never gated — it fires on every row click whether or not
+highlight is connected, so listening for clicks costs you nothing. Calling
+`toggleHighlighted` from a cell slot on an unconnected table does nothing and
+warns once in dev.
+
 Highlight ships with a **default cursor**: the row gets `aria-current="true"`
 and the `bb-table-data__row--highlighted` class, and the shipped stylesheet
-paints that class with a subtle primary-tinted fill plus a left accent bar —
-distinct from hover and from a plain focus ring, and readable in both light
-and dark. Screen-reader users get the `aria-current` announcement either way;
+paints that class with a quiet neutral fill plus a left accent bar in your
+brand primary — distinct from hover and from a plain focus ring, and readable
+in both light and dark. The fill is `--bb-muted` (the shared "selected/active"
+stop on the neutral surface ladder, one step above the `--bb-surface-hover`
+used for row hover) and steps to `--bb-pressed` while hovered, so it never
+depends on what your `--bb-primary` happens to be — only the accent bar does. Screen-reader users get the `aria-current` announcement either way;
 sighted users now get a visible cursor out of the box too, including once
 `keyboard-navigation` is on and the roving tabindex needs to be seen. Override
 it with `row-class` (or equivalent visible styling) whenever the default
@@ -2145,6 +2482,9 @@ leave the screen. Collapse instead of scroll:
   out. Removing the column removes its grid track. Do **not** hide cells with
   `thClass`/`tdClass` + `display: none`: the table is a grid, a hidden cell
   leaves its track in place and every following cell shifts one track over.
+  A dropped key keeps its slot in `order` (the write-back never drops
+  unknown keys), so the column returns where it was — never filter the
+  order array.
 - **Stack what survives into the primary cell.** The identity slot renders the
   name plus the hidden facts under it, at `--bb-text-muted`, so nothing is
   actually lost.
@@ -2174,20 +2514,23 @@ root `.bb-table__table[role=table]` owns the column tracks and every row group
 and row is a subgrid of it. Style it through the classes and the roles — never
 through element names, which match nothing:
 
-| Region       | Class                                                    | Role                                      |
-| ------------ | -------------------------------------------------------- | ----------------------------------------- |
-| grid root    | `.bb-table__table`                                       | `table`                                   |
-| header group | `.bb-table__head`                                        | `rowgroup`                                |
-| header row   | `.bb-table-header-row`                                   | `row`                                     |
-| header cell  | `.bb-table-header` (+ `--select`, `--actions`)           | `columnheader`                            |
-| body group   | `.bb-table__body`                                        | `rowgroup`                                |
-| data row     | `.bb-table-data__row` (+ `--highlighted`)                | `row`                                     |
-| data cell    | `.bb-table-data__cell` (+ `--select`)                    | `cell`                                    |
-| actions cell | `.bb-table__cell--actions`                               | `cell`                                    |
-| expand row   | `.bb-table-expand__row` > `.bb-table-expand__cell`       | `row` > `cell`                            |
-| empty state  | `.bb-table-no-data__row` > `.bb-table-no-data__cell`     | `row` > `cell`                            |
-| footer group | `.bb-table__foot` (`#tfoot` content)                     | `rowgroup` only when `#tfoot` is provided |
-| caption      | `.bb-table-caption` (before the root, `aria-labelledby`) | —                                         |
+| Region         | Class                                                                                                                     | Role                                      |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| grid root      | `.bb-table__table`                                                                                                        | `table`                                   |
+| header group   | `.bb-table__head`                                                                                                         | `rowgroup`                                |
+| header row     | `.bb-table-header-row`                                                                                                    | `row`                                     |
+| header cell    | `.bb-table-header` (+ `--select`, `--actions`)                                                                            | `columnheader`                            |
+| body group     | `.bb-table__body`                                                                                                         | `rowgroup`                                |
+| data row       | `.bb-table-data__row` (+ `--highlighted`)                                                                                 | `row`                                     |
+| data cell      | `.bb-table-data__cell` (+ `--select`)                                                                                     | `cell`                                    |
+| actions cell   | `.bb-table__cell--actions`                                                                                                | `cell`                                    |
+| expand row     | `.bb-table-expand__row` > `.bb-table-expand__cell`                                                                        | `row` > `cell`                            |
+| empty state    | `.bb-table-no-data__row` > `.bb-table-no-data__cell`                                                                      | `row` > `cell`                            |
+| footer group   | `.bb-table__foot` (`#tfoot` content)                                                                                      | `rowgroup` only when `#tfoot` is provided |
+| focused header | `.bb-table-header[data-column-key]:focus-visible` (`reorderable` only; inset ring, the header row is one roving tab stop) | `columnheader`                            |
+| dragged column | `.bb-table-header--dragging` on the header; `.bb-table__head--dragging` on the head group during a drag                   | —                                         |
+| drag chip      | `.bb-table-column-ghost` (a `popover="manual"` in the top layer; paints `--bb-panel`, not the table's `--bg`)             | — (`aria-hidden`)                         |
+| caption        | `.bb-table-caption` (before the root, `aria-labelledby`)                                                                  | —                                         |
 
 `[role='row']`, `[role='cell']` and `[role='columnheader']` are supported
 hooks, not incidental markup — use them when you mean "every row kind" or
@@ -2295,6 +2638,8 @@ 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.)
 - `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.
@@ -2317,8 +2662,13 @@ reader.
   localized `common.loadingText`, so an unset value still announces.
 - Row selection labels default to the localized "select" word plus every
   cell's content. `accessible-label` overrides that per row — it is called
-  `(columns, item)` with the mapped cells and the raw record, and whatever it
-  returns becomes the checkbox's label.
+  `(columns, item)` with the mapped cells (in **render** order — look them up
+  by `key`, never by position) and the raw record, and whatever it returns
+  becomes the checkbox's label.
+- `fixed-columns` pins **slots**, not columns: under `order` the
+  column that lands in a pinned slot is the pinned one (see Column order).
+- A column panel that holds a partial `order` receives the completed
+  array on the user's first move — its persisted list grows to every key.
 - Enabling select-all does not re-emit an empty `modelValue` (see the
   select-all section) — in all-mode, read `select-all` +
   `unselected-items`, not `modelValue`.
@@ -2358,6 +2708,15 @@ reader.
   identity rather than object reference.
 - Sortable headers set `aria-sort` and render real buttons; custom header
   slots should keep a button calling `toggleSort`.
+- With `reorderable` the header row becomes one roving tab stop
+  (the AG Grid grammar): ←/→ move focus between headers, Home/End to the
+  ends, **Shift+←/→** move the focused column one slot (Shift+Home/End to
+  the ends), Enter/Space sorts a sortable header — every move committed
+  immediately and announced through a polite status region ("X moved to
+  position 2 of 5"); a one-line sr-only instruction describes each header.
+  The sort button leaves the tab order (the header is the target; it still
+  works for the mouse). NVDA/JAWS browse mode intercepts arrows on a focused
+  element — the same focus-mode step as row keyboard navigation.
 - When you paginate, pass `page` / `per-page` / `total-items` so the table
   announces the full result count (`aria-rowcount`) and each row's absolute
   index (`aria-rowindex`, expansion-aware), not just the current page.
@@ -2377,6 +2736,7 @@ reader.
 - `v-model:expandedItems` — type: `any[] \| undefined`
 - `v-model:highlighted` — type: `any`
 - `v-model` — type: `any`
+- `v-model:order` — type: `string[] \| undefined`
 - `v-model:selectAll` — type: `boolean \| undefined`
 - `v-model:sort` — type: `BbTableSortEntry[] \| undefined`
 - `v-model:unselectedItems` — type: `any[] \| undefined`
@@ -2385,7 +2745,7 @@ 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. |
+| `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` |  |  | 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. |
@@ -2400,10 +2760,10 @@ reader.
 | `enforceCoherence` | `boolean \| undefined` |  |  | After every load (initial, `dependencies` refetch or a change of the `items` array) prunes the row-keyed models of values whose row is no longer in the result set: `modelValue`, `unselected-items`, `highlighted` and `expanded-items`. Values… |
 | `expandedItems` | `any[] \| undefined` | `[]` |  | Used by `v-model:expandedItems`. Array of the currently expanded items — toggled by the row expand control and by external writes (mirrors the `highlighted`/`sort` v-model surfaces). Drives the `#expand` slot rows and their `aria-expanded`/… |
 | `fixed` | `boolean \| undefined` |  |  | 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. |
+| `fixedColumns` | `(number \| { index: number; position: "left" \| "right"; })[] \| undefined` | `[]` |  | Definition for which column should be fixed. It can be an array of index of the column to fix on the left side of the table or an array of objects indicating the index and the position `left` or `right` where to affix the columns. Indices a… |
 | `fixedHeaders` | `boolean \| undefined` |  |  | Boolean that sets the headers as sticky to the top of the table. |
 | `headerRowClass` | `Classes \| undefined` |  |  | Defines the classes to be passed to the header row. |
-| `highlighted` | `any` | `undefined` |  | Used by `v-model:highlighted`. A parallel, UI-intent state to selection — typically "the row whose details are open". A single item value (or `null`) — highlight is single by design. Purely mechanical: highlighted rows only get the `bb-tabl… |
+| `highlighted` | `any` | `undefined` |  | Used by `v-model:highlighted`. A parallel, UI-intent state to selection — typically "the row whose details are open". A single item value (or `null`) — highlight is single by design. **Opt-in, and `undefined` is the opt-out.** Leave it unbo… |
 | `id` | `string \| undefined` |  |  | Stable id for this table's width context. When omitted a unique id is generated. Nested tables use the nearest ancestor id to inherit widths. |
 | `inheritColumnWidths` | `string \| boolean \| undefined` |  |  | Opt a nested table into inheriting its column widths from an ancestor table's matching tracks (accounting for `select`/`actions` columns). This also makes the parent's tracks authoritative, so it is **off by default** — a nested table rende… |
 | `interactiveWhileLoading` | `boolean \| undefined` |  |  | Keeps the table interactive while it is loading. The header and the rows are `inert` while loading by default — a refetch is about to replace the rows, so editing, selecting or sorting them races the incoming data. This escape hatch exists … |
@@ -2418,9 +2778,12 @@ reader.
 | `multiple` | `boolean \| undefined` | `true` |  | Allows the selection of multiple items. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
 | `noDataText` | `string \| undefined` |  |  | String displayed when there are no items to display. |
+| `order` | `string[] \| undefined` | `[]` |  | Used by `v-model:order`. Ordered array of column keys — the render order of the data columns. Keys listed here render first, in this order; declared columns it omits follow, in declaration order (so a column added to `columns` later renders… |
 | `page` | `string \| number \| undefined` |  |  | Current page number starting from 1, used for accessibility purposes. Also flows into the shared table context, so a `BbPagination` paired through `id` reads it as the current page. Numeric strings are coerced (server pagination fields ofte… |
 | `perPage` | `string \| number \| undefined` |  |  | Number of items per page, used for accessibility purposes. Also flows into the shared table context read by a `BbPagination` paired through `id`. When omitted, an array `items` table infers it from `items.length`; an explicit value (or a co… |
 | `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
+| `reorderable` | `boolean \| undefined` |  |  | Lets the user reorder the data columns: drag a header cell (AG Grid style — the column moves live under the pointer and a chip with its label follows) or, from the keyboard, use each header's reorder handle (ArrowLeft / ArrowRight move the … |
+| `resizable` | `boolean \| undefined` |  |  | Lets the user resize the data columns of a root table: drag the handle on a header's trailing edge (the column follows live, the width commits on release), or press Alt + ArrowLeft / ArrowRight on the focused header; double-click the handle… |
 | `rowClass` | `RowClasses<Item> \| undefined` |  |  | Defines the classes to be passed to each data row. Can also be a function of the row's item for dynamic values. |
 | `selectable` | `boolean \| ((item: Item) => boolean) \| undefined` |  |  | Defines whether the table is selectable. Can be a global boolean that affects all rows or a function that accepts an item and returns a boolean that only affects that item. |
 | `selectAll` | `boolean \| undefined` | `false` |  | Defines whether the "Select all" checkbox is checked. |
@@ -2440,9 +2803,11 @@ reader.
 - `dblclick:row` — `(e: "dblclick:row", event: MouseEvent, item: any): void`
 - `item:selected` — `(e: "item:selected", value: any): void`
 - `item:unselected` — `(e: "item:unselected", value: any): void`
+- `resize:column` — `(e: "resize:column", key: string, width: number \| null): void` — A column was resized by the user (`resizable`): the new width in px, or `null` when the handle was double-clicked to reset the column to its declared width.
 - `update:expandedItems` — `(e: "update:expandedItems", value: any[]): void`
 - `update:highlighted` — `(e: "update:highlighted", value: any): void`
 - `update:modelValue` — `(e: "update:modelValue", value: any): void`
+- `update:order` — `(e: "update:order", value: string[]): void`
 - `update:selectAll` — `(e: "update:selectAll", value: boolean): void`
 - `update:sort` — `(e: "update:sort", value: BbTableSortEntry[]): void`
 - `update:unselectedItems` — `(e: "update:unselectedItems", value: any[]): void`

package/dist/ai/changelog.json

@@ -1,12 +1,12 @@
 {
 	"schemaVersion": 1,
 	"library": "bitboss-ui",
-	"version": "3.0.0-beta.8",
+	"version": "3.0.0-beta.9",
 	"upgrade": "v2-to-v3",
 	"guide": "ai/guides/migration/v2-to-v3.md",
 	"summary": {
 		"renames": 9,
-		"behaviourBreaks": 43
+		"behaviourBreaks": 44
 	},
 	"breaking": [
 		{
@@ -292,6 +292,12 @@
 			"ruling": "grid substrate, plans/BBTABLE-GRID.md",
 			"guide": "components/bb-table.md § Do not override; guide § Narrow screens"
 		},
+		{
+			"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",
+			"ruling": "owner 2026-08-27",
+			"guide": "components/bb-table.md § Highlight is opt-in"
+		},
 		{
 			"kind": "behaviour",
 			"description": "BbTable renders a CSS grid of divs with ARIA roles, not a <table>: every element selector under .bb-table (table/thead/tbody/tfoot/caption/tr/th/td/colgroup/col) matches nothing. Every .bb-table* class survives; .bb-table__table/__head/__body/__foot + [role=row]/[role=columnheader]/[role=cell] are the blessed translation (no data-* hooks, no shim classes)",