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

package/README.md

@@ -327,13 +327,13 @@ part you need.
 
 ### CLI commands
 
-| Command                                                                   | What it does                                                                                                                                                                                          |
-| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `npx bitboss-ui ai-init [--update] [--no-mcp]`                            | Writes the agent pointer files and registers the MCP server (installs its optional peers).                                                                                                            |
-| `npx bitboss-ui check [paths… \| --changed] [--fix] [--json]`             | Validates `Bb*` markup in `.vue` / `.md` files against the installed version; `--fix` applies the v2 → v3 renames first; `--changed` checks only the files git sees changed vs HEAD (plus untracked). |
-| `npx bitboss-ui changelog --since <version> [--until <version>] [--json]` | Lists the **breaking** changes between the version you are on and the installed one — what breaks if you bump.                                                                                        |
-| `npx bitboss-ui mcp`                                                      | Starts the MCP server on stdio (harnesses launch it for you after `ai-init`).                                                                                                                         |
-| `npx bitboss-ui --help`                                                   | Every command and flag.                                                                                                                                                                               |
+| Command                                                                   | What it does                                                                                                                                                                                                                             |
+| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `npx bitboss-ui ai-init [--update] [--no-mcp]`                            | Writes the agent pointer files and registers the MCP server (installs its optional peers).                                                                                                                                               |
+| `npx bitboss-ui check [paths… \| --changed] [--fix] [--json]`             | Validates `Bb*` markup in `.vue` / `.md` files against the installed version; `--fix` applies the library's renames first (v2 → v3, and between 3.0 betas); `--changed` checks only the files git sees changed vs HEAD (plus untracked). |
+| `npx bitboss-ui changelog --since <version> [--until <version>] [--json]` | Lists the **breaking** changes between the version you are on and the installed one — what breaks if you bump.                                                                                                                           |
+| `npx bitboss-ui mcp`                                                      | Starts the MCP server on stdio (harnesses launch it for you after `ai-init`).                                                                                                                                                            |
+| `npx bitboss-ui --help`                                                   | Every command and flag.                                                                                                                                                                                                                  |
 
 ### ESLint plugin
 
@@ -533,6 +533,23 @@ const draft = reactive({ name: '' });
 
 `bitboss-ui check` reports the same as `form-v-model`.
 
+#### Item fields: `no-renamed-item-field` and `no-redundant-item-accessor`
+
+Dropdown, tab and breadcrumb items take `value` and `label` (dropdown groups:
+`id`). `bitboss-ui/no-renamed-item-field` (error) rewrites an item literal still
+spelled the old way: `{ key: 'edit', text: 'Edit' }` → `{ value: 'edit', label:
+'Edit' }` on a `BbDropdown` / `BbDropdownButton` row or a crumb, a tab's `key` →
+`value`, a dropdown group's `key` → `id`.
+
+Object items are read by their own `label` (else `text`) and `value`, so an
+accessor naming those fields restates the default.
+`bitboss-ui/no-redundant-item-accessor` (warn) deletes it: `item-text="label"`,
+`item-value="value"`, and `item-text="text"` when no item has a `label`. It only
+reports what removing cannot change.
+
+`bitboss-ui check` reports the same as `renamed-item-field` and
+`redundant-item-accessor`.
+
 #### Rating star colours: `no-star-color`
 
 `bitboss-ui/no-star-color` flags any colour utility in `BbRating`'s `pt:item`,

package/bin/bitboss-ui-mcp.mjs

@@ -2852,7 +2852,7 @@ const SERVER_INSTRUCTIONS = [
 	'- Which component: search_components (empty query = the whole catalog). One component: get_component({ name }), one line per member; members: [names] for whole rows, sections for prose.',
 	'- A type in a props table (BbTableColumn, ButtonVariantType): get_component({ name }) returns its definition and values.',
 	'- After writing markup: validate. Before custom CSS: list_tokens.',
-	'- An old name (v2 or earlier-beta prop, slot, pt key, class) that stopped working: search_docs(the old name). What a bump breaks: list_changes({ since: <your version> }), one line per change.',
+	'- An old name (v2 or earlier-beta prop, slot, item field, pt key, class) that stopped working: search_docs(the old name). What a bump breaks: list_changes({ since: <your version> }), one line per change.',
 	"- pt in <script> (a const, a wrapper's prop): type it <Name>Props['pt']; Pt* types are not exported.",
 	'- Composables: get_composable. Whole pages: list_recipes, get_recipe (prose + files). Long docs answer with an outline: pass sections.',
 ].join('\n');
