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

package/dist/ai/guides/migration/v3-beta-css-classes.md

@@ -35,7 +35,7 @@ Each `pt` part now has a class with the same name, on the same element:
 
 <!-- generated:count -->
 
-In numbers: **85** classes renamed, **23** added beside an existing class, and **7** new state classes and elements.
+In numbers: **86** classes renamed, **23** added beside an existing class, and **7** new state classes and elements.
 
 <!-- /generated:count -->
 
@@ -75,7 +75,7 @@ bash and zsh. On Windows, use Git Bash or WSL.
 
 ```sh
 rg -nP --glob '!node_modules' --glob '!dist' --glob '!rename-bb-classes.mjs' \
-  '(?<![\w-])(bb-checkbox-group-item__description|bb-switch-group-item__description|bb-radio-group-item__description|bb-dropdown-button__dropdown-btn|bb-segmented-field__trigger-btn|bb-select-popover__search-input|bb-select-popover__search-clear|bb-listbox__option-description|bb-dropzone__interactive-label|bb-time-picker-input-offcanvas|bb-checkbox-group-item__label|bb-dropdown__items-container|bb-dropdown-button__main-btn|bb-pagination__page-chevron|bb-switch-group-item__label|bb-table-column-ghost__icon|bb-select-popover-offcanvas|bb-radio-group-item__label|bb-color-palette-offcanvas|bb-checkbox-group__no-data|bb-segmented-field__field|bb-time-selector__readout|bb-toast-message__content|bb-toast-message__actions|bb-color-palette__popover|bb-commabox-item--focused|bb-listbox__option-label|bb-calendar__header-cell|bb-calendar__date-button|bb-time-selector__header|bb-date-picker-offcanvas|bb-time-picker-offcanvas|bb-calendar__date-append|bb-switch-group__no-data|bb-indicator__indicator|bb-toast-message__title|bb-toast-message__close|bb-date-picker__popover|bb-time-picker__popover|bb-toast-message__inner|bb-radio-group__no-data|bb-badge__clear-button|bb-checkbox-group-item|bb-toast-message__icon|bb-toast-message__text|bb-table-no-data__cell|bb-table-no-data__text|bb-select__comma-item|bb-calendar__controls|bb-time-selector__btn|bb-tabs-list__tablist|bb-table-no-data__row|bb-calendar__nav-btn|bb-switch-group-item|bb-popover-offcanvas|bb-field__hint-text|bb-tooltip__content|bb-radio-group-item|bb-table-header-row|bb-table-sort__icon|bb-table-data__cell|bb-listbox--no-data|bb-listbox__no-data|bb-tag__text-input|bb-button__content|bb-table-data__row|bb-offcanvas__body|bb-calendar__month|bb-badge__content|bb-calendar__date|item__description|bb-rating__option|bb-badge--focused|bb-chipsbox-item|bb-commabox-item|bb-table-caption|bb-tabs__trigger|bb-toast-message|bb-select__chip|bb-table-header|bb-dialog__body|bb-tree__node|bb-tabs-panes|bb-tabs__pane|item__text)(?![\w]|-(?!-))'
+  '(?<![\w-])(bb-checkbox-group-item__description|bb-switch-group-item__description|bb-radio-group-item__description|bb-dropdown-button__dropdown-btn|bb-segmented-field__trigger-btn|bb-select-popover__search-input|bb-select-popover__search-clear|bb-listbox__option-description|bb-dropzone__interactive-label|bb-time-picker-input-offcanvas|bb-checkbox-group-item__label|bb-dropdown__items-container|bb-dropdown-button__main-btn|bb-pagination__page-chevron|bb-switch-group-item__label|bb-table-column-ghost__icon|bb-select-popover-offcanvas|bb-radio-group-item__label|bb-color-palette-offcanvas|bb-checkbox-group__no-data|bb-segmented-field__field|bb-time-selector__readout|bb-toast-message__content|bb-toast-message__actions|bb-color-palette__popover|bb-commabox-item--focused|bb-listbox__option-label|bb-calendar__header-cell|bb-calendar__date-button|bb-time-selector__header|bb-date-picker-offcanvas|bb-time-picker-offcanvas|bb-calendar__date-append|bb-switch-group__no-data|bb-indicator__indicator|bb-toast-message__title|bb-toast-message__close|bb-date-picker__popover|bb-time-picker__popover|bb-toast-message__inner|bb-radio-group__no-data|bb-badge__clear-button|bb-checkbox-group-item|bb-toast-message__icon|bb-toast-message__text|bb-table-no-data__cell|bb-table-no-data__text|bb-select__comma-item|bb-calendar__controls|bb-time-selector__btn|bb-tabs-list__tablist|bb-table-no-data__row|bb-calendar__nav-btn|bb-switch-group-item|bb-popover-offcanvas|bb-field__hint-text|bb-tooltip__content|bb-radio-group-item|bb-table-header-row|bb-table-sort__icon|bb-table-data__cell|bb-listbox--no-data|bb-listbox__no-data|bb-tag__text-input|bb-button__content|bb-table-data__row|bb-offcanvas__body|bb-calendar__month|bb-badge__content|bb-calendar__date|item__description|bb-rating__option|bb-badge--focused|bb-button--active|bb-chipsbox-item|bb-commabox-item|bb-table-caption|bb-tabs__trigger|bb-toast-message|bb-select__chip|bb-table-header|bb-dialog__body|bb-tree__node|bb-tabs-panes|bb-tabs__pane|item__text)(?![\w]|-(?!-))'
 ```
 
 <!-- /generated:find -->
