bitboss-ui 3.0.0-beta.51 → 3.0.0-beta.53

package/dist/ai/BbTable.md

@@ -373,7 +373,7 @@ scope in `#<key>:header`. With it each name gets its own scope, as on `BbTable`.
 **Add beside a header instead of replacing it** with
 `#<key>:header:prepend` / `#<key>:header:append` — rendered before / after the
 column's existing header content (the label + sort control, or your own
-`#<key>:header` replacement), so a resize grip or reorder handle no longer
+`#<key>:header` replacement), so a resize handle or reorder handle no longer
 costs you the built-in sort button. The table-wide pair `#header:prepend` /
 `#header:append` applies one template to every data column's header (never the
 structural select/actions cells); both forms receive the header scope above
@@ -953,6 +953,20 @@ a native `<input>` / `<select>`:
 <BbTable :items="filteredItems" :columns="columns" caption="Invoices" />
 ```
 
+```ts
+// An emptied (or cleared) BbTextInput writes `null`, not '' — type it so.
+const search = ref<string | null>('');
+const statuses = ref<string[]>([]);
+const filteredItems = computed(() => {
+	const q = search.value?.trim().toLowerCase() ?? '';
+	return invoices.value.filter(
+		(row) =>
+			(!q || row.client.toLowerCase().includes(q)) &&
+			(!statuses.value.length || statuses.value.includes(row.status))
+	);
+});
+```
+
 Pick the shape by where the rows come from:
 
 | Your situation                         | The filter mechanism                                                                     |
@@ -1172,7 +1186,7 @@ const sortedInvoices = computed(() => {
 A custom `#<key>:header` slot replaces the built-in sort button, but its scope
 hands you `sortOrder` and `toggleSort` so your header can keep sorting alive
 (render your own button and call `toggleSort`). To merely add something next
-to the control — a resize grip, a filter icon — use
+to the control — a resize handle, a filter icon — use
 `#<key>:header:prepend/append` instead and keep the built-in button (see
 "Custom cells and headers"). The column-level `sorted`
 field only seeds the header's `aria-sort` when no live model entry exists — it
@@ -1471,11 +1485,17 @@ Add `selectable` for multi-select (`multiple` is the default) bound with
 `v-model` — the model **must** be an array in multiple mode (the table throws
 otherwise). With `item-value` set, the model holds ids rather than whole rows.
 Pass `selectable` a predicate (`(item) => boolean`) to gate specific rows: the
-excluded rows' controls disable and `toggleSelected` refuses them too.
+excluded rows' controls disable and `toggleSelected` refuses them too. Under
+`select-all` an excluded row stays unticked (select-all covers the rows the
+user can select); one the model names explicitly still shows ticked.
 
 To drive a toolbar that lives **outside** the table subtree, give the table an
 `id` and read `useBbTableContext(id).selected` — the handle mirrors the
