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

package/dist/ai/guides/inertia-helpers.md

@@ -6,10 +6,14 @@ summary: App-side toolkit for Laravel + Inertia apps — typed page props, lazy
 # Inertia Helpers
 
 A curated toolkit of composables for **Laravel + Inertia (Vue 3)** apps built
-on bitboss-ui. These are _app-side_ code: copy the ones you need into your
-project (conventionally `src/composables/`) — they are not exported by the
-`bitboss-ui` package. The [Inertia recipes](../recipes/inertia/records-workspace.md)
-assume this toolkit.
+on bitboss-ui. These are _app-side_ code, not exported by the `bitboss-ui`
+package: one folder, `inertia-helpers/`, that lives in your app
+(`resources/js/composables/inertia-helpers/` in a Laravel app). Inside it the
+files import each other by relative path (`./utils`, `./useQuery`), so the
+folder works wherever it sits and never touches your own `@/utils` or
+`@/types`. Pages import from it by path:
+`import { useQuery } from '@/composables/inertia-helpers/useQuery'`. The
+[Inertia recipes](../recipes/inertia/records-workspace.md) assume this toolkit.
 
 Why it exists: in Inertia there is no client data layer — data arrives as
 **page props** and changes through **visits**. These helpers give that model
@@ -18,14 +22,67 @@ filters live in the URL, paginated data and selection are shared through
 keyed contexts instead of prop drilling, and forms return promises that
 bitboss-ui buttons and dialogs can await.
 
-Copying this toolkit pulls in real npm dependencies beyond the app's own
-`@inertiajs/vue3`/`vue` — install them explicitly rather than relying on them
-already being hoisted transitively through `bitboss-ui`'s own `dependencies`
-(that works today by npm hoisting luck, and breaks under pnpm/Yarn PnP or the
-next time `bitboss-ui` changes what it depends on):
+## Install: `npx bitboss-ui add`
 
+Install a helper with the CLI, from the app root. Never paste one from this
+guide:
+
+```sh
+npx bitboss-ui add useQueryObject useTableContext
+npx bitboss-ui add --all           # the whole toolkit
+npx bitboss-ui helpers list        # every id, what it does, its state here
 ```