@@ -98,7 +98,7 @@ List the nested selectors that may spell an old name:
 
 ```sh
 rg -nP --glob '*.{css,scss,sass,less,styl,pcss,postcss,vue,svelte,astro}' --glob '!node_modules' --glob '!dist' \
-  '(?:&|#\{&\})(-picker-input-offcanvas|__option-description|__interactive-label|-popover-offcanvas|-palette-offcanvas|__items-container|-picker-offcanvas|-input-offcanvas|__dropdown-btn|__search-input|__search-clear|__page-chevron|-item--focused|__option-label|__clear-button|__description|__trigger-btn|-column-ghost|__header-cell|__date-button|__date-append|-description|__comma-item|__text-input|-group-item|__indicator|__hint-text|-header-row|-offcanvas|-container|__main-btn|__controls|__no-data|__readout|-selector|__content|__actions|__popover|--focused|__tablist|__nav-btn|--no-data|__trigger|-popover|-chevron|-message|-palette|-focused|__header|-no-data|__option|-caption|-button|__label|__field|-append|__title|__close|-picker|__inner|__month|-header|-field|-input|-clear|-label|__icon|-ghost|-group|__text|__cell|__body|__date|__chip|__node|-panes|__pane|-item|-data|-cell|__btn|-list|__row|-text|-sort|-btn|-row)(?=[\s,{:.>+~\[)]|__|--|$)'
+  '(?:&|#\{&\})(-picker-input-offcanvas|__option-description|__interactive-label|-popover-offcanvas|-palette-offcanvas|__items-container|-picker-offcanvas|-input-offcanvas|__dropdown-btn|__search-input|__search-clear|__page-chevron|-item--focused|__option-label|__clear-button|__description|__trigger-btn|-column-ghost|__header-cell|__date-button|__date-append|-description|__comma-item|__text-input|-group-item|__indicator|__hint-text|-header-row|-offcanvas|-container|__main-btn|__controls|__no-data|__readout|-selector|__content|__actions|__popover|--focused|__tablist|__nav-btn|--no-data|__trigger|-popover|-chevron|-message|-palette|-focused|__header|-no-data|__option|--active|-caption|-button|__label|__field|-append|__title|__close|-picker|__inner|__month|-active|-header|-field|-input|-clear|-label|__icon|-ghost|-group|__text|__cell|__body|__date|__chip|__node|-panes|__pane|-item|-data|-cell|__btn|-list|__row|-text|-sort|-btn|-row)(?=[\s,{:.>+~\[)]|__|--|$)'
 ```
 
 <!-- /generated:nested -->
