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

package/README.md

@@ -36,46 +36,53 @@ Full detail: `ai/guides/installation-and-plugin-setup.md`.
 
 ### Composables
 
-| Composable                    | Role                                                       |
-| ----------------------------- | ---------------------------------------------------------- |
-| `useBbConfig`                 | Global options for the kit (locale, defaults, etc.).       |
-| `useBroadcastChannelInstance` | Shared `BroadcastChannel` helper for cross-tab messaging.  |
-| `useConfirm`                  | Programmatic confirm / modal flows.                        |
-| `useCountdown`                | Countdown timer state.                                     |
-| `useMobile`                   | Mobile / viewport-oriented behaviour.                      |
-| `useQueue`                    | Simple async task queue.                                   |
-| `useSafeArea`                 | Claim a screen edge for a docked panel so toasts avoid it. |
-| `useToast`                    | Toast notifications API.                                   |
-
-### Base\* components (primitives) _(reference-only - prefer `Bb*` equivalents for consumer code)_
-
-Headless or low-level pieces used inside **Bb\*** wrappers or your own compositions:
-
-- **Actions:** `BbBaseButton`
-- **Text & numbers:** `BaseTextInput`, `BaseTextarea`, `BaseNumberInput`, `BaseTag`
-- **Choice:** `BaseCheckbox`, `BaseCheckboxGroup`, `BaseRadio`, `BaseRadioGroup`, `BaseSwitch`, `BaseSwitchGroup`, `BaseSlider`, `BaseRating`
-- **Choice glyphs (presentational SVGs):** `BbBaseCheckboxIcon`, `BbBaseRadioIcon`, `BbBaseSwitchIcon`
-- **Rich inputs:** `BaseSelect`, `BaseColorInput`, `BaseDatePicker`, `BaseDatePickerInput`
-- **Layout / chrome:** `BaseInputContainer`, `BaseDialog`
+| Composable             | Role                                                                  |
+| ---------------------- | --------------------------------------------------------------------- |
+| `useBbConfig`          | Global options for the kit (locale, defaults, etc.).                  |
+| `useBbDropdownContext` | Read a `BbDropdown`'s resolved groups/selections from anywhere by id. |
+| `useBbTableContext`    | Imperative handle onto a `BbTable` by id.                             |
+| `useBbTabsContext`     | Programmatic tab selection for a `BbTabs` by id.                      |
+| `useConfirm`           | Programmatic confirm / modal flows.                                   |
+| `useCountdown`         | Countdown timer state.                                                |
+| `useId`                | SSR-safe unique ids.                                                  |
+| `useMobile`            | Mobile / viewport-oriented behaviour.                                 |
+| `useSafeArea`          | Claim a screen edge for a docked panel so toasts avoid it.            |
+| `useToast`             | Toast notifications API.                                              |
+
+### Utilities
+
+- **`slotKey`** — the normalizer behind every dynamic per-item named slot (`BbDropdown`, `BbTable`, `BbTabs`, `BbTree`, `BbBreadcrumbs`). Import it when building slot names programmatically instead of restating the rule.
+
+### Directives
+
+`vBbTooltip`, `vBbDropdown`, `vBbColor`, `vBbDate`, `vBbTime` — plus a
+`Bb*DirectivePlugin` for each, for app-level registration. Prefer the directive
+over the component for simple no-slot cases.
+
+### Base\* primitives
+
+The styled `Base*` input controls and the input chrome (`BbBaseInputContainer`,
+`CommonInputWrapper` — label, prepend/append, prefix/suffix, clear button,
+spacing) are **internal composition layers and are not exported**. Use the full
+public inputs (`BbTextInput`, `BbSelect`, …); pass `hideLabel` for a
+bare/inline control. The exported primitives are **`BbBaseButton`** and the
+presentational glyphs **`BbBaseCheckboxIcon`**, **`BbBaseRadioIcon`**,
+**`BbBaseSwitchIcon`**.
 
 ### Bb\* components (composed)
 
 Product-ready components with labels, hints, errors, and consistent styling:
 
