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

package/dist/ai/guides/migration/components/bb-text-input.md

@@ -7,12 +7,12 @@ summary: The type prop narrows to the text-like input types — number/date valu
 
 ## Changes
 
-| v2                                                                               | v3                                                                           | Kind                                                                                                                                                                                                      |
-| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `type?: HTMLInputElement['type']` (any string)                                   | `type?: 'text' \| 'email' \| 'url' \| 'tel' \| 'search' \| 'password'`       | retype — other values fail to compile                                                                                                                                                                     |
-| `direction?: string`-ish                                                         | `InputDirection` (`'auto' \| 'horizontal' \| 'vertical' \| '<n> <m>'` ratio) | family-wide retype — typos now fail to compile                                                                                                                                                            |
-| imperative template-ref API (`inputRef.value.focus()` / `.blur()` / `.select()`) | removed                                                                      | no consumer-facing expose; use the native `autofocus` prop, or reach the underlying `<input>` for the rare programmatic focus. **⚠ silent**: a stale `inputRef.value?.focus()` is `undefined` at runtime. |
-| —                                                                                | `description`, extra keyboard/composition events                             | additive                                                                                                                                                                                                  |
+| v2                                                                               | v3                                                                                                                                                               | Kind                                                                                                                                                                                                      |
+| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type?: HTMLInputElement['type']` (any string)                                   | `type?: 'text' \| 'email' \| 'url' \| 'tel' \| 'search' \| 'password'`                                                                                           | retype — other values fail to compile                                                                                                                                                                     |
+| `direction?: string`-ish                                                         | `InputDirection` (`'auto' \| 'horizontal' \| 'vertical' \| 'xx xxxx'`) — in a two-token pattern the tokens' **character counts** are the ratio, not their values | family-wide retype — typos now fail to compile                                                                                                                                                            |
+| imperative template-ref API (`inputRef.value.focus()` / `.blur()` / `.select()`) | removed                                                                                                                                                          | no consumer-facing expose; use the native `autofocus` prop, or reach the underlying `<input>` for the rare programmatic focus. **⚠ silent**: a stale `inputRef.value?.focus()` is `undefined` at runtime. |
+| —                                                                                | `description`, extra keyboard/composition events                                                                                                                 | additive                                                                                                                                                                                                  |
 
 ## Edits
 

package/dist/ai/guides/migration/v2-to-v3.md

@@ -62,8 +62,12 @@ explicitly (section 8).
 ### What v2 looked like
 
 v2 was a plain ESM library: named exports, one manual CSS import, optional
-manual directive registration. There was no Vite plugin, no Nuxt module, and
-no `app.use`.
+manual directive registration. There was no Vite plugin and no `app.use`.
+
+Nuxt apps were the exception: they installed a **separate companion package**,
+`@bitboss-dev/bitboss-ui-nuxt`, which wrapped v2 in a Nuxt module. v3 absorbs
+that package — the module now ships inside the library as `bitboss-ui/nuxt`.
+See [Nuxt](#nuxt) below for the option-by-option move.
 
 ```ts
 // v2 main.ts
@@ -173,8 +177,7 @@ nothing else about the plugin changes.
 
 ### Nuxt
 
-v2 had no Nuxt story. v3 ships a module that does both halves — do **not**
-also call `app.use`:
+v3 ships a module that does both halves — do **not** also call `app.use`:
 
 ```ts
 // v3 nuxt.config.ts
@@ -186,6 +189,57 @@ export default defineNuxtConfig({
 });
 ```
 