@@ -243,6 +243,7 @@ const MAP = {
 	'bb-calendar__month': 'bb-calendar__month-grid',
 	'bb-toast-message__inner': 'bb-toast__inner',
 	'bb-badge--focused': 'bb-badge--highlighted',
+	'bb-button--active': 'bb-button--pressed',
 	'bb-commabox-item--focused': 'bb-tag__comma--highlighted',
 	'bb-tabs-list__tablist': 'bb-tabs-list__list',
 	'bb-tabs-panes': 'bb-tabs-panels',
@@ -723,29 +724,30 @@ consistent.
 
 ### Everything else
 
-| Before                              | After                            | Part                                    | Note                                                                                                                                                                                      |
-| ----------------------------------- | -------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `.bb-badge__content`                | `.bb-badge__text`                | `text`                                  |                                                                                                                                                                                           |
-| `.bb-badge__clear-button`           | `.bb-badge__clear`               | `clear`                                 |                                                                                                                                                                                           |
-| `.bb-button__content`               | `.bb-button__text`               | `text`                                  |                                                                                                                                                                                           |
-| `.bb-dropdown__items-container`     | `.bb-dropdown__list`             | `list`                                  |                                                                                                                                                                                           |
-| `.item__text`                       | `.bb-dropdown__item-text`        | `itemText`                              | No `bb-` prefix: the script only reports it. Rename it where it is the dropdown menu row's (inside a `.bb-dropdown` / `.bb-dropdown-button` selector); an `item__text` of your own stays. |
-| `.item__description`                | `.bb-dropdown__item-description` | `itemDescription`                       | As above.                                                                                                                                                                                 |
-| `.bb-dropzone__interactive-label`   | `.bb-dropzone__content`          | `content`                               |                                                                                                                                                                                           |
-| `.bb-indicator__indicator`          | `.bb-indicator__bubble`          | `bubble`                                |                                                                                                                                                                                           |
-| `.bb-pagination__page-chevron`      | `.bb-pagination__icon`           | `icon`                                  |                                                                                                                                                                                           |
-| `.bb-rating__option`                | `.bb-rating__item`               | `item`                                  |                                                                                                                                                                                           |
-| `.bb-tooltip__content`              | `.bb-tooltip__panel`             | `panel`                                 |                                                                                                                                                                                           |
-| `.bb-tree__node`                    | `.bb-tree__item`                 | `item`                                  |                                                                                                                                                                                           |
-| `.bb-tabs__trigger`                 | `.bb-tabs-list__item`            | `item`                                  | The tab button is drawn by BbTabsList, so it takes BbTabsList's block.                                                                                                                    |
-| `.bb-badge--focused`                | `.bb-badge--highlighted`         | BbTag `badge`, state `highlighted`      | The arrow-key cursor on a BbTag chip. It was never real focus (focus stays in the input), hence the new name.                                                                             |
-| `.bb-tabs-list__tablist`            | `.bb-tabs-list__list`            | `list`                                  | The sliding indicator is no longer this list's `::before`: it is an element, `.bb-tabs-list__indicator`, the list's first child. Move a `::before` override there.                        |
-| `.bb-tabs-panes`                    | `.bb-tabs-panels`                | BbTabs `panels` (the BbTabsPanels root) | The component is renamed too: `BbTabsPanes` → `BbTabsPanels`.                                                                                                                             |
-| `.bb-tabs__pane`                    | `.bb-tabs__panel`                | `panel`                                 | Drawn by BbTabsPanels; the class keeps the tabs' own word for the part.                                                                                                                   |
-| `.bb-dropdown-button__main-btn`     | `.bb-dropdown-button__main`      | `main`                                  | The main half of the split button (the `main` part).                                                                                                                                      |
-| `.bb-dropdown-button__dropdown-btn` | `.bb-dropdown-button__toggle`    | `toggle`                                | The chevron half that opens the menu (the `toggle` part).                                                                                                                                 |
-| `.bb-checkbox-group__no-data`       | `.bb-checkbox-group__empty`      | `empty`                                 |                                                                                                                                                                                           |
-| `.bb-radio-group__no-data`          | `.bb-radio-group__empty`         | `empty`                                 |                                                                                                                                                                                           |
-| `.bb-switch-group__no-data`         | `.bb-switch-group__empty`        | `empty`                                 |                                                                                                                                                                                           |
+| Before                              | After                            | Part                                    | Note                                                                                                                                                                                                                                               |
+| ----------------------------------- | -------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.bb-badge__content`                | `.bb-badge__text`                | `text`                                  |                                                                                                                                                                                                                                                    |
+| `.bb-badge__clear-button`           | `.bb-badge__clear`               | `clear`                                 |                                                                                                                                                                                                                                                    |
+| `.bb-button__content`               | `.bb-button__text`               | `text`                                  |                                                                                                                                                                                                                                                    |
+| `.bb-dropdown__items-container`     | `.bb-dropdown__list`             | `list`                                  |                                                                                                                                                                                                                                                    |
+| `.item__text`                       | `.bb-dropdown__item-text`        | `itemText`                              | No `bb-` prefix: the script only reports it. Rename it where it is the dropdown menu row's (inside a `.bb-dropdown` / `.bb-dropdown-button` selector); an `item__text` of your own stays.                                                          |
+| `.item__description`                | `.bb-dropdown__item-description` | `itemDescription`                       | As above.                                                                                                                                                                                                                                          |
+| `.bb-dropzone__interactive-label`   | `.bb-dropzone__content`          | `content`                               |                                                                                                                                                                                                                                                    |
+| `.bb-indicator__indicator`          | `.bb-indicator__bubble`          | `bubble`                                |                                                                                                                                                                                                                                                    |
+| `.bb-pagination__page-chevron`      | `.bb-pagination__icon`           | `icon`                                  |                                                                                                                                                                                                                                                    |
+| `.bb-rating__option`                | `.bb-rating__item`               | `item`                                  |                                                                                                                                                                                                                                                    |
+| `.bb-tooltip__content`              | `.bb-tooltip__panel`             | `panel`                                 |                                                                                                                                                                                                                                                    |
+| `.bb-tree__node`                    | `.bb-tree__item`                 | `item`                                  |                                                                                                                                                                                                                                                    |
+| `.bb-tabs__trigger`                 | `.bb-tabs-list__item`            | `item`                                  | The tab button is drawn by BbTabsList, so it takes BbTabsList's block.                                                                                                                                                                             |
+| `.bb-badge--focused`                | `.bb-badge--highlighted`         | BbTag `badge`, state `highlighted`      | The arrow-key cursor on a BbTag chip. It was never real focus (focus stays in the input), hence the new name.                                                                                                                                      |
+| `.bb-button--active`                | `.bb-button--pressed`            | `root`                                  | A toggle `BbButton` (`v-model`) that is on: it is pressed (`aria-pressed="true"`), not "active". Style it with `pt:root:pressed`, or keep a selector on `.bb-button--pressed`. A pointer press is the `:active` pseudo-class (Tailwind `active:`). |
+| `.bb-tabs-list__tablist`            | `.bb-tabs-list__list`            | `list`                                  | The sliding indicator is no longer this list's `::before`: it is an element, `.bb-tabs-list__indicator`, the list's first child. Move a `::before` override there.                                                                                 |
+| `.bb-tabs-panes`                    | `.bb-tabs-panels`                | BbTabs `panels` (the BbTabsPanels root) | The component is renamed too: `BbTabsPanes` → `BbTabsPanels`.                                                                                                                                                                                      |
+| `.bb-tabs__pane`                    | `.bb-tabs__panel`                | `panel`                                 | Drawn by BbTabsPanels; the class keeps the tabs' own word for the part.                                                                                                                                                                            |
+| `.bb-dropdown-button__main-btn`     | `.bb-dropdown-button__main`      | `main`                                  | The main half of the split button (the `main` part).                                                                                                                                                                                               |
+| `.bb-dropdown-button__dropdown-btn` | `.bb-dropdown-button__toggle`    | `toggle`                                | The chevron half that opens the menu (the `toggle` part).                                                                                                                                                                                          |
+| `.bb-checkbox-group__no-data`       | `.bb-checkbox-group__empty`      | `empty`                                 |                                                                                                                                                                                                                                                    |
+| `.bb-radio-group__no-data`          | `.bb-radio-group__empty`         | `empty`                                 |                                                                                                                                                                                                                                                    |
+| `.bb-switch-group__no-data`         | `.bb-switch-group__empty`        | `empty`                                 |                                                                                                                                                                                                                                                    |
 
 <!-- /generated:renames -->

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

package/dist/ai/guides/options-items-playbook.md

@@ -19,12 +19,12 @@ Companion playbooks: [Fetch Items](./fetch-items-playbook.md) (async providers),
 `items` means two different things in this library, and picking the wrong one is
 the most common early mistake. Ask **whose data is it?**
 
-|                       | **Accessor mode** — _your data_                                                   | **Authored mode** — _your UI_                                                                                                                                                      |
-| --------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Components            | `BbSelect`, `BbSelectPopover`, `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup` | `BbDropdown`, `BbDropdownButton`, `BbTabs`, `BbBreadcrumbs`, `BbTree`                                                                                                              |
-| Shape                 | any shape — raw API rows                                                          | entries you write, each carrying its own caption (`text` on dropdown items and breadcrumbs, `label` on tabs); `BbTree` nodes carry your `meta` and render through its default slot |
-| Caption               | you point at a field: `item-text`, `item-value`                                   | it is on the entry itself                                                                                                                                                          |
-| Rest of this playbook | **applies**                                                                       | mostly does **not** — no accessors, no hash-matching                                                                                                                               |
+|                       | **Accessor mode** — _your data_                                                      | **Authored mode** — _your UI_                                                                                                                                                                            |
+| --------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Components            | `BbSelect`, `BbSelectPopover`, `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`    | `BbDropdown`, `BbDropdownButton`, `BbTabs`, `BbBreadcrumbs`, `BbTree`                                                                                                                                    |
+| Shape                 | any shape — raw API rows                                                             | entries you write, each carrying its own `label` and, where it has one, its identity in `value` (dropdown rows, tabs, breadcrumbs); `BbTree` nodes carry your `meta` and render through its default slot |
+| Caption               | read from `label` (else `text`) and `value`; other fields: `item-text`, `item-value` | it is on the entry itself                                                                                                                                                                                |
+| Rest of this playbook | **applies**                                                                          | mostly does **not** — no accessors, no hash-matching                                                                                                                                                     |
 
 ```vue
 <!-- Accessor mode: customers came from an API, keep their field names. -->
@@ -37,15 +37,17 @@ the most common early mistake. Ask **whose data is it?**
 />
 
 <!-- Authored mode: a menu you typed out. The caption lives on the entry. -->
-<BbDropdown :items="[{ key: 'edit', text: 'Edit' }]" />
+<BbDropdown :items="[{ value: 'edit', label: 'Edit' }]" />
 ```
 
 **Why two, deliberately.** A picker lists records that arrive with their own
-field names (`full_name`, `uuid`), so forcing them into `{ text, value }` would
+field names (`full_name`, `uuid`), so forcing them into `{ label, value }` would
 mean a pointless `.map()` on every list — and it cannot work at all for the
 async form, where the component fetches the items itself and never sees your
 array. A dropdown or a tab strip is the opposite: you are writing those captions
 by hand anyway, so an accessor would be indirection with nothing to point at.
+Rows that already carry `label` (or `text`) and `value` need no accessor in
+either mode: both vocabularies use the same words.
 
 `BbTable` sits between the two: rows stay **raw data** (accessor mode —
 `item-value` is row identity), but the captions live on `columns[].label`, not
@@ -61,18 +63,22 @@ Pass backend/domain items **as-is** to `items` and resolve text/value declarativ
 - `item-text="path.to.label"` or `:item-text="(item) => ..."` — display text
 - `item-value="path.to.id"` or `:item-value="(item) => ..."` — the value stored in `v-model`
 
+`{ label, value }` and `{ text, value }` items work as they are; any other shape
+needs `item-text` / `item-value`.
+
 A **string** item is its own text and value: `item-text` / `item-value` do not
 run on it, so `:item-text="(code) => labels[code]"` over `string[]` still shows
 the raw codes. Give such lists objects (`{ code, label }`) and point the
 accessors at their fields.
 
-Never pre-map accessor-mode items into `{ label, value }` arrays. Matching is hash-based on the extracted value, so component-native extraction stays robust and the raw item remains available to slots (`#option`, cell slots) untouched.
+Never pre-map accessor-mode items into `{ label, value }` arrays: point `item-text` / `item-value` at the fields they already have. Matching is hash-based on the extracted value, so component-native extraction stays robust and the raw item remains available to slots (`#option`, cell slots) untouched.
 
 ### Mapping modes
 
-1. **Primitive items** (`string[]`, `number[]`): omit both props; the value is the primitive itself.
-2. **Dot paths** for nested objects: `item-text="profile.fullName"`, `item-value="profile.id"`.
-3. **Extractor functions** only when a path can't express it:
+1. **`{ label, value }` objects** (or `{ text, value }`): omit both props; the text is the own `label` (else `text`), the value the own `value`.
+2. **Primitive items** (`string[]`, `number[]`): omit both props; the value is the primitive itself.
+3. **Dot paths** for nested objects: `item-text="profile.fullName"`, `item-value="profile.id"`.
+4. **Extractor functions** only when a path can't express it:
 
 ```vue
 <script setup lang="ts">
@@ -137,11 +143,11 @@ prop, `item-props`, and from nowhere else.
 
 Anything else is a type error.
 
-| Component                                          | Fields                                                                          | Notes                                                                                                                                                  |
-| -------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup` | `description`                                                                   | Under the option label, beside the control; may wrap. No icons — the `#icon` slot already means the control glyph.                                     |
-| `BbSelect`, `BbSelectPopover`                      | `description`, `prepend:icon`, `append:icon`                                    | A description makes every row a fixed two lines tall (virtualized) and ellipsizes on one line. The check replaces the append icon on the selected row. |
-| `BbDropdown` fetched (pipeline) groups             | every hand-written row field except `key`, `text`, `items`, `group`, `disabled` | `description`, icons, `variant`, `onClick`, `href` / `to` and the link / Inertia options. Declared in the group config, camelCase: `itemProps`.        |
+| Component                                          | Fields                                                                             | Notes                                                                                                                                                  |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup` | `description`                                                                      | Under the option label, beside the control; may wrap. No icons — the `#icon` slot already means the control glyph.                                     |
+| `BbSelect`, `BbSelectPopover`                      | `description`, `prepend:icon`, `append:icon`                                       | A description makes every row a fixed two lines tall (virtualized) and ellipsizes on one line. The check replaces the append icon on the selected row. |
+| `BbDropdown` fetched (pipeline) groups             | every hand-written row field except `value`, `label`, `items`, `group`, `disabled` | `description`, icons, `variant`, `onClick`, `href` / `to` and the link / Inertia options. Declared in the group config, camelCase: `itemProps`.        |
 
 Everywhere, the description is announced as the row's description (never part
 of its name), the search matches it along with the text when `filter-by` is