-- **Forms & actions:** `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbSelect`, `BbCheckbox`, `BbCheckboxGroup`, `BbRadio`, `BbRadioGroup`, `BbSwitch`, `BbSwitchGroup`, `BbSlider`, `BbRating`, `BbColorInput`, `BbDatePickerInput`, `BbButton`, `BbBadge`, `BbIndicator`, `BbTag`, `BbDropdown`, `BbDropdownButton`
-- **Feedback:** `BbAlert`, `BbProgress`, `BbSpinner`, `BbToast`, `BbTooltip`
-- **Layout & navigation:** `BbAccordion`, `BbCollapsible`, `BbTab`, `BbBreadcrumbs`, `BbPagination`,`BbSmoothHeight`
+- **Forms & actions:** `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbSelect`, `BbSelectPopover`, `BbCheckbox`, `BbCheckboxGroup`, `BbRadio`, `BbRadioGroup`, `BbSwitch`, `BbSwitchGroup`, `BbSlider`, `BbRating`, `BbColorInput`, `BbColorPalette`, `BbDatePicker`, `BbDatePickerInput`, `BbTimePicker`, `BbTimePickerInput`, `BbButton`, `BbBadge`, `BbBadgeButton`, `BbIndicator`, `BbTag`, `BbDropdown`, `BbDropdownGroup`, `BbDropdownButton`, `BbAsterisk`
+- **Feedback:** `BbAlert`, `BbProgress`, `BbSpinner`, `BbToast`, `BbToastPortal`, `BbTooltip`
+- **Layout & navigation:** `BbAccordion`, `BbCollapsible`, `BbTabs` (+ `BbTabsRoot`, `BbTabsList`, `BbTabsPanes`), `BbBreadcrumbs`, `BbPagination`, `BbSmoothHeight`
 - **Overlays & panels:** `BbDialog`, `BbConfirm`, `BbConfirmPortal`, `BbOffCanvas`, `BbPopover`
 - **Data:** `BbTable`, `BbTree`
 - **Media & files:** `BbAvatar`, `BbDropzone`, `BbIcon`
 
-### Shared input shells _(internal layout primitives - not for direct consumer use)_
-
-- **`CommonInputWrapper`** — the internal input-chrome primitive (label, prepend/append, prefix/suffix, clear button, spacing) that every `Bb*` input composes. Not exported; use the full public inputs (`BbTextInput`, `BbSelect`, …).
-
 ### Exported component types
 
-For most **Base\*** and **Bb\*** components, the package exports matching **props**, **events**, and (where relevant) **slots** types (for example `BbSelectProps`, `BaseSelectEvents`). Use them for typed wrappers and design-system layers; the docs list the full set per component.
+For the public **Bb\*** components, the package exports matching **props**, **events**, and (where relevant) **slots** types (for example `BbSelectProps`, `BbTableEvents`), plus supporting shapes like `BbDropdownItem` and `DropdownGroupItemsGetter`. Use them for typed wrappers and design-system layers; the docs list the full set per component.
 
 ---
 

package/dist/ai/BbBadge.md

@@ -309,9 +309,12 @@ state in the handler. Prefer `secondary` / `outline` for filter chips; reserve
 ```
 
 The clear button inherits the variant's foreground, so it reads on every surface
-— light on a filled `primary`, dark on a `secondary`/`outline`. Set
-`clearable-label` for the button's accessible name (defaults to the localized
-`badge.clearLabel`).
+— light on a filled `primary`, dark on a `secondary`/`outline`. By default its
+accessible name composes the localized verb with the badge's own text — a chip
+reading "Italy" announces "Remove Italy", with no per-chip wiring. Set
+`clearable-label` only when that composition is wrong for the context (it
+replaces the whole name). With a `BbBadgeButton` body the composition is
+skipped and the button falls back to the bare localized `badge.clearLabel`.
 
 Icons combine with `clearable`: a **`prepend:icon`** stays (it leads the label);
 an **`append:icon`** shares the trailing slot with the clear button — the icon
@@ -695,8 +698,10 @@ selectors like `.bb-badge > .bb-badge__content`, which no longer match.
 - An icon-only badge (`icon`) has no visible text; the default slot is rendered
   as a screen-reader-only label — never leave it empty. In button mode that
   label is also the **button's accessible name**, so it is doubly required.
-- The `clearable` button has an accessible name from `clearable-label` (or the
-  localized `badge.clearLabel`).
+- The `clearable` button's accessible name is composed by default: the
+  localized `badge.clearLabel` verb plus the badge body's text ("Remove
+  Italy"). `clearable-label` replaces the whole name; with a `BbBadgeButton`
+  body the composition is skipped (bare verb only).
 - A clickable **and** clearable badge is two tab stops (body, then clear). That
   is intended: two actions, two controls.
 - Keyboard focus on either control rings the whole pill, so the focused target

package/dist/ai/BbSelect.md

@@ -1212,6 +1212,14 @@ Shipped behavior — never reimplement it:
   library default) — `direction="horizontal"` gives a label-beside-field row.
   Only `floating`/`inside` label modes force the vertical layout, since they
   embed the label in the field itself.
+- **A long `placeholder` or a long selected label never widens the control's
+  track.** The trigger is a button, not an `<input>`, so the placeholder is
+  real text rather than a paint-only `::placeholder` — but the field's minimum
+  size is capped so that text cannot become the floor of a grid or flex track.
+  Put a select with a paragraph-length placeholder in
+  `grid-template-columns: repeat(3, 1fr)` and you still get three equal
+  columns, with the text ellipsised inside its field. You do **not** need
+  `min-w-0` on the item or `minmax(0, 1fr)` on the track to get this.
 
 ### Adaptive mobile sheet
 

package/dist/ai/BbTable.md

@@ -55,13 +55,15 @@ needs is declared here, not in markup:
   `align` prop sets the default for the whole table (`left`).
 - **`width`** freezes the column: numbers and bare numeric strings are px
   (`130`, `'130'`); anything carrying a unit passes through (`'12rem'`,
-  `'20%'`). Declaring any `width` switches the table to `table-layout: fixed`
-  (widths are only authoritative there); unfrozen columns then share the
-  leftover space proportionally to their content.
+  `'20%'`). A declared width is the column's grid track and holds exactly;
+  unfrozen columns size to their content and share any leftover space equally
+  (the table is a CSS grid — the tracks are the width API, there is no
+  `table-layout`). When _every_ column declares a width, the surplus is shared
+  in proportion to the declared widths so the table still fills its container.
 - **`skeleton`** picks the loading placeholder shape (see Loading below).
 - **`sortable` / `sorted`** — see Sorting.
 - **`thClass` / `tdClass` / `rowClass`** style the header cell, the data cells,
-  and the whole `<tr>`. `tdClass` and `rowClass` may be functions
+  and the whole row. `tdClass` and `rowClass` may be functions
   `(content, key, item) => Classes` for state-dependent styling. Table-level
   `thClass` / `tdClass` / `rowClass` / `headerRowClass` apply everywhere; a
   row's classes accumulate the table `rowClass` plus every column's.
@@ -155,7 +157,7 @@ const invoices: Invoice[] = [
 	},
 ];
 
-// `row-class` is applied to each `<tr>`; use it to flag rows by state. Soft amber
+// `row-class` is applied to each row (`.bb-table-data__row`); use it to flag rows by state. Soft amber
 // wash matches the design-language attention accent — public API, no internals.
 const rowClass = (invoice: Invoice) =>
 	invoice.status === 'overdue'
@@ -207,7 +209,11 @@ Override any column's body with a `#<key>` slot and its header with a
 characters turned into `_` (dashes are kept as-is), **lowercased**:
 `address.city` → `#address_city`, `first_name` → `#first_name`, `issued-at` →
 `#issued-at`, but also `issuedAt` → `#issuedat` — prefer snake_case keys so
