bitboss-ui 3.0.0-beta.64 → 3.0.0-beta.66

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,30 @@ 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) and one at the root of a component's template (the parent lays out its
+label) 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 +659,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

@@ -1020,7 +1020,7 @@ function summarizeComponent(entry, manifest) {
 				}
 			: {}),
 		...(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 +1417,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 +2284,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 +3352,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/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

@@ -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/BbBadge.md

@@ -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. |
@@ -51,7 +51,7 @@
 | `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`). |
+| `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
@@ -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

package/dist/ai/BbBaseButton.md

@@ -56,8 +56,10 @@ in this priority order:
    `NuxtLink` (Nuxt), or the Inertia `Link` — resolved for you from the active
    framework.
 2. **Anchor `<a>`** — when `href` is set but the above doesn't apply: external or
-   cross-origin URLs, any `href` with a `target`, or a disabled `to` link (kept
-   as an anchor for correct link semantics).
+   cross-origin URLs, a fragment (`href="#actions"`), any `href` with a
+   `target`, or a disabled `to` link (kept as an anchor for correct link
+   semantics). Those need no `external`: it is for a same-origin route the
+   router must not take.
 3. **Native `<button>`** — the default when there is no `href`/`to`. Polymorphic
    via `tag` (below), but a real `<button>` unless you say otherwise.
 
@@ -73,21 +75,21 @@ primitive brings no look of its own):
 	<div class="flex flex-wrap items-center gap-2 text-sm">
 		<!-- No href/to → a native <button>. -->
 		<BbBaseButton
-			class="rounded-(--bb-radius) bg-(--bb-primary) px-3 py-1.5 text-(--bb-primary-fg) focus-visible:ring-2 focus-visible:ring-(--bb-ring)"
+			class="rounded-(--bb-radius) bg-(--bb-primary) px-3 py-1.5 text-(--bb-primary-fg) focus-visible:outline-(--bb-ring)"
 			@click="pinged = true"
 		>
 			Native button
 		</BbBaseButton>
 		<!-- Same-origin href → an <a>. -->
 		<BbBaseButton
-			class="rounded-(--bb-radius) px-3 py-1.5 text-(--bb-primary) underline focus-visible:ring-2 focus-visible:ring-(--bb-ring)"
+			class="rounded-(--bb-radius) px-3 py-1.5 text-(--bb-primary) underline focus-visible:outline-(--bb-ring)"
 			href="#docs"
 		>
 			Anchor link
 		</BbBaseButton>
 		<!-- href + target → a plain <a target="_blank"> with rel secured. -->
 		<BbBaseButton
-			class="rounded-(--bb-radius) px-3 py-1.5 underline focus-visible:ring-2 focus-visible:ring-(--bb-ring)"
+			class="rounded-(--bb-radius) px-3 py-1.5 underline focus-visible:outline-(--bb-ring)"
 			href="https://example.com"
 			target="_blank"
 		>
@@ -117,19 +119,21 @@ scaffold, `cursor` and transitions), `bb-base-button--block` and
 library button, tab, row and menu item draws on, and each of those paints its
 own focus; a native outline would sit on top of all of them. So a bare
 `BbBaseButton` shows **no keyboard focus until you style it**. Every class you
-give it needs a `:focus-visible` style too; the library's own ring is one
-utility pair:
+give it needs a `:focus-visible` style too. The base already draws a 2px
+transparent outline (the ring scaffold), so the library's own ring is one
+utility that colours it:
 
 ```vue
 <BbBaseButton
