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

package/dist/ai/guides/migration/components/bb-table.md

@@ -1,23 +1,26 @@
 ---
 title: 'Migration v2→v3: BbTable'
-summary: 'allowSelectAll inverted to disableSelectAll; loading no longer blanks populated tables and now inerts rows; #loading is first-load-only; #no-data fills a full-width table cell instead of replacing the row; columns gained sortable + rowClass, which collide with same-named consumer fields.'
+summary: 'The table renders as a CSS grid of divs with ARIA roles, not a <table> — every element selector (table/thead/tbody/tr/th/td) under .bb-table matches nothing, #thead/#tbody/#tfoot take role-complete div rows, --fill/--natural-width are gone, column widths drift within documented bounds, copy-to-spreadsheet and print header repetition degrade; allowSelectAll inverted to disableSelectAll; loading no longer blanks populated tables and now inerts rows; #loading is first-load-only; #no-data fills a full-width cell instead of replacing the row; row events drop the selected argument; columns gained sortable + rowClass, which collide with same-named consumer fields.'
 ---
 
 # BbTable — v2 → v3
 
 ## Changes
 
-| v2                                              | v3                                                                                                                                                                                                        | Kind                                                                    |
-| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| `allowSelectAll?: boolean` (default `true`)     | `disableSelectAll?: boolean` (default `false`)                                                                                                                                                            | rename, polarity inverted                                               |
-| refetch with rows → skeleton                    | refetch keeps rows visible (dimmed + progress bar)                                                                                                                                                        | **behavior** — the skeleton only shows when there is nothing to display |
-| rows interactive while loading                  | header + rows go `inert` while loading                                                                                                                                                                    | **behavior** — opt out with `interactive-while-loading`                 |
-| `#loading` slot fired on every load             | fires on the **first load only** (it replaces the skeleton, so it follows the skeleton's rule)                                                                                                            | **⚠ silent** for anyone styling refetches through it                    |
-| `#no-data` replaced the empty-state `<tr>`      | fills the table's own full-width `<td>` (colspan counted, centred)                                                                                                                                        | **behavior** — pass content, not a row                                  |
-| —                                               | props `enforceCoherence` (prunes row-keyed models after each load; incompatible with pagination-via-`dependencies`), `expandedItems` + `#expand`, `sort`, `keyboardNavigation`, `highlighted`, `rowClass` | additive                                                                |
-| —                                               | **column** fields `sortable?: boolean`, `rowClass?: ColumnClasses`                                                                                                                                        | additive, **collides** — see below                                      |
-| `useBbTableContext(id).total` _(v3 alphas ≤ 4)_ | `useBbTableContext(id).totalItems`                                                                                                                                                                        | **hard rename** on the composable handle — see below                    |
-| `--bb-table-*` custom properties                | same names without the `bb-` prefix                                                                                                                                                                       | **⚠ silent** for nested-table layouts — see below                       |
+| v2                                                                                                                    | v3                                                                                                                                                                                                        | Kind                                                                                                    |
+| --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `allowSelectAll?: boolean` (default `true`)                                                                           | `disableSelectAll?: boolean` (default `false`)                                                                                                                                                            | rename, polarity inverted                                                                               |
+| refetch with rows → skeleton                                                                                          | refetch keeps rows visible (dimmed + progress bar)                                                                                                                                                        | **behavior** — the skeleton only shows when there is nothing to display                                 |
+| rows interactive while loading                                                                                        | header + rows go `inert` while loading                                                                                                                                                                    | **behavior** — opt out with `interactive-while-loading`                                                 |
+| `#loading` slot fired on every load                                                                                   | fires on the **first load only** (it replaces the skeleton, so it follows the skeleton's rule)                                                                                                            | **⚠ silent** for anyone styling refetches through it                                                    |
+| `#no-data` replaced the empty-state `<tr>`                                                                            | fills the table's own full-width cell (`aria-colspan` counted, centred)                                                                                                                                   | **behavior** — pass content, not a row                                                                  |
+| `<table>` / `<thead>` / `<tbody>` / `<tr>` / `<th>` / `<td>` markup _(v2 and v3 ≤ beta.5)_                            | a CSS grid of `<div>`s carrying `role="table\|rowgroup\|row\|columnheader\|cell"`; `.bb-table__table` / `__head` / `__body` / `__foot` are the new containers, every `.bb-table*` class survives          | **⚠ silent** for element selectors, `#thead`/`#tbody`/`#tfoot` markup, copy/paste and print — see below |
+| `--fill` / `--natural-width` published on `.bb-table` _(v3 ≤ beta.5)_                                                 | **removed** — nothing publishes them                                                                                                                                                                      | **⚠ silent** — see below                                                                                |
+| —                                                                                                                     | props `enforceCoherence` (prunes row-keyed models after each load; incompatible with pagination-via-`dependencies`), `expandedItems` + `#expand`, `sort`, `keyboardNavigation`, `highlighted`, `rowClass` | additive                                                                                                |
+| —                                                                                                                     | **column** fields `sortable?: boolean`, `rowClass?: ColumnClasses`                                                                                                                                        | additive, **collides** — see below                                                                      |
+| `useBbTableContext(id).total` _(v3 alphas ≤ 4)_                                                                       | `useBbTableContext(id).totalItems`                                                                                                                                                                        | **hard rename** on the composable handle — see below                                                    |
+| `@click:row` / `@contextmenu:row` / `@dblclick:row` handlers receive `(event, item, selected)` _(v2 and v3 ≤ beta.5)_ | `(event, item)` — `item` is now your raw record (was the internal row wrapper, record at `row.item`); the trailing `selected` boolean is gone                                                             | **payload slimmed** — see below                                                                         |
+| `--bb-table-*` custom properties                                                                                      | same names without the `bb-` prefix                                                                                                                                                                       | **⚠ silent** for nested-table layouts — see below                                                       |
 
 ## Columns gained `sortable` and `rowClass` — check yours first
 
@@ -70,7 +73,8 @@ migration. Fix it at the type, not at the call sites:
 `BbTable` coerces the field (`sortable: !!column.sortable` in `BbTable.vue`), so
 **any** truthy value counts — including a sort-key string like
 `'patients.created_at'`. The header stops rendering a plain label and renders a
-`.bb-table-sort` button instead, and the `<th>` gains `aria-sort="none"`. An app
+`.bb-table-sort` button instead, and the header cell (`.bb-table-header`,
+`role="columnheader"`) gains `aria-sort="none"`. An app
 that already ships its own sortable-header UI now draws two.
 
 The damage is bounded: `sort` is a controlled model (`v-model:sort`), so the
@@ -88,8 +92,9 @@ const tableColumns = computed(() =>
 
 Column `rowClass` is the same shape of trap without the type error, because
 `ColumnClasses` already accepts `string`: a leftover `rowClass: 'w-40'` you
-meant for the column typechecks fine and is now merged onto the whole row's
-`<tr>`, alongside the table-level `rowClass` prop. A non-`Classes` shape
+meant for the column typechecks fine and is now merged onto the whole row
+(`.bb-table-data__row`), alongside the table-level `rowClass` prop. A
+non-`Classes` shape
 (`rowClass?: { colspan: number }`) does error, with the same `undefined`
 wording.
 
@@ -127,9 +132,13 @@ first-paint placeholder.
 v2 handed the slot the whole empty-state `<tr>`, so anything that was not a
 row — the usual `<div>` with a message and a "clear filters" button — landed
 loose inside `<tbody>` and rendered left-aligned at content width instead of
-spanning the table. v3 keeps the `<tr>`/`<td>` shell (with the colspan already
-counting the selection and actions columns) and puts the slot inside it, so
-that same markup now centres across the full width.
+spanning the table. v3 owns the row/cell shell itself
+(`.bb-table-no-data__row[role=row]` > `.bb-table-no-data__cell[role=cell]`,
+spanning every column with `grid-column: 1 / -1` and an `aria-colspan` that
+already counts the selection and actions columns) and puts the slot inside it,
+so that same markup now centres across the full width. A v2 `<tr>`/`<td>`
+passed here is not just redundant any more — it is table markup inside a
+grid, which is why the diff below deletes it rather than keeping it.
 
 ```diff
   <BbTable :items="rows" :columns="columns" selectable actions>
@@ -184,6 +193,372 @@ unrelated and does not change.
 `BbPagination` consumers see the same rename through `table-id`; see
 [BbPagination](./bb-pagination.md).
 
+### Row events carry `(event, item)` — your raw record (v3 beta, 2026-08-26)
+
+`click:row`, `contextmenu:row` and `dblclick:row` used to pass **the table's
+internal row wrapper** (cells, classes, selection/highlight/expansion flags,
+value hash — your record buried at `row.item`) plus a third `selected`
+argument. Both are gone: the payload is the native event and **the record
+exactly as you passed it in `items`**, nothing else. Selection state is
+already yours through the `v-model` / `unselected-items` models, so the
+handler read it from a second source of truth — and the owner wants row events
+to carry the row, not a state dump.
+
+```diff
+- <BbTable @click:row="(event, row, selected) => open(row.item, selected)" />
++ <BbTable @click:row="(event, item) => open(item, selectedIds.includes(item.id))" />
+```
+
+Two silent JavaScript failures and one loud one: `row.item` is now
+`undefined` (the record has no `.item` field unless yours does), the third
+parameter is simply `undefined`, and any handler typed against `BbTableEvents`
+with three parameters is a **type error** under `vue-tsc` 3. Grep:
+`rg '(click|contextmenu|dblclick):row' --type vue` and inspect every handler
+for `.item` reads and a third parameter.
+
+## The table is a CSS grid, not a `<table>` (v3 beta, 2026-08-26)
+
+`BbTable` no longer renders a single `<table>` element. The substrate is a CSS
+grid of `<div>`s: the root owns `grid-template-columns` (the column tracks
+_are_ the width API — `columns[].width`, `fixed`, `inherit-column-widths` and
+`snap` all resolve to tracks), and every row group and row is a `subgrid` of
+it, so a cell lands on its column through two levels without a width of its
+own. Nothing about the props, slots, events or models changed for this; what
+changed is everything that touched the **markup** — CSS element selectors,
+the markup you hand to `#thead` / `#tbody` / `#tfoot`, two published custom
+properties, and a handful of things browsers do for real tables that they do
+not do for grids (copy/paste, print, global element CSS).
+
+### What renders now
+
+```
+.bb-table                                   container (div, or fieldset when selectable) — unchanged: [data-bb-table-id], aria-busy, overflow-x: auto
+  legend.sr-only                            (selectable) — unchanged
+  .bb-table-caption[id]                     replaces <caption>; sr-only unless display-caption; sits BEFORE the grid root
+  .bb-table__table[role=table]              grid root — aria-labelledby → the caption, aria-rowcount
+    .bb-table__head[role=rowgroup]          replaces <thead>; goes inert while loading; hosts the busy bar
+      .bb-table-header-row[role=row]
+        .bb-table-header[role=columnheader] (+ --select / --actions / --edge-start / --edge-end, aria-sort)
+    .bb-table__body[role=rowgroup]          replaces <tbody>
+      .bb-table-data__row[role=row]         tabindex / aria-rowindex / aria-current / inert / row events — as before
+        .bb-table-data__cell[role=cell]     (+ --select / --edge-start / --edge-end)
+        .bb-table__cell.bb-table__cell--actions[role=cell]
+      .bb-table-expand__row[role=row]       id="expanded_{hash}" (the aria-controls target) — unchanged
+        .bb-table-expand__cell[role=cell]   aria-colspan=N, grid-column: 1 / -1
+      .bb-table-no-data__row  > .bb-table-no-data__cell[role=cell]      aria-colspan=N, grid-column: 1 / -1
+      .bb-table-skeleton__row > .bb-table-skeleton__cell[role=cell]
+      .bb-table-loading__row  > .bb-table-loading__cell[role=cell] > span.bb-table-loading__text[role=status][aria-live=polite]
+    .bb-table__foot                         replaces <tfoot>; always rendered, role=rowgroup only when #tfoot is provided
+```
+
+**Every `.bb-table*` class survives on the equivalent node** — including the
+asymmetric `bb-table__cell--actions` and the caption's `bb-table-caption` (no
+`__`). The one exception is the transient `bb-table--measuring` state class,
+which was never documented and existed only to hide the old probe's
+scrollbar flash: it is gone with the probe. Four container classes are new: `.bb-table__table`, `.bb-table__head`,
+`.bb-table__body`, `.bb-table__foot`. Every row carries `role="row"`, every
+header cell `role="columnheader"`, every body/foot cell `role="cell"`. The
+role chain `table → rowgroup → row → columnheader|cell` is what assistive
+technology reads as a table; without it the whole tree is a pile of generic
+`div`s. `aria-colspan` replaces the deleted `colspan` on the three full-width
+cells (expand, no-data, loading).
+
+### Selector translation
+
+Element selectors are the break. Nothing throws: a rule on `tbody td` matches
+nothing, the browser applies nothing, and the page renders with the
+override silently missing. Translate every element name under `.bb-table`:
+
+| v2 element                                                      | v3 selector                                                                                                                                       |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `table`                                                         | `.bb-table__table`                                                                                                                                |
+| `thead`                                                         | `.bb-table__head`                                                                                                                                 |
+| `tbody`                                                         | `.bb-table__body`                                                                                                                                 |
+| `tfoot`                                                         | `.bb-table__foot`                                                                                                                                 |
+| `caption`                                                       | `.bb-table-caption`                                                                                                                               |
+| `tr`                                                            | `[role=row]` — or `.bb-table-data__row` for data rows only (the old bare `tr` matched every row kind: header, skeleton, no-data, expand, loading) |
+| `th`                                                            | `[role=columnheader]` / `.bb-table-header`                                                                                                        |
+| `td`                                                            | `[role=cell]` / `.bb-table-data__cell`                                                                                                            |
+| `:first-child` / `:last-child` / `:not(.bb-table-expand__cell)` | **verbatim** — cells stay siblings inside their row                                                                                               |
+| `td:nth-of-type(n)`                                             | `:nth-child(n)` — the children are type-uniform now, so `nth-of-type` and `nth-child` mean the same thing                                         |
+| `colgroup` / `col`                                              | **gone** — use `columns[].width`                                                                                                                  |
+
+`[role=row]`, `[role=cell]` and `[role=columnheader]` are **supported styling
+hooks**, not incidental markup: the role tree is pinned by the component's own
+tests, so a future move to `role="grid"` would be a deliberate selector break,
+not an accident. There are no `data-*` hooks and no shim classes — the roles
+plus the four container classes are the whole translation.
+
+**Specificity caveat.** `[role=cell]` is an attribute selector, specificity
+(0,1,0); `td` was a type selector, (0,0,1). A translated rule is therefore
+_stronger_ than the one it replaces, and an override that used to lose to a
+library rule (or to another of your own rules) by one type-selector point can
+now win. Diff any page where two rules targeted the same cell, and prefer the
+class forms (`.bb-table-data__cell`) when you need the old ordering back.
+
+The library's own body-cell rules are deliberately held at **(0,2,0)** — the
+row step is wrapped in `:where()` — so a scoped override of yours that beat
+the old `.bb-table tbody tr td` (0,1,3) at (0,2,0) or better keeps winning.
+An override written at exactly (0,1,x) (one class plus type selectors) is
+the only band that loses ground: give it one more class.
+
+The one idiom that dominates real apps — a full-bleed table that re-adds the
+page inset on its outermost cells, scoped with direct-child combinators so a
+nested table inheriting the parent's tracks is not touched — translates like
+this:
+
+```diff
+- .table-flush :deep(> table > thead > tr > th:first-child),
+- .table-flush :deep(> table > tbody > tr > td:first-child:not(.bb-table-expand__cell)) {
++ .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(> table > tbody > tr > td.bb-table-expand__cell) {
++ .table-flush :deep(> .bb-table__table > .bb-table__body > [role='row'] > .bb-table-expand__cell) {
+  	padding-inline: 0;
+  }
+```
+
+The direct-child chain matters exactly as before: `.table-flush` lands on the
+container, `.bb-table__table` is its direct child, and a nested table lives
+inside `.bb-table-expand__cell`, so `>` at every step keeps the override off
+the child's cells (whose padding is the alignment mechanism).
+
+Grep for the hits: element names inside `:deep()`, inside `.bb-table` rules,
+and — easy to miss — any **global** table CSS (`table { … }`, `td { padding }`,
+`.prose table`), which reached the v2 markup and now reaches nothing (see
+"Global element CSS" below).
+
+### `#thead` / `#tbody` / `#tfoot` take role-complete rows
+
+These three slots replace a whole row group, and the markup you pass into them
+is now grid markup: a `<div role="row">` per row holding one
+`<div role="columnheader">` (head) or `<div role="cell">` (body, foot) per
+column — **never** a `<tr>` / `<th>` / `<td>`. A `<tr>` inside a grid is not
+just wrong semantically: the `<tr>` is blockified into a single grid item and
+the browser wraps its `<td>`s in an anonymous CSS table (under SSR the parser
+drops the tags outright), so the cells never land on the tracks.
+
+Rows are subgrid rows, so a cell takes the matching column track with no
+width of its own. A cell that spans columns uses `grid-column`, not `colspan`:
+the slot's `columnCount` (total rendered columns, selection and actions
+included) is still handed to `#tfoot`, and it now feeds `grid-column: span N`
+/ `grid-column: 1 / -1` instead of a `colspan` attribute. Add `aria-colspan`
+on a spanning cell so column math stays right for assistive technology.
+
+```diff
+  <template #tfoot="{ columnCount }">
+-   <tr>
+-     <td :colspan="columnCount - 1">Total</td>
+-     <td class="text-right">{{ total }}</td>
+-   </tr>
++   <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 full-width row is `grid-column: 1 / -1` on its single cell (plus
+`aria-colspan="columnCount"`). Keep the invariant the component keeps: no
+role-bearing element between the row group and the row, and every child of a
+row is a `cell` or `columnheader`. **Nothing lints this** — a slot ported to
+`<div>`s without roles renders fine and ships a table screen readers cannot
+read; the docs are the only guard, hence the emphasis.
+
+Two side effects of replacing the header: the table measures its column
+tracks off the header cells, so with a custom `#thead` it falls back to the
+first row with one child per track (the first data row) — **a custom header
+over an empty table publishes no tracks**, and a nested table cannot inherit
+from it until rows arrive. And under `fixed-headers`, a `#thead` with several
+rows now sticks as a block (all rows stack); the old cell-level sticky stacked
+them on top of each other.
+
+### `--fill` and `--natural-width` are removed, not renamed
+
+Both were plumbing for the `table-layout: fixed` self-correction loop (a
+measured natural width the table could never shrink below, and a fill
+correction that compensated fixed-layout arithmetic). The grid has no such
+loop: tracks are sized by the engine from the declarations, in one layout
+pass, with no offscreen probe. Republishing the sum of the resolved tracks
+under the same names would publish the _container_ width under a name
+promising the _natural_ width — wrong by 2× in the panel's probe — so they
+are dropped outright, the same treatment `--available-height` got. No consumer
+outside the component's own stylesheet ever read them; a
+`var(--natural-width)` in your CSS now resolves to its fallback.
+
+### Column widths: what holds and what drifts
+
+Frozen widths (`columns[].width`) hold **exactly**: a `120px` column is
+120px. The overflow threshold (the container width at which the table starts
+scrolling) and the wrap floor (the narrowest a column gets before its text
+wraps) are **pixel-identical** to table auto layout — the panel measured 905px
+against 905px. `fixed` still splits the width equally (`minmax(0, 1fr)` per
+column). Everything else below is documented drift, each with the numbers
+from the panel's probes (`plans/BBTABLE-GRID.md` § Tracks and § v2.1), so
+you know what a screenshot diff is showing you:
+
+- **Roomy containers share the surplus equally, not proportionally to
+  content.** Two auto columns that the table sized 748px / 52px now come out
+  544px / 256px. Short columns get wider; long ones narrower. Add a `width` to
+  any column whose proportion you relied on.
+- **Constrained wrapping distributes differently.** When several wrappable
+  columns compete for a narrow container, tracks grow in equal increments up
+  to their max-content instead of proportionally — the longest column ends up
+  ~22% narrower and its rows taller. The table starts scrolling at the same
+  width as before; only the split before that point moved.
+- **Frozen + auto mixes drift ≤ ~19px per column** — the fixed-layout regime
+  where declared widths sat next to unfrozen ones.
+- **All-frozen tables inflate their data columns exactly as before, but not
+  the structural ones.** When every column declares a width and the sum is
+  below the container, the surplus is still shared in proportion to the
+  declared widths (`[100, 200, 100]` at 600px → `[150, 300, 150]`, `%` too),
+  so the table keeps filling. The selection and actions columns stay at
+  content width instead of inflating with the rest.
+- **A cell that is its own scroll container no longer floors the column.**
+  Under table auto layout an `overflow: hidden` / `auto` cell still
+  contributed its content width to the column. Under grid it does not — which
+  means native `text-overflow: ellipsis` finally works in a cell — **and the
+  classic table trick `max-width: 0` breaks**: the cell collapses to its
+  padding. Delete every `max-width: 0` you added to make ellipsis work.
+- **Percentage widths in an overflowing table resolve against the grid's
+  min-content width**, not the container: a `30%` column that the table gave
+  181px gets 303px once the table overflows. Non-overflowing tables are
+  identical. (`width: fit-content` on the grid root keeps the root's box
+  covering its tracks only without `%` tracks under overflow — a `%`-wide
+  overflowing table is the one case where row backgrounds can paint short of
+  the scroll width.)
+- **Expand-row content never widens the parent's columns.** A wide nested
+  table or a long unbroken string in `#expand` used to push an auto-layout
+  parent's columns apart (a 300px track became 500px in the probe); the grid
+  contains the full-width cells (`contain: inline-size`), so the parent's
+  tracks hold and the content overflows into the scrollport instead. Fixed
+  layout was already immune; auto layout was not; the grid always is.
+- **A `snap` on a column whose table has no parent** used to fall into an
+  accidental equal split. It now sizes like any other unfrozen column
+  (`auto`).
+- **Nested tables align by contract, at any depth.** A child's select/actions
+  cell is widened to the parent's region (`minmax(region, max-content)` — two
+  equal cells, controls at the row's end); a child without one folds the
+  region into its edge cell's padding. A child cell _wider_ than the parent's
+  is reclaimed from the adjacent content column only. What each table
+  publishes to its own children is the pure content rails plus the two
+  regions, so a grandchild aligns with the root — previously the middle
+  table's padding compensation was invisible to its children. The fill
+  column now only ever grows (`minmax(<its rail>, 1fr)`); it no longer
+  shrinks to absorb a wider actions column.
+
+### Copy-to-spreadsheet degrades
+
+Selecting rows in a real `<table>` and pasting into a spreadsheet gave one
+cell per column. Chrome's selection serializer keys off the computed
+`display`, not the element or its role, so a grid pastes **one value per
+line** — the columns are lost. Accepted: the substrate is not going to carry a
+hidden `<table>` for the clipboard. The sanctioned path is an app-level
+"copy as TSV" action built from the **items model** (the same rows you gave
+`items`, joined with tabs and newlines and written with `navigator.clipboard`)
+— a recipe for it is queued (FOLLOWUPS Q7.4); do not scrape the DOM for it.
+
+### Print: header repetition is gone
+
+Browsers repeat a `<thead>` at the top of every printed page; there is no
+grid equivalent, so a long table prints its header once. Data rows carry
+`break-inside: avoid` so a row is never split across pages, which is the most
+the substrate can do. No `@media print` rule exists in the library, so nothing
+of yours is fighting one — but if a printed report depended on the repeated
+header, that is a real regression to plan for (a print-specific view, or
+paginated sections with their own headers).
+
+### Global element CSS no longer reaches the table
+
+Any CSS that reached `BbTable` through element names now misses it: a reset
+(`table { border-collapse: … }`, `td, th { padding: 0 }`), Tailwind's
+`.prose table` typography, a stray `td { vertical-align: top }` in a legacy
+sheet. This cuts both ways. It is an **immunity** — the table no longer
+inherits whatever global table styling the app carries — and it is a **silent
+change** on every page where that global CSS was, knowingly or not, part of
+the look. Diff those pages; then re-express what you actually wanted on
+`.bb-table-data__cell` / `[role=cell]` scoped to a table.
+
+### Browser floor
+
+The table requires `grid-template-columns: subgrid`: **Chrome/Edge 117,
+Firefox 71, Safari 16**. There is no `@supports` fallback and none is planned —
+maintaining two substrates defeats the rewrite. Cell content is centred
+vertically with `align-content` on a block container, which lands one notch
+higher: **Chrome 123, Safari 17.4, Firefox 125**. Below that, cells still lay
+out correctly but content sits at the top of the cell instead of the middle.
+
+All of this sits inside the library-wide floor — **Chrome/Edge 114, Safari 17,
+Firefox 125**, set by the native Popover API (see
+`installation-and-plugin-setup.md` § Browser support) — so the only engine the
+grid actually raises is Chrome/Edge, 114 → 117 (123 for centred cells).
+
+### Do not override
+
+- **Do not hide cells with `display: none`** (a `thClass`/`tdClass` of
+  `hidden`, the v2/early-v3 narrow-screen recipe). A hidden grid item leaves
+  its track in place: every following cell shifts one track over and the last
+  track collapses. Hide a column by removing it from `columns` at the
+  breakpoint, which removes the track.
+- **`contain: inline-size` on `.bb-table-expand__cell`,
+  `.bb-table-no-data__cell` and `.bb-table-loading__cell`.** It is the only
+  thing keeping a full-width cell's content from resizing the column tracks —
+  `min-width: 0` and `width: 100%` wrappers do not work here, and with a nested
+  inheriting table inside the expand row the result without it is a feedback
+  loop. Removing it (or setting `contain: none` on a cell) is not a styling
+  choice.
+- **`gap: 0` on `.bb-table__table`.** A gap set on the root cannot be undone
+  from a subgrid level; it opens gutters between every column.
+- **`display: grid` on the root, row groups and rows**, and the
+  `grid-column: 1 / -1` on the full-width cells — the geometry.
+- **`white-space: nowrap` on `.bb-table__cell--actions`** — the actions track
+  is `max-content`, and `nowrap` is what makes that the width of the controls
+  side by side rather than a wrapped stack.
+- **`position: sticky` on `.bb-table__head`** under `fixed-headers`: sticky
+  lives on the row group, not on cells — a sticky cell inside the subgrid
+  cannot stick in any engine.
+
+### Small semantic and visual changes
+
+- **Pinned cells and the stuck header are opaque.** `fixed-columns` cells and
+  the `fixed-headers` band used to be transparent, so scrolled content showed
+  through them. They now paint the table's surface local `--bg` (default
+  `var(--bb-panel)`); a pinned cell also paints its row's hover/highlight
+  tint. On a non-panel surface set `.bb-table { --bg: … }` once. The
+  highlighted row's left accent bar moved from the row onto its first cell
+  (same position; an opaque pinned first column would have hidden it).
+- **The sort glyph is one arrow.** The two-chevron `sort.svg` (with its
+  inner `sort-icon__asc` / `sort-icon__desc` paths) is gone; the sort button
+  renders an inline `<svg class="bb-table-sort__icon">` — a single arrow,
+  hidden at rest, faint on hover/focus, solid when sorted: up for ascending,
+  rotated down for descending (the AG Grid convention). Apps that copied the old glyph to rebuild
+  a header no longer need to (use the header prepend/append slots); any CSS
+  on `.sort-icon__asc` / `.sort-icon__desc` matches nothing.
+- **Caption reading order.** The caption is now a `div` _before_ the table
+  role, named through `aria-labelledby`, rather than a `<caption>` inside it.
+  The accessible name is identical; a screen reader reading linearly meets the
+  caption text just before the table instead of as its first child.
+- **The busy bar rides with a stuck header.** With `fixed-headers`, the
+  refetch progress bar is anchored to the sticky head row group, so it stays
+  at the header/body boundary while you scroll. It used to anchor to the
+  in-flow `<thead>` box and scroll away while the header cells stuck — the
+  documented intent, now the behavior.
+- **Multi-row `#thead` heads stack when stuck** (above).
+- **`aria-rowcount` now counts the header row**: it is `totalItems + 1`, so
+  the last row's `aria-rowindex` no longer exceeds the count. Anything
+  asserting the old value must add one.
+- **Row heights change with the wrapping drift** — expect it in screenshot
+  diffs of narrow, text-heavy tables.
+
 ## The custom properties the table _publishes_ lost the `bb-` prefix
 
 These are not theming inputs — they are values `BbTable` measures at runtime and
