bitboss-ui 3.0.0-beta.48 → 3.0.0-beta.49

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

@@ -1,19 +1,20 @@
 ---
 title: 'Migration v2→v3: BbDropdownButton'
-summary: autoLoading renamed to disableAutoLoading, disabledWhileLoading and theme removed.
+summary: autoLoading renamed to disableAutoLoading, disabledWhileLoading and theme removed; items are { label, value } rows like BbDropdown's.
 ---
 
 # 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)                                                                        |
-| —                                                 | `toggle:icon?: IconType`                         | additive — replaces the default toggle chevron (spelled `right:icon` up to beta.33)                              |
+| 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)                                                                        |
+| —                                                 | `toggle:icon?: IconType`                                                                         | additive — replaces the default toggle chevron (spelled `right:icon` up to beta.33)                              |
+| items `{ key, text }` (v2, and v3 up to beta.48)  | items `{ value, label }` — the same rows as `BbDropdown`; the main button reads `items[0].label` | hard rename — `npx bitboss-ui check --fix` rewrites literal items; see [bb-dropdown.md](./bb-dropdown.md)        |
 
 ## Edits
 

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

@@ -1,24 +1,25 @@
 ---
 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.
+summary: Rows are { label, value } (v2 and v3 up to beta.48 { key, text }), groups are named by id; rows 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                                                                                                                                                                                                                                                                                                                                                                                           |
-| async (pipeline) group rows copied `BbBaseButton` props, icons, `variant`, `onClick` and `disabled` off each raw item                                                                                                                 | a fetched row takes text/value from `itemText`/`itemValue` and **every other field only from `itemProps`**; per-row `disabled` becomes a `selectable` predicate on the group                                                                                                                 | **⚠ silent**: a raw `href`/`prepend:icon`/`disabled` field is now ignored. Move it: `itemProps: { href: 'url', 'prepend:icon': 'icon' }`, `selectable: (item) => !item.disabled`                                                                                                                                                                                                                   |
-| 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.                                                                                                                                                                                                                                                                           |
-| _(v3 prereleases up to beta.24 only; v2 had no panel)_ `span.bb-dropdown__panel` nested inside `.bb-common-popover__bubble`                                                                                                           | one `<div>` carries both classes; `__header` / `__list` / `__footer` are its direct children                                                                                                                                                                                                 | DOM only, and only for projects already on a v3 prerelease. Every class name survives and the menu's sizes are unchanged; `span.bb-dropdown__panel` and `.bb-common-popover__bubble > .bb-dropdown__panel` now match nothing — write `.bb-dropdown__panel` alone. `pt:panel` used to reach an unpainted box inside the border; it now reaches the bordered surface itself. Submenus are unchanged. |
-| _(v3 prereleases up to beta.30)_ a shared `item:append` lost to a row's `append:icon`; a named `#<key>:append` replaced the check and the submenu chevron; every row of a selectable group reserved its trailing region for the check | each row edge holds **one** occupant, strongest first. Trailing: the check (selected row only) → `#<key>:append` → the submenu chevron → `#<groupKey>:item:append` → `item:append` → `append:icon`. Leading: `#<key>:prepend` → `#<groupKey>:item:prepend` → `item:prepend` → `prepend:icon` | **⚠ silent**: an `item:append` now replaces the rows' `append:icon`; a `#<key>:append` on the selected row gives way to the check; unselected rows of a selectable group now show their `append:icon` or append slot. Nothing renders side by side — to keep an icon next to your slot content, draw both in the slot                                                                              |
-| _(v3 prereleases up to beta.33; v2 had no selectable groups)_ re-clicking the selected row of a single (non-`multiple`) selectable group cleared it (`item:unselected`, `v-model` → `null`)                                           | the group behaves like a radio group: a re-click keeps the pick; the group field `clearable: true` restores clear-on-re-click                                                                                                                                                                | **⚠ silent**: no `item:unselected` and no `null` on a re-click. Add `clearable: true` to the group where click-to-clear was the UX                                                                                                                                                                                                                                                                 |
+| 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                                                                                                                                                                                                                                                                                                                                                                                           |
+| async (pipeline) group rows copied `BbBaseButton` props, icons, `variant`, `onClick` and `disabled` off each raw item                                                                                                                 | a fetched row takes text/value from `itemText`/`itemValue` and **every other field only from `itemProps`**; per-row `disabled` becomes a `selectable` predicate on the group                                                                                                                                                                  | **⚠ silent**: a raw `href`/`prepend:icon`/`disabled` field is now ignored. Move it: `itemProps: { href: 'url', 'prepend:icon': 'icon' }`, `selectable: (item) => !item.disabled`                                                                                                                                                                                                                   |
+| 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.                                                                                                                                                                                                                                                                           |
+| _(v3 prereleases up to beta.24 only; v2 had no panel)_ `span.bb-dropdown__panel` nested inside `.bb-common-popover__bubble`                                                                                                           | one `<div>` carries both classes; `__header` / `__list` / `__footer` are its direct children                                                                                                                                                                                                                                                  | DOM only, and only for projects already on a v3 prerelease. Every class name survives and the menu's sizes are unchanged; `span.bb-dropdown__panel` and `.bb-common-popover__bubble > .bb-dropdown__panel` now match nothing — write `.bb-dropdown__panel` alone. `pt:panel` used to reach an unpainted box inside the border; it now reaches the bordered surface itself. Submenus are unchanged. |
+| _(v3 prereleases up to beta.30)_ a shared `item:append` lost to a row's `append:icon`; a named `#<key>:append` replaced the check and the submenu chevron; every row of a selectable group reserved its trailing region for the check | each row edge holds **one** occupant, strongest first. Trailing: the check (selected row only) → `#<key>:append` → the submenu chevron → `#<groupKey>:item:append` → `item:append` → `append:icon`. Leading: `#<key>:prepend` → `#<groupKey>:item:prepend` → `item:prepend` → `prepend:icon`                                                  | **⚠ silent**: an `item:append` now replaces the rows' `append:icon`; a `#<key>:append` on the selected row gives way to the check; unselected rows of a selectable group now show their `append:icon` or append slot. Nothing renders side by side — to keep an icon next to your slot content, draw both in the slot                                                                              |
+| _(v3 prereleases up to beta.33; v2 had no selectable groups)_ re-clicking the selected row of a single (non-`multiple`) selectable group cleared it (`item:unselected`, `v-model` → `null`)                                           | the group behaves like a radio group: a re-click keeps the pick; the group field `clearable: true` restores clear-on-re-click                                                                                                                                                                                                                 | **⚠ silent**: no `item:unselected` and no `null` on a re-click. Add `clearable: true` to the group where click-to-clear was the UX                                                                                                                                                                                                                                                                 |
+| rows `{ key, text }` (v2, and v3 up to beta.48); groups `{ key, label }` (v3 only); a single-choice group with a `null` model showed no row checked                                                                                   | rows `{ value, label }` — `value` is the identity, any type (the selection value, compared by hash; the `#<value>` slots; the submenu id seed); groups `{ id, label }` (the `<BbDropdownGroup id>` word; `#<groupId>:item`); a `null` model checks the row whose `value` is `null`; slot scopes and `useBbDropdownContext` say `label` / `id` | hard rename, no alias — `npx bitboss-ui check --fix` (ESLint `bitboss-ui/no-renamed-item-field`) rewrites literal items; rows built in `.ts` or mapped from data need a hand pass (typed ones fail `vue-tsc`)                                                                                                                                                                                      |
 
 ## Edits
 