+#### Coming from `@bitboss-dev/bitboss-ui-nuxt`
+
+That package was the v2 Nuxt story. It is superseded: **uninstall it** and
+delete it from `modules`. Everything it did is now inside `bitboss-ui/nuxt`,
+under the same `bitboss` config key — so the migration is mostly renaming keys,
+not rewriting setup.
+
+| `@bitboss-dev/bitboss-ui-nuxt` option | v3 `bitboss-ui/nuxt`                                                                                                                                                    |
+| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `icons.path`                          | `iconDir`. Same job, one level up.                                                                                                                                      |
+| `icons.enabled: false`                | **Gone** — the icon pipeline is not optional in v3; components import the virtual icon module. Point `iconDir` at an empty folder if you ship no local art.             |
+| `styles.enabled`                      | `injectStyles` (still defaults `true`).                                                                                                                                 |
+| `styles.index`                        | **Gone**, and nothing replaces it — see the ordering note below.                                                                                                        |
+| `link.name`                           | `nuxtLinkName` (still defaults `'NuxtLink'`).                                                                                                                           |
+| `link.enabled: false`                 | **Gone.** The runtime plugin only registers the configured name when the app has not already claimed it, so there is nothing to switch off.                             |
+| `components.enabled`                  | `autoImport` — see below. Note the **default flipped**: v2's module auto-imported components, v3 does not.                                                              |
+| `components.validation: true`         | `autoImport: { validated: true }`, or explicit imports from `bitboss-ui/validated`. The wrappers moved into the library and gained `BbForm` + `useValidatedField`.      |
+| `components.requiredAsterisk`         | `requiredAsterisk`, same meaning, one level up.                                                                                                                         |
+| `composables`                         | Folded into `autoImport`. `useBroadcastChannelInstance`, `useQueue` and `useWizard` are **not exported by v3** — the module registered names the library no longer has. |
+| `logLevel`                            | **Gone.** The v3 module has nothing to log at setup; build-plugin diagnostics go through Vite.                                                                          |
+
+**⚠ silent — auto-imports are off by default.** The v2 module registered every
+`Bb*` component with Nuxt, so templates used them with no import line. v3 does
+not: an unmigrated template compiles, and each unresolved `<BbButton>` renders
+as an empty unknown element with no error anywhere. Either add explicit imports,
+or opt back in:
+
+```ts
+// v3 nuxt.config.ts — the closest equivalent of the v2 module's defaults
+export default defineNuxtConfig({
+	modules: ['bitboss-ui/nuxt'],
+	bitboss: {
+		iconDir: './assets/icons',
+		autoImport: { validated: true }, // drop `validated` if you had no vee-validate
+	},
+});
+```
+
+Set `"vueCompilerOptions": { "checkUnknownComponents": true }` in `tsconfig.json`
+before you start either way — it is what turns that silent empty element into a
+`vue-tsc` error naming the file and line.
+
+**Style ordering.** `styles.index` let you splice `bitboss-ui/styles.css`
+anywhere in Nuxt's `css` array. v3 injects the sheet at runtime and always puts
+it **first** in `<head>`, ahead of every other stylesheet — so your own CSS is
+always later and always wins, which is the order `styles.index` was normally
+used to obtain. If you need the opposite (library rules winning over yours),
+raise specificity in your own sheet rather than reordering; if you genuinely
+need the library sheet elsewhere in the cascade, set `injectStyles: false` and
+import `bitboss-ui/styles.css` yourself at the position you want.
+
 ### Inertia
 
 Inertia apps configure `bitboss-ui/vite` exactly like plain Vite, install
