bitboss-ui 3.0.0-beta.61 → 3.0.0-beta.63

package/dist/ai/BbTable.md

@@ -78,7 +78,9 @@ needs is declared here, not in markup:
   even when the value is nullish, so a virtual column whose `key` matches no
   field can still compute from `item`; set `formatOnNull: false` when a
   formatter must only see real values.
-- **`placeholder`** fills the cell when the pipeline still ends nullish.
+- **`placeholder`** fills the cell when the pipeline still ends nullish. Its
+  cell carries `--placeholder`, a cell with a value `--value`: style a blank
+  through those, not a slot ([Empty cells](#empty-cells-value-and-placeholder)).
 - **`align`** (`'left' | 'center' | 'right'`) per column; the table-level
   `align` prop sets the default for the whole table (`left`).
 - **`width`** freezes the column: numbers and bare numeric strings are px
@@ -88,11 +90,22 @@ needs is declared here, not in markup:
   (the table is a CSS grid — the tracks are the width API, there is no
   `table-layout`). An unfrozen text column also has a **floor estimated from
   what it shows**: short values (IDs, emails, dates) ask for one line, prose
-  for about three, fitted to the room the sized columns leave — short values
-  give way first and wrap, prose keeps at least half its width, and only then
-  does the table scroll sideways. The header is always part of that floor, so
-  a heading never clips. No floor on `fixed` or `virtual` tables, slot
-  columns, or under a custom `#thead`. A grid keyword or function is the track as written:
+  for about three, fitted to the room the sized columns leave. Values a line
+  break would harm stay whole: a short name or status ("Poltrona 10", "In
+  attesa di verifica"), an amount with its currency, a range or pair ("0,00 € /
+  450,00 €"), a date or code ("16/10/2026", a grouped IBAN). When room runs
+  short, longer values wrap first, then prose narrows, then a long heading of
+  several words takes two lines; a table that scrolls sideways anyway keeps
+  all of those whole. Only a table that would otherwise _start_ scrolling
+  wraps them, and long-form text never runs wider than a readable measure.
+  You rarely need `whitespace-nowrap` in a `td-class`. The header is always
+  part of that floor, so a heading never clips. (On a server-rendered page
+  the server cannot know the width: a table whose headings need two lines
+  takes them, once, when the page hydrates.) The floors read every row up
+  to 2,000; past that, the first 1,000 and a sample across the rest (a
+  `virtual` table has no floors at all). No floor on `fixed` or
+  `virtual` tables, slot columns, or under a custom `#thead`, so never slot a
+  column only to restyle its blank: use [`--placeholder`](#empty-cells-value-and-placeholder). A grid keyword or function is the track as written:
   `'auto'`, `'2fr'`, `'minmax(0, 1fr)'` (a share that may shrink below its
   content), `'fit-content(200px)'`. When _every_ column declares a length, the
   lengths become floors and the surplus is shared in proportion to their
@@ -354,7 +367,9 @@ not sure — write the name through the function instead of by hand:
 `#[slotKey('Qualità')]`, with `import { slotKey } from 'bitboss-ui'`; the same
 goes for slot names built in code (columns from config, a dynamic `<template>`
 loop). A hand copy that differs by one character makes the slot silently never
-match; `bitboss-ui check` catches it when `columns` is in the same file. Keep the column in `columns`
+match; `bitboss-ui check` catches it when `columns` is in the same file, and
+warns on a loop over keys it cannot see (`#[column.key]` over a prop) until
+the name goes through `slotKey`. Keep the column in `columns`
 even when you fully slot it: label, alignment and width still come from there.
 
 Body cell scope: `content` (the formatted value), `item` (raw row), `value`
@@ -692,7 +707,9 @@ empty the table shows its empty row — localized default text, overridable via
 `empty-text` or fully via the `#empty` slot. That slot fills the table's own
 full-width empty-state cell (already centred, already spanning every column),
 so pass the content — a message, a "clear filters" button — not a row of your
-own.
+own. On a table that scrolls sideways (wide columns at phone width) the
+content centres in the visible part, not on the whole grid, and stays there
+as the table scrolls.
 
 `loading-text` is the loading row's `aria-live` announcement. Like
 `empty-text` it has a **localized default** (`common.loadingText` —
@@ -1096,13 +1113,19 @@ scriptable from anywhere via `useBbTableContext`
 Mark columns `sortable` and bind `v-model:sort` — an ordered
 `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**
-(client-side, as below) or forward it to the server as `orderBy` and refetch
-via `dependencies`.
+button is the keyboard/AT control), or Enter on it, sorts by **that column
+alone**, cycling it unsorted → asc → desc → removed (`[]`).
+
+**Shift+click** (or Shift+Enter) adds the column instead: it joins the end of
+the model, a direction flip updates its entry in place (it keeps its priority)
+and its third click removes it alone; the other entries are never touched. Set
+`multi-sort` when a plain click should add too. The array order **is** the
+priority: first entry sorts first. A several-entry model you write yourself
+is shown as is in either mode; the next plain click replaces it.
+
+The table only reports the model; **apply it to your data** (client-side, as
+below) or forward it to the server as `orderBy` and refetch via
+`dependencies`.
 
 The affordance is one arrow: nothing at rest, a faint arrow previewed while
 the header is hovered or focused, solid once the column is sorted (up for
@@ -1114,9 +1137,9 @@ third click.
 ```vue
 <template>
 	<div class="flex max-w-2xl flex-col gap-1.5">
-		<!-- Mark columns `sortable` and bind `v-model:sort`. The header buttons
-		     cycle asc → desc → off; the table only REPORTS the model — you sort
-		     the data. -->
+		<!-- Mark columns `sortable` and bind `v-model:sort`. A click sorts by
+		     that column (asc → desc → off), Shift+click adds it; the table only
+		     REPORTS the model — you sort the data. -->
 		<div
 			class="overflow-hidden rounded-(--bb-radius) border border-(--bb-border)"
 		>
@@ -1189,7 +1212,9 @@ 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
+(render your own button with `@click="toggleSort"`: given the event, Shift adds
+the column like on the built-in header; `toggleSort()` with no event sorts by
+that column alone). To merely add something next
 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`
@@ -1211,7 +1236,8 @@ it **renders** in — an array of column keys, the same split as `sortable` +
   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.
+  (Shift+Home/End to the ends), Enter sorts a sortable header (Shift+Enter
+  adds it to the sort).
   Each committed move writes the model once and is announced.
 
 The model's contract is what makes a column panel trivial:
@@ -2014,6 +2040,33 @@ fixed first track).
 The actions-column toggle remains valid — prefer it when expansion reveals
 _detail about the row_ rather than _children of it_.
 
+#### Styling the detail area
+
+The cell that holds `#expand` (it spans every column) is the `expand`
+passthrough part. It has no padding of its own, so the slot's content sits
+flush; give the area a surface or an inset there:
+
+```vue
+<BbTable
+	v-model:expanded-items="open"
+	:columns="columns"
+	:items="invoices"
+	item-value="id"
+	pt:expand="bg-(--bb-surface-hover) px-4 py-3"
+	pt:expand:highlighted="bg-(--bb-muted)"
+>
+	<template #expand="{ item }">…</template>
+</BbTable>
+```
+
+It takes the data row's `selected`, `highlighted` and `expanded` (always
+on), and, like `pt:row`, a
+per-item function: `:pt:expand="({ item }) => item.overdue && 'bg-red-50'"`.
+It is not a `cell`, so `pt:cell` never reaches it: a table that moves its row
+rules off the cells (`pt:cell="border-b-0"`, a top rule on `pt:row`) takes
+the expand cell's off too (`pt:expand="border-b-0"`), or the line under each
+open row is drawn twice.
+
 ### Reordering rows
 
 `reorderable-rows` adds a slim drag handle at the start of every row: the user drags
@@ -2214,10 +2267,12 @@ keeps until that column's `width` changes:
 - A resized width is always px; `width` still accepts `'20%'` / `'12rem'`
   for what you declare yourself.
 
-Headers never wrap. A column you have not sized is never narrower than its
-own heading — the label is the table's size hint, so an empty or slim column
-with a long heading still reads on a narrow screen (the table overflows
-instead). Once a track is a length (a declared `width`, a user resize) the
+Headers stay on one line. A column you have not sized is never narrower
+than its own heading — the label is the table's size hint, so an empty or
+slim column with a long heading still reads on a narrow screen. The one
+exception: a long heading of several words ("Numero e data emissione") takes
+two lines when the alternative is the table scrolling sideways; short
+headings never do, and no `pt` class is needed for it. Once a track is a length (a declared `width`, a user resize) the
 label cannot widen it: squeezed, it 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
@@ -3312,7 +3367,7 @@ const columns = [
 ];
 ```
 
-Three rules:
+Four 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
@@ -3327,6 +3382,15 @@ Three rules:
 - **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).
+- **Pinned cells sit at `z-index: 2`.** Body and header cells alike; under
+  `fixed-headers` the stuck header band and its pinned headers sit at `3`,
+  and so do the `fixed-first` / `fixed-last` rows; column resize handles sit
+  at `1`. Cell content that sets its own `z-index` (a positioned badge with
+  `z-10`, say) paints over the pinned column as it scrolls under it: keep
+  such content at `z-index: 1` or lower, or put `isolate` on its wrapper so
+  its layers stay inside it. The table root opens no stacking context of
+  its own, so these values also count against the page: a sticky app bar
+  that a scrolled table must pass under needs `z-index: 4` or more.
 
 ### Virtual rows
 
@@ -3468,6 +3532,60 @@ root (`--cue-w: 0px` turns it off):
 }
 ```
 
+#### Empty cells: `--value` and `--placeholder`
+
+Every data cell says what the column's pipeline (`formatter`, then
+`placeholder`) produced: **`bb-table__cell--value`** when it shows a value,
+**`bb-table__cell--placeholder`** when the value was empty and the
+column's `placeholder` shows instead. The same two are `pt` states on
+`cell`. The class names the outcome, not the text, so a placeholder can read
+"–", "N/D" or anything else and the styling holds. A cell whose value is empty
+with no `placeholder` has neither. Slot cells carry it too (the class follows
+the `content` the slot is handed); the select, drag and actions cells never
+do.
+
+```vue
+<script setup lang="ts">
+import { BbTable, type BbTableColumn } from 'bitboss-ui';
+
+type Person = { id: number; name: string; email: string | null; city: string };
+
+const blank = (value: unknown) =>
+	typeof value === 'string' && value.trim() === '' ? null : value;
+
+const columns: Array<BbTableColumn<Person>> = [
+	{ key: 'name', label: 'Nome' },
+	{ key: 'email', label: 'Email', placeholder: 'N/D' },
+	{ key: 'city', label: 'Provincia', placeholder: '–', formatter: blank },
+];
+
+const people: Person[] = [
+	{ id: 1, name: 'Giulia Bianchi', email: null, city: 'Milano' },
+	{ id: 2, name: 'Marco Rossi', email: 'marco@example.com', city: '  ' },
+];
+</script>
+
+<template>
+	<BbTable
+		:columns="columns"
+		item-value="id"
+		:items="people"
+		pt:cell:placeholder="text-(--bb-text-muted)"
+	/>
+</template>
+```
+
+Or in CSS, once for the whole app:
+`.bb-table__cell--placeholder { color: var(--bb-text-muted); }`.
+
+- **The placeholder shows only for `null` / `undefined`.** An empty or
+  whitespace-only string is a value. To treat it as blank, return `null` from
+  the `formatter` (`blank` above), and the placeholder takes over.
+- **Don't slot a column just to restyle its blank.** A slot column gets no
+  width floor (see Columns), so a wrapper that slots every column to print a
+  muted dash costs every column its floor. `placeholder` plus the class does
+  the same with none of that.
+
 #### The table as a card
 
 The root paints no background, border or radius of its own — it is the
@@ -3517,7 +3635,7 @@ through element names, which match nothing:
 | header cell      | `.bb-table__cell-column-header` (+ `--select`, `--actions`)                                                                                                                          | `columnheader`                                 |
 | body group       | `.bb-table__body`                                                                                                                                                                    | `rowgroup`                                     |
 | data row         | `.bb-table__row` (+ `--highlighted`)                                                                                                                                                 | `row`                                          |
-| data cell        | `.bb-table__cell` (+ `--select`)                                                                                                                                                     | `cell` (`gridcell` with `keyboard-navigation`) |
+| data cell        | `.bb-table__cell` (+ `--select`; `--value` / `--placeholder`: what the pipeline produced)                                                                                            | `cell` (`gridcell` with `keyboard-navigation`) |
 | actions cell     | `.bb-table__cell--actions`                                                                                                                                                           | `cell` (`gridcell` with `keyboard-navigation`) |
 | expand row       | `.bb-table-expand__row` > `.bb-table-expand__cell`                                                                                                                                   | `row` > `cell` (`gridcell`)                    |
 | empty state      | `.bb-table-empty__row` > `.bb-table-empty__cell`                                                                                                                                     | `row` > `cell`                                 |
@@ -3652,21 +3770,25 @@ object form, a style and attributes — optionally only while a state is on.
 Parts: `root` (the container), `caption` (the visible caption), `table` (the
 grid), `head` / `body` / `foot` (the row groups), `header-row`,
 `cell-column-header` (every header cell — the select and actions ones
-included, a broadcast), `row` (every DATA row, a broadcast) and `cell` (every
-data cell — the select and actions cells included, a broadcast), and three
-glyphs: `sort-icon`, `select-icon` (each row's checkbox or radio and the
-select-all) and `drag-icon` (on the chip a column drag carries). The grid is
-`div`s with ARIA roles, so these are parts, not `th` / `td` selectors.
-
-States: `loading` and `empty` (the table); `selected`, `highlighted`,
+included, a broadcast), `row` (every DATA row, a broadcast), `cell` (every
+data cell — the select and actions cells included, a broadcast), `expand`
+(the cell holding an open row's `#expand`), `first-row` / `last-row` (the
+edge rows), `drag-handle` (each row's grip under `reorderable-rows`), and
+three glyphs: `sort-icon`, `select-icon` (each row's checkbox or radio and
+the select-all) and `drag-icon` (on the chip a column drag carries). The grid
+is `div`s with ARIA roles, so these are parts, not `th` / `td` selectors.
+
+States: `loading` and `empty` (the table); `value` / `placeholder` per data
+cell (what its pipeline produced, see [Empty cells](#empty-cells-value-and-placeholder)); `selected`, `highlighted`,
 `expanded` and `disabled` resolved per row — a cell takes its row's states,
-and a row's `select-icon` its `selected` / `disabled`; `sorted` /
+a row's `select-icon` its `selected` / `disabled`, and its `expand` its
+`selected` / `highlighted` / `expanded`; `sorted` /
 `sorted-desc` per header, on its cell and its `sort-icon`; `indeterminate` on
 the select-all glyph. **`disabled` means the row cannot be selected**
 (`selectable` rejects it, or the table is `disabled`): the row still clicks,
-highlights and expands, and a table without selection never has it. Expand
-rows, the empty row and the skeleton are not parts — `pt:row:expanded` and
-`pt:body:empty` cover the usual asks.
+highlights and expands, and a table without selection never has it. The
+empty row and the skeleton are not parts — `pt:body:empty` covers the usual
+ask.
 
 The selectable invoices table above, restyled through those parts: muted
 type on `pt:head`, weight on `pt:row:selected` (Globex is checked), a muted
@@ -3843,8 +3965,9 @@ A value that depends on the ITEM — a danger wash on overdue rows — is a
 **per-item function** on `pt:row`: `({ item, highlighted }) => …`, called
 with the row's item and every state as a boolean for it, its result merged after the
 state entries (so the overdue wash below steps aside while the row is
-highlighted). `rowClass` still works and is computed once per row rather than
-per render; `pt:cell` takes no function (`tdClass` is the per-cell hook).
+highlighted). `pt:expand` takes one the same way. `rowClass` still works and
+is computed once per row rather than per render; `pt:cell` takes no function
+(`tdClass` is the per-cell hook).
 
 **pt:row as a function — overdue invoices washed by status**
 
@@ -4048,7 +4171,13 @@ for a preset that fits any row type (never `<any>`), not an imported
 - Set `item-value` so selection, expansion and highlight track rows by stable
   identity rather than object reference.
 - Sortable headers set `aria-sort` and render real buttons; custom header
-  slots should keep a button calling `toggleSort`.
+  slots should keep a button calling `toggleSort`. Enter sorts by the column
+  alone and **Shift+Enter adds it** to a multi-column sort. The sortable
+  header's accessible description says so (on the sort button, or on the
+  header cell when the header row is a keyboard surface, after the
+  reorder / resize instructions); with `multi-sort` there is no hint, since a
+  plain Enter adds. A custom `#<key>:header` button carries no hint: describe
+  it yourself if it should.
 - **The role follows the keyboard.** A plain table is `role="table"` with
   `cell`s. `keyboard-navigation` makes it `role="grid"` (the APG data grid:
   one tab stop, cell focus, `gridcell`s, `aria-selected` on selectable rows
@@ -4105,7 +4234,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>`. |
+| `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`, `expand`, `firstRow`, `foot`, `head`, `headerRow`, `lastRow`, `root`, `row`, `selectIcon`, `sortIcon`, `table`. States: `disabled`, `empty`, `expanded`, `highlighted`, `indeterminate`, `loading`, `placeholder`, `selected`, `sorted`, `sortedDesc`, `value`. 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` |  |  | The label of each row's selection checkbox, 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. |
@@ -4142,6 +4271,7 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `max` | `number \| undefined` | `Infinity` |  | Maximum number of items that can be selected. |
 | `modelValue` | `any` | `[]` |  | Used by v-model. Can be any serializable type. |
 | `multiple` | `boolean \| undefined` | `true` |  | Allows the selection of multiple items. |
+| `multiSort` | `boolean \| undefined` | `false` |  | A plain click on a sortable header adds the column to the sort, as Shift+click always does. Off, a plain click makes the sort that column alone. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
 | `order` | `string[] \| undefined` | `[]` |  | Used by `v-model:order`: the column keys in render order. Columns it omits follow in declaration order; unknown keys stay put. A `reorderable` move writes it back complete. Works unbound, like `sort`; never holds `select` / `actions`. |
 | `page` | `string \| number \| undefined` |  |  | Current page (from 1), for the rows' `aria-rowindex` and a `BbPagination` paired through `id`. Doesn't slice `items`: pass the current page's rows. Numeric strings are coerced. |
@@ -4177,8 +4307,9 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `cellColumnHeader` | Every column header cell (`role="columnheader"`), the select and actions headers included — a broadcast resolved per header. Not a `<th>`: the grid is `div`s with ARIA roles. |
 | `sortIcon` | A sortable column's sort arrow, resolved per header. |
 | `body` | The body row group. |
-| `row` | Every DATA row — a broadcast resolved per row. Expand rows and the skeleton are not parts. Also takes a per-item function, called with the row's raw item, once per rendered row: keep it cheap. |
+| `row` | Every DATA row — a broadcast resolved per row. The skeleton is not a part, and an expand row is styled through `expand`. Also takes a per-item function, called with the row's raw item, once per rendered row: keep it cheap. |
 | `cell` | Every data cell, the select and actions cells included — a broadcast resolved with its row's states (`role="cell"`, `gridcell` under `keyboardNavigation`) — and the cells of the `firstRow` / `lastRow`, with no row state. Takes no function: use `tdClass` for a per-cell hook. |
+| `expand` | The cell under an open row that holds the `#expand` slot and spans every column — resolved with its data row's `selected`, `highlighted` and `expanded` (always on: the cell exists only while its row is open). Not a `cell`, so `pt:cell` never reaches it: a rule taken off the cells (`pt:cell="border-b-0"`) needs `pt:expand="border-b-0"` too. Also takes a per-item function, called with the open row's raw item. |
 | `firstRow` | The row of `#<key>:first` cells, before the data rows. |
 | `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. |
@@ -4190,14 +4321,16 @@ States are listed in precedence order: when two are on at once and their entries
 
 | State | When it is on |
 | --- | --- |
+| `value` | Per node, on a DATA `cell`: the formatter / placeholder pipeline produced a value (not `null` / `undefined`), slot cells included (`bb-table__cell--value`). Not on the select, drag or actions cells. |
+| `placeholder` | Per node, on a DATA `cell`: the value was empty and the column's `placeholder` shows instead, whatever its text (`bb-table__cell--placeholder`). A cell with an empty value and no `placeholder` has neither state. |
 | `empty` | Component-wide: there are no rows (`bb-table--empty`). |
 | `sorted` | Per node, on `cellColumnHeader` and `sortIcon`: the column is sorted, either direction (`bb-table__cell-column-header--sorted`). |
 | `sortedDesc` | Per node, on `cellColumnHeader` and `sortIcon`: sorted descending (`bb-table__cell-column-header--sorted-desc`). Ascending is `sorted` alone. |
-| `selected` | Per node, on `row`, its cells and its `selectIcon`: a checked row; on the select-all glyph, every row is selected. |
+| `selected` | Per node, on `row`, its cells, its `expand` and its `selectIcon`: a checked row; on the select-all glyph, every row is selected. |
 | `indeterminate` | Per node, on the select-all `selectIcon`: some rows are selected, not all. |
 | `disabled` | Per node, on `row`, its cells and its `selectIcon`: the row cannot be SELECTED — `selectable` rejects it, or the table is `disabled` (`bb-table__row--disabled`). It still clicks, highlights and expands. Never on a table without selection. The select-all glyph takes it from the table's `disabled`. |
-| `expanded` | Per node, on `row` and its cells: the row's expand row is open (`bb-table__row--expanded`). |
-| `highlighted` | Per node, on `row` and its cells: the highlighted row. |
+| `expanded` | Per node, on `row`, its cells and its `expand`: the row's expand row is open (`bb-table__row--expanded`). |
+| `highlighted` | Per node, on `row`, its cells and its `expand`: the highlighted row. |
 | `loading` | Component-wide: the table is `loading`. |
 
 ## Events
@@ -4224,8 +4357,8 @@ States are listed in precedence order: when two are on at once and their entries
 - `actions:header` — scope: `{ text: string; }` — Replaces the default actions header cell content.
 - `empty` — scope: `{ error: unknown; }` — Content shown when there are no rows and nothing is loading, inside the table's own full-width cell: pass content, never a row. `error` is what the latest failed load threw (`null` when none).
 - `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:append` — scope: `BbTableHeaderAffixSlotProps<Item>` `{ classes?: Classes; columnKey: string; items?: Item[]; label?: string; sortable?: boolean; sortOrder?: "asc" \| "desc" \| null; toggleSort?: (() => void); hideColumn?: (() => void) }` — Content after every data column's header content (the label + sort control, or its own `<key>:header` replacement). A column's `<key>:header:append` wins over this for that column; they never stack. Branch on `columnKey` for per-column output.
-- `header:prepend` — scope: `BbTableHeaderAffixSlotProps<Item>` `{ classes?: Classes; columnKey: string; items?: Item[]; label?: string; sortable?: boolean; sortOrder?: "asc" \| "desc" \| null; toggleSort?: (() => void); hideColumn?: (() => void) }` — Content before every data column's header content (the label + sort control, or its own `<key>:header` replacement). A column's `<key>:header:prepend` wins over this for that column; they never stack. Branch on `columnKey` for per-column output.
+- `header:append` — scope: `BbTableHeaderAffixSlotProps<Item>` `{ classes?: Classes; columnKey: string; items?: Item[]; label?: string; sortable?: boolean; sortOrder?: "asc" \| "desc" \| null; toggleSort?: ((event?: MouseEvent \| KeyboardEvent \| undefined) => void); hideColumn?: (() => void) }` — Content after every data column's header content (the label + sort control, or its own `<key>:header` replacement). A column's `<key>:header:append` wins over this for that column; they never stack. Branch on `columnKey` for per-column output.
+- `header:prepend` — scope: `BbTableHeaderAffixSlotProps<Item>` `{ classes?: Classes; columnKey: string; items?: Item[]; label?: string; sortable?: boolean; sortOrder?: "asc" \| "desc" \| null; toggleSort?: ((event?: MouseEvent \| KeyboardEvent \| undefined) => void); hideColumn?: (() => void) }` — Content before every data column's header content (the label + sort control, or its own `<key>:header` replacement). A column's `<key>:header:prepend` wins over this for that column; they never stack. Branch on `columnKey` for per-column output.
 - `loading` — scope: `{ items: Item[]; }` — Content shown while table rows are loading (replaces the skeleton rows).
 - `select` — scope: `{ item: Item; value: any; checked: boolean; disabled: boolean; inputName: string; readonly: boolean; toggleSelected?: (() => void) \| undefined; }` — Replaces the default checkbox/radio in the selection cell for each row.
 - `select:header` — scope: `{ multiple: boolean; selectAll: boolean; text: string; }` — Replaces the default selection header cell content (checkbox or radio label).

package/dist/ai/BbToast.md

@@ -191,7 +191,8 @@ Three things worth internalising:
 
 #### Variant icons
 
-The object form of the plugin's `toastVariants` sets each variant's icon for
+A default icon per variant, set once: the object form of the plugin's
+`toastVariants` option sets each variant's icon for
 the whole app. A toast without its own `icon` uses its variant's; its own
 `icon` wins; `hideIcon: true` hides either (and does nothing when there is no
 icon). The loading spinner still shows with `hideIcon`: it is state, not

package/dist/ai/changelog.json

@@ -1,7 +1,7 @@
 {
 	"schemaVersion": 3,
 	"library": "bitboss-ui",
-	"version": "3.0.0-beta.61",
+	"version": "3.0.0-beta.63",
 	"upgrade": "v2-to-v3",
 	"guide": "ai/guides/migration/v2-to-v3.md",
 	"legend": {
@@ -71,7 +71,9 @@
 		"3.0.0-beta.58",
 		"3.0.0-beta.59",
 		"3.0.0-beta.60",
-		"3.0.0-beta.61"
+		"3.0.0-beta.61",
+		"3.0.0-beta.62",
+		"3.0.0-beta.63"
 	],
 	"unpublished": [
 		"3.0.0-alpha.2",
@@ -94,7 +96,7 @@
 	],
 	"summary": {
 		"renames": 220,
-		"behaviourBreaks": 228,
+		"behaviourBreaks": 231,
 		"bySurface": {
 			"prop": 15,
 			"option": 1,
@@ -105,7 +107,7 @@
 			"class": 138
 		},
 		"unreleased": 0,
-		"added": 409
+		"added": 416
 	},
 	"added": {
 		"3.0.0-alpha.1": [
@@ -2067,6 +2069,33 @@
 					"BbSelectPopover"
 				]
 			}
+		],
+		"3.0.0-beta.62": [
+			{
+				"text": "bbtable · pt:expand part for the expand cell",
+				"components": [
+					"BbTable"
+				]
+			},
+			"table · single sort by default, shift+click adds",
+			{
+				"text": "check · warn on computed slot names that skip slotKey",
+				"components": [
+					"BbTable"
+				]
+			},
+			"table · keep short multi-word values on one line",
+			"table · sortable headers describe shift+enter"
+		],
+		"3.0.0-beta.63": [
+			"table · cells name what the pipeline produced, value or placeholder",
+			{
+				"text": "confirm · every confirm() call opens its own dialog",
+				"components": [
+					"BbHost",
+					"BbPtScope"
+				]
+			}
 		]
 	},
 	"breaking": [
@@ -8445,6 +8474,43 @@
 			"ruling": "owner 2026-10-16 (Q75.1 R7 reading b, R2, G4, G5, G7)",
 			"guide": "v2-to-v3.md § 6 item 94 + BbSelect.md § Rows the form already holds",
 			"firstReleasedIn": "3.0.0-beta.59"
+		},
+		{
+			"id": "f368",
+			"kind": "behaviour",
+			"summary": "BbTable: a plain header click sorts by that column alone; Shift+click adds a column; multi-sort makes a plain click add",
+			"components": [
+				"BbTable"
+			],
+			"description": "BbTable sorts by ONE column by default: a plain click (or Enter / Space) on a sortable header makes v-model:sort that column alone at its next state (unsorted → asc → desc → []); Shift+click / Shift+Enter adds the column or cycles it in place, leaving the other entries (a plain click's old behaviour). multi-sort (new, default false) makes a plain click add too. The model's shape is unchanged and a several-entry model written from outside is shown as is (the next plain click replaces it). The header slots' toggleSort takes the event (@click=\"toggleSort\" gets Shift); toggleSort() sorts single. Tables that want click-adds set multi-sort",
+			"ruling": "owner 2026-10-21 (Q76.9 b)",
+			"guide": "v2-to-v3.md § 6 item 95 + BbTable.md § Sorting",
+			"firstReleasedIn": "3.0.0-beta.62"
+		},
+		{
+			"id": "f369",
+			"kind": "behaviour",
+			"summary": "BbTable: unsized text columns keep names, statuses, amounts, ranges, dates and codes on one line; a long heading may take two lines instead of a sideways scroll",
+			"components": [
+				"BbTable"
+			],
+			"description": "BbTable: an unsized text column keeps the values a line break would harm on ONE line (short names and statuses, an amount with its currency, a pair or range, a spelled-out date, a code or IBAN; voted by a five-lens panel on a 392-value corpus, widthCorpus.*.json), and a table that scrolls sideways anyway no longer squeezes them. A table that fitted before still fits: only then do those values give way. A long heading of several words takes two lines when the alternative is a sideways scroll (--wrap, Q76.9 e); short headings never wrap, and the pt:cell-column-header=\"whitespace-normal\" workaround is no longer needed. The floors are converted at the body text's size (they used the table root's 16px, ~14% wide), and structural columns (drag handle, selection, actions) no longer count as room. Unsized columns change width (wider for units, narrower otherwise)",
+			"ruling": "owner 2026-10-16 (Q75.3) + 2026-10-21 (Q76.9 e)",
+			"guide": "v2-to-v3.md § 6 item 96 + BbTable.md § Columns, § Column resize",
+			"firstReleasedIn": "3.0.0-beta.62"
+		},
+		{
+			"id": "f370",
+			"kind": "behaviour",
+			"summary": "confirm(): every call opens its own dialog; a new one covers the open one instead of resolving it false; it takes the caller's pt scope; new stack option",
+			"components": [
+				"BbConfirm",
+				"BbHost"
+			],
+			"description": "confirm(): every call opens its own dialog, under the caller's provides. A call while another confirm is open COVERS it (a shared confirm BbDialog stack) instead of resolving it false: the first stays pending and comes back when the newer one closes, so two un-awaited calls ask both, newest first; Escape and the backdrop answer only the top one. close() hides the newest open confirm opened through the same useConfirm() (it used to hide THE confirm); dismissAll() dismisses every open one. The dialog takes the <BbPtScope> and tokens of the component that called useConfirm() (a store's: the host's), so areas need no host of their own for confirms; a component portal injects from the caller's tree. New message option stack (join a dialog's stack: the confirm replaces its view)",
+			"ruling": "owner 2026-10-22 (Q75.9)",
+			"guide": "v2-to-v3.md § 6 item 97 + components/use-confirm.md + components/bb-host.md + BbConfirm.md § Several confirms at once + useConfirm.md",
+			"firstReleasedIn": "3.0.0-beta.63"
 		}
 	]
 }