@@ -3018,9 +3018,21 @@ function buildServer() {
 					.optional()
 					.describe("Only this component's breaks, e.g. 'BbSelect'."),
 				surface: z
-					.enum(['prop', 'slot', 'pt', 'cssVar', 'class', 'option', 'method'])
+					.enum([
+						'prop',
+						'slot',
+						'pt',
+						'cssVar',
+						'class',
+						'option',
+						'method',
+						'event',
+						'item',
+					])
 					.optional()
-					.describe('Only renames of this surface.'),
+					.describe(
+						'Only renames of this surface (`item` = a field of an `items` entry, e.g. a dropdown row `key` → `value`).'
+					),
 				kind: z
 					.enum(['rename', 'behaviour'])
 					.optional()

package/bin/bitboss-ui.mjs

@@ -37,6 +37,9 @@
  *             it may never have been one anywhere. `printFindingLegend` says
  *             so in the output, because two migrating fleets each spent real
  *             time discovering it the hard way.
+ *   add       Copy Inertia helpers into the app as files it owns
+ *             (scripts/lib/helpers-add.mjs); `helpers list|diff|update`
+ *             reports on them and refreshes the ones the app has not edited.
  *   changelog Breaking changes between two releases — `--since <version>`
  *             answers "what breaks if I bump", without MCP. Reads the
  *             installed `dist/ai/changelog.json`.
@@ -93,6 +96,7 @@ import {
 	HAND_IMPORTED_STYLES_EXTENSIONS,
 	handImportedStylesFindings,
 } from '../scripts/lib/hand-imported-styles.mjs';
+import { unknownLocaleFindings } from '../scripts/lib/locale-check.mjs';
 import { syncProjectVariantDts } from '../scripts/lib/project-variant-dts.mjs';
 import { refuseLinkedTarget } from '../scripts/lib/linked-target.mjs';
 import {
@@ -148,7 +152,7 @@ function coreRules(version) {
 3. **Prefer \`Bb*\` consumer components**; never use entries marked "Reference Only - Internal" unless the user explicitly asks for internals. (\`BbBaseButton\` and the \`BbBase*Icon\` glyphs are consumer API; the \`Common*\` building blocks are not.)
 4. **Never invent prop/event/slot names** — open \`${KNOWLEDGE_BASE}/<ComponentName>.md\` (Usage & Guidelines first) or its API file \`${KNOWLEDGE_BASE}/manifest/components/<ComponentName>.json\` (one member per line; the list is \`${KNOWLEDGE_BASE}/manifest/index.json\`). Never read \`components.json\` whole: it is the 1.2 MB file the tools use.
 5. **Icons**: discover names first; never invent them (\`${KNOWLEDGE_BASE}/guides/icons-policy.md\`).
-6. **Item-driven components**: declarative \`items\` / \`item-text\` / \`item-value\`, \`dependencies\`, \`enforce-coherence\` — no manual watchers for coherence.
+6. **Item-driven components**: declarative \`items\` (an object row reads its own \`label\` and \`value\`; \`item-text\` / \`item-value\` only for other field names, never to restate those two), \`dependencies\`, \`enforce-coherence\` — no manual watchers for coherence.
 7. **Whole pages**: one recipe under \`${KNOWLEDGE_BASE}/recipes/{vue|nuxt|inertia}/\` (see the router table).
 8. **CSS near components**: \`${KNOWLEDGE_BASE}/guides/design-language.md\`. Paint as data is \`${KNOWLEDGE_BASE}/design-tokens.json\` and \`design-tokens.manifest.yaml\` (DESIGN.md-shaped). Grep \`--bb-*\`, not \`--color-*\` or \`--radius-*\`. A repo-root DESIGN.md is not this library. Two token tiers, and reaching for the wrong one is why apps end up re-skinning by class: \`--bb-*\` is the small GLOBAL theme tier (brand knobs, no numeric ramp — there is no \`--bb-primary-800\`), while each component declares its own **unprefixed** \`--*\` tokens for its look (\`.bb-table { --cell-h: 32px }\`). A missing \`--bb-*\` name is not a gap in the library — it means the knob you want is a component token. Set it on the element that DECLARES it (grep \`${KNOWLEDGE_BASE}/source/<ComponentName>.md\`); a value set further out is masked, not inherited. Prefer tokens, variants and \`pt\`; CSS on \`.bb-*__*\` internals is allowed for fine-tuning but unsupported: it can break on upgrade. \`.bb-common-*\` / \`.bb-field*\` internals: expect it to break. (\`.bb-base-button\` and the three \`.bb-base-*-icon\` glyph classes are consumer API — a supported hook, not an internal.) An override on an internal is a signal to check for a \`pt\` part or request one. A Tailwind utility on a \`Bb*\` component that does nothing is rule 9, not a library bug. One primary action per view region.
 9. **Tailwind v4 app: turn on cascade layers when you set bitboss-ui up**, not later when a class "doesn't work". In the build plugin: \`import { bitbossUi, TAILWIND_V4_LAYERS } from 'bitboss-ui/vite'\` and \`bitbossUi({ cssLayers: TAILWIND_V4_LAYERS })\` (Nuxt: \`bitboss: { cssLayers: TAILWIND_V4_LAYERS }\`, same import). Tailwind v4 emits layered CSS; without this the library's CSS is unlayered and beats every utility you put on a \`Bb*\` component or a \`pt:*\` part, whatever the specificity. With it, your utilities win. You still need the runtime plugin (\`app.use(bitbossUiPlugin)\`; Nuxt does it for you): it is what injects the sheet, into that layer. **Do not also \`@import 'bitboss-ui/styles.css'\`**: a hand import adds a second, unlayered copy and undoes the setting. Tailwind v3 or plain CSS: leave it unset. Details: \`${KNOWLEDGE_BASE}/guides/installation-and-plugin-setup.md\` § Cascade layers.
@@ -157,8 +161,9 @@ function coreRules(version) {
 12. **Never name your own components \`Bb…\`** — that prefix is bitboss-ui's. Use your app's prefix (\`App…\`, \`Acme…\`). \`check\` leaves an app's own \`Bb*\` component alone but warns: a future bitboss-ui component could take the name.
 13. **Set \`locale\` explicitly** in the build plugin (\`bitbossUi({ locale: 'it' })\` / nuxt \`bitboss: { locale: 'it' }\`) for any app that is not English: the built-in strings default to English (\`'en'\`, since 3.0.0-beta.41; it was \`'it'\`).
 14. **After writing bitboss-ui markup**, run \`npx bitboss-ui check\` — validates \`Bb*\` usage against the installed \`components.json\` and catches invented/removed props before review. In an edit loop, \`npx bitboss-ui check --changed\` checks only the files git sees changed; run the full check before you finish.
+15. **Inertia apps: install the app-side helpers with \`npx bitboss-ui add <name>\`** (\`useQueryObject\`, \`usePromiseForm\`, \`useTableContext\`, …; \`npx bitboss-ui helpers list\` names them). Never paste them from the guide. If \`add\` or \`helpers update\` refuses, stop and show the user its output and \`npx bitboss-ui helpers diff <name>\`; never edit \`bitboss-ui.lock.json\`, and never delete a helper file to get past a refusal.
 
-After upgrading bitboss-ui, re-run: \`npx bitboss-ui ai-init\``;
+After upgrading bitboss-ui, re-run: \`npx bitboss-ui ai-init\` (Inertia apps: then \`npx bitboss-ui helpers update\`)`;
 }
 
 // A blank line after the start marker and before the end marker: an HTML
@@ -1147,6 +1152,16 @@ async function checkCommand(
 			readText
 		)
 	);
+	// A locale the library does not ship, in the build config and in
+	// `setConfig({ locale })` (owner 2026-10-07: `en-UK` → `en-GB`).
+	findings.push(
+		...unknownLocaleFindings(
+			projectRoot,
+			styleScan.map((path) => ({ path, relPath: relative(projectRoot, path) })),
+			manifest,
+			readText
+		)
+	);
 	// Q46.5: `.bb-*` selectors in the app's stylesheets (the `.vue` `<style>`
 	// blocks are read by the validator above).
 	for (const path of styleScan) {
@@ -1340,6 +1355,37 @@ Commands:
                       tsconfig unless it is already named (Nuxt: says where).
                       \`--no-mcp\` skips the server and the install. Idempotent —
                       safe to re-run after upgrades.
+  add <id…> | --all [--dir <path>] [--dry-run] [--json]
+                      Copy Inertia helpers (\`helpers list\`; --all for every
+                      one) into the app as
+                      files it owns, with every file they import, and record
+                      them in bitboss-ui.lock.json. Creates missing files and
+                      adopts identical ones; never changes an existing file.
+                      Prints the install line for missing npm packages; never
+                      runs it. First run: --dir, else
+                      resources/js/composables/inertia-helpers (Laravel) or
+                      src/composables/inertia-helpers.
+  helpers [list] [--json]
+                      Every helper id, what it does, its files and packages,
+                      and its state in this app.
+  helpers diff [id…] [--json]
+                      The state of every installed helper file; with ids, the
+                      difference between your copy and this bitboss-ui's.
+                      Exit 1 when something differs. Comments never count as
+                      edits: a stale file's comments are replaced by update.
+  helpers update [id…] [--dry-run] [--json]
+                      Replace helper files that hold an older bitboss-ui
+                      version (formatting does not matter); keep the files
+                      you edited; refuse a group of helpers where you edited a
+                      file bitboss-ui also changed. \`npm update bitboss-ui\`
+                      does not touch your copies: run this after upgrading.
+                      add/helpers exit codes: 0 done or nothing to do; 1 usage
+                      error or diff found a difference; 2 refused (add wrote
+                      nothing); 3 a precondition failed, nothing written; 4 a
+                      write failed and was rolled back. No --force: to take
+                      bitboss-ui's copy over your edit, delete the file and
+                      run add again. --yes is accepted and does nothing (the
+                      commands never prompt).
   check [glob…] [--changed] [--json] [--allow-empty] [--allow-component <Name>]
                       [--no-hints] [--manifest <path>] [--fix]
                       Validate \`Bb*\` markup in .vue/.md files against the
@@ -1372,8 +1418,8 @@ Commands:
                       under \`--manifest\`.
 
                       \`--fix\` first applies the ESLint plugin's fixes (the
-                      registered v2→v3 renames, polarity flips and value
-                      remaps) to the matched .vue files with ONLY the
+                      registered renames — v2→v3 and between 3.0 betas, item
+                      fields included — polarity flips and value remaps) to the matched .vue files with ONLY the
                       bitboss-ui rules — your own ESLint config is not used —
                       then reports what is left. Needs \`eslint\` and
                       \`vue-eslint-parser\` in the project.
@@ -1430,9 +1476,18 @@ Commands:
                       \`dist/\`), \`not-exported-type\` (a \`Pt*\` pt type
                       imported from bitboss-ui: type pt through
                       \`<Component>Props['pt']\` instead),
-                      \`missing-key\` / \`duplicate-row-text\` (a
-                      BbDropdown row or group that needs a \`key\`: selectable,
-                      or identical keyless text in one group),
+                      \`missing-value\` / \`missing-id\` /
+                      \`duplicate-row-label\` (a BbDropdown row in a
+                      selectable group without a \`value\`, a selectable
+                      group without an \`id\`, or two value-less rows with
+                      the same \`label\` in one group; before
+                      3.0.0-beta.49 \`missing-key\` / \`duplicate-row-text\`),
+                      \`renamed-item-field\` (a dropdown row \`key\` /
+                      \`text\`, a dropdown group \`key\`, a tab \`key\` or a
+                      crumb \`key\` / \`text\` in an inline or same-file
+                      items array: rows and crumbs take \`value\` /
+                      \`label\`, tabs \`value\`, groups \`id\`; \`--fix\`
+                      rewrites it),
                       \`unknown-variant\` (a variant name from another
                       library, e.g. \`danger\` on BbAlert / BbBadge; the
                       message names ours),
@@ -1488,17 +1543,23 @@ Commands:
                       \`--fix\` rewrites it), \`missing-partner-prop\`,
                       \`partner-prop\`,
                       \`validated-only-prop\`, \`object-items-without-text\`
-                      (object \`items\` with no \`item-text\`; reads only
+                      (object \`items\` with neither a \`label\` nor a
+                      \`text\` field and no \`item-text\`; reads only
                       an inline array, or a \`const\` array, \`ref([…])\` or
                       \`reactive([…])\` in the same file's
-                      \`<script setup>\`), \`reserved-key\` (a key
-                      whose slot name is one of the component's own slots,
-                      e.g. a BbTable column keyed \`actions\`; read from the
-                      manifest, same-file keys only), \`hand-imported-styles\`
+                      \`<script setup>\`), \`reserved-key\` (a column
+                      \`key\` or item \`value\` whose slot name is one of
+                      the component's own slots, e.g. a BbTable column keyed
+                      \`actions\`; read from the manifest, same-file items
+                      only), \`hand-imported-styles\`
                       (\`bitboss-ui/styles.css\` imported in CSS, a script or
                       Nuxt's \`css\` while \`injectStyles\` is on: delete it;
                       read only when vite.config / nuxt.config says so),
-                      \`unknown-class\` (a selector on a \`.bb-*\` class the
+                      \`unknown-locale\` (a \`locale\` / \`enabledLocales\`
+                      literal in vite.config / nuxt.config, or a
+                      \`setConfig({ locale })\`, that bitboss-ui does not
+                      ship; \`suggestion\` is the nearest one: en-UK →
+                      en-GB), \`unknown-class\` (a selector on a \`.bb-*\` class the
                       library does not render, in a stylesheet or a
                       \`<style>\` block; \`suggestion\` is the nearest real
                       one), \`renamed-class\` (a class the library renamed;
@@ -1666,6 +1727,47 @@ switch (command) {
 		await main();
 		break;
 	}
+	case 'add':
+	case 'helpers': {
+		const { values, positionals } = parseCommandArgs(
+			command,
+			commandArgs,
+			{
+				json: { type: 'boolean' },
+				'dry-run': { type: 'boolean' },
+				yes: { type: 'boolean', short: 'y' },
+				...(command === 'add'
+					? { dir: { type: 'string' }, all: { type: 'boolean' } }
+					: {}),
+			},
+			{ allowPositionals: true }
+		);
+		const [sub, ...rest] =
+			command === 'add' ? ['add', ...positionals] : positionals;
+		const subcommand = command === 'add' ? 'add' : (sub ?? 'list');
+		if (subcommand === 'list' && values['dry-run']) {
+			console.error(
+				'[bitboss-ui] helpers list: --dry-run applies to add and update'
+			);
+			process.exit(1);
+		}
+		const { runHelpers } = await import('../scripts/lib/helpers-add.mjs');
+		const result = await runHelpers({
+			command: subcommand,
+			ids: command === 'add' ? positionals : rest,
+			options: {
+				dir: values.dir,
+				dryRun: values['dry-run'] ?? false,
+				all: values.all ?? false,
+			},
+			cwd: process.cwd(),
+			packageRoot: PACKAGE_ROOT,
+		});
+		if (values.json) console.log(JSON.stringify(result.report));
+		else (result.stderr ? console.error : console.log)(result.lines.join('\n'));
+		process.exitCode = result.code;
+		break;
+	}
 	case 'help':
 	case '--help':
 	case '-h':

package/dist/ai/BbAvatar.md

@@ -257,7 +257,7 @@ const hiddenCount = computed(() => reviewers.length - maxVisible);
 }
 
 .stack :deep(.bb-avatar + .bb-avatar) {
-	margin-left: -12px;
+	margin-inline-start: -12px;
 }
 </style>
 ```

package/dist/ai/BbBreadcrumbs.md

@@ -36,9 +36,9 @@ use `BbPagination`. Show at most one breadcrumb trail per view.
 
 ### Build the trail from `items`
 
-Each item is `{ key, text }` plus a navigation target. `key` must be unique (it
-also becomes the crumb's named-slot name and the label fallback when `text` is
-missing). Navigation is always the item's job — give a crumb an `href` (or
+Each item is `{ label, value }` plus a navigation target. `label` is the
+crumb's text; `value` is optional and, when set, must be unique (it names the
+crumb's own slots). Navigation is always the item's job — give a crumb an `href` (or
 `to`, or an `onClick`) and it renders as a real link; **never** wrap a crumb in
 your own click-to-route handler. Leave the **last** item without a target: a
 last crumb with no target is the current page, and the component marks it
@@ -51,10 +51,10 @@ it) never marks the parent current.
 ```vue
 <BbBreadcrumbs
 	:items="[
-		{ key: 'dashboard', text: 'Dashboard', href: '#dashboard' },
-		{ key: 'billing', text: 'Billing', href: '#billing' },
-		{ key: 'invoices', text: 'Invoices', href: '#invoices' },
-		{ key: 'invoice', text: 'Invoice #1042' },
+		{ value: 'dashboard', label: 'Dashboard', href: '#dashboard' },
+		{ value: 'billing', label: 'Billing', href: '#billing' },
+		{ value: 'invoices', label: 'Invoices', href: '#invoices' },
+		{ value: 'invoice', label: 'Invoice #1042' },
 	]"
 />
 ```
@@ -124,20 +124,20 @@ import type { BbBreadcrumbsItem } from 'bitboss-ui';
 // crumb is a real link; the current page stays without a target.
 const trail: BbBreadcrumbsItem[] = [
 	{
-		key: 'settings',
-		text: 'Settings',
+		value: 'settings',
+		label: 'Settings',
 		href: '#settings',
 		'prepend:icon': 'lucide:settings',
 	},
 	{
-		key: 'team',
-		text: 'Team',
+		value: 'team',
+		label: 'Team',
 		href: '#team',
 		'prepend:icon': 'lucide:users',
 	},
 	{
-		key: 'members',
-		text: 'Members',
+		value: 'members',
+		label: 'Members',
 		'prepend:icon': 'lucide:user-round',
 	},
 ];
@@ -164,7 +164,7 @@ other crumb goes into the menu and the current page stays, its label truncated
 with an ellipsis (the full text in a tooltip and to assistive tech). That is the
 floor: in a very narrow toolbar the trail reads `… / Quarterly rev…`. If that is
 too little, give the trail its own full-width row, or shorten the last label
-(`text` is yours).
+(`label` is yours).
 
 **Overflow folds into an ellipsis menu**
 
@@ -172,12 +172,12 @@ too little, give the trail its own full-width row, or shorten the last label
 <div class="max-w-xs">
 	<BbBreadcrumbs
 		:items="[
-			{ key: 'workspace', text: 'Workspace', href: '#workspace' },
-			{ key: 'engineering', text: 'Engineering', href: '#engineering' },
-			{ key: 'frontend', text: 'Frontend', href: '#frontend' },
-			{ key: 'design-system', text: 'Design System', href: '#design-system' },
-			{ key: 'components', text: 'Components', href: '#components' },
-			{ key: 'breadcrumbs', text: 'Breadcrumbs' },
+			{ value: 'workspace', label: 'Workspace', href: '#workspace' },
+			{ value: 'engineering', label: 'Engineering', href: '#engineering' },
+			{ value: 'frontend', label: 'Frontend', href: '#frontend' },
+			{ value: 'design-system', label: 'Design System', href: '#design-system' },
+			{ value: 'components', label: 'Components', href: '#components' },
+			{ value: 'breadcrumbs', label: 'Breadcrumbs' },
 		]"
 	/>
 </div>
