bitboss-ui 2.1.135 → 3.0.0-alpha.4

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 -->
+```

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-[color:var(--bb-text-muted)]" />
+```
+
+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-offcanvas.md

@@ -0,0 +1,63 @@
+---
+title: 'Migration v2→v3: BbOffCanvas'
+summary: direction→side; showClose→hideClose; size defaults change; adaptive drawer configs unify on offCanvasProps.
+---
+
+# BbOffCanvas — v2 → v3
+
+## 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'`                                                                                                                    |
+| `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                                                                                                                                                                                                 |
+
+`direction` → **`side`** is 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). Same value set, same
+default.
+
+```diff
+- <BbOffCanvas v-model="open" direction="right" :show-close="false" size="md" title="Filters" />
++ <BbOffCanvas v-model="open" side="right" hide-close size="md" title="Filters" />
+```
+
+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.
+
+**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
+- <BbDialog :off-canvas-props="{ direction: 'bottom' }" />
++ <BbDialog :off-canvas-props="{ side: 'bottom' }" />
+```
+
+The failure mode for leftover `direction` is silent (Vue does not warn on
+unknown props; it 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.