bitboss-ui 2.1.135 → 3.0.0-alpha.4

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

@@ -0,0 +1,24 @@
+---
+title: 'Migration v2→v3: BbPagination'
+summary: querykey renamed to queryKey; the loading prop is removed.
+---
+
+# BbPagination — v2 → v3
+
+## Changes
+
+| v2                                           | v3                                                              | Kind                                                                                                                                   |
+| -------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `querykey?: string`                          | `queryKey?: string` (default `'page'`)                          | **⚠ silent** — a leftover `querykey` is ignored; URL sync moves to `?page=`, breaking deep links and server code reading the old param |
+| `loading?: boolean`                          | removed                                                         | use `disabled` while a page loads if you need to block interaction                                                                     |
+| `label` default `'Paginazione'` (hard-coded) | localized default                                               | cosmetic unless you asserted on it                                                                                                     |
+| —                                            | `tableId` (binds to a `BbTable` context and derives page count) | additive                                                                                                                               |
+
+## Edits
+
+```diff
+- <BbPagination v-model="page" :total="pages" querykey="p" :loading="fetching" />
++ <BbPagination v-model="page" :total="pages" query-key="p" :disabled="fetching" />
+```
+
+`rg -i 'querykey'` finds every case, including kebab usage.

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

@@ -0,0 +1,52 @@
+---
+title: 'Migration v2→v3: BbPopover'
+summary: Built-in close button, restoreFocus, theme, and the arrow are gone; close affordances move into your content.
+---
+
+# BbPopover — v2 → v3
+
+## Changes
+
+| v2                                                                               | v3                                                                                                                    | Kind                                                                                                                                                                                                                                |
+| -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `showClose`, `closeLabel`                                                        | removed                                                                                                               | render your own close control with the default slot's `close` callback                                                                                                                                                              |
+| `restoreFocus?: boolean` (default `true`)                                        | removed                                                                                                               | focus restoration is built-in behavior now, not a knob                                                                                                                                                                              |
+| `theme?: string`                                                                 | removed                                                                                                               | style via class/CSS                                                                                                                                                                                                                 |
+| `block`                                                                          | removed                                                                                                               | dead prop                                                                                                                                                                                                                           |
+| `hideArrow` (default `true`), `arrowPadding`                                     | removed                                                                                                               | **arrows are tooltip-only in v3.** A popover never shows one. If you passed `:hide-arrow="false"` to get a pointing bubble, that UI is now `BbTooltip`'s job. **⚠ silent**: a leftover `hide-arrow` binding just lands in `$attrs`. |
+| `activator` / `boundary` loose types                                             | `ElementOrComponentRef` / `…OrSelector`                                                                               | transparent in templates                                                                                                                                                                                                            |
+| imperative template-ref API (`popoverRef.value.show()` / `.close()` / `.isOpen`) | removed → `v-model`                                                                                                   | write `true`/`false` to open/close; the popover writes it back on dismiss (the BbDialog/BbOffCanvas pattern). **⚠ silent**: a stale `popoverRef.value?.show()` is `undefined` at runtime (no compile error in untyped templates).   |
+| —                                                                                | `adaptive` + `offCanvasProps` (mobile bottom sheet, on by default), `header` / `footer` slots, `show` / `hide` events | additive                                                                                                                                                                                                                            |
+| floating wrapper/bubble rendered as `<span>`                                     | rendered as `<div>` (`<dialog>` in dialog mode, as before)                                                            | DOM only — the bubble holds block content, so `<span>` was invalid markup. Class hooks (`.bb-common-popover`, `.bb-common-popover__bubble`) are unchanged; only element selectors like `span.bb-common-popover` break.              |
+
+## Edits
+
+```diff
+- <BbPopover :activator="btn" show-close close-label="Dismiss">
+-   <p>Saved searches let you…</p>
++ <BbPopover :activator="btn">
++   <template #default="{ close }">
++     <p>Saved searches let you…</p>
++     <BbButton variant="ghost" size="sm" @click="close">Dismiss</BbButton>
++   </template>
+  </BbPopover>
+
+  <!-- v2 arrow popover = v3 tooltip -->
+- <BbPopover :activator="info" :hide-arrow="false">Short hint text</BbPopover>
++ <BbTooltip :activator="info">Short hint text</BbTooltip>
+```
+
+For the imperative case, the template-ref expose is gone — drive the popover
+with `v-model` instead (it writes the model back on every dismiss, so reading it
+stays accurate):
+
+```diff
+- <BbPopover ref="popoverRef">…</BbPopover>
++ <BbPopover v-model="open">…</BbPopover>
+
+- popoverRef.value?.show();
++ open.value = true;   // open.value = false to close; reads true only while open
+```
+
+Remember `adaptive`: on mobile the popover becomes a bottom sheet by default —
+opt out with `:adaptive="false"` if the floating panel must persist.

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

