bitboss-ui 3.0.0-beta.65 → 3.0.0-beta.67

package/README.md

@@ -38,20 +38,20 @@ Full detail: `dist/ai/guides/installation-and-plugin-setup.md`.
 
 ### Composables
 
-| Composable              | Role                                                                  |
-| ----------------------- | --------------------------------------------------------------------- |
-| `useBbConfig`           | `setConfig()` patches the one runtime-editable kit option: `locale`.  |
-| `useBbDialogContext`    | Open, close and read a `BbDialog` by id (nearest scope).              |
-| `useBbDropdownContext`  | Read a `BbDropdown`'s resolved groups/selections from anywhere by id. |
-| `useBbOffCanvasContext` | Open, close and read a `BbOffCanvas` by id (nearest scope).           |
-| `useBbTableContext`     | Imperative handle onto a `BbTable` by id.                             |
-| `useBbTabsContext`      | Programmatic tab selection for a `BbTabs` by id.                      |
-| `useConfirm`            | Programmatic confirm / modal flows.                                   |
-| `useCountdown`          | Countdown timer state.                                                |
-| `useId`                 | SSR-safe unique ids.                                                  |
-| `useMobile`             | Mobile / viewport-oriented behaviour.                                 |
-| `useSafeArea`           | Claim a screen edge for a docked panel so toasts avoid it.            |
-| `useToast`              | Toast notifications API.                                              |
+| Composable       | Role                                                                  |
+| ---------------- | --------------------------------------------------------------------- |
+| `useBbConfig`    | `setConfig()` patches the one runtime-editable kit option: `locale`.  |
+| `useBbDialog`    | Open, close and read a `BbDialog` by id (nearest scope).              |
+| `useBbDropdown`  | Read a `BbDropdown`'s resolved groups/selections from anywhere by id. |
+| `useBbOffCanvas` | Open, close and read a `BbOffCanvas` by id (nearest scope).           |
+| `useBbTable`     | Imperative handle onto a `BbTable` by id.                             |
+| `useBbTabs`      | Programmatic tab selection for a `BbTabs` by id.                      |
+| `useConfirm`     | Programmatic confirm / modal flows.                                   |
+| `useCountdown`   | Countdown timer state.                                                |
+| `useId`          | SSR-safe unique ids.                                                  |
+| `useMobile`      | Mobile / viewport-oriented behaviour.                                 |
+| `useSafeArea`    | Claim a screen edge for a docked panel so toasts avoid it.            |
+| `useToast`       | Toast notifications API.                                              |
 
 ### Utilities
 
@@ -84,7 +84,7 @@ Product-ready components with labels, hints, errors, and consistent styling:
 - **Overlays & panels:** `BbDialog`, `BbConfirm`, `BbConfirmPortal`, `BbOffCanvas`, `BbPopover`, `BbHoverCard`
 - **Data:** `BbTable`, `BbTree`
 - **Media & files:** `BbAvatar`, `BbDropzone`, `BbIcon`