@@ -26,7 +27,7 @@ Fetched groups — raw-item fields move into `itemProps`:
 
 ```diff
   {
-    key: 'assignee',
+    id: 'assignee',
 -   selectable: true,
     items: () => api.users(),
     itemText: 'name',

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

@@ -11,4 +11,5 @@ surface, one set of changes. Everything is in
 `legendPosition`, `direction` / `inputDirection` → `layout` / `listLayout`),
 per-item `disabled` becoming inert (use `selectable`), the `bb-cr-container`
 CSS block split per group, and the `--bb-checkbox-*` / `--bb-radio-*` /
-`--bb-switch-*` variables becoming glyph locals.
+`--bb-switch-*` variables becoming glyph locals, and object items reading
+their own `label` (else `text`) and `value` by default.

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

@@ -14,7 +14,7 @@ summary: flip and allowWriting inverted, arrow props removed, filterBy narrowed,
 | `hideArrow` (default `true`), `arrowPadding` (default `10`) | removed                                                                                                           | arrows are tooltip-only in v3; **⚠ silent** — `:hide-arrow="false"` (the only meaningful v2 use) now lands in `$attrs` and no arrow renders |
 | `transitionDuration` default `300`                          | default `250`                                                                                                     | visual — the panel now animates on the shared `transitions.medium` scale, like `BbDialog`                                                   |
 | `filterBy` union (fn, `false`, `'not_stashed'`, …)          | `filterBy?: string[]` (default `[]`)                                                                              | retype — filter your `items`/provider instead                                                                                               |
-| `itemText` / `itemValue`                                    | `ItemAccessor<Item, …>`                                                                                           | retype                                                                                                                                      |
+| `itemText` / `itemValue`                                    | `ItemAccessor<Item, …>`                                                                                           | retype; left out, an object item reads its own `label` / `text` and `value` (see Behavior)                                                  |
 | per-item `disabled`                                         | inert — use `selectable`                                                                                          | **⚠ silent**                                                                                                                                |
 | —                                                           | `anchor`, `adaptive` + `offCanvasProps`, `selectable`, `active` event, activator scope `text` / `selectedOptions` | additive                                                                                                                                    |
 
@@ -52,6 +52,11 @@ the panel now has `#header` / `#footer`.
   `(query, prefill, modelValue)`; `prefill === true` becomes
   `reason !== 'search'`, a failure throws (never `return []`). **⚠ silent**
   for untyped code — see [§6 item 37](../v2-to-v3.md).
+- **Object items read their own `label` and `value`** (beta.49): no
+  `item-text` → the item's `label`, else `text`; no `item-value` → its
+  `value`, else the whole item. **⚠ silent** for items carrying a `value` key:
+  `v-model` gets that value, not the object. See
+  [§6 item 49](../v2-to-v3.md).
 
 ## Edits
 

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