@@ -155,7 +161,7 @@ descriptions_, BbDropdown _Fetched assignees_ and _Fetched links_.
 
 ## How options resolve (verified semantics)
 
-- Default `item-value` is the **whole item**; default `itemText` is the string itself for strings, `JSON.stringify(item)` otherwise. For object items, always set both props.
+- With no `item-text`, an object option reads its own `label`, else its own `text`, else `JSON.stringify(item)`; a string is its own text. With no `item-value`, an object option's value is its own `value` (whatever it holds, `null` included), else the **whole item**. So `{ label, value }` and `{ text, value }` items need neither prop; any other shape needs both. An explicit accessor always wins. (BbTable rows keep the whole row: set `item-value` there.)
 - Selection matching compares `hash(itemValue(item))` against `hash(modelValue entry)` — a **deep value** comparison, not reference identity. Object values match structurally, but prefer primitive ids: they are stable across refetches and cheap to submit.
 - Items resolving to a **duplicate value are silently dropped** (first occurrence wins). Guarantee unique `item-value` per option.
 - `modelValue` holds the resolved value(s), never the option wrapper. Slots receive the raw `item` plus resolved `text` / `value`.
@@ -222,14 +228,14 @@ A `disabled` field on the item object (`{ id: 1, label: '…', disabled: true }`
 - `selectable` prop — per-option gating on `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`, `BbSelect`, `BbSelectPopover` and `BbTable`. Either a global boolean (`false` disables every option) or a predicate `(item) => boolean`; options the predicate rejects render disabled. Defaults to `true` on the option components; on `BbTable` it is unset until you pass it — and an unset `selectable` there means "no selection column", not "every row selectable".
 - `max` — caps a multiple selection: at the cap, unselected options auto-disable while **selected options never disable**, so the user can always deselect.
 - `BbDropdown` **hand-written** items are buttons, not options — `disabled` there is a regular button prop and stays supported.
-- `BbDropdown` **fetched (pipeline) group** rows have no `disabled` field: fetched groups are for selection, so gate rows with the group's `selectable` predicate — `selectable: (item) => !item.archived` — which receives the raw fetched item. A raw item's own `disabled` (or `href`, icons, `variant`, …) is data; row fields beyond text and value come only from the group's `itemProps`. Hand-written dropdown groups accept the same predicate, receiving the row object.
+- `BbDropdown` **fetched (pipeline) group** rows have no `disabled` field: fetched groups are for selection, so gate rows with the group's `selectable` predicate — `selectable: (item) => !item.archived` — which receives the raw fetched item. A raw item's own `disabled` (or `href`, icons, `variant`, …) is data; row fields beyond label and value come only from the group's `itemProps`. Hand-written dropdown groups accept the same predicate, receiving the row object.
 
 If your domain data carries an availability flag, feed it to the predicate — e.g. `:selectable="(item) => !item.disabled"` or `:selectable="(user) => user.active"` — or filter the items out entirely when a dead row would add noise.
 
 ## Component-specific notes
 
 - **`BbTable`** — always set `item-value`: selection, expansion (`v-model:expanded-items`) and highlight track rows by that value, so state survives refetches where object references change.
-- **`BbDropdown` pipeline groups** — the group is fully declared in the host's `items` (getter + `itemText` / `itemValue` / `max`, camelCase — it's data, not template props). The `<BbDropdownGroup>` companion is only `id` + `v-model`; its `id` matches the group's `key`:
+- **`BbDropdown` pipeline groups** — the group is fully declared in the host's `items` (getter + `itemText` / `itemValue` (optional when the fetched rows carry `label` and `value`) / `max`, camelCase — it's data, not template props). The `<BbDropdownGroup>` companion is only `id` + `v-model`; its `id` matches the group's `id`:
 
 ```vue
 <script setup lang="ts">
@@ -238,9 +244,9 @@ import { BbButton, BbDropdown, BbDropdownGroup } from 'bitboss-ui';
 
 const assignee = ref<string | null>(null);
 const items = [
-	{ key: 'edit', text: 'Edit invoice', href: '/invoices/42/edit' },
+	{ value: 'edit', label: 'Edit invoice', href: '/invoices/42/edit' },
 	{
-		key: 'assignee',
+		id: 'assignee',
 		label: 'Assign to',
 		selectable: true,
 		items: () => api.members.list(),
@@ -347,7 +353,7 @@ The same rules hold for `BbCheckboxGroup`, `BbRadioGroup` and
 
 ## Items that navigate
 
-When an item is a link, the component navigates — never your code. `BbDropdown` items take `href` (anchor / Inertia visit with `method`, `data`, …) or `to` (vue-router); table row links are a `BbButton` with `href`/`to` in a cell or `#actions` slot. Never `onClick: () => router.push(...)` on an item, and never a row `@click` that sets `window.location`.
+When an item is a link, the component navigates — never your code. `BbDropdown` rows take `href` (anchor / Inertia visit with `method`, `data`, …) or `to` (vue-router); table row links are a `BbButton` with `href`/`to` in a cell or `#actions` slot. Never `onClick: () => router.push(...)` on an item, and never a row `@click` that sets `window.location`.
 
 ## Anti-patterns
 