-npm i @vueuse/core @vueuse/shared object-code query-string
+
+`add` copies each named helper and every file it imports into
+`resources/js/composables/inertia-helpers/` (`src/composables/inertia-helpers/`
+outside a Laravel layout, or `--dir <path>` on the first run) and records them
+in `bitboss-ui.lock.json` at the app root. Commit both the folder and the lock.
+`add` never changes a file that already exists. It prints the import line for
+each helper and the install command for any npm package the app lacks; it
+never runs it. `--dry-run` shows the plan and writes nothing. The app must be
+TypeScript with `moduleResolution: "bundler"`; JavaScript apps are refused.
+
+The files are yours, so edit them freely:
+
+- **Formatting never counts as an edit**, and neither do comments: your
+  formatter can reformat the folder, and nothing needs to be excluded from it.
+  Any code change does count, including one made by a linter's `--fix`.
+- **`npm update bitboss-ui` does not change your copies.** After an upgrade
+  run `npx bitboss-ui helpers diff`, then `npx bitboss-ui helpers update`. It
+  replaces only the files that still hold an older bitboss-ui version and
+  keeps every file you edited.
+- **Comments are not edits, so `helpers update` replaces a file whose only
+  change is a comment, and the comment is lost.** `helpers diff` and
+  `helpers update --dry-run` mark those files `your comments differ`; copy
+  any comment you want to keep before updating.
+- If you edited a file that bitboss-ui also changed, `update` leaves that
+  group of helpers alone and says so; `npx bitboss-ui helpers diff <id>` shows
+  both sides. To take bitboss-ui's version over your edit, delete the file and
+  run `add` again. There is no `--force`.
+- To uninstall a helper, delete its file and remove its id from `ids` in the
+  lock. Shared files (`utils.ts`, `types.ts`) stay while another helper uses
+  them.
+
+Run the app's own copy of the CLI. `add` refuses to run as a bitboss-ui other
+than the one in `node_modules` (npm's `latest` tag is still v2), and prints
+the command to use instead (`npm exec -- bitboss-ui add …`,
+`pnpm exec bitboss-ui add …`).
+
+**Coming from hand-copied helpers** (an older version of this guide had you
+paste them into `src/composables/` with `@/utils` imports): run `add` for the
+helpers you use, switch your pages' imports to
+`@/composables/inertia-helpers/<name>`, then delete the old copies once
+nothing imports them. Your own `@/utils` and `@/types` stay yours. If the app
+auto-imports `composables/**`, exclude one of the two trees until the old
+copies are gone, or both export `useQuery`.
+
+The helpers need these npm packages beyond the app's own
+`@inertiajs/vue3`/`vue` (`add` prints the ones a helper needs). Install them
+explicitly rather than relying on them being hoisted through `bitboss-ui`'s own
+`dependencies`, which breaks under pnpm and Yarn PnP:
+
+```
+npm i @vueuse/core object-code query-string
 npm i -D @inertiajs/core
 ```
 
@@ -33,17 +90,16 @@ npm i -D @inertiajs/core
 (`usePaginatedResponseContext`, `useTableSelectionContext`, `useTableContext`,
 `usePageShellContext`) and `useDeleteCmd`/`useScreenSizes`; `object-code`
 powers the `isEqual` hash-comparison utility below; `query-string` backs
-`useQuery`/`useRouteQuery`/`useQueryObject`; `@vueuse/shared` supplies
-`createSharedComposable` to `useScreenSizes`; `@inertiajs/core` is a type-only
+`useQuery`/`useRouteQuery`/`useQueryObject`; `@inertiajs/core` is a type-only
 import (`PageProps` in `usePaginatedResponseContext`) that `@inertiajs/vue3`
-does not re-export, so a strict pnpm app fails to type-check without it. A few
-tiny utilities are assumed
-under `@/utils` and defined below.
+does not re-export, so a strict pnpm app fails to type-check without it. The
+helpers' shared types and tiny utilities are two files of the folder,
+`types.ts` and `utils.ts`, below.
 
 ## Shared types and utilities
 
 ```ts
-// src/types/index.ts
+// inertia-helpers/types.ts
 // the Laravel paginator shape and base page props
 export type PaginatedResponse<T> = {
 	data: T[];
@@ -69,7 +125,7 @@ below before wiring a paginated prop — passing a raw paginator straight
 through leaves `meta` `undefined` and the composable silently reads zeros.
 
 ```ts
-// src/utils/index.ts
+// inertia-helpers/utils.ts
 // micro-utilities the helpers share
 import { hash } from 'object-code';
 
@@ -113,7 +169,7 @@ again: a persistent layout or a store that keeps reading a prop the new page
 doesn't share still fails loudly, one tick later.
 
 ```ts
-// src/composables/useProp.ts
+// inertia-helpers/useProp.ts
 import { usePage } from '@inertiajs/vue3';
 import { computed, nextTick, ref, type ComputedRef } from 'vue';
 
@@ -187,8 +243,8 @@ when the data lands. `loading`/`loaded`/`error` expose the fetch state;
 `execute()` forces the load imperatively.
 
 ```ts
-// src/composables/useLazyProp.ts
-import { isEqual, isNil, isNotNil } from '@/utils';
+// inertia-helpers/useLazyProp.ts
+import { isEqual, isNil, isNotNil } from './utils';
 import { router, usePage } from '@inertiajs/vue3';
 import type { Ref } from 'vue';
 import { customRef, onBeforeUnmount, readonly, ref, watch } from 'vue';
@@ -245,7 +301,7 @@ export function useLazyProp<T>(
 			router.reload({
 				only: [propName],
 				replace: true,
-				headers: options.headers,
+				...(options.headers ? { headers: options.headers } : {}),
 				onStart: () => {
 					loading.value = true;
 				},
@@ -352,12 +408,9 @@ loads on first demand (e.g. when the select opens) instead of inflating the
 initial page load.
 
 ```ts
-// src/composables/useLazyPropGetter.ts
-import {
-	useLazyProp,
-	type UseLazyPropOptions,
-} from '@/composables/useLazyProp';
-import { isNil } from '@/utils';
+// inertia-helpers/useLazyPropGetter.ts
+import { useLazyProp, type UseLazyPropOptions } from './useLazyProp';
+import { isNil } from './utils';
 import type { Ref } from 'vue';
 
 export type UseLazyPropGetter<U> = {
@@ -438,7 +491,7 @@ Parses the current page URL's query string into an object. Snapshot, not
 reactive — used by the writers below.
 
 ```ts
-// src/composables/useQuery.ts
+// inertia-helpers/useQuery.ts
 // requires: npm i query-string
 import { usePage } from '@inertiajs/vue3';
 import qs, { type StringifyOptions } from 'query-string';
@@ -478,7 +531,7 @@ server re-renders with the new value. Writing the current value is a no-op —
 safe to sync from server responses without visit loops.
 
 ```ts
-// src/composables/useRouteQuery.ts
+// inertia-helpers/useRouteQuery.ts
 // requires: npm i query-string
 import { router, usePage } from '@inertiajs/vue3';
 import qs from 'query-string';
@@ -516,7 +569,7 @@ export function useRouteQuery<T = string>(
 			const nextRaw = String(next);
 			if (nextRaw === readRaw()) return;
 
-			const [path, queryString = ''] = page.url.split('?');
+			const [path = '', queryString = ''] = page.url.split('?');
 			const query = qs.parse(queryString);
 			if (nextRaw === defaultValue) {
 				delete query[key]; // keep URLs clean at the default
@@ -542,10 +595,10 @@ seen are cleaned up when they empty out; the `page` parameter resets on
 every filter change so results are never hidden on an out-of-range page.
 
 ```ts
-// src/composables/useQueryObject.ts
+// inertia-helpers/useQueryObject.ts
 // requires: npm i query-string
-import { useQuery } from '@/composables/useQuery';
-import { isEmpty, isNil } from '@/utils';
+import { useQuery } from './useQuery';
+import { isEmpty, isNil } from './utils';
 import { router, usePage } from '@inertiajs/vue3';
 import qs, { type StringifyOptions } from 'query-string';
 import { toValue, watch, type MaybeRefOrGetter } from 'vue';
@@ -716,10 +769,10 @@ context: `items` (editable until next navigation), `totalItems`,
 visit the context re-syncs from the fresh prop.
 
 ```ts
-// src/composables/usePaginatedResponseContext.ts
-import { useRouteQuery } from '@/composables/useRouteQuery';
-import type { PaginatedResponse } from '@/types';
-import { isNotNil } from '@/utils';
+// inertia-helpers/usePaginatedResponseContext.ts
+import { useRouteQuery } from './useRouteQuery';
+import type { PaginatedResponse } from './types';
+import { isNotNil } from './utils';
 import type { PageProps } from '@inertiajs/core';
 import { router, usePage } from '@inertiajs/vue3';
 import { injectLocal, provideLocal } from '@vueuse/core';
@@ -755,7 +808,9 @@ export const usePaginatedResponseContext = <T = object>(
 	// either way, augmented or not.
 	const paginated = computed(
 		() =>
-			usePage<PageProps & Record<string, PaginatedResponse<T>>>().props[dataKey]
+			usePage<PageProps & Record<string, PaginatedResponse<T>>>().props[
+				dataKey
+			] as PaginatedResponse<T>
 	);
 
 	const items = ref<T[]>(paginated.value.data ?? []) as Ref<T[]>;
@@ -863,8 +918,8 @@ combines `all` + `unselected` instead). Bind these to `BbTable`'s
 `v-model`, `v-model:unselected-items` and `v-model:select-all`.
 
 ```ts
-// src/composables/useTableSelectionContext.ts
-import { isNotNil } from '@/utils';
+// inertia-helpers/useTableSelectionContext.ts
+import { isNotNil } from './utils';
 import { injectLocal, provideLocal } from '@vueuse/core';
 import { ref, type Ref } from 'vue';
 
@@ -921,16 +976,16 @@ what the [Inertia CRUD listing recipe](../recipes/inertia/records-workspace.md)
 builds on.
 
 ```ts
-// src/composables/useTableContext.ts
+// inertia-helpers/useTableContext.ts
 import {
 	usePaginatedResponseContext,
 	type PaginatedResponseContext,
-} from '@/composables/usePaginatedResponseContext';
+} from './usePaginatedResponseContext';
 import {
 	useTableSelectionContext,
 	type TableSelectionContext,
-} from '@/composables/useTableSelectionContext';
-import { isNotNil } from '@/utils';
+} from './useTableSelectionContext';
+import { isNotNil } from './utils';
 import { injectLocal, provideLocal } from '@vueuse/core';
 
 export type TableContext<T, U> = TableSelectionContext<U> &
@@ -1002,8 +1057,8 @@ are. The same applies to any nested shape (a line-item row, say). It is a
 TypeScript quirk, not a statement about your data.
 
 ```ts
-// src/composables/usePromiseForm.ts
-import { useLoading } from '@/composables/useLoading';
+// inertia-helpers/usePromiseForm.ts
+import { useLoading } from './useLoading';
 import {
 	useForm,
 	type InertiaForm,
@@ -1102,7 +1157,7 @@ export type NullableKeys<T> = {
 ```
 
 ```ts
-import { usePromiseForm } from '@/composables/usePromiseForm';
+import { usePromiseForm } from '@/composables/inertia-helpers/usePromiseForm';
 import type { NullableKeys } from '@/types/nullable-keys';
 import type { InvoiceRequest } from '@/types';
 
@@ -1126,8 +1181,8 @@ state is not a single Inertia form (multiple forms, ad-hoc refs). For a
 single `usePromiseForm`, prefer the built-in `form.isDirty`.
 
 ```ts
-// src/composables/useHasChanged.ts
-import { isEqual } from '@/utils';
+// inertia-helpers/useHasChanged.ts
+import { isEqual } from './utils';
 import { computed, ref, toValue, type WatchSource } from 'vue';
 
 export function useHasChanged<T extends WatchSource<unknown>[]>(
@@ -1173,7 +1228,7 @@ whitelisted action carry the `X-Whitelisted-Action` header so a saving
 visit's redirect is never blocked by its own guard.
 
 ```ts
-// src/composables/useConfirmOnRouteLeave.ts
+// inertia-helpers/useConfirmOnRouteLeave.ts
 import { router } from '@inertiajs/vue3';
 import { useConfirm } from 'bitboss-ui';
 import { onScopeDispose, toValue, type MaybeRefOrGetter } from 'vue';
@@ -1287,7 +1342,7 @@ Wraps any async function with a concurrent-safe `loading` flag (a counter,
 so overlapping calls don't flicker it off early).
 
 ```ts
-// src/composables/useLoading.ts
+// inertia-helpers/useLoading.ts
 import { computed, ref } from 'vue';
 
 export const useLoading = <TArgs extends unknown[], TResult>(
@@ -1317,8 +1372,8 @@ per run, auto-abort of the previous run on re-execute, and abort on
 unmount.
 
 ```ts
-// src/composables/useAsyncFn.ts
-import { isPlainObject } from '@/utils';
+// inertia-helpers/useAsyncFn.ts
+import { isPlainObject } from './utils';
 import {
 	onBeforeMount,
 	onBeforeUnmount,
@@ -1408,8 +1463,7 @@ export function useAsyncFn<T>(
 				error.value = new Error(err);
 			} else if (isPlainObject(err)) {
 				// Laravel validation bag: surface the first message.
-				const firstKey = Object.keys(err)[0];
-				error.value = new Error(String(err[firstKey]));
+				error.value = new Error(String(Object.values(err)[0]));
 			}
 		} finally {
 			loading.value = false;
@@ -1438,9 +1492,9 @@ changes, resets to `null` when the id clears, exposes `loading` and
 it the highlighted row's id.
 
 ```ts
-// src/composables/useResourceContext.ts
-import { useLoading } from '@/composables/useLoading';
-import { noop } from '@/utils';
+// inertia-helpers/useResourceContext.ts
+import { useLoading } from './useLoading';
+import { noop } from './utils';
 import { ref, toValue, watch, type MaybeRefOrGetter, type Ref } from 'vue';
 
 type UseResourceContextOptions<T, ID> = {
@@ -1533,7 +1587,7 @@ contenteditable is focused. Pairs with table selection: select rows, hit
 Delete, dispatch the same confirm-guarded bulk action as the button.
 
 ```ts
-// src/composables/useDeleteCmd.ts
+// inertia-helpers/useDeleteCmd.ts
 import { useMagicKeys, whenever } from '@vueuse/core';
 import { toValue, type MaybeRefOrGetter } from 'vue';
 
@@ -1560,8 +1614,8 @@ export function useDeleteCmd(
 		if (!toValue(options.disabled)) onDelete();
 	};
 
-	whenever(keys['delete'], handleDelete);
-	whenever(keys['backspace'], handleDelete);
+	whenever(() => keys['delete']?.value, handleDelete);
+	whenever(() => keys['backspace']?.value, handleDelete);
 }
 ```
 
@@ -1571,9 +1625,8 @@ Shared reactive breakpoints aligned with Tailwind `md`/`lg` — one window
 listener for the whole app via `createSharedComposable`.
 
 ```ts
-// src/composables/useScreenSizes.ts
-import { useWindowSize } from '@vueuse/core';
-import { createSharedComposable } from '@vueuse/shared';
+// inertia-helpers/useScreenSizes.ts
+import { createSharedComposable, useWindowSize } from '@vueuse/core';
 import { computed } from 'vue';
 
 /** Tailwind md breakpoint (px). Mobile when width < 768. */
@@ -1603,7 +1656,7 @@ Index an item list by key for O(1) lookups — e.g. mapping the ids in a
 selection context back to full rows for a bulk-action payload.
 
 ```ts
-// src/composables/useIndexById.ts
+// inertia-helpers/useIndexById.ts
 import { computed, unref, type MaybeRef } from 'vue';
 
 type Options<TItem> = {
@@ -1634,8 +1687,8 @@ A ref that flips once, the first time a condition becomes true, then stops
 watching — for one-shot reveals ("has ever loaded", onboarding hints).
 
 ```ts
-// src/composables/useUntil.ts
-import { noop } from '@/utils';
+// inertia-helpers/useUntil.ts
+import { noop } from './utils';
 import { ref, toValue, watch, type MaybeRefOrGetter } from 'vue';
 
 type Options<T, U> = {

package/dist/ai/guides/installation-and-plugin-setup.md

@@ -955,9 +955,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.
 
@@ -989,8 +990,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:
@@ -1016,18 +1017,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.
@@ -1241,7 +1267,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
@@ -1299,10 +1325,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.

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

@@ -1,6 +1,6 @@
 ---
 title: 'Migration v2→v3: BbBreadcrumbs'
-summary: Item keys must be strings, the text divider prop is gone, per-item slot names are normalized.
+summary: Items are { label, value } (were { key, text }), the text divider prop is gone, per-item slot names are normalized.
 ---
 
 # BbBreadcrumbs — v2 → v3
@@ -16,12 +16,13 @@ summary: Item keys must be strings, the text divider prop is gone, per-item slot
 | —                                                                                                                                                      | item `prepend:icon` / `append:icon`, per-key `:prepend`/`:append` slots, overflow forwarding                                                                                                                                                                       | additive                                                                                                                                                                                                                                                                                                                                                                                                     |
 | _(v3 prereleases only)_ glyphs and `item:prepend` / `item:append` content beside the crumb's link, both inside `.bb-breadcrumbs__breadcrumb-container` | inside the link (`.bb-breadcrumbs__breadcrumb > .bb-breadcrumbs__item-icon`), which is now the item's direct child; the label is wrapped in `.bb-breadcrumbs__text`; `.bb-breadcrumbs__breadcrumb-container` no longer exists (nor around the overflow `…` button) | DOM + behaviour: the whole crumb is the click target. Any rule on `.bb-breadcrumbs__breadcrumb-container` matches nothing. The hover colour and the disabled fade moved from the link to `.bb-breadcrumbs__text`, so a rule on `.bb-breadcrumbs__breadcrumb:disabled { opacity }` now also fades the glyphs. Slot content inside the link joins its accessible name — mark decorative content `aria-hidden`. |
 | the last crumb is the current page by position (`aria-current="page"`, bold), even with an `href` / `to` / `onClick`                                   | only a last crumb **without** a target is the current page; one with a target is an ordinary working link, flat                                                                                                                                                    | **⚠ silent** behaviour: a trail ending on a linked crumb loses its bold current page. Drop the target from the last crumb to keep it; keep the target when the trail lists ancestors only                                                                                                                                                                                                                    |
+| item `{ key, text }` (v2, and v3 up to beta.48)                                                                                                        | item `{ value, label }` — `value` (a string, like the v3 `key`: wrap a number in `String(...)`) names the crumb's `#<value>` slots, and its slot scope says `label` (was `text`); a crumb hidden in the overflow menu is a dropdown row with the same fields       | hard rename — `npx bitboss-ui check --fix` rewrites literal items                                                                                                                                                                                                                                                                                                                                            |
 
 ## Edits
 
 ```diff
 - <BbBreadcrumbs :items="[{ key: 1, text: 'Home', href: '/' }]" divider=">">
-+ <BbBreadcrumbs :items="[{ key: 'home', text: 'Home', href: '/' }]">
++ <BbBreadcrumbs :items="[{ value: 'home', label: 'Home', href: '/' }]">
 -   <template #Order History>…</template>
 +   <template #order-history>…</template>
   </BbBreadcrumbs>

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

@@ -1,6 +1,6 @@
 ---
 title: 'Migration v2→v3: BbCheckboxGroup / BbRadioGroup / BbSwitchGroup'
-summary: labelPosition renamed legendPosition, per-item disabled is now inert (use selectable), color and the option affix slots removed, 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.
+summary: 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.
 ---
 
 # BbCheckboxGroup / BbRadioGroup / BbSwitchGroup — v2 → v3
@@ -10,21 +10,21 @@ The three groups share their surface (`BbSwitchGroup` re-exports
 
 ## Changes
 
-| v2                                                                              | v3                                                                                            | Kind                                                                                                                                                                                                                                            |
-| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `direction`                                                                     | `layout` (`FieldLayout`)                                                                      | family-wide rename + retype (adds `'label-fill'` / `'input-fill'`); the ESLint plugin's `--fix` renames it                                                                                                                                      |
-| `inputDirection`                                                                | `listLayout` (`ListLayout`: `'horizontal'` / `'vertical'` / `'vertical-stretch'` / `'tiles'`) | **⚠ silent** — v2 `'vertical'` rows spanned the list; v3 `'vertical'` rows keep their own width and `'vertical-stretch'` is the v2 look. `--fix` maps a static `'vertical'` to `'vertical-stretch'`; a bound value is only renamed, so check it |
-| —                                                                               | `itemLayout` (one row: input against label, the `layout` keywords), `itemReverse`             | additive                                                                                                                                                                                                                                        |
-| `labelPosition?: 'left' \| 'center' \| 'right'`                                 | `legendPosition`                                                                              | rename                                                                                                                                                                                                                                          |
-| a click the parent did not apply still showed as checked on the row             | rows show the model; a click only emits until the parent applies it                           | **⚠ behaviour** — bind `v-model`, or apply the update yourself                                                                                                                                                                                  |
-| per-item `disabled` honored (with a deprecation warning)                        | **inert** — plain data, no warning                                                            | **⚠ silent** — use `selectable?: boolean \| ((item) => boolean)`                                                                                                                                                                                |
-| `color?: string`                                                                | removed                                                                                       | style via tokens/CSS                                                                                                                                                                                                                            |
-| `#option:prepend` / `#option:append` slots                                      | removed                                                                                       | use the `#label` slot (scoped `{ item, text, checked }`) to decorate options                                                                                                                                                                    |
-| `items` provider unions, `itemText` / `itemValue`                               | unified provider signature + `ItemAccessor`                                                   | retype — plain arrays and zero-argument providers unchanged; a provider now receives ONE object `({ reason, modelValue, signal }: BbCheckboxGroupItemsContext)` ([§6 item 37](../v2-to-v3.md))                                                  |
-| `name: string` required (**BbRadioGroup** only; the other two already optional) | `name?: string` (auto-generated per group when omitted)                                       | relaxation — the generated name is unique per group instance, so options still group and two groups never collide                                                                                                                               |
-| —                                                                               | `legendMode: 'outside' \| 'inside'`, `description`                                            | additive                                                                                                                                                                                                                                        |
-| `BbSwitchGroup` `multiple: false` silently ignored (always array emit)          | honored — emits a bare value in single-select mode                                            | **⚠ behavioral** (bugfix: the prop was advertised but never forwarded; fixed 2026-07-18)                                                                                                                                                        |
-| `disabled` / `selectable: false` left a **selected** option interactive         | a selected option is disabled like any other                                                  | **⚠ behavioral** (bugfix, 2026-08-31 — see below)                                                                                                                                                                                               |
+| v2                                                                              | v3                                                                                            | Kind                                                                                                                                                                                                                                                                                                                                                                                                |
+| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `direction`                                                                     | `layout` (`FieldLayout`)                                                                      | family-wide rename + retype (adds `'label-fill'` / `'input-fill'`); the ESLint plugin's `--fix` renames it                                                                                                                                                                                                                                                                                          |
+| `inputDirection`                                                                | `listLayout` (`ListLayout`: `'horizontal'` / `'vertical'` / `'vertical-stretch'` / `'tiles'`) | **⚠ silent** — v2 `'vertical'` rows spanned the list; v3 `'vertical'` rows keep their own width and `'vertical-stretch'` is the v2 look. `--fix` maps a static `'vertical'` to `'vertical-stretch'`; a bound value is only renamed, so check it                                                                                                                                                     |
+| —                                                                               | `itemLayout` (one row: input against label, the `layout` keywords), `itemReverse`             | additive                                                                                                                                                                                                                                                                                                                                                                                            |
+| `labelPosition?: 'left' \| 'center' \| 'right'`                                 | `legendPosition`                                                                              | rename                                                                                                                                                                                                                                                                                                                                                                                              |
+| a click the parent did not apply still showed as checked on the row             | rows show the model; a click only emits until the parent applies it                           | **⚠ behaviour** — bind `v-model`, or apply the update yourself                                                                                                                                                                                                                                                                                                                                      |
+| per-item `disabled` honored (with a deprecation warning)                        | **inert** — plain data, no warning                                                            | **⚠ silent** — use `selectable?: boolean \| ((item) => boolean)`                                                                                                                                                                                                                                                                                                                                    |
+| `color?: string`                                                                | removed                                                                                       | style via tokens/CSS                                                                                                                                                                                                                                                                                                                                                                                |
+| `#option:prepend` / `#option:append` slots                                      | removed                                                                                       | use the `#label` slot (scoped `{ item, text, checked }`) to decorate options                                                                                                                                                                                                                                                                                                                        |
+| `items` provider unions, `itemText` / `itemValue`                               | unified provider signature + `ItemAccessor`                                                   | retype; left out, an object item reads its own `label` (else `text`) and `value` (else the whole item) — **⚠ silent** for items with a `value` key: `v-model` gets that value ([§6 item 49](../v2-to-v3.md)); plain arrays and zero-argument providers unchanged; a provider now receives ONE object `({ reason, modelValue, signal }: BbCheckboxGroupItemsContext)` ([§6 item 37](../v2-to-v3.md)) |
+| `name: string` required (**BbRadioGroup** only; the other two already optional) | `name?: string` (auto-generated per group when omitted)                                       | relaxation — the generated name is unique per group instance, so options still group and two groups never collide                                                                                                                                                                                                                                                                                   |
+| —                                                                               | `legendMode: 'outside' \| 'inside'`, `description`                                            | additive                                                                                                                                                                                                                                                                                                                                                                                            |
+| `BbSwitchGroup` `multiple: false` silently ignored (always array emit)          | honored — emits a bare value in single-select mode                                            | **⚠ behavioral** (bugfix: the prop was advertised but never forwarded; fixed 2026-07-18)                                                                                                                                                                                                                                                                                                            |
+| `disabled` / `selectable: false` left a **selected** option interactive         | a selected option is disabled like any other                                                  | **⚠ behavioral** (bugfix, 2026-08-31 — see below)                                                                                                                                                                                                                                                                                                                                                   |
 
 `max` (checkbox/switch), `required` (radio), and `multiple` defaults are
 unchanged.