bitboss-ui 3.0.0-beta.60 → 3.0.0-beta.62

package/bin/bitboss-ui-mcp.mjs

@@ -1923,9 +1923,17 @@ let cachedDocIndex = null;
 function docIndex() {
 	if (cachedDocIndex) return cachedDocIndex;
 	const entries = [];
-	const addSections = (source, markdown, read) => {
+	// What a document says before its first `##` (its lead), and then every
+	// section. The lead used to be skipped, and a composable was cut at 4000
+	// chars: useToast's object-form row sat past the cut (2026-10-20).
+	// `check-mcp` walks dist/ai and fails on any doc unit left out of here.
+	const addSections = (source, markdown, read, lead, skip = () => false) => {
+		const intro = stripFrontmatter(markdown).split(/^## /m)[0].trim();
+		if (lead && intro.length >= 40)
+			entries.push({ source, ...lead, text: intro });
 		for (const section of splitSections(markdown)) {
-			if (section.own.length < 40) continue;
+			// `skip` first: it tracks the `##` it is under, even a bare one.
+			if (skip(section) || section.own.length < 40) continue;
 			entries.push({
 				source,
 				section: section.title,
@@ -1936,13 +1944,18 @@ function docIndex() {
 	};
 	const guidesDir = join(AI_ROOT, 'guides');
 	for (const path of collectGuidePaths(guidesDir)) {
+		const markdown = readFileSync(join(guidesDir, path), 'utf-8');
 		addSections(
 			`guide ${path}`,
-			readFileSync(join(guidesDir, path), 'utf-8'),
+			markdown,
 			(title) => ({
 				tool: 'get_guide',
 				args: { name: path, sections: [title] },
-			})
+			}),
+			{
+				section: frontmatter(markdown).title ?? path,
+				read: { tool: 'get_guide', args: { name: path } },
+			}
 		);
 	}
 	const composablesDir = join(AI_ROOT, 'composables');
@@ -1952,16 +1965,22 @@ function docIndex() {
 		)) {
 			const markdown = readFileSync(join(composablesDir, file), 'utf-8');
 			const name = file.slice(0, -3);
-			entries.push({
-				source: `composable ${name}`,
-				section: frontmatter(markdown).summary ?? name,
-				text: stripFrontmatter(markdown).slice(0, 4000),
-				read: { tool: 'get_composable', args: { name } },
-			});
+			addSections(
+				`composable ${name}`,
+				markdown,
+				(title) => ({
+					tool: 'get_composable',
+					args: { name, sections: [title] },
+				}),
+				{
+					section: frontmatter(markdown).summary ?? name,
+					read: { tool: 'get_composable', args: { name } },
+				}
+			);
 		}
 	}
 	const manifest = loadComponentsManifest();
-	for (const component of manifest.components.filter((c) => !c.referenceOnly)) {
+	for (const component of manifest.components) {
 		const path = join(PACKAGE_ROOT, 'dist', component.contract ?? '');
 		if (component.contract && existsSync(path)) {
 			for (const section of contractGuideSections(
@@ -1979,6 +1998,11 @@ function docIndex() {
 				});
 			}
 		}
+		// BbToast and BbConfirm are reference-only (a composable drives them)
+		// but their guides are the docs: § Variant icons never ranked
+		// (progetto-32, 2026-10-20). Internals have no guide, so nothing else
+		// comes in; their props stay out.
+		if (component.referenceOnly) continue;
 		for (const prop of component.props) {
 			if (prop.name.startsWith('pt')) continue;
 			entries.push({
@@ -2003,6 +2027,45 @@ function docIndex() {
 				},
 			});
 		}
+		// Slots, v-models and pt parts / states: `members` serves each row, and
+		// "BbSelect option slot" had nothing to find.
+		const member = (section, text, name) =>
+			entries.push({
+				source: `component ${component.name}`,
+				section,
+				text,
+				read: {
+					tool: 'get_component',
+					args: { name: component.name, members: [name] },
+				},
+			});
+		for (const slot of component.slots ?? [])
+			member(
+				`slot #${slot.name}`,
+				`#${slot.name} slot. ${slot.description ?? ''}`,
+				`#${slot.name}`
+			);
+		for (const model of component.models ?? []) {
+			const name =
+				model.name === 'modelValue' ? 'v-model' : `v-model:${model.name}`;
+			member(
+				name,
+				`${name}: ${model.type ?? ''}. ${model.description ?? ''}`,
+				name
+			);
+		}
+		for (const part of component.pt?.parts ?? [])
+			member(
+				`pt part ${part.name}`,
+				`pt:${part.name} part. ${part.description ?? ''}`,
+				`pt:${part.name}`
+			);
+		for (const state of component.pt?.states ?? [])
+			member(
+				`pt state ${state.name}`,
+				`pt state ${state.name}. ${state.description ?? ''}`,
+				`pt:${state.name}`
+			);
 		/*
 		 * The rename registry: an agent upgrading an app searches the OLD name
 		 * (`enabled-while-loading`, `pt:input`, `#no-data`), which no current
@@ -2053,6 +2116,22 @@ function docIndex() {
 				text: frontmatter(markdown).summary ?? name,
 				read: { tool: 'get_recipe', args: { platform, name } },
 			});
+			// The prose sections; the code files under "The code" are `files`.
+			let inCode = false;
+			addSections(
+				`recipe ${platform}/${name}`,
+				markdown,
+				(title) => ({
+					tool: 'get_recipe',
+					args: { platform, name, sections: [title] },
+				}),
+				null,
+				(section) => {
+					if (section.level === 2)
+						inCode = /^the (code|files)\b/i.test(section.title);
+					return inCode;
+				}
+			);
 		}
 	}
 	// Class renames (the sweep map rows of changelog.json): an app's
@@ -2151,10 +2230,18 @@ function docIndex() {
 	if (existsSync(readme)) {
 		// Served by get_guide under the name 'README' (it used to point at a
 		// "read file" call, which is not a tool).
-		addSections('README', readFileSync(readme, 'utf-8'), (title) => ({
-			tool: 'get_guide',
-			args: { name: 'README', sections: [title] },
-		}));
+		addSections(
+			'README',
+			readFileSync(readme, 'utf-8'),
+			(title) => ({
+				tool: 'get_guide',
+				args: { name: 'README', sections: [title] },
+			}),
+			{
+				section: 'README',
+				read: { tool: 'get_guide', args: { name: 'README' } },
+			}
+		);
 	}
 	cachedDocIndex = entries;
 	return entries;
@@ -3341,6 +3428,7 @@ export {
 	SERVER_INSTRUCTIONS,
 	searchComponents,
 	searchDocs,
+	docIndex,
 	getComposable,
 	getComponent,
 	listTokens,

package/bin/bitboss-ui.mjs

@@ -1735,7 +1735,9 @@ Commands:
                       \`warnings[]\` (never fail the run) use the same shape with
                       \`severity: "warning"\`: \`likely-squashed-slot\` (a slot
                       name that looks like a camelCase key squashed, e.g.
-                      \`#createdat\`), \`local-bb-component\` (your own
+                      \`#createdat\`), \`computed-slot-key\` (a computed slot
+                      name over keys \`check\` cannot see, not spelled
+                      through \`slotKey(…)\`), \`local-bb-component\` (your own
                       component uses the \`Bb\` prefix; rename it),
                       \`single-reason\` (an \`items\` provider that tests
                       \`reason\` against one cause other than \`'search'\`;

package/dist/ai/BbAlert.md

@@ -107,6 +107,9 @@ distinct success tone.
 
 #### Variant icons
 
+A default icon per variant, set once for the whole app: the object form of
+the plugin's `alertVariants` option.
+
 ```ts
 // vite.config.ts (Nuxt: the `bitboss` key)
 bitbossUi({

package/dist/ai/BbForm.md

@@ -1617,7 +1617,8 @@ The `id` is also the `<form>`'s own (it follows a BbForm; a plain `<form>`
 submits but has no save state to follow), so a `<BbButton form="id" type="submit">`
 outside it submits it too, through the same validation, and spins while the
 save runs exactly like a submit button inside (`disable-auto-loading` opts
-out): no `:loading` to bind.
+out): no `:loading` to bind. Server errors (`setErrors`, `field-errors`) then
+focus the first failing field, as they do after a submit from inside.
 
 ```vue
 <script setup lang="ts">

package/dist/ai/BbSelect.md

@@ -1617,7 +1617,11 @@ const createLabel = (text: string) => {
 Set `group-by` to a field path (or a function) to bucket options under headers.
 The `#group` slot styles the header and receives
 `{ text, item, index, length, disabled }` — `length` is the number of options
-in the group, `index` the list index of its first option.
+in the group, `index` the list index of its first option. A row whose
+`group-by` gives `null` or `undefined` has no group: those rows are listed
+without a header, and `#group` is not called for them (a known row is listed
+the same way). Rows in the middle of the list with no header read as part of
+the group above, so give them a group of their own (`row.team ?? 'Other'`).
 
 A grouped list virtualizes **whole groups, not rows**: a group mounts only
 when it scrolls into range, but all of its rows mount together. Many
@@ -2346,7 +2350,7 @@ States are listed in precedence order: when two are on at once and their entries
 - `description` — scope: `BbSelectDescriptionSlotProps` `{ text: string; hasErrors: boolean; hasWarnings: boolean }` — Replaces the description text. Provided alone (no `description` prop) it still renders the description region and wires it into `aria-describedby`.
 - `empty` — scope: `{ query: string; focus: () => void; error: unknown; }` — Content shown when no options match the query or the list is empty. `error` is what the latest failed load threw, untouched (`null` when none).
 - `footer` — scope: `BbSelectPanelSlotProps` `{ close: () => Promise<void>; clear: () => void; focus: () => void; query: string; selectedOptions: BbSelectResolvedOption[] }` — Content pinned to the bottom of the options panel, below the options list. Rendered in both the desktop popover and the adaptive sheet.
-- `group` — scope: `BbSelectGroupSlotProps<T>` `{ text: string; item: T; index: number; length: number; disabled: boolean }` — Replaces the default group header rendered above grouped options.
+- `group` — scope: `BbSelectGroupSlotProps<T>` `{ text: string; item: T; index: number; length: number; disabled: boolean }` — Replaces the default group header rendered above grouped options. Not called for rows with no group (`group-by` gives `null`/`undefined`, known rows): they are listed without a header.
 - `header` — scope: `BbSelectPanelSlotProps` `{ close: () => Promise<void>; clear: () => void; focus: () => void; query: string; selectedOptions: BbSelectResolvedOption[] }` — Content pinned to the top of the options panel, above the search field. Rendered in both the desktop popover and the adaptive sheet.
 - `label` — scope: `BbSelectLabelSlotProps` `{ showAsterisk?: boolean; text: string; hasErrors: boolean; hasWarnings: boolean }` — Replaces the default label text rendered above the input.
 - `loading` — scope: `{ query: string; }` — Content shown inside the options dropdown while items are loading.

package/dist/ai/BbSelectPopover.md

@@ -1916,7 +1916,7 @@ States are listed in precedence order: when two are on at once and their entries
 - `activator` — scope: `BbSelectPopoverActivatorSlotProps` `{ clear: () => void; close: () => Promise<void>; focus: () => void; disabled: boolean; loading: boolean; open: () => Promise<void>; props: { ref: (reference: unknown) => void; }; query: string; readonly: boolean; selectedOptions: BbSelectResolvedOption<any>[]; shown: boolean; text: string; toggle: () => Promise<void> }` — Replaces the default trigger element that opens the select popover.
 - `empty` — scope: `{ query: string; focus: () => void; error: unknown; }` — Content shown when no options match the query or the list is empty. `error` is what the latest failed load threw, untouched (`null` when none).
 - `footer` — scope: `BbSelectPopoverPanelSlotProps` `{ close: () => Promise<void>; clear: () => void; focus: () => void; query: string; selectedOptions: BbSelectResolvedOption<any>[] }` — Content pinned to the bottom of the panel, below the options list. Rendered in both the desktop popover and the adaptive sheet.
-- `group` — scope: `BbSelectPopoverGroupSlotProps<Item>` `{ disabled: boolean; index: number; item: Item; length: number; text: string }` — Replaces the default group header rendered above grouped options.
+- `group` — scope: `BbSelectPopoverGroupSlotProps<Item>` `{ disabled: boolean; index: number; item: Item; length: number; text: string }` — Replaces the default group header rendered above grouped options. Not called for rows with no group (`group-by` gives `null`/`undefined`, known rows): they are listed without a header.
 - `header` — scope: `BbSelectPopoverPanelSlotProps` `{ close: () => Promise<void>; clear: () => void; focus: () => void; query: string; selectedOptions: BbSelectResolvedOption<any>[] }` — Content pinned to the top of the panel, above the search field. Rendered in both the desktop popover and the adaptive sheet.
 - `loading` — scope: `{ query: string; }` — Content shown inside the options dropdown while items are loading.
 - `option` — scope: `BbSelectPopoverOptionSlotProps<Item>` `{ disabled: boolean; focused: boolean; index: number; item: Item; loading: boolean; selected: boolean; text: string; value: any; description: string }` — Replaces the default rendering of each option row in the dropdown.

package/dist/ai/BbTable.md

@@ -88,11 +88,21 @@ 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`. 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 +364,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 +704,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 +1110,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 +1134,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 +1209,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 +1233,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 +2037,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 +2264,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 +3364,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 +3379,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
 
@@ -3652,21 +3713,24 @@ 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.
+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); `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 +3907,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 +4113,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 +4176,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`, `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` |  |  | 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 +4213,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 +4249,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. |
@@ -4193,11 +4266,11 @@ States are listed in precedence order: when two are on at once and their entries
 | `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 +4297,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/GroupedListBox.md

@@ -53,7 +53,7 @@
 ## Slots
 
 - `empty` — scope: `object` — Content shown when no options are available (replaces the default "no data" text).
-- `group` — scope: `GroupedListBoxGroupSlotProps<Item>` `{ text: string; item: Item; index: number; length: number; disabled: boolean }` — Replaces the default group header rendered above each group of options.
+- `group` — scope: `GroupedListBoxGroupSlotProps<Item>` `{ text: string; item: Item; index: number; length: number; disabled: boolean }` — Replaces the default group header rendered above each group of options. A group whose `data` is `null`/`undefined` has no header, so no call.
 - `loading` — scope: `object` — Content shown while items are loading (replaces the default loading text).
 - `option` — scope: `GroupedListBoxOptionSlotProps<Item>` `{ disabled: boolean; focused: boolean; index: number; item: Item; selected: boolean; text: string; value: any; description: string }` — Replaces the default rendering of each option row within a group.
 - `options:append` — scope: `object` — Content appended inside the options list, after the last group.