@@ -1,6 +1,6 @@
 ---
 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).
+summary: allowWriting inverted to disableWriting, filterBy narrowed to string[], prefill value renamed, chevron/options slots removed, and three behavior changes (second click, mount-time coherence, object items read their own label / value).
 ---
 
 # BbSelect — v2 → v3
@@ -17,7 +17,7 @@ summary: allowWriting inverted to disableWriting, filterBy narrowed to string[],
 | `prefill?: boolean \| 'focus'` (default `'focus'`)                            | `prefill?: boolean \| 'interaction'` (default `'interaction'`)                                                                                                           | value renamed; `'focus'` no longer compiles. Unset now genuinely inherits the default (v2's wrapper silently coerced an unset prop to `false`).                                                                                                |
 | `prefill: false` (fetched on first open)                                      | `prefill: false` is **search-first**: with a provider, nothing fetches until the user types — opening shows a "search to begin" hint (`select.searchToStart`)            | **⚠ silent** — a v2 `prefill: false` select opens to the hint instead of options. If you meant "load on open", delete the prop: that is the default. Falls back to load-on-open for array `items`, `disable-writing`, or a non-empty model.    |
 | `transitionDuration` default `300`                                            | default `250`                                                                                                                                                            | visual — the panel now animates on the shared `transitions.medium` scale, like `BbDialog`                                                                                                                                                      |
-| `itemText` / `itemValue`                                                      | `ItemAccessor<T, …>`                                                                                                                                                     | retype — keys autocomplete, functions unchanged                                                                                                                                                                                                |
+| `itemText` / `itemValue`                                                      | `ItemAccessor<T, …>`                                                                                                                                                     | retype — keys autocomplete, functions unchanged; left out, an object item reads its own `label` (else `text`) and `value` (else the whole item) — see Behavior 7                                                                               |
 | per-item `disabled` honored (deprecated)                                      | inert — use `selectable?: boolean \| ((item) => boolean)`                                                                                                                | **⚠ silent** — see below                                                                                                                                                                                                                       |
 | —                                                                             | `adaptive` + `offCanvasProps` (mobile sheet, on by default), `labelMode`, `description`, and the new `active` event (fires when the panel opens; `inactive` pre-existed) | 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). |
@@ -68,6 +68,14 @@ summary: allowWriting inverted to disableWriting, filterBy narrowed to string[],
    `(query, prefill, modelValue)`; `prefill === true` becomes
    `reason !== 'search'`, a failure throws (never `return []`). **⚠ silent**
    for untyped code — see [§6 item 37](../v2-to-v3.md).
+7. **Object items read their own `label` and `value`** (beta.49). With no
+   `item-text`, an object item shows its `label`, else its `text`, else
+   `JSON.stringify(item)`; with no `item-value`, `v-model` gets its `value`
+   (whatever it holds, `null` included), else the whole item. Explicit
+   accessors win. **⚠ silent**: `{ value: 1, label: 'One' }` items with no
+   `item-value` used to put the object in `v-model`; now they put `1` — pass
+   `:item-value="(item) => item"` to keep the object. See
+   [§6 item 49](../v2-to-v3.md).
 
 ## Edits
 

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

@@ -11,4 +11,5 @@ surface, one set of changes. Everything is in
 `legendPosition`, `direction` / `inputDirection` → `layout` / `listLayout`),
 per-item `disabled` becoming inert (use `selectable`), the `bb-cr-container`
 CSS block split per group, and the `--bb-checkbox-*` / `--bb-radio-*` /
-`--bb-switch-*` variables becoming glyph locals.
+`--bb-switch-*` variables becoming glyph locals, and object items reading
+their own `label` (else `text`) and `value` by default.

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

@@ -1,6 +1,6 @@
 ---
 title: 'Migration v2→v3: BbTabs (was BbTab)'
-summary: Component renamed; querykey→queryKey; animations default on; label slots renamed, header:* slots → wrapper:*, and all dynamic names/URL slugs normalized; the entire .bb-tab BEM tree renamed to .bb-tabs / .bb-tabs-list / .bb-tabs-panels.
+summary: Component renamed; item key→value (v-model carries it); querykey→queryKey; animations default on; label slots renamed, header:* slots → wrapper:*, and all dynamic names/URL slugs normalized; the entire .bb-tab BEM tree renamed to .bb-tabs / .bb-tabs-list / .bb-tabs-panels.
 ---
 
 # BbTabs — v2 → v3
@@ -15,9 +15,9 @@ aliases survive as deprecated re-exports, the tag name does not).
 | `<BbTab>`                                                                      | `<BbTabs>`                                                     | rename                                                                                           |
 | `querykey?: string`                                                            | `queryKey?: string` (default `'tab'`)                          | **⚠ silent** — a leftover `querykey` is ignored and URL sync moves to `?tab=`                    |
 | `animateX` / `animateY` (default `true`)                                       | `disableAnimateX` / `disableAnimateY` (default `false`)        | polarity rename — bare `animate-x` → delete; `:animate-x="false"` → `disable-animate-x`          |