@@ -361,7 +367,7 @@ When an item is a link, the component navigates — never your code. `BbDropdown
 
 ## Validation checklist
 
-- [ ] Object items set both `item-text` and `item-value` (dot-path first, function only when needed).
+- [ ] Object items without their own `label`/`text` and `value` set both `item-text` and `item-value` (dot-path first, function only when needed); no accessor restates the default (`item-text="label"`, `item-value="value"`).
 - [ ] `item-value` resolves to a stable, unique, preferably primitive identity.
 - [ ] Multiple-mode `v-model` refs are seeded with arrays.
 - [ ] No manual option mapping or template-level reshaping.

package/dist/ai/guides/passthrough.md

@@ -217,7 +217,7 @@ the dialog closing; it observes it.
 one in this list wins, on every component:
 
 ```
-hasValue → nearLimit → atLimit → empty → outside → today → inRange → sorted → sortedDesc → selected → rangeStart → rangeEnd → checked → indeterminate → readonly → disabled → warnings → errors → active → expanded → open → fullscreen → focused → focusVisible → highlighted → loading
+hasValue → nearLimit → atLimit → empty → outside → today → inRange → sorted → sortedDesc → selected → rangeStart → rangeEnd → checked → indeterminate → pressed → readonly → disabled → warnings → errors → active → expanded → open → fullscreen → focused → focusVisible → highlighted → loading
 ```
 
 It is ordered by meaning — the more temporary state wins: a spinner replaces
@@ -316,7 +316,7 @@ part accepts a function** on the instance, beside a plain value:
 
 ```vue
 <!-- a dropdown: the entry's own data says it is destructive —
