bitboss-ui 2.1.134 → 3.0.0-alpha.1

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

@@ -0,0 +1,649 @@
+---
+title: Migration v2 → v3
+summary: Complete upgrade guide from bitboss-ui 2.x to 3.0 — plugin-based setup, token overhaul, variant registries, global behavioral changes, and the silent-failure audit playbook.
+---
+
+# Migrating from bitboss-ui 2.x to 3.0
+
+v3 is a single coordinated break: the library moved from a plain component
+package to a **build-plugin + runtime-plugin architecture**, replaced the
+free-form `theme`/`color` styling props with **typed variant registries**,
+overhauled the design-token system, and flipped a family of boolean props to
+a consistent **opt-in polarity** (props default `false`; `disable*`/`hide-*`
+turn a default behavior off).
+
+This guide covers everything cross-cutting. Component-specific breaks live in
+the per-component guides under [`migration/components/`](./components/) —
+only components with **functional** changes have one; if a component has no
+guide there, nothing about it needs migration.
+
+**How to read the tables:** every row is a hard break — old names are gone,
+with no alias and no deprecation shim. Where the break is _silent_ (the app
+compiles and runs but behaves differently), the row is marked **⚠ silent**;
+these are the rows you cannot find by waiting for errors, so grep for them
+explicitly (section 8).
+
+## For agents: surface what this guide misses
+
+This guide is the contract for the upgrade. If during a migration you hit
+something it does not cover, **do not silently work around it** — a quiet
+workaround hides a gap that will bite the next project. Report it to the
+user in your migration summary, clearly separated from the routine edits.
+
+Reportable findings, in order of severity:
+
+1. **An undocumented break** — v2 code that compiled or behaved one way and
+   changes in v3 without a matching entry here or in the component's guide.
+2. **A mapping that doesn't hold** — you applied a documented old→new edit
+   and the result compiles but renders or behaves differently than the guide
+   promises.
+3. **An ambiguity you had to guess on** — two plausible migrations for the
+   same v2 usage and the guide doesn't say which is intended.
+4. **A pattern with no v3 home** — a v2 usage (prop combination, slot trick,
+   CSS hook) whose replacement you could not find at all.
+
+For each finding include: the component, the exact v2 usage (snippet), what
+you expected from the guide, and what actually happened. Recommend that the
+user forwards it to the bitboss-ui maintainers so the guide gets a row —
+these reports are how this document stays truthful.
+
+Routine work — renames that behaved exactly as the tables say — belongs in
+the normal summary, not in this report. The report is only for surprises.
+
+## 0. Upgrade strategy — do it in this order
+
+1. **Swap the setup** (section 1): install the build plugin and the runtime
+   plugin. Nothing renders correctly until this is done.
+2. **Move your config** (section 2): everything you passed to
+   `useBbConfig().setConfig()` except `locale` now lives in the build-plugin
+   options.
+3. **Re-base your theme** (section 3): the token system changed names and
+   defaults — including the primary color itself. Your brand theme must be
+   re-declared before visual review makes any sense.
+4. **Fix what the compiler finds** (sections 4–6): with typed templates
+   (`vue-tsc`), renamed props, removed props, and unregistered variants all
+   fail loudly. Fix them component by component with the per-component guides.
+5. **Audit what the compiler cannot find** (section 8): untyped templates,
+   `v-bind` objects, and behavioral flips are silent. Run the grep playbook.
+6. **Convert class overrides to variants** (section 7): userland
+   `class="bb-button--outline"`-style overrides keep _working_ but are now the
+   wrong pattern — the variant prop exists, is typed, and is the only form the
+   registry validates.
+
+## 1. The plugin pattern
+
+### 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`.
+
+```ts
+// v2 main.ts
+import { createApp } from 'vue';
+import 'bitboss-ui/styles.css';
+import {
+	BbTooltipDirectivePlugin,
+	BbDropdownDirectivePlugin,
+} from 'bitboss-ui';
+
+const app = createApp(App);
+app.use(BbTooltipDirectivePlugin); // only if you used v-bb-tooltip
+app.use(BbDropdownDirectivePlugin); // only if you used v-bb-dropdown
+app.mount('#app');
+```
+
+### What v3 requires
+
+Two pieces, both mandatory:
+
+1. the **build plugin** — `bitboss-ui/vite` (or the `bitboss-ui/nuxt` module,
+   which wraps it). It serves the virtual config/icon modules, scans your
+   local SVG icons, and generates the typed variant registries;
+2. the **runtime plugin** — `bitbossUiPlugin` via `app.use` (automatic in
+   Nuxt). It injects the stylesheet, provides the icon registry, and registers
+   the `v-bb-tooltip` / `v-bb-dropdown` directives.
+
+```ts
+// v3 vite.config.ts
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+import { bitbossUi } from 'bitboss-ui/vite';
+
+export default defineConfig({
+	plugins: [
+		vue(),
+		bitbossUi({
+			iconDir: './src/assets/icons', // required — create the folder
+		}),
+	],
+});
+```
+
+```ts
+// v3 main.ts
+import { createApp } from 'vue';
+import { bitbossUiPlugin } from 'bitboss-ui';
+
+const app = createApp(App);
+app.use(bitbossUiPlugin);
+app.mount('#app');
+```
+
+Migration deltas, one by one:
+
+| v2                                                                         | v3                                                                                                                                                                                                                                        |
+| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `import 'bitboss-ui/styles.css'` in the entry file                         | **Delete it.** The runtime plugin auto-injects styles (`injectStyles` defaults `true`). Keep a manual import only if you set `injectStyles: false`.                                                                                       |
+| No build plugin                                                            | **Add `bitbossUi({ iconDir })`** to `vite.config.ts` (or the `bitboss-ui/nuxt` module). The app does not build without it — components import the virtual config module.                                                                  |
+| `app.use(BbTooltipDirectivePlugin)` / `app.use(BbDropdownDirectivePlugin)` | **Delete both.** `bitbossUiPlugin` registers `v-bb-tooltip` and `v-bb-dropdown` itself (opt out with `injectDirectives: false` if the names collide).                                                                                     |
+| No reset stylesheet                                                        | Optional: `resetCss: true` or `import 'bitboss-ui/reset.css'`. Skip in Tailwind apps — Preflight already does this.                                                                                                                       |
+| Icons registered by augmenting the `IconRegistry` type                     | **Gone** (the `IconRegistry` export no longer exists — see section 5). Drop `.svg` files into `iconDir` and reference them as `local:<name>`; provider icons (`lucide:*`, `mdi:*`, …) need the matching `@iconify-json/*` dev dependency. |
+
+### Nuxt
+
+v2 had no Nuxt story. v3 ships a module that does both halves — do **not**
+also call `app.use`:
+
+```ts
+// v3 nuxt.config.ts
+export default defineNuxtConfig({
+	modules: ['bitboss-ui/nuxt'],
+	bitboss: {
+		iconDir: './assets/icons',
+	},
+});
+```
+
+### Inertia
+
+Inertia apps configure `bitboss-ui/vite` exactly like plain Vite, install
+`@inertiajs/vue3` (now an optional peer), and add the runtime plugin inside
+`createInertiaApp`:
+
+```ts
+createInertiaApp({
+	setup({ el, App, props, plugin }) {
+		createApp({ render: () => h(App, props) })
+			.use(plugin)
+			.use(bitbossUiPlugin)
+			.mount(el);
+	},
+});
+```
+
+Full option reference:
+[Installation & Plugin Setup](../installation-and-plugin-setup.md).
+
+## 2. Runtime config moves into the build plugin
+
+In v2 all configuration was runtime and mutable:
+
+```ts
+// v2 — anywhere, usually App.vue setup
+import { useBbConfig } from 'bitboss-ui';
+
+useBbConfig().setConfig({
+	locale: 'en',
+	inertiaLinkName: 'Link',
+	mobileMaxWidth: 768,
+	dialogDefaultSizes: { md: 700 },
+});
+```
+
+In v3 `setConfig` accepts **only `locale`**. Every other key is a build-plugin
+option — same names, set once in `vite.config.ts` / the `bitboss` Nuxt key:
+
+```ts
+// v3
+bitbossUi({
+	iconDir: './src/assets/icons',
+	inertiaLinkName: 'Link',
+	mobileMaxWidth: 768,
+	dialogDefaultSizes: { md: 700 },
+});
+
+// runtime — locale only (e.g. reacting to a user preference)
+useBbConfig().setConfig({ locale: 'en' });
+```
+
+| v2 `setConfig` key                            | Where it goes in v3                                                            |
+| --------------------------------------------- | ------------------------------------------------------------------------------ |
+| `locale`                                      | stays runtime (`setConfig`) — the only survivor                                |
+| `inertiaLinkName`, `nuxtLinkName`             | build-plugin option, same name                                                 |
+| `linkActiveClass`, `linkExactActiveClass`     | build-plugin option, same name                                                 |
+| `mobileMaxWidth`                              | build-plugin option, same name                                                 |
+| `dialogDefaultSizes`, `offCanvasDefaultSizes` | build-plugin option, same name — **but the default values changed, see below** |
+| `documentationURL`                            | removed — no v3 equivalent                                                     |
+
+**⚠ silent — the size maps changed shape and values.** v2 defaulted
+`{ sm: 384, md: 652, lg: 896 }`; v3 defaults
+`{ xs: 320, sm: 384, md: 448, lg: 512, xl: 576, '2xl': 672 }`. A
+`<BbDialog size="md">` that was 652px wide in v2 renders **448px** in v3
+without any error. If your app relied on the v2 widths, pin them explicitly:
+
+```ts
+bitbossUi({
+	iconDir: '…',
+	dialogDefaultSizes: { md: 652, lg: 896 },
+	offCanvasDefaultSizes: { md: 652, lg: 896 },
+});
+```
+
+v3 also adds config that v2 didn't have — notably `adaptive` (default `true`:
+dialogs/popovers/dropdowns/selects open as a bottom sheet on mobile),
+`defaultInputLabelMode`, `toastPosition`, `iconDefaultSizes`. `adaptive`
+defaulting **on** is itself a behavior change for surfaces on small viewports;
+set `adaptive: false` at the plugin level to keep v2-like floating behavior
+everywhere, or per component with the `adaptive` prop.
+
+## 3. Design tokens and theming
+
+The token architecture was rebuilt (full doctrine:
+[Design Tokens](../design-tokens.md)). What it means for a migrating theme:
+
+### The triple is gone
+
+v2 themed through `--x-light` / `--x-dark` / `--x` triples plus dozens of
+global per-component variables in `:root`. v3 has **one name per token** and
+two tiers:
+
+- **`--bb-*` theme tokens** — the public theming surface, declared only in
+  the library's `variables.css`. You override these.
+- **unprefixed component tokens** (`--indent`, `--track`, …) — scoped to each
+  component's root class. You override them _on the component's class_, not
+  globally.
+
+Dark mode is no longer a parallel token set: `.dark` re-declares only the
+knobs that change, and derived tokens follow automatically. Delete every
+`--x-light`/`--x-dark` override; re-express as `.light { … }` / `.dark { … }`
+blocks. Note: overriding a knob on an arbitrary selector does **not**
+re-derive dependent tokens — re-apply the `.light`/`.dark` block on that
+scope instead.
+
+### ⚠ silent — two visual defaults changed
+
+- `--bb-primary` is now **black** (`rgb(0 0 0)`), not v2's blue
+  (`rgb(37, 29, 255)`). If you never overrode the primary because the blue
+  suited you, your whole app changes color on upgrade. Set your brand color
+  explicitly.
+- `--bb-radius` went `4px` → `8px`.
+
+### Token rename map
+
+| v2 override                                                                                                                                                                           | v3 replacement                                                                                                                                                            |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--bb-primary-base`                                                                                                                                                                   | deleted — set `--bb-primary` directly                                                                                                                                     |
+| `--bb-contrasting` / `--bb-contrasting-dark`                                                                                                                                          | `--bb-primary-fg`                                                                                                                                                         |
+| `--bb-panel-disabled`, `--bb-input-bg-secondary`                                                                                                                                      | `--bb-muted`                                                                                                                                                              |
+| `--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-overlay-color` + `--bb-overlay-opacity`                                                                                                                                         | `--bb-overlay` (one color with alpha)                                                                                                                                     |
+| `--bb-overlay-z-index`                                                                                                                                                                | `--bb-z-overlay`                                                                                                                                                          |
+| `--bb-easing-bezier`                                                                                                                                                                  | `--bb-ease`                                                                                                                                                               |
+| `--bb-dialog-px/pt/pb/gap`                                                                                                                                                            | `--bb-panel-p` (surfaces share one padding token)                                                                                                                         |
+| `--bb-button-h`, `--bb-button-icon`, `--bb-tabs-*`, `--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 token on the component's own class. |
+
+A complete v3 theme is typically two small blocks of ~10 declarations
+(`--bb-primary`, `--bb-radius`, `--bb-control-h`, `--bb-panel`, `--bb-text`,
+`--bb-border`, `--bb-danger`, …) — one in `:root, .light`, the changed knobs
+again in `.dark`. If your v2 theme was long, most of it maps to "delete".
+
+## 4. Variants: from `theme` strings and class overrides to typed registries
+
+### What changed
+
+v2 components had **no `variant` prop**. Styling hooks were:
+
+- the free-form `theme?: string` prop (generated an arbitrary class), and
+- a free-form `color?: string` on the old badge,
+- …which in practice meant userland applied the library's internal modifier
+  classes directly: `<BbButton class="bb-button--outline">`.
+
+v3 replaces all of that with per-component `variant` props whose types are
+**locked to a registry** — built-in names plus whatever your build plugin
+registers. An unregistered name is a **compile error** (v2's silent
+render-unstyled behavior is gone by design), and the `theme` prop is gone.
+
+Built-in sets and the class each name maps to:
+
+| Plugin option          | Built-in variants                                                             | Class hook                          |
+| ---------------------- | ----------------------------------------------------------------------------- | ----------------------------------- |
+| `buttonVariants`       | `primary, outline, secondary, ghost, destructive, link` (+ `none` to opt out) | `bb-button--<name>`                 |
+| `alertVariants`        | `outline, primary, destructive, warning`                                      | `bb-alert--<name>`                  |
+| `badgeVariants`        | `primary, secondary, destructive, outline`                                    | `bb-badge--<name>`                  |
+| `indicatorVariants`    | `default, success, info, warning, destructive`                                | `bb-indicator--<name>`              |
+| `toastVariants`        | `default, success, info, warning, destructive`                                | `bb-toast-message--<name>`          |
+| `confirmVariants`      | `default, destructive`                                                        | `bb-confirm--<name>`                |
+| `dropdownItemVariants` | `default, destructive`                                                        | `bb-dropdown__item--variant-<name>` |
+| `tooltipVariants`      | `default, destructive`                                                        | `bb-tooltip--<name>`                |
+
+### Custom variants are first-class
+
+If your v2 app invented its own look (a `theme="brand"` or a hand-written
+modifier class), register the name and ship its CSS:
+
+```ts
+// vite.config.ts
+bitbossUi({
+	iconDir: '…',
+	buttonVariants: ['brand'],
+	badgeVariants: ['soft-blue'],
+});
+```
+
+```css
+/* your CSS — the registered name is just a class hook */
+.bb-button--brand {
+	background: var(--bb-primary);
+	/* … */
+}
+```
+
+The plugin regenerates the typed union on build start, so `variant="brand"`
+type-checks and autocompletes. A one-off that you refuse to register still
+works with a visible cast (`variant="brand" as ButtonVariantType` won't
+compile — cast the value, not the prop), but the registry is the intended
+path.
+
+## 5. API-wide changes
+
+These patterns repeat across many components. The per-component guides list
+every occurrence; this section explains each pattern once.
+
+### 5.1 Components renamed, split, or removed
+
+| v2                                                                            | v3                                                                        | What to do                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BbBadge` (floating count/dot anchored to an element)                         | **`BbIndicator`**                                                         | `content` → `text`, `color` → `variant`, `floating` removed. New `max` prop renders `${max}+`.                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `BbChip`                                                                      | **removed** — use `BbBadge`                                               | v3 `BbBadge` is the inline pill/token: same `click:clear` event and `clearableLabel`, but `clearable` is now **opt-in** (v2 chips defaulted clearable).                                                                                                                                                                                                                                                                                                                                                  |
+| —                                                                             | **`BbBadge`** (repurposed)                                                | The v3 badge is a new component in an old name: inline label with `variant`, `icon`, `loading`, `clearable`. Any v2 `<BbBadge>` you have is an _indicator_ — rename it.                                                                                                                                                                                                                                                                                                                                  |
+| `BbTab`                                                                       | **`BbTabs`**                                                              | Component and types renamed (`BbTabProps` → `BbTabsProps`; deprecated type aliases remain, the component name does not).                                                                                                                                                                                                                                                                                                                                                                                 |
+| `Base*` internals (`BaseButton`, `BaseDialog`, `BaseCheckbox`, `BaseTag`, …)  | **`BbBase*`**                                                             | If you imported any base primitive or targeted its BEM block in CSS (`.base-btn` → `.bb-base-button`), rename. `BbBaseButton` is now a supported public export.                                                                                                                                                                                                                                                                                                                                          |
+| `BbCheckboxIcon` / `BbRadioIcon` / `BbSwitchIcon`                             | **`BbBaseCheckboxIcon`** / **`BbBaseRadioIcon`** / **`BbBaseSwitchIcon`** | Rename import + BEM block (`.bb-checkbox-icon` → `.bb-base-checkbox-icon`).                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `BbBase*` input controls + `CommonInputWrapper` / `CommonInputOuterContainer` | **no longer exported** — use the full public component                    | v2 exposed the styled base inputs (`BbBaseTextInput`, `BbBaseSelect`, `BbBaseSwitch`, `BbBaseDatePickerInput`, …) and the input-chrome wrappers because a few full inputs were missing. v3 ships a full public component for every input, so these are internal now. Use `BbTextInput` / `BbSelect` / `BbSwitch` / … ; for a bare/inline control with no label gap, pass **`hideLabel`**. Still exported: `BbBaseButton` and the glyphs (`BbBaseCheckboxIcon` / `BbBaseRadioIcon` / `BbBaseSwitchIcon`). |
+| `useWizard` (+ `Step`, `WizardState`, `wizardInjectionKey`)                   | **removed**                                                               | No replacement — it was unused scaffolding. Copy the v2 implementation into your app if you depended on it.                                                                                                                                                                                                                                                                                                                                                                                              |
+| `BbToastMessage` type export                                                  | **removed**                                                               | Use `BbToastOptions` (the `toast()` options shape).                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `IconRegistry` / `IconNameFromRegistry` exports                               | **removed**                                                               | Icon names are plain strings now. Local art goes in `iconDir` as `local:<name>`; delete your `IconRegistry` augmentation.                                                                                                                                                                                                                                                                                                                                                                                |
+
+### 5.2 The polarity wave: booleans now read as opt-in
+
+v3 rule: **boolean props default `false` and their name states what turning
+them on does.** Props that defaulted `true` were renamed to their inverse.
+Consequence: if you passed the old prop with its default (`:show-close="true"`),
+just delete it; if you passed the non-default (`:show-close="false"`), switch
+to the new name (`hide-close`).
+
+| Component(s)                                       | v2 prop (default)                                         | v3 prop (default)                                                                                                                                                                                                               |
+| -------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BbAlert`, `BbDialog`, `BbOffCanvas`               | `showClose` (`true`)                                      | `hideClose` (`false`) — also new on `toast()` / `confirm()` options                                                                                                                                                             |
+| `BbTable`                                          | `allowSelectAll` (`true`)                                 | `disableSelectAll` (`false`)                                                                                                                                                                                                    |
+| `BbTabs`                                           | `animateX` / `animateY` (`true`)                          | `disableAnimateX` / `disableAnimateY` (`false`)                                                                                                                                                                                 |
+| `BbButton`                                         | `autoLoading` (`false`)                                   | `disableAutoLoading` (`false`) — **⚠ silent behavior flip:** async `@click` handlers now show the loading spinner and disable the button automatically. Pass `disable-auto-loading` to keep v2 behavior.                        |
+| `BbDropdownButton`                                 | `autoLoading` (`true`)                                    | `disableAutoLoading` (`false`)                                                                                                                                                                                                  |
+| `BbDropdownButton`                                 | `disabledWhileLoading` (`true`)                           | **removed** — always disabled while loading now                                                                                                                                                                                 |
+| `BbSlider`                                         | `thumbTranslate` (`true`)                                 | `disableThumbTranslate` (`false`)                                                                                                                                                                                               |
+| `BbColorPalette`, `BbSelectPopover`                | `flip` (`true`)                                           | `disableFlip` (`false`)                                                                                                                                                                                                         |
+| `BbSelect`, `BbSelectPopover`, `BbDatePickerInput` | `allowWriting` (`true`, tokens `boolean \| 'not-mobile'`) | `disableWriting` (`false`, tokens `boolean \| 'mobile' \| 'desktop'`) — `allow-writing="not-mobile"` becomes `disable-writing="mobile"`                                                                                         |
+| `BbCheckbox`, `BbRadio`, `BbSwitch`                | `reverse` (`true`)                                        | `reverse` (`false`, **meaning inverted**) — unset renders identically, but explicit values flip: v2 `:reverse="false"` → v3 `reverse`; v2 `reverse` → delete. **⚠ silent** — see [bb-checkbox.md](./components/bb-checkbox.md). |
+| `BbAlert`                                          | `ariaAtomic` (`true`)                                     | **removed** — correct live-region behavior is hardcoded                                                                                                                                                                         |
+| `BbChip`                                           | `clearable` (`true`)                                      | **removed with the component** — `BbBadge.clearable` defaults `false`                                                                                                                                                           |
+
+### 5.3 Straight renames
+
+| Component                                          | v2                                | v3                                                                                                                                                                     |
+| -------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BbPagination`, `BbTabs`                           | `querykey`                        | `queryKey` — **⚠ silent**: a leftover `querykey` falls through to the DOM and the component uses the default key (`'page'` / `'tab'`), quietly moving your URL params. |
+| `BbTooltip`                                        | `timeout`                         | `delay`                                                                                                                                                                |
+| `BbIcon`                                           | `type` (required)                 | `icon`                                                                                                                                                                 |
+| `BbColorPalette`, `BbColorInput`                   | `picker`                          | `eyeDropper`                                                                                                                                                           |
+| `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup` | `labelPosition`                   | `legendPosition`                                                                                                                                                       |
+| `BbSelect`                                         | `prefill: 'focus'`                | `prefill: 'interaction'` (value rename; same default)                                                                                                                  |
+| `BbToast` (host)                                   | `placement` (e.g. `bottom-start`) | `position` (corner set: `top-left` … `bottom-right`)                                                                                                                   |
+| `BbAlert`, `BbTooltip`, `toast()`                  | `theme`                           | `variant` (typed — see section 4)                                                                                                                                      |
+
+### 5.4 Removed props (no replacement needed — behavior became default or moved)
+
+- **`theme` everywhere it existed** (`BbButton` family, `BbPopover`,
+  `BbDropdownButton`, …): replaced by the variant system or simply gone.
+  Reproduce one-off looks with a normal `class` plus your own CSS, or register
+  a custom variant.
+- **`color` everywhere**: gone from `BbAvatar`, `BbIcon`, `BbSpinner`,
+  `BbCheckbox`, `BbRadio`, `BbSwitch`, `BbSlider`, `BbRating` and all three
+  groups. Components inherit `currentColor` / theme tokens; style via CSS or
+  the token knobs.
+- **`BbSelect`**: `showChevron` and `updateOnAnimationFrame` removed; the
+  `#chevron` slot and the four `#options:prepend/append(:outer)` slots are
+  gone (use the new `#header` / `#footer` panel slots). Same options-slot
+  removal on `BbSelectPopover`.
+- **Group option affix slots** (`#option:prepend` / `#option:append` on the
+  checkbox/radio/switch groups): removed — decorate options through the
+  scoped `#label` slot.
+- **`BbDatePickerInput`**: `width` removed. **⚠ silent**: non-floating output
+  now carries the local offset (`2026-01-01T00:00:00+01:00`) instead of UTC
+  `Z` — same instant, different digits; the new `utc` prop restores the v2
+  emission (reading accepts both forms either way). Details in the
+  [component page](./components/bb-date-picker-input.md).
+- **`BbTag`**: `multiple` removed (always an array input).
+- **Built-in tooltip on `BbButton`** (`tooltip`, `tooltipPlacement`,
+  `tooltipTimeout`): use the `v-bb-tooltip` directive or wrap in `BbTooltip`.
+- **Arrow props on non-tooltip surfaces**: `hideArrow`
+  (`BbPopover`/`BbSelectPopover`), `showArrow` (`BbColorPalette`) and
+  `arrowPadding` are gone — arrows are a tooltip-only affordance now.
+  **⚠ silent**: a stray `hide-arrow`/`show-arrow` lands in `$attrs`, nothing
+  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).
+- **`BbBreadcrumbs`**: string `divider` removed (slot-driven now);
+  `dividerWidth` default changed `5` → `16`.
+- **`BbPagination`**: `loading` removed.
+- **`BbCollapsible`**: `tag` removed.
+- **Per-item `disabled` on option components**: item data no longer carries UI
+  state — pass the `selectable` predicate
+  (`boolean | ((item) => boolean)`) on `BbSelect`, `BbSelectPopover`,
+  `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`. **⚠ silent**: a
+  `disabled` field on an item object is plain data in v3; nothing warns.
+  (`BbTabs` keeps its tab-level `item.disabled` — different feature.)
+
+### 5.5 Types tightened (compile errors that are doing you a favor)
+
+- **Variant props are registry-locked** (section 4): unknown strings fail
+  `vue-tsc` instead of rendering unstyled.
+- **`BbBreadcrumbs` item `key`: `string | number` → `string`** — wrap numeric
+  keys in `String(...)`.
+- **`checked` on `BbCheckbox`/`BbRadio`/`BbSwitch`: `boolean | 'true' | 'false'`
+  → `boolean`** — the string forms no longer compile.
+- **`size` unions**: responsive maps (`Responsive<…>`) accepted everywhere the
+  concept applies; `BbButton` gains `'2xl'`; `BbIcon`'s `xxl` key is now
+  `'2xl'`.
+- **`itemText` / `itemValue`** unified on `ItemAccessor<T, R>` — top-level keys
+  autocomplete, functions unchanged; deep dot-paths still work but are
+  unchecked.
+- **`BbTextInput.type`** narrowed to the text-like set
+  (`text, email, url, tel, search, password`) — `type="number"` / `"date"`
+  belong to `BbNumberInput` / `BbDatePickerInput`.
+- **`filterBy`** (`BbSelect`, `BbSelectPopover`): `string[]` only — the
+  function, `false`, `'not_stashed'` and single-string forms are gone; filter
+  the items you pass instead.
+- **Models**: `BbTag.modelValue` is `string[]`; `BbDropzone.modelValue` is
+  `File | File[] | null`; `BbSlider.modelValue` drops its `string` member.
+- **`direction`** on inputs: the exported `InputDirection` union — keyword
+  typos now fail to compile; two-word ratio strings (`'1 2'`) still work.
+
+### 5.6 Renamed CSS blocks
+
+If app CSS or test selectors target library internals, these blocks moved:
+
+| v2                                                                                    | v3                                                                                                                                    |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `.bb-common-input-inner-container` (+ `--clearable`, `__prefix`, `__prepend-icon`, …) | `.common-input-wrapper` — modifiers `--active --compact --disabled --errors --loading --readonly --clearable` (note: no `bb-` prefix) |
+| `.base-btn`, `.base-btn--block`, …                                                    | `.bb-base-button*`                                                                                                                    |
+| `.bb-checkbox-icon` / `.bb-radio-icon` / `.bb-switch-icon`                            | `.bb-base-checkbox-icon` / `.bb-base-radio-icon` / `.bb-base-switch-icon`                                                             |
+| `.bb-chip*`                                                                           | `.bb-badge*` (component replaced)                                                                                                     |
+| `.bb-badge*` used as a floating count/dot                                             | `.bb-indicator*` (component renamed)                                                                                                  |
+
+## 6. Behavior changes you will feel at runtime
+
+No rename to grep for — these change what existing, still-compiling code does.
+
+1. **`BbButton` tracks async click handlers by default.** An `async @click`
+   now disables the button and shows a spinner until it settles. Opt out per
+   button with `disable-auto-loading`.
+2. **Single-select no longer clears on a second click**
+   (`BbSelect`, `BbSelectPopover`): re-clicking the selected option re-picks
+   and closes; it used to emit `null` and empty the field. If your UX relied on
+   click-to-clear, add `clearable` (or the `clear` slot callback). Multiple
+   mode still toggles.
+3. **`enforce-coherence` prunes on mount.** A seeded-but-invalid model value is
+   now cleared on the first load, not on the next change. If "my value clears
+   on load" appears after upgrading, your provider isn't resolving the current
+   selection on `prefill === true` calls — honor that contract or enable
+   `stash`.
+4. **Array `items` are never lazy**: they resolve on mount regardless of
+   `prefill`, so activator `text` is reliable from first paint.
+   And **`prefill: false` is search-first** on provider-backed selects: nothing
+   fetches until the user types (the panel shows a "search to begin" hint). A
+   v2 `prefill: false` select fetched on first open — if that's what you
+   wanted, delete the prop; load-on-open is the default. Details in
+   [bb-select.md](./components/bb-select.md).
+5. **A loading `BbTable` with rows keeps them visible** (dimmed, with a
+   progress bar) instead of flashing to skeleton — and the rows and header go
+   `inert` during the refetch. Escape hatch: `interactive-while-loading`. The
+   `#loading` slot fires on the **first load only** now.
+6. **Dynamic slot names are normalized** via
+   `slotKey(key) = key.split(/\W+/g).join('_').toLowerCase()` in
+   `BbBreadcrumbs`, `BbTree`, `BbTabs`, and the date-picker day slots.
+   `#Order History` → `#order_history`. **⚠ silent**: a stale raw-key slot
+   simply renders fallback content. `BbTabs` goes further: the label slot is
+   renamed (`#label-<key>` → `#label:<slotKey>`), the URL query value is the
+   normalized slug (`?tab=In%20Review` → `?tab=in_review` — update deep links
+   and server code), and tab/panel DOM ids are normalized. Only `v-model` /
+   item `key` stay raw.
+7. **Dialogs, popovers, dropdowns and selects open as bottom sheets on mobile**
+   by default (`adaptive`, default `true`). Set `adaptive: false` in the
+   plugin, or per component, for v2-like floating behavior.
+8. **`confirm()` buttons**: default labels are localized (no more hard-coded
+   "OK"/"Annulla") and footer buttons default to `md`.
+9. **Invalid enum-ish prop values** (`size`, `direction`, `BbSlider.labelMode`)
+   now warn in dev and fall back to the documented default instead of
+   rendering broken or throwing.
+10. **`BbTree` is a disclosure list, not an ARIA tree**: the unfulfilled
+    `role="tree"` / `treeitem` / `aria-level` markup is gone, and a collapsed
+    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).
+
+## 7. Class overrides → variants
+
+### The v2 pattern to hunt down
+
+v2 had no typed variant affordance, so project code commonly reached for the
+library's internal modifier classes (or invented look-alikes):
+
+```vue
+<!-- v2 userland -->
+<BbButton class="bb-button--outline">Cancel</BbButton>
+<BbAlert class="bb-alert--warning" title="Heads up" />
+<span class="bb-badge bb-badge--secondary">Draft</span>
+```
+
+These keep _rendering_ in v3 (the class hooks still exist), but they are now
+the wrong layer: they bypass the typed registry, silently drift when the
+library renames internals, and duplicate what a prop expresses. Convert them.
+
+### Finding them
+
+Run in the consumer project:
+
+```bash
+# any hand-applied bitboss modifier class in templates
+rg -n 'class="[^"]*bb-[a-z-]+--' --type vue
+rg -n ":class=\"[^\"]*'bb-[a-z-]+--" --type vue
+# free-form theme props (removed in v3)
+rg -n '(:?theme)=' --type vue
+# raw component markup rebuilt from classes (no <BbX> tag on the same line)
+rg -n 'class="bb-(button|badge|alert|toast-message|tooltip|indicator)\b' --type vue
+```
+
+### 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 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
+class.
+
+## 8. The silent-failure audit
+
+Everything the compiler cannot catch, in one grep pass. Run each in the
+consumer project; every hit needs a decision, not necessarily a change.
+
+```bash
+rg -in 'querykey'                         # → queryKey (URL params silently move)
+rg -n 'show-close|showClose'              # → hide-close, polarity inverted
+rg -n 'allow-select-all|allowSelectAll'   # → disable-select-all, inverted
+rg -n 'auto-loading|autoLoading'          # BbButton behavior flip / rename
+rg -n 'disabled-while-loading|disabledWhileLoading'  # removed
+rg -n 'animate-x|animate-y|animateX|animateY'        # → disableAnimate*, now default-on
+rg -n 'thumb-translate|thumbTranslate'    # → disable-thumb-translate
+rg -n ':flip=|flip="'                     # → disable-flip on palette/select-popover
+rg -n 'hide-arrow|show-arrow|arrow-padding|hideArrow|showArrow|arrowPadding'  # removed off tooltips
+rg -n '<BbChip'                           # component removed → BbBadge clearable
+rg -n '<BbBadge'                          # v2 badges are v3 indicators — review each
+rg -n '<BbTab[ >]'                        # → BbTabs
+rg -n '#label-'                           # BbTabs label slot → #label:<slotKey>
+rg -n 'reverse' --type vue                # BbRadio/BbSwitch default flipped
+rg -n ':timeout=' --type vue              # BbTooltip → delay (BbAvatar keeps timeout)
+rg -n '<BbIcon[^>]*type='                 # → icon=
+rg -n 'allow-writing|allowWriting'        # → disable-writing, inverted + new tokens
+rg -n 'show-chevron|showChevron|updateOnAnimationFrame|update-on-animation-frame'  # removed
+rg -n 'label-position|labelPosition'      # groups → legend-position
+rg -n 'prefill="focus"|prefill: .focus.'  # → 'interaction'
+rg -n ':prefill="false"|prefill: false'   # now search-first, not load-on-open
+rg -n 'role="tree|treeitem'               # BbTree ARIA roles removed
+rg -n ':filter-by="[^\x27\[]'             # function/string filterBy → string[]
+rg -n 'option:prepend|option:append|options:prepend|options:append|#chevron'  # removed slots
+rg -n '<Bb(Checkbox|Radio|Switch|Slider|Rating|Avatar|Icon|Spinner)[^>]*color='  # removed color props
+rg -n 'disabled:' --type ts --type vue    # item.disabled near option components → selectable
+rg -n 'picker' --type vue                 # color input/palette → eye-dropper
+rg -n 'bb-common-input-inner-container'   # CSS block → .common-input-wrapper
+rg -n 'IconRegistry|BbToastMessage|useWizard|BaseButtonProps|BaseDialog'  # removed exports
+rg -n 'setConfig'                         # only locale survives at runtime
+rg -n -- '--bb-(contrasting|primary-base|hint|icon-color|input-|overlay-|button-|dialog-p)'  # retired tokens
+```
+
+Also review, with no greppable signature: dialog/off-canvas **widths**
+(section 2), the **primary color** (section 3), `adaptive` bottom sheets on
+mobile (section 6), and any UX that relied on second-click-to-clear selects.
+
+## 9. Per-component guide index
+
+Detailed old→new tables and edit outlines live in
+[`migration/components/`](./components/). Components not listed have **no
+functional changes** — nothing to migrate beyond the family-wide notes above.
+That no-migration set is: `BbNumberInput`, `BbTextarea`, `BbProgress`,
+`BbSmoothHeight` (additive changes only).
+
+| Area              | Guides                                                                                                                                                                                                                                                    |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Actions           | [BbButton](./components/bb-button.md) · [BbDropdownButton](./components/bb-dropdown-button.md)                                                                                                                                                            |
+| Badges & status   | [BbBadge / BbIndicator](./components/bb-badge.md) · [BbChip (removed)](./components/bb-chip.md)                                                                                                                                                           |
+| Feedback          | [BbAlert](./components/bb-alert.md) · [BbToast / toast()](./components/bb-toast.md) · [confirm()](./components/use-confirm.md) · [BbSpinner](./components/bb-spinner.md)                                                                                  |
+| Surfaces          | [BbDialog](./components/bb-dialog.md) · [BbOffCanvas](./components/bb-off-canvas.md) · [BbPopover](./components/bb-popover.md) · [BbTooltip](./components/bb-tooltip.md) · [BbCollapsible](./components/bb-collapsible.md)                                |
+| Navigation & data | [BbDropdown](./components/bb-dropdown.md) · [BbTabs](./components/bb-tabs.md) · [BbTable](./components/bb-table.md) · [BbTree](./components/bb-tree.md) · [BbBreadcrumbs](./components/bb-breadcrumbs.md) · [BbPagination](./components/bb-pagination.md) |
+| Media             | [BbAvatar](./components/bb-avatar.md) · [BbIcon](./components/bb-icon.md)                                                                                                                                                                                 |
+| Text-ish inputs   | [BbTextInput](./components/bb-text-input.md) · [BbColorInput](./components/bb-color-input.md) · [BbDatePickerInput](./components/bb-date-picker-input.md) · [BbColorPalette](./components/bb-color-palette.md)                                            |
+| Selects           | [BbSelect](./components/bb-select.md) · [BbSelectPopover](./components/bb-select-popover.md)                                                                                                                                                              |
+| Choice controls   | [BbCheckbox / BbRadio / BbSwitch](./components/bb-checkbox.md) · [the three groups](./components/bb-checkbox-group.md)                                                                                                                                    |
+| Other inputs      | [BbSlider](./components/bb-slider.md) · [BbRating](./components/bb-rating.md) · [BbTag](./components/bb-tag.md) · [BbDropzone](./components/bb-dropzone.md)                                                                                               |