bitboss-ui 2.1.135 → 3.0.0-alpha.1

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

@@ -0,0 +1,36 @@
+---
+title: 'Migration v2→v3: BbDropdown'
+summary: Items now expect text as the label and can carry variants/submenus; arrowPadding removed; adaptive mobile sheet on by default.
+---
+
+# BbDropdown / `v-bb-dropdown` — v2 → v3
+
+## Changes
+
+| v2                                   | v3                                                                                                                                                                                                                        | Kind                                                                                                                                                                |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| items extended `BaseButtonProps`     | items extend `BbBaseButtonProps`                                                                                                                                                                                          | transparent unless you typed items with the old export                                                                                                              |
+| item label conventions               | `text` is the expected label field; `description` renders a second line                                                                                                                                                   | check items built as plain link objects                                                                                                                             |
+| `arrowPadding`                       | removed                                                                                                                                                                                                                   | dead prop (dropdowns never show an arrow)                                                                                                                           |
+| exposed `loading` (via template ref) | removed                                                                                                                                                                                                                   | read in-flight async state from the activator slot scope (`loading`) instead of a component ref. **⚠ silent**: a stale `dropdownRef.value?.loading` is `undefined`. |
+| —                                    | item `variant?: DropdownItemVariantType` (`default, destructive`), recursive `items` submenus, config-driven **groups** (titled/selectable/async sections via `BbDropdownGroup`), `adaptive` + `offCanvasProps`, `anchor` | additive                                                                                                                                                            |
+| floating wrapper/bubble as `<span>`  | rendered as `<div>`                                                                                                                                                                                                       | DOM only — the menu is block content. Class hooks unchanged; only element selectors like `span.bb-common-popover` break.                                            |
+
+## Edits
+
+```diff
+  <BbDropdown :items="[
+-   { text: 'Rename', onClick: rename },
+-   { text: 'Delete', onClick: destroy, class: 'text-red-600' },
++   { text: 'Rename', onClick: rename },
++   { text: 'Delete', onClick: destroy, variant: 'destructive' },
+  ]">
+```
+
+The hand-colored destructive item is the dropdown flavor of the
+class-override pattern — `variant: 'destructive'` is the typed form, and
+custom names register via the plugin's `dropdownItemVariants` option
+([main guide §7](../v2-to-v3.md)).
+
+`adaptive` is on by default: on mobile the menu opens as a bottom sheet. Pass
+`:adaptive="false"` to keep the floating menu everywhere.

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

@@ -0,0 +1,27 @@
+---
+title: 'Migration v2→v3: BbDropzone'
+summary: modelValue is typed, accept no longer throws and takes bare tokens, and the hidden native-submit input only renders when name is set.
+---
+
+# BbDropzone — v2 → v3
+
+## Changes
+
+| v2                                                                  | v3                                                                                                                                                                             | Kind                                                                                                                                                                                                                                              |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `modelValue: any`                                                   | `File \| File[] \| null`                                                                                                                                                       | retype                                                                                                                                                                                                                                            |
+| `accept: string[]` — non-array **threw**; extensions mapped eagerly | MIME (`'image/png'`), wildcards (`'image/*'`), extensions (`'.png'`) **and bare tokens** (`'png'`); never throws — unknown tokens dev-warn and fall back to extension matching | behavior (more permissive; validation is queued until rules resolve, so early drops are still validated correctly)                                                                                                                                |
+| hidden submittable `<input type="file">` always rendered            | rendered **only when `name` is set**; mirrors the model (including pre-seeded values)                                                                                          | **⚠ silent** — a native `<form>` post that relied on the hidden input without a `name`… actually posted nothing useful in v2 either, but if you passed `name`, behavior improves; if you _removed_ `name` thinking it inert, the input disappears |
+| `error` event / `errors` round-trip (`DropZoneError` union)         | unchanged                                                                                                                                                                      | —                                                                                                                                                                                                                                                 |
+| —                                                                   | default-slot `open()` callback (opens the native picker)                                                                                                                       | additive                                                                                                                                                                                                                                          |
+| `tag: string` (any non-void element)                                | `'div' \| 'span'`                                                                                                                                                              | narrowed — wrap the dropzone in your own element for anything else                                                                                                                                                                                |
+
+## Edits
+
+```diff
+- <BbDropzone v-model="file" :accept="['application/pdf']" name="attachment" />
++ <BbDropzone v-model="file" :accept="['pdf']" name="attachment" />
+```
+
+Keep `name` wherever a surrounding `<form>` submits natively — without it v3
+renders no hidden input at all.

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