-- **Forms** (`BbForm` needs the `vee-validate` peer; an app without forms needs nothing): `BbForm`, `useBbFormContext`, and the 16 form controls join the form they are inside (plus `rules` / `validation-label` / `validation-mode` / `formless`; the field's path is its `name`, else its label).
+- **Forms** (`BbForm` needs the `vee-validate` peer; an app without forms needs nothing): `BbForm`, `useBbForm`, and the 16 form controls join the form they are inside (plus `rules` / `validation-label` / `validation-mode` / `formless`; the field's path is its `name`, else its label).
 - **Schema validation, no adapter:** pass a Zod, Valibot, ArkType or Yup schema (any [Standard Schema](https://standardschema.dev)) to `BbForm`'s `schema` as it is. Messages land on the field by path (`address.city`, `lines.0.qty`), `@submit` receives the schema's parsed output typed from the schema, the required asterisk comes from the schema, and a failed submit focuses the first invalid field on screen. Per-step schemas plus `keep-values-on-unmount` cover multi-step wizards. No extra runtime dependency.
 - **Passthrough scopes:** `BbPtScope` + `definePt` — a named `pt` map applied to one area of the app.
 
@@ -389,7 +389,6 @@ in place — the rule is a codemod, not just a linter:
 | `<BbTable :allow-select-all="x" />`       | `<BbTable :disable-select-all="!x" />`  | polarity inversion        |
 | `<BbTabs :animate-x="false" />`           | `<BbTabs disable-animate-x />`          | inversion, literal folded |
 | `<BbSelect allow-writing="not-mobile" />` | `<BbSelect disable-writing="mobile" />` | rename + value remap      |
-| `<BbHost />`                              | `<BbHost />`                            | value map                 |
 | `<BbPopover show-arrow />`                | `<BbPopover />`                         | removed & inert → deleted |
 | `<BbBadge content="5" />`                 | _(unchanged — reported)_                | needs a slot: manual      |
 
@@ -557,6 +556,14 @@ reports what removing cannot change.
 `bitboss-ui check` reports the same as `renamed-item-field` and
 `redundant-item-accessor`.
 
+#### Tabs as links: `tab-links`
+
+A `BbTabs` whose items have `href` / `to` is a `<nav>` of links, each going to
+its own page. `bitboss-ui/tab-links` (error) flags `navigation` on it (a link
+has no query parameter to sync, so it does nothing) and an item with neither
+`href` nor `to` among links (it renders as a disabled link). `bitboss-ui check`
+reports the same as `tab-link-navigation` and `tab-link-missing`.
+
 #### A trigger in BbDropdown's default slot: `dropdown-default-slot`
 
 `BbDropdown`'s default slot holds `<BbDropdownGroup>` companions, which render
@@ -604,6 +611,31 @@ script, a switch bound to the same ref and your own components are never
 reported. `BbAccordion` wires all of it for you.
 `bitboss-ui check` reports the same as `collapsible-trigger-aria`.
 
+#### A hidden label with no placeholder: `hidden-label-placeholder`
+
+`hide-label` keeps the label for screen readers, but a sighted user then sees
+an empty box. `bitboss-ui/hidden-label-placeholder` (warning) reports a
+library field or select with a static `hide-label` and no `placeholder`:
+
+```vue
+<template>
+	<BbSelect
+		v-model="status"
+		label="Status"
+		hide-label
+		placeholder="Status"
+		:items="statuses"
+	/>
+</template>
+```
+
+An `aria-labelledby`, a `#prefix` slot and an object `v-bind` count as
+legible; a field inside a `BbTable` / `BbTree` slot (its column header labels
+it), one at the root of a component's template (the parent lays out its
+label), a `variant="ghost"` cell editor and a single select that is neither
+`clearable` nor `multiple` (it always shows its pick) are not judged. `bitboss-ui check` reports the same as
+`hidden-label-placeholder`, as a warning.
+
 #### A dialog opened through a ref: `prefer-v-bb-dialog`
 
 A `ref(false)` whose only jobs are a `BbDialog` / `BbOffCanvas` `v-model` and
@@ -628,6 +660,37 @@ after a save) is reported without a fix: those closes become the slots'
 toggle) is never reported, since the page needs the state.
 `bitboss-ui check` reports the same as `prefer-v-bb-dialog` (a warning).
 
+#### A dialog trigger inside a closing panel: `no-dialog-in-panel`
+
+A `v-bb-dialog` (or `v-bb-off-canvas`) button that opens a component on demand
+(`v-bb-dialog="{ component: PersonDialog }"`) in `BbSelect`'s `#empty`, or any
+other slot of a select or dropdown panel, never opens it: the panel closes as
+the dialog takes focus, the slot unmounts with it, and the opening is dismissed
+with its trigger. `bitboss-ui/no-dialog-in-panel` (error) reports it, and any
+bound value that is not a literal id, which may be one. A literal id opens a
+placed `BbDialog` and is fine. Open a component from `<script setup>` instead:
+
+```vue
+<script setup lang="ts">
+import { useBbDialog } from 'bitboss-ui';
+import CreatePersonDialog from './CreatePersonDialog.vue';
+
+const personDialog = useBbDialog(CreatePersonDialog);
+</script>
+<template>
+	<BbSelect v-model="contactId" :items="people" label="Contact">
+		<template #empty="{ query }">
+			<BbBaseButton @click="personDialog.show({ name: query })">
+				Create {{ query }}
+			</BbBaseButton>
+		</template>
+	</BbSelect>
+</template>
+```
+
+The activators and the field slots (`#append`, `#prepend`…) stay mounted and
+are not reported. No `bitboss-ui check` twin.
+
 #### A rule nobody registered: `no-unregistered-rule`
 
 A string rule is a vee-validate rule name, and vee-validate knows only the

package/bin/bitboss-ui-mcp.mjs

@@ -15,14 +15,13 @@
  * loaded by nothing else. `bin/bitboss-ui.mjs` catches the resolution failure
  * and names them; `missingMcpPeers()` warns at registration time.
  *
- * `zod`'s declared range is `^3.25 || ^4.0` — copied verbatim from the SDK's
- * own dependency range, NOT invented. Do not "simplify" it to `>=` or to a
- * single major: the schemas built here are validated by the SDK's OWN copy of
- * zod, so a consumer hoisting a different MAJOR fails the SDK's brand checks
- * while npm stays silent (both ranges are independently satisfied). Mirroring
- * the range means it moves when the SDK's does. Everything used here
- * (`z.string`, `z.enum`, `z.number`, `.describe`, `.int`, `.min`, `.optional`)
- * is stable across zod 3 and 4, so the lower bound costs nothing.
+ * `zod`'s declared range is `^4.0`: the SDK's own dependency range
+ * (`^3.25 || ^4.0`) without zod 3, which carries an unpatched advisory and
+ * which nothing here needs. Never `>=`: the schemas
+ * built here are validated by the SDK's OWN copy of zod, so a consumer
+ * hoisting a different MAJOR fails the SDK's brand checks while npm stays
+ * silent (both ranges are independently satisfied). Keep it inside the SDK's
+ * range when that moves.
  *
  * Run standalone: `npx bitboss-ui mcp` (delegated from bin/bitboss-ui.mjs).
  * Registered with every MCP-capable harness by `npx bitboss-ui ai-init`
@@ -981,6 +980,38 @@ function historyWithCss(entry, manifest) {
 	];
 }
 