-     actions = [{ key: 'delete', text: 'Delete', variant: 'destructive' }, …] -->
+     actions = [{ value: 'delete', label: 'Delete', variant: 'destructive' }, …] -->
 <BbDropdown
 	:items="actions"
 	:pt:item="
@@ -906,7 +906,7 @@ _Passthrough parts and states_ table in that component's contract
 | `BbBaseRadioIcon`    | `root`                                                                                                                                                                                                                                                                                                                        | `errors`, `warnings`, `disabled`, `readonly`, `checked`, `focused`, `focusVisible`                                                                       |
 | `BbBaseSwitchIcon`   | `root`                                                                                                                                                                                                                                                                                                                        | `errors`, `warnings`, `disabled`, `readonly`, `checked`, `indeterminate`, `focused`, `focusVisible`                                                      |
 | `BbBreadcrumbs`      | `root`, `item`, `icon`, `text`                                                                                                                                                                                                                                                                                                | `active`, `disabled` _(per crumb)_                                                                                                                       |
-| `BbButton`           | `root`, `icon`, `spinner`, `text`                                                                                                                                                                                                                                                                                             | `loading`, `disabled`                                                                                                                                    |
+| `BbButton`           | `root`, `icon`, `spinner`, `text`                                                                                                                                                                                                                                                                                             | `loading`, `disabled`, `pressed`                                                                                                                         |
 | `BbCalendar`         | `root`, `header`, `arrow`, `month`, `year`, `cellColumnHeader`, `day`, `dayButton`, `monthItem`, `yearItem`, `item` _(the time rail's entries)_                                                                                                                                                                               | `outside`, `today`, `inRange`, `selected`, `rangeStart`, `rangeEnd`, `disabled`, `highlighted` _(per cell)_, `active` _(month / year)_                   |
 | `BbCheckbox`         | `root`, `label`, `description`, `message`, `hint`, `icon`                                                                                                                                                                                                                                                                     | `errors`, `warnings`, `disabled`, `readonly`, `checked`, `indeterminate`, `focused`, `focusVisible`                                                      |
 | `BbCheckboxGroup`    | `root`, `legend`, `description`, `message`, `hint`, `list`, `item`, `icon`, `label`, `itemDescription`                                                                                                                                                                                                                        | `errors`, `warnings`, `disabled`, `readonly`, `loading`, `hasValue`; `checked`, `focused`, `focusVisible` _(row parts only)_                             |
@@ -927,7 +927,7 @@ _Passthrough parts and states_ table in that component's contract
 | `BbOffCanvas`        | `root`, `header`, `title`, `description`, `content`, `footer`, `close`                                                                                                                                                                                                                                                        | `open`, `fullscreen`                                                                                                                                     |
 | `BbPagination`       | `root`, `item`, `arrow`, `ellipsis`, `icon`                                                                                                                                                                                                                                                                                   | `active` _(the current page)_, `disabled` _(per control)_                                                                                                |
 | `BbPopover`          | `root`, `panel`, `sheet`, `header`, `content`, `footer`                                                                                                                                                                                                                                                                       | `open`                                                                                                                                                   |
-| `BbProgress`         | `root`, `bar`                                                                                                                                                                                                                                                                                                                 | —                                                                                                                                                        |
+| `BbProgress`         | `root`, `bar`                                                                                                                                                                                                                                                                                                                 | `indeterminate`                                                                                                                                          |
 | `BbRadio`            | `root`, `label`, `description`, `message`, `hint`, `icon`                                                                                                                                                                                                                                                                     | `errors`, `warnings`, `disabled`, `readonly`, `checked`, `focused`, `focusVisible`                                                                       |
 | `BbRadioGroup`       | `root`, `legend`, `description`, `message`, `hint`, `list`, `item`, `icon`, `label`, `itemDescription`                                                                                                                                                                                                                        | `errors`, `warnings`, `disabled`, `readonly`, `loading`, `hasValue`; `checked`, `focused`, `focusVisible` _(row parts only)_                             |
 | `BbRating`           | `root`, `label`, `description`, `message`, `hint`, `item`                                                                                                                                                                                                                                                                     | `errors`, `warnings`, `disabled`, `readonly`, `hasValue`, `selected` _(per star)_                                                                        |

package/dist/ai/guides/preset-components.md

@@ -145,9 +145,23 @@ type RowOf<P> = P extends { items?: infer I }
 	? Extract<NonNullable<I>, readonly unknown[]>[number]
 	: never;
 
+/**
+ * With no `itemValue`, an option surface (a component with `itemText`) emits
+ * a row's own `value` when it has one, else the row (Q60.24). BbTable keeps
+ * the row.
+ */
+type DefaultValueOf<P> = P extends { itemText?: unknown }
+	? RowOf<P> extends infer R
+		? R extends { value: infer V }
+			? V
+			: R
+		: never
+	: RowOf<P>;
+
 /**
  * The value type when the preset decides it: a fixed key or getter as
- * `itemValue`, or fixed `items` with no `itemValue` (the value is the row).
+ * `itemValue`, or fixed `items` with no `itemValue` (the row's own `value`,
+ * else the row).
  * `never` = not decided (a dotted path, or `itemValue` left to the caller):
  * the component keeps its own model type.
  */
@@ -160,7 +174,7 @@ type ValueOf<P, F> = [RowOf<P>] extends [never]
 				? R
 				: never
 		: F extends { items: unknown }
-			? RowOf<P>
+			? DefaultValueOf<P>
 			: never;
 
 type ModelProps<V, F> = F extends { multiple: true }
@@ -346,7 +360,8 @@ is a `.ts` module, not an `.vue` file.
 2. **What defines the data is fixed; what a page may change is a default.**
    `items`, `itemText`, `itemValue`, `multiple` go in the second argument;
    `label`, `placeholder`, `clearable` in `defaults`.
-3. **A key (or a getter) as `itemValue` types the model.** A dotted path
+3. **A key (or a getter) as `itemValue` types the model.** Rows that carry
+   their own `value` need no `itemValue`: the model is that `value`. A dotted path
    (`'meta.code'`) cannot be typed, so the model keeps `BbSelect`'s own loose
    type. Prefer a getter: `itemValue: (c: Customer) => c.meta.code`.
 4. **`multiple` is fixed or left to the caller**, never a default (the helper

package/dist/ai/guides/typescript-generic-components.md

@@ -6,7 +6,7 @@ summary: Which bitboss-ui components are generic, and the four places their type
 # TypeScript and Generic Components
 
 Some components are **generic**: their types follow what you pass in. The
-row type of `items`, the tab keys, and the empty value a text field emits
+row type of `items`, the tab values, and the empty value a text field emits
 (`null-value`) all flow into the slots and events. In templates this costs
 nothing. In `<script>`, a generic component's type is a **function**
 (`<T>(props, ctx) => VNode`), not a component class, and four everyday

package/dist/ai/guides/validated-forms.md

@@ -40,12 +40,10 @@ async function createAccount(values: z.output<typeof signup>) {
 </script>
 
 <template>
-	<BbForm v-slot="{ isSubmitting }" :schema="signup" @submit="createAccount">
+	<BbForm :schema="signup" @submit="createAccount">
 		<BbTextInput label="Email" name="email" type="email" />
 		<BbCheckbox label="I accept the terms" name="terms" />
-		<BbButton :loading="isSubmitting" type="submit" variant="primary">
-			Create account
-		</BbButton>
+		<BbButton type="submit" variant="primary"> Create account </BbButton>
 	</BbForm>
 </template>
 ```
@@ -77,8 +75,9 @@ That is the whole pattern. The rules that keep a form this small:
   undeclared keys from `@submit`'s values, so a switch or a hidden field the
   schema does not name vanishes (declare it: `separateShipping: z.boolean()`).
 - **`@submit` fires only when the form is valid**, with the values (the
-  schema's output, typed). The slot's `isSubmitting` drives the button. No
-  `saving` ref, no `@submit.prevent`, no `<form>` of your own.
+  schema's output, typed). Return the handler's promise: while it runs the
+  fields are read-only and the `type="submit"` button spins on its own. No
+  `saving` ref, no `:loading`, no `@submit.prevent`, no `<form>` of your own.
 - **A server's 422** goes to the form in one call:
   `useBbFormContext(id).setErrors(body.errors)` (§ 4). No `:errors` ref per
   field. Call `useBbFormContext(id)` once, at the top of `<script setup>`
@@ -173,7 +172,7 @@ async function order(values: Record<string, unknown>) {
 </script>
 
 <template>
-	<BbForm v-slot="{ isSubmitting }" @submit="order">
+	<BbForm @submit="order">
 		<BbTextInput label="Email" name="email" rules="required|email" />
 		<BbNumberInput
 			label="Quantity"
@@ -181,7 +180,7 @@ async function order(values: Record<string, unknown>) {
 			rules="required|min_value:1"
 		/>
 		<BbCheckbox label="Accept terms" name="terms" rules="required" />
-		<BbButton :loading="isSubmitting" type="submit">Order</BbButton>
+		<BbButton type="submit">Order</BbButton>
 	</BbForm>
 </template>
 ```
@@ -276,16 +275,11 @@ const save = async (values: z.output<typeof schema>) => {
 </script>
 
 <template>
-	<BbForm
-		v-slot="{ isSubmitting }"
-		:model="order"
-		:schema="schema"
-		@submit="save"
-	>
+	<BbForm :model="order" :schema="schema" @submit="save">
 		<BbTextInput label="Email" name="email" type="email" />
 		<BbTextInput label="City" name="address[city]" />
 		<BbNumberInput label="Quantity" name="quantity" />
-		<BbButton :loading="isSubmitting" type="submit">Save</BbButton>
+		<BbButton type="submit">Save</BbButton>
 	</BbForm>
 </template>
 ```
@@ -396,7 +390,7 @@ async function save(values: z.output<typeof schema>) {
 	<p>{{ profile.name }}: {{ profile.bio }}</p>
 	<BbForm
 		id="profile"
-		v-slot="{ dirty, isSubmitting }"
+		v-slot="{ dirty }"
 		:model="profile"
 		:schema="schema"
 		@submit="save"
@@ -406,12 +400,7 @@ async function save(values: z.output<typeof schema>) {
 		<BbButton :disabled="!dirty" variant="ghost" @click="form.reset()">
 			Discard
 		</BbButton>
-		<BbButton
-			:disabled="!dirty"
-			:loading="isSubmitting"
-			type="submit"
-			variant="primary"
-		>
+		<BbButton :disabled="!dirty" type="submit" variant="primary">
 			Save
 		</BbButton>
 	</BbForm>

package/dist/ai/guides/validation-providers.md

@@ -102,9 +102,10 @@ there ([BbForm § Server errors](../BbForm.md#server-errors-seterrors-and-fields
 - **Inertia `useForm`** → keep Inertia for the request (`router.post` or
   `useForm().post`), move the fields into `BbForm` with `name`s equal to the
   Laravel keys, and replace `:errors="form.errors.email"` on each input with
-  one `:field-errors="form.errors"` on the `BbForm`. `form.processing` → the slot's
-  `isSubmitting`. Client-side checks move to `rules` or a
-  `schema`.
+  one `:field-errors="form.errors"` on the `BbForm`. `form.processing` → return
+  the visit's promise from `@submit`: the fields lock and the submit button
+  spins while it runs (the slot's `isSubmitting` for anything else). Client-side
+  checks move to `rules` or a `schema`.
 - **Inertia router with an error bag** → `:field-errors="$page.props.errors.<bag>"`.
   `$page.props.errors.<bag>` readers become `errors` / `fields`.
 - **Laravel 422 over fetch / axios** → `if (status === 422) errors.value =