-slot names read naturally. Keep the column in `columns`
+slot names read naturally. Building slot names in code (columns from config, a
+dynamic `<template>` loop)? Import the normalizer itself — `import { slotKey }
+from 'bitboss-ui'` — instead of restating the rule: a hand copy that differs by
+one character (`\W+` collapses dashes; the real rule keeps them) makes the slot
+silently never match. 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`
@@ -219,6 +225,22 @@ one-way state; the `toggle*` callbacks are the write path.
 Header scope: `label`, `items` (the full list — handy for counts), `sortable`,
 `sortOrder`, `toggleSort`, `classes`.
 
+**Add beside a header instead of replacing it** with
+`#header:<key>:prepend` / `#header:<key>:append` — rendered before / after the
+column's existing header content (the label + sort control, or your own
+`#header:<key>` replacement), so a resize grip 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
+plus `columnKey` (the raw column key) so a table-wide template can branch per
+column. When both a per-column and the table-wide slot are provided for the
+same side, the per-column one wins for that column — they never stack. Affixes
+render even beside a full `#header:<key>` replacement (the same rule as
+BbDropdown's `#<key>:prepend/append`). One caveat: a column key that
+normalizes to `prepend` or `append` collides with the table-wide slot names;
+the table-wide interpretation wins, per-column header slots are unavailable
+for that column, and dev builds warn.
+
 Below, the status badges carry brand glyphs shipped in the app's `iconDir`,
 referenced as `local:*` names on the badge's `prepend:icon`. Per the icons
 policy the dynamic status maps to **full-name literals** (a lookup object) —
@@ -365,7 +387,10 @@ Beyond per-column slots, the structural slots cover every other region:
 (replace the per-row checkbox/radio; scope: `item`, `value`, `checked`,
 `disabled`, `readonly`, `inputName`, `toggleSelected`), `#loading`, `#no-data`
 (both below), and `#thead` / `#tbody` / `#tfoot` to replace an entire region
-when you need full control (you then own its markup and semantics).
+when you need full control (you then own its markup and semantics: the table
+is a CSS grid, so pass `<div role="row">` rows holding `<div role="cell">` /
+`<div role="columnheader">` cells — never `<tr>`/`<td>`; a spanning cell uses
+`grid-column: span N` with `#tfoot`'s `columnCount`, see **Styling hooks**).
 
 ### Loading and empty states
 
@@ -396,8 +421,9 @@ it renders only when there is nothing to keep. (Scope: the current, possibly
 stale `items` — handy for matching the previous row count.) When `items` resolves
 empty the table shows its no-data row — localized default text, overridable via
 `no-data-text` or fully via the `#no-data` slot. That slot fills the table's own
-full-width empty-state cell (already centred, colspan already counted), so pass
-the content — a message, a "clear filters" button — not a `<tr>` of your 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.
 
 `loading-text` is the loading row's `aria-live` announcement. Like
 `no-data-text` it has a **localized default** (`common.loadingText` —
@@ -693,6 +719,11 @@ 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`.
 
+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
+ascending, down for descending — the AG Grid convention), gone again on the
+third click.
+
 **Sortable headers driving a client-side sort**
 
 ```vue
@@ -773,7 +804,10 @@ const sortedInvoices = computed(() => {
 
 A custom `#header:<key>` 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`). The column-level `sorted`
+(render your own button and call `toggleSort`). To merely add something next
+to the control — a resize grip, a filter icon — use
+`#header:<key>: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
 does not move the visual indicator; to start pre-sorted, seed `v-model:sort`
 instead (as the example does).
@@ -1282,7 +1316,7 @@ _detail about the row_ rather than _children of it_.
 A `BbTable` rendered inside another's `#expand` slot is independent by
 default. Add `inherit-column-widths` and it snaps its columns to the parent's
 tracks, so a line-items breakdown reads as a continuation of the invoice row
-above it (this also forces fixed layout). The mechanics:
+above it. The mechanics:
 
 - `inherit-column-widths` — `true` inherits from the nearest ancestor table;
   a string targets a specific ancestor's `id` (useful when an intermediate
@@ -1293,23 +1327,34 @@ above it (this also forces fixed layout). The mechanics:
   allowed; `end: -1` runs to the end of the data region). Structural columns
   (`select`, actions) are accounted for automatically.
 - A child with **more** columns than the parent content-sizes the extras and
-  scrolls; with fewer, the last width-free column absorbs the slack so both
-  tables end flush.
-- **When the parent has `selectable`/`actions` columns, snap every child
-  column** (`snap: base` … `base + n`, where `base` is `1` under a selectable
-  parent, `0` otherwise). A width-free last column becomes the fill track and
-  absorbs the parent's actions region — right-aligned content then sits under
-  the expand/actions control instead of under the parent's last data column.
-  With every column snapped, the parent's select and actions tracks fold into
-  the child's first/last cell as _padding_, so the child's content stays flush
-  with the parent's data grid on both edges (a child without its own select
-  column starts flush with the parent's first data column — the inset itself
-  reads as hierarchy).
+  overflows into the parent's scroll (see below); with fewer, the last
+  width-free column absorbs the slack so both tables end flush.
+- **An inheriting child does not scroll on its own — the parent's scrollport
+  is the only one.** That is what keeps the two grids locked together: a child
+  with its own scroll position would fall out of alignment the moment either
+  one moved, which is the whole thing `inherit-column-widths` exists to
+  prevent. One scrollbar moves both.
+- **The parent's `selectable`/`actions` columns are handled for you** — the
+  child's content columns map to the parent's content columns 1:1 (no `snap`
+  needed for that), and the parent's select/actions _regions_ are reserved on
+  each side: a child with its own select or actions column widens that cell
+  to the parent's (two equal cells, controls at the row's end, so the ⌃ sits
+  under the parent's); a child without one folds the region into its first/
+  last cell as _padding_, so its content stays flush with the parent's data
+  grid on both edges (the inset reads as hierarchy). Only a child cell
+  _wider_ than the parent's — a select the parent lacks, more buttons — moves
+  anything, and only the adjacent content column: it shrinks by the surplus
+  so every other rail holds. What a child publishes to its own children is
+  the same contract (content rails + regions), so a three-level nest aligns
+  at every depth.
 - **Scope any page-level cell-padding overrides to the parent's own cells.** A
-  bare `:deep(tbody td:first-child)` also matches the nested table's cells and
-  clobbers the offset padding it computes to stay aligned — use direct-child
-  combinators (`:deep(> table > tbody > tr > td:first-child)`) so the child
-  keeps its structural padding.
+  bare `:deep([role='cell']:first-child)` also matches the nested table's
+  cells and clobbers the offset padding it computes to stay aligned — use the
+  direct-child chain through the grid's containers
+  (`:deep(> .bb-table__table > .bb-table__body > [role='row'] > :first-child)`)
+  so the child, which lives inside `.bb-table-expand__cell`, keeps its
+  structural padding. The canonical `.table-flush` idiom is under **Styling
+  hooks**.
 
 **Invoice lines aligned under the invoice columns**
 
@@ -1419,6 +1464,41 @@ const expanded = ref<string[]>([]);
 </script>
 ```
 
+#### Affixed actions on both tables
+
+A nested table can carry its own `fixed-columns` — child rows usually need
+their own row actions — and both action columns pin to the same visible edge:
+
+```vue
+<BbTable
+	id="programmes"
+	actions
+	:columns="columns"
+	:fixed-columns="[{ index: columns.length, position: 'right' }]"
+	:items="rows"
+	item-value="id"
+>
+	<template #expand="{ item }">
+		<BbTable
+			actions
+			:columns="childColumns"
+			:fixed-columns="[{ index: childColumns.length, position: 'right' }]"
+			inherit-column-widths="programmes"
+			:items="item.children"
+			item-value="id"
+		/>
+	</template>
+</BbTable>
+```
+
+This works because the child shares the parent's scrollport. `position: sticky`
+resolves against the nearest scrolling ancestor, and the child's own box is as
+wide as the parent's **content** — so if it opened a scrollport of its own, the
+child's actions would affix to an edge sitting out in the overflow, hundreds of
+pixels past what anyone can see, while the parent's pinned correctly. Snap the
+child's actions column onto the parent's actions track (see the snapping rule
+above) so the two columns line up rather than merely both being pinned.
+
 #### Flush tables + inherited widths: mind the edge padding
 
 `table-flush` removes the outer cell padding so the table reads edge-to-edge in
@@ -1432,9 +1512,10 @@ Two rules keep them honest:
 1. **Snap against the same base you paint.** Measure the parent's columns with
    the same flush/padded state the child renders in — never measure padded and
    render flush.
-2. **Never add nest padding on the body only.** Padding the child's `tbody` but
-   not its header (or vice versa) reintroduces exactly the offset the snap just
-   removed. Put the inset on the nest container, where both rows inherit it.
+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.
 
 ### Row highlight (master–detail)
 
@@ -1636,9 +1717,11 @@ const rowClass = (event: AuditEvent) =>
 ```
 
 Row events: `click:row`, `dblclick:row` and `contextmenu:row` fire with
-`(event, row, selected)`. Note that `row` is the table's internal row wrapper,
-not your item: read the raw record from `row.item` and its resolved value from
-`row.value`. Reserve these events for side effects that are not navigation —
+`(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
+events for side effects that are not navigation —
 logging, opening a drawer (though `v-model:highlighted` usually covers that
 without any handler).
 
@@ -2057,10 +2140,11 @@ leave the screen. Collapse instead of scroll:
 
 - **Rank the columns.** Identity + status + the one number that matters stay;
   everything else is secondary.
-- **Hide the secondary ones at a breakpoint** with the column's `thClass` _and_
-  `tdClass` (there is no `classes` field): give both the same
-  `'hidden md:table-cell'`, so they are gone rather than off-screen. Both are
-  needed — `thClass` hides the header, `tdClass` the body cells.
+- **Drop the secondary ones from `columns` at the breakpoint** — a `computed`
+  over `useMobile()` (or your own `matchMedia`) that filters the secondary keys
+  out. Removing the column removes its grid track. Do **not** hide cells with
+  `thClass`/`tdClass` + `display: none`: the table is a grid, a hidden cell
+  leaves its track in place and every following cell shifts one track over.
 - **Stack what survives into the primary cell.** The identity slot renders the
   name plus the hidden facts under it, at `--bb-text-muted`, so nothing is
   actually lost.
@@ -2069,6 +2153,125 @@ Keep the sticky/pinned identity column for the case where the full grid really
 must stay reachable (a spreadsheet-shaped tool), not as the default for a
 records list.
 
+### Styling hooks
+
+**The table's surface is `--bg`** (default `var(--bb-panel)`), a local on
+`.bb-table`. Cells are transparent at rest so the row can tint them, but
+anything that slides over scrolled content — the stuck header band with
+`fixed-headers`, and `fixed-columns` cells — is opaque and paints `--bg` (a
+pinned cell also picks up its row's hover/highlight tint, so it never reads
+as a hole). When a table sits on a surface that is not the panel colour, set
+the one knob and everything pinned follows:
+
+```css
+.my-card .bb-table {
+	--bg: var(--card-bg);
+}
+```
+
+The table is a **CSS grid of `<div>`s with ARIA roles, not a `<table>`**: the
+root `.bb-table__table[role=table]` owns the column tracks and every row group
+and row is a subgrid of it. Style it through the classes and the roles — never
+through element names, which match nothing:
+
+| Region       | Class                                                    | Role                                      |
+| ------------ | -------------------------------------------------------- | ----------------------------------------- |
+| grid root    | `.bb-table__table`                                       | `table`                                   |
+| header group | `.bb-table__head`                                        | `rowgroup`                                |
+| header row   | `.bb-table-header-row`                                   | `row`                                     |
+| header cell  | `.bb-table-header` (+ `--select`, `--actions`)           | `columnheader`                            |
+| body group   | `.bb-table__body`                                        | `rowgroup`                                |
+| data row     | `.bb-table-data__row` (+ `--highlighted`)                | `row`                                     |
+| data cell    | `.bb-table-data__cell` (+ `--select`)                    | `cell`                                    |
+| actions cell | `.bb-table__cell--actions`                               | `cell`                                    |
+| expand row   | `.bb-table-expand__row` > `.bb-table-expand__cell`       | `row` > `cell`                            |
+| empty state  | `.bb-table-no-data__row` > `.bb-table-no-data__cell`     | `row` > `cell`                            |
+| footer group | `.bb-table__foot` (`#tfoot` content)                     | `rowgroup` only when `#tfoot` is provided |
+| caption      | `.bb-table-caption` (before the root, `aria-labelledby`) | —                                         |
+
+`[role='row']`, `[role='cell']` and `[role='columnheader']` are supported
+hooks, not incidental markup — use them when you mean "every row kind" or
+"every cell"; use the classes when you mean one kind. Cells are direct
+children of their row, so `:first-child` / `:last-child` / `:nth-child(n)`
+address columns.
+
+The full-bleed idiom every workspace page reaches for — the table bleeds past
+the content padding and hands the inset back to its outermost cells — is
+written with a **direct-child chain** so a nested table inheriting the
+parent's tracks (it lives inside `.bb-table-expand__cell`) is never touched:
+
+```css
+.table-flush {
+	--page-inset: 1rem;
+	margin-inline: calc(var(--page-inset) * -1);
+	width: calc(100% + var(--page-inset) * 2);
+}
+
+.table-flush
+	:deep(> .bb-table__table > .bb-table__head > [role='row'] > :first-child),
+.table-flush
+	:deep(
+		> .bb-table__table
+			> .bb-table__body
+			> [role='row']
+			> :first-child:not(.bb-table-expand__cell)
+	) {
+	padding-inline-start: var(--page-inset);
+}
+
+.table-flush
+	:deep(> .bb-table__table > .bb-table__head > [role='row'] > :last-child),
+.table-flush
+	:deep(
+		> .bb-table__table
+			> .bb-table__body
+			> [role='row']
+			> :last-child:not(.bb-table-expand__cell)
+	) {
+	padding-inline-end: var(--page-inset);
+}
+
+/* Expand rows stay edge-to-edge so the nested table can snap onto the parent
+   tracks without an extra inset shifting it sideways. */
+.table-flush
+	:deep(
+		> .bb-table__table > .bb-table__body > [role='row'] > .bb-table-expand__cell
+	) {
+	padding-inline: 0;
+}
+```
+
+Leave the geometry alone: `display: grid` / `gap: 0` on the root, row groups
+and rows, `grid-column: 1 / -1` **and `contain: inline-size`** on the
+full-width cells (without the containment, expand-row content resizes the
+parent's columns), `white-space: nowrap` on the actions cell (it sizes the
+actions track), and `position: sticky` on `.bb-table__head` under
+`fixed-headers`.
+
+When you replace a region with `#thead` / `#tbody` / `#tfoot`, ship the same
+shape the table does — role-complete rows, spanning with `grid-column` rather
+than `colspan`:
+
+```vue
+<template #tfoot="{ columnCount }">
+	<div role="row">
+		<div
+			role="cell"
+			:aria-colspan="columnCount - 1"
+			:style="{ gridColumn: `span ${columnCount - 1}` }"
+		>
+			Total
+		</div>
+		<div role="cell" class="text-right">{{ total }}</div>
+	</div>
+</template>
+```
+
+A `<tr>` inside the grid is not merely unsemantic — the browser wraps it in an
+implicit `<table>` and the cells never land on the tracks. Nothing lints the
+roles: a `<div>` row without them renders fine and is invisible to a screen
+reader.
+
 ### Config and platform
 
 - **Locale.** The plugin's `locale` (`it`/`en`) drives the built-in strings:
@@ -2119,7 +2322,8 @@ records list.
 - Enabling select-all does not re-emit an empty `modelValue` (see the
   select-all section) — in all-mode, read `select-all` +
   `unselected-items`, not `modelValue`.
-- Row event payloads are the internal row wrapper — your record is `row.item`.
+- Row event payloads are `(event, item)` with `item` your raw record — there is
+  no wrapper to unpack and no `selected` argument.
 - A mistyped context/pagination `id` does not error; it silently syncs with
   nothing. If a toolbar "works" but the table never reacts, check the id.
 - In multiple mode `modelValue` must be an array, or it throws.
@@ -2195,13 +2399,13 @@ records list.
 | `displayCaption` | `boolean \| undefined` |  |  | Boolean that defines whether to display or hide the caption. By default is true and the caption is hidden. |
 | `enforceCoherence` | `boolean \| undefined` |  |  | After every load (initial, `dependencies` refetch or a change of the `items` array) prunes the row-keyed models of values whose row is no longer in the result set: `modelValue`, `unselected-items`, `highlighted` and `expanded-items`. Values… |
 | `expandedItems` | `any[] \| undefined` | `[]` |  | Used by `v-model:expandedItems`. Array of the currently expanded items — toggled by the row expand control and by external writes (mirrors the `highlighted`/`sort` v-model surfaces). Drives the `#expand` slot rows and their `aria-expanded`/… |
-| `fixed` | `boolean \| undefined` |  |  | Defines the table layout as fixed making each column take up the same amount of space. |
+| `fixed` | `boolean \| undefined` |  |  | Splits the width equally among the columns that declare no `width` (each undeclared column becomes a `minmax(0, 1fr)` track) making each column take up the same amount of space. |
 | `fixedColumns` | `(number \| { index: number; position: "left" \| "right"; })[] \| undefined` | `[]` |  | Definition for which column should be fixed. It can be an array of index of the column to fix on the left side of the table or an array of objects indicating the index and the position `left` or `right` where to affix the columns. |
 | `fixedHeaders` | `boolean \| undefined` |  |  | Boolean that sets the headers as sticky to the top of the table. |
-| `headerRowClass` | `Classes \| undefined` |  |  | Defines the classes to be passed to the header `<tr>`. |
+| `headerRowClass` | `Classes \| undefined` |  |  | Defines the classes to be passed to the header row. |
 | `highlighted` | `any` | `undefined` |  | Used by `v-model:highlighted`. A parallel, UI-intent state to selection — typically "the row whose details are open". A single item value (or `null`) — highlight is single by design. Purely mechanical: highlighted rows only get the `bb-tabl… |
 | `id` | `string \| undefined` |  |  | Stable id for this table's width context. When omitted a unique id is generated. Nested tables use the nearest ancestor id to inherit widths. |
-| `inheritColumnWidths` | `string \| boolean \| undefined` |  |  | Opt a nested table into inheriting its column widths from an ancestor table's matching tracks (accounting for `select`/`actions` columns). This also forces `table-layout: fixed`, so it is **off by default** — a nested table renders independ… |
+| `inheritColumnWidths` | `string \| boolean \| undefined` |  |  | Opt a nested table into inheriting its column widths from an ancestor table's matching tracks (accounting for `select`/`actions` columns). This also makes the parent's tracks authoritative, so it is **off by default** — a nested table rende… |
 | `interactiveWhileLoading` | `boolean \| undefined` |  |  | Keeps the table interactive while it is loading. The header and the rows are `inert` while loading by default — a refetch is about to replace the rows, so editing, selecting or sorting them races the incoming data. This escape hatch exists … |
 | `items` | `Item[] \| ((prefill: boolean, modelValue?: any) => Item[] \| Promise<Item[]>)` | `[]` | yes | Rows to render, or a fetcher that returns them. |
 | `itemValue` | `ItemAccessor<Item> \| undefined` |  |  |  |
@@ -2217,23 +2421,23 @@ records list.
 | `page` | `string \| number \| undefined` |  |  | Current page number starting from 1, used for accessibility purposes. Also flows into the shared table context, so a `BbPagination` paired through `id` reads it as the current page. Numeric strings are coerced (server pagination fields ofte… |
 | `perPage` | `string \| number \| undefined` |  |  | Number of items per page, used for accessibility purposes. Also flows into the shared table context read by a `BbPagination` paired through `id`. When omitted, an array `items` table infers it from `items.length`; an explicit value (or a co… |
 | `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
-| `rowClass` | `RowClasses<Item> \| undefined` |  |  | Defines the classes to be passed to each data `<tr>`. Can also be a function of the row's item for dynamic values. |
+| `rowClass` | `RowClasses<Item> \| undefined` |  |  | Defines the classes to be passed to each data row. Can also be a function of the row's item for dynamic values. |
 | `selectable` | `boolean \| ((item: Item) => boolean) \| undefined` |  |  | Defines whether the table is selectable. Can be a global boolean that affects all rows or a function that accepts an item and returns a boolean that only affects that item. |
 | `selectAll` | `boolean \| undefined` | `false` |  | Defines whether the "Select all" checkbox is checked. |
 | `selectAllLabel` | `string \| undefined` |  |  | Text of the label used by the "Select all" boolean. |
 | `selectText` | `string \| undefined` |  |  | Text of the header used for the radio inputs when the table is not `multiple`. |
 | `sort` | `BbTableSortEntry[] \| undefined` | `[]` |  | Used by `v-model:sort`. Ordered array of `[columnKey, direction]` entries, one per actively sorted column. Bidirectional: the header buttons of `sortable` columns update it, and external writes update the header indicators. The table does n… |
-| `tdClass` | `ColumnClasses<Item> \| undefined` |  |  | Defines the classes to be passed to the `<td>` elements. Can also be a function for dynamic values. |
-| `thClass` | `Classes \| undefined` |  |  | Defines the classes to be passed to the `<th>`. |
+| `tdClass` | `ColumnClasses<Item> \| undefined` |  |  | Defines the classes to be passed to every data cell. Can also be a function for dynamic values. |
+| `thClass` | `Classes \| undefined` |  |  | Defines the classes to be passed to every header cell. |
 | `totalItems` | `string \| number \| undefined` |  |  | Total number of items there is. Also flows into the shared table context, where a `BbPagination` paired through `id` derives its page count from it. When omitted, an array `items` table infers it from `items.length`; an explicit value (or a… |
 | `totalPages` | `string \| number \| undefined` |  |  | Seeds the page count shown by a `BbPagination` paired through `id`. A shortcut for when the server reports a page count rather than a row count: the table renders nothing from it, it only flows into the shared table context. A known total a… |
 | `unselectedItems` | `any[] \| undefined` | `[]` |  | Items that are not selected. |
 
 ## Events
 
-- `click:row` — `(e: "click:row", event: MouseEvent, item: any, selected: boolean): void`
-- `contextmenu:row` — `(e: "contextmenu:row", event: MouseEvent, item: any, selected: boolean): void`
-- `dblclick:row` — `(e: "dblclick:row", event: MouseEvent, item: any, selected: boolean): void`
+- `click:row` — `(e: "click:row", event: MouseEvent, item: any): void`
+- `contextmenu:row` — `(e: "contextmenu:row", event: MouseEvent, item: any): void`
+- `dblclick:row` — `(e: "dblclick:row", event: MouseEvent, item: any): void`
 - `item:selected` — `(e: "item:selected", value: any): void`
 - `item:unselected` — `(e: "item:unselected", value: any): void`
 - `update:expandedItems` — `(e: "update:expandedItems", value: any[]): void`
@@ -2248,13 +2452,15 @@ records list.
 - `actions` — scope: `{ expanded?: boolean \| undefined; expandProps?: ExpandControllerProps \| undefined; toggleExpanded?: (() => void) \| undefined; highlighted?: boolean \| undefi…` — Content rendered in the actions cell for each row.
 - `expand` — scope: `{ expanded: boolean; expandProps?: ExpandControllerProps \| undefined; toggleExpanded: () => void; highlighted?: boolean \| undefined; toggleHighlighted?: (() =…` — Full-width expandable content row rendered below each main row when expanded.
 - `header:actions` — scope: `{ text: string; }` — Replaces the default actions header cell content.
+- `header:append` — scope: `BbTableHeaderAffixSlotProps<Item>` — Content rendered after every data column's header cell content — the label + sort control, or the column's own `header:<key>` replacement. A column's `header:<key>:append` slot wins over this one for that column; they never stack. Branch on…
+- `header:prepend` — scope: `BbTableHeaderAffixSlotProps<Item>` — Content rendered before every data column's header cell content — the label + sort control, or the column's own `header:<key>` replacement. A column's `header:<key>:prepend` slot wins over this one for that column; they never stack. Branch …
 - `header:select` — scope: `{ multiple: boolean; selectAll: boolean; text: string; }` — Replaces the default selection header cell content (checkbox or radio label).
 - `loading` — scope: `{ items: Item[]; }` — Content shown while table rows are loading (replaces the skeleton rows).
-- `no-data` — scope: `object` — Content shown when the items list is empty and not loading. It fills the table's own full-width empty-state cell (the colspan already accounts for the selection/actions columns), so provide the *content* — a message, an illustration, a "cle…
+- `no-data` — scope: `object` — Content shown when the items list is empty and not loading. It fills the table's own full-width empty-state cell (it already spans the selection/actions columns), so provide the *content* — a message, an illustration, a "clear filters" butt…
 - `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.
-- `tbody` — scope: `object` — Replaces the entire `<tbody>` element. Use when you need full control over the body markup.
-- `tfoot` — scope: `{ columnCount: number; }` — Replaces the entire `<tfoot>` element. Use when you need full control over the footer markup.
-- `thead` — scope: `object` — Replaces the entire `<thead>` element. Use when you need full control over the header markup.
+- `tbody` — scope: `object` — Replaces the content of the body row group (`.bb-table__body`). Use when you need full control over the body markup. Provide role-complete rows — `<div role="row">` holding one `<div role="cell">` per column — never a `<tr>`/`<td>`. A full-…
+- `tfoot` — scope: `{ columnCount: number; }` — Fills the footer row group (`.bb-table__foot`). Use when you need a footer. Provide role-complete rows — `<div role="row">` holding `<div role="cell">` elements — never a `<tr>`/`<td>`.
+- `thead` — scope: `object` — Replaces the content of the header row group (`.bb-table__head`). Use when you need full control over the header markup. The table is a CSS grid, not a `<table>`: provide role-complete rows — `<div role="row">` holding one `<div role="colum…
 
 ## See Also