+/**
+ * `; states: a, b; c on x, y` — the states every part takes, then each state
+ * that reaches some parts only, with them (a group's `checked` is a row's,
+ * never the legend's). Read off the declared `pt:*` rows, so it cannot drift
+ * from what type-checks.
+ */
+function ptStatesLine(entry) {
+	const states = (entry.pt.states ?? []).map((x) => x.name);
+	if (!states.length) return '';
+	const parts = entry.pt.parts.map((x) => x.name);
+	const declared = new Set((entry.props ?? []).map((p) => p.name));
+	const wide = [];
+	const scoped = new Map();
+	for (const state of states) {
+		const on = parts.filter((part) => declared.has(`pt:${part}:${state}`));
+		if (on.length === parts.length) wide.push(state);
+		else if (on.length) {
+			// The shorter spelling: the parts it reaches, or the ones it does not.
+			const off = parts.filter((part) => !on.includes(part));
+			const key =
+				off.length < on.length
+					? `(not ${off.join(', ')})`
+					: `on ${on.join(', ')}`;
+			scoped.set(key, [...(scoped.get(key) ?? []), state]);
+		}
+	}
+	const some = [...scoped].map(
+		([where, list]) => `${list.join(', ')} ${where}`
+	);
+	return `; states: ${[wide.join(', '), ...some].filter(Boolean).join('; ')}`;
+}
+
 /** The compact `component` of the summary answer. */
 function summarizeComponent(entry, manifest) {
 	const shared = sharedProps(manifest);
@@ -1016,11 +1047,11 @@ function summarizeComponent(entry, manifest) {
 			: {}),
 		...(entry.pt?.parts?.length
 			? {
-					pt: `parts: ${entry.pt.parts.map((x) => x.name).join(', ')}${entry.pt.states?.length ? `; states: ${entry.pt.states.map((x) => x.name).join(', ')}` : ''}. Each is a \`pt:<part>\` / \`pt:<part>:<state>\` prop; the \`pt\` object takes the same keys WITHOUT the \`pt:\` prefix: { ${ptExample(entry)} }. What a part or state is: members: ['<part>'].`,
+					pt: `parts: ${entry.pt.parts.map((x) => x.name).join(', ')}${ptStatesLine(entry)}. Each a \`pt:<part>[:<state>]\` prop; \`pt\` object: the same keys WITHOUT the \`pt:\` prefix: { ${ptExample(entry)} }. Meanings: members: ['<part>'].`,
 				}
 			: {}),
 		...(entry.cssProps?.length
-			? { cssProps: entry.cssProps.map((c) => c.name ?? c) }
+			? { cssProps: [...new Set(entry.cssProps.map((c) => c.name ?? c))] }
 			: {}),
 		...(() => {
 			const history = historyWithCss(entry, manifest);
@@ -1417,7 +1448,7 @@ function getComponent({
 			? {
 					cssProps: wanted.has('cssProps')
 						? entry.cssProps
-						: entry.cssProps.map((c) => c.name ?? c),
+						: [...new Set(entry.cssProps.map((c) => c.name ?? c))],
 				}
 			: {}),
 		...(wanted.has('tree') && entry.tree ? { tree: entry.tree } : {}),
@@ -2284,11 +2315,11 @@ function getComposable({ name, sections, maxChars } = {}) {
 	}
 	const markdown = readFileSync(join(dir, file), 'utf-8');
 	/*
-	 * A composable that needs a host component says so FIRST, as a field: with
-	 * no `<BbHost />`, `await confirm()` resolves `false` after a second and a
-	 * toast never shows. Every blind answerer
-	 * of "await an Are-you-sure dialog" (4 of 4, 2026-09-24) left the host out,
-	 * although the doc's second paragraph states it.
+	 * A composable that needs a host component says so FIRST, as a field (its
+	 * summary's "Requires exactly one <Bb… />"). Every blind answerer of
+	 * "await an Are-you-sure dialog" (4 of 4, 2026-09-24) left `<BbHost />`
+	 * out; since Q82.21 the plugin renders it, so useConfirm / useToast carry
+	 * none.
 	 */
 	const host = frontmatter(markdown).summary?.match(
 		/Requires (exactly one <Bb\w+ \/>(?: host)?[^.]*)\./
@@ -3352,7 +3383,7 @@ function buildServer() {
 		'get_composable',
 		{
 			description:
-				"Read one composable's doc (useToast, useConfirm, useBbTableContext, useMobile…): what it returns, what host it needs, examples. A long doc answers its intro and outline; pass `sections`.",
+				"Read one composable's doc (useToast, useConfirm, useBbTable, useMobile…): what it returns, what host it needs, examples. A long doc answers its intro and outline; pass `sections`.",
 			inputSchema: {
 				name: z.string().describe("Composable name, e.g. 'useToast'."),
 				sections: z

package/bin/bitboss-ui.mjs

@@ -69,7 +69,12 @@ import {
 	findHandRollHints,
 	loadKnownTokens,
 } from '../scripts/lib/hand-roll-hints.mjs';
-import { loadAdoptionRows, scanIdioms } from '../scripts/lib/idiom-scan.mjs';
+import {
+	loadAdoptionRows,
+	repeatedIdioms,
+	repeatOccurrences,
+	scanIdioms,
+} from '../scripts/lib/idiom-scan.mjs';
 import {
 	disabledChecker,
 	ruleForFinding,
@@ -99,7 +104,9 @@ import {
 import {
 	HAND_IMPORTED_STYLES_EXTENSIONS,
 	handImportedStylesFindings,
+	readPluginConfig,
 } from '../scripts/lib/hand-imported-styles.mjs';
+import { unstyledVariants } from '../scripts/lib/unstyled-variants.mjs';
 import { unknownLocaleFindings } from '../scripts/lib/locale-check.mjs';
 import {
 	readShippedDefinePreset,
@@ -114,6 +121,7 @@ import {
 import { refuseLinkedTarget } from '../scripts/lib/linked-target.mjs';
 import {
 	ensureCheckUnknownComponents,
+	strictTemplateSuggestion,
 	toolchainWarnings,
 } from '../scripts/lib/toolchain-check.mjs';
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
@@ -402,6 +410,14 @@ function aiInit({ mcp = true } = {}) {
 			'MCP: skipped (--no-mcp). Re-run without it to let agents query the knowledge base through the bitboss-ui MCP server instead of reading files.'
 		);
 	}
+	// L34: the guide's strict set, suggested only (see STRICT_TEMPLATE_SET).
+	const strict = strictTemplateSuggestion(projectRoot);
+	if (strict) console.log(strict);
+	// Q82.15 (c): Muse skips project rules and skills in an untrusted
+	// workspace and reads MCP servers from its user settings only.
+	console.log(
+		'Muse: trust the workspace (its prompt, or `--trust-workspace`) so it loads AGENTS.md and the skill; for MCP, add `bitboss-ui` under `mcpServers` in ~/.config/muse/settings.json (or ask Muse to migrate it from .mcp.json).'
+	);
 	// Q61.7: Laravel's vue-starter-kit (and others) git-ignore these.
 	console.log(
 		"Some starters (Laravel's vue-starter-kit) git-ignore AGENTS.md, CLAUDE.md, .claude, .cursor and .mcp.json: teammates won't see these files until you un-ignore them."
@@ -1217,6 +1233,28 @@ async function checkCommand(
 		}
 	}
 
+	// Q82.20 (b): a variant the build plugin registers that nothing paints
+	// renders as the base plate (a solid primary badge). Read across the whole
+	// project whatever the file scope: the paint can live in any stylesheet.
+	{
+		const config = readPluginConfig(projectRoot)?.config ?? 'vite.config';
+		const sources = projectSources.flatMap((path) => {
+			try {
+				return [readText(path)];
+			} catch {
+				return [];
+			}
+		});
+		for (const { option, name, className } of unstyledVariants(
+			validateOptions.registeredVariants,
+			sources
+		))
+			warnings.push({
+				file: config,
+				message: `\`${option}\` registers "${name}", but no project file paints \`.${className}\` (or a \`pt\` state for it): it renders as the default variant. Style it in a stylesheet loaded after bitboss-ui/styles.css (design-language guide § Getting soft semantic badges).`,
+			});
+	}
+
 	// Q63.8: portal names, judged against the whole project's declarations
 	// and call sites (scripts too: `confirm({ portal })` lives there). A full
 	// run reads every source file; explicit paths / `--changed`, only those.
@@ -1264,6 +1302,8 @@ async function checkCommand(
 		const exts = new Set(rows.flatMap((row) => row.ext));
 		const TEST_FILE = /\.(?:test|spec)(?:-d)?\.[cm]?[jt]sx?$/;
 		const scope = changed ? changed.all : globs.length ? files : projectSources;
+		// Q82.4: the repeats count across files, so they are judged at the end.
+		const repeats = [];
 		for (const path of scope) {
 			const ext = path.slice(path.lastIndexOf('.') + 1);
 			if (!exts.has(ext) || path.endsWith('.d.ts') || TEST_FILE.test(path))
@@ -1274,9 +1314,13 @@ async function checkCommand(
 			} catch {
 				continue;
 			}
+			const file = relative(projectRoot, path);
 			for (const hit of scanIdioms(content, ext, rows))
-				idioms.push({ file: relative(projectRoot, path), ...hit });
+				idioms.push({ file, ...hit });
+			for (const occurrence of repeatOccurrences(content, ext))
+				repeats.push({ file, ...occurrence });
 		}
+		idioms.push(...repeatedIdioms(repeats));
 	}
 
 	for (const [name, file] of projectLocal) warnLocal(name, file);
@@ -1539,7 +1583,9 @@ Commands:
                       merges, never overwrites other servers — and install its
                       optional peers with the project's package manager. Sets
                       \`vueCompilerOptions.checkUnknownComponents: true\` in the
-                      tsconfig unless it is already named (Nuxt: says where).
+                      tsconfig unless it is already named (Nuxt: says where),
+                      and suggests (never writes) the install guide's strict
+                      template set when \`strictTemplates\` is not on.
                       \`--no-mcp\` skips the server and the install. Idempotent —
                       safe to re-run after upgrades.
   add <id…> | --all [--dir <path>] [--dry-run] [--json]
@@ -1563,8 +1609,9 @@ Commands:
   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\`
+                      you edited; keep a file you edited that bitboss-ui also
+                      changed, and the files that import it (exit 2), and
+                      update the rest of its group. \`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
@@ -1616,8 +1663,11 @@ Commands:
                       controls, sortable headers, steppers, app sheets, app
                       confirms, …) with file:line and the replacement: the
                       adoption checklist's own rows, run over .vue and script
-                      files. Report-only and opt-in: it never changes the exit
-                      code, and plain \`check\` never runs it. Guide:
+                      files, and two repeats across files: one \`icon\` literal
+                      on 3+ BbAlert / toasts (→ a variant) and one \`pt:<part>\`
+                      literal on 3+ instances of a component (→ the global
+                      \`pt\` map). Report-only and opt-in: it never changes the
+                      exit code, and plain \`check\` never runs it. Guide:
                       dist/ai/guides/migration/adoption-checklist.md.
 
                       Honours ESLint disable comments in .vue files: a finding
@@ -1650,7 +1700,7 @@ Commands:
                       \`--json\` prints \`{ findings: [...], warnings: [...], hints: [...],
                       suppressed, files, manifestVersion, installedVersion }\`
                       (plus \`changed: true\` under \`--changed\`, and
-                      \`idioms: [{ file, line, id, use }]\` under \`--idioms\`).
+                      \`idioms: [{ file, line, id, use, count? }]\` under \`--idioms\`).
                       Each finding: \`{ file, line, component, attr, kind,
                       message, hint?, to? }\` (plus \`fenceIndex\`/\`fenceInfo\`
                       inside a markdown fence; \`line\` is absolute in the file).
@@ -1666,11 +1716,15 @@ Commands:
                       e.g. BbColorPalette \`@update:open\`), \`unknown-slot\`,
                       \`unknown-pt-key\` (a key of the \`pt\` object form that
                       matches no part / state; \`to\` when the part was renamed),
-                      \`no-default-slot\`, \`inert-nav-attr\`,
+                      \`no-default-slot\`, \`empty-dropzone\` (a warning: a
+                      BbDropzone with nothing in its slot, the only surface
+                      it has, renders 0px tall), \`inert-nav-attr\`,
                       \`nameless-control\` (an icon-only BbButton or BbBadge,
                       or a BbProgress, with no accessible name),
                       \`removed-css-local\` (a component CSS local the
                       library removed, e.g. \`--day-slot-allowance\`),
+                      \`renamed-export\` (an import of a name bitboss-ui
+                      renamed, e.g. \`useBbFormContext\` → \`useBbForm\`),
                       \`private-import\` (an import from inside the package's
                       \`dist/\`), \`not-exported-type\` (a \`Pt*\` pt type
                       imported from bitboss-ui: type pt through
@@ -1687,6 +1741,10 @@ Commands:
                       items array: rows and crumbs take \`value\` /
                       \`label\`, tabs \`value\`, groups \`id\`; \`--fix\`
                       rewrites it),
+                      \`tab-link-navigation\` / \`tab-link-missing\` (a
+                      BbTabs whose items have \`href\` / \`to\` is a nav of
+                      links: \`navigation\` on it does nothing, and an item
+                      with neither renders as a disabled link),
                       \`unknown-variant\` (a variant name from another
                       library, e.g. \`danger\` on BbAlert / BbBadge; the
                       message names ours),
@@ -1726,8 +1784,8 @@ Commands:
                       other way round; literal names only, a \`:name\`
                       binding or a non-literal call site is never judged),
                       \`unknown-dialog\` (\`v-bb-dialog\` /
-                      \`v-bb-off-canvas\` / \`useBbDialogContext()\` /
-                      \`useBbOffCanvasContext()\` names an id no
+                      \`v-bb-off-canvas\` / \`useBbDialog()\` /
+                      \`useBbOffCanvas()\` names an id no
                       \`<BbDialog | BbOffCanvas id>\` declares, or one of
                       the other family; literal ids only),
                       \`positional-provider\` (an \`items\` provider with
@@ -1814,7 +1872,10 @@ Commands:
                       \`v-model\` and \`@click="x = true"\` use: give the
                       dialog an \`id\` and put \`v-bb-dialog\` on the
                       trigger; ESLint's \`--fix\` rewrites it when nothing
-                      else uses the ref).
+                      else uses the ref), \`hidden-label-placeholder\` (a
+                      field or select with \`hide-label\` and no
+                      \`placeholder\`: an empty unlabelled box to a sighted
+                      user; add a \`placeholder\`).
   changelog [--since <version>] [--until <version>] [--json]
                       Breaking changes between two releases — "what breaks if I
                       bump". \`--since\` is the version you are ON, and is

package/dist/_virtual/_plugin-vue_export-helper.js

@@ -1,8 +1,7 @@
-//#region \0plugin-vue:export-helper
+// \0plugin-vue:export-helper
 var e = (e, t) => {
 	let n = e.__vccOpts || e;
 	for (let [e, r] of t) n[e] = r;
 	return n;
 };
-//#endregion
 export { e as default };

package/dist/ai/BbAccordion.md

@@ -610,9 +610,10 @@ States are listed in precedence order: when two are on at once and their entries
 
 Set these on the element, or on a class you put on it, to retune this component alone — the sanctioned alternative to reaching past the API with `:deep()`. They are this component's own locals — a **Set on** of `pt:<part>` means the local lives on that part's element, so set it through that entry (`pt:box="[--border-color:var(--color-green-500)]"`); the global `--bb-*` theme tokens are a separate tier (see the [design-tokens guide](./guides/design-tokens.md), or the MCP `list_tokens` tool).
 
-| Property | Default | What it is |
-| --- | --- | --- |
-| `--py` | `16px` | trigger padding, and the panel's bottom padding |
+| Property | Set on | Default | What it is |
+| --- | --- | --- | --- |
+| `--ring-t` | `.bb-accordion__header` | `var(--bb-transition-medium)` |  |
+| `--py` | `.bb-accordion--titled` | `16px` | trigger padding, and the panel's bottom padding |
 
 ## Component tree
 

package/dist/ai/BbAlert.md

@@ -99,7 +99,7 @@ The default variant is `outline`. `warning` and `destructive` are treated as
 high-priority for accessibility (see below).
 
 There is no built-in `success` (or `positive`) variant, and none will be added — the
-shared status vocabulary is closed to `danger`/`warn` by ruling, see
+shared status vocabulary is closed to `danger`/`warn` by design, see
 [Design Tokens § Brand knobs](./guides/design-tokens.md#brand-knobs-what-a-theme-builder-sets)
 ("state colors are project-owned"). Reach for `primary` for a positive
 confirmation, or register your own project variant (below) if you need a
@@ -496,7 +496,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `close`, `icon`, `root`, `text`, `title`. States: `destructive`, `outline`, `primary`, `warning`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbAlertProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
-| `ariaLive` | `"off" \| "polite" \| "assertive" \| undefined` |  |  | ARIA live region politeness. Unset, it follows `role` when you set one (`'alert'` → `'assertive'`, `'status'` → `'polite'`), else the variant: `'assertive'` for destructive/warning, otherwise `'polite'`. |
+| `ariaLive` | `"off" \| "assertive" \| "polite" \| undefined` |  |  | ARIA live region politeness. Unset, it follows `role` when you set one (`'alert'` → `'assertive'`, `'status'` → `'polite'`), else the variant: `'assertive'` for destructive/warning, otherwise `'polite'`. |
 | `closeLabel` | `string \| undefined` |  |  | Visually hidden string used to label the close button. |
 | `hideClose` | `boolean \| undefined` | `false` |  | Defines whether to hide the close button. |
 | `hideIcon` | `boolean \| undefined` | `false` |  | Hide the icon, its own or its variant's; with neither it does nothing. |

package/dist/ai/BbAvatar.md

@@ -626,7 +626,7 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--fg` | `.bb-avatar` | `var(--bb-primary-fg)` | Initials; the built-in icon is an 80/20 mix of this toward --bg |
 | `--default-icon-size` | `.bb-avatar` | `clamp(14px, calc(var(--size) * 0.7), 48px)` | Built-in fallback icon: 70% of the avatar, floored at 14px and capped at 48px. `--size` is the avatar's own box, set inline from the `size` prop. |
 | `--fs` | `.bb-avatar` | `max(8px, calc(var(--size) * 0.4))` | Initials: 40% of the avatar, floored at 8px |
-| `--elev` | `.bb-avatar` | `var(--bb-elev-sm)` | The theme's resting lift on small chrome (Q44.15), declared here so an ancestor's `--elev` cannot reach in; `--elev: none` flattens one. |
+| `--elev` | `.bb-avatar` | `var(--bb-elev-sm)` | The theme's resting lift on small chrome, declared here so an ancestor's `--elev` cannot reach in; `--elev: none` flattens one. |
 | `--size` | `.bb-avatar__default-icon` | `var(--default-icon-size)` |  |
 
 ## Component tree

package/dist/ai/BbBadge.md

@@ -955,7 +955,7 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--min-size` | `.bb-badge` | `var(--min-size-md)` | pill min height and min width |
 | `--elev` | `.bb-badge` | `var(--bb-elev-sm)` | Resting lift. Invisible while `--bb-elev` is its default transparent layer. A chip is small enough that a theme wanting a different lift here than on a button sets `--elev` on this class. |
 | `--r` | `.bb-badge` | `calc(var(--bb-radius) * 0.5)` | Pill corners; the body and trailing wrappers round their outer edges to match |
-| `--fs` | `.bb-badge` | `calc(var(--bb-fs) - 2px)` | 12px at the default (Q49.25) |
+| `--fs` | `.bb-badge` | `calc(var(--bb-fs) - 2px)` | 12px at the default |
 | `--icon-size` | `.bb-badge` | `12px` | leading/append icons (passed to BbIcon as --size) |
 | `--gap` | `.bb-badge` | `3px` | space between label, icons and the trailing side |
 | `--px` | `.bb-badge` | `6px` | base side padding; the modifiers below scale it per side |
@@ -965,6 +965,7 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--border-disabled` | `.bb-badge` | `var(--bb-muted)` | the frame while disabled |
 | `--pad-left` | `.bb-badge` | `var(--px)` | Side-owned padding: the body and trailing wrappers carry the pill's inline padding (and its radius) so their hit areas run flush to the border. The modifiers below retune these vars instead of the pill's own padding. |
 | `--pad-right` | `.bb-badge` | `var(--px)` |  |
+| `--ring-t` | `.bb-badge` | `var(--bb-transition-medium)` |  |
 | `--size` | `.bb-badge__icon` | `var(--icon-size)` |  |
 
 ## Component tree

package/dist/ai/BbBadgeButton.md

@@ -14,7 +14,7 @@
 | --- | --- | --- | --- | --- |
 | `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `root`. States: `activeLink`, `disabled`, `exactActiveLink`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbBadgeButtonProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `activeClass` | `string \| undefined` | `'router-link-active'` |  | CSS class applied when the component renders as a link and the target of the link is the current route or the url matches partially. Ported for Inertia compatibility. |
-| `ariaCurrentValue` | `"page" \| "step" \| "location" \| "date" \| "time" \| "true" \| "false" \| undefined` | `'page'` |  | Value forwarded to the `aria-current` attribute when the component renders as a router link and the target route is an exact match. Use to communicate the current location to assistive technologies. |
+| `ariaCurrentValue` | `"time" \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| undefined` | `'page'` |  | Value forwarded to the `aria-current` attribute when the component renders as a router link and the target route is an exact match. Use to communicate the current location to assistive technologies. |
 | `async` | `boolean \| undefined` | `false` |  | Inertia: runs the visit without blocking — the page stays interactive and several async visits can be in flight at once. |
 | `cacheFor` | `string \| number \| (string \| number)[] \| undefined` |  |  | Inertia: how long a prefetched response stays fresh before it is re-fetched. A single duration, or `[staleAfter, expiresAfter]`. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be installed. |
 | `cacheTags` | `string \| string[] \| undefined` |  |  | Inertia: tags to file this visit's prefetch cache under, so a later request can invalidate the whole tagged group. |
@@ -26,7 +26,7 @@
 | `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, as Nuxt's `NuxtLink` `external` does. For links outside the SPA; a native-anchor signal alongside `target` and `download`. |
 | `headers` | `object \| undefined` |  |  | Additional HTTP headers forwarded to Inertia when navigating via `href` in an Inertia-enabled app. |
-| `href` | `string \| undefined` |  |  | Hyperlink reference used when rendering as an anchor (or as an Inertia link in Inertia-enabled apps). If provided and not disabled, the component renders as an anchor/Inertia link. |
+| `href` | `string \| { url: string; method: "get" \| "post" \| "put" \| "patch" \| "delete"; } \| undefined` |  |  | The link target: renders an anchor (an Inertia `<Link>` under Inertia). Also takes Inertia's `{ url, method }`, a Wayfinder route: Inertia visits with its method; elsewhere the link is its `url`. |
 | `instant` | `boolean \| undefined` | `false` |  | Inertia: navigate optimistically on click and reconcile when the response lands, instead of waiting for the round trip. |
 | `method` | `"get" \| "post" \| "put" \| "patch" \| "delete" \| undefined` |  |  | HTTP method used for Inertia navigation when `href` is provided in an Inertia-enabled app. Ignored otherwise: an Inertia POST visit is `href="/orders/5/archive" method="post"`, never `to` (a `to` link is a Vue Router link and sends no method). |
 | `onBefore` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia right before the request is sent. |
@@ -50,8 +50,8 @@
 | `replace` | `boolean \| undefined` | `false` |  | Uses history replacement instead of push navigation. - With Vue Router (`to`), calls `router.replace`. - With Inertia (`href`), performs a replace visit. |
 | `tag` | `'button'` \| `'div'` \| `'span'` \| `'label'` | `'button'` |  | Element of the plain (non-link) button: `'button'` (default), `'div'` / `'span'` (a clickable box inside a button or link) or `'label'` (a file-upload trigger). Ignored with `href` / `to`. Off `button`, native `type` / `disabled` drop (disabled stays a class). |
 | `target` | `string \| undefined` |  |  | Target browsing context for anchor/Inertia links (e.g. `_self`, `_blank`). Ignored when rendering as a native button. |
-| `to` | `string \| wt \| bt \| undefined` |  |  | Route location to navigate to. When provided (and not disabled), the component renders as a Vue Router link. |
-| `type` | `"button" \| "submit" \| "reset" \| undefined` | `'button'` |  | Native `type` attribute used when rendering as a button (e.g. `button`, `submit`, `reset`). |
+| `to` | `string \| et \| X \| undefined` |  |  | Route location to navigate to. When provided (and not disabled), the component renders as a Vue Router link. |
+| `type` | `"button" \| "reset" \| "submit" \| undefined` | `'button'` |  | Native `type` attribute used when rendering as a button (e.g. `button`, `submit`, `reset`). |
 | `viewTransition` | `boolean \| undefined` | `false` |  | Inertia: run the page swap inside a View Transition, where the browser supports one. |
 
 ## Passthrough parts and states
@@ -94,7 +94,7 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--min-size` | `.bb-badge` | `var(--min-size-md)` | pill min height and min width |
 | `--elev` | `.bb-badge` | `var(--bb-elev-sm)` | Resting lift. Invisible while `--bb-elev` is its default transparent layer. A chip is small enough that a theme wanting a different lift here than on a button sets `--elev` on this class. |
 | `--r` | `.bb-badge` | `calc(var(--bb-radius) * 0.5)` | Pill corners; the body and trailing wrappers round their outer edges to match |
-| `--fs` | `.bb-badge` | `calc(var(--bb-fs) - 2px)` | 12px at the default (Q49.25) |
+| `--fs` | `.bb-badge` | `calc(var(--bb-fs) - 2px)` | 12px at the default |
 | `--icon-size` | `.bb-badge` | `12px` | leading/append icons (passed to BbIcon as --size) |
 | `--gap` | `.bb-badge` | `3px` | space between label, icons and the trailing side |
 | `--px` | `.bb-badge` | `6px` | base side padding; the modifiers below scale it per side |
@@ -104,6 +104,7 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--border-disabled` | `.bb-badge` | `var(--bb-muted)` | the frame while disabled |
 | `--pad-left` | `.bb-badge` | `var(--px)` | Side-owned padding: the body and trailing wrappers carry the pill's inline padding (and its radius) so their hit areas run flush to the border. The modifiers below retune these vars instead of the pill's own padding. |
 | `--pad-right` | `.bb-badge` | `var(--px)` |  |
+| `--ring-t` | `.bb-badge` | `var(--bb-transition-medium)` |  |
 | `--size` | `.bb-badge__icon` | `var(--icon-size)` |  |
 
 ## Component tree