bitboss-ui 2.1.135 → 3.0.0-alpha.1

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

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

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

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

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

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

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

@@ -0,0 +1,55 @@
+---
+title: 'Migration v2→v3: BbButton'
+summary: Async click handlers now auto-track loading (behavior flip), built-in tooltip props removed, variant locked to the registry.
+---
+
+# BbButton — v2 → v3
+
+## Changes
+
+| v2                                              | v3                                                | Kind                                                               |
+| ----------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------ |
+| `autoLoading?: boolean` (default `false`)       | `disableAutoLoading?: boolean` (default `false`)  | **⚠ silent behavior flip** — auto loading is now **on** by default |
+| `tooltip`, `tooltipPlacement`, `tooltipTimeout` | removed                                           | built-in tooltip dropped                                           |
+| `theme?: string`                                | removed                                           | use `variant` (typed) or a class                                   |
+| `variant?: string`-ish                          | `variant?: ButtonVariantType` (default `primary`) | unregistered names are now compile errors; `none` opts out         |
+| `size`                                          | `Responsive<Sizes>`, gains `'2xl'`                | additive; per-breakpoint maps use `{ default: 'md', lg: 'xl' }`    |
+| `tag: string`                                   | `'button' \| 'div' \| 'span' \| 'label'`          | narrowed to the tags the button actually supports                  |
+
+## The loading flip
+
+In v2 a button with an `async` `@click` handler did nothing special unless you
+passed `auto-loading`. In v3 every async handler shows the spinner and
+disables the button until the promise settles.
+
+- If you passed `auto-loading` in v2: **delete the prop** — it's the default.
+- If you relied on the button staying enabled during an async handler
+  (double-submit flows, fire-and-forget clicks): pass `disable-auto-loading`,
+  or `interactive-while-loading` if you want the spinner but not the disable.
+- If you hand-rolled loading (`:loading="saving"` + a `saving` ref around an
+  await): you can usually delete the ref — the button does it now.
+
+```diff
+- <BbButton auto-loading @click="save">Save</BbButton>
++ <BbButton @click="save">Save</BbButton>
+
+  <!-- v2 behavior preserved explicitly -->
+- <BbButton @click="fireAndForget">Ping</BbButton>
++ <BbButton disable-auto-loading @click="fireAndForget">Ping</BbButton>
+```
+
+## Tooltip props
+
+```diff
+- <BbButton tooltip="Delete forever" tooltip-placement="top" variant="destructive" />
++ <BbButton v-bb-tooltip:top="'Delete forever'" variant="destructive" />
+```
+
+The `v-bb-tooltip` directive is registered by the runtime plugin (see the
+[main guide](../v2-to-v3.md) §1). For rich content, wrap in `BbTooltip`.
+
+## Class overrides
+
+`<BbButton class="bb-button--outline">` → `<BbButton variant="outline">`.
+See [main guide §7](../v2-to-v3.md) for the full pattern and how to register
+custom variant names.

package/dist/ai/guides/migration/components/bb-checkbox-group.md

