bitboss-ui 3.0.0-beta.2 → 3.0.0-beta.21

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

@@ -1,23 +1,30 @@
 ---
 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`, `order` (v-model) + `reorderable`, `resizable` + `resize:column`, header-slot `hideColumn()` + `hide:column`, `fixedSelect` / `fixedActions` | additive                                                                                                |
+| —                                                                                                                                                             | **column** fields `sortable?: boolean`, `rowClass?: ColumnClasses`, `hidden?: boolean` (the column stays declared — the way to hide, see § Do not override), `fixed?: 'left' \| 'right'` (replaces `fixedColumns`, see below)                                                                                                                           | additive, **collides** — see below                                                                      |
+| `actions?: boolean` prop _(v2 and v3 ≤ beta.20)_                                                                                                              | **removed** — the `#actions` slot creates the column by itself                                                                                                                                                                                                                                                                                          | **⚠ silent** if you passed the prop without the slot — see below                                        |
+| `fixedColumns` prop (rendered-slot indices, `[0, { index, position }]`) _(v2 and v3 ≤ beta.20)_                                                               | **removed** — `fixed: 'left' \| 'right'` on the column definition, `fixed-select` / `fixed-actions` for the structural columns                                                                                                                                                                                                                          | **⚠ silent** — see below                                                                                |
+| column `snap?: number \| [number, number]` — gridline indices into the parent's rendered columns (`select` at 0, fractions, `-1` = data end) _(v3 ≤ beta.20)_ | `snap?: string \| [string, string]` — the PARENT's column key, or `'select'` / `'actions'`; a pair is inclusive; `'amount.5'` is a fraction. Same-key columns pair by default. Ignored (dev warning) under a parent that uses `order` / `reorderable`                                                                                                   | **⚠ silent** — see below                                                                                |
+| `--table-{id}-track-{index}` published per data column _(v3 ≤ beta.20)_                                                                                       | `--table-{id}-track-{key}` — the column key in its slot-name spelling (`address_city`); `select` / `actions` unchanged                                                                                                                                                                                                                                  | **⚠ silent** for CSS that read the vars by index — 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 +77,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 +96,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.
 
@@ -122,14 +131,125 @@ If you used `#loading` to show a custom refetch treatment, that role is gone —
 the built-in dim + progress bar covers refetches; `#loading` is now only the
 first-paint placeholder.
 