-| label slot `#label-<key>` (v3 ≤ beta.43: `#label:<key>`)                       | `#<slotKey(key)>:label`                                        | rename + normalization — dev builds warn on `#label:<key>`, `bitboss-ui check --fix` rewrites it |
+| label slot `#label-<key>` (v3 ≤ beta.43: `#label:<key>`)                       | `#<slotKey(value)>:label`                                      | rename + normalization — dev builds warn on `#label:<key>`, `bitboss-ui check --fix` rewrites it |
 | `#header:prepend` / `#header:append`                                           | `#wrapper:prepend` / `#wrapper:append` (same slot props)       | a leftover `#header:*` renders nothing — `bitboss-ui check` flags it                             |
-| pane slot `#<key>` (raw)                                                       | `#<slotKey(key)>`                                              | normalization                                                                                    |
+| pane slot `#<key>` (raw)                                                       | `#<slotKey(value)>`                                            | normalization                                                                                    |
 | URL value = raw key                                                            | URL value = normalized slug                                    | **⚠ breaking for deep links**                                                                    |
 | tab/panel DOM ids from raw key                                                 | normalized (also fixes invalid ids for spaced keys)            | check E2E selectors                                                                              |
 | `.bb-tab*` CSS                                                                 | `.bb-tabs*` / `.bb-tabs-list*` / `.bb-tabs-panels`             | **⚠ silent** — the whole BEM tree renamed, see below                                             |
@@ -25,13 +25,14 @@ aliases survive as deprecated re-exports, the tag name does not).
 | —                                                                              | `variant` (`pill` default, `line`, `none`, + registered)       | additive — replaces hand-rolled underline / no-chrome strips, see below                          |
 | `--pill-bg` / `--pill-border` / `--pill-shadow` on `.bb-tabs-list` (beta ≤ 28) | `--indicator-bg` / `--indicator-border` / `--indicator-shadow` | **⚠ silent** — inert locals, the strip reverts to its default pill                               |
 
-`slotKey(key)` is kebab-case (lodash `kebabCase` rules): `"In Review"` →
-`in-review`, `"in_review"` → `in-review`, `"inReview"` → `in-review`. Keys that
+`slotKey(value)` is kebab-case (lodash `kebabCase` rules): `"In Review"` →
+`in-review`, `"in_review"` → `in-review`, `"inReview"` → `in-review`. Values that
 are already lowercase kebab slugs are untouched — then only the
-`#label-<key>` → `#<key>:label` rename applies. (On a v3 beta ≤ 37 the rule was `_`: `in_review`.)
+`#label-<key>` → `#<value>:label` rename applies. (On a v3 beta ≤ 37 the rule was `_`: `in_review`.)
 
-**What stays raw:** `v-model` and the item `key`. `v-model="'In Review'"`
+**What stays raw:** `v-model` and the item `value`. `v-model="'In Review'"`
 still selects that tab; only slots, ids, and the URL use the slug.
+| item `key` (v2, and v3 up to beta.48) | item `value` — what `v-model` carries and what names the `#<value>` / `#<value>:label` slots (the same characters as before); `useBbTabsContext().select(value)`; the `#label` / `#<value>:label` slot scope says `label` (was `text`) | hard rename — `npx bitboss-ui check --fix` rewrites literal items; `label` is unchanged |
 
 ## Edits
 
@@ -53,7 +54,7 @@ the kebab slug (`?section=in-review`, not `?section=In%20Review`). Bookmarks
 with a v3 beta's underscore slug (`?section=in_review`) still land and are
 rewritten in place; raw v2 values fall back to the default tab — add a
 redirect if those links matter. App code that WRITES tab values (links,
-`router.push`, redirects, emails) must use the kebab slug: `slotKey(key)`.
+`router.push`, redirects, emails) must use the kebab slug: `slotKey(value)`.
 
 ## CSS: every class renamed with the component
 

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

@@ -9,7 +9,7 @@ summary: timeout renamed to delay; theme replaced by typed variant; hideArrow is
 
 | v2                                     | v3                                                                         | Kind                                                                                                                  |
 | -------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `timeout?: number`                     | `delay?: number` (default `0`)                                             | rename (`BbAvatar.timeout` is unrelated and keeps its name)                                                           |
+| `timeout?: number`                     | `delay?: number` (default `100`)                                           | rename (`BbAvatar.timeout` is unrelated and keeps its name)                                                           |
 | `theme?: string` (deprecated)          | `variant?: TooltipVariantType` (`default, destructive`; default `default`) | typed rename                                                                                                          |
 | arrow via undeclared fall-through      | `hideArrow?: boolean` (default `false` — arrow shown)                      | now a real, typed prop                                                                                                |
 | `activator` / `boundary` loose types   | `ElementOrComponentRef*`                                                   | transparent in templates                                                                                              |

package/dist/ai/guides/migration/v2-to-v3.md

@@ -871,22 +871,26 @@ to the new name (`hide-close`).
 
 ### 5.3 Straight renames
 