@@ -0,0 +1,24 @@
+---
+title: 'Migration v2→v3: BbRating'
+summary: color removed; name no longer required.
+---
+
+# BbRating — v2 → v3
+
+## Changes
+
+| v2                        | v3                                                                                    | Kind                                                    |
+| ------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `color?: string`          | removed                                                                               | stars follow `currentColor` / theme tokens              |
+| `name: string` (required) | `name?: string` (auto-generated when omitted)                                         | relaxation — keep passing it only for native form posts |
+| —                         | `clearable` (click the current value to zero the rating), `legendMode`, `description` | additive                                                |
+
+## Edits
+
+```diff
+- <BbRating v-model="score" name="score" color="#eab308" />
++ <BbRating v-model="score" clearable />
+```
+
+Adding `clearable` is recommended: the old "re-click to clear" folklore is
+now a visible affordance.

package/dist/ai/guides/migration/components/bb-select-popover.md

@@ -0,0 +1,59 @@
+---
+title: 'Migration v2→v3: BbSelectPopover'
+summary: flip and allowWriting inverted, arrow props removed, filterBy narrowed, options slots replaced by header/footer; shares BbSelect's behavior changes.
+---
+
+# BbSelectPopover — v2 → v3
+
+## Props
+
+| v2                                                          | v3                                                                                                                | Kind                                                                                                                                        |
+| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `flip?: boolean` (default `true`)                           | `disableFlip?: boolean` (default `false`)                                                                         | rename, polarity inverted                                                                                                                   |
+| `allowWriting?: boolean \| 'not-mobile'` (default `true`)   | `disableWriting?: boolean \| 'mobile' \| 'desktop'` (default `false`)                                             | rename, polarity inverted, token set changed                                                                                                |
+| `hideArrow` (default `true`), `arrowPadding` (default `10`) | removed                                                                                                           | arrows are tooltip-only in v3; **⚠ silent** — `:hide-arrow="false"` (the only meaningful v2 use) now lands in `$attrs` and no arrow renders |
+| `transitionDuration` default `300`                          | default `250`                                                                                                     | visual — the panel now animates on the shared `transitions.medium` scale, like `BbDialog`                                                   |
+| `filterBy` union (fn, `false`, `'not_stashed'`, …)          | `filterBy?: string[]` (default `[]`)                                                                              | retype — filter your `items`/provider instead                                                                                               |
+| `itemText` / `itemValue`                                    | `ItemAccessor<Item, …>`                                                                                           | retype                                                                                                                                      |
+| per-item `disabled`                                         | inert — use `selectable`                                                                                          | **⚠ silent**                                                                                                                                |
+| —                                                           | `anchor`, `adaptive` + `offCanvasProps`, `selectable`, `active` event, activator scope `text` / `selectedOptions` | additive                                                                                                                                    |
+
+## Slots
+
+`#options:prepend`, `#options:append` and their `:outer` twins are removed —
+the panel now has `#header` / `#footer`.
+
+## Behavior (shared with BbSelect — same engine)
+
+- Single-select second click re-picks instead of clearing; use the slot-scope
+  `clear` callback for an explicit clear affordance.
+- `enforce-coherence` + a seeded model forces the first load and prunes
+  invalid values **on mount**.
+- Array `items` resolve on mount regardless of `prefill` — activator `text`
+  is reliable from first paint for arrays. Provider-backed popovers stay lazy
+  by default (0 requests until opened) — that per-row affordability is a
+  feature; don't blanket-add `prefill: true`.
+- `prefill: false` is **search-first**: with a provider, opening the panel no
+  longer performs the initial fetch — nothing loads until the user types, and
+  the list shows a "search to begin" hint. **⚠ silent** — v2's `false` still
+  fetched on first open; if that's what you wanted, drop the prop (it's the
+  default). Falls back to load-on-open when writing is disabled, `items` is an
+  array, or the model is non-empty.
+
+## Edits
+
+```diff
+- <BbSelectPopover
+-   v-model="row.status"
+-   :items="statuses"
+-   :flip="false"
+-   :hide-arrow="false"
+-   :allow-writing="false"
+- />
++ <BbSelectPopover
++   v-model="row.status"
++   :items="statuses"
++   disable-flip
++   disable-writing
++ />
+```

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