@@ -250,8 +250,8 @@ When slot (or icon) content adds width the estimator cannot see, set
 <BbBreadcrumbs
 	:offset-width="96"
 	:items="[
-		{ key: 'settings', text: 'Settings', href: '#settings' },
-		{ key: 'notifications', text: 'Notifications' },
+		{ value: 'settings', label: 'Settings', href: '#settings' },
+		{ value: 'notifications', label: 'Notifications' },
 	]"
 >
 	<template #prepend>
@@ -260,7 +260,7 @@ When slot (or icon) content adds width the estimator cannot see, set
 	<template #item:prepend="{ item }">
 		<BbIcon
 			class="mr-1"
-			:icon="item.key === 'settings' ? 'lucide:settings' : 'lucide:bell'"
+			:icon="item.value === 'settings' ? 'lucide:settings' : 'lucide:bell'"
 			size="14"
 		/>
 	</template>
@@ -310,10 +310,10 @@ import type { BbBreadcrumbsItem } from 'bitboss-ui';
 // File-view header: trail says where you are; compact `append` actions act on
 // the file. Declare their width with `offset-width` so overflow stays honest.
 const items: BbBreadcrumbsItem[] = [
-	{ key: 'repo', text: 'acme-ui', href: '#repo' },
-	{ key: 'src', text: 'src', href: '#src' },
-	{ key: 'components', text: 'components', href: '#components' },
-	{ key: 'button', text: 'Button.tsx' },
+	{ value: 'repo', label: 'acme-ui', href: '#repo' },
+	{ value: 'src', label: 'src', href: '#src' },
+	{ value: 'components', label: 'components', href: '#components' },
+	{ value: 'button', label: 'Button.tsx' },
 ];
 
 const copied = ref(false);