@@ -238,6 +292,23 @@ bitbossUi({
 useBbConfig().setConfig({ locale: 'en' });
 ```
 
+**Under SSR, set the locale where the app is created.** The runtime config is
+held **per Vue app** (3.0.0-beta.15), and SSR builds one app per request, so
+this is per-visitor and correct on the first paint — which is what crawlers
+index and what a JS-disabled reader keeps:
+
+```ts
+const app = createSSRApp(App);
+app.use(bitbossUiPlugin, { locale: localeFor(request) });
+```
+
+`setConfig` still works for runtime switching. During a server render, call it
+from a component's `setup` so it can resolve the current app; from module scope
+there is no app to address, the write lands on the build-time defaults shared
+by the whole process, and it warns in dev. (Before beta.15 the config was a
+single process-global object, so a per-visitor locale was not possible at all —
+if you carried a workaround for that, you can drop it.)
+
 | v2 `setConfig` key                            | Where it goes in v3                                                            |
 | --------------------------------------------- | ------------------------------------------------------------------------------ |
 | `locale`                                      | stays runtime (`setConfig`) — the only survivor                                |
@@ -314,19 +385,30 @@ to the rename map and to every grep below — see
 | `--bb-hint`, `--bb-icon-color`, `--bb-placeholder`, `--bb-prefix-color`, `--bb-muted-color`                                                                            | `--bb-text-muted`                                                                                                                                                                                                                                                                                                                                          |
 | `--bb-input-color`, `--bb-input-bg`                                                                                                                                    | `--bb-text`, `--bb-panel`                                                                                                                                                                                                                                                                                                                                  |
 | `--bb-input-font-size`, `--bb-input-mobile-font-size`                                                                                                                  | `--bb-input-fs`, `--bb-input-fs-mobile`                                                                                                                                                                                                                                                                                                                    |
+| `--bb-label-size`                                                                                                                                                      | `--bb-label-fs`                                                                                                                                                                                                                                                                                                                                            |
+| `--bb-label-compact-spacing-y`                                                                                                                                         | `--bb-label-spacing-y-compact`                                                                                                                                                                                                                                                                                                                             |
+| `--bb-input-compact-h`, `--bb-input-compact-py`                                                                                                                        | `--bb-input-h-compact`, `--bb-input-py-compact` — the `compact` qualifier moved from infix to suffix                                                                                                                                                                                                                                                       |
+| `--bb-input-compact-px`, `--bb-input-compact-prefix-w`, `--bb-input-compact-floating-py`, `--bb-input-prefix`, `--bb-input-prefix-px`                                  | **deleted, no counterpart.** v3's compact mode re-points only height and vertical padding (the two tokens in the row above); horizontal padding and the prefix column keep their normal-size values, and the prefix's own font-size/padding knobs are gone.                                                                                                |
 | `--bb-overlay-color` + `--bb-overlay-opacity`                                                                                                                          | `--bb-overlay` (one color with alpha)                                                                                                                                                                                                                                                                                                                      |
 | `--bb-overlay-z-index`                                                                                                                                                 | `--bb-z-overlay`                                                                                                                                                                                                                                                                                                                                           |
 | _(no v2 equivalent)_                                                                                                                                                   | `--bb-ease` — new in v3. v2 hard-coded seven different `cubic-bezier()` curves and exposed no easing token, so there is nothing to rename; set `--bb-ease` once if you want a house curve.                                                                                                                                                                 |
-| `--bb-dialog-px`, `--bb-dialog-py`                                                                                                                                     | `--bb-panel-p` — **one value on both axes**, for dialogs and off-canvas alike. If your v2 px ≠ py, see "Asymmetric surface padding" below.                                                                                                                                                                                                                 |
+| `--bb-dialog-px`, `--bb-dialog-py`                                                                                                                                     | the local pair `--px` / `--py` on `.bb-dialog` / `.bb-offcanvas` — a direct map, set on the component's class (never `:root`). Both branch off `--bb-panel-p`, so if your v2 px = py, set `--bb-panel-p` alone. See "Asymmetric surface padding" below.                                                                                                    |
 | `--bb-dialog-close`                                                                                                                                                    | **delete it** — do not map it onto `.bb-close-button { --size }`; v3's default already reproduces the v2 control. See below.                                                                                                                                                                                                                               |
 | `--bb-dialog-title-size`                                                                                                                                               | the local `--dialog-title-fs` on `.bb-dialog` / `.bb-offcanvas` (default `calc(var(--bb-fs) + 2px)`)                                                                                                                                                                                                                                                       |
 | `--bb-dialog-title-weight`                                                                                                                                             | **no knob** — the title is hardcoded `font-weight: 500`. Override with a CSS rule, see below.                                                                                                                                                                                                                                                              |
 | `--bb-button-h`, `--bb-button-icon`, `--bb-checkbox-*`, `--bb-radio-*`, `--bb-switch-*`, `--bb-rating-*`, `--bb-slider-*`, `--bb-table-cell-h`, `--bb-select-option-*` | **no longer global.** Component dimensions hang off `--bb-control-h`, `--bb-fs`, `--bb-radius`; anything finer is an unprefixed local on the component's own class — with one exception: `--bb-select-option-px/-py` have **no** v3 local, the listbox option's inline padding is a literal (`.bb-listbox__option { padding-inline: … }` in your own CSS). |
 
-**`--bb-input-*` and `--bb-label-*` are NOT in the row above.** They are still
-global v3 theme tokens, declared in `variables.css` and read across the whole
-form family — do not delete them. Several changed their default value; the
-drift table below lists which.
+**Most `--bb-input-*` and `--bb-label-*` tokens survive — but only these
+exact names:** `--bb-input-h`, `--bb-input-px`, `--bb-input-py`,
+`--bb-input-spacing`, `--bb-input-icon`, `--bb-input-prefix-w`,
+`--bb-label-spacing-x`, `--bb-label-spacing-y`, `--bb-label-weight`,
+`--bb-leading`. Those are still global v3 theme tokens, declared in
+`variables.css` and read across the whole form family — do not delete them
+(several changed default value; the drift table below lists which). Everything
+else in the two families either renamed (`--bb-label-size` → `--bb-label-fs`,
+the compact pair — rows above) or is deleted outright, so a declaration that
+is not in this list and not in the rename map is inert: it looks correct and
+does nothing. §8's retired-token grep catches every deleted name.
 
 **When a v2 global becomes a component token, resize only what you use.** That
 last row is the trap: a v2 global like `--bb-button-icon` had ONE value for
@@ -347,50 +429,59 @@ doctrine in `design-tokens.md` § "Overriding one from a consumer app". And chec
 first whether the v2 value was a real customisation: if it merely restated v2's
 default, the migration is to **delete it** and inherit the v3 scale.
 
-**Asymmetric surface padding.** `--bb-panel-p` is a single value used on both
-axes. If your v2 theme set `--bb-dialog-px` ≠ `--bb-dialog-py`, set
-`--bb-panel-p` to the **horizontal** value (it also positions the close button)
-and override the vertical with a normal `padding` rule on the part classes.
-There is no `--bb-panel-px` / `--bb-panel-py` pair.
+**Asymmetric surface padding.** v3 splits the axes with the local pair
+`--px` / `--py`, declared on both surface roots (`.bb-dialog`,
+`.bb-offcanvas`) and each branching off `var(--bb-panel-p)`. Like every
+unprefixed component token, you override them _on the component's class_,
+never `:root`. v2's `--bb-dialog-px` / `--bb-dialog-py` map onto them
+directly:
 
 ```css
-/* v2: --bb-dialog-px: 24px; header --bb-dialog-py: 10px; body --bb-dialog-py: 20px */
+/* v2: --bb-dialog-px: 24px; --bb-dialog-py: 10px */
 .my-dialog {
-	--bb-panel-p: 24px; /* horizontal + close-button inset */
+	--px: 24px; /* horizontal padding + the close button's inline inset */
+	--py: 10px; /* vertical padding + the close button's block inset */
 }
+```
+
+Setting only `--bb-panel-p` still moves both axes together (the pair defaults
+to it, resolved on the component root, so a scoped `--bb-panel-p` override
+keeps working too). Per-**part** asymmetry (header `py: 10px`, body
+`py: 20px`) works by scoping the token to the part class — the padding rules
+resolve it on the part elements and the pair inherits:
+
+```css
 .my-dialog .bb-dialog__header {
-	padding-block: 10px 5px;
+	--py: 10px; /* header block padding (bottom is py/2); × inset follows */
 }
-.my-dialog .bb-dialog__body .bb-dialog__body-content {
-	padding-block: 0 20px;
-}
-.my-dialog .bb-dialog__body:first-child .bb-dialog__body-content {
-	padding-top: 20px;
-}
-.my-dialog .bb-dialog__footer {
-	padding-block: 20px;
+.my-dialog .bb-dialog__body-content {
+	--py: 20px; /* body bottom padding, and its top in the headerless case */
 }
 ```
 
-Use `padding-block`, not the `padding` shorthand, so the horizontal half keeps
-tracking `--bb-panel-p`. Specificity: the library rules are
-`.bb-dialog .bb-dialog__header` (0,2,0), `.bb-dialog__body-content` (0,1,0) and
-`.bb-dialog__body:first-child .bb-dialog__body-content` (0,2,1) — the
-three-class app selectors above beat all of them. `BbOffCanvas` is identical
-with `.bb-offcanvas__*`.
-
-**`--px` and `--pt` are not dialog knobs.** `.bb-dialog` declares them, but
-nothing in the dialog or off-canvas CSS reads them, and every component that
-_does_ read `--px` (`BbButton`, `BbAlert`, `BbTooltip`, `BbBaseSlider`)
-re-declares it on its own root class, so an ancestor value never reaches those
-either. Setting `--px` on a dialog part is inert — it silently leaves the
-horizontal padding at whatever `--bb-panel-p` resolves to.
+Derived spacings scale with it — the header's bottom padding is `py / 2` and
+the close button's block inset tracks the header's `py`. If you need exact
+literals instead of those ratios, a `padding-block` rule on the part class
+still works (use `padding-block`, not the `padding` shorthand, so the
+horizontal half keeps tracking `--px`; the library part selectors are
+at most (0,2,1) specific, so a three-class app selector beats them all).
+`BbOffCanvas` is identical with `.bb-offcanvas__*` and the same `--px` /
+`--py` names.
+
+**Scope the pair to the surface, and it stays the surface's.** `--px` is also
+a local on other components (`BbButton`, `BbAlert`, `BbTooltip`,
+`BbBaseSlider`), but each of those re-declares it on its own root class, so a
+dialog-scoped `--px` never leaks into the buttons or alerts inside the dialog
+— and, symmetrically, never set the pair on `:root` or an arbitrary ancestor:
+the surface roots' own defaults mask it there, and you would be reaching into
+every other `--px`-reading component anyway. (`--pt` remains dead — nothing
+reads it.)
 
 If only the **vertical rhythm between parts** differs, the local `--dialog-gap`
-(default `--bb-panel-p`) already does it without a padding rule: it drives the
-gap below the body content and the footer's block padding on `.bb-dialog` and
+(default `--py`) already does it without a padding rule: it drives the gap
+below the body content and the footer's block padding on `.bb-dialog` and
 `.bb-offcanvas`. It does **not** cover the header's top padding, or the body's
-top padding in the headerless case — those still take `--bb-panel-p`.
+top padding in the headerless case — those still take `--py`.
 
 **`--bb-dialog-close` maps to nothing — delete it.** In v2 it was the close
 **icon** width (`12px`) and the button around it added `8px` of padding, so the
@@ -454,15 +545,25 @@ and delete only the declarations that merely restated a **v2** default.
 **A type that narrowed.** `--bb-ring-opacity` survives by name but v3 registers
 it with `@property … syntax: '<percentage>'`:
 
-| token               | v2 form                                                  | v3 form                          | symptom                                                                                                                                                                                              |
-| ------------------- | -------------------------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--bb-ring-opacity` | unitless `0.25` / `0.4`, multiplied by `100%` internally | `25%` / `40%` — a `<percentage>` | ⚠ silent: a unitless override is invalid at computed-value time, so it is discarded and the token falls back to the registered `initial-value: 25%`. v3's own defaults are `15%` light / `40%` dark. |
+| token               | v2 form                                                  | v3 form                          | symptom                                                                                                                                                                                                                                                                                    |
+| ------------------- | -------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--bb-ring-opacity` | unitless `0.25` / `0.4`, multiplied by `100%` internally | `25%` / `40%` — a `<percentage>` | ⚠ silent: a unitless override is invalid at computed-value time, so it is discarded and the token falls back to the registered `initial-value: 15%` — v3's own light default, so a light page silently renders the stock ring, while a dark page lands on `15%` against the shipped `40%`. |
 
 Nothing reports this — not `vue-tsc`, not the eslint plugin, not
 `npx bitboss-ui check` (none of them read CSS), and not the browser console:
 an invalid registered-property value is not a parse error, so it logs nothing.
-Grep your stylesheets for `--bb-ring-opacity` and confirm every value carries a
-`%`.
+Grep your stylesheets for `--bb-ring-opacity` and check **both directions of
+every hit**:
+
+- every **write** must carry a `%` (`0.15` → `15%`), and
+- every **read** must stop multiplying by `100%`. The v2 idiom for consuming
+  the unitless form was exactly that —
+  `calc(100% - var(--bb-ring-opacity) * 100%)` — and under v3 it multiplies a
+  percentage by a percentage, which is invalid in `calc()`. The invalid math
+  takes the whole declaration down (typically a `color-mix()` ring), so the
+  failure is _worse_ than the write side: a stale write still produces a ring
+  at the fallback strength, a stale read produces **no ring at all**, equally
+  silently. Delete the `* 100%`.
 
 Nine tokens are `@property`-registered in v3 — the eight color knobs
 (`syntax: '<color>'`) plus `--bb-ring-opacity`. Each rejects values outside its
@@ -565,9 +666,26 @@ this order:
 1. **Name is in the table, and your app never styled it** → use the built-in
    `variant`. This is the only genuinely free conversion.
 2. **Name is in the table, but your app styled it itself** → v3's built-in now
-   paints underneath your rules. Decide explicitly: accept v3's look and delete
-   your CSS, or register the name (`alertVariants: ['warning']`) so your CSS
-   stays the sole styling source.
+   paints underneath your rules, and **registering the name does not stop it**.
+   The registries feed the type-checker only: `alertVariants: ['warning']`
+   regenerates the typed union and nothing else — no CSS is generated and none
+   is suppressed; the built-in `.bb-alert--warning` skin ships unconditionally
+   in `styles.css` and still applies, so every property your CSS does not
+   explicitly set shows through as the library's. Decide explicitly: accept
+   v3's look and delete your CSS, or keep your look — which requires your rules
+   to **win the cascade** over the library's. Note the library's skin
+   selectors are not uniform: some families compile single-class
+   (`.bb-alert--warning`, `.bb-toast-message--*` — (0,1,0)), others
+   block-scoped (`.bb-button.bb-button--outline`, `.bb-badge.bb-badge--*`,
+   `.bb-indicator.bb-indicator--*`, `.bb-tooltip.bb-tooltip--*` — (0,2,0)).
+   The pattern that wins everywhere: author your override at block+modifier
+   (`.bb-alert.bb-alert--warning`, or nest the modifier under the block) **and**
+   load your sheet after `styles.css` — that outweighs the single-class
+   families and ties-then-wins-on-order against the block-scoped ones. Or
+   sidestep the collision by renaming to a name not in the table, which moves
+   you to case 3, where your CSS genuinely is the sole source. Whichever you pick,
+   still register the name: that part is required for the type-check either
+   way.
 3. **Name is not in the table** → register it and keep your CSS. **Do not remap
    onto the "nearest" built-in.** `error → destructive`, `danger →
 destructive`, `info → primary` all compile, all look plausible in review,
@@ -575,8 +693,12 @@ destructive`, `info → primary` all compile, all look plausible in review,
    deliberate redesign decision, never as a mechanical migration step.
 4. **Name was never styled by anyone** → see the next subsection.
 
-Registering is cheap — one array entry per name — and it is the
-behaviour-preserving default. Prefer it whenever you are not sure.
+Registering is cheap — one array entry per name — and for a name **not** in
+the table it is the behaviour-preserving default: the library has no rule for
+an unknown name, so your CSS is the sole styling source. For a name that **is**
+in the table, registering buys the type-check and nothing else — behaviour
+preservation there is a cascade question (case 2 above). When unsure, prefer a
+non-colliding name.
 
 ### ⚠ silent — a `theme` value that did nothing in v2 may do something in v3
 
@@ -753,16 +875,16 @@ to the new name (`hide-close`).
   warns.
 - **`BbPopover`**: `showClose`, `closeLabel`, `restoreFocus`, `block` removed —
   render your own close affordance in the content (`#default="{ close }"`).
-- **`BbDialog`**: `description`, `hideHeader`, `compact`, `overlayClasses`,
-  `panelClasses` removed (use the `header` slot and normal classes). The
-  `#description` and `#close` **slots** are gone too — v3's slot set is
-  `header | title | default | footer`, and a custom close control goes inside
-  `#header`, which replaces the whole default header including the ✕ (so
-  `hide-close` is not needed alongside it).
-- **`BbOffCanvas`**: the same `description` prop and the same `#description` /
-  `#close` slots were removed, with the same replacements. The
-  `aria-describedby` wiring `description` used to provide is gone — put the
-  copy in the default slot.
+- **`BbDialog`**: `hideHeader`, `compact`, `overlayClasses`, `panelClasses`
+  removed (use the `header` slot and normal classes). The `#close` **slot** is
+  gone too — v3's slot set is `header | title | description | default | footer`,
+  and a custom close control goes inside `#header`, which replaces the whole
+  default header including the ✕ (so `hide-close` is not needed alongside it).
+  **`description` and `#description` survive**: they were dropped in early v3
+  and restored in 3.0.0-beta.19, unchanged from v2 and with `aria-describedby`
+  wired again.
+- **`BbOffCanvas`**: the same — `#close` removed, `description` /
+  `#description` kept (restored in 3.0.0-beta.19).
 - **`BbBreadcrumbs`**: string `divider` removed (slot-driven now);
   `dividerWidth` default changed `5` → `16`.
 - **`BbPagination`**: `loading` removed.
@@ -837,6 +959,15 @@ is the complete set — a class-by-class diff of the v2 stylesheet against v3
 leaves nothing else orphaned. All of it is **silent**: a selector on a class
 nobody emits matches nothing and throws nothing.
 
+One caution when auditing on your own: absence from `styles.css` answers _"is
+it styled"_, not _"is it emitted"_. Some classes carry no library rule but are
+still rendered as styling hooks for you (`.bb-base-input-container__hint-text`
+is one: its wrapper `__hint-wrap` carries the rules, the inner text node is
+bare) — those are correct targets and correctly
+absent from this table, which maps only classes that moved or died. Before
+filing a class as removed, check the component's markup, not just the
+stylesheet.
+
 **Input chrome**
 
 | v2                                                                                                                                | v3                                                                                                                                                                                                                                                                                                                                       |
@@ -881,6 +1012,23 @@ v2 had no full-width tab strip, so apps hand-rolled one (commonly a
 `.bb-tabs--block` / `.bb-tabs-list--block` and gives the triggers equal widths.
 Delete the hand-rolled modifier rather than porting it.
 
+**BbTable** — no class was renamed, but the markup under `.bb-table` is no
+longer a `<table>`: it is a CSS grid of `<div>`s carrying ARIA roles. Every
+**element** selector on it (`table`, `thead`, `tbody`, `tfoot`, `caption`,
+`tr`, `th`, `td`, `colgroup`/`col`) matches nothing in v3 — silently. The
+classes all survive; four containers and the roles are the translation:
+
+| v2 element                            | v3 selector                                                                                  |
+| ------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `table` / `thead` / `tbody` / `tfoot` | `.bb-table__table` / `.bb-table__head` / `.bb-table__body` / `.bb-table__foot`               |
+| `caption`                             | `.bb-table-caption`                                                                          |
+| `tr` / `th` / `td`                    | `[role=row]` / `[role=columnheader]` / `[role=cell]` (or the `.bb-table-*` row/cell classes) |
+| `colgroup` / `col`                    | gone — `columns[].width`                                                                     |
+
+Full table, the `.table-flush` idiom rewrite, the `#thead`/`#tbody`/`#tfoot`
+markup contract and the layout drift that comes with the substrate:
+[bb-table.md](./components/bb-table.md#the-table-is-a-css-grid-not-a-table-v3-beta-2026-08-26).
+
 **Everything else**
 
 | v2                                                                                                                                                                                                                                            | v3                                                                                                                                                                                                                            |
@@ -914,9 +1062,13 @@ The date **input**'s own field tree (`.bb-base-date-picker-input__field`,
 **Removed with no counterpart:** `.bb-base-dialog--compact`,
 `.bb-offcanvas--compact`, `.bb-base-textarea--compact` (compact now lives on
 `.common-input-wrapper--compact`), `.bb-base-select--active` / `--compact` /
-`__inner-wrapper` / `__input-container` (the select activator was rebuilt —
-nearest hooks are `.bb-base-select__activator`, `__value`, `__display-value`;
-`--shown` survives), `.bb-base-rating__option--highlighted` (v3 uses
+`__inner-wrapper` / `__input-container` / `__text-input` (the select activator
+was rebuilt — nearest hooks are `.bb-base-select__activator`, `__value`,
+`__display-value`; `--shown` survives. `__text-input` was v2's combobox typing
+field inside the activator; v3's activator is a `type="button"` overlay with no
+typable field, and typing moved into the panel's
+`.bb-select-popover__search-input` — restyle that instead, knowing it now sits
+in the popover, not the field), `.bb-base-rating__option--highlighted` (v3 uses
 `--filled` / `--empty`), `.bb-progress--horizontal` (`.bb-progress` /
 `.bb-progress-bar` are the blocks), `.bb-ratio` (component removed).
 
@@ -928,23 +1080,27 @@ nested-table column alignment. They all dropped the `bb-` prefix, and every one
 of them is consumed through `var(name, fallback)`, so a v2 name silently
 resolves to the fallback instead of failing.
 
-| 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` / `--offset-internal-end`                        |
-| `--bb-table-fill`                                     | `--fill`                                                                   |
-| `--bb-table-natural-width`                            | `--natural-width`                                                          |
-| `--bb-select-popover-width` (on `.bb-select-popover`) | `--w` — and the supported path is now the `width` prop, not a CSS override |
-| `--bb-icon-dimensions-w` (on `.bb-icon`)              | `--w`                                                                      |
-| `--bb-breadcrumbs-flex-basis` / `-flex-grow`          | `--flex-basis` / `--flex-grow`                                             |
-| `--bb-picker-preview-color`                           | `--picker-preview-color`                                                   |
+| 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` / `--offset-internal-end`                                       |
+| `--bb-table-fill`                                     | **removed in 3.0.0** (briefly `--fill` in the betas; the grid substrate has no fill loop) |
+| `--bb-table-natural-width`                            | **removed in 3.0.0** (briefly `--natural-width` in the betas)                             |
+| `--bb-select-popover-width` (on `.bb-select-popover`) | `--w` — and the supported path is now the `width` prop, not a CSS override                |
+| `--bb-icon-dimensions-w` (on `.bb-icon`)              | `--w`                                                                                     |
+| `--bb-breadcrumbs-flex-basis` / `-flex-grow`          | `--flex-basis` / `--flex-grow`                                                            |
+| `--bb-picker-preview-color`                           | `--picker-preview-color`                                                                  |
 
 A regex matching the old shape (`/--bb-table-[\w-]+-track/`) matches nothing in
 v3. Search your app for `--bb-table-`, `--bb-select-popover-`,
 `--bb-icon-dimensions-`, `--bb-breadcrumbs-` and `--bb-picker-` — none of those
 names exist in v3 and all of them fail quietly. `--available-height`,
-`--inner-width` and `--overlay-min-height` were dropped outright.
+`--inner-width`, `--overlay-min-height`, `--bb-table-fill` and
+`--bb-table-natural-width` were dropped outright — the last two because
+`BbTable` is a CSS grid in 3.0.0 and the fixed-layout self-correction they fed
+no longer exists (see
+[bb-table.md](./components/bb-table.md#--fill-and---natural-width-are-removed-not-renamed)).
 
 If you re-published track variables by hand to align a deeply nested table,
 delete that code: `inherit-column-widths` takes a **table id**
@@ -1013,6 +1169,16 @@ Nothing here fails to compile — these change what existing code does.
     branch's children are now `inert` (out of the Tab order). Tests or CSS
     keyed on the removed roles match nothing — see
     [bb-tree.md](./components/bb-tree.md).
+13. **`BbTable` is a CSS grid, not a `<table>`.** Column widths hold their
+    overflow threshold, wrap floor and frozen widths exactly, but leftover
+    space is shared equally between auto columns rather than proportionally
+    to content, and a few table-only tricks stop working (`max-width: 0` for
+    ellipsis collapses the cell). Copying rows into a spreadsheet pastes one
+    value per line, and a printed table no longer repeats its header on each
+    page. `#thead`/`#tbody`/`#tfoot` take `<div role="row">` rows, never
+    `<tr>`. Requires subgrid (Chrome/Edge 117, Firefox 71, Safari 16) — no
+    fallback. Full detail and the selector translation in
+    [bb-table.md](./components/bb-table.md#the-table-is-a-css-grid-not-a-table-v3-beta-2026-08-26).
 
 ## 7. Class overrides → variants
 
@@ -1046,8 +1212,12 @@ screenshot; do not assume. Two consequences before you start:
   `variant="none"`; it is the one value that emits no variant class.
 - **A name that collides with a v3 built-in is the dangerous case, not the easy
   one.** If your app owned the look of `warning` / `destructive` / `secondary`,
-  converting to the same-named `variant` hands that look to the library.
-  Register the name as a custom variant (§4) to keep your CSS the only source.
+  converting to the same-named `variant` hands that look to the library — and
+  registering the name does **not** take it back: registration is type-only
+  (§4), the built-in skin stays in `styles.css`. Keep your look by winning the
+  cascade over the library's skin rules — author at block+modifier and load
+  after `styles.css` (§4 case 2 has the specificity detail) — or convert to a
+  non-colliding custom name.
 
 ### Finding them
 
@@ -1067,17 +1237,17 @@ rg -n 'class="bb-(button|badge|alert|toast-message|tooltip|indicator)\b' --type
 
 ### Correcting them
 
-| Found                                                                                               | Rewrite as                                                                                                                                                                                                                                                                                                 |
-| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `<BbButton class="bb-button--outline">`                                                             | `<BbButton variant="outline">` (same for `secondary`, `ghost`, `destructive`, `link`)                                                                                                                                                                                                                      |
-| `<BbAlert class="bb-alert--warning">` / v2 `theme="warning"`                                        | `<BbAlert variant="warning">`                                                                                                                                                                                                                                                                              |
-| `class="bb-badge bb-badge--secondary"` on a `<span>`                                                | `<BbBadge variant="secondary">` — the real component, not markup cosplay                                                                                                                                                                                                                                   |
-| `bb-toast-message--success` styling / v2 `theme` on toasts                                          | `toast({ variant: 'success' })`                                                                                                                                                                                                                                                                            |
-| `bb-tooltip--destructive`                                                                           | `<BbTooltip variant="destructive">` / `v-bb-tooltip="{ text, variant: 'destructive' }"`                                                                                                                                                                                                                    |
-| A **custom** modifier (`bb-button--brand`, any name not in section 4's table)                       | Register it: `buttonVariants: ['brand']` in the plugin, keep your CSS, pass `variant="brand"`.                                                                                                                                                                                                             |
-| A modifier your app **styled itself**, whatever its name                                            | Decide before you convert: accept v3's built-in look and delete your CSS, or register the name (§4) so your CSS stays the sole styling source. Converting silently does the former.                                                                                                                        |
-| A **state** modifier that stacks on a variant (`bb-button--pressed` alongside `bb-button--outline`) | Not convertible — `variant` holds exactly one value. Keep it a class and rename it out of `bb-*` (`app-button--pressed`). If it marks a real toggle, `v-model` on `BbButton` owns the state: it sets `aria-pressed` and emits `bb-button--active`, which the library deliberately leaves unstyled for you. |
-| A class that overrides _layout_, not look (widths, margins)                                         | Leave it — classes remain the right tool for layout; variants own _appearance semantics_.                                                                                                                                                                                                                  |
+| Found                                                                                               | Rewrite as                                                                                                                                                                                                                                                                                                                                                                      |
+| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<BbButton class="bb-button--outline">`                                                             | `<BbButton variant="outline">` (same for `secondary`, `ghost`, `destructive`, `link`)                                                                                                                                                                                                                                                                                           |
+| `<BbAlert class="bb-alert--warning">` / v2 `theme="warning"`                                        | `<BbAlert variant="warning">`                                                                                                                                                                                                                                                                                                                                                   |
+| `class="bb-badge bb-badge--secondary"` on a `<span>`                                                | `<BbBadge variant="secondary">` — the real component, not markup cosplay                                                                                                                                                                                                                                                                                                        |
+| `bb-toast-message--success` styling / v2 `theme` on toasts                                          | `toast({ variant: 'success' })`                                                                                                                                                                                                                                                                                                                                                 |
+| `bb-tooltip--destructive`                                                                           | `<BbTooltip variant="destructive">` / `v-bb-tooltip="{ text, variant: 'destructive' }"`                                                                                                                                                                                                                                                                                         |
+| A **custom** modifier (`bb-button--brand`, any name not in section 4's table)                       | Register it: `buttonVariants: ['brand']` in the plugin, keep your CSS, pass `variant="brand"`.                                                                                                                                                                                                                                                                                  |
+| A modifier your app **styled itself**, whatever its name                                            | Decide before you convert: accept v3's built-in look and delete your CSS, or keep yours. Keeping it is free for a non-built-in name (register it, done — there is no library rule to fight); for a built-in name registering only satisfies the type-check, and your rules must also win the cascade over the library's skin (§4, case 2). Converting silently does the former. |
+| A **state** modifier that stacks on a variant (`bb-button--pressed` alongside `bb-button--outline`) | Not convertible — `variant` holds exactly one value. Keep it a class and rename it out of `bb-*` (`app-button--pressed`). If it marks a real toggle, `v-model` on `BbButton` owns the state: it sets `aria-pressed` and emits `bb-button--active`, which the library deliberately leaves unstyled for you.                                                                      |
+| A class that overrides _layout_, not look (widths, margins)                                         | Leave it — classes remain the right tool for layout; variants own _appearance semantics_.                                                                                                                                                                                                                                                                                       |
 
 Rule of thumb: if the class name encodes a **meaning** (state, emphasis,
 severity), it should be a variant; if it encodes **geometry**, it stays a
@@ -1156,6 +1326,7 @@ rg -n -- '--bb-(contrasting|hint|icon-color|primary-(base|dark)|panel-(light|dar
 rg -n -- '--bb-ring-opacity'              # survives by name; every value must now carry a % (section 3)
 rg -n 'bb-base-dialog|bb-tab__|bb-tab--|bb-cr-container|bb-common-input-outer-container|bb-common-input-inner-container|bb-base-input-container__input|bb-base-(checkbox|radio|switch)-container|bb-tree-row|bb-tree-main-content|bb-confirm__no|bb-dropdown__wrapper|bb-offcanvas__close|bb-popover__close|bb-ratio'  # renamed or deleted CSS blocks — nothing in v3 emits any of these (§5.6)
 rg -n 'bb-color-palette__'                # → .bb-base-color-palette__*; only __popover survives under the old name
+rg -n '\b(table|thead|tbody|tfoot|caption|colgroup|col|tr|th|td)\b' --type css --type vue  # element selectors aimed at BbTable (`.bb-table table`, `:deep(> table > tbody …)`, a global `td { padding }`, `.prose table`) — BbTable is a div grid in v3, none of them reach it; translate per bb-table.md § Selector translation. Expect noise from `<table>` markup of your own and from words in comments — judge each hit
 rg -n 'bb-tabs--'                         # v3's own modifiers are --horizontal --vertical --block --compact --disabled; anything else is app-minted, and a hand-rolled full-width tab list is now <BbTabs block>
 ```