bitboss-ui 3.0.0-beta.50 → 3.0.0-beta.52

package/README.md

@@ -550,6 +550,85 @@ reports what removing cannot change.
 `bitboss-ui check` reports the same as `renamed-item-field` and
 `redundant-item-accessor`.
 
+#### A trigger in BbDropdown's default slot: `dropdown-default-slot`
+
+`BbDropdown`'s default slot holds `<BbDropdownGroup>` companions, which render
+nothing. A button written there renders with no activator wiring, so clicking
+it opens nothing. `bitboss-ui/dropdown-default-slot` (error) reports a native
+element or a library component other than `BbDropdownGroup` in that slot; the
+trigger belongs in the activator slot:
+
+```vue
+<template>
+	<BbDropdown :items="items">
+		<template #activator="{ props }">
+			<BbButton v-bind="props" text="Actions" />
+		</template>
+	</BbDropdown>
+</template>
+```
+
+With no slot to fill, `v-bb-dropdown="items"` on the trigger does the same.
+Your own components there are not reported: one may render a group.
+`bitboss-ui check` reports the same as `dropdown-default-slot`.
+
+#### A BbCollapsible trigger without `aria-expanded`: `collapsible-trigger-aria`
+
+`BbCollapsible` ships no trigger, so the button that opens it owns the
+disclosure state. `bitboss-ui/collapsible-trigger-aria` (error) reports a
+native element or a library component whose `@click` is exactly
+`open = !open` on the ref a `BbCollapsible` binds, when it carries no
+`aria-expanded`:
+
+```vue
+<template>
+	<BbButton
+		aria-controls="advanced"
+		:aria-expanded="open"
+		text="Advanced options"
+		@click="open = !open"
+	/>
+	<BbCollapsible id="advanced" v-model="open">…</BbCollapsible>
+</template>
+```
+
+Only that certain case is judged: a handler that calls a method, a toggle in
+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`.
+
+#### `required` inside a BbForm: `no-required-in-form`
+
+A `BbForm` posts `novalidate` (vee-validate owns validation), so `required` on
+a form control inside one shows the asterisk and enforces nothing: an empty
+field submits. `bitboss-ui/no-required-in-form` (error) reports a static
+`required` or a bound `:required` on a library form control inside a
+`<BbForm>` in the same template. Write the requirement where the form
+validates; the asterisk follows:
+
+```vue
+<template>
+	<BbForm :model="draft" @submit="save">
+		<BbTextInput name="email" label="Email" rules="required|email" />
+		<BbTextInput
+			name="vat"
+			label="VAT number"
+			:rules="{ required: isCompany }"
+		/>
+	</BbForm>
+</template>
+```
+
+`--fix` rewrites a bare `required` to `rules="required"` when the control has
+no `rules` and the form no `schema`; anything else is reported for you to move
+(with a `schema`, require the key there). A control your own component renders
+inside the form's slot is not seen. `required` beside a `:rules` function is
+reported too, without a fix: the function checks a value only when there is
+one, so register it (`defineRule('vat', isVat)`) and write
+`rules="required|vat"`, or require the key in the schema. Outside a `BbForm`
+`required` stays: a plain `<form>` validates natively.
+`bitboss-ui check` reports the same as `required-in-form`.
+
 #### 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

@@ -1416,13 +1416,14 @@ function getComponent({
 	// `removed` and `renamed` repeat each other with migration metadata; one
 	// line per old name answers "what happened to X" (include 'history' for
 	// the records the fixers use).
+	// The agent file leaves both out (they are `<Name>.removed.json`).
 	if (wanted.has('history')) {
+		if (entry.removed) component.removed = entry.removed;
 		if (entry.renamed) component.renamed = entry.renamed;
 		component.cssRenames = cssRenameLines(entry, manifest);
 	} else {
 		const history = historyWithCss(entry, manifest);
 		if (history.length) component.history = history;
-		delete component.removed;
 	}
 
 	const always = guide.filter(
@@ -2732,7 +2733,7 @@ function listChanges({
 							: compareVersions(a, b)
 				)
 			),
-			hint: 'Counts only. What breaks when you bump: list_changes({ since: "<the version you have>" }) — one line per change; coming from v2: since: "2". One component: { component: "BbSelect" }. Full rows: detail: "rows".',
+			hint: 'Counts only. What a bump breaks: list_changes({ since: "<your version>" }), one line per change; from v2: since: "2". One component: { component: "BbSelect" }. Full rows: detail: "rows".',
 		};
 	}
 

package/bin/bitboss-ui.mjs

@@ -97,7 +97,10 @@ import {
 	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 {
+	syncNotice,
+	syncProjectVariantDts,
+} from '../scripts/lib/project-variant-dts.mjs';
 import { refuseLinkedTarget } from '../scripts/lib/linked-target.mjs';
 import {
 	ensureCheckUnknownComponents,
@@ -906,10 +909,10 @@ async function checkCommand(
 				pathToFileURL(join(PACKAGE_ROOT, 'dist', 'project-dts.js')).href
 			);
 			const synced = syncProjectVariantDts(projectRoot, projectDts);
-			if (synced.status === 'written' && !jsonMode)
-				console.log(
-					`[bitboss-ui] Wrote ${synced.path} from your build config: registered variant names now type-check. Commit it.`
-				);
+			const notice = syncNotice(synced);
+			// Q65.2: a skip is said too (stderr under `--json`, like `--fix`'s lines).
+			if (notice && !(jsonMode && synced.status === 'written'))
+				(jsonMode ? console.error : console.log)(notice);
 		} catch {
 			// No built `dist/project-dts.js` (the library repo before a build):
 			// nothing to write with, and nothing for `check` to fail over.
@@ -1500,6 +1503,23 @@ Commands:
                       \`reactive-v-model\` (a \`v-model\` on a \`<script
                       setup>\` \`const x = reactive(…)\`: a production build
                       rejects the write-back; hold it in a \`ref()\`),
+                      \`text-null-value\` (a \`v-model\` on BbTextInput /
+                      BbTextarea bound to a ref typed \`string\` while the
+                      field writes \`null\` once emptied: widen it to
+                      \`ref<string | null>\`, or \`null-value="string"\`),
+                      \`dropdown-default-slot\` (a trigger in a BbDropdown's
+                      default slot, which holds BbDropdownGroup companions:
+                      it opens nothing; use \`#activator="{ props }"\` with
+                      \`v-bind="props"\`, or \`v-bb-dropdown\`),
+                      \`collapsible-trigger-aria\` (an element whose
+                      \`@click="open = !open"\` flips a BbCollapsible's
+                      ref, with no \`aria-expanded\`: add
+                      \`:aria-expanded="open"\` + \`aria-controls\`),
+                      \`required-in-form\` (\`required\` on a form control
+                      inside a \`BbForm\`: the asterisk shows but the form
+                      posts \`novalidate\`, so nothing enforces it; write
+                      \`rules="required"\` or make it required in the
+                      schema),
                       \`form-v-model\` (\`v-model\`, \`:model-value\` or an
                       \`@update:model-value\` listener on a \`BbForm\`: it
                       takes its object one way, \`:model="draft"\`),

package/dist/ai/BbAccordion.md

@@ -644,7 +644,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: `header`, `panel`, `root`. States: `open`. 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 `BbAccordionProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `eager` | `boolean \| undefined` | `false` |  | Renders the content at mount, while closed, instead of on the first open. Closed content is `inert` and `aria-hidden` either way. |
-| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` |  |  | Wraps the header button in a heading of this level (`<h1>`–`<h6>`), the APG accordion shape, so the header joins the page's outline. Match the level to where the accordion sits (a section under an `<h2>` takes `3`). No visual change: the heading's margins and font are reset. Omitted, there is no heading. |
+| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` |  |  | Wraps the header button in a heading of this level (`<h1>`–`<h6>`, the APG accordion shape) so it joins the page outline: under an `<h2>`, pass `3`. Its margins and font are reset. Omitted, no heading. |
 | `id` | `string \| undefined` |  |  | The root's `id`; the header button's id (`<id>_header`) derives from it. Generated when omitted. |
 | `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to trigger opening / closing the collapsible. An accordion with no `v-model` starts closed. |
 | `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds |

package/dist/ai/BbAlert.md

@@ -494,7 +494,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 
 ## Slots
 
-- `default` — scope: `any` — The alert body — the shortest form, and the one to reach for: `<BbAlert>Something went wrong</BbAlert>`. Same idiom as the rest of the `text`-prop family (BbButton, BbBaseButton, BbTooltip, BbIndicator). When more than one source is present the most specific wins: `#text` > children > the `text` prop.
+- `default` — scope: `any` — The alert body, the shortest form: `<BbAlert>Something went wrong</BbAlert>`. The most specific source wins: `#text` > children > the `text` prop.
 - `text` — scope: `BbAlertTextSlotProps` `{ text: string }` — Replaces the default alert body text. Wins over children and `text`.
 - `title` — scope: `BbAlertTitleSlotProps` `{ text: string }` — Replaces the default alert title text.
 

package/dist/ai/BbAsterisk.md

@@ -42,8 +42,10 @@ placed in a label is not a reliable way to convey a requirement. What actually
 carries mandatoriness to assistive tech is the **control itself**: the native
 `required` attribute when you set the `required` prop, and
 `aria-required="true"` when a `BbForm` makes the field mandatory (a `required`
-rule or the schema). Inside a form the browser never validates: only your
-explicit `required` prop puts the native attribute on.
+rule or the schema). Inside a form the browser never validates, so there the
+`required` prop is an error (`bitboss-ui/no-required-in-form`): it would mark
+the field with nothing enforcing it; write `rules="required"` or require the
+key in the schema.
 
 The practical consequence: the marker is a _visual_ affordance only, and the
 control's own required state is the real thing. Never ship a field that shows