@@ -0,0 +1,69 @@
+---
+title: 'Migration v2→v3: BbSelect'
+summary: allowWriting inverted to disableWriting, filterBy narrowed to string[], prefill value renamed, chevron/options slots removed, and two behavior changes (second click, mount-time coherence).
+---
+
+# BbSelect — v2 → v3
+
+## Props
+
+| v2                                                                            | v3                                                                                                                                                            | Kind                                                                                                                                                                                                                                           |
+| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `allowWriting?: boolean \| 'not-mobile'` (default `true`)                     | `disableWriting?: boolean \| 'mobile' \| 'desktop'` (default `false`)                                                                                         | rename, polarity inverted, token set changed (`'not-mobile'` → `disable-writing="mobile"`)                                                                                                                                                     |
+| `showChevron?: boolean` (default `true`)                                      | removed                                                                                                                                                       | the chevron is standard trim now                                                                                                                                                                                                               |
+| `updateOnAnimationFrame?: boolean`                                            | removed                                                                                                                                                       | positioning is handled internally                                                                                                                                                                                                              |
+| `filterBy: string \| string[] \| false \| 'not_stashed' \| fn`                | `filterBy?: string[]` (default `[]`)                                                                                                                          | retype — **function/`false`/`'not_stashed'` forms removed.** For custom logic, filter the `items` you pass (or do it in the provider) instead of filtering inside the select.                                                                  |
+| `prefill?: boolean \| 'focus'` (default `'focus'`)                            | `prefill?: boolean \| 'interaction'` (default `'interaction'`)                                                                                                | value renamed; `'focus'` no longer compiles. Unset now genuinely inherits the default (v2's wrapper silently coerced an unset prop to `false`).                                                                                                |
+| `prefill: false` (fetched on first open)                                      | `prefill: false` is **search-first**: with a provider, nothing fetches until the user types — opening shows a "search to begin" hint (`select.searchToStart`) | **⚠ silent** — a v2 `prefill: false` select opens to the hint instead of options. If you meant "load on open", delete the prop: that is the default. Falls back to load-on-open for array `items`, `disable-writing`, or a non-empty model.    |
+| `transitionDuration` default `300`                                            | default `250`                                                                                                                                                 | visual — the panel now animates on the shared `transitions.medium` scale, like `BbDialog`                                                                                                                                                      |
+| `itemText` / `itemValue`                                                      | `ItemAccessor<T, …>`                                                                                                                                          | retype — keys autocomplete, functions unchanged                                                                                                                                                                                                |
+| per-item `disabled` honored (deprecated)                                      | inert — use `selectable?: boolean \| ((item) => boolean)`                                                                                                     | **⚠ silent** — see below                                                                                                                                                                                                                       |
+| —                                                                             | `adaptive` + `offCanvasProps` (mobile sheet, on by default), `labelMode`, `description`                                                                       | additive                                                                                                                                                                                                                                       |
+| `name` + empty selection posts `name=null` (single) / omits the field (multi) | empty selection (`null`/`[]`) posts **no field**, like a native `<select multiple>` with nothing chosen                                                       | **⚠ behavioral** (bugfix 2026-07-18) — backends reading the literal `"null"` string must treat the absent field as empty. Note: `required` never participated in native validation here (hidden inputs are barred from constraint validation). |
+
+## Slots
+
+| v2                                                                                       | v3                                                      |
+| ---------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `#chevron`                                                                               | removed                                                 |
+| `#options:prepend`, `#options:append`, `#options:prepend:outer`, `#options:append:outer` | removed — use the new `#header` / `#footer` panel slots |
+| `#prepend` / `#append` (± `-outer`)                                                      | unchanged; scope gains `close`                          |
+
+## Behavior
+
+1. **Second click no longer clears.** Clicking the already-selected option in
+   single mode re-picks and closes; v2 emitted `null` and emptied the field.
+   If click-to-clear was your only clear affordance, add `clearable`.
+2. **`enforce-coherence` prunes on mount.** A seeded value the first load
+   can't resolve is cleared immediately (v2 let it linger until the next
+   change). If values "clear on load" after upgrading, your provider isn't
+   resolving the current selection on `prefill === true` calls — honor that
+   contract or enable `stash`.
+3. **Array `items` resolve on mount** regardless of `prefill` — the field's
+   text renders correctly from first paint.
+4. **Disabled options:** a `disabled` field on an item object no longer does
+   anything (v2 honored it with a deprecation warning). Pass a predicate:
+
+```diff
+- <BbSelect :items="users.map(u => ({ ...u, disabled: !u.active }))" … />
++ <BbSelect :items="users" :selectable="(u) => u.active" … />
+```
+
+## Edits
+
+```diff
+- <BbSelect
+-   v-model="assignee"
+-   :items="searchUsers"
+-   :allow-writing="false"
+-   :show-chevron="false"
+-   :filter-by="(v, item, q) => item.name.includes(q)"
+-   prefill="focus"
+- />
++ <BbSelect
++   v-model="assignee"
++   :items="searchUsers"
++   disable-writing
++   :filter-by="['name']"
++ />
+```

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

