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

package/dist/llms-medium.txt

@@ -115,7 +115,7 @@ inline-edit playbook) instead of inventing a new shape.
 | ⌘K / Ctrl+K global command palette                                                                                   | [BbSelectPopover](https://llms-bitboss-ui.bitboss.it/dist/ai/BbSelectPopover.md#a-k-command-palette) § A ⌘K command palette                                                                                                                                                                                                                                                                                                                           |
 | Tied selects / stale model cleanup                                                                                   | [coherence-playbook](https://llms-bitboss-ui.bitboss.it/dist/ai/guides/coherence-playbook.md)                                                                                                                                                                                                                                                                                                                                                                 |
 | Async `items` providers / prefill                                                                                    | [fetch-items-playbook](https://llms-bitboss-ui.bitboss.it/dist/ai/guides/fetch-items-playbook.md)                                                                                                                                                                                                                                                                                                                                                             |
-| `item-text` / `item-value` / disabled                                                                                | [options-items-playbook](https://llms-bitboss-ui.bitboss.it/dist/ai/guides/options-items-playbook.md)                                                                                                                                                                                                                                                                                                                                                         |
+| `item-text` / `item-value` / the default `label` / `value` keys / disabled                                           | [options-items-playbook](https://llms-bitboss-ui.bitboss.it/dist/ai/guides/options-items-playbook.md)                                                                                                                                                                                                                                                                                                                                                         |
 | Table cell edit ownership                                                                                            | [inline-edit-playbook](https://llms-bitboss-ui.bitboss.it/dist/ai/guides/inline-edit-playbook.md)                                                                                                                                                                                                                                                                                                                                                             |
 | Table row → detail (identity cells)                                                                                  | [agent-contract](https://llms-bitboss-ui.bitboss.it/dist/ai/guides/agent-contract.md) § Inline Links                                                                                                                                                                                                                                                                                                                                                          |
 | Peek that drills into related records                                                                                | [agent-contract](https://llms-bitboss-ui.bitboss.it/dist/ai/guides/agent-contract.md) § Consult-Stack                                                                                                                                                                                                                                                                                                                                                         |
@@ -188,32 +188,32 @@ Use this contract before generating any UI code with `bitboss-ui`.
 The names agents guess most often, and the real ones. There are no aliases:
 a guessed name is an error (`npx bitboss-ui check` or `vue-tsc` says so).
 
-| You'd guess                                                                                  | bitboss-ui                                                                                                                              |
-| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `toast.success('Saved')`, `{ message }`, `{ description }`, `type`                           | `const { toast } = useToast(); toast({ title, text, variant: 'success' })`; variants `default` `success` `info` `warning` `destructive` |
-| `<BbToastStack>`, a toaster per page                                                         | one `<BbToast />` (and one `<BbConfirm />` for `useConfirm`) at the app root                                                            |
-| BbDialog `v-model:open`, `:open`                                                             | `v-model` (a boolean)                                                                                                                   |
-| BbDialog `@close`, `@confirm`, `@cancel`, `#actions`                                         | `@hide` (closing starts) / `@hidden` (closed); your own buttons in `#footer="{ close }"`                                                |
-| BbTable `sortable`, `v-model:sorted`, `sort-order`, `@sort`                                  | `sortable: true` per column + `v-model:sort` (a `BbTableSortEntry[]`, `[key, 'asc' \| 'desc']`); the table never sorts: you do          |
-| `@row-click`, `@row:click`                                                                   | `@click:row="(event, item) => …"`                                                                                                       |
-| `row-key`                                                                                    | `item-value`                                                                                                                            |
-| column `title`, `header`                                                                     | column `label`                                                                                                                          |
-| `#cell:createdAt`, `#createdAt`, `{ row }`                                                   | `#<key>` in kebab-case (`createdAt` → `#created-at`), scope `{ item, value }`                                                           |
-| a column keyed `actions`                                                                     | reserved: the `#actions="{ item }"` slot creates the actions column                                                                     |
-| BbPagination `current-page`, `v-model:page`, `page-size`                                     | `v-model` (the 1-based page) + `per-page` + `total-items` (or `total-pages`)                                                            |
-| `BbDateInput`                                                                                | `BbDatePickerInput`                                                                                                                     |
-| `<BbDropdownItem>`, `<BbTableColumn>`                                                        | types, not components: rows are `items` objects (`{ key, text, onClick }`), columns are `columns` objects                               |
-| BbDropdown `#trigger`, `#button`                                                             | `#activator="{ props }"`, spread `v-bind="props"` on your button                                                                        |
-| a menu row's click via `@select` / `@item:selected`                                          | the item's `onClick` (or `href` / `to`); `@item:selected` fires only for `selectable` groups                                            |
-| `icon` on BbTextInput / BbDropdownButton, `#icon` on BbButton                                | `prepend:icon` / `append:icon`; BbButton's `icon` is the icon-only button                                                               |
-| badge `success` / `warning` / `info` / `danger`                                              | built-ins `primary` `secondary` `destructive` `outline`; register more (§ Variants Rule)                                                |
-| BbBadge `text` / `label` prop                                                                | the default slot: `<BbBadge>Paid</BbBadge>`                                                                                             |
-| `label` on BbCheckboxGroup / BbRadioGroup / BbSwitchGroup / BbRating, a `selectable` BbTable | `legend` (they render a `<fieldset>`; the legend is its name)                                                                           |
-| `{ label, value }` items as they are                                                         | `item-text="label" item-value="value"` (BbSelect, BbSelectPopover, the groups); without them each option reads as JSON                  |
-| BbSelect `searchable`                                                                        | search is on by default; `disable-writing` hides it; `multiple` for a multi-select                                                      |
-| a native `<input>` in a filter bar (to skip the label)                                       | `<BbTextInput label="Search" hide-label />`: the label stays for screen readers                                                         |
-| `--bb-text-secondary`                                                                        | `--bb-text-muted`                                                                                                                       |
-| a 422 through each field's `errors` prop                                                     | inside `BbForm`: `setErrors(errors)` ([validated-forms § 4](https://llms-bitboss-ui.bitboss.it/dist/ai/guides/validated-forms.md#4-server-errors-seterrors-fields-unmatchederrors))     |
+| You'd guess                                                                                  | bitboss-ui                                                                                                                                   |
+| -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `toast.success('Saved')`, `{ message }`, `{ description }`, `type`                           | `const { toast } = useToast(); toast({ title, text, variant: 'success' })`; variants `default` `success` `info` `warning` `destructive`      |
+| `<BbToastStack>`, a toaster per page                                                         | one `<BbToast />` (and one `<BbConfirm />` for `useConfirm`) at the app root                                                                 |
+| BbDialog `v-model:open`, `:open`                                                             | `v-model` (a boolean)                                                                                                                        |
+| BbDialog `@close`, `@confirm`, `@cancel`, `#actions`                                         | `@hide` (closing starts) / `@hidden` (closed); your own buttons in `#footer="{ close }"`                                                     |
+| BbTable `sortable`, `v-model:sorted`, `sort-order`, `@sort`                                  | `sortable: true` per column + `v-model:sort` (a `BbTableSortEntry[]`, `[key, 'asc' \| 'desc']`); the table never sorts: you do               |
+| `@row-click`, `@row:click`                                                                   | `@click:row="(event, item) => …"`                                                                                                            |
+| `row-key`                                                                                    | `item-value`                                                                                                                                 |
+| column `title`, `header`                                                                     | column `label`                                                                                                                               |
+| `#cell:createdAt`, `#createdAt`, `{ row }`                                                   | `#<key>` in kebab-case (`createdAt` → `#created-at`), scope `{ item, value }`                                                                |
+| a column keyed `actions`                                                                     | reserved: the `#actions="{ item }"` slot creates the actions column                                                                          |
+| BbPagination `current-page`, `v-model:page`, `page-size`                                     | `v-model` (the 1-based page) + `per-page` + `total-items` (or `total-pages`)                                                                 |
+| `BbDateInput`                                                                                | `BbDatePickerInput`                                                                                                                          |
+| `<BbDropdownItem>`, `<BbTableColumn>`                                                        | types, not components: rows are `items` objects (`{ value, label, onClick }`), columns are `columns` objects                                 |
+| BbDropdown `#trigger`, `#button`                                                             | `#activator="{ props }"`, spread `v-bind="props"` on your button                                                                             |
+| a menu row's click via `@select` / `@item:selected`                                          | the item's `onClick` (or `href` / `to`); `@item:selected` fires only for `selectable` groups                                                 |
+| `icon` on BbTextInput / BbDropdownButton, `#icon` on BbButton                                | `prepend:icon` / `append:icon`; BbButton's `icon` is the icon-only button                                                                    |
+| badge `success` / `warning` / `info` / `danger`                                              | built-ins `primary` `secondary` `destructive` `outline`; register more (§ Variants Rule)                                                     |
+| BbBadge `text` / `label` prop                                                                | the default slot: `<BbBadge>Paid</BbBadge>`                                                                                                  |
+| `label` on BbCheckboxGroup / BbRadioGroup / BbSwitchGroup / BbRating, a `selectable` BbTable | `legend` (they render a `<fieldset>`; the legend is its name)                                                                                |
+| `{ label, value }` items as they are                                                         | they work as they are, and so do `{ text, value }`: any other shape needs `item-text` / `item-value` (BbSelect, BbSelectPopover, the groups) |
+| BbSelect `searchable`                                                                        | search is on by default; `disable-writing` hides it; `multiple` for a multi-select                                                           |
+| a native `<input>` in a filter bar (to skip the label)                                       | `<BbTextInput label="Search" hide-label />`: the label stays for screen readers                                                              |
+| `--bb-text-secondary`                                                                        | `--bb-text-muted`                                                                                                                            |
+| a 422 through each field's `errors` prop                                                     | inside `BbForm`: `setErrors(errors)` ([validated-forms § 4](https://llms-bitboss-ui.bitboss.it/dist/ai/guides/validated-forms.md#4-server-errors-seterrors-fields-unmatchederrors))          |
 
 ## Default API Boundary
 
@@ -389,7 +389,7 @@ recipe's conformance checklist.
 
 For components accepting `items`:
 
-- prefer declarative mapping with `item-text` and `item-value`;
+- prefer declarative mapping with `item-text` and `item-value` (none when the items already carry `label` and `value`: never restate the default);
 - use `dependencies` and `deps-debounce-time` for tied fields;
 - use `enforce-coherence` instead of custom watchers for stale model cleanup;
 - to style a row BY ITS DATA (a destructive entry, a tile by tier, a row by
@@ -1548,9 +1548,10 @@ payload the same way.
 English since 3.0.0-beta.41 (it was `'it'`): an Italian app sets `locale: 'it'`.
 
 Global locale for the library's built-in strings (empty states, close/clear
-labels, screen-reader announcements, confirm buttons, …). The library ships
-**22 built-in dictionaries** — it, en, es, fr, de, pt (Brazilian-leaning), nl,
-pl, tr, ru, uk, cs, ro, hu, el, sv, da, nb, fi, ja, ko, zh-cn — but shipping ≠
+labels, screen-reader announcements, confirm buttons, …) and for the formats
+around them (dates, numbers, week start). The list is fixed and typed (see
+[Locales](#locales) below): a language (`it`, `de`, …), a region (`en-GB`,
+`de-CH`, `fr-CA`, …), or `pt-BR` / `pt-PT` / `zh-CN` / `zh-TW`. Shipping ≠
 bundling: only the **enabled** locales enter your build (next option). Runtime
 switching: `useBbConfig().setConfig({ locale })` — to a locale you enabled.
 
@@ -1582,8 +1583,8 @@ a locale can.
 
 ### `enabledLocales?: BuiltinLocaleKey[]` (default: your `locale` + `'en'`)
 
-Which built-in dictionaries (and their dayjs calendar packs) actually ship in
-the bundle. The unset default is the minimal set — the `locale` you configured
+Which built-in locales (their dictionaries and dayjs calendar packs) actually
+ship in the bundle; regions of one language share its dictionary. The unset default is the minimal set — the `locale` you configured
 plus `en` (the per-key fallback anchor) — roughly 4KB of strings, so a
 single-language app pays for exactly what it uses without configuring
 anything. Apps that switch locales at runtime list what they offer:
@@ -1609,18 +1610,43 @@ fallback: your project's `bitboss-ui.d.ts` (see
 Start the dev server or run a build once after changing the list, and commit
 the file. Before that file exists, every built-in locale type-checks.
 
-### Custom locales are not a supported surface
-
-The library ships **22 dictionaries** and that is the whole set:
-
-```
-cs da de el en es fi fr hu it ja ko nb nl pl pt ro ru sv tr uk zh-cn
-```
+### Locales
+
+One fixed list (owner ruling, 2026-10-07). A bare language is its default
+region (CLDR likely subtags): `it` is `it-IT`, `de` `de-DE`, `en` `en-US`, `pt`
+`pt-BR`, `zh` `zh-CN` (Simplified).
+
+| Language        | Default                                                          | Regions (same words, own formats)                             | Own dictionary                                                  |
+| --------------- | ---------------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------- |
+| English         | `en` (US)                                                        | `en-GB`, `en-AU`, `en-CA`, `en-IE` (British spelling: colour) |                                                                 |
+| German          | `de`                                                             | `de-AT`                                                       | `de-CH` (ss for ß)                                              |
+| French          | `fr`                                                             | `fr-BE`, `fr-CA`, `fr-CH`                                     |                                                                 |
+| Italian         | `it`                                                             | `it-CH`                                                       |                                                                 |
+| Dutch           | `nl`                                                             | `nl-BE`                                                       |                                                                 |
+| Swedish         | `sv`                                                             | `sv-FI`                                                       |                                                                 |
+| Spanish         | `es` (Spain)                                                     |                                                               | `es-MX` (Mexico)                                                |
+| Portuguese      | `pt-BR`                                                          |                                                               | `pt-PT` (European; week from Sunday, CLDR)                      |
+| Chinese         | `zh-CN` (Simplified)                                             |                                                               | `zh-TW` (Traditional, Taiwan), `zh-HK` (Traditional, Hong Kong) |
+| One region each | `cs` `da` `el` `fi` `hu` `ja` `ko` `nb` `pl` `ro` `ru` `tr` `uk` |                                                               |                                                                 |
+
+A region reads its language's dictionary and follows its own formats: the
+long date and the number grouping (`Intl`, through the region's tag:
+`de-CH` groups `1’234.5`), the week start (its dayjs pack: `en-GB` Monday,
+`en-CA` Sunday), and the date-input field order and AM / PM words (`fr-CA`
+types `AAAA-MM-JJ`, `en-GB` `DD/MM/YYYY`). A region is on the list only where
+its language's words are right there; where they are not (`es-MX`, `zh-HK`),
+the region has its own dictionary.
+
+Codes are case-insensitive (`zh-cn`, the spelling before 3.0.0-beta.49, still
+works), and the full code of a default region is the same locale (`it-IT` is
+`it`). A code that is not on the list is a type error, and
+`npx bitboss-ui check` names the nearest one (`unknown-locale`: `en-UK` →
+`en-GB`).
 
 There is no `additionalLocales` option and no `npx bitboss-ui locale` blueprint
 generator — both were removed deliberately (owner ruling, 2026-08-08). If your
-language is not on that list, the supported answer is to ask for it to be
-added upstream rather than to author a dictionary in your app.
+language or region is not on the list, the supported answer is to ask for it
+to be added upstream rather than to author a dictionary in your app.
 
 Locale selection is **build-time**: `enabledLocales` decides what ships, and
 only the active `locale` switches at runtime, among what the build enabled.
@@ -1834,7 +1860,7 @@ For a human-in-the-loop (and agent) safety net, add the `bitboss-ui/eslint-plugi
 
 Two rules in `recommended` are `warn` rather than `error`, because each describes markup that may be deliberate. `bitboss-ui/no-unknown-event` flags an `@event` the component does not emit (it falls through to the root element, so it may be a considered native listener). `bitboss-ui/no-unknown-token` flags a bare `var(--bb-…)` naming a token the installed package does not declare, in a `<style>` block or a static `style="…"` attribute — an undefined custom property is invalid-at-computed-value-time, so CSS discards the **entire declaration** and the rule silently does nothing at runtime. Supplying a fallback (`var(--bb-canvas, #f8fafc)`) is defined behaviour and is never reported; `allowTokens` exempts names you define yourself. The token list is read from the `dist/styles.css` you installed, so it cannot claim a token is invented when your version declares it, and with no stylesheet present the rule stays silent. Before reaching for a `--bb-*` name at all, re-read the two tiers above: a name the library does not declare usually means the knob you want is a **component** token, not a gap in the global set. `bitboss-ui check` carries two further advisory hints that are deliberately not ESLint rules — the hand-rolled avatar and spinner detectors — because both are guesses, and a lint rule that fires on correct code teaches people to ignore all of them.
 
-`bitboss-ui check` also has one finding with no ESLint twin: `object-items-without-text`. It flags object `items` on an item-driven control (`BbSelect`, `BbSelectPopover`, `BbRadioGroup`, `BbCheckboxGroup`, `BbSwitchGroup`, and each `BbDropdown` group with `group: true`) when `item-text` (a group's `itemText`) is not set. Without it every label is `JSON.stringify(item)`, and without `item-value` the whole object is the value. Setting `item-text` without `item-value` is a deliberate whole-object value and is not flagged, and string items never are. **Its reach is the same file only:** an inline `:items="[…]"`, or a top-level `const x = […]` (or `ref([…])` / `reactive([…])`) in the file's `<script setup>` bound as `:items="x"`. An imported array, a computed or a fetched list is not read, and `check` never guesses at one. Silence one site with `<!-- eslint-disable-next-line bitboss-ui/require-partner-prop -->`.
+`bitboss-ui check` also has one finding with no ESLint twin: `object-items-without-text`. With no `item-text` an option reads its own `label`, else its own `text`, and with no `item-value` its own `value`, so `{ label, value }` and `{ text, value }` items need no accessor. The finding flags object `items` on an item-driven control (`BbSelect`, `BbSelectPopover`, `BbRadioGroup`, `BbCheckboxGroup`, `BbSwitchGroup`) when `item-text` is not set and an item has neither `label` nor `text`: that option's label is `JSON.stringify(item)`. On `BbDropdown` it flags a hand-written group (`group: true`, no mapper) whose rows have neither `label` nor `text`, since hand-written rows are labelled by `label`: give each row one, or make it a mapped group (an `items` getter, or `itemText` / `itemValue`), which reads `label` / `text` and `value` by default. Setting `item-text` without `item-value` is a deliberate whole-object value and is not flagged, and string items never are. **Its reach is the same file only:** an inline `:items="[…]"`, or a top-level `const x = […]` (or `ref([…])` / `reactive([…])`) in the file's `<script setup>` bound as `:items="x"`. An imported array, a computed or a fetched list is not read, and `check` never guesses at one. Silence one site with `<!-- eslint-disable-next-line bitboss-ui/require-partner-prop -->`.
 
 **The manifest ships with the package** — `dist/ai/components.json` is inside
 the tarball, and the rules resolve it relative to their own file, so a normal
@@ -1892,10 +1918,14 @@ for it to quieten a `Bb*` name the library itself exports.
 
 `recommended` also enables **`bitboss-ui/no-unimported-component`**: a `.vue` file that uses a real library tag (`<BbTabs>`, or `<bb-tabs>`) that nothing resolves renders it as an empty custom element. A name counts as resolved when the file imports it (from `bitboss-ui`, a subpath, a barrel or a local file, under any alias) or binds it in a script (`const BbTabs = defineAsyncComponent(…)`), when a namespace import from `bitboss-ui` covers it, or when the project registers it globally: Nuxt's `.nuxt/components.d.ts`, any `.d.ts` adding to `GlobalComponents` (unplugin's `components.d.ts`), or `app.component('BbTabs', …)`. When it can't tell, it stays quiet: a Nuxt app with no generated `.nuxt/components.d.ts` yet, unplugin with `dts: false`, a registration loop over the library's exports. A name not in the manifest is `no-unknown-attributes`' (with a did-you-mean). `bitboss-ui check` reports the same finding as `unimported-component`.
 
+`recommended` also enables **`bitboss-ui/portal-names`** (error) and **`bitboss-ui/unused-portal`** (warning). A named portal is a string at the call site (`v-bb-hover-card="'person'"`, `v-bb-popover="{ portal: 'rename' }"`, `confirm({ portal: 'remove-member' })`) and a `<BbHoverCardPortal | BbPopoverPortal | BbConfirmPortal name>` in a template, so a typo opens nothing, silently. Both rules read the whole project once (tests skipped): `portal-names` reports a name no file declares, with a did-you-mean, and a name that belongs to the other family (a hover-card portal opened by `v-bb-popover`); `unused-portal` reports a declared portal no call site opens and no string in the project names. Only literals are judged: a `:name` binding, a name in a variable, a template literal or `confirm(options)` is never reported. `bitboss-ui check` reports the same findings as `unknown-portal`, `portal-family-mismatch` and `unused-portal` (a warning), in `.vue` and script files.
+
 `recommended` also enables **`bitboss-ui/text-null-value`**: a `v-model` on `BbTextInput` / `BbTextarea` bound to a `<script setup>` ref typed `string` (`ref('')`, `ref<string>('…')`, `shallowRef('')`) on a field whose null-value policy is `'null'`: its own `null-value="null"`, or no `null-value` and the app's `formControls` policy, read from the project's `bitboss-ui.d.ts`. Emptying the field writes `null` into a ref whose type says it can't hold one, and vue-tsc doesn't check a `v-model`'s write-back, so a later `name.value.trim()` passes the type check and throws once the user clears the field. The fix widens the declaration to `ref<string | null>(…)`, so vue-tsc then flags every read that assumed a string. The other way out is `null-value="string"` on the field (it emits `''`), which changes what the field emits, so it is left to you. A bound `:null-value`, a member expression (`v-model="form.name"`) and a ref imported from elsewhere are not reported. `bitboss-ui check` reports the same finding as `text-null-value`.
 
 `recommended` also enables **`bitboss-ui/form-model`**: `<BbForm>` takes the object it fills one way, `:model="draft"` — any reactive object (`reactive()`, `ref`, Pinia state, Inertia `useForm()`), written in place, never replaced. The rule fixes `v-model="…"` and `:model-value="…"` on `<BbForm>` to `:model="…"`, and reports without a fix an `@update:model-value` listener (the form emits none: `watch(draft, …, { deep: true })` or `useBbFormContext(id).values`) and a writable `computed` bound as the model (the form writes into what the getter returns and never calls the setter). `bitboss-ui check` reports the same finding as `form-v-model`.
 
+`recommended` also enables **`bitboss-ui/no-redundant-item-accessor`** (warn), with an autofix that deletes the attribute: an accessor that restates the option default. That covers `item-text="label"`, `item-text="text"` and `item-value="value"` (static or `:item-text="'label'"`, kebab or camel) on `BbSelect`, `BbSelectPopover`, `BbRadioGroup`, `BbCheckboxGroup` and `BbSwitchGroup`, and `itemText: 'label'` / `'text'` / `itemValue: 'value'` in a `BbDropdown` / `BbDropdownButton` group. It only reports what removing cannot change. `item-text="text"` is kept when any item also has `label` (the default would read `label`), and on items the file cannot see only `item-text="label"` and `item-value="value"` are reported. A visible item that is a primitive or lacks the field keeps its accessor. A dropdown group whose only mapper is the redundant one keeps it, since without it the group turns hand-written. `bitboss-ui check` reports the same finding as `redundant-item-accessor` (a warning).
+
 `recommended` also enables **`bitboss-ui/items-provider-context`** (error) and **`bitboss-ui/items-provider-reason`** (warn). Every `items` provider receives one context object, `({ query, reason, modelValue, signal })` (`query` only on `BbSelect`, `BbSelectPopover` and a `searchable` `BbDropdown` group). `items-provider-context` reports a positional provider bound to `:items` (an inline function, or a function / const in the same file; on `BbDropdown` / `BbDropdownButton` and in a `v-bb-dropdown` directive's value, each group's `items:`): two or more parameters, or one parameter typed `string` / `boolean` or named like a query or a prefill flag. Untyped, an old `(query) => …` reads the whole object as its query (`q=[object Object]`). Annotate it with its component's context type (`BbSelectItemsContext`, `BbTableItemsContext`, `BbCheckboxGroupItemsContext`, … `BbDropdownGroupItemsContext`); the message names the one to use. The fix, for untyped parameters, destructures by position: `(query, prefill, m)` → `({ query, reason, modelValue: m })`, each use of `prefill` rewritten as `reason !== 'search'`; a typed provider (vue-tsc already fails it), a group whose `searchable` is not a literal, and a body that already uses `reason` are reported without a fix. `items-provider-reason` warns when a provider compares `reason` with one cause other than `'search'` (`reason === 'initial'`; the causes are `'search'`, `'initial'`, `'dependencies'`, `'model'`, `'reopen'` and, on `BbTable`, `'pagination'`) or switches on it without a `default`: an id lookup that runs on one cause loses the selected labels on the others, so check `reason !== 'search'`. Imported providers are left to TypeScript. `bitboss-ui check` reports the same findings as `positional-provider` and `single-reason` (a warning).
 
 It also enables `bitboss-ui/require-partner-prop`: an opt-in prop set without its documented required partner — BbTable `keyboard-navigation` / `v-model:highlighted` without `row-class` (the shipped tint says "current row"; `row-class` says why, and is how you override it), `loading-text` without `:loading` bound, or `method` on BbButton / BbBadgeButton / BbBaseButton without `href` (only an `href` becomes an Inertia visit; `to` is a RouterLink) — compiles and mounts clean and just does nothing; the rule names the missing partner and quotes why.
@@ -2173,7 +2203,7 @@ compose it or write it yourself.
 | `useLiveFeed` / any polling or cross-tab feed helper                                             | Does not exist, and neither does a cross-tab helper — `useBroadcastChannelInstance` was removed (cross-tab messaging is not a UI concern). Use `useBroadcastChannel` from `@vueuse/core`; the polling and the merge are yours.                                                                                                                                                                                                                                                         |
 | `BbStepper` / `BbWizard`                                                                         | Does not exist as a component; the wizard-form recipe under `recipes/<platform>/wizard-form.md` ([Vue](https://llms-bitboss-ui.bitboss.it/dist/ai/recipes/vue/wizard-form.md) · [Nuxt](https://llms-bitboss-ui.bitboss.it/dist/ai/recipes/nuxt/wizard-form.md) · [Inertia](https://llms-bitboss-ui.bitboss.it/dist/ai/recipes/inertia/wizard-form.md)) composes one.                                                                                                                                                                                                                                           |
 | `BbSkeleton` (standalone)                                                                        | Only `BbTable` ships skeletons, via the column `skeleton` field.                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `BbWorkspaceSwitcher` / `BbTeamSwitcher` / `BbAccountSwitcher` / org, tenant or project switcher | Does not exist as a component — it is a [BbDropdown](https://llms-bitboss-ui.bitboss.it/dist/ai/BbDropdown.md) pattern: a row for the current record whose submenu is a `selectable` (single), `searchable`, fetched group bound to the current id with `<BbDropdownGroup v-model>`. Carry each record to the slots with `meta` (`itemProps: (w) => ({ meta: w })`) and draw it with `#<groupKey>:item:prepend`, so the other rows keep their icons. See BbDropdown.md § Rows that stand for records.                          |
+| `BbWorkspaceSwitcher` / `BbTeamSwitcher` / `BbAccountSwitcher` / org, tenant or project switcher | Does not exist as a component — it is a [BbDropdown](https://llms-bitboss-ui.bitboss.it/dist/ai/BbDropdown.md) pattern: a row for the current record whose submenu is a `selectable` (single), `searchable`, fetched group bound to the current id with `<BbDropdownGroup v-model>`. Carry each record to the slots with `meta` (`itemProps: (w) => ({ meta: w })`) and draw it with `#<groupId>:item:prepend`, so the other rows keep their icons. See BbDropdown.md § Rows that stand for records.                           |
 | `BbCommand` / command palette                                                                    | Does not exist. Compose `BbDialog` + `BbSelectPopover` — do not hand-roll the search: [BbSelectPopover § A ⌘K command palette](https://llms-bitboss-ui.bitboss.it/dist/ai/BbSelectPopover.md#a-k-command-palette) is the worked example (⌘K / Ctrl+K, grouped server results, debouncing and race protection from the popover, navigation per platform).                                                                                                                                                                       |
 | `BbSeatMap` / `BbSeatPicker` / `BbSeatGrid` / a seat map, desk or parking-bay picker             | Does not exist, on purpose (a niche need), and there is no recipe for it. Build it in your app as a WAI-ARIA grid with one tab stop (roving `tabindex`, arrow keys move between positions) styled with the library tokens; do not give every seat its own tab stop.                                                                                                                                                                                                                    |
 | `BbCalendar` as a scheduling / events view                                                       | [BbCalendar](https://llms-bitboss-ui.bitboss.it/dist/ai/BbCalendar.md) is the picker's calendar rendered in place — a value control (day, range, set, month, year, datetime), not an events grid. Put per-day content in its `#day` / `#day:append` slots; an agenda or booking board is your own layout around it.                                                                                                                                                                                                            |
@@ -2192,13 +2222,13 @@ recipe under `recipes/<platform>/layout-scaffold.md` ([Vue](https://llms-bitboss
 
 ## Item-Driven Components
 
-The following components accept an `items` prop (array or async provider function) with `item-text`/`item-value` mapping. Consult the items playbooks before wiring them:
+The following components accept an `items` prop (array or async provider function): object items are read through their own `label` (else `text`) and `value`, or through `item-text`/`item-value` when your fields are named otherwise. Consult the items playbooks before wiring them:
 
 - [BbSelect](https://llms-bitboss-ui.bitboss.it/dist/ai/BbSelect.md), [BbSelectPopover](https://llms-bitboss-ui.bitboss.it/dist/ai/BbSelectPopover.md)
 - [BbCheckboxGroup](https://llms-bitboss-ui.bitboss.it/dist/ai/BbCheckboxGroup.md), [BbRadioGroup](https://llms-bitboss-ui.bitboss.it/dist/ai/BbRadioGroup.md), [BbSwitchGroup](https://llms-bitboss-ui.bitboss.it/dist/ai/BbSwitchGroup.md)
 - [BbTable](https://llms-bitboss-ui.bitboss.it/dist/ai/BbTable.md)
 
-`BbDropdown`, `BbBreadcrumbs`, `BbTabs`, and `BbTree` are also declared through `items`, but with typed item objects (label/key/href/…) rather than arbitrary domain objects. `BbDropdown` bridges the two: a fetched group maps domain objects through `itemText` / `itemValue` / `itemProps`, and any row carries its domain object to the slots in `meta`.
+`BbDropdown`, `BbBreadcrumbs`, `BbTabs`, and `BbTree` are also declared through `items`, but with typed item objects (`value`/`label`/`href`/…) rather than arbitrary domain objects. `BbDropdown` bridges the two: a fetched group reads `label` / `value` like the pickers, or maps domain objects through `itemText` / `itemValue` / `itemProps`, and any row carries its domain object to the slots in `meta`.
 
 See:
 

package/dist/llms.txt

@@ -5,7 +5,7 @@
 ## AI Knowledge Base
 
 - [Core knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-medium.txt): **Fetch this if you can only fetch one file** — hard rules, setup, component picker, design language, and the full component catalogue in ~250 KB.
-- [Complete knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-full.txt): Everything concatenated (~5.8 MB). Bulk ingestion only — too large to prompt with.
+- [Complete knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-full.txt): Everything concatenated (~5.9 MB). Bulk ingestion only — too large to prompt with.
 - [AI Router](ai/guides/ai-router.md): **Start here** — tiny hop map for any coding agent (which file to open next).
 - [Component index](ai/index.md): Full component catalogue with agent rules, grouped by category. Each entry links a typed contract (props/events/slots/v-model).
 - [Component API files](ai/manifest/index.json): Machine-readable API, one JSON file per component (`manifest/components/<Name>.json`: every prop, event, slot, v-model and pt part, one per line, plus the public types it uses) — open the index, then the one component. The same data in one ~1.2 MB file for tools is [components.json](ai/components.json); its `types` array lists the public TYPE exports with a `usage` tier (`api` = the ones you reach for) and, on the `api` ones, a `usedBy` array naming the component and prop or event each is the type OF — `BbTableColumn` is `usedBy` `BbTable.columns`, a value you pass, not a tag you write. This file is props and events, not paint.
@@ -33,18 +33,18 @@
 - [Migration v2→v3: BbAlert](ai/guides/migration/components/bb-alert.md): showClose inverted to hideClose, theme replaced by typed variant.
 - [Migration v2→v3: BbAvatar](ai/guides/migration/components/bb-avatar.md): The color prop is removed — retheme the fallback through the --bg / --fg locals.
 - [Migration v2→v3: BbBadge (and where your v2 badges went)](ai/guides/migration/components/bb-badge.md): The v2 BbBadge (floating count/dot) is now BbIndicator; the v3 BbBadge is a new inline pill that also replaces BbChip.
-- [Migration v2→v3: BbBreadcrumbs](ai/guides/migration/components/bb-breadcrumbs.md): Item keys must be strings, the text divider prop is gone, per-item slot names are normalized.
+- [Migration v2→v3: BbBreadcrumbs](ai/guides/migration/components/bb-breadcrumbs.md): Items are { label, value } (were { key, text }), the text divider prop is gone, per-item slot names are normalized.
 - [Migration v2→v3: BbButton](ai/guides/migration/components/bb-button.md): Async click handlers now auto-track loading (behavior flip), built-in tooltip props removed, variant locked to the registry. Leftover v2 --border-color on .bb-button* still paints.
 - [Migration v2→v3: BbCheckbox / BbRadio / BbSwitch](ai/guides/migration/components/bb-checkbox.md): reverse polarity inverted (explicit values flip, default layout unchanged), checked narrowed to boolean, color removed, BbRadio's name no longer required.
-- [Migration v2→v3: BbCheckboxGroup / BbRadioGroup / BbSwitchGroup](ai/guides/migration/components/bb-checkbox-group.md): labelPosition renamed legendPosition, per-item disabled is now inert (use selectable), color and the option affix slots removed, BbRadioGroup's name no longer required, the shared bb-cr-container CSS block split into one per group, and the --bb-checkbox-* / --bb-radio-* / --bb-switch-* globals replaced by glyph locals.
+- [Migration v2→v3: BbCheckboxGroup / BbRadioGroup / BbSwitchGroup](ai/guides/migration/components/bb-checkbox-group.md): labelPosition renamed legendPosition, per-item disabled is now inert (use selectable), color and the option affix slots removed, BbRadioGroup's name no longer required, the shared bb-cr-container CSS block split into one per group, and the --bb-checkbox-* / --bb-radio-* / --bb-switch-* globals replaced by glyph locals, and object items now read their own label / value by default.
 - [Migration v2→v3: BbChip (removed)](ai/guides/migration/components/bb-chip.md): BbChip is gone — BbBadge with clearable is the replacement; non-clearable chips were badges all along.
 - [Migration v2→v3: BbCollapsible](ai/guides/migration/components/bb-collapsible.md): `tag` narrows to `'span' | 'div'` and defaults to `span`; the inner element mirrors it.
 - [Migration v2→v3: BbColorInput](ai/guides/migration/components/bb-color-input.md): picker renamed to eyeDropper.
 - [Migration v2→v3: BbColorPalette](ai/guides/migration/components/bb-color-palette.md): flip inverted to disableFlip, showArrow removed, picker renamed eyeDropper, update:open dropped, model updates never emit null.
 - [Migration v2→v3: BbDatePickerInput](ai/guides/migration/components/bb-date-picker-input.md): allowWriting inverted to disableWriting and hidePopover renamed to disableCalendar, both with a changed token set; the width prop is removed; adaptive mobile sheet by default; non-floating output carries the local offset instead of UTC `Z` (new `utc` prop restores v2 output).
 - [Migration v2→v3: BbDialog](ai/guides/migration/components/bb-dialog.md): showClose inverted to hideClose, #close removed (description restored in beta.19), default widths changed, adaptive bottom sheet on mobile by default, --bb-dialog-* tokens replaced by --bb-panel-p plus locals.
-- [Migration v2→v3: BbDropdown](ai/guides/migration/components/bb-dropdown.md): Items now expect text as the label and can carry variants/submenus; arrowPadding removed; adaptive mobile sheet on by default.
-- [Migration v2→v3: BbDropdownButton](ai/guides/migration/components/bb-dropdown-button.md): autoLoading renamed to disableAutoLoading, disabledWhileLoading and theme removed.
+- [Migration v2→v3: BbDropdown](ai/guides/migration/components/bb-dropdown.md): 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.
+- [Migration v2→v3: BbDropdownButton](ai/guides/migration/components/bb-dropdown-button.md): autoLoading renamed to disableAutoLoading, disabledWhileLoading and theme removed; items are { label, value } rows like BbDropdown's.
 - [Migration v2→v3: BbDropzone](ai/guides/migration/components/bb-dropzone.md): modelValue is typed, accept no longer throws and takes bare tokens, and the hidden native-submit input only renders when name is set.
 - [Migration v2→v3: BbIcon](ai/guides/migration/components/bb-icon.md): The required prop is renamed type→icon, color is removed, and the xxl size key becomes 2xl.
 - [Migration v2→v3: BbIntersection](ai/guides/migration/components/bb-intersection.md): Removed with no replacement — it wrapped IntersectionObserver and carried no styling; use @vueuse/core's useIntersectionObserver.
@@ -53,14 +53,14 @@
 - [Migration v2→v3: BbPopover](ai/guides/migration/components/bb-popover.md): Built-in close button, restoreFocus, theme, and the arrow are gone; close affordances move into your content.
 - [Migration v2→v3: BbRadioGroup](ai/guides/migration/components/bb-radio-group.md): Shares its migration with BbCheckboxGroup — see bb-checkbox-group.md.
 - [Migration v2→v3: BbRating](ai/guides/migration/components/bb-rating.md): color removed; name no longer required; the star classes moved from .bb-base-rating to the .bb-rating block (--highlighted became --filled/--empty); --bb-rating-size demoted to a local --size on .bb-rating__stars; input-position finally works.
-- [Migration v2→v3: BbSelect](ai/guides/migration/components/bb-select.md): allowWriting inverted to disableWriting, filterBy narrowed to string[], prefill value renamed, chevron/options slots removed, and two behavior changes (second click, mount-time coherence).
+- [Migration v2→v3: BbSelect](ai/guides/migration/components/bb-select.md): 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).
 - [Migration v2→v3: BbSelectPopover](ai/guides/migration/components/bb-select-popover.md): flip and allowWriting inverted, arrow props removed, filterBy narrowed, options slots replaced by header/footer; shares BbSelect's behavior changes.
 - [Migration v2→v3: BbSlider](ai/guides/migration/components/bb-slider.md): thumbTranslate inverted to disableThumbTranslate; string model values and color removed.
 - [Migration v2→v3: BbSmoothHeight](ai/guides/migration/components/bb-smooth-height.md): The `tag` prop is narrowed to `div | span`, and the inner measuring element now mirrors it instead of always being a `<div>`.
 - [Migration v2→v3: BbSpinner](ai/guides/migration/components/bb-spinner.md): The color prop is removed; spinners follow currentColor.
 - [Migration v2→v3: BbSwitchGroup](ai/guides/migration/components/bb-switch-group.md): Shares its migration with BbCheckboxGroup — see bb-checkbox-group.md.
 - [Migration v2→v3: BbTable](ai/guides/migration/components/bb-table.md): The table renders as a CSS grid of divs with ARIA roles, not a <table> — every element selector (table/thead/tbody/tr/th/td) under .bb-table matches nothing, #thead/#tbody/#tfoot take role-complete div rows, --fill/--natural-width are gone, column widths drift within documented bounds, copy-to-spreadsheet and print header repetition degrade; allowSelectAll inverted to disableSelectAll; loading no longer blanks populated tables and now inerts rows; #loading is first-load-only; #empty fills a full-width cell instead of replacing the row; row events drop the selected argument; columns gained sortable + rowClass, which collide with same-named consumer fields.
-- [Migration v2→v3: BbTabs (was BbTab)](ai/guides/migration/components/bb-tabs.md): 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.
+- [Migration v2→v3: BbTabs (was BbTab)](ai/guides/migration/components/bb-tabs.md): 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.
 - [Migration v2→v3: BbTag](ai/guides/migration/components/bb-tag.md): modelValue is strictly string[] now, multiple is removed, and duplicates are rejected case-insensitively by default.
 - [Migration v2→v3: BbTextInput](ai/guides/migration/components/bb-text-input.md): The type prop narrows to the text-like input types — number/date values must move to their dedicated components; a bare `floating` attribute was never a prop, the spelling is label-mode="floating".
 - [Migration v2→v3: BbToast and toast()](ai/guides/migration/components/bb-toast.md): Host placement becomes position with a corner-based value set; toast() options rewritten (variant, duration, actions, portal).

package/dist/locale-blueprint.json

@@ -2,9 +2,12 @@
 	"builtins": [
 		"cs",
 		"da",
+		"de-CH",
 		"de",
 		"el",
+		"en-GB",
 		"en",
+		"es-MX",
 		"es",
 		"fi",
 		"fr",
@@ -15,13 +18,16 @@
 		"nb",
 		"nl",
 		"pl",
-		"pt",
+		"pt-BR",
+		"pt-PT",
 		"ro",
 		"ru",
 		"sv",
 		"tr",
 		"uk",
-		"zh-cn"
+		"zh-CN",
+		"zh-HK",
+		"zh-TW"
 	],
 	"template": {
 		"common": {
@@ -29,18 +35,16 @@
 			"loadingText": "Loading...",
 			"emptyText": "No data to display",
 			"failedText": "Couldn't load items",
-			"clearLabel": "Reset selected value",
+			"clearLabel": "Clear value",
 			"fieldLabel": "This field"
 		},
 		"colorInput": {
 			"dialogLabel": "Color picker",
 			"openPicker": "Open color picker",
 			"openPickerSelected": "Open color picker, current color: {0}",
-			"paletteLabel": "Select a color from the palette",
 			"mainCanvasDesc": "Use the arrows to select a color",
 			"mainCanvasSelectedColor": "Selected color: {0}",
 			"hueCanvasDesc": "Use the arrows to select a hue",
-			"hueCanvasSelectedHue": "Selected hue: {0}",
 			"alphaSliderDesc": "Use the arrows to adjust opacity",
 			"eyeDropper": "Pick color from screen"
 		},
@@ -66,11 +70,11 @@
 		"datePickerInput": {
 			"dateFormat": "Date format",
 			"dateFormatSingle": "MM/DD/YYYY",
-			"dateFormatRange": "MM/DD/YYYY - MM/DD/YYYY",
+			"dateFormatRange": "MM/DD/YYYY – MM/DD/YYYY",
 			"monthFormatSingle": "MM/YYYY",
-			"monthFormatRange": "MM/YYYY - MM/YYYY",
+			"monthFormatRange": "MM/YYYY – MM/YYYY",
 			"yearFormatSingle": "YYYY",
-			"yearFormatRange": "YYYY - YYYY",
+			"yearFormatRange": "YYYY – YYYY",
 			"emptyRange": "Select a range",
 			"changeSelectionRange": "Change selection, from {0} to {1}",
 			"changeSelection": "Change selection, {0}",
@@ -96,8 +100,7 @@
 			"back": "Back"
 		},
 		"dropdownButton": {
-			"open": "Open menu",
-			"close": "Close menu"
+			"open": "Open menu"
 		},
 		"dropzone": {
 			"selectFiles": "Select files",
@@ -123,7 +126,7 @@
 		},
 		"breadcrumbs": {
 			"label": "Breadcrumbs",
-			"openHiddenLabelCount": "Show {0} hidden breadcrumbs"
+			"openHiddenLabelCount": "Show hidden breadcrumbs ({0})"
 		},
 		"pagination": {
 			"label": "Pagination",
@@ -141,11 +144,11 @@
 			"actionsText": "Actions",
 			"selectAllLabel": "Select all items on this page",
 			"selectText": "Select an item",
-			"select": "Select",
+			"select": "Select {0}",
 			"selectableLegend": "Select items",
 			"reorderInstructions": "Use the left and right arrow keys to move between columns; hold Shift to move the column, with Home and End for the ends. Enter sorts a sortable column.",
 			"columnMoved": "{0} moved to position {1} of {2}",
-			"resizeInstructions": "Alt + left or right arrow resizes the column; double-click its edge to restore the declared width."
+			"resizeInstructions": "Alt + left or right arrow resizes the column; double-click its edge to restore the default width."
 		},
 		"timePickerInput": {
 			"emptySelection": "Select a time",