@@ -330,17 +330,17 @@ const onCopyPath = () => {
 
 ### Own one crumb's label with its named slot
 
-Every item also gets a slot named after its `key`, replacing that crumb's
-default text (same scope as `item:prepend`). Use it when a single crumb needs
-richer content — a status dot on the current record, a badge on one level —
-while the rest of the trail stays plain. A crumb's `key` is optional unless
-it has a slot of its own — a keyless crumb renders with the generic `item:*`
-slots and its text, and its slot name is never derived from the text (a label
-changes with translation; a slot name must not). The slot name is the key through
+Every item with a `value` also gets a slot named after it, replacing that
+crumb's default label (same scope as `item:prepend`). Use it when a single crumb
+needs richer content — a status dot on the current record, a badge on one level —
+while the rest of the trail stays plain. A crumb's `value` is optional unless
+it has a slot of its own — a crumb without one renders with the generic `item:*`
+slots and its label, and its slot name is never derived from the label (a label
+changes with translation; a slot name must not). The slot name is the value through
 `slotKey`, which is kebab-case — `'Order History'` → `#order-history`,
 `'orderHistory'` → `#order-history`, `'order_history'` → `#order-history`; for
-a key with accents or other scripts write `#[slotKey('Qualità')]` (`import {
-slotKey } from 'bitboss-ui'`). Because keys become slot names, a key spelled
+a value with accents or other scripts write `#[slotKey('Qualità')]` (`import {
+slotKey } from 'bitboss-ui'`). Because values become slot names, a value spelled
 like a reserved slot (`prepend`, `append`, `divider`, `ellipsis`, `item`) is an
 error: `bitboss-ui check` flags it when `items` is in the same file.
 
@@ -349,16 +349,16 @@ error: `bitboss-ui check` flags it when `items` is in the same file.
 ```vue
 <BbBreadcrumbs
 	:items="[
-		{ key: 'deployments', text: 'Deployments', href: '#deployments' },
-		{ key: 'release', text: 'v2.4.0' },
+		{ value: 'deployments', label: 'Deployments', href: '#deployments' },
+		{ value: 'release', label: 'v2.4.0' },
 	]"
 >
-	<template #release="{ text }">
+	<template #release="{ label }">
 		<span class="inline-flex items-center gap-1.5">
 			<span
 				class="size-2 rounded-full bg-(--bb-primary)"
 			></span>
-			{{ text }}
+			{{ label }}
 		</span>
 	</template>
 </BbBreadcrumbs>
@@ -380,10 +380,10 @@ wider than `…`, pair it with `ellipsis-width`.
 	<BbBreadcrumbs
 		:ellipsis-width="40"
 		:items="[
-			{ key: 'library', text: 'Library', href: '#library' },
-			{ key: 'photos', text: 'Photos', href: '#photos' },
-			{ key: 'albums', text: 'Albums', href: '#albums' },
-			{ key: 'summer', text: 'Summer 2026' },
+			{ value: 'library', label: 'Library', href: '#library' },
+			{ value: 'photos', label: 'Photos', href: '#photos' },
+			{ value: 'albums', label: 'Albums', href: '#albums' },
+			{ value: 'summer', label: 'Summer 2026' },
 		]"
 	>
 		<template #divider>
@@ -482,8 +482,8 @@ const items = computed<BbBreadcrumbsItem[]>(() =>
 	path.value.map((name, index) => {
 		const isCurrent = index === path.value.length - 1;
 		return {
-			key: `${index}-${name}`,
-			text: name,
+			value: `${index}-${name}`,
+			label: name,
 			'prepend:icon': 'lucide:folder',
 			...(isCurrent
 				? {}
@@ -507,9 +507,9 @@ active-class props are wired for you:
 ```vue
 <BbBreadcrumbs
 	:items="[
-		{ key: 'home', text: 'Home', to: { name: 'index' } },
-		{ key: 'team', text: 'Team', to: '/team' },
-		{ key: 'member', text: 'Ada Lovelace' },
+		{ value: 'home', label: 'Home', to: { name: 'index' } },
+		{ value: 'team', label: 'Team', to: '/team' },
+		{ value: 'member', label: 'Ada Lovelace' },
 	]"
 />
 ```
@@ -521,9 +521,9 @@ visit:
 ```vue
 <BbBreadcrumbs
 	:items="[