package/dist/ai/BbBadge.md

@@ -858,9 +858,9 @@ 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: `clear`, `icon`, `root`, `spinner`, `text`. States: `loading`. 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 `BbBadgeProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `append:icon` | `string \| undefined` |  |  | Icon rendered after the label. On a `clearable` badge it shares the trailing slot with the clear button: the icon shows at rest and the clear button reveals over it on hover/focus. |
 | `clearable` | `boolean \| undefined` | `false` |  | Renders a trailing clear button and emits `click:clear` when pressed — turns the badge into a dismissible token (the pattern formerly served by `BbChip`). |
-| `clearableLabel` | `string \| undefined` |  |  | Accessible label for the clear button. Rarely needed: unset, the name is **composed** from the localized `badge.clearLabel` verb and the badge's own text — "Remove Italy", not a bare "Remove" — which is already the right name in almost every case. Composition is skipped when a `BbBadgeButton` owns the body (the verb then stands alone, so the two controls do not both announce the label). Set this only to override that composed name outright. |
+| `clearableLabel` | `string \| undefined` |  |  | Accessible name of the clear button. Rarely needed: unset, it is composed from the localized `badge.clearLabel` verb and the badge text ("Remove Italy"), or the verb alone when a `BbBadgeButton` owns the body. |
 | `icon` | `string \| undefined` |  |  | Renders an icon-only badge. When set, `prepend:icon` / `append:icon` are ignored and the default slot becomes the badge's visually hidden accessible label — always provide it. |
-| `loading` | `boolean \| undefined` | `false` |  | Shows a spinner in place of the leftmost icon, mirroring `BbButton`: it replaces the `icon` glyph or the `prepend:icon` when one is set; when the `append:icon` is the sole icon it replaces that instead (e.g. a select-activator chevron while the value saves), and with no icons at all it takes the leading slot. Adds a visually hidden loading announcement for screen readers. |
+| `loading` | `boolean \| undefined` | `false` |  | Shows a spinner in place of the leftmost icon (`icon` or `prepend:icon`; the `append:icon` when it is the only one; else the leading slot), as `BbButton` does, with a hidden loading announcement. |
 | `prepend:icon` | `string \| undefined` |  |  | Icon rendered before the label. |
 | `size` | `'xs'` \| `'sm'` \| `'md'` \| `'lg'` \| `'xl'` \| `'2xl'` | `"md"` |  | Preset size of the badge. |
 | `variant` | `'outline'` \| `'primary'` \| `'destructive'` \| `'secondary'` \| `'none'` | `"primary"` |  | Visual variant: `primary`, `secondary`, `destructive`, or `outline`. Register more via the vite plugin `badgeVariants` option and style `.bb-badge--<variant>` (set `--bg` / `--fg`). `'none'` renders no variant class — an escape hatch for a one-off look set through `--bg` / `--fg` on the element. |

package/dist/ai/BbBadgeButton.md

@@ -21,7 +21,7 @@
 | `component` | `string \| undefined` |  |  | Inertia: the page component this visit resolves to. Rarely set by hand — the server normally decides it. |
 | `data` | `object \| undefined` |  |  | Request payload forwarded to Inertia when navigating via `href` in an Inertia-enabled app. Ignored when not using Inertia. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables user interaction. - When rendering as a native button, sets the `disabled` attribute. - When rendering as a link (anchor/Inertia), removes `href`, adds `aria-disabled="true"` and `tabindex="-1"`, and prevents navigation: the link stays announced as a link but leaves the tab order. |
-| `download` | `string \| boolean \| undefined` |  |  | Marks an `href` link as a download. Renders a plain `<a download>` doing a native navigation — never an Inertia/router visit — so file downloads (including same-origin, `blob:` and `data:` URLs) work. Pass a string to set the suggested filename. One of the native-anchor signals alongside `target` and `external`. |
+| `download` | `string \| boolean \| undefined` |  |  | Marks an `href` link as a download: a plain `<a download>` with a native navigation (never an Inertia or router visit), so `blob:` and `data:` files work too. A string sets the suggested filename. |
 | `exactActiveClass` | `string \| undefined` | `'router-link-exact-active'` |  | CSS class applied when the component renders as a link and the target of the link and the url matches exactly. Ported for Inertia compatibility. |
 | `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 — the same intent as Nuxt's `NuxtLink` `external`. Use for links outside the SPA. One of the native-anchor signals alongside `target` and `download`. |