@@ -0,0 +1,54 @@
+---
+title: 'Migration v2→v3: BbCheckboxGroup / BbRadioGroup / BbSwitchGroup'
+summary: labelPosition renamed legendPosition, per-item disabled is now inert (use selectable), color and the option affix slots removed.
+---
+
+# BbCheckboxGroup / BbRadioGroup / BbSwitchGroup — v2 → v3
+
+The three groups share their surface (`BbSwitchGroup` re-exports
+`BbCheckboxGroupProps`); everything below applies to all three unless noted.
+
+## Changes
+
+| v2                                                                     | v3                                                 | Kind                                                                                     |
+| ---------------------------------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `labelPosition?: 'left' \| 'center' \| 'right'`                        | `legendPosition`                                   | rename                                                                                   |
+| per-item `disabled` honored (with a deprecation warning)               | **inert** — plain data, no warning                 | **⚠ silent** — use `selectable?: boolean \| ((item) => boolean)`                         |
+| `color?: string`                                                       | removed                                            | style via tokens/CSS                                                                     |
+| `#option:prepend` / `#option:append` slots                             | removed                                            | use the `#label` slot (scoped `{ item, text, checked }`) to decorate options             |
+| `items` provider unions, `itemText` / `itemValue`                      | unified provider signature + `ItemAccessor`        | retype — plain arrays and `(prefill) => Promise<T[]>` providers unchanged                |
+| —                                                                      | `legendMode: 'outside' \| 'inside'`, `description` | additive                                                                                 |
+| `BbSwitchGroup` `multiple: false` silently ignored (always array emit) | honored — emits a bare value in single-select mode | **⚠ behavioral** (bugfix: the prop was advertised but never forwarded; fixed 2026-07-18) |
+
+`max` (checkbox/switch), `required` + mandatory `name` (radio), and
+`multiple` defaults are unchanged.
+
+## Edits
+
+```diff
+- <BbCheckboxGroup
+-   v-model="plans"
+-   :items="tiers.map(t => ({ ...t, disabled: t.soldOut }))"
+-   label-position="left"
+-   color="#0ea5e9"
+- >
+-   <template #option:append="{ item }">
+-     <BbBadge v-if="item.popular">Popular</BbBadge>
+-   </template>
+- </BbCheckboxGroup>
++ <BbCheckboxGroup
++   v-model="plans"
++   :items="tiers"
++   :selectable="(t) => !t.soldOut"
++   legend-position="left"
++ >
++   <template #label="{ item, text }">
++     {{ text }}
++     <BbBadge v-if="item.popular" variant="secondary">Popular</BbBadge>
++   </template>
++ </BbCheckboxGroup>
+```
+
+The `item.disabled` change is the dangerous one: nothing errors, options that
+used to render disabled simply become selectable. Grep item-building code for
+`disabled:` near these groups.

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

@@ -0,0 +1,45 @@
+---
+title: 'Migration v2→v3: BbCheckbox / BbRadio / BbSwitch'
+summary: reverse polarity inverted (explicit values flip, default layout unchanged), checked narrowed to boolean, color removed.
+---
+
+# BbCheckbox / BbRadio / BbSwitch — v2 → v3
+
+The three single controls share their prop surface (`BbSwitch` re-exports
+`BbCheckboxProps`); every change below applies to all three.
+
+## Changes
+
+| v2                                       | v3                                                          | Kind                                                                                                                           |
+| ---------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `reverse?: boolean` (default `true`)     | `reverse?: boolean` (default `false`, **meaning inverted**) | **⚠ silent** — see below                                                                                                       |
+| `checked?: boolean \| 'true' \| 'false'` | `checked?: boolean`                                         | retype — string forms fail to compile (`checked="false"` was truthy anyway; this failure is loud where the old one was silent) |
+| `color?: string`                         | removed                                                     | style via theme tokens / CSS                                                                                                   |
+| `indeterminate` loose type (checkbox)    | `boolean`                                                   | retype                                                                                                                         |
+| —                                        | `description`, `compact`                                    | additive                                                                                                                       |
+
+## The `reverse` flip, precisely
+
+Both versions render the **same default layout** (control first, then label).
+What inverted is what the prop _means_:
+
+- v2: `reverse` defaulted `true`; passing `:reverse="false"` produced the
+  swapped (label-first) layout.
+- v3: `reverse` defaults `false` = the same standard layout; passing
+  `reverse` now _opts into_ the swapped layout.
+
+So explicit values translate **by inversion**:
+
+| v2 usage                      | v3 equivalent                 |
+| ----------------------------- | ----------------------------- |
+| (unset)                       | (unset) — identical rendering |
+| `reverse` / `:reverse="true"` | delete the prop               |
+| `:reverse="false"`            | `reverse`                     |
+
+```diff
+- <BbCheckbox v-model="ok" :reverse="false" label="I agree" color="#16a34a" />
++ <BbCheckbox v-model="ok" reverse label="I agree" />
+```
+
+`rg -n 'reverse' --type vue` and review each hit on these components — the
+compiler cannot catch a boolean that changed meaning.

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