@@ -0,0 +1,25 @@
+---
+title: 'Migration v2→v3: BbSlider'
+summary: thumbTranslate inverted to disableThumbTranslate; string model values and color removed.
+---
+
+# BbSlider — v2 → v3
+
+## Changes
+
+| v2                                                 | v3                                                                                                                                                                                                | Kind                                                         |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `thumbTranslate?: boolean` (default `true`)        | `disableThumbTranslate?: boolean` (default `false`)                                                                                                                                               | rename, polarity inverted — same effective default           |
+| `modelValue: number \| number[] \| string \| null` | `number \| number[] \| null`                                                                                                                                                                      | retype — string models fail to compile; parse before binding |
+| `color?: string`                                   | removed                                                                                                                                                                                           | style via tokens/CSS                                         |
+| —                                                  | `labelMode: 'outside' \| 'inside'` (floating unsupported — an explicit `'floating'` warns and falls back to `'outside'`), `maxPrecision` (forwarded to the companion number input), `description` | additive                                                     |
+
+## Edits
+
+```diff
+- <BbSlider v-model="volume" :thumb-translate="false" color="#f59e0b" />
++ <BbSlider v-model="volume" disable-thumb-translate />
+```
+
+If your global config sets `defaultInputLabelMode: 'floating'`, sliders
+silently degrade to `'outside'` — expected, not a bug.

package/dist/ai/guides/migration/components/bb-smooth-height.md