-| Component                                                                                                                                                                                                                                                                                                                                                                                              | v2                                       | v3                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `BbPagination`, `BbTabs`                                                                                                                                                                                                                                                                                                                                                                               | `querykey`                               | `queryKey` — **⚠ silent**: a leftover `querykey` falls through to the DOM and the component uses the default key (`'page'` / `'tab'`), quietly moving your URL params.                                                                                                                                                                                                                                                                                         |
-| `BbTooltip`                                                                                                                                                                                                                                                                                                                                                                                            | `timeout`                                | `delay`                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `toast()`, `confirm()` options                                                                                                                                                                                                                                                                                                                                                                         | `timeout`                                | `duration` — same meaning (ms before auto-dismiss). `toast()` throws on `duration <= 0`; on `confirm()` it resolves the promise `false` quietly and implies `autoClose: true`.                                                                                                                                                                                                                                                                                 |
-| `useToast()`                                                                                                                                                                                                                                                                                                                                                                                           | `dismissAll()`                           | `dismiss()` with **no argument**. The v3 return shape is `{ toast, dismiss, update }`.                                                                                                                                                                                                                                                                                                                                                                         |
-| `BbIcon`                                                                                                                                                                                                                                                                                                                                                                                               | `type` (required)                        | `icon`                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `BbColorPalette`, `BbColorInput`                                                                                                                                                                                                                                                                                                                                                                       | `picker`                                 | `eyeDropper`                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`                                                                                                                                                                                                                                                                                                                                                     | `labelPosition`                          | `legendPosition`                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| Every form control — `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbColorInput`, `BbSelect`, `BbDatePickerInput`, `BbTimePickerInput`, `BbTag`, `BbCheckbox`, `BbRadio`, `BbSwitch`, `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`, `BbRating`, `BbSlider`                                                                                                                                      | `direction`                              | `layout` — same values (`'auto'`, `'horizontal'`, `'vertical'`, a `'xx xxxxxx'` ratio), plus `'label-fill'` (the label takes the free space, the input keeps its size — with `reverse`, the settings row) and `'input-fill'`. **⚠ silent**: a leftover `direction` falls through to the root as an HTML attribute and the field keeps its default layout. The ESLint plugin's `--fix` renames it.                                                              |
-| `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`                                                                                                                                                                                                                                                                                                                                                     | `inputDirection`                         | `listLayout` — `'horizontal'` (default) / `'vertical'` / `'vertical-stretch'` / `'tiles'`. **⚠ silent**: v2 `'vertical'` rows spanned the list; v3 `'vertical'` rows keep their own width, and `'vertical-stretch'` is the v2 look — the ESLint plugin's `--fix` maps a static `'vertical'` to `'vertical-stretch'`, a bound value is only renamed. New beside it: `itemLayout` (each row's input against its label, the `layout` keywords) and `itemReverse`. |
-| `BbSelect`                                                                                                                                                                                                                                                                                                                                                                                             | `prefill: 'focus'`                       | `prefill: 'interaction'` (value rename; same default)                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `BbToast` (host)                                                                                                                                                                                                                                                                                                                                                                                       | `placement` (e.g. `bottom-start`)        | `position` (corner set: `top-left` … `bottom-right`)                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `BbAlert`, `BbTooltip`, `toast()`, `confirm()`                                                                                                                                                                                                                                                                                                                                                         | `theme`                                  | `variant` (typed — see section 4). On `confirm()` the v2 type was a free-form `theme?: string`; v3's is `ConfirmVariantType` (`default`, `destructive`).                                                                                                                                                                                                                                                                                                       |
-| Every form control with a warning state — `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbColorInput`, `BbSelect`, `BbSelectPopover`, `BbDatePickerInput`, `BbTimePickerInput`, `BbTag`, `BbCheckbox`, `BbRadio`, `BbSwitch`, `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`, `BbRating`, `BbSlider`, `BbDropzone` — and the `BbBaseCheckboxIcon` / `BbBaseRadioIcon` / `BbBaseSwitchIcon` glyphs | `hasWarning` _(v3 ≤ beta.24; not in v2)_ | `hasWarnings` — plural, matching `hasErrors` and the `warnings` prop. **⚠ silent**: a leftover `has-warning` falls through to the root as an HTML attribute and the warning chrome never shows. The ESLint plugin's `--fix` renames it. Slot props that carried it (`#input`, `#label`) are renamed the same way.                                                                                                                                              |
-| `BbForm` _(v3 ≤ beta.41; not in v2)_                                                                                                                                                                                                                                                                                                                                                                   | `modelValue` (`v-model`)                 | `model`, bound one way: `<BbForm :model="draft">` — any reactive object (`reactive()`, a `ref`, Pinia state, Inertia `useForm()`), written in place; watch it `{ deep: true }`. The form-level `update:modelValue` is gone (it carried the same object back). **⚠ silent**: a leftover `v-model` / `:model-value` falls through to the `<form>` as an attribute and the fields stop seeing the object. The ESLint rule `bitboss-ui/form-model` fixes both.     |
+| Component                                                                                                                                                                                                                                                                                                                                                                                              | v2                                       | v3                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BbPagination`, `BbTabs`                                                                                                                                                                                                                                                                                                                                                                               | `querykey`                               | `queryKey` — **⚠ silent**: a leftover `querykey` falls through to the DOM and the component uses the default key (`'page'` / `'tab'`), quietly moving your URL params.                                                                                                                                                                                                                                                                                                              |
+| `BbTooltip`                                                                                                                                                                                                                                                                                                                                                                                            | `timeout`                                | `delay`                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `toast()`, `confirm()` options                                                                                                                                                                                                                                                                                                                                                                         | `timeout`                                | `duration` — same meaning (ms before auto-dismiss). `toast()` throws on `duration <= 0`; on `confirm()` it resolves the promise `false` quietly and implies `autoClose: true`.                                                                                                                                                                                                                                                                                                      |
+| `useToast()`                                                                                                                                                                                                                                                                                                                                                                                           | `dismissAll()`                           | `dismiss()` with **no argument**. The v3 return shape is `{ toast, dismiss, update }`.                                                                                                                                                                                                                                                                                                                                                                                              |
+| `BbIcon`                                                                                                                                                                                                                                                                                                                                                                                               | `type` (required)                        | `icon`                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `BbColorPalette`, `BbColorInput`                                                                                                                                                                                                                                                                                                                                                                       | `picker`                                 | `eyeDropper`                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`                                                                                                                                                                                                                                                                                                                                                     | `labelPosition`                          | `legendPosition`                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Every form control — `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbColorInput`, `BbSelect`, `BbDatePickerInput`, `BbTimePickerInput`, `BbTag`, `BbCheckbox`, `BbRadio`, `BbSwitch`, `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`, `BbRating`, `BbSlider`                                                                                                                                      | `direction`                              | `layout` — same values (`'auto'`, `'horizontal'`, `'vertical'`, a `'xx xxxxxx'` ratio), plus `'label-fill'` (the label takes the free space, the input keeps its size — with `reverse`, the settings row) and `'input-fill'`. **⚠ silent**: a leftover `direction` falls through to the root as an HTML attribute and the field keeps its default layout. The ESLint plugin's `--fix` renames it.                                                                                   |
+| `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`                                                                                                                                                                                                                                                                                                                                                     | `inputDirection`                         | `listLayout` — `'horizontal'` (default) / `'vertical'` / `'vertical-stretch'` / `'tiles'`. **⚠ silent**: v2 `'vertical'` rows spanned the list; v3 `'vertical'` rows keep their own width, and `'vertical-stretch'` is the v2 look — the ESLint plugin's `--fix` maps a static `'vertical'` to `'vertical-stretch'`, a bound value is only renamed. New beside it: `itemLayout` (each row's input against its label, the `layout` keywords) and `itemReverse`.                      |
+| `BbSelect`                                                                                                                                                                                                                                                                                                                                                                                             | `prefill: 'focus'`                       | `prefill: 'interaction'` (value rename; same default)                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `BbToast` (host)                                                                                                                                                                                                                                                                                                                                                                                       | `placement` (e.g. `bottom-start`)        | `position` (corner set: `top-left` … `bottom-right`)                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `BbAlert`, `BbTooltip`, `toast()`, `confirm()`                                                                                                                                                                                                                                                                                                                                                         | `theme`                                  | `variant` (typed — see section 4). On `confirm()` the v2 type was a free-form `theme?: string`; v3's is `ConfirmVariantType` (`default`, `destructive`).                                                                                                                                                                                                                                                                                                                            |
+| Every form control with a warning state — `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbColorInput`, `BbSelect`, `BbSelectPopover`, `BbDatePickerInput`, `BbTimePickerInput`, `BbTag`, `BbCheckbox`, `BbRadio`, `BbSwitch`, `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`, `BbRating`, `BbSlider`, `BbDropzone` — and the `BbBaseCheckboxIcon` / `BbBaseRadioIcon` / `BbBaseSwitchIcon` glyphs | `hasWarning` _(v3 ≤ beta.24; not in v2)_ | `hasWarnings` — plural, matching `hasErrors` and the `warnings` prop. **⚠ silent**: a leftover `has-warning` falls through to the root as an HTML attribute and the warning chrome never shows. The ESLint plugin's `--fix` renames it. Slot props that carried it (`#input`, `#label`) are renamed the same way.                                                                                                                                                                   |
+| `BbForm` _(v3 ≤ beta.41; not in v2)_                                                                                                                                                                                                                                                                                                                                                                   | `modelValue` (`v-model`)                 | `model`, bound one way: `<BbForm :model="draft">` — any reactive object (`reactive()`, a `ref`, Pinia state, Inertia `useForm()`), written in place; watch it `{ deep: true }`. The form-level `update:modelValue` is gone (it carried the same object back). **⚠ silent**: a leftover `v-model` / `:model-value` falls through to the `<form>` as an attribute and the fields stop seeing the object. The ESLint rule `bitboss-ui/form-model` fixes both.                          |
+| `BbDropdown`, `v-bb-dropdown`, `BbDropdownButton` rows                                                                                                                                                                                                                                                                                                                                                 | `key`, `text`                            | `value`, `label` (also v3 ≤ beta.48). `value` is the row's identity, any type: the selection value a selectable group puts in `v-model` (compared by hash, so `null` and objects work), the `#<value>` slot name, the submenu id seed. A row with no `value` still renders and runs `onClick` (disabled in a selectable group). **⚠ silent**: an old `key` / `text` is ignored; `npx bitboss-ui check --fix` (or ESLint `bitboss-ui/no-renamed-item-field`) rewrites literal items. |
+| `BbDropdown`, `v-bb-dropdown`, `BbDropdownButton` groups _(v3 ≤ beta.48; not in v2)_                                                                                                                                                                                                                                                                                                                   | `key`                                    | `id`, the word `<BbDropdownGroup id>` binds by (`#<groupId>:item` slots, same characters). **⚠ silent**: a group with `key` is not selectable and no companion binds it; `check --fix` rewrites it.                                                                                                                                                                                                                                                                                 |
+| `BbTabs`, `BbTabsRoot` items                                                                                                                                                                                                                                                                                                                                                                           | `key`                                    | `value` — what `v-model` carries and what names `#<value>` / `#<value>:label` (the same characters as before); `server` tabs and `useBbTabsContext().select(value)` follow. `label` is unchanged. `check --fix` rewrites literal items.                                                                                                                                                                                                                                             |
+| `BbBreadcrumbs` items                                                                                                                                                                                                                                                                                                                                                                                  | `key`, `text`                            | `value`, `label` — `value` names the crumb's `#<value>` slots; a crumb hidden in the overflow menu is a dropdown row with the same fields. `check --fix` rewrites literal items.                                                                                                                                                                                                                                                                                                    |
 
 ### 5.4 Removed props (no replacement needed — behavior became default or moved)
 