@@ -0,0 +1,35 @@
+---
+title: 'Migration v2→v3: BbChip (removed)'
+summary: BbChip is gone — BbBadge with clearable is the replacement; non-clearable chips were badges all along.
+---
+
+# BbChip — removed in v3
+
+The component and its exports (`BbChipProps`, …) no longer exist. The
+reasoning: a clearable chip is a dismissible badge, and a non-clearable chip
+_is_ a badge — so the library ships one component.
+
+| v2                                                            | v3                                                           |
+| ------------------------------------------------------------- | ------------------------------------------------------------ |
+| `<BbChip :text="label" />` (default `clearable`)              | `<BbBadge clearable>{{ label }}</BbBadge>`                   |
+| `<BbChip :text="label" :clearable="false" />`                 | `<BbBadge variant="secondary">{{ label }}</BbBadge>`         |
+| `clearableLabel`, `@click:clear`                              | unchanged on `BbBadge`                                       |
+| `.bb-chip`, `.bb-chip__content`, `.bb-chip__clear-button` CSS | `.bb-badge`, default slot content, `.bb-badge__clear-button` |
+
+Two gotchas:
+
+- `clearable` **defaults flipped**: chips were clearable unless told otherwise;
+  badges are not clearable unless told so. A bare swap silently loses the ×.
+- The label moves from the `text` prop to the **default slot** — the v3 badge
+  has no text/content prop, and a prop passed anyway renders an empty pill.
+
+Do not reach for `BbTag` — despite the name it is an unrelated multi-value
+_input_ (`v-model: string[]`), not a display token.
+
+If your chip was **clickable as well as dismissible** (a filter chip: press the
+body to edit, press the × to remove), that is now `BbBadgeButton` slotted into
+the badge — see [bb-badge.md](./bb-badge.md#clickable-chips-bbbadgebutton).
+Don't reproduce the v2 habit of wrapping the whole chip in a `<button>`: with
+`clearable` that nests a button inside a button, which is invalid markup.
+
+Full badge/indicator picture: [bb-badge.md](./bb-badge.md).

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

@@ -0,0 +1,26 @@
+---
+title: 'Migration v2→v3: BbCollapsible'
+summary: The tag prop is removed; the root is always a div.
+---
+
+# BbCollapsible — v2 → v3
+
+## Changes
+
+| v2                                          | v3        | Kind                                                                           |
+| ------------------------------------------- | --------- | ------------------------------------------------------------------------------ |
+| `tag?: string` (default `'div'`)            | removed   | root is a `div`; wrap in a semantic element if you passed `tag="section"` etc. |
+| `modelValue`, `eager`, `transitionDuration` | unchanged | —                                                                              |
+
+## Edits
+
+```diff
+- <BbCollapsible v-model="open" tag="section">…</BbCollapsible>
++ <section>
++   <BbCollapsible v-model="open">…</BbCollapsible>
++ </section>
+```
+
+Reminder (unchanged from v2, but often misread): the component is fully
+controlled — it renders `modelValue` and never toggles itself; the trigger
+stays in your markup.

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

@@ -0,0 +1,23 @@
+---
+title: 'Migration v2→v3: BbColorInput'
+summary: picker renamed to eyeDropper.
+---
+
+# BbColorInput — v2 → v3
+
+## Changes
+
+| v2                                   | v3                                       | Kind                                                        |
+| ------------------------------------ | ---------------------------------------- | ----------------------------------------------------------- |
+| `picker?: boolean` (default `false`) | `eyeDropper?: boolean` (default `false`) | rename (same feature; `BbColorPalette` got the same rename) |
+| `direction`                          | `InputDirection`                         | family-wide retype                                          |
+| —                                    | `labelMode`, `description`               | additive                                                    |
+
+## Edits
+
+```diff
+- <BbColorInput v-model="brand" picker />
++ <BbColorInput v-model="brand" eye-dropper />
+```
+
+`alpha` and `swatches` are unchanged.

package/dist/ai/guides/migration/components/bb-color-palette.md

@@ -0,0 +1,31 @@
+---
+title: 'Migration v2→v3: BbColorPalette'
+summary: flip inverted to disableFlip, showArrow removed, picker renamed eyeDropper, update:open dropped, model updates never emit null.
+---
+
+# BbColorPalette — v2 → v3
+
+## Changes
+
+| v2                                           | v3                                                                 | Kind                                                                                               |
+| -------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| `flip?: boolean` (default `true`)            | `disableFlip?: boolean` (default `false`)                          | rename, polarity inverted                                                                          |
+| `showArrow?: boolean` (default `false`)      | removed                                                            | arrows are tooltip-only in v3; **⚠ silent** — a leftover `show-arrow` lands in `$attrs`            |
+| `arrowPadding`                               | removed                                                            | dead with the arrow                                                                                |
+| `picker?: boolean`                           | `eyeDropper?: boolean`                                             | rename (same eyedropper feature)                                                                   |
+| `update:open` event                          | removed                                                            | track open state via the activator slot's `open` if you need it                                    |
+| `update:modelValue` payload `string \| null` | `string` — the palette always emits a concrete color, never `null` | **behavior** — clearing is the consumer's job now; handlers narrowing on `null` have dead branches |
+| activator slot prop `color`                  | `value`                                                            | rename                                                                                             |
+
+## Edits
+
+```diff
+- <BbColorPalette v-model="color" :flip="false" show-arrow picker @update:open="track">
+-   <template #activator="{ props, color }">
+-     <button v-bind="props" :style="{ background: color }" />
++ <BbColorPalette v-model="color" disable-flip eye-dropper>
++   <template #activator="{ props, value, open }">
++     <button v-bind="props" :style="{ background: value }" />
+    </template>
+  </BbColorPalette>
+```

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

@@ -0,0 +1,84 @@
+---
+title: 'Migration v2→v3: BbDatePickerInput'
+summary: allowWriting inverted to disableWriting and hidePopover renamed to disableCalendar, both with a changed token set; the width prop is removed; adaptive mobile sheet by default; non-floating output carries the local offset instead of UTC `Z` (new `utc` prop restores v2 output).
+---
+
+# BbDatePickerInput — v2 → v3
+
+## Changes
+
+| v2                                                        | v3                                                                                                                         | Kind                                                             |
+| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `allowWriting?: boolean \| 'not-mobile'` (default `true`) | `disableWriting?: boolean \| 'mobile' \| 'desktop'` (default `false`)                                                      | rename, polarity inverted, **token set changed**                 |
+| `hidePopover?: boolean \| 'not-mobile'`                   | `disableCalendar?: boolean \| 'mobile' \| 'desktop'` (default `false`)                                                     | rename, same polarity, **token set changed**                     |
+| `width?: number \| string`                                | removed                                                                                                                    | calendar sizes itself; use CSS on `.bb-date-picker*` if you must |
+| day slots by raw date                                     | `#<slotKey(date)>` — `#2024-03-15` → `#2024_03_15` (plus new scoped `day` / `append:day` slots)                            | **⚠ silent** — stale raw-date slot names render fallback         |
+| non-floating output: UTC `Z` (`2025-12-31T23:00:00.000Z`) | local-offset ISO (`2026-01-01T00:00:00+01:00`); new `utc` prop restores the v2 output                                      | **⚠ silent** — same instant, different digits (see below)        |
+| —                                                         | `adaptive` (mobile bottom sheet, on by default), `offCanvasProps`, `labelMode`, `description`, `transitionDuration`, `utc` | additive                                                         |
+
+`floating` (plain-date output), `range`, `min`/`max`, `selectable`,
+`firstDayOfWeek` are unchanged.
+
+> **`range` requires an array modelValue.** As in v2, range mode's value must
+> always be an array — use `[]` for the empty state, never `null`/`undefined`.
+> Binding a non-array throws _"Date picker is set to select multiple dates but
+> modelValue is not an array."_ If a filter models "unset" as `null` elsewhere,
+> seed and clear this field to `[]`.
+
+## The allowWriting mapping
+
+| v2                                                    | v3                                |
+| ----------------------------------------------------- | --------------------------------- |
+| unset / `allow-writing`                               | unset (typing allowed everywhere) |
+| `:allow-writing="false"`                              | `disable-writing`                 |
+| `allow-writing="not-mobile"` (typing only on desktop) | `disable-writing="mobile"`        |
+
+```diff
+- <BbDatePickerInput v-model="date" allow-writing="not-mobile" :width="320" />
++ <BbDatePickerInput v-model="date" disable-writing="mobile" />
+```
+
+## The hidePopover mapping
+
+Same polarity (`true` still means "no calendar"), but the platform token
+changed: v2's `'not-mobile'` meant "hidden where not mobile", which is v3's
+`'desktop'`.
+
+| v2                                                    | v3                           |
+| ----------------------------------------------------- | ---------------------------- |
+| unset / `:hide-popover="false"`                       | unset (calendar everywhere)  |
+| `hide-popover` / `:hide-popover="true"`               | `disable-calendar`           |
+| `hide-popover="not-mobile"` (calendar only on mobile) | `disable-calendar="desktop"` |
+
+```diff
+- <BbDatePickerInput v-model="date" disable-writing="mobile" hide-popover="not-mobile" />
++ <BbDatePickerInput v-model="date" disable-writing="mobile" disable-calendar="desktop" />
+```
+
+> v2 additionally threw on the `disable-writing="mobile"` +
+> `hide-popover="not-mobile"` combination even though its own error message
+> recommended it (the mobile guard misread `'not-mobile'`). v3's guard is
+> coherent: the pair above is the blessed "type on desktop, tap the calendar
+> on mobile" split.
+
+## Non-floating output: local offset instead of UTC `Z`
+
+v2 emitted `value.toISOString()` — always UTC. A Berlin user picking Jan 1
+emitted `2025-12-31T23:00:00.000Z`, so backends doing `substring(0, 10)` got
+the wrong day. v3 emits the same instant with the local offset —
+`2026-01-01T00:00:00+01:00` — so the emitted digits match what the user sees
+in the fields.
+
+- **Reading is unaffected.** Incoming values parse identically whether they
+  carry `Z`, an offset, or no zone at all — stored v2 values keep working.
+- **If your backend requires `Z` output**, add the `utc` prop: it restores
+  the exact v2 emission and changes nothing else (fields still display local
+  time).
+- `utc` is ignored (with a DEV warning) when `floating` is set — a plain date
+  carries no zone.
+
+```diff
+  <!-- keep v2's UTC output -->
+- <BbDatePickerInput v-model="date" />
++ <BbDatePickerInput v-model="date" utc />
+```

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

@@ -0,0 +1,46 @@
+---
+title: 'Migration v2→v3: BbDialog'
+summary: showClose inverted to hideClose, several presentation props removed, default widths changed, adaptive bottom sheet on mobile by default.
+---
+
+# BbDialog — v2 → v3
+
+v2's `BbDialog` was a re-export of `BaseDialog`; v3 makes it first-class
+(deprecated `BaseDialogProps`-style type aliases remain for one major).
+
+## Changes
+
+| v2                                                  | v3                                                                                                                                  | Kind                                                            |
+| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `showClose?: boolean` (default `true`)              | `hideClose?: boolean` (default `false`)                                                                                             | rename, polarity inverted                                       |
+| `description`                                       | removed                                                                                                                             | put it in the default slot / `header` slot                      |
+| `hideHeader`                                        | removed                                                                                                                             | omit `title` and the header collapses; or use the `header` slot |
+| `compact`                                           | removed                                                                                                                             | spacing is token-driven now (`--bb-panel-p`)                    |
+| `overlayClasses`, `panelClasses` (deprecated in v2) | removed                                                                                                                             | use normal `class` / CSS on `.bb-dialog*`                       |
+| `size?: 'sm' \| 'md' \| 'lg'`                       | `size?: Responsive<'xs'…'2xl' \| CSS length>`                                                                                       | widened — **but defaults changed, see below**                   |
+| `transitionDuration` default `300`                  | default `250`                                                                                                                       | visual                                                          |
+| —                                                   | `adaptive` (default from config, **on**), `offCanvasProps`, `stack`, `fullscreen`, `persistent`, `disabled`, `focusTarget`, `eager` | additive                                                        |
+
+## ⚠ The two silent ones
+
+1. **Widths.** The size presets resolve from config, and the defaults changed:
+   v2 `{ sm: 384, md: 652, lg: 896 }` → v3
+   `{ xs: 320, sm: 384, md: 448, lg: 512, xl: 576, '2xl': 672 }`. A
+   `size="md"` dialog loses ~200px. Pin the old values via
+   `dialogDefaultSizes` in the plugin if your layouts assumed them
+   ([main guide §2](../v2-to-v3.md)).
+2. **Mobile.** With `adaptive` on by default, dialogs render as a bottom sheet
+   below the mobile breakpoint. Opt out per dialog (`:adaptive="false"`) or
+   globally (`adaptive: false` plugin option).
+
+## Edits
+
+```diff
+- <BbDialog v-model="open" :show-close="false" size="md" description="Review before sending">
++ <BbDialog v-model="open" hide-close size="md">
++   <template #header="{ titleId }">
++     <h2 :id="titleId">Review before sending</h2>
++   </template>
+    …
+  </BbDialog>
+```

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

@@ -0,0 +1,31 @@
+---
+title: 'Migration v2→v3: BbDropdownButton'
+summary: autoLoading renamed to disableAutoLoading, disabledWhileLoading and theme removed.
+---
+
+# BbDropdownButton — v2 → v3
+
+## Changes
+
+| v2                                                | v3                                               | Kind                                                                                                             |
+| ------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| `autoLoading?: boolean` (default `true`)          | `disableAutoLoading?: boolean` (default `false`) | rename, polarity inverted — same effective default                                                               |
+| `disabledWhileLoading?: boolean` (default `true`) | removed                                          | always disabled while loading now; `BbButton`'s `interactive-while-loading` is the escape hatch on plain buttons |
+| `theme?: string`                                  | removed                                          | use `variant` (shares `ButtonVariantType`)                                                                       |
+| `arrowPadding`                                    | removed                                          | dead prop (no arrow on dropdown surfaces)                                                                        |
+| —                                                 | `right:icon?: IconType`                          | additive — replaces the default toggle chevron                                                                   |
+
+## Edits
+
+```diff
+- <BbDropdownButton :auto-loading="false" :items="items">Actions</BbDropdownButton>
++ <BbDropdownButton disable-auto-loading :items="items">Actions</BbDropdownButton>
+
+  <!-- passing autoLoading's default -->
+- <BbDropdownButton auto-loading :items="items">Actions</BbDropdownButton>
++ <BbDropdownButton :items="items">Actions</BbDropdownButton>
+
+  <!-- disabledWhileLoading had no opt-out replacement -->
+- <BbDropdownButton :disabled-while-loading="false" … />
++ <BbDropdownButton … />  <!-- accept the disable; it prevents racing the pending action -->
+```