@@ -0,0 +1,45 @@
+---
+title: 'Migration v2→v3: BbSmoothHeight'
+summary: The `tag` prop is narrowed to `div | span`, and the inner measuring element now mirrors it instead of always being a `<div>`.
+---
+
+# BbSmoothHeight — v2 → v3
+
+## Changes
+
+| v2                                            | v3                | Kind                                                              |
+| --------------------------------------------- | ----------------- | ----------------------------------------------------------------- |
+| `tag: string` (any non-void element)          | `'div' \| 'span'` | narrowed — invalid tags are now compile errors                    |
+| inner `.bb-smooth-height__content` always div | mirrors `tag`     | DOM — `tag="span"` now yields span-in-span instead of span-in-div |
+
+## Why the tag list shrank
+
+The wrapper animates `height`, and the element inside it exists purely to
+measure content. Those two boxes are always the same element type now, so any
+tag with a restricted content model would nest invalidly inside itself — `ul >
+ul`, `p > p`. Restricting the prop to `div | span` makes every combination
+valid by construction.
+
+Both elements are forced to `display: block` in CSS, so a `span` measures and
+animates exactly like a `div`; the choice is purely about the markup the
+surrounding context accepts.
+
+```diff
+- <BbSmoothHeight tag="section">
++ <section>
++   <BbSmoothHeight>
+      …
++   </BbSmoothHeight>
++ </section>
+- </BbSmoothHeight>
+```
+
+If you passed `ul`, note the v2 output was already invalid (`ul > div > li`),
+because the inner measuring element was a hardcoded `<div>`. Wrap the component
+in your own element instead of asking for it via `tag`.
+
+## CSS
+
+`.bb-smooth-height` and `.bb-smooth-height__content` are unchanged. Only
+element-qualified selectors break — `div.bb-smooth-height__content` no longer
+matches when `tag="span"`.

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

@@ -0,0 +1,23 @@
+---
+title: 'Migration v2→v3: BbSpinner'
+summary: The color prop is removed; spinners follow currentColor.
+---
+
+# BbSpinner — v2 → v3
+
+## Changes
+
+| v2               | v3                                                      | Kind                                          |
+| ---------------- | ------------------------------------------------------- | --------------------------------------------- |
+| `color?: string` | removed                                                 | inherits `currentColor` — style the parent    |
+| —                | `label?: string` (sr-only `role="status"` announcement) | additive, recommended for standalone spinners |
+
+## Edits
+
+```diff
+- <BbSpinner color="#2563eb" size="lg" />
++ <BbSpinner size="lg" class="text-blue-600" label="Loading results" />
+```
+
+Note for tests/CSS: idle `BbButton`s no longer contain a mounted spinner node
+— `.bb-spinner` only matches while a button is actually loading.

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

