bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/guides/installation-and-plugin-setup.md

@@ -0,0 +1,440 @@
+---
+title: Installation and Plugin Setup
+summary: Canonical installation, style handling, and full plugin option reference for Vite, Nuxt, and Inertia consumers.
+---
+
+# Installation and Plugin Setup
+
+Source of truth for integrating `bitboss-ui`. Two pieces are always required:
+
+1. a **build plugin** (`bitboss-ui/vite` or `bitboss-ui/nuxt`) that serves the `virtual:bitboss-ui/icons` and `virtual:bitboss-ui/config` modules, scans local SVG icons, and generates typed variant registries;
+2. the **runtime plugin** (`bitbossUiPlugin` — installed automatically by the Nuxt module) that injects styles, provides the icon registry, and registers the `v-bb-tooltip` / `v-bb-dropdown` directives.
+
+## 1) Install
+
+```bash
+# v3 is a prerelease — the `@alpha` tag is REQUIRED.
+# A bare `npm install bitboss-ui` still resolves to v2, which has no build
+# plugin and no `dist/ai` knowledge base, so everything below silently fails.
+npm install bitboss-ui@alpha
+# recommended default icon set (any @iconify-json/* works)
+npm install -D @iconify-json/lucide
+```
+
+Confirm you got v3 before continuing — `npm ls bitboss-ui` must report a
+`3.0.0-alpha.*` version. If it reports `2.x`, nothing in this guide applies.
+
+Peer dependencies: `vue ^3.5.12` and `@iconify/collections` (auto-installed by npm 7+; powers dev-time icon-name validation). `@inertiajs/vue3` is an **optional** peer — only needed in Inertia apps.
+
+**Known-good toolchain:** TypeScript **5.x** if your build gate runs `vue-tsc`
+— TypeScript 7 changed its package layout in a way `vue-tsc` (not a peer of
+this library, but the typical `--noEmit` gate) cannot load, and fails with an
+`ERR_PACKAGE_PATH_NOT_EXPORTED` on `./lib/tsc`. This library doesn't pin
+TypeScript for you (it isn't `vue-tsc`'s maintainer), but a bare
+`npm i -D typescript` in a fresh project can resolve to 7.x today — pin
+`typescript: ^5.x` yourself if `vue-tsc` is part of your gate.
+
+### Browser support
+
+The library targets **evergreen browsers** and ships **no polyfills**. The
+floor is set by the native [Popover API](https://developer.mozilla.org/docs/Web/API/Popover_API),
+which every floating surface (selects, dropdowns, popovers, tooltips, color
+palette) renders through:
+
+| Engine        | Minimum            |
+| ------------- | ------------------ |
+| Chrome / Edge | **114** (May 2023) |
+| Safari        | **17** (Sep 2023)  |
+| Firefox       | **125** (Apr 2024) |
+
+Also relied on, all older than that floor: `<dialog>`, the `inert` attribute,
+`ResizeObserver`, and CSS `grid-template-rows` transitions. On older engines
+the floating surfaces simply don't render — there is no degraded mode — so if
+your fleet includes browsers below the floor, this library is not a fit
+without your own polyfill strategy (untested, unsupported).
+
+## 2) Vite + Vue
+
+```ts
+// 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',
+		}),
+	],
+});
+```
+
+```ts
+// main.ts
+import { createApp } from 'vue';
+import App from './App.vue';
+import { bitbossUiPlugin } from 'bitboss-ui';
+
+const app = createApp(App);
+app.use(bitbossUiPlugin);
+app.mount('#app');
+```
+
+If the icon folder does not exist yet, create it (`mkdir -p src/assets/icons`) and keep the path aligned with `iconDir`.
+
+## 3) Nuxt
+
+The Nuxt module wraps the same Vite plugin and auto-registers the runtime plugin — no `app.use` needed:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+	modules: ['bitboss-ui/nuxt'],
+	bitboss: {
+		iconDir: './assets/icons', // module default
+	},
+});
+```
+
+All options below go under the `bitboss` config key. `nuxtLinkName` controls which globally registered component renders router links (default `'NuxtLink'`).
+
+## 4) Inertia
+
+Inertia apps are Vite apps: configure `bitboss-ui/vite` exactly as in section 2, install `@inertiajs/vue3`, then install the runtime plugin in `createInertiaApp`:
+
+```ts
+createInertiaApp({
+	// ...resolve/setup
+	setup({ el, App, props, plugin }) {
+		createApp({ render: () => h(App, props) })
+			.use(plugin)
+			.use(bitbossUiPlugin)
+			.mount(el);
+	},
+});
+```
+
+That is the whole setup — **you do not need to register a link component**. When
+the build plugin sees `@inertiajs/vue3` in your app, it imports Inertia's `Link`
+on your behalf, so `href` on buttons/items performs Inertia visits (`method`,
+`data`, `headers`, `preserveScroll`, …) out of the box.
+
+If your app registers its **own** link wrapper globally — one with baked-in
+defaults, analytics, whatever — that keeps winning: a component registered under
+`inertiaLinkName` (default `'Link'`) is always preferred over the imported one.
+Register it under a different name and point `inertiaLinkName` at it.
+
+## 5) Styling
+
+Two runtime options control CSS:
+
+- `injectStyles` (default `true`) — auto-injects the library stylesheet (equivalent to `bitboss-ui/styles.css`: base styles + design tokens);
+- `resetCss` (default `false`) — opt-in injection of the reset stylesheet.
+
+Guaranteed order when injected: **reset → library styles → all other stylesheets**, so app-local CSS can always override the library.
+
+`resetCss` stays opt-in because Tailwind projects already ship Preflight — a second reset is usually unnecessary.
+
+**Tailwind v4 cascade layers vs. scoped `<style>`:** Tailwind v4's `@import
+'tailwindcss'` puts every utility class in `@layer utilities`. A Vue SFC's
+`<style scoped>` block is **unlayered** CSS, and per the cascade, unlayered
+rules always beat layered rules of equal specificity — regardless of source
+order. So a component with its own scoped layout-affecting rule silently
+defeats a Tailwind utility applied to it from outside, with no warning from
+`bitboss-ui check`, `eslint`, or `vue-tsc`:
+
+```vue
+<!-- Parent -->
+<CategoryTree class="hidden lg:block" />
+
+<!-- CategoryTree.vue -->
+<style scoped>
+.category-tree {
+	display: flex; /* unlayered — always wins over the layered `hidden` utility */
+}
+</style>
+```
+
+`CategoryTree` never actually hides. Prefer `v-if`/JS conditionals over
+utility classes for hide/show behavior on components (yours or ones built on
+top of `bitboss-ui`) that carry their own layout-affecting scoped styles:
+
+```vue
+<CategoryTree v-if="showSidebar" />
+```
+
+Manual alternatives:
+
+```ts
+// with injectStyles: false — import once, before your own CSS
+import 'bitboss-ui/styles.css';
+// explicit reset instead of resetCss: true
+import 'bitboss-ui/reset.css';
+```
+
+## 6) Icons
+
+- `iconDir` (required) is scanned recursively for `.svg` files; each file becomes `local:<basename>`.
+- Provider icons (`lucide:pencil`, `mdi:home`, …) require the matching `@iconify-json/<prefix>` package installed in the consumer app. Missing packages/icons produce actionable dev-overlay errors.
+- Production builds bundle **only statically referenced** provider icons — write icon names as literal strings (`icon="lucide:trash-2"`), never assemble them dynamically.
+- The plugin also writes `node_modules/.bitboss-ui/local-icons.json` and wires `.vscode/settings.json` so the Iconify editor extension previews local icons.
+
+Policy for choosing icons: [Icons Policy](./icons-policy.md).
+
+## 7) Complete Option Reference
+
+Options are the same for `bitboss-ui/vite` and the `bitboss` key in Nuxt.
+
+### `iconDir: string` (required)
+
+Path to local SVG icons, absolute or relative to project root. Scanned recursively; file basename (without extension) becomes the icon name, addressable as `local:<name>`.
+
+### `injectStyles?: boolean` (default: `true`)
+
+Auto-inject the library stylesheet at runtime. If `false`, you must `import 'bitboss-ui/styles.css'` manually.
+
+### `resetCss?: boolean` (default: `false`)
+
+Inject the reset stylesheet (always ordered before the library stylesheet). Keep `false` and import `bitboss-ui/reset.css` if you prefer explicit control.
+
+### `injectDirectives?: boolean` (default: `true`)
+
+Registers the global `v-bb-tooltip` and `v-bb-dropdown` directives when the runtime plugin installs. Disable only if the names collide with your own directives.
+
+### `adaptive?: boolean` (default: `true`)
+
+Default for the `adaptive` prop of surface components (BbDialog, BbPopover, BbDropdown, BbSelect): when true they open as a bottom sheet on mobile (below `mobileMaxWidth`) instead of their floating surface. An explicit per-component `adaptive` prop always wins.
+
+### `mcp?: boolean` (default: `false`)
+
+When `true`, the **dev server** registers the bitboss-ui MCP server in each project-scoped agent-harness config on boot — `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), and `.vscode/mcp.json` (VS Code / Copilot) — so agents can query the knowledge base with no manual setup. The write is merge-safe (leaves other servers alone) and idempotent (only logs when it actually changes a file). Windsurf is intentionally **not** written here: its config is global (`~/.codeium`), and silently editing a home-dir file that affects every project on the machine from a dev-server boot would be surprising — run `npx bitboss-ui ai-init --mcp` to register Windsurf too. This flag is the zero-command equivalent of that command's project-scoped writes.
+
+### `inertiaLinkName?: string` (default: `'Link'`)
+
+Global component name used for Inertia links. **Optional** — when nothing is
+registered under this name, the library falls back to the `Link` the build
+plugin imported from your `@inertiajs/vue3` install. Set it only when you want a
+wrapper of your own to be used instead.
+
+### `nuxtLinkName?: string` (default: `'NuxtLink'`)
+
+Global component name used for Nuxt link rendering.
+
+### `linkActiveClass?: string` (default: `'router-link-active'`)
+
+### `linkExactActiveClass?: string` (default: `'router-link-exact-active'`)
+
+Class names applied to active / exact-active links in router-aware components. Align them with your router configuration.
+
+### `mobileMaxWidth?: number` (default: `768`)
+
+Pixel breakpoint for the library's mobile behavior (including `adaptive` surfaces).
+
+### `ssrViewportWidth?: number` (default: `1024`)
+
+The viewport width the library assumes while rendering **on the server**, where
+the real screen size is unknowable. The default `1024` is a desktop width, so
+server output is desktop-first. On the client the real `window.innerWidth` is
+used from the first paint.
+
+**Client-only SPA?** Ignore this — the real width is known from the first paint,
+so `adaptive` surfaces are correct immediately.
+
+**Server-rendering (Nuxt / Inertia SSR)?** By default the server renders
+desktop-shaped; a mobile visitor's first paint is desktop-shaped and adjusts
+once the client measures the real width (for closed overlays this is invisible —
+they're not on screen yet; a Vue hydration warning may appear in dev). Set this
+to a different width if your app is primarily consumed on a known form factor:
+
+```ts
+// vite.config.ts — build-time, applied to every server render.
+bitbossUi({
+	// ...other options,
+	ssrViewportWidth: 768,
+});
+```
+
+This is a **single global default baked in at build time** (it comes from the
+Vite plugin config), so it is the same for every request — it is _not_ a
+per-request value. There is no per-request/per-visitor override today: the
+viewport signal is a process-wide singleton, so a mobile layout that must be
+correct on the server's first paint (e.g. a modal already open on load) needs a
+client adjustment after hydration, or a fixed `ssrViewportWidth` matching your
+audience.
+
+### `defaultInputLabelMode?: 'outside' | 'floating' | 'inside'` (default: `'outside'`)
+
+Default label rendering mode for input-like components; set globally instead of repeating per field.
+
+### `locale?: LocaleKey` (default: `'it'`)
+
+Global locale for the library's built-in strings (empty states, close/clear
+labels, screen-reader announcements, confirm buttons, …). The library ships
+**22 built-in dictionaries** — it, en, es, fr, de, pt (Brazilian-leaning), nl,
+pl, tr, ru, uk, cs, ro, hu, el, sv, da, nb, fi, ja, ko, zh-cn — but shipping ≠
+bundling: only the **enabled** locales enter your build (next option). Runtime
+switching: `useBbConfig().setConfig({ locale })` — to a locale you enabled.
+
+### `enabledLocales?: BuiltinLocaleKey[]` (default: your `locale` + `'en'`)
+
+Which built-in dictionaries (and their dayjs calendar packs) actually ship in
+the bundle. The unset default is the minimal set — the `locale` you configured
+plus `en` (the per-key fallback anchor) — roughly 4KB of strings, so a
+single-language app pays for exactly what it uses without configuring
+anything. Apps that switch locales at runtime list what they offer:
+
+```ts
+bitbossUi({
+	iconDir: './src/assets/icons',
+	locale: 'it',
+	enabledLocales: ['it', 'en', 'de', 'fr'], // ~4 dictionaries + 4 dayjs packs
+});
+```
+
+Your `locale` and `'en'` are always auto-included, so the list never needs to
+repeat them; custom `additionalLocales` keys are always enabled and don't
+belong here.
+There is deliberately **no catch-all** ("all") value — it would hide the
+bundle cost. Wanting every built-in means writing the list, so the cost is
+visible in your config where reviewers can see it.
+
+**Selecting a non-enabled locale is a compile error**, not a silent runtime
+fallback: the generated `locale-registry.d.ts` registers only enabled
+built-ins + custom keys, so `setConfig({ locale: 'ja' })` fails to type-check
+until `'ja'` is enabled. Run dev once after changing the list.
+
+### `additionalLocales?: CustomLocales` (default: `{}`)
+
+**Additional** locale dictionaries, keyed by locale. Strictly additive:
+built-in locales cannot be overridden — a built-in key here is a type error,
+and one smuggled past the compiler is ignored with a build-time warning.
+
+The full flow for adding a locale (using Georgian, which the library doesn't
+ship):
+
+```bash
+# 1. Generate a translation blueprint (English strings) at the project root
+npx bitboss-ui locale ka
+```
+
+```ts
+// 2. Translate ka.locale.ts, then register it
+import ka from './ka.locale';
+
+bitbossUi({
+	iconDir: './src/assets/icons',
+	locale: 'ka',
+	additionalLocales: { ka },
+});
+```
+
+That's the whole setup — on build start the plugin:
+
+- **verifies the dictionary against the library's English template** and warns
+  about `missing` keys (strings the library requires that your translation
+  doesn't cover — this is how a library upgrade that adds new strings alerts
+  you instead of silently falling back to the default locale forever) and
+  `unknown` keys (typos, or strings an upgrade removed).
+
+- **regenerates `locale-registry.d.ts`**, augmenting `LocaleRegistry` with
+  your keys (exactly like the variant registries), so `'ka'` is a valid
+  `locale` value everywhere — the plugin option and `setConfig({ locale })`
+  alike. Run dev once after adding a key so the file exists.
+- **wires the matching dayjs locale** (`dayjs/locale/ka`) so calendars follow
+  your locale's month/day names and week start. Any dayjs-shipped name works.
+  If dayjs has no locale under your key, the plugin **warns at build time**
+  and calendars fall back to English (there is no runtime warning) — when a
+  nearby dayjs name exists (`zh-cn`, `pt-br`, …), prefer it as your key.
+
+Keys you delete from the blueprint fall back per-key to the default locale
+(your `locale` when it's a built-in, otherwise `en` — always bundled, always
+complete) — and are reported by the completeness warning above, which is the
+point: partial is allowed, silent-partial is not.
+
+Locale dictionaries are **build-time only**: `setConfig` accepts `locale` but
+deliberately not `additionalLocales` — a runtime path would bypass every check
+the plugin performs (built-in collision, completeness verification, dayjs
+wiring, registry typing). Only the active `locale` switches at runtime, among
+what the build enabled.
+
+### `toastPosition?: BbToastPosition` (default: `'bottom-right'`)
+
+Default viewport corner for toasts when neither the toast nor the `<BbToast>` host specify one. One of `'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'`.
+
+### `iconDefaultSizes?: Partial<Sizes>`
+
+Default icon size scale used by `BbIcon` and avatar dimensions. Partial overrides merge onto:
+
+`{ xs: 12, sm: 16, md: 24, lg: 28, xl: 36, '2xl': 40 }`
+
+### `dialogDefaultSizes?: Partial<Sizes>`
+
+### `offCanvasDefaultSizes?: Partial<Sizes>`
+
+Global size maps (pixels) for BbDialog / BbOffCanvas. Both default to:
+
+`{ xs: 320, sm: 384, md: 448, lg: 512, xl: 576, '2xl': 672 }`
+
+Provide only the keys you want to override, e.g. `dialogDefaultSizes: { md: 500, xl: 680 }`.
+
+### Variant registries
+
+Each option **appends** custom names to the default set (trimmed, deduplicated) and regenerates a typed union (`*-variants.d.ts`) on build start. Unstyled custom variants only add a class hook — supply their CSS yourself.
+
+**The generated `*-variants.d.ts` files are per-project output, not a portable
+variant list.** They mirror the plugin config of the project that last ran the
+plugin in that folder, and are rewritten by every build/dev/test process. Your
+project's registry is what **your** plugin config declares — never trust names
+read out of another checkout's copy (e.g. the library repo's own tracked seeds
+list variants that exist only in its dev showcase). Each generated file now
+says this in its header.
+
+| Option                 | Defaults                                                | Class hook for custom entries       |
+| ---------------------- | ------------------------------------------------------- | ----------------------------------- |
+| `buttonVariants`       | `primary, outline, secondary, ghost, destructive, link` | `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>`              |
+| `confirmVariants`      | `default, destructive`                                  | `bb-confirm--<name>`                |
+| `dropdownItemVariants` | `default, destructive`                                  | `bb-dropdown__item--variant-<name>` |
+| `tooltipVariants`      | `default, destructive`                                  | `bb-tooltip--<name>`                |
+| `toastVariants`        | `default, success, info, warning, destructive`          | `bb-toast-message--<name>`          |
+
+Variant props are locked to the registered set (`keyof <X>VariantRegistry`):
+an unregistered name is a compile error, not a silently unstyled render.
+Register custom names here (typed, autocompleted), or force a one-off with an
+explicit cast — the runtime class is still plain interpolation, so its CSS
+applies either way.
+
+**Adding a variant is a normal, expected consumer change** — the defaults are a
+floor, not a vocabulary you must stay inside. A page that needs a tone the
+library doesn't ship registers it here **and** styles its class hook in a
+project stylesheet loaded after `bitboss-ui/styles.css`; both halves, or you get
+an unstyled pill (CSS missing) or a compile error (registration missing). If the
+design calls for semantic status colors, take the canonical palette from
+[Design Language](./design-language.md) § Getting soft semantic badges rather
+than inventing hues.
+
+## 8) AI Knowledge Base
+
+The package ships its agent docs in `node_modules/bitboss-ui/dist/ai/`. **Start at** `guides/ai-router.md`, then the catalogue `index.md`. Run `npx bitboss-ui ai-init` in the consumer project to inject harness-agnostic pointers (AGENTS.md, Cursor rules, Copilot instructions, Claude skill, Windsurf rules) so coding agents discover them without a vendor lock-in. After generating Bb\* markup, run `npx bitboss-ui check` (supports `--json`) so unknown props fail before review.
+
+Add `--mcp` to also register a live MCP server (`npx bitboss-ui mcp`) the harness launches on demand — it merges the entry (never overwriting other servers) into `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), `.vscode/mcp.json` (VS Code / Copilot), and `~/.codeium/windsurf/mcp_config.json` (Windsurf). **Windsurf's config is global** — it has no per-project scope, so registering it affects every project on the machine; that is why only the explicit `ai-init --mcp` command writes it, while the plugin's `mcp: true` dev-server flag (§7) auto-registers the project-scoped harnesses only.
+
+For a human-in-the-loop (and agent) safety net, add the `bitboss-ui/eslint-plugin` flat-config plugin (`...bitbossUi.configs.recommended`) so unknown/removed `Bb*` props surface as ESLint errors in the editor and CI — the same manifest checks as `bitboss-ui check`, reusing your `eslint-plugin-vue` parser. Real HTML attributes fall through untouched; escape hatches are the standard `<!-- eslint-disable-next-line bitboss-ui/no-unknown-attributes -->` and the rule's `allowAttributes` / `allowComponents` options. **`eslint --fix` also auto-migrates deprecated v2 props** (renames, boolean-polarity inversions like `allowWriting`→`disableWriting`, value remaps like BbToast `placement`→`position`, and deletion of inert removed props); structural migrations that need a slot/directive/CSS are reported but left by hand. **This library is TS-first (recipes ship `<script setup lang="ts">`, some with `generic="T"`), so wire `@typescript-eslint/parser` for both `.ts` and `.vue` files** — without it `vue-eslint-parser` throws a `Parsing error` on those files, which means no rule (including `no-unknown-attributes`) runs on them at all. See the README "ESLint plugin" section for the full config snippet (both parser blocks + the `npm i -D @typescript-eslint/parser` line) and the fix table.
+
+## 9) Setup Verification Checklist
+
+- [ ] package installed (plus `@iconify-json/*` packages for every provider prefix used);
+- [ ] build plugin configured: `bitboss-ui/vite` plugin or `bitboss-ui/nuxt` module (`bitboss` config key);
+- [ ] `iconDir` points at an existing SVG folder;
+- [ ] runtime plugin installed: `app.use(bitbossUiPlugin)` (automatic in Nuxt);
+- [ ] style strategy chosen: auto injection (default) or `injectStyles: false` + `import 'bitboss-ui/styles.css'`;
+- [ ] if a reset is required: `resetCss: true` or `import 'bitboss-ui/reset.css'`;
+- [ ] Inertia apps: `@inertiajs/vue3` installed (no link registration needed; set `inertiaLinkName` only if you register your own link wrapper).
+- [ ] building the [Layout Scaffold](../recipes/vue/layout-scaffold.md)? `npm i @vueuse/core` — `usePageShellContext.ts` imports `injectLocal`/`provideLocal` from it. This library depends on it too, so it can resolve via hoisting without being declared — don't rely on that; declare it in your own `package.json` or a strict installer (pnpm, Yarn PnP) will fail to resolve it.
+- [ ] `vite.config.ts` (and any other build config, e.g. `eslint.config.js`) is inside your project's type-check scope — a `tsconfig.node.json` project reference is the conventional shape. Otherwise `bitbossUi(...)`'s typed options (`locale`, the `*Variants` registries, `iconDefaultSizes`, …) are never checked by `vue-tsc --noEmit`, silently defeating the compile-time guarantees this guide documents (e.g. "selecting a non-enabled locale is a compile error").
+
+If one of the checks fails, fix setup before creating component examples.

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

@@ -0,0 +1,37 @@
+---
+title: 'Migration v2→v3: BbAlert'
+summary: showClose inverted to hideClose, theme replaced by typed variant.
+---
+
+# BbAlert — v2 → v3
+
+## Changes
+
+| v2                                      | v3                                                                                                   | Kind                                       |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| `showClose?: boolean` (default `true`)  | `hideClose?: boolean` (default `false`)                                                              | rename, polarity inverted                  |
+| `theme?: string`                        | `variant?: AlertVariantType` (default `outline`; built-ins `outline, primary, destructive, warning`) | typed — unregistered names fail to compile |
+| `ariaAtomic?: boolean` (default `true`) | removed                                                                                              | correct live-region behavior hardcoded     |
+| `icon?: BbIconProps['type']`            | `icon?: IconType` (also accepts raw `?raw` SVG)                                                      | widened                                    |
+| —                                       | `role`, `ariaLive`, `transitionDuration`                                                             | additive (auto-derived from variant)       |
+
+Also fixed, worth knowing if you worked around it: the `#text` slot's scope
+prop now actually carries `text` (v2 mistakenly passed `title`).
+
+## Edits
+
+```diff
+- <BbAlert :show-close="false" title="Saved" text="All changes stored." />
++ <BbAlert hide-close title="Saved" text="All changes stored." />
+
+  <!-- passing showClose's default -->
+- <BbAlert show-close … />
++ <BbAlert … />
+
+- <BbAlert theme="warning" title="Quota almost reached" />
++ <BbAlert variant="warning" title="Quota almost reached" />
+```
+
+A hand-applied `class="bb-alert--warning"` also becomes `variant="warning"` —
+see [main guide §7](../v2-to-v3.md). Custom `theme` names: register via the
+plugin's `alertVariants` option and keep your CSS.

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

@@ -0,0 +1,24 @@
+---
+title: 'Migration v2→v3: BbAvatar'
+summary: The color prop is removed — the initials fallback is always primary.
+---
+
+# BbAvatar — v2 → v3
+
+## Changes
+
+| v2               | v3                                                                                            | Kind                                                                                            |
+| ---------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `color?: string` | removed                                                                                       | initials fallback always uses the primary tokens; override `.bb-avatar` CSS for anything custom |
+| `timeout`        | unchanged (SSR image grace period — **not** renamed; only `BbTooltip.timeout` became `delay`) | —                                                                                               |
+
+## Edits
+
+```diff
+- <BbAvatar :src="user.photo" :alt="user.name" color="#7c3aed" />
++ <BbAvatar :src="user.photo" :alt="user.name" />
+```
+
+If per-user colors mattered, set them in CSS on a wrapper
+(`.team-avatar--purple .bb-avatar { … }`) — the component no longer carries
+presentation-by-prop.

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

@@ -0,0 +1,110 @@
+---
+title: 'Migration v2→v3: BbBadge (and where your v2 badges went)'
+summary: The v2 BbBadge (floating count/dot) is now BbIndicator; the v3 BbBadge is a new inline pill that also replaces BbChip.
+---
+
+# BbBadge — v2 → v3
+
+**The name changed meaning.** This is the one place in v3 where the same tag
+renders a different component:
+
+- **v2 `BbBadge`** anchored a floating count/dot to a wrapped element
+  (notification-bubble pattern). That component is now **`BbIndicator`**.
+- **v3 `BbBadge`** is an inline pill/label with `variant`, `icon`, `loading`,
+  `clearable` — it also absorbs the removed `BbChip`.
+
+Every v2 `<BbBadge>` in your codebase must be reviewed: rename it to
+`BbIndicator`, or — if it was actually used as a standalone colored label —
+re-express it with the new badge's `variant` API.
+
+## v2 BbBadge → v3 BbIndicator
+
+| v2 `BbBadge`                         | v3 `BbIndicator`                                                                                     |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------- |
+| `content?: string \| number \| null` | `text?: string \| number` — plus new `max?: number` (renders `${max}+`)                              |
+| `color?: string` (free-form)         | `variant?: IndicatorVariantType` (`default, success, info, warning, destructive`; default `default`) |
+| `dot`, `left`, `bottom`              | unchanged                                                                                            |
+| `floating`                           | removed — the indicator always positions against its slotted anchor                                  |
+| `#content` slot                      | dropped — use `text`                                                                                 |
+
+```diff
+- <BbBadge :content="unread" color="#dc2626" floating>
++ <BbIndicator :text="unread" :max="99" variant="destructive">
+    <BbButton icon="lucide:bell" variant="ghost" />
+- </BbBadge>
++ </BbIndicator>
+```
+
+If you styled `.bb-badge` in CSS for this use, the block is now
+`.bb-indicator` (`--dot`, `--left`, `--bottom`, `--<variant>` modifiers).
+
+## v2 BbChip → v3 BbBadge
+
+Same role (dismissible token), two functional deltas: `clearable` is now
+**opt-in** (chips defaulted clearable), and the label is the **default slot**
+— there is **no `text`/`content` prop** on the v3 badge.
+
+```diff
+- <BbChip :text="tag.name" @click:clear="remove(tag)" />
++ <BbBadge clearable @click:clear="remove(tag)">{{ tag.name }}</BbBadge>
+```
+
+`clearableLabel` and the `click:clear` event carry over unchanged. CSS:
+`.bb-chip*` → `.bb-badge*` (`.bb-chip__clear-button` → `.bb-badge__clear-button`).
+
+### Clickable chips: `BbBadgeButton`
+
+A v2 chip that was _also_ clickable was typically hand-built — a `<button>`
+wrapping the chip, or a chip inside an `@click` div. v3 has a first-class form:
+slot a **`BbBadgeButton`** as a direct child and the badge body becomes a real
+`<button>`, while the clear control stays a separate sibling button.
+
+```diff
+- <button class="chip-button" @click="edit(filter)">
+-   <BbChip :text="filter.label" @click:clear="remove(filter)" />
+- </button>
++ <BbBadge clearable @click:clear="remove(filter)">
++   <BbBadgeButton @click="edit(filter)">{{ filter.label }}</BbBadgeButton>
++ </BbBadge>
+```
+
+The v2 nesting was invalid markup (a `<button>` may not contain another
+button); the v3 form is two sibling controls, so both are keyboard-reachable.
+`BbBadgeButton` composes `BbBaseButton`, so `href`/`to`/Inertia navigation and
+`disabled` work on it too. It must be a **direct child** of the badge.
+
+## The v3 badge itself
+
+`variant?: BadgeVariantType` (default `primary`; built-ins
+`primary, secondary, destructive, outline`), `size` (default `md`), `icon` /
+`prepend:icon` / `append:icon`, `loading`. Unregistered variant names are
+compile errors — register custom ones via the plugin's `badgeVariants` option
+([main guide §4](../v2-to-v3.md)).
+
+Hand-built pills (`<span class="bb-badge bb-badge--secondary">`) should become
+real `<BbBadge variant="secondary">` elements — see
+[main guide §7](../v2-to-v3.md).
+
+### Internal DOM changed (CSS only)
+
+The badge now renders two side wrappers so the body and the clear control can
+be independent controls:
+
+```html
+<span class="bb-badge">
+	<span class="bb-badge__body">…icon + <span class="bb-badge__content" /></span>
+	<span class="bb-badge__trailing">…append icon + clear button</span>
+</span>
+```
+
+All existing class hooks (`.bb-badge`, `.bb-badge__content`,
+`.bb-badge__clear-button`, `.bb-badge__prepend-icon`, `.bb-badge__append-icon`,
+every `--<variant>` / `--<size>` modifier) are unchanged and still match. **Only
+direct-child selectors break** — `.bb-badge > .bb-badge__content` must become a
+descendant selector, since the content span now sits inside `.bb-badge__body`.
+
+Two related CSS shifts, both invisible unless you overrode them: the pill's
+inline padding moved onto the side wrappers (via new `--pad-left` /
+`--pad-right` custom properties) so each hit area runs flush to the border, and
+the clear button's hover wash moved from the button onto its glyph, so the
+button can span the full pill height while only the circle looks interactive.

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

@@ -0,0 +1,26 @@
+---
+title: 'Migration v2→v3: BbBreadcrumbs'
+summary: Item keys must be strings, the text divider prop is gone, per-item slot names are normalized.
+---
+
+# BbBreadcrumbs — v2 → v3
+
+## Changes
+
+| v2                                | v3                                                                                           | Kind                                                                                                                |
+| --------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| item `key: string \| number`      | `key: string`                                                                                | retype — numeric keys fail `vue-tsc`; wrap in `String(...)` (runtime already stringified, so behavior is unchanged) |
+| `divider?: string` (text divider) | removed                                                                                      | the divider is slot-driven; use the divider slot for custom glyphs                                                  |
+| `dividerWidth` default `5`        | default `16`                                                                                 | visual — only matters if you tuned overflow math around the old default                                             |
+| per-item slots by raw `key`       | by `slotKey(key)` — `#Order History` → `#order_history`                                      | **⚠ silent** — stale raw names render fallback content                                                              |
+| —                                 | item `prepend:icon` / `append:icon`, per-key `:prepend`/`:append` slots, overflow forwarding | additive                                                                                                            |
+
+## Edits
+
+```diff
+- <BbBreadcrumbs :items="[{ key: 1, text: 'Home', href: '/' }]" divider=">">
++ <BbBreadcrumbs :items="[{ key: 'home', text: 'Home', href: '/' }]">
+-   <template #Order History>…</template>
++   <template #order_history>…</template>
+  </BbBreadcrumbs>
+```