@@ -0,0 +1,27 @@
+---
+title: 'Migration v2→v3: BbIcon'
+summary: The required prop is renamed type→icon, color is removed, and the xxl size key becomes 2xl.
+---
+
+# BbIcon — v2 → v3
+
+## Changes
+
+| v2                                                   | v3                                                                     | Kind                                                              |
+| ---------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `type: IconType` (required)                          | `icon: IconType`                                                       | rename                                                            |
+| `color?: string`                                     | removed                                                                | icons render `currentColor` — set `color` on a wrapper, or in CSS |
+| size key `xxl`                                       | `2xl`                                                                  | retype (shared `Sizes` scale)                                     |
+| type export `Size`                                   | `BbIconSize`                                                           | rename                                                            |
+| `IconType` restricted by `IconRegistry` augmentation | plain `string` (`provider:name` or `local:name`, raw `<svg>` accepted) | see icon setup in the [main guide §1](../v2-to-v3.md)             |
+
+## Edits
+
+```diff
+- <BbIcon type="mdi:home" color="#6b7280" size="xxl" />
++ <BbIcon icon="mdi:home" size="2xl" class="text-gray-500" />
+```
+
+Provider prefixes now require the matching `@iconify-json/<prefix>` dev
+dependency, and names must be **literal strings** (the build scans statically;
+dynamically assembled names won't be bundled).

package/dist/ai/guides/migration/components/bb-off-canvas.md

@@ -0,0 +1,25 @@
+---
+title: 'Migration v2→v3: BbOffCanvas'
+summary: showClose inverted to hideClose; size becomes responsive with new (smaller) default widths.
+---
+
+# BbOffCanvas — v2 → v3
+
+## Changes
+
+| v2                                     | v3                                                                                                         | Kind                                                                                                                                                                                                     |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `showClose?: boolean` (default `true`) | `hideClose?: boolean` (default `false`)                                                                    | rename, polarity inverted                                                                                                                                                                                |
+| `size?: 'sm' \| 'md' \| 'lg'`          | `size?: Responsive<'xs'…'2xl' \| 'auto' \| CSS length>`                                                    | widened — **defaults changed**, same trap as BbDialog: v2 `{ sm: 384, md: 652, lg: 896 }` → v3 `{ xs: 320, sm: 384, md: 448, lg: 512, xl: 576, '2xl': 672 }`. Pin via `offCanvasDefaultSizes` if needed. |
+| —                                      | `draggable`, `stack` / `stackGap`, `persistent`, `disabled`, `fullscreen`, `eager`, `focusTarget`, `title` | additive                                                                                                                                                                                                 |
+
+## Edits
+
+```diff
+- <BbOffCanvas v-model="open" :show-close="false" size="md">
++ <BbOffCanvas v-model="open" hide-close size="md">
+```
+
+If the panel was sized to fit content designed for 652px, either pass
+`offCanvasDefaultSizes: { md: 652 }` to the plugin or move to `size="xl"`
+(576px) / an explicit CSS length.

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

@@ -0,0 +1,54 @@
+---
+title: 'Migration v2→v3: BbOffCanvas'
+summary: direction renamed to side (same left/top/right/bottom values); adaptive drawer configs (offCanvasProps) rename direction→side too.
+---
+
+# BbOffCanvas — v2 → v3
+
+The prop that chooses which viewport edge the panel docks to is renamed
+`direction` → **`side`**. Same value set, same default — a pure rename that
+aligns the kit's positioning vocabulary (`side` for edge-docked surfaces,
+`position` for BbToast's viewport corners, `placement` for anchor-relative
+popovers).
+
+## Changes
+
+| v2                                                                      | v3                                                                 | Kind                                                                                  |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| `direction?: 'left' \| 'top' \| 'right' \| 'bottom'` (default `'left'`) | `side?: 'left' \| 'top' \| 'right' \| 'bottom'` (default `'left'`) | **⚠ silent** — a leftover `direction` is ignored and the panel falls back to `'left'` |
+
+**Adaptive surfaces** — components that render a BbOffCanvas drawer on mobile
+(`BbDialog`, `BbPopover`, `BbDropdown`, `BbSelectPopover`) configure it through
+`offCanvasProps` (`Partial<BbOffCanvasProps>`). The nested
+`direction` there renames to `side` for the same reason:
+
+```diff
+- <BbOffCanvas v-model="open" direction="right" title="Filters" />
++ <BbOffCanvas v-model="open" side="right" title="Filters" />
+
+- <BbDialog :off-canvas-props="{ direction: 'bottom' }" />
++ <BbDialog :off-canvas-props="{ side: 'bottom' }" />
+```
+
+The failure mode is silent (Vue does not warn on unknown props; a leftover
+`direction` falls through `$attrs`). `vue-tsc` catches it in typed templates;
+`bitboss-ui/eslint-plugin` catches it everywhere and **`eslint --fix`
+auto-renames it**. Grep: `rg -i 'direction' --type vue` in offcanvas markup.
+
+## Adaptive-drawer config prop unified → `offCanvasProps`
+
+The prop that configures the mobile drawer on adaptive components was spelled
+two ways — `canvasProps` (BbDialog) and `offcanvasProps` (BbSelect,
+BbSelectPopover, BbDropdown, BbPopover, BbDatePickerInput). Both are unified to
+**`offCanvasProps`** (camelCase reflecting the `BbOffCanvas` component name).
+Pure rename — the `Partial<BbOffCanvasProps>` object is unchanged.
+
+```diff
+- <BbDialog :canvas-props="{ side: 'bottom' }" />
++ <BbDialog :off-canvas-props="{ side: 'bottom' }" />
+
+- <BbSelect :offcanvas-props="{ size: 'lg' }" />
++ <BbSelect :off-canvas-props="{ size: 'lg' }" />
+```
+
+Also silent on upgrade; `eslint --fix` auto-renames it.

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,58 @@
+---
+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 |
+| `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,68 @@
+---
+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.    |
+| `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.