@@ -1340,7 +1344,7 @@ Nothing here fails to compile — these change what existing code does.
     family's day slots are `#<YYYY-MM-DD>:append` and the shared
     `#day:append` (v3 betas: `#append:<date>` / `#append:day`). The same
     warnings and `check --fix` cover these.
-    `BbTabs` goes further: the label slot is `#<key>:label` (v2 `#label-<key>`,
+    `BbTabs` goes further: the label slot is `#<value>:label` (v2 `#label-<key>`,
     v3 betas `#label:<key>`),
     the URL query value is the kebab slug (`?tab=In%20Review` →
     `?tab=in-review`; old `?tab=in_review` links from a v3 beta still land and
@@ -1751,6 +1755,99 @@ Nothing here fails to compile — these change what existing code does.
     pseudo-class (Tailwind `active:`), and the current-route highlight stays
     `activeClass` / `exactActiveClass`.
 
+48. **Tooltips wait 100 ms on hover** (since 3.0.0-beta.49). `BbTooltip` and
+    `v-bb-tooltip` used to show on hover at once (`delay` defaulted to `0`);
+    the default is now `100`, so a pointer passing over a row of buttons no
+    longer flashes a bubble at each. Keyboard focus shows the tooltip at once
+    whatever `delay` says, and a tooltip reached while another shows or
+    within 300 ms of one closing skips its delay. A test that hovers and
+    expects the bubble on the next tick now waits for it (`vi.waitFor`, or
+    `:delay="0"` in that test); `:delay="0"` / `{ text, delay: 0 }` restores
+    the instant hover open.
+
+49. **`{ label, value }` items need no `item-text` / `item-value`** (since
+    3.0.0-beta.49). With neither prop, an option on `BbSelect`,
+    `BbSelectPopover`, `BbRadioGroup`, `BbCheckboxGroup`, `BbSwitchGroup` and a
+    mapped `BbDropdown` group reads its own `label` (else its own `text`) as
+    its text, and its own `value` as its value, whatever it holds (`null`
+    included). Before, the text was `JSON.stringify(item)` and the value the
+    whole object. The break: object items with a `value` key and no
+    `item-value` used to put the whole object in `v-model`, and now put
+    `item.value` there. To keep the old value, write it out:
+    `:item-value="(item) => item"`. An explicit accessor always wins, and
+    `BbTable` rows keep the whole row. `item-text="label"` /
+    `item-value="value"` now restate the default: the
+    `bitboss-ui/no-redundant-item-accessor` autofix deletes them.
+
+50. **A dropdown group's "None" row shows checked** (since 3.0.0-beta.49).
+    A single-choice `BbDropdown` / `BbDropdownButton` group whose `v-model`
+    is `null` (or that has nothing selected) shows its row whose `value` is
+    `null` as checked, as `BbSelect` and `BbRadioGroup` already do (they
+    match by hash); picking it emits `null`. Before, nothing showed checked.
+    A hand-written group's `v-model` holds its rows' `value`s, of any type,
+    where it held their `key` strings (§ 5.3).
+
+51. **Slot scopes and `useBbDropdownContext` follow the item fields** (since
+    3.0.0-beta.49). The row slots of `BbDropdown` / `BbDropdownButton`
+    (`#<value>`, `#<groupId>:item`, `#item:prepend`, …), `BbTabs`'
+    `#<value>:label` / `#label` and `BbBreadcrumbs`' crumb slots hand
+    `{ label }` where they handed `{ text }`; a row slot's `group` carries
+    `id` (was `key`); the `#loading` / `#empty` slots' `groupKey` is
+    `groupId`. `useBbDropdownContext(id).groups` is keyed by each group's
+    `id`, and `selectedOptions[]` carry `label` (was `text`). A destructured
+    `{ text }` reads `undefined`, with no error: rename it to `{ label }`.
+
+52. **`BbPopover` is non-modal** (since 3.0.0-beta.49). Its panel is a
+    `role="dialog"` without `aria-modal`, not a `<dialog>` opened with
+    `showModal()`: the page behind stays clickable, focusable and scrollable,
+    an outside click closes the popover and still reaches what was clicked,
+    and Tab past the last control (or Shift+Tab before the first) leaves the
+    panel and closes it. Escape still closes it and returns focus. A flow that
+    relied on the page being blocked while the popover is open adds `modal`
+    (`v-bb-popover="{ portal, modal: true }"` on the directive), which restores
+    the old behaviour exactly. A test that queried `dialog.bb-popover` queries
+    `.bb-popover[role="dialog"]`. The phone sheet is modal either way.
+
+53. **A form locks while its save runs** (since 3.0.0-beta.49). While a
+    `@submit` that returned a promise is pending, every field joined to the
+    `BbForm` is read-only (never disabled: values stay visible and focusable,
+    `aria-readonly`) and every `type="submit"` `BbButton` inside it shows its
+    spinner; both end when the promise settles. A sync `@submit` never locks.
+    A `:loading="isSubmitting"` on the submit button is now redundant (drop
+    it); a submit button outside the form still binds `loading` itself. A
+    page that wants the fields editable during the save sets
+    `disable-submit-lock` on the form.
+
+54. **A set of `group` toggle buttons is one Tab stop** (since
+    3.0.0-beta.49). Adjacent `group` `BbButton`s that each bind a `v-model`
+    take a roving `tabindex`: Tab lands on the pressed one (else the one last
+    focused, else the first), ArrowLeft / ArrowRight and Home / End move
+    between them, Space / Enter toggle. They keep `aria-pressed`. A keyboard
+    test that pressed Tab once per button now presses an arrow key instead;
+    `group` buttons without a `v-model` are unchanged.
+
+55. **`BbNumberInput` formats live in the locale** (since 3.0.0-beta.49). The
+    field shows `10.005,6` in Italian and `10,005.6` in English while the user
+    types; the model is still the plain number. Code that reads the input's
+    text (`event.target.value`, a `pt:input` listener, a consumer `maxlength`
+    or `pattern`) now sees the formatted text, which is also wider: check
+    narrow fixed-width fields at 200% zoom. `name` moves to a hidden input
+    that posts the raw value (`10005.6`): `form.elements[name]` and
+    `input[name=x]` find that one, so a test that typed into
+    `input[name=x]` targets `input[role="spinbutton"]`. A pasted `1.000` in
+    Italian is 1000 (it was 1), an English `1,234` is 1234, and a paste keeps
+    only the first number (`$1,234.56 - $2,000` is 1234.56, `(1,234.56)` is negative, `1.2E+05` is 120000, `15 m²`
+    is 15); a typed `,` or
+    `.` is still always the decimal; with `maxPrecision` 0 it stays in the
+    text and refuses the digits after it (`12,5` is 12, it was 125), and
+    below 3 decimals (every currency field) a second `,` / `.` is refused.
+    `-` typed anywhere flips the sign (it only counted at the start). While
+    the text is a bare `-` the model keeps its last value instead of
+    becoming `null`; blur rewrites the text from the value (`1,50` → `1,5`).
+    With the new `currency` / `unit` the symbol is in that text too
+    (`$1,234.50`, `20 kg`), so a `maxlength` counts it. `disable-formatting`
+    restores the old field exactly.
+
 ## 7. Class overrides → variants
 
 ### The v2 pattern to hunt down

package/dist/ai/guides/migration/v3-beta-tooling.md

@@ -118,6 +118,17 @@ All of these land in 3.0.0-beta.41.
 - A new `warnings` array (never fails the run), with `severity: "warning"`:
   `likely-squashed-slot` and `local-bb-component`.
 
+In 3.0.0-beta.49 the dropdown kinds follow the item fields (Q64.2):
+`missing-key` is `missing-value` (a row in a selectable group without a
+`value`) or `missing-id` (a selectable group without an `id`), and
+`duplicate-row-text` is `duplicate-row-label`. A new `renamed-item-field`
+reports an item field spelled the old way (a dropdown row's `key` / `text`, a
+dropdown group's `key`, a tab's `key`, a crumb's `key` / `text`) and
+`check --fix` rewrites it; its ESLint twin is
+`bitboss-ui/no-renamed-item-field` (`error` in `recommended`). A script that
+matches the old kind names in `check --json` output needs the new ones;
+`eslint-disable` comments name rules, which did not change.
+
 After 3.0.0-beta.41, `check` alone (not MCP `validate`: it needs the project's
 build config) adds `kind: "hand-imported-styles"`: `bitboss-ui/styles.css`
 imported in a CSS file, a script, a `.vue` block or Nuxt's `css: [...]` while