-	class="rounded-(--bb-radius) px-3 py-1.5 focus-visible:ring-2 focus-visible:ring-(--bb-ring)"
+	class="rounded-(--bb-radius) px-3 py-1.5 focus-visible:outline-(--bb-ring)"
 >
 	Save
 </BbBaseButton>
 ```
 
-The ring animates in through the base's `box-shadow` transition (that is the
-scaffold). There is **no padding, background, border, or
+The ring fades in through the base's `outline-color` transition (that is the
+scaffold), as the library's own rings do: an outline, never a `box-shadow`, so
+a shadow you set on the element never takes the ring with it. There is **no padding, background, border, or
 variant appearance** — that is the whole point. It sets **no text color**, so a
 `text-*` utility on the element just works with no specificity fight; the text
 inherits from its container (in anchor mode, the browser's blue-and-underlined
@@ -146,7 +150,7 @@ the right base for a clickable card or a bespoke nav item:
 	<!-- Styled entirely by utility classes — neutral hover chrome. -->
 	<BbBaseButton
 		href="#b"
-		class="rounded-(--bb-radius) border border-(--bb-border) px-3 py-1 font-medium hover:bg-(--bb-hover) focus-visible:ring-2 focus-visible:ring-(--bb-ring)"
+		class="rounded-(--bb-radius) border border-(--bb-border) px-3 py-1 font-medium hover:bg-(--bb-hover) focus-visible:outline-(--bb-ring)"
 	>
 		Branded pill
 	</BbBaseButton>
@@ -172,7 +176,7 @@ stay outside the link:
 		<article
 			v-for="project in projects"
 			:key="project.name"
-			class="relative flex flex-col items-start gap-1.5 rounded-(--bb-radius) border border-(--bb-border) bg-(--bb-panel) p-3 hover:bg-(--bb-surface-hover) has-focus-visible:ring-2 has-focus-visible:ring-(--bb-ring)"
+			class="relative flex flex-col items-start gap-1.5 rounded-(--bb-radius) border border-(--bb-border) bg-(--bb-panel) p-3 hover:bg-(--bb-surface-hover) has-focus-visible:outline-2 has-focus-visible:outline-(--bb-ring)"
 		>
 			<span class="flex w-full items-center justify-between gap-2">
 				<span
@@ -236,9 +240,9 @@ const projects: Project[] = [
 - **Optional links:** render the overlay only when there is a destination
   (`v-if="href"`); the card needs no other change — no `tag` switching.
 - **Focus:** the overlay is invisible, so show focus on the card
-  (`has-focus-visible:ring-2 has-focus-visible:ring-(--bb-ring)`) and drop it
-  from the overlay (`outline-none`; the primitive's own ring scaffold is
-  zero-width until you style it).
+  (`has-focus-visible:outline-2 has-focus-visible:outline-(--bb-ring)`) and
+  drop it from the overlay (`outline-none`, so the scaffold's transparent
+  outline never paints).
 
 ### Label
 
@@ -450,7 +454,7 @@ When it renders as a native button you can retune the element:
 		</p>
 		<BbBaseButton
 			block
-			class="rounded-(--bb-radius) bg-(--bb-primary) px-3 py-1.5 text-sm text-(--bb-primary-fg) focus-visible:ring-2 focus-visible:ring-(--bb-ring)"
+			class="rounded-(--bb-radius) bg-(--bb-primary) px-3 py-1.5 text-sm text-(--bb-primary-fg) focus-visible:outline-(--bb-ring)"
 			type="submit"
 		>
 			Create workspace
@@ -520,7 +524,8 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 - `tag="div"`/`tag="span"` throws away native button semantics — only do it when a
   `<button>` is genuinely invalid, and restore keyboard/focus behavior yourself.
 - Style the focus state: the base removes the browser's ring and provides only
-  a _scaffold_ (`box-shadow`/`outline` transitions), so a class without a
+  a _scaffold_ (a transparent 2px outline and its colour transition), so a
+  class without a
   `:focus-visible` style ships an invisible keyboard focus. See "It removes the
   browser's focus ring" above.
 
@@ -544,7 +549,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | --- | --- | --- | --- | --- |
 | `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 `BbBaseButtonProps['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. |
 | `block` | `boolean \| undefined` | `false` |  | Makes the component take the full available width (block-level layout) and centres its label; an anchor becomes `display: block` so the width applies. Adds the `bb-base-button--block` modifier class. |
 | `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. |
@@ -557,7 +562,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `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. |
@@ -583,7 +588,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `target` | `string \| undefined` |  |  | Target browsing context for anchor/Inertia links (e.g. `_self`, `_blank`). Ignored when rendering as a native button. |
 | `text` | `string \| undefined` |  |  | Fallback text content rendered when no default slot is provided. |
 | `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`). |
+| `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

package/dist/ai/BbBaseCheckboxIcon.md

@@ -294,6 +294,7 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--elev` | `var(--bb-elev-sm)` | Resting lift; a no-op until a theme pins `--bb-elev`. |
 | `--bg` | `var(--bb-panel)` | The glyph plate. DECLARED here, not consumed bare, because this glyph renders inside surfaces that declare `--bg` themselves — a table row or header cell, a dialog, an off-canvas sheet. Without the declaration it would inherit that surface's fill, which happens to match at the shipped default and would diverge the moment anyone writes `.my-table { --bg: … }`. Identical to the raw tokens it replaces at every theme. |
 | `--border-color` | `var(--bb-border)` | Resting border colour of the glyph; re-pointed by error and warning states. |
+| `--ring-t` | `var(--bb-transition-medium)` |  |
 
 ## See Also
 

package/dist/ai/BbBaseRadioIcon.md

@@ -306,6 +306,7 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--elev` | `var(--bb-elev-sm)` | Same resting lift as the checkbox glyph — see BbBaseCheckboxIcon. |
 | `--bg` | `var(--bb-panel)` | The glyph plate. DECLARED here, not consumed bare, because this glyph renders inside surfaces that declare `--bg` themselves — a table row or header cell, a dialog, an off-canvas sheet. Without the declaration it would inherit that surface's fill, which happens to match at the shipped default and would diverge the moment anyone writes `.my-table { --bg: … }`. Identical to the raw tokens it replaces at every theme. |
 | `--border-color` | `var(--bb-border)` |  |
+| `--ring-t` | `var(--bb-transition-medium)` |  |
 
 ## See Also
 

package/dist/ai/BbBaseSwitchIcon.md

@@ -307,6 +307,7 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--thumb` | `min(16px, calc(var(--h) - 2 * var(--bw)))` | Capped by the track's inner height, so a thick-hairline theme shrinks the thumb instead of overflowing it. Unclamped, a 6px plate hairline leaves a 12px inner track carrying a 16px thumb; `--inset` then goes negative and the thumb paints over its own border. `16px` at every hairline the library ships, so no shipped pixel moves. Do NOT floor `--inset` at 0 instead: that keeps the oversized thumb and pushes it out of the bottom of the track (measured +1px protrusion at a 6px hairline), and it uncancels `--bw` from `--travel`, which is a constant 14px by construction. |
 | `--inset` | `calc((var(--h) - 2 * var(--bw) - var(--thumb)) / 2)` | Equal gap around the thumb — centres it vertically by construction, and is reused as the resting left/right inset. |
 | `--travel` | `calc(var(--w) - 2 * var(--bw) - var(--thumb) - 2 * var(--inset))` | How far the thumb slides between off and on (inset ↔ inset). |
+| `--ring-t` | `var(--bb-transition-medium)` |  |
 
 ## See Also