-table's selection both ways, so a bulk-action bar needs no prop drilling. As
+table's selection both ways, so a bulk-action bar needs no prop drilling.
+Count from `all` and `unselected` too: the header checkbox is select-all,
+which leaves `selected` empty (see [§ Single select, select-all and
+limits](#single-select-select-all-and-limits)), so a bar that reads
+`selected` alone vanishes while every row shows ticked. As
 everywhere in the library, the destructive bulk action is gated by
 `useConfirm` before it touches the data.
 
@@ -1564,14 +1584,27 @@ const selected = ref<string[]>([]);
 
 // Same id as the table — the handle mirrors the table's selection both ways.
 const ctx = useBbTableContext('member-selection', { selected: [] });
-const selectedCount = computed(() => ctx.selected.value?.length ?? 0);
-const clear = () => (ctx.selected.value = []);
+// The header checkbox is "select all": it sets `all` and leaves `selected`
+// empty (built for "all across pages"), with the rows unticked since in
+// `unselected`. A client-side table reads the chosen rows from both.
+const chosenIds = computed<string[]>(() =>
+	ctx.all.value
+		? members.value
+				.map((member) => member.id)
+				.filter((id) => !ctx.unselected.value.includes(id))
+		: (ctx.selected.value ?? [])
+);
+const selectedCount = computed(() => chosenIds.value.length);
+const clear = () => {
+	ctx.all.value = false;
+	ctx.selected.value = [];
+};
 
 const { confirm } = useConfirm();
 
 // Destructive bulk action: `await` the decision, act only on a yes.
 const removeSelected = async () => {
-	const ids: string[] = ctx.selected.value ?? [];
+	const ids = chosenIds.value;
 	const ok = await confirm({
 		title: `Delete ${ids.length} ${ids.length === 1 ? 'member' : 'members'}?`,
 		text: 'They will lose access to this workspace immediately.',
@@ -1979,7 +2012,7 @@ _detail about the row_ rather than _children of it_.
 
 ### Reordering rows
 
-`reorderable-rows` adds a slim grip at the start of every row: the user drags
+`reorderable-rows` adds a slim drag handle at the start of every row: the user drags
 a row to a new place and the table reports the move with **`reorder:rows`**.
 The table never reorders `items` itself. Your handler splices the array, and
 saves the order if it should outlive the page:
@@ -1991,8 +2024,8 @@ saves the order if it should outlive the page:
 	<div class="flex max-w-2xl flex-col gap-3">
 		<!-- The table only REPORTS the move: `reorder:rows` says which item went
 		     from where to where, and the handler below splices the array and
-		     saves the order. Drag a row by its grip (or anywhere on it with a
-		     mouse), or focus a grip and use Space, the arrow keys and Space. -->
+		     saves the order. Drag a row by its handle (or anywhere on it with a
+		     mouse), or focus a handle and use Space, the arrow keys and Space. -->
 		<div
 			class="overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 		>
@@ -2106,11 +2139,11 @@ function move({ from, to }: { from: number; to: number }) {
   `items` (`items.indexOf(item)` finds it); `from` and `to` index the `items`
   the table holds. Remove at `from`, insert at `to`. A drop where the row
   already was emits nothing.
-- **Mouse and pen** drag from the grip, or from anywhere on the row once the
+- **Mouse and pen** drag from the handle, or from anywhere on the row once the
   pointer has moved 5px. A press on a control inside the row never starts a
   drag (a button, a link, an input, the select checkbox, anything with a
   widget role or `draggable`), and a press that sets off sideways selects text
-  instead. **Touch** drags from the grip only, at once (no long-press), so a
+  instead. **Touch** drags from the handle only, at once (no long-press), so a
   finger on the row still scrolls. The click that ends a drag is not a row
   click: no `click:row`, no highlight.
 - **While it drags**, a copy of the row follows the pointer with its real cell
@@ -2119,10 +2152,10 @@ function move({ from, to }: { from: number; to: number }) {
   Near the top or bottom edge the nearest scroll container scrolls, `virtual`
   tables included, and the rows that scroll in are targets; the wheel scrolls
   too.
-- **Keyboard:** the grip is a button. Space or Enter picks the row up, ↑ / ↓ /
+- **Keyboard:** the drag handle is a button. Space or Enter picks the row up, ↑ / ↓ /
   Home / End move it, Space or Enter drops it, Esc or Tab cancels. Under
-  `keyboard-navigation`, Space or Enter on the grip's cell picks it up at once.
-- **Accessibility:** each grip is named "Move row" + the row's label (its
+  `keyboard-navigation`, Space or Enter on the handle's cell picks it up at once.
+- **Accessibility:** each drag handle is named "Move row" + the row's label (its
   cell in the `rowHeader: true` column, else the first column) and described by the keyboard
   instructions. A polite live region announces the pick-up, each position
   ("Position 3 of 6"), the drop and a cancel.
@@ -2135,10 +2168,16 @@ function move({ from, to }: { from: number; to: number }) {
 - **Server pages:** the indexes are into the page the table holds. For the
   whole list, add the page's offset (`(page - 1) * perPage + from`). Moving a
   row to another page is not supported.
-- **Sorting:** the grips stay enabled while a column sort is active, so a move
-  is reported against the sorted rows. What that means for your stored order
-  is your app's call (clear the sort first, or hide reordering while sorted).
-- **Pinning and RTL:** the grip column is structural, like the select column:
+- **Sorting:** the drag handles stay enabled while a column sort is active, and a
+  move is reported against the sorted rows, the order the user sees. This is
+  easy to get wrong: splicing your stored array changes nothing a sort shows,
+  so the row snaps back. Give the drop a meaning the sort can show. Sorted by
+  a rank the drag edits (priority, position), write the new ranks in the order
+  the user now sees and the sort reproduces the drop. Sorted by something the
+  drag cannot change (a name, a date), turn the drag handles off for that sort
+  (`:reorderable-rows="!sort.length || sort[0][0] === 'priority'"`) rather
+  than snapping back or clearing the user's sort behind their back.
+- **Pinning and RTL:** the drag handle column is structural, like the select column:
   it never appears in `order` and never moves, it pins with the first
   left-pinned column, and in RTL it sits at the logical start (the right
   edge).
@@ -2146,7 +2185,7 @@ function move({ from, to }: { from: number; to: number }) {
   goes on while its row is still there, and cancels cleanly, announced, when
   it is gone. Expanding or collapsing one of the table's own rows cancels it.
   While `loading`, no new drag starts.
-- **No grips** with a custom `#tbody`.
+- **No drag handles** with a custom `#tbody`.
 - **Styling:** `pt:dragHandle` takes a class list or an object (no per-row
   function).
 
@@ -2194,6 +2233,13 @@ 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.
 
+**Lock one column with `resizable: false`** on its definition, the way
+`reorderable: false` locks its place: its header has no handle, Alt+←/→ on
+it does nothing, and a neighbour's Shift+drag resizes the neighbour alone. Use
+it for control columns sized to their content (an expand chevron, a row
+number at `width: 'max-content'`). The lock stops the user, not your code: a
+`width` you set still applies.
+
 **Resizable columns reporting widths back into the definition**
 
 ```vue
@@ -2340,7 +2386,7 @@ above it. The mechanics:
 			</template>
 
 			<template #expand="{ item }">
-				<div class="bg-(--bb-muted) px-1 py-1">
+				<div class="bg-(--bb-muted) py-1">
 					<BbTable
 						:caption="`Line items of ${item.number}`"
 						:columns="lineColumns"
@@ -2476,7 +2522,42 @@ Two rules keep them honest:
 2. **Never add nest padding on the body only.** Padding the child's body
    (`.bb-table__body`) but not its header (or vice versa) reintroduces exactly
    the offset the snap just removed. Put the inset on the nest container, where
-   both row groups inherit it.
+   both row groups inherit it, and keep it **vertical** (`py-1`): the child
+   inherits the parent's track widths, not their positions, so horizontal
+   padding moves every column off its rail by that much and pushes the child
+   past the parent's edge into its scroll.
+
+#### Indenting nested levels
+
+Two CSS tokens on the **root** table step each nested level in, the way a
+tree reads, while every other column stays on the parent's columns:
+
+- `--indent` — the step per level (a length; `0px` by default, no indent).
+- `--indent-at` — where the step goes: `drag-handle`, `select` (the default) or
+  `content`.
+
+```css
+.services-table {
+	--indent: 24px;
+	--indent-at: select;
+}
+```
+
+| `--indent-at` | Stays in one column at every level | Steps in per level                       |
+| ------------- | ---------------------------------- | ---------------------------------------- |
+| `drag-handle` | nothing before the content         | the drag handle, the select, the content |
+| `select`      | the drag handle                    | the select and the content               |
+| `content`     | the drag handle and the select     | the first column's content               |
+
+Each nested level adds one step before the anchor and takes it from its
+first content column, so Status, Total or any other column never moves and
+level three lands two steps in by itself. A missing anchor falls through: no
+drag handle column behaves as `select`, no select column as `content`. Set the tokens
+on the root table (nested tables inherit them), or on one nested table to
+change the anchor from that level down. `--indent-at` is read when the table
+measures (mount, resize): set it in CSS, not from an animation. A nested
+table also carries `--depth` (1, 2, …) for styling by level, e.g. a group bar:
+`border-inline-start: calc(var(--depth) * 2px) solid var(--bb-primary)`.
 
 ### Row highlight (master–detail)
 
@@ -2485,37 +2566,63 @@ details are open" — independent of selection. Clicking anywhere on a row
 toggles it: a new click replaces the previous highlight, and clicking the
 highlighted row clears it back to `null`. **Highlight is single by design** —
 one row is "the open one" — so bind a single item value, never an array. Two kinds of
-clicks are ignored on purpose: those inside interactive elements (links,
-buttons, inputs, labels keep their own semantics) and those ending a text
-selection (dragging to copy a cell must not mutate state).
+clicks are not row clicks: those starting on a control inside the row (a link,
+a button, an input, the select checkbox, any ARIA widget — they keep their own
+semantics) and those ending a text selection (dragging to copy a cell must not
+mutate state). Neither highlights the row nor emits `click:row`.
 
-**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
+**Highlight is opt-in: it is on when it is bound.** 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:
+drive a cursor the app can neither read nor clear. Bound means
+`v-model:highlighted` (whatever its value — `ref()` and `ref(null)` both mean
+"nothing open yet"), or `highlighted` provided through the shared context,
+which binds two ways just like the prop:
 
 ```ts
-const highlighted = ref(null); // ✅ connected
-const highlighted = ref(); // ❌ undefined — highlight stays off (warns in dev)
+const highlighted = ref<number | null>(null);
+useBbTableContext('invoices-table', { highlighted });
 ```
 
-A value seeded through the shared context counts exactly the same, and binds
-two ways just like the prop:
+**`highlightable` decides which rows a click may open.** `false` turns the
+click off for every row (a user without the privilege to open details), and a
+function of the row's item turns it off for some. A refused row ignores a
+click, Enter and `toggleHighlighted`, loses the pointer cursor highlightable
+rows get, and never clears the row that is open. It gates the user only: a
+value your code puts in `highlighted` (a deep link to a record) shows on a
+refused row too — the table reflects your state, it does not correct it, just
+as a `selectable`-refused row the model names stays ticked.
+
+Fetching the details belongs in a watcher on the model, not in `click:row`
+(the model also changes on the click that closes, on Enter, and from your own
+code). Abort the previous fetch when the highlight moves on, so a slow answer
+never paints over a newer one:
 
 ```ts
-const highlighted = ref(null);
-useBbTableContext('invoices-table', { highlighted });
+const openTaskId = ref<string | null>(null);
+watch(openTaskId, (id, _previous, onCleanup) => {
+	if (id === null) return taskStore.closeDetails();
+	const controller = new AbortController();
+	onCleanup(() => controller.abort());
+	void taskStore.showDetails(id, { signal: controller.signal });
+});
+```
+
+```vue
+<BbTable
+	v-model:highlighted="openTaskId"
+	:highlightable="can(Privilege.TASKS_SHOW)"
+	item-value="id"
+	:items="tasks"
+	:columns="columns"
+/>
 ```
 
-`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.
+`click:row` is never gated by highlight — it fires on every row click whether
+or not highlight is bound or the row highlightable, so listening for clicks
+costs you nothing. Calling `toggleHighlighted` from a cell slot on an unbound
+table does nothing and warns once in dev.
 
 Highlight ships with a **default cursor**: the row gets `aria-current="true"`
 and the `bb-table__row--highlighted` class, and the shipped stylesheet
@@ -2743,7 +2850,11 @@ Row events: `click:row`, `dblclick:row` and `contextmenu:row` fire with
 `(event, item)` — the native event and **your record exactly as you passed it
 in `items`**, nothing else. No wrapper to unpack, no third argument; selection
 state is already yours through the `v-model`, and the row's value resolves
-from the record through `item-value` exactly as the models do. Reserve these
+from the record through `item-value` exactly as the models do. A click that
+starts on a control inside the row (the select checkbox, a link, a button, any
+ARIA widget) is the control's, not the row's: none of the three fires, so a
+cell's button needs no `@click.stop` and a right-click on a cell link keeps
+the browser's menu. Reserve these
 events for side effects that are not navigation —
 logging, opening a drawer (though `v-model:highlighted` usually covers that
 without any handler).
@@ -3851,8 +3962,13 @@ for a preset that fits any row type (never `<any>`), not an imported
 - `loading-text` is `sr-only` — it is announced, never painted. The visible
   loading signal is the skeleton (or your `#loading` slot). It defaults to the
   localized `common.loadingText`, so an unset value still announces.
-- Row selection labels default to every cell's content inside the locale's
-  "select" template (`Select {0}`, `{0} auswählen`). `accessible-label` overrides that per row — it is called
+- Row selection labels default to the row's **name** inside the locale's
+  "select" template (`Select {0}`, `{0} auswählen`): its `rowHeader` cells,
+  else its first column ("Select INV-1041"), the same name the drag handle
+  uses. Not every cell: a name tells rows apart, and a screen reader reads the
+  other cells with their headers in table navigation. Mark the identity
+  column `rowHeader` when it is not the first (a receipt thumbnail leads).
+  `accessible-label` overrides that per row — it is called
   `(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.
@@ -3907,8 +4023,9 @@ for a preset that fits any row type (never `<any>`), not an imported
   (`role="rowheader"`), and a screen reader reading across a row, or down
   another column, announces that name with each value — "Ada Lovelace,
   ada@x.io" instead of a bare "ada@x.io". The cells look the same.
-  `accessible-label` is a different thing: it only names each row's
-  selection checkbox. The column:
+  It also names the row's selection checkbox and drag handle ("Select Ada
+  Lovelace", "Move row Ada Lovelace"); `accessible-label` overrides only the
+  checkbox. The column:
   `{ key: 'name', label: 'Name', rowHeader: true }`.
 
 - Set `item-value` so selection, expansion and highlight track rows by stable
@@ -3972,7 +4089,7 @@ for a preset that fits any row type (never `<any>`), not an imported
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `body`, `caption`, `cell`, `cellColumnHeader`, `dragHandle`, `dragIcon`, `firstRow`, `foot`, `head`, `headerRow`, `lastRow`, `root`, `row`, `selectIcon`, `sortIcon`, `table`. States: `disabled`, `empty`, `expanded`, `highlighted`, `indeterminate`, `loading`, `selected`, `sorted`, `sortedDesc`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbTableProps<Row>['pt']` (`BbTableProps['pt']` for a preset that fits any row type, never `<any>`) (`PtValue` is not exported): § Typing `pt` in `<script>`. |
-| `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`, never by position. |
+| `accessibleLabel` | `((columns: MappedCell[], item: any) => string) \| undefined` |  |  | The row's selection checkbox label, from `(columns, item)`. Unset: the row's name in the locale's select template (its `rowHeader` cells, else its first column: "Select INV-1041"). The cells arrive in render order: look one up by `key`, never by position. |
 | `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. |
@@ -3994,7 +4111,8 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `fixedLast` | `boolean \| undefined` | `false` |  | Sticks the `#<key>:last` row (a totals row) to the bottom of the scrollport. |
 | `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 `selectable`. |
 | `headerRowClass` | `Classes \| undefined` |  |  | Defines the classes to be passed to the header row. |
-| `highlighted` | `any` | `undefined` |  | Used by `v-model:highlighted`: the one row the UI is about ("the row whose details are open"), a single item value or `null`. Opt-in: bind `ref(null)`, not `ref()`; unbound or `undefined`, a row click only emits `click:row`. The row gets `aria-current="true"` and a shipped tint. |
+| `highlightable` | `boolean \| ((item: Item) => boolean) \| undefined` | `undefined` |  | Which rows a click, Enter or `toggleHighlighted` may highlight: `false` for none, or a function of the row's item. Unset: every row, when `highlighted` is bound. A value the app sets still shows on a refused row. |
+| `highlighted` | `any` | `undefined` |  | Used by `v-model:highlighted`: the one row the UI is about ("the row whose details are open"), a single item value or `null`. Opt-in: bound, a row click highlights; unbound, it only emits `click:row`. The row gets `aria-current="true"` and a shipped tint. |
 | `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` |  |  | A nested table snaps its columns to an ancestor table's tracks: `true` = the nearest ancestor, a table `id` = that ancestor (when an intermediate table has a different column count). Off by default: a nested table sizes itself. |
 | `interactiveWhileLoading` | `boolean \| undefined` | `false` |  | Keeps the header and rows interactive while loading (by default they are `inert`: a refetch is about to replace them). For background refreshes that must not interrupt an open editor. |
@@ -4013,7 +4131,7 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `perPage` | `string \| number \| undefined` |  |  | Rows per page, for `aria-rowindex` and a paired `BbPagination`. Doesn't slice `items`. Unset, an array `items` infers it from its length; an explicit value wins. Numeric strings are coerced. |
 | `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
 | `reorderable` | `boolean \| undefined` | `false` |  | Lets the user reorder the data columns: drag a header, or Shift+←/→ on a focused header. Every move writes `v-model:order`; a column panel that only writes `order` does not need it. `select` / `actions` and a custom `#thead` never move. |
-| `reorderableRows` | `boolean \| undefined` | `false` |  | Adds a grip at the start of each row: the user drags a row, or lifts it with Space / Enter and the arrow keys, and `reorder:rows` reports `{ item, from, to }`. The table never reorders `items`: splice it in the handler. |
+| `reorderableRows` | `boolean \| undefined` | `false` |  | Adds a drag handle at the start of each row: the user drags a row, or lifts it with Space / Enter and the arrow keys, and `reorder:rows` reports `{ item, from, to }`. The table never reorders `items`: splice it in the handler. |
 | `resizable` | `boolean \| undefined` | `false` |  | Lets the user resize the data columns (drag a header's trailing edge, or Alt+←/→; double-click resets). Each commit fires `resize:column(key, width)` once: write the width back into the column definition to keep it. Ignored when inheriting widths. |
 | `rowClass` | `BbTableRowClasses<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. |
@@ -4048,7 +4166,7 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `lastRow` | The row of `#<key>:last` cells, after the data rows (a totals row: `pt:lastRow="font-semibold"`). |
 | `selectIcon` | The selection glyph: each row's checkbox (radio with single selection) and the select-all checkbox — resolved per node. Not rendered when the `select` / `select:header` slots replace them. |
 | `dragIcon` | The move glyph on the chip that follows a column drag (`reorderable`). |
-| `dragHandle` | Each row's grip button (`reorderable-rows`), resolved with its row's states. A class list or an object; no per-row function. |
+| `dragHandle` | Each row's drag handle button (`reorderable-rows`), resolved with its row's states. A class list or an object; no per-row function. |
 | `foot` | The footer row group (the `tfoot` slot's container). |
 
 States are listed in precedence order: when two are on at once and their entries conflict, the later one wins.
@@ -4117,6 +4235,13 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--actions-spacing` | `.bb-table` | `8px` |  |
 | `--offset-start` | `.bb-table` | `0px` | Raw structural edge offset measured by the component (the parent's select/actions track width). Default 0 keeps every calc at its base. |
 | `--offset-end` | `.bb-table` | `0px` |  |
+| `--ig` | `.bb-table` | `0px` | Nested indent locals (see `indentAnchor` in BbTable.vue): the step lands on ONE cell's leading padding. Reset on every table so a parent's step never inherits into a child's cells; the modifier picks the anchor. |
+| `--is` | `.bb-table` | `0px` |  |
+| `--ic` | `.bb-table` | `0px` |  |
+| `--depth` | `.bb-table` | `0` | Nesting depth (0 at the root) and the parent-region floors of the own structural tracks, both set inline by the component on nested tables; declared here so a parent's values never inherit into a child. |
+| `--min-g` | `.bb-table` | `0px` |  |
+| `--min-s` | `.bb-table` | `0px` |  |
+| `--min-a` | `.bb-table` | `0px` |  |
 | `--offset-internal-start` | `.bb-table` | `var(--offset-start)` | Routing of that offset. By default it is "internal": added to the first/last cell padding and folded into the first/last column width. Swap internal↔external (set internal to 0 and external to the raw offset) to pad the whole table instead of the edge cells. |
 | `--offset-internal-end` | `.bb-table` | `var(--offset-end)` |  |
 | `--offset-external-start` | `.bb-table` | `0px` |  |

package/dist/ai/BbTimePicker.md

@@ -289,7 +289,7 @@ typeahead. Always pass a `label` when the trigger is an unlabelled cell or icon.
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile, open in a bottom off-canvas sheet instead of a floating popover. When unset, falls back to the global `config.adaptive`. |
 | `ampm` | `boolean \| undefined` | `false` |  | 12-hour display with an AM/PM column; emitted values stay 24-hour. |
 | `anchor` | `ElementOrComponentRef \| undefined` |  |  | Element or component ref the popover positions itself relative to. Defaults to the activator when omitted (anchor to a larger row while a smaller element stays the click target). |
-| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the popover within a bounding element or CSS selector. |
+| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the popover within a bounding element or CSS selector: sideways only, alongside the trigger; it flips at the viewport. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the activator and the columns. |
 | `disableFlip` | `boolean \| undefined` | `false` |  | Disable the automatic flip to the opposite side on overflow. |
 | `eager` | `boolean \| undefined` | `false` |  | Render popover content before it is first shown. |

package/dist/ai/BbTooltip.md

@@ -597,7 +597,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `panel`, `root`. States: `open`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbTooltipProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `activator` | `ElementOrComponentRef \| undefined` |  |  | External activator element or component ref. When provided, the activator slot is not rendered and event listeners are attached programmatically to the referenced element. |
 | `arrowPadding` | `number \| undefined` | `10` |  | Space the arrow will maintain to the edge of the tooltip bubble. Useful when the floating element has border radius so it won't appear broken |
-| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the tooltip within a bounding element. When provided, the tooltip will not overflow this container's bounds (e.g. a sidebar). Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
+| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the tooltip within a bounding element: it stays inside it alongside its trigger (sideways for a tooltip above or below); away from the trigger it may pass the edge, and it flips at the viewport only. Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
 | `delay` | `number \| undefined` | `100` |  | Milliseconds a pointer rests on the activator before the tooltip shows (`0`: at once). Keyboard focus shows it at once, and so does a pointer arriving while another tooltip shows or within 300 ms of one closing. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
 | `eager` | `boolean \| undefined` | `false` |  | Renders the tooltip's popover and content at mount instead of on the first open. The description screen readers hear exists from mount either way. |

package/dist/ai/CommonPopover.md

@@ -18,7 +18,7 @@
 | --- | --- | --- | --- | --- |
 | `anchor` | `any` |  |  | The element the popover positions itself relative to. Accepts an HTMLElement, a Vue component ref, or a virtual element with a `getBoundingClientRect` method. |
 | `arrowPadding` | `number \| undefined` |  |  | Space the arrow will maintain to the edge of the dropdown. Useful when the floating element has border radius so it won't appear broken |
-| `boundary` | `string \| Record<string, any> \| HTMLElement \| null \| undefined` |  |  | Constrains the popover's placement (`flip` / `shift` keep it inside); it never clamps the size, so a short boundary never collapses the bubble: use `overflowBoundary` for that. An HTMLElement, a component ref or a CSS selector. |
+| `boundary` | `string \| Record<string, any> \| HTMLElement \| null \| undefined` |  |  | Keeps the popover inside this element alongside its anchor (sideways above or below, vertically beside it); away from the anchor it may pass the edge, and only the viewport flips it. It never clamps the size (that is `overflowBoundary`). An HTMLElement, component ref or selector. |
 | `bubbleAttrs` | `Record<string, unknown> \| ((space: CommonPopoverAvailableSpace) => Record<string, unknown>) \| undefined` |  |  | Attributes bound on the bubble (`class`, `style`, `inert`, …) after its own class, so the owner can make the bubble its layout container. The function form receives the default slot's free space (for a height cap). |
 | `dialog` | `boolean \| undefined` | `false` |  | Renders the popover as a `<dialog>` element (modal overlay) instead of a `<span>` with the Popover API. |
 | `disableFlip` | `boolean \| undefined` | `false` |  | Disables the automatic flip to the opposite side when the popover would overflow (flipping is on by default). |

package/dist/ai/changelog.json

@@ -1,7 +1,7 @@
 {
 	"schemaVersion": 3,
 	"library": "bitboss-ui",
-	"version": "3.0.0-beta.51",
+	"version": "3.0.0-beta.53",
 	"upgrade": "v2-to-v3",
 	"guide": "ai/guides/migration/v2-to-v3.md",
 	"legend": {
@@ -62,7 +62,9 @@
 		"3.0.0-beta.48",
 		"3.0.0-beta.49",
 		"3.0.0-beta.50",
-		"3.0.0-beta.51"
+		"3.0.0-beta.51",
+		"3.0.0-beta.52",
+		"3.0.0-beta.53"
 	],
 	"unpublished": [
 		"3.0.0-alpha.2",
@@ -83,7 +85,7 @@
 	],
 	"summary": {
 		"renames": 220,
-		"behaviourBreaks": 188,
+		"behaviourBreaks": 193,
 		"bySurface": {
 			"prop": 15,
 			"option": 1,
@@ -5901,6 +5903,78 @@
 			"ruling": "owner 2026-10-08 (Q60.31 option B)",
 			"guide": "v2-to-v3.md § 6 item 56 + useBbFormField.md + validated-forms.md § validationMode",
 			"firstReleasedIn": "3.0.0-beta.51"
+		},
+		{
+			"id": "f328",
+			"kind": "behaviour",
+			"summary": "BbTable row events (`click:row`, `dblclick:row`, `contextmenu:row`) skip clicks on controls inside the row (select checkbox, link, button, ARIA widget); drop `@click.stop` guards",
+			"components": [
+				"BbTable"
+			],
+			"description": "BbTable: a click that starts on a control inside a row (the select checkbox, a link, a button, an input, any ARIA widget, contenteditable, [draggable]) emits no click:row, dblclick:row or contextmenu:row (they emitted for every click; the highlight already ignored them, now one rule for all, the row drag's); a click ending a text selection emits no click:row either. A cell button needs no @click.stop; a page guard on .bb-table__cell--select can go; a right-click on a cell link keeps the browser menu",
+			"ruling": "owner 2026-10-09 (progetto-32 report)",
+			"guide": "v2-to-v3.md § 6 item 57 + BbTable.guide.md § Row events",
+			"firstReleasedIn": "3.0.0-beta.52"
+		},
+		{
+			"id": "f329",
+			"kind": "behaviour",
+			"summary": "BbTable highlight is on when bound (any value; `undefined` no longer turns it off); new `highlightable` (bool or row function) gates which rows a click may highlight, app-set values still show",
+			"components": [
+				"BbTable"
+			],
+			"description": "BbTable highlight is on when BOUND (v-model:highlighted with any value, ref() included, or highlighted provided through useBbTableContext); the model's value no longer switches it (undefined was off, null on, with a dev warning for a bound undefined — gone). New highlightable (boolean | (item) => boolean; unset = on exactly when highlight is bound) gates which rows a click / Enter / toggleHighlighted may highlight; a refused row never clears the open one, and a value the app sets still shows on it. Highlightable rows get bb-table__row--highlightable and a pointer cursor. A page that kept highlight off by binding undefined moves to :highlightable=\"false\"",
+			"ruling": "owner 2026-10-09 (progetto-32, panel)",
+			"guide": "v2-to-v3.md § 6 item 58 + BbTable.guide.md § Row highlight + components/bb-table.md",
+			"firstReleasedIn": "3.0.0-beta.52"
+		},
+		{
+			"id": "f330",
+			"kind": "behaviour",
+			"summary": "Option components: a function `item-text` runs on string items (was skipped: raw codes showed); a path on a primitive keeps the primitive as text and value",
+			"components": [
+				"BbSelect",
+				"BbSelectPopover",
+				"BbCheckboxGroup",
+				"BbRadioGroup",
+				"BbSwitchGroup",
+				"BbDropdown"
+			],
+			"description": "Option surfaces (BbSelect, BbSelectPopover, BbCheckboxGroup, BbRadioGroup, BbSwitchGroup, a BbDropdown pipeline group): on a primitive item (string[], number[]) a FUNCTION item-text now runs (strings skipped it and showed the raw string, numbers ran it), and a path item-text / item-value keeps the primitive (a number blanked its text, every primitive got undefined as its value). :item-text=\"(code) => labels[code]\" over a list of codes shows the labels and keeps the codes as values",
+			"ruling": "owner 2026-10-12 (docs paragraph review)",
+			"guide": "v2-to-v3.md § 6 item 59 + options-items-playbook.md § Primitive items",
+			"firstReleasedIn": "3.0.0-beta.53"
+		},
+		{
+			"id": "f331",
+			"kind": "behaviour",
+			"summary": "Floating panels: `boundary` confines a panel sideways only; it no longer flips at the boundary edge (only the viewport flips), so a table's last-row menu opens below",
+			"components": [
+				"BbDropdown",
+				"BbPopover",
+				"BbTooltip",
+				"BbHoverCard",
+				"BbSelectPopover",
+				"BbColorPalette",
+				"BbDatePicker",
+				"BbTimePicker"
+			],
+			"description": "Floating panels (BbDropdown + v-bb-dropdown, BbPopover, BbTooltip + v-bb-tooltip, BbHoverCard, BbSelectPopover, BbColorPalette, BbDatePicker, BbTimePicker): boundary keeps the panel inside it ALONGSIDE the trigger only (sideways for a panel above or below); away from the trigger it may pass the boundary, and it flips at the viewport, never at the boundary's edge (it flipped there: a menu in a table's last rows, bounded by the table, opened above its row)",
+			"ruling": "owner 2026-10-12 (table matrix review)",
+			"guide": "v2-to-v3.md § 6 item 60 + BbPopover.guide.md § Placement, offset and boundary",
+			"firstReleasedIn": "3.0.0-beta.53"
+		},
+		{
+			"id": "f332",
+			"kind": "behaviour",
+			"summary": "BbTable row checkbox name is the row's name (rowHeader cells, else first column), not every cell; mark the identity column rowHeader when it is not first",
+			"components": [
+				"BbTable"
+			],
+			"description": "BbTable: a row's selection checkbox is named by the row's NAME, its rowHeader cells else its first column (\"Select INV-1041\"), the same name the drag grip uses; it read every cell (\"Select INV-1041 Northwind €4,200 Paid 2026-09-01 …\"). A test or e2e finding the checkbox by the long name, or by a prefix with more text after the name, matches the short one now; a table whose first column is not its identity (a thumbnail) marks the identity column rowHeader. accessible-label still overrides",
+			"ruling": "owner 2026-10-12 (table matrix review)",
+			"guide": "v2-to-v3.md § 6 item 61 + BbTable.guide.md § Accessibility",
+			"firstReleasedIn": "3.0.0-beta.53"
 		}
 	]
 }