-		{ key: 'dashboard', text: 'Dashboard', href: '/dashboard' },
-		{ key: 'orders', text: 'Orders', href: '/orders', preserveScroll: true },
-		{ key: 'order', text: 'Order #8842' },
+		{ value: 'dashboard', label: 'Dashboard', href: '/dashboard' },
+		{ value: 'orders', label: 'Orders', href: '/orders', preserveScroll: true },
+		{ value: 'order', label: 'Order #8842' },
 	]"
 />
 ```
@@ -597,20 +597,20 @@ import type { BbBreadcrumbsItem } from 'bitboss-ui';
 
 const trail: BbBreadcrumbsItem[] = [
 	{
-		key: 'settings',
-		text: 'Settings',
+		value: 'settings',
+		label: 'Settings',
 		href: '#settings',
 		'prepend:icon': 'lucide:settings',
 	},
 	{
-		key: 'team',
-		text: 'Team',
+		value: 'team',
+		label: 'Team',
 		href: '#team',
 		'prepend:icon': 'lucide:users',
 	},
 	{
-		key: 'members',
-		text: 'Members',
+		value: 'members',
+		label: 'Members',
 		'prepend:icon': 'lucide:user-round',
 	},
 ];
@@ -682,7 +682,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
   when its URL is the page you are on. Do not link the page the user is
   already on.
 - The overflow button is a real `button` with a localized, count-aware label
-  ("Show N hidden breadcrumbs"); its menu is a `BbDropdown` with full keyboard
+  ("Show hidden breadcrumbs (N)"); its menu is a `BbDropdown` with full keyboard
   support — nothing to add on your side.
 - The dividers are decorative (`aria-hidden`); never encode meaning in them.
 - `disabled` on the component (or an item) removes `href` and exposes
@@ -728,12 +728,12 @@ States are listed in precedence order: when two are on at once and their entries
 - `append` — scope: `BbBreadcrumbsEdgeSlotProps` `{ disabled?: boolean }` — Content rendered after the breadcrumb list, in a dedicated append region.
 - `divider` — scope: `Record<string, never>` — Replaces the default separator rendered between breadcrumb items.
 - `ellipsis` — scope: `BbBreadcrumbsEllipsisSlotProps` `{ props: { ref: (reference: unknown) => void; }; disabled?: boolean; overflowCount: number; ellipsisWidth: number }` — Replaces the default `…` overflow button shown when items overflow.
-- `item:append` — scope: `BbBreadcrumbsItemSlotProps` `{ disabled: boolean; index: number; item: Item; text?: string }` — Content rendered after **every** breadcrumb item's link/button. Generic fallback below a per-item `<key>:append` slot and above the item's `append:icon`.
-- `item:prepend` — scope: `BbBreadcrumbsItemSlotProps` `{ disabled: boolean; index: number; item: Item; text?: string }` — Content rendered before **every** breadcrumb item's link/button, in the leading edge region. Generic fallback: a per-item `<key>:prepend` slot takes precedence, and the item's `prepend:icon` is used when neither slot is present.
+- `item:append` — scope: `BbBreadcrumbsItemSlotProps` `{ disabled: boolean; index: number; item: Item; label?: string }` — Content rendered after **every** breadcrumb item's link/button. Generic fallback below a per-item `<value>:append` slot and above the item's `append:icon`.
+- `item:prepend` — scope: `BbBreadcrumbsItemSlotProps` `{ disabled: boolean; index: number; item: Item; label?: string }` — Content rendered before **every** breadcrumb item's link/button, in the leading edge region. Generic fallback: a per-item `<value>:prepend` slot takes precedence, and the item's `prepend:icon` is used when neither slot is present.
 - `prepend` — scope: `BbBreadcrumbsEdgeSlotProps` `{ disabled?: boolean }` — Content rendered before the breadcrumb list, in a dedicated prepend region.
-- `#<key>` (named from data) — scope: `BbBreadcrumbsItemSlotProps` — One crumb's label, by its `key` through `slotKey`; falls back to `item.text`. A crumb folded into the overflow menu follows BbDropdown's slot rules instead. Reserved keys (their slot is one of this component's own, so a key spelled like them is an error): `append`, `divider`, `ellipsis`, `item`, `prepend`.
-- `#<key>:prepend` (named from data) — scope: `BbBreadcrumbsItemSlotProps` — The glyph before one crumb's label; beats `item:prepend`, which beats its `prepend:icon`.
-- `#<key>:append` (named from data) — scope: `BbBreadcrumbsItemSlotProps` — The glyph after one crumb's label; beats `item:append`, which beats its `append:icon`.
+- `#<value>` (named from data) — scope: `BbBreadcrumbsItemSlotProps` — One crumb's label, by its `value` through `slotKey`; falls back to `item.label`. A crumb folded into the overflow menu follows BbDropdown's slot rules instead (the same `#<value>` names). Reserved names (their slot is one of this component's own, so an item value or column key spelled like them is an error): `append`, `divider`, `ellipsis`, `item`, `prepend`.
+- `#<value>:prepend` (named from data) — scope: `BbBreadcrumbsItemSlotProps` — The glyph before one crumb's label; beats `item:prepend`, which beats its `prepend:icon`.
+- `#<value>:append` (named from data) — scope: `BbBreadcrumbsItemSlotProps` — The glyph after one crumb's label; beats `item:append`, which beats its `append:icon`.
 
 ## Component tree
 
@@ -747,7 +747,7 @@ States are listed in precedence order: when two are on at once and their entries
 - `BbBreadcrumbs` _(this component)_ — its own template binds: `item` → `li.bb-breadcrumbs__item`, `icon` → `BbIcon`, `text` → `span.bb-breadcrumbs__text`
   - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
   - `BbDropdown` _(public — [contract](./BbDropdown.md))_ — its own pt parts (`BbDropdown`): `panel` → `CommonPopover`, `root` → `CommonPopover`, `header` → `div.bb-dropdown__header`, `list` → `span.bb-dropdown__list`, `footer` → `div.bb-dropdown__footer`; documented CSS variables: `--menu-inset`; also mounts `CommonPopover`, `DropdownPipelineResolver`
-    - `BbDropdownList` _(internal — not importable, reach it through `BbDropdown`)_ — also mounts `BbBaseButton`, `BbIcon`, `ErrorIcon`, `CommonPopover`, `BbDropdownList`
+    - `BbDropdownList` _(internal — not importable, reach it through `BbDropdown`)_ — also mounts `BbIcon`, `ErrorIcon`, `CommonPopover`, `BbDropdownList`
       - `BbBadge` _(public — [contract](./BbBadge.md))_ — its own pt parts (`BbBadge`): `spinner` → `BbSpinner`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear`; documented CSS variables: `--bg`, `--fg`, `--bw`, `--ring-color`, `--ring-size`, `--min-size-md`, `--min-size`, `--elev`, `--r`, `--fs`, `--icon-size`, `--gap`, `--px`, `--clear-size`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--pad-left`; also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
     - `AdaptiveDropdown` _(internal — not importable, reach it through `BbDropdown`)_ — hands `BbOffCanvas` the pt map `{ header: 'header', footer: 'footer', panel: 'root', sheet: 'root' }` (ours → theirs); also mounts `BbSmoothHeight`, `BbDropdownList`
       - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__content`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--handle-w`, `--handle-h`, `--handle-bg`, `--safe-top`, `--close-size`

package/dist/ai/BbButton.md

@@ -410,9 +410,15 @@ live example below uses this shape). The mistake above only becomes possible
 once that loop is unrolled into separate elements with their own literal
 strings.
 