@@ -0,0 +1,66 @@
+---
+title: 'Migration v2→v3: BbTable'
+summary: 'allowSelectAll inverted to disableSelectAll; loading no longer blanks populated tables and now inerts rows; #loading is first-load-only; #no-data fills a full-width table cell instead of replacing the row.'
+---
+
+# BbTable — v2 → v3
+
+## Changes
+
+| v2                                          | v3                                                                                                                                                                                                  | Kind                                                                    |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `allowSelectAll?: boolean` (default `true`) | `disableSelectAll?: boolean` (default `false`)                                                                                                                                                      | rename, polarity inverted                                               |
+| refetch with rows → skeleton                | refetch keeps rows visible (dimmed + progress bar)                                                                                                                                                  | **behavior** — the skeleton only shows when there is nothing to display |
+| rows interactive while loading              | header + rows go `inert` while loading                                                                                                                                                              | **behavior** — opt out with `interactive-while-loading`                 |
+| `#loading` slot fired on every load         | fires on the **first load only** (it replaces the skeleton, so it follows the skeleton's rule)                                                                                                      | **⚠ silent** for anyone styling refetches through it                    |
+| `#no-data` replaced the empty-state `<tr>`  | fills the table's own full-width `<td>` (colspan counted, centred)                                                                                                                                  | **behavior** — pass content, not a row                                  |
+| —                                           | `enforceCoherence` (prunes row-keyed models after each load; incompatible with pagination-via-`dependencies`), `expandedItems` + `#expand`, `sort`, `keyboardNavigation`, `highlighted`, `rowClass` | additive                                                                |
+
+## Edits
+
+```diff
+- <BbTable :items="provider" :columns="columns" multiple :allow-select-all="false" />
++ <BbTable :items="provider" :columns="columns" multiple disable-select-all />
+
+  <!-- passing allowSelectAll's default -->
+- <BbTable … allow-select-all />
++ <BbTable … />
+```
+
+If a flow _depends_ on interacting with rows mid-refetch (rare, e.g. rapid
+inline edits over a polling table):
+
+```diff
+- <BbTable :items="provider" :dependencies="[filters]" />
++ <BbTable :items="provider" :dependencies="[filters]" interactive-while-loading />
+```
+
+If you used `#loading` to show a custom refetch treatment, that role is gone —
+the built-in dim + progress bar covers refetches; `#loading` is now only the
+first-paint placeholder.
+
+### `#no-data` is content, not a row
+
+v2 handed the slot the whole empty-state `<tr>`, so anything that was not a
+row — the usual `<div>` with a message and a "clear filters" button — landed
+loose inside `<tbody>` and rendered left-aligned at content width instead of
+spanning the table. v3 keeps the `<tr>`/`<td>` shell (with the colspan already
+counting the selection and actions columns) and puts the slot inside it, so
+that same markup now centres across the full width.
+
+```diff
+  <BbTable :items="rows" :columns="columns" selectable actions>
+    <template #no-data>
+-     <tr>
+-       <td :colspan="columns.length + 2">
+-         <p>No invoices match the current filters.</p>
+-       </td>
+-     </tr>
++     <p>No invoices match the current filters.</p>
+    </template>
+  </BbTable>
+```
+
+Only tables that hand-rolled the row shell need editing — content-only slots
+(the overwhelmingly common case) are correct as they stand, and simply start
+rendering where they always should have.

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

@@ -0,0 +1,47 @@
+---
+title: 'Migration v2→v3: BbTabs (was BbTab)'
+summary: Component renamed; querykey→queryKey; animations default on; label slots renamed and all dynamic names/URL slugs normalized.
+---
+
+# BbTabs — v2 → v3
+
+The component `BbTab` is renamed **`BbTabs`** (types too; `BbTabProps`-style
+aliases survive as deprecated re-exports, the tag name does not).
+
+## Changes
+
+| v2                                       | v3                                                      | Kind                                                                                    |
+| ---------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `<BbTab>`                                | `<BbTabs>`                                              | rename                                                                                  |
+| `querykey?: string`                      | `queryKey?: string` (default `'tab'`)                   | **⚠ silent** — a leftover `querykey` is ignored and URL sync moves to `?tab=`           |
+| `animateX` / `animateY` (default `true`) | `disableAnimateX` / `disableAnimateY` (default `false`) | polarity rename — bare `animate-x` → delete; `:animate-x="false"` → `disable-animate-x` |
+| label slot `#label-<key>`                | `#label:<slotKey(key)>`                                 | rename + normalization                                                                  |
+| pane slot `#<key>` (raw)                 | `#<slotKey(key)>`                                       | normalization                                                                           |
+| URL value = raw key                      | URL value = normalized slug                             | **⚠ breaking for deep links**                                                           |
+| tab/panel DOM ids from raw key           | normalized (also fixes invalid ids for spaced keys)     | check E2E selectors                                                                     |
+
+`slotKey(key)` lowercases and replaces every non-word run with `_`:
+`"In Review"` → `in_review`, `"2024-03-15"` → `2024_03_15`. Keys that are
+already lowercase slugs are untouched — then only the `label-` → `label:`
+rename applies.
+
+**What stays raw:** `v-model` and the item `key`. `v-model="'In Review'"`
+still selects that tab; only slots, ids, and the URL use the slug.
+
+## Edits
+
+```diff
+- <BbTab :items="items" navigation querykey="section" :animate-x="false">
++ <BbTabs :items="items" navigation query-key="section" disable-animate-x>
+-   <template #label-in-review="{ item }">…</template>
++   <template #label:in_review="{ item }">…</template>
+-   <template #In Review>…</template>            <!-- was never valid HTML anyway -->
++   <template #in_review>…</template>
+- </BbTab>
++ </BbTabs>
+```
+
+**Server side:** if backend code reads the tab query param, it now receives
+the normalized slug (`?section=in_review`, not `?section=In%20Review`).
+Existing bookmarks with raw values fall back to the default tab — add a
+redirect if those links matter.

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

@@ -0,0 +1,29 @@
+---
+title: 'Migration v2→v3: BbTag'
+summary: modelValue is strictly string[] now, multiple is removed, and duplicates are rejected case-insensitively by default.
+---
+
+# BbTag — v2 → v3
+
+## Changes
+
+| v2                                    | v3                                               | Kind                                                                                                                              |
+| ------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| `modelValue: any`                     | `modelValue: string[]`                           | retype — non-array/typed-object models fail to compile; map to strings at the boundary                                            |
+| `multiple?: boolean` (default `true`) | removed                                          | always a multi-value array input                                                                                                  |
+| `divider?: KeyboardEvent['key']`      | `KeyboardEvent['key'] \| KeyboardEvent['key'][]` | widened — e.g. `:divider="['Enter', ',']"`                                                                                        |
+| duplicate handling: exact match       | trimmed + **case-insensitive** dedup by default  | **behavior** — `'Vue'` then `'vue'` now triggers `duplicate` instead of adding both; pass `case-sensitive` to restore v2 matching |
+| —                                     | `max` event, `caseSensitive`, extra input events | additive                                                                                                                          |
+
+## Edits
+
+```diff
+- <BbTag v-model="tags" :multiple="true" divider="," />
++ <BbTag v-model="tags" :divider="[',']" />
+
+  <!-- v2 exact-match dedup preserved -->
++ <BbTag v-model="tags" case-sensitive />
+```
+
+If your model held objects (`{ id, label }[]`), keep the objects in your own
+state and bind a mapped `string[]`, syncing on `update:modelValue`.

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

@@ -0,0 +1,37 @@
+---
+title: 'Migration v2→v3: BbTextInput'
+summary: The type prop narrows to the text-like input types — number/date values must move to their dedicated components.
+---
+
+# BbTextInput — v2 → v3
+
+## 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                                                                                                                                                                                                  |
+
+## Edits
+
+```diff
+- <BbTextInput v-model="qty" type="number" label="Quantity" />
++ <BbNumberInput v-model="qty" label="Quantity" />
+
+- <BbTextInput v-model="when" type="date" label="Due" />
++ <BbDatePickerInput v-model="when" label="Due" />
+```
+
+Values that were never text-like (`checkbox`, `file`, `range`, …) were always
+the wrong component; the type now says so.
+
+The sibling **`BbNumberInput`** likewise dropped its `increase()` / `decrease()`
+template-ref API: build an in-affix stepper from the `prepend`/`append`/`prefix`/
+`suffix` slot scope (`{ increase, decrease }`), and for an external stepper drive
+`v-model` directly (`model += step`).
+
+Also relevant here: the shared input wrapper's CSS block was renamed — any CSS
+or test selectors on `.bb-common-input-inner-container*` must move to
+`.common-input-wrapper--*` (see [main guide §5](../v2-to-v3.md)).

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

@@ -0,0 +1,47 @@
+---
+title: 'Migration v2→v3: BbToast and toast()'
+summary: Host placement becomes position with a corner-based value set; toast() options rewritten (variant, duration, actions, portal).
+---
+
+# BbToast / `toast()` — v2 → v3
+
+## The host component
+
+| v2                                                         | v3                                                                                                         | Kind                          |
+| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| `placement?: 'bottom' \| 'bottom-start' \| … \| 'top-end'` | `position?: BbToastPosition` — `top-left, top-center, top-right, bottom-left, bottom-center, bottom-right` | rename + new value vocabulary |
+
+Value mapping: `bottom` → `bottom-center`, `bottom-start` → `bottom-left`,
+`bottom-end` → `bottom-right` (same for `top-*`). Unset now falls back to the
+plugin's `toastPosition` config (default `bottom-right`).
+
+```diff
+- <BbToast placement="top-end" />
++ <BbToast position="top-right" />
+```
+
+## `toast()` options
+
+| v2                      | v3                                                                                                                                                        | Kind         |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
+| `theme?: string`        | `variant?: ToastVariantType` (built-ins `default, success, info, warning, destructive`)                                                                   | typed rename |
+| `persistent`            | unchanged                                                                                                                                                 |              |
+| `title`, `text`, `icon` | unchanged                                                                                                                                                 |              |
+| —                       | `duration`, `hideClose`, `position`, `loading`, `id` + `updateToast()`, `dismissToast(reason)`, `portal` / `portalProps`, `actions: ActionButtonConfig[]` | additive     |
+
+`toast('plain string')` still works. The `BbToastMessage` type export is gone
+— type options as `BbToastOptions`.
+
+```diff
+- toast({ title: 'Deleted', theme: 'success' });
++ toast({ title: 'Deleted', variant: 'success' });
+
+  // the hand-rolled undo pattern collapses to:
++ toast({ title: 'Deleted', actions: [{ text: 'Undo', onClick: restore }] });
+```
+
+Notes on `actions` (additive but with rules): handlers run with a spinner and
+sibling-disable, and hold the dismiss timer; portal toasts ignore `actions`.
+Styling hooks moved from `theme` classes to `bb-toast-message--<variant>` —
+custom looks register through the plugin's `toastVariants` option
+([main guide §4](../v2-to-v3.md)).

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

@@ -0,0 +1,34 @@
+---
+title: 'Migration v2→v3: BbTooltip'
+summary: timeout renamed to delay; theme replaced by typed variant; hideArrow is now a declared prop.
+---
+
+# BbTooltip / `v-bb-tooltip` — v2 → v3
+
+## Changes
+
+| v2                                   | v3                                                                         | Kind                                                        |
+| ------------------------------------ | -------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `timeout?: number`                   | `delay?: number` (default `0`)                                             | rename (`BbAvatar.timeout` is unrelated and keeps its name) |
+| `theme?: string` (deprecated)        | `variant?: TooltipVariantType` (`default, destructive`; default `default`) | typed rename                                                |
+| arrow via undeclared fall-through    | `hideArrow?: boolean` (default `false` — arrow shown)                      | now a real, typed prop                                      |
+| `activator` / `boundary` loose types | `ElementOrComponentRef*`                                                   | transparent in templates                                    |
+
+The tooltip is the **only** surface that kept its arrow — popovers, selects,
+dropdowns and the color palette dropped theirs (see
+[bb-popover.md](./bb-popover.md)).
+
+## Edits
+
+```diff
+- <BbTooltip :activator="el" :timeout="300" theme="destructive">Careful</BbTooltip>
++ <BbTooltip :activator="el" :delay="300" variant="destructive">Careful</BbTooltip>
+
+  <!-- directive form: object options follow the same prop names -->
+- <span v-bb-tooltip="{ text: 'Careful', timeout: 300 }">…</span>
++ <span v-bb-tooltip="{ text: 'Careful', delay: 300 }">…</span>
+```
+
+The directive itself is unchanged (`v-bb-tooltip:placement`), but in v3 it is
+registered by the runtime plugin — drop any manual
+`app.use(BbTooltipDirectivePlugin)` ([main guide §1](../v2-to-v3.md)).