@@ -191,18 +566,21 @@ writes onto its own DOM, for the table's CSS and for descendants to read. You
 reach for them for exactly one reason: aligning a nested table's columns to its
 parent's. They all dropped the prefix.
 
-| v2                                          | v3                                          |
-| ------------------------------------------- | ------------------------------------------- |
-| `--bb-table-{id}-track-{key}`               | `--table-{id}-track-{key}`                  |
-| `--bb-table-offset-start` / `-end`          | `--offset-start` / `--offset-end`           |
-| `--bb-table-offset-internal-start` / `-end` | `--offset-internal-start` / `-internal-end` |
-| `--bb-table-offset-external-start` / `-end` | `--offset-external-start` / `-external-end` |
-| `--bb-table-fill`                           | `--fill`                                    |
-| `--bb-table-natural-width`                  | `--natural-width`                           |
-| `--bb-table-cell-h`                         | `--cell-h`                                  |
+| v2                                          | v3                                                 |
+| ------------------------------------------- | -------------------------------------------------- |
+| `--bb-table-{id}-track-{key}`               | `--table-{id}-track-{key}`                         |
+| `--bb-table-offset-start` / `-end`          | `--offset-start` / `--offset-end`                  |
+| `--bb-table-offset-internal-start` / `-end` | `--offset-internal-start` / `-internal-end`        |
+| `--bb-table-offset-external-start` / `-end` | `--offset-external-start` / `-external-end`        |
+| `--bb-table-fill`                           | **removed** (was `--fill` in v3 ≤ beta.5)          |
+| `--bb-table-natural-width`                  | **removed** (was `--natural-width` in v3 ≤ beta.5) |
+| `--bb-table-cell-h`                         | `--cell-h`                                         |
 
 Only the track bridge keeps a `table-` segment, because it crosses component
-boundaries; the rest are plain locals on `.bb-table`. `--padding-x`,
+boundaries; the rest are plain locals on `.bb-table`. `--fill` and
+`--natural-width` were the fixed-layout self-correction values; the grid
+substrate (next section) has no such loop, so they are gone rather than
+republished under a name that would lie about what they hold. `--padding-x`,
 `--padding-y` and `--actions-spacing` were already unprefixed in v2 and keep
 their names (their _values_ tightened: `16px`/`8px` → `12px`/`6px`, and the cell
 height `42px` → `36px`).