-Add `group` to fuse adjacent buttons into one visual segment control. It is
-purely visual (shared borders/radius between siblings) — each button keeps its
-own semantics, and there is no arrow-key roving between them.
+Add `group` to fuse adjacent buttons into one visual segment control (shared
+borders and radius between siblings). Each button keeps its own semantics: a
+toggle still announces as a toggle button with its pressed state. Adjacent
+`group` **toggles** are also one Tab stop: Tab lands on the pressed button (or
+the one last focused, or the first), ArrowLeft / ArrowRight move between the
+buttons (mirrored under `dir="rtl"`, wrapping at the ends), Home / End jump to
+the first / last, and Space / Enter toggle. Disabled and loading buttons are
+skipped. Any other element between two buttons splits them into two sets, and
+`group` buttons without a `v-model` keep one Tab stop each.
 
 **Exclusive toggle groups**
 
@@ -1051,7 +1057,10 @@ Gotchas (real behavior, verified against source):
   attribute and drops yours. A hand-rolled toggle (`:aria-pressed` plus a
   `variant` swap) therefore looks right and is invisible to assistive tech.
   Use `v-model` — see [Toggle buttons](#toggle-buttons). Dev builds warn.
-- `group` fuses looks only; it adds no radio semantics or arrow-key navigation.
+- `group` adds no radio semantics: an exclusive set is still toggle buttons
+  with `aria-pressed`. Adjacent `group` toggles share one Tab stop and move
+  with the arrow keys (see [Toggle buttons](#toggle-buttons)); keep a set's
+  buttons side by side in one parent, since anything between them splits it.
 - Responsive `size` maps change height/font/gap per breakpoint; padding, icon
   size and radius follow the `default` entry.
 - Auto-loading tracks the promise **returned** from `@click`; a handler that
@@ -1080,6 +1089,8 @@ Anti-patterns:
   report one as an error.
 - Toggles expose `aria-pressed` (`true`/`false`) automatically — never add your
   own.
+- A set of adjacent `group` toggles is one Tab stop (roving `tabindex`), with
+  ArrowLeft / ArrowRight / Home / End inside it — the APG toolbar pattern.
 - While loading: `aria-disabled="true"`, `tabindex="-1"`, and a localized
   visually-hidden loading announcement.
 - Disabled links render with `role="link"`, `aria-disabled="true"`, no `href`,
@@ -1115,7 +1126,7 @@ Anti-patterns:
 | `except` | `string[] \| undefined` |  |  | Inertia: the inverse of `only` — properties to EXCLUDE from a partial reload. Pass one or the other, not both. |
 | `external` | `boolean \| undefined` | `false` |  | Forces an `href` link to render as a plain `<a>` (native navigation), bypassing Inertia/router interception — same intent as Nuxt's `external`. A native-anchor signal alongside `target` and `download`. |
 | `falseValue` | `any` | `false` |  | Value emitted when the toggle is deactivated. |
-| `group` | `boolean \| undefined` | `false` |  | Identifies the button as part of a button group. |
+| `group` | `boolean \| undefined` | `false` |  | Identifies the button as part of a button group: adjacent `group` buttons fuse into one segment (shared borders and radius). Adjacent `group` toggles (each with a `v-model`) are also one Tab stop, with ArrowLeft / ArrowRight / Home / End moving between them. |
 | `headers` | `object \| undefined` |  |  | Additional HTTP headers forwarded to Inertia when navigating via `href` in an Inertia-enabled app. |
 | `href` | `string \| undefined` |  |  | Returns the hyperlink's URL. Can be set, to change the URL. |
 | `icon` | `string \| undefined` |  |  | Used when only an icon with no text should be displayed. |