+### The `#actions` slot creates the actions column — the prop is gone (v3 beta, 2026-09-07)
+
+`actions` used to be a boolean prop that rendered the column, with the
+`#actions` slot filling it. The prop carried no information the slot did
+not, and it had a footgun: a consumer who declared `{ key: 'actions' }` in
+`columns` instead of setting the prop got a stray empty data cell and a slot
+that never rendered. Now the slot alone creates the column — header cell
+(labelled by `actions-text`, replaceable through `#header:actions`), one
+cell per row, and the `actions` track for nested tables — and removing the
+slot (or gating it with `v-if`) removes the column live.
+
+```diff
+- <BbTable actions :columns="columns" :items="rows">
++ <BbTable :columns="columns" :items="rows">
+    <template #actions="{ item }">…</template>
+  </BbTable>
+```
+
+Delete the attribute. The removed-prop warner flags it in dev, the ESLint rule
+flags it in-editor. The only silent case is a table that set `actions`
+without ever providing the slot: it had an empty column, and now it does not.
+
+### `fixedColumns` → `fixed` on the column, `fixed-select` / `fixed-actions` (v3 beta, 2026-09-07)
+
+Pins used to be **slot indices** into the rendered column list (a selection
+column was index 0), like spreadsheet freeze panes: with `order` and
+`reorderable` the pinned _slot_ held and whichever column landed in it was
+pinned, which is fragile once users drag headers and hide columns. Pins are
+now a property of the column, the way `width` and `hidden` are, and follow
+it through reorders. The sticky behaviour itself is unchanged: in place, at
+the column's own render position, offset by the pinned columns before it on
+the same side.
+
+```diff
+- <BbTable
+-   :columns="columns"
+-   :fixed-columns="[0, { index: columns.length + 1, position: 'right' }]"
+-   selectable
+- >
++ <BbTable :columns="columns" fixed-select fixed-actions selectable>
+    <template #actions="{ item }">…</template>
+  </BbTable>
+```
+
+```diff
+  const columns = [
+-   { key: 'name', label: 'Name' },
++   { key: 'name', label: 'Name', fixed: 'left' },
+    { key: 'amount', label: 'Amount', align: 'right' },
+  ];
+```
+
+Translate each index to the column that sat there: data columns get
+`fixed: 'left' | 'right'` on their definition, the selection column becomes
+`fixed-select`, the actions column `fixed-actions` (each has one sensible
+side, so they are booleans). A nested table that pinned its own actions with
+`{ index: childColumns.length, position: 'right' }` now says
+`fixed-actions`. Silent on upgrade: the old prop is ignored (the warner and
+the ESLint rule flag it), so a table that pinned columns stops pinning until
+you move the pins onto the definitions.
+
+### `snap` names the parent column, not a gridline (v3 beta, 2026-09-07)
+
+A nested table's `snap` was a number: a gridline index into the parent's
+rendered columns, with the selection column at `0`, fractions for partial
+tracks and `-1` for the end of the data region. Index `k` was whatever column
+happened to render there, so a reorder or a hidden column on the parent
+moved every snap. The parent now publishes its tracks under **column keys**,
+and `snap` names the parent column:
+
+```diff
+  const holdings = [
+-   { key: 'name', label: 'Resource', snap: 1 },
+-   { key: 'kind', label: 'Type', snap: 2 },
+-   { key: 'monthlyCost', label: '$ / mo', align: 'right', snap: [3, 4.5] },
++   { key: 'name', label: 'Resource', snap: 'name' },
++   { key: 'kind', label: 'Type', snap: 'team' },
++   { key: 'monthlyCost', label: '$ / mo', align: 'right', snap: ['region', 'monthly.5'] },
+  ];
+```
+
+- Translate each index to the parent column that rendered there. The
+  selection column is `'select'`, the actions column `'actions'` — both are
+  targets by name, so `['name', 'actions']` runs a child column across the
+  parent's actions cell.
+- A pair is **inclusive**: `['client', 'amount']` spans from the start of
+  `client` through the end of `amount` (the old `[a, b]` ended at the start
+  of `b`). A trailing `.digits` on a key is a fraction of that track. `-1`
+  is gone: the last column already runs to the end of the data region unless
+  it declares a `width` or a pair.
+- A child column with no `snap` now pairs with the parent column of the
+  **same key** when there is one, so most children need no snaps at all; a
+  column the parent lacks (or hides) flows into the next free parent track.
+- Under a parent that uses `order` or `reorderable`, snaps and key pairing
+  are ignored (dev builds warn) and the child inherits by position, as it
+  always did — a moving parent can only be followed slot by slot.
+
+Silent on upgrade: a numeric `snap` fails the type check but is ignored at
+runtime, so the child falls back to key pairing and flow, which for a child
+sharing the parent's keys is the same alignment as before.
+
+**The published track variables changed name with it.** `--table-{id}-track-{k}`
+per data column became `--table-{id}-track-{key}`, the key in its slot-name
+spelling (`address.city` → `address_city`); `select` and `actions` are
+unchanged. Consumer CSS that read the numbered variables directly has to
+switch to the keys. Nothing else about the bridge moved.
+
 ### `#no-data` is content, not a row
 
 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 +304,415 @@ 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.
+
+### Highlight is opt-in — bind `ref(null)`, not `ref()` (v3 beta, 2026-08-27)
+
+Row highlight used to run whether or not you bound it. With nothing bound the
+table wrote to `defineModel`'s **local** fallback, so clicking any row applied
+`bb-table-data__row--highlighted` and `aria-current="true"` and drove a state
+your app could neither read nor clear. Invisible while the class shipped
+unstyled; once a default cursor shipped, every table in the app started tinting
+rows on click.
+
+Highlight is now inert until something is connected, and **the model's value is
+the switch**: `undefined` means "never initialised" (off), `null` means
+"initialised and currently empty" (on).
+
+```diff
+- const highlighted = ref();
++ const highlighted = ref(null);
+  // <BbTable v-model:highlighted="highlighted" … />
+```
+
+A bound-but-`undefined` model **warns in dev** naming the fix, so this does not
+fail silently. A value seeded through the context counts the same and needs no
+prop:
+
+```ts
+const highlighted = ref(null);
+useBbTableContext('invoices-table', { highlighted });
+```
+
+Two things that did **not** change: `click:row` still fires on every row click,
+connected or not — if you only wanted click notifications you never needed the
+model and nothing breaks; and a table that already binds a real value or `null`
+behaves exactly as before.
+
+What to check: any table relying on the free highlight **without** binding the
+model — styling `.bb-table-data__row--highlighted` yourself, or reading
+`aria-current` in a test or E2E selector. Those now need the model bound.
+`rg 'bb-table-data__row--highlighted|aria-current' --type vue --type css` and
+keep the hits on tables whose `highlighted` is unbound. A `toggleHighlighted`
+call from a cell slot on an unconnected table does nothing and warns once.
+
+## 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 with `hidden: true` on its definition at the
+  breakpoint, which removes the track while the column stays declared (so
+  its slot in `order` survives). Filtering it out of `columns` was the
+  interim advice and is now reserved for a column that does not exist for
+  this user at all.
+- **`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.** Pinned (`column.fixed`) 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 +720,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`).