@@ -32,7 +32,7 @@
 | `onBefore` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia right before the request is sent. |
 | `onCancel` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request is cancelled. |
 | `onCancelToken` | `((cancelToken: unknown) => void) \| undefined` |  |  | Receives the Inertia cancel token source when a request is initiated. Can be used to cancel the request. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be installed. |
-| `onError` | `((errors: Record<string, string>) => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when the server responds with VALIDATION errors — the ordinary 422 path. This is the only failure callback Inertia's `Link` accepts. `onHttpException` (server answered 5xx) and `onNetworkError` (the request never arrived) are `router.visit()` / `useForm()` options, NOT Link props — declaring them here would only paste bogus listeners onto the anchor. Use a form or an explicit visit when you need to tell them apart. |
+| `onError` | `((errors: Record<string, string>) => void) \| undefined` |  |  | Inertia's hook for a VALIDATION error answer (the 422 path): the only failure callback `Link` accepts. `onHttpException` (5xx) and `onNetworkError` are `router.visit()` / `useForm()` options, never Link props. |
 | `onFinish` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia after the request has finished (regardless of success or error). |
 | `only` | `string[] \| undefined` |  |  | Limits the properties that are preserved in Inertia partial reloads. |
 | `onPrefetched` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a prefetch for this link has completed and is cached. |
@@ -48,7 +48,7 @@
 | `queryStringArrayFormat` | `"brackets" \| "indices" \| undefined` | `'brackets'` |  | Format to use when serializing array values into the query string for Inertia requests. |
 | `rel` | `string \| undefined` |  |  | Relationship between the current document and the linked resource. Useful for security when opening new tabs (e.g. `noopener noreferrer`). |
 | `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 to render for the plain (non-link, non-router) button: - `'button'` (default) — real button semantics and keyboard behavior - `'div'` / `'span'` — a clickable box nested inside another button or link, where a nested `<button>` would be invalid markup - `'label'` — a file-upload trigger wrapping a visually hidden `<input>` Ignored when the component renders as a link/router (`href`/`to`) — those always render `<a>`/router-link. When set to a non-`button` tag the native `type`/`disabled` attributes are dropped (they're invalid off a `<button>`); disabled state is still conveyed via the `bb-base-button--disabled` class. |
+| `tag` | `'button'` \| `'div'` \| `'span'` \| `'label'` | `'button'` |  | Element for the plain (non-link) button: `'button'` (default), `'div'` / `'span'` (a clickable box inside another 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`). |

package/dist/ai/BbBaseButton.md

@@ -239,6 +239,11 @@ destination onto these props instead of an `@click` handler:
   any target other than `_self` (`_blank`, named windows, …) automatically
   merges `noopener noreferrer` into `rel`.
 - **`to`** — a Vue Router `RouteLocationRaw`, rendered as a router/Nuxt link.
+- **`download`** — marks an `href` link as a download: a plain `<a download>`
+  doing a native navigation, never an Inertia / router visit, so file
+  downloads work (same-origin, `blob:` and `data:` URLs included). A string
+  sets the suggested filename. It is a native-anchor signal like `target` and
+  `external`.
 - **`replace`** — history replacement (`router.replace` under Vue Router, a
   replace visit under Inertia).
 - **Inertia visit options** ride along with `href`: request shape (`method`,
@@ -519,7 +524,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `component` | `string \| undefined` |  |  | Inertia: the page component this visit resolves to. Rarely set by hand — the server normally decides it. |
 | `data` | `object \| undefined` |  |  | Request payload forwarded to Inertia when navigating via `href` in an Inertia-enabled app. Ignored when not using Inertia. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables user interaction. - When rendering as a native button, sets the `disabled` attribute. - When rendering as a link (anchor/Inertia), removes `href`, adds `aria-disabled="true"` and `tabindex="-1"`, and prevents navigation: the link stays announced as a link but leaves the tab order. |
-| `download` | `string \| boolean \| undefined` |  |  | Marks an `href` link as a download. Renders a plain `<a download>` doing a native navigation — never an Inertia/router visit — so file downloads (including same-origin, `blob:` and `data:` URLs) work. Pass a string to set the suggested filename. One of the native-anchor signals alongside `target` and `external`. |
+| `download` | `string \| boolean \| undefined` |  |  | Marks an `href` link as a download: a plain `<a download>` with a native navigation (never an Inertia or router visit), so `blob:` and `data:` files work too. A string sets the suggested filename. |
 | `exactActiveClass` | `string \| undefined` | `'router-link-exact-active'` |  | CSS class applied when the component renders as a link and the target of the link and the url matches exactly. Ported for Inertia compatibility. |
 | `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 — the same intent as Nuxt's `NuxtLink` `external`. Use for links outside the SPA. One of the native-anchor signals alongside `target` and `download`. |
@@ -530,7 +535,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `onBefore` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia right before the request is sent. |
 | `onCancel` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request is cancelled. |
 | `onCancelToken` | `((cancelToken: unknown) => void) \| undefined` |  |  | Receives the Inertia cancel token source when a request is initiated. Can be used to cancel the request. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be installed. |
-| `onError` | `((errors: Record<string, string>) => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when the server responds with VALIDATION errors — the ordinary 422 path. This is the only failure callback Inertia's `Link` accepts. `onHttpException` (server answered 5xx) and `onNetworkError` (the request never arrived) are `router.visit()` / `useForm()` options, NOT Link props — declaring them here would only paste bogus listeners onto the anchor. Use a form or an explicit visit when you need to tell them apart. |
+| `onError` | `((errors: Record<string, string>) => void) \| undefined` |  |  | Inertia's hook for a VALIDATION error answer (the 422 path): the only failure callback `Link` accepts. `onHttpException` (5xx) and `onNetworkError` are `router.visit()` / `useForm()` options, never Link props. |
 | `onFinish` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia after the request has finished (regardless of success or error). |
 | `only` | `string[] \| undefined` |  |  | Limits the properties that are preserved in Inertia partial reloads. |
 | `onPrefetched` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a prefetch for this link has completed and is cached. |
@@ -546,7 +551,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `queryStringArrayFormat` | `"brackets" \| "indices" \| undefined` | `'brackets'` |  | Format to use when serializing array values into the query string for Inertia requests. |
 | `rel` | `string \| undefined` |  |  | Relationship between the current document and the linked resource. Useful for security when opening new tabs (e.g. `noopener noreferrer`). |
 | `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 to render for the plain (non-link, non-router) button: - `'button'` (default) — real button semantics and keyboard behavior - `'div'` / `'span'` — a clickable box nested inside another button or link, where a nested `<button>` would be invalid markup - `'label'` — a file-upload trigger wrapping a visually hidden `<input>` Ignored when the component renders as a link/router (`href`/`to`) — those always render `<a>`/router-link. When set to a non-`button` tag the native `type`/`disabled` attributes are dropped (they're invalid off a `<button>`); disabled state is still conveyed via the `bb-base-button--disabled` class. |
+| `tag` | `'button'` \| `'div'` \| `'span'` \| `'label'` | `'button'` |  | Element for the plain (non-link) button: `'button'` (default), `'div'` / `'span'` (a clickable box inside another 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. |
 | `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. |

package/dist/ai/BbBaseCheckboxIcon.md

@@ -41,11 +41,25 @@ the glyph in for the visuals.
 ### Compose it into a custom control
 
 The glyph is decorative (`aria-hidden`), so it **must** be paired with a real
-control. The reliable pattern: a `<label>` wrapping a visually-hidden native
-`<input type="checkbox">` (keep it in the a11y tree with `sr-only`, never
-`display:none`) plus the glyph reflecting `checked`. You get native keyboard
-support, focus, and form submission for free, and total freedom over the layout
-around it.
+control. The reliable pattern: a `<label>` wrapping a native
+`<input type="checkbox">` stacked under the glyph, the glyph reflecting
+`checked`. You get native keyboard support, focus, and form submission for
+free, and total freedom over the layout around it.
+
+**Stack the input under the glyph; never shrink it to `sr-only`.** Put both in
+one grid cell (`grid` on a wrapper, `col-start-1 row-start-1` on each). The
+input is `opacity-0` and fills the cell (`size-full min-w-0 m-0
+appearance-none`); the glyph is `pointer-events-none`. Test runners click the
+input itself and first check that it is the element under the pointer
+(Playwright's `getByLabel(…).check()`): a 1px clipped `sr-only` input is never
+that element, so the click times out. Stacked, the pointer, a label click and
+the test runner all reach the input. Never `display:none` or `visibility:
+hidden` either: the input must stay in the accessibility tree and focusable.
+
+**Show keyboard focus on the glyph.** The input is invisible, so pass its
+focus to the glyph's `focus-visible` prop: on the input's `focus`, keep
+whether it `matches(':focus-visible')`; clear it on `blur` (the example does
+this).
 
 **Invoice alert channel cards**
 
@@ -71,14 +85,27 @@ around it.
 						: 'border-(--bb-border) hover:bg-(--bb-surface-hover)'
 				"
 			>
-				<!-- Glyph is decorative; the sr-only input owns focus, keyboard, and form state. -->
-				<input
-					v-model="selected"
-					class="sr-only"
-					type="checkbox"
-					:value="channel.id"
-				/>
-				<BbBaseCheckboxIcon :checked="selected.includes(channel.id)" />
+				<!--
+					The input and the glyph share one grid cell. The input is invisible
+					but fills the cell, so a click (and a test runner's "is the input the
+					hit target" check) lands on it; the glyph lets the pointer through
+					and shows the input's state, keyboard focus included.
+				-->
+				<span class="grid shrink-0">
+					<input
+						v-model="selected"
+						class="col-start-1 row-start-1 m-0 size-full min-w-0 cursor-pointer appearance-none opacity-0"
+						type="checkbox"
+						:value="channel.id"
+						@blur="focusVisible = null"
+						@focus="onFocus(channel.id, $event)"
+					/>
+					<BbBaseCheckboxIcon
+						:checked="selected.includes(channel.id)"
+						class="pointer-events-none col-start-1 row-start-1"
+						:focus-visible="focusVisible === channel.id"
+					/>
+				</span>
 				<span class="flex min-w-0 flex-col">
 					<span class="text-sm font-medium">{{ channel.label }}</span>
 					<span class="text-xs text-(--bb-text-muted)">{{ channel.hint }}</span>
@@ -101,6 +128,14 @@ const channels: Channel[] = [
 ];
 
 const selected = ref<string[]>(['email']);
+
+// The ring shows for keyboard focus only, as the library's own toggles do.
+const focusVisible = ref<string | null>(null);
+function onFocus(id: string, event: FocusEvent) {
+	focusVisible.value = (event.target as HTMLElement).matches(':focus-visible')
+		? id
+		: null;
+}
 </script>
 ```
 

package/dist/ai/BbBaseRadioIcon.md

@@ -40,11 +40,25 @@ the glyph in for the visuals.
 ### Compose it into a custom control
 
 The glyph is decorative (`aria-hidden`), so it **must** be paired with a real
-control. The reliable pattern: a `<label>` wrapping a visually-hidden native
-`<input type="radio">` (keep it in the a11y tree with `sr-only`, never
-`display:none`), all radios in the group sharing one `name`, plus the glyph
-reflecting `checked`. Native radios give you exclusive selection, roving focus
-and arrow-key navigation for free.
+control. The reliable pattern: a `<label>` wrapping a native
+`<input type="radio">` stacked under the glyph, all radios in the group
+sharing one `name`, the glyph reflecting `checked`. Native radios give you
+exclusive selection, roving focus and arrow-key navigation for free.
+
+**Stack the input under the glyph; never shrink it to `sr-only`.** Put both in
+one grid cell (`grid` on a wrapper, `col-start-1 row-start-1` on each). The
+input is `opacity-0` and fills the cell (`size-full min-w-0 m-0
+appearance-none`); the glyph is `pointer-events-none`. Test runners click the
+input itself and first check that it is the element under the pointer
+(Playwright's `getByLabel(…).check()`): a 1px clipped `sr-only` input is never
+that element, so the click times out. Stacked, the pointer, a label click and
+the test runner all reach the input. Never `display:none` or `visibility:
+hidden` either: the input must stay in the accessibility tree and focusable.
+
+**Show keyboard focus on the glyph.** The input is invisible, so pass its
+focus to the glyph's `focus-visible` prop: on the input's `focus`, keep
+whether it `matches(':focus-visible')`; clear it on `blur` (the example does
+this).
 
 **Workspace plan cards**
 
@@ -70,15 +84,28 @@ and arrow-key navigation for free.
 						: 'border-(--bb-border) hover:bg-(--bb-surface-hover)'
 				"
 			>
-				<!-- Native radios sharing `name` give exclusive selection + arrow keys. -->
-				<input
-					v-model="selected"
-					class="sr-only"
-					name="plan"
-					type="radio"
-					:value="plan.id"
-				/>
-				<BbBaseRadioIcon :checked="selected === plan.id" />
+				<!--
+					Native radios sharing `name` give exclusive selection and arrow
+					keys. Each one shares a grid cell with its glyph: invisible, but
+					filling the cell, so clicks and test runners hit the input; the
+					glyph lets the pointer through and shows the input's state.
+				-->
+				<span class="grid shrink-0">
+					<input
+						v-model="selected"
+						class="col-start-1 row-start-1 m-0 size-full min-w-0 cursor-pointer appearance-none opacity-0"
+						name="plan"
+						type="radio"
+						:value="plan.id"
+						@blur="focusVisible = null"
+						@focus="onFocus(plan.id, $event)"
+					/>
+					<BbBaseRadioIcon
+						:checked="selected === plan.id"
+						class="pointer-events-none col-start-1 row-start-1"
+						:focus-visible="focusVisible === plan.id"
+					/>
+				</span>
 				<span class="flex min-w-0 flex-1 items-start justify-between gap-3">
 					<span class="flex min-w-0 flex-col">
 						<span class="text-sm font-medium">{{ plan.label }}</span>
@@ -121,6 +148,14 @@ const plans: Plan[] = [
 ];
 
 const selected = ref('team');
+
+// The ring shows for keyboard focus only, as the library's own toggles do.
+const focusVisible = ref<string | null>(null);
+function onFocus(id: string, event: FocusEvent) {
+	focusVisible.value = (event.target as HTMLElement).matches(':focus-visible')
+		? id
+		: null;
+}
 </script>
 ```
 

package/dist/ai/BbBaseSwitchIcon.md

@@ -41,10 +41,25 @@ checkbox with `role="switch"`) and drop the glyph in for the visuals.
 ### Compose it into a custom control
 
 The glyph is decorative (`aria-hidden`), so it **must** be paired with a real
-control. The reliable pattern: a `<label>` wrapping a visually-hidden native
-`<input type="checkbox" role="switch">` (keep it in the a11y tree with `sr-only`,
-never `display:none`) plus the glyph reflecting `checked`. You get native
-keyboard support, focus, and switch semantics for free.
+control. The reliable pattern: a `<label>` wrapping a native
+`<input type="checkbox" role="switch">` stacked under the glyph, the glyph
+reflecting `checked`. You get native keyboard support, focus, and switch
+semantics for free.
+
+**Stack the input under the glyph; never shrink it to `sr-only`.** Put both in
+one grid cell (`grid` on a wrapper, `col-start-1 row-start-1` on each). The
+input is `opacity-0` and fills the cell (`size-full min-w-0 m-0
+appearance-none`); the glyph is `pointer-events-none`. Test runners click the
+input itself and first check that it is the element under the pointer
+(Playwright's `getByLabel(…).check()`): a 1px clipped `sr-only` input is never
+that element, so the click times out. Stacked, the pointer, a label click and
+the test runner all reach the input. Never `display:none` or `visibility:
+hidden` either: the input must stay in the accessibility tree and focusable.
+
+**Show keyboard focus on the glyph.** The input is invisible, so pass its
+focus to the glyph's `focus-visible` prop: on the input's `focus`, keep
+whether it `matches(':focus-visible')`; clear it on `blur` (the example does
+this).
 
 **Feature flag rows**
 
@@ -68,21 +83,33 @@ keyboard support, focus, and switch semantics for free.
 					<span class="text-sm font-medium">{{ flag.label }}</span>
 					<span class="text-xs text-(--bb-text-muted)">{{ flag.hint }}</span>
 				</span>
-				<!-- Glyph tracks state; the checkbox + role="switch" owns a11y. -->
-				<input
-					v-model="state[flag.id]"
-					class="sr-only"
-					role="switch"
-					type="checkbox"
-				/>
-				<BbBaseSwitchIcon :checked="state[flag.id]" />
+				<!--
+					The input (checkbox + role="switch") and the glyph share one grid
+					cell: invisible, the input fills it, so clicks and test runners hit
+					the input; the glyph lets the pointer through and shows its state.
+				-->
+				<span class="grid shrink-0">
+					<input
+						v-model="state[flag.id]"
+						class="col-start-1 row-start-1 m-0 size-full min-w-0 cursor-pointer appearance-none opacity-0"
+						role="switch"
+						type="checkbox"
+						@blur="focusVisible = null"
+						@focus="onFocus(flag.id, $event)"
+					/>
+					<BbBaseSwitchIcon
+						:checked="state[flag.id]"
+						class="pointer-events-none col-start-1 row-start-1"
+						:focus-visible="focusVisible === flag.id"
+					/>
+				</span>
 			</label>
 		</div>
 	</div>
 </template>
 
 <script setup lang="ts">
-import { reactive } from 'vue';
+import { reactive, ref } from 'vue';
 import { BbBaseSwitchIcon } from 'bitboss-ui';
 
 type Flag = { id: string; label: string; hint: string };
@@ -111,6 +138,14 @@ const state = reactive<Record<string, boolean>>({
 	summaries: false,
 	analytics: false,
 });
+
+// The ring shows for keyboard focus only, as the library's own toggles do.
+const focusVisible = ref<string | null>(null);
+function onFocus(id: string, event: FocusEvent) {
+	focusVisible.value = (event.target as HTMLElement).matches(':focus-visible')
+		? id
+		: null;
+}
 </script>
 ```
 

package/dist/ai/BbButton.md

@@ -60,7 +60,10 @@ disguised as text — pair it with `href`/`to`, not with heavy actions.
 behaviour and accessibility but takes no look, so your own classes don't have
 to fight a built-in one. You then own hover, focus and disabled. It is fine for
 a one-off; keep the inline styling short, and when the same look shows up
-again, register it as a real variant instead.
+again, register it as a real variant instead: the plugin's `buttonVariants`
+option types the name, and you style `.bb-button--<name>` (the library ships
+no CSS for it). The same holds for `BbDropdownButton`, whose `variant` styles
+both halves of the split control.
 
 **`link` changes color, not layout.** It keeps the button box: the size scale's
 height and horizontal padding still apply, so it occupies button space and never
@@ -1138,7 +1141,7 @@ Anti-patterns:
 | `onBefore` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia right before the request is sent. |
 | `onCancel` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request is cancelled. |
 | `onCancelToken` | `((cancelToken: unknown) => void) \| undefined` |  |  | Receives the Inertia cancel token source when a request is initiated. Can be used to cancel the request. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be installed. |
-| `onError` | `((errors: Record<string, string>) => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when the server responds with VALIDATION errors — the ordinary 422 path. This is the only failure callback Inertia's `Link` accepts. `onHttpException` (server answered 5xx) and `onNetworkError` (the request never arrived) are `router.visit()` / `useForm()` options, NOT Link props — declaring them here would only paste bogus listeners onto the anchor. Use a form or an explicit visit when you need to tell them apart. |
+| `onError` | `((errors: Record<string, string>) => void) \| undefined` |  |  | Inertia's hook for a VALIDATION error answer (the 422 path): the only failure callback `Link` accepts. `onHttpException` (5xx) and `onNetworkError` are `router.visit()` / `useForm()` options, never Link props. |
 | `onFinish` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia after the request has finished (regardless of success or error). |
 | `only` | `string[] \| undefined` |  |  | Limits the properties that are preserved in Inertia partial reloads. |
 | `onPrefetched` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a prefetch for this link has completed and is cached. |
@@ -1161,7 +1164,7 @@ Anti-patterns:
 | `to` | `string \| wt \| bt \| undefined` |  |  | Route Location the link should navigate to when clicked on. |
 | `trueValue` | `any` | `true` |  | Value emitted when the toggle is activated. |
 | `type` | `"button" \| "submit" \| "reset" \| undefined` |  |  | Gets the classification and default behavior of the button. |
-| `variant` | `'outline'` \| `'primary'` \| `'destructive'` \| `'secondary'` \| `'none'` \| `'ghost'` \| `'link'` | `"primary"` |  | Visual variant of the button. Controls colors and surface style while keeping spacing and sizing unchanged. `'none'` is a blank starting point: the button keeps its structure and behaviour but takes no look, so your own classes don't fight a built-in one. You then own hover, focus and disabled. Fine for a one-off; keep inline styling short, and register a real variant when the look recurs: the plugin's `buttonVariants` option types the name, and you style `.bb-button--<name>` (the library ships no CSS for it). |
+| `variant` | `'outline'` \| `'primary'` \| `'destructive'` \| `'secondary'` \| `'none'` \| `'ghost'` \| `'link'` | `"primary"` |  | Visual variant of the button: colours and surface only, never spacing or size. `'none'` takes no look (you own hover, focus and disabled); register a real one with the plugin's `buttonVariants` and style `.bb-button--<name>` (no CSS ships for it). |
 | `viewTransition` | `boolean \| undefined` | `false` |  | Inertia: run the page swap inside a View Transition, where the browser supports one. |
 
 ## Passthrough parts and states