bitboss-ui 3.0.0-beta.4 → 3.0.0-beta.41

package/dist/ai/BbBaseButton.md

@@ -8,6 +8,14 @@
 - Usage rule: Prefer this component for consumer-facing implementations.
 - Implementation source (only when the contract below is not enough): [source/BbBaseButton.md](./source/BbBaseButton.md)
 
+## Reachable through `BbBaseButton`
+
+`BbBaseButton` mounts other components (all of them: _Component tree_, near the end). These are the parts of its API that land inside them. Prefer these over `:deep()` on an inner class (allowed, unsupported: it can break on upgrade) — and never an import of an internal component.
+
+| pt part | Lands on | In |
+| --- | --- | --- |
+| `pt:root` | the root of `RouterComponent` | `RouterComponent` _(internal)_ |
+
 ## Usage & Guidelines
 
 ### When to use
@@ -65,27 +73,27 @@ 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-[var(--bb-radius)] bg-[var(--bb-primary)] px-3 py-1.5 text-[var(--bb-primary-fg)]"
+			class="rounded-(--bb-radius) bg-(--bb-primary) px-3 py-1.5 text-(--bb-primary-fg)"
 			@click="pinged = true"
 		>
 			Native button
 		</BbBaseButton>
 		<!-- Same-origin href → an <a>. -->
 		<BbBaseButton
-			class="rounded-[var(--bb-radius)] px-3 py-1.5 text-[color:var(--bb-primary)] underline"
+			class="rounded-(--bb-radius) px-3 py-1.5 text-(--bb-primary) underline"
 			href="#docs"
 		>
 			Anchor link
 		</BbBaseButton>
 		<!-- href + target → a plain <a target="_blank"> with rel secured. -->
 		<BbBaseButton
-			class="rounded-[var(--bb-radius)] px-3 py-1.5 underline"
+			class="rounded-(--bb-radius) px-3 py-1.5 underline"
 			href="https://example.com"
 			target="_blank"
 		>
 			External ↗
 		</BbBaseButton>
-		<span class="text-xs text-[color:var(--bb-text-muted)]">{{
+		<span class="text-xs text-(--bb-text-muted)">{{
 			pinged ? 'button clicked' : ''
 		}}</span>
 	</div>
@@ -120,42 +128,52 @@ 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-[var(--bb-radius)] border border-[var(--bb-border)] px-3 py-1 font-medium hover:bg-[color:var(--bb-hover)]"
+		class="rounded-(--bb-radius) border border-(--bb-border) px-3 py-1 font-medium hover:bg-(--bb-hover)"
 	>
 		Branded pill
 	</BbBaseButton>
 </div>
 ```
 
-A whole card as a single navigable element — the primitive's signature use:
+A clickable card — the primitive's signature use. The card stays a plain box
+and one **overlay** `BbBaseButton` covers it (the stretched-link pattern), so
+the link's accessible name is a short visually-hidden phrase rather than the
+card's entire content, and the badge, the meta line and any nested control
+stay outside the link:
 
 **A clickable card built on the primitive**
 
 ```vue
 <template>
 	<div class="grid max-w-md gap-2 sm:grid-cols-2">
-		<!-- The whole card is ONE navigable element — a BbBaseButton rendered as an
-		     anchor, styled entirely by these utility classes. No wrapper <a>, no
-		     @click; navigation rides on `href` (a `to`/Inertia target works the same). -->
-		<BbBaseButton
+		<!-- The card is a plain box; ONE overlay BbBaseButton covers it (the
+		     stretched-link pattern). Its accessible name is the short sr-only
+		     text, not the card's whole content; the badge stays outside the link.
+		     Focus shows on the card via `has-focus-visible:`, never on the
+		     invisible overlay (`outline-none`). -->
+		<article
 			v-for="project in projects"
 			:key="project.name"
-			class="project-card flex flex-col items-start gap-1.5 rounded-[var(--bb-radius)] border border-[var(--bb-border)] bg-[var(--bb-panel)] p-3 text-left hover:bg-[color:var(--bb-surface-hover)]"
-			:href="project.href"
+			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)"
 		>
 			<span class="flex w-full items-center justify-between gap-2">
 				<span
-					class="flex size-7 shrink-0 items-center justify-center rounded-[var(--bb-radius-sm)] bg-[color:var(--bb-muted)] text-[color:var(--bb-text-muted)]"
+					class="flex size-7 shrink-0 items-center justify-center rounded-(--bb-radius-sm) bg-(--bb-muted) text-(--bb-text-muted)"
 				>
 					<BbIcon :icon="project.icon" size="sm" />
 				</span>
 				<BbBadge variant="secondary">{{ project.status }}</BbBadge>
 			</span>
 			<span class="text-sm font-medium">{{ project.name }}</span>
-			<span class="text-xs text-[color:var(--bb-text-muted)]">{{
-				project.meta
-			}}</span>
-		</BbBaseButton>
+			<span class="text-xs text-(--bb-text-muted)">{{ project.meta }}</span>
+
+			<BbBaseButton
+				class="absolute inset-0 rounded-[inherit] outline-none"
+				:href="project.href"
+			>
+				<span class="sr-only">Open {{ project.name }}</span>
+			</BbBaseButton>
+		</article>
 	</div>
 </template>
 
@@ -187,15 +205,23 @@ const projects: Project[] = [
 	},
 ];
 </script>
-
-<style scoped>
-/* Visible focus uses the base ring scaffold (box-shadow / --bb-ring). */
-.project-card:focus-visible {
-	box-shadow: 0 0 0 var(--bb-ring-size) var(--bb-ring);
-}
-</style>
 ```
 
+- **Overlay when** the card has several pieces of information, badges,
+  nested controls or long text. One `BbBaseButton` with `absolute inset-0`
+  and an `sr-only` name (`Open {{ project.name }}`) covers the box; nested
+  controls sit above it with `relative z-10` and stay clickable.
+- **Wrap when** the row's whole content _is_ its label — "Manage
+  subscription ›", a menu-like list row, an icon plus a word. Then the
+  element's own text is the right accessible name, and `BbBaseButton` wraps
+  it as in the pill above.
+- **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).
+
 ### Label
 
 Same as `BbButton`: **prefer the default slot** (`<BbBaseButton>Label</BbBaseButton>`);
@@ -269,7 +295,7 @@ The classic home for this is a settings sidebar — every item is a bare
 <template>
 	<nav
 		aria-label="Settings"
-		class="grid w-full max-w-xs gap-0.5 rounded-[var(--bb-radius)] border border-[var(--bb-border)] bg-[var(--bb-panel)] p-1.5"
+		class="grid w-full max-w-xs gap-0.5 rounded-(--bb-radius) border border-(--bb-border) bg-(--bb-panel) p-1.5"
 	>
 		<!-- Each nav item is a bare BbBaseButton: element resolution and active
 		     matching come from the primitive, the entire look comes from these
@@ -279,7 +305,7 @@ The classic home for this is a settings sidebar — every item is a bare
 			v-for="item in items"
 			:key="item.label"
 			block
-			class="settings-nav-item flex items-center gap-2 rounded-[var(--bb-radius-sm)] px-2 py-1.5 text-left text-sm text-[color:var(--bb-text-muted)] hover:bg-[color:var(--bb-hover)] hover:text-[color:var(--bb-text)]"
+			class="settings-nav-item flex items-center gap-2 rounded-(--bb-radius-sm) px-2 py-1.5 text-left text-sm text-(--bb-text-muted) hover:bg-(--bb-hover) hover:text-(--bb-text)"
 			exact-active-class="settings-nav-active"
 			:href="item.href"
 		>
@@ -347,7 +373,7 @@ attribute. On a link it keeps the element in place but strips navigation: the
 <div class="flex items-center gap-2 text-sm">
 	<BbBaseButton
 		disabled
-		class="rounded-[var(--bb-radius)] bg-[var(--bb-primary)] px-3 py-1.5 text-[var(--bb-primary-fg)] opacity-50"
+		class="rounded-(--bb-radius) bg-(--bb-primary) px-3 py-1.5 text-(--bb-primary-fg) opacity-50"
 	>
 		Disabled button
 	</BbBaseButton>
@@ -379,11 +405,11 @@ When it renders as a native button you can retune the element:
 ```vue
 <template>
 	<form
-		class="grid max-w-xs gap-2 rounded-[var(--bb-radius)] border border-[var(--bb-border)] bg-[var(--bb-panel)] p-3"
+		class="grid max-w-xs gap-2 rounded-(--bb-radius) border border-(--bb-border) bg-(--bb-panel) p-3"
 		@submit.prevent="sent = true"
 	>
 		<p class="text-sm font-medium">New workspace</p>
-		<p class="text-xs text-[color:var(--bb-text-muted)]">
+		<p class="text-xs text-(--bb-text-muted)">
 			{{
 				sent
 					? 'Submitted via the native form event.'
@@ -392,7 +418,7 @@ When it renders as a native button you can retune the element:
 		</p>
 		<BbBaseButton
 			block
-			class="rounded-[var(--bb-radius)] bg-[var(--bb-primary)] px-3 py-1.5 text-sm text-[var(--bb-primary-fg)]"
+			class="rounded-(--bb-radius) bg-(--bb-primary) px-3 py-1.5 text-sm text-(--bb-primary-fg)"
 			type="submit"
 		>
 			Create workspace
@@ -408,6 +434,34 @@ const sent = ref(false);
 </script>
 ```
 
+### Restyling with passthrough
+
+`pt` reaches the one part with a class list — or, in the object form, a
+style and attributes — optionally only while a state is on. Part: `root`
+(whichever element renders — the `<button>`, the `<a>` or the router link;
+where a `class` on the component lands too). State: `disabled`. The label is
+your slot markup, so there is no `content`; `BbButton` wraps this component
+and exposes its own vocabulary.
+
+The unstyled primitive, branded through those parts: a primary fill on
+`pt:root`, a fade on `pt:root:disabled`, underline on the anchor.
+
+**pt:root — a branded button and a branded anchor**
+
+```vue
+<div class="flex flex-wrap items-center gap-2 text-sm">
+	<BbBaseButton pt:root="rounded-(--bb-radius) bg-(--bb-primary) px-3 py-1.5 text-(--bb-primary-fg) hover:opacity-90" pt:root:disabled="opacity-40">Save draft</BbBaseButton>
+	<BbBaseButton href="https://example.com" pt:root="rounded-(--bb-radius) px-3 py-1.5 text-(--bb-primary) underline" target="_blank">Docs ↗</BbBaseButton>
+</div>
+```
+
+The full grammar, the merge rules and the global map are in the
+[passthrough guide](./guides/passthrough.md).
+
+A `pt` value written in `<script>` (a constant, a preset, a wrapper's
+`pt` prop) is typed as `BbBaseButtonProps['pt']`, never an imported `PtValue`: see
+[passthrough § Typing `pt` in `<script>`](./guides/passthrough.md#typing-pt-in-script).
+
 ### Works well with
 
 - [`BbButton`](./BbButton.md) — the variant-first sibling built on this
@@ -455,27 +509,28 @@ const sent = ref(false);
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `activeClass` | `string \| undefined` |  |  | 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` |  |  | 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` |  |  | Inertia: runs the visit without blocking — the page stays interactive and several async visits can be in flight at once. |
-| `block` | `boolean \| undefined` |  |  | Makes the component take the full available width (block-level layout). 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 in… |
+| `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: `disabled`. 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. |
+| `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). 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. |
 | `cacheTags` | `string \| string[] \| undefined` |  |  | Inertia: tags to file this visit's prefetch cache under, so a later request can invalidate the whole tagged group. |
 | `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` |  |  | 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 prevents navigation while keeping focusable semanti… |
-| `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 file… |
-| `exactActiveClass` | `string \| undefined` |  |  | 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. |
+| `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`. |
+| `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` |  |  | 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… |
+| `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`. |
 | `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. |
-| `instant` | `boolean \| undefined` |  |  | 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. |
+| `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. |
 | `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… |
+| `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. |
 | `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. |
@@ -483,20 +538,34 @@ const sent = ref(false);
 | `onProgress` | `((progress: { percentage: number \| undefined; }) => void) \| undefined` |  |  | Progress callback invoked by Inertia with the upload/download percentage when available. |
 | `onStart` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request starts. |
 | `onSuccess` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request succeeds. |
-| `pageProps` | `Record<string, unknown> \| ((currentProps: Record<string, unknown>, sharedProps: Record<string, unknown>) => Record<string, unknown>) \| null \| undefined` |  |  | Inertia: props to merge into the next page optimistically, before the server responds. Either an object or a function of the current props. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue… |
+| `pageProps` | `Record<string, unknown> \| ((currentProps: Record<string, unknown>, sharedProps: Record<string, unknown>) => Record<string, unknown>) \| null \| undefined` |  |  | Inertia: props to merge into the next page optimistically, before the server responds. Either an object or a function of the current props. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be installed. |
 | `prefetch` | `string \| boolean \| string[] \| undefined` |  |  | Inertia: fetch and cache this link's page ahead of the click. `true` uses the default trigger; a string or list of strings picks them (`'mount'`, `'hover'`, `'click'`). |
-| `preserveScroll` | `boolean \| ((props: Record<string, unknown>) => boolean) \| undefined` |  |  | Controls whether Inertia should preserve the current scroll position after navigation. Can be a boolean or a predicate receiving the visit props. |
-| `preserveState` | `boolean \| ((props: Record<string, unknown>) => boolean) \| null \| undefined` |  |  | Controls whether Inertia should preserve the current state after navigation. Can be a boolean or a predicate receiving the visit props. |
-| `preserveUrl` | `boolean \| undefined` |  |  | Inertia: keep the current URL in the address bar even though the page content changes. |
-| `queryStringArrayFormat` | `"brackets" \| "indices" \| undefined` |  |  | Format to use when serializing array values into the query string for Inertia requests. |
+| `preserveScroll` | `boolean \| ((props: Record<string, unknown>) => boolean) \| undefined` | `false` |  | Controls whether Inertia should preserve the current scroll position after navigation. Can be a boolean or a predicate receiving the visit props. |
+| `preserveState` | `boolean \| ((props: Record<string, unknown>) => boolean) \| null \| undefined` | `false` |  | Controls whether Inertia should preserve the current state after navigation. Can be a boolean or a predicate receiving the visit props. |
+| `preserveUrl` | `boolean \| undefined` | `false` |  | Inertia: keep the current URL in the address bar even though the page content changes. |
+| `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` |  |  | Uses history replacement instead of push navigation. - With Vue Router (`to`), calls `router.replace`. - With Inertia (`href`), performs a replace visit. |
-| `tag` | `ButtonTag \| undefined` |  |  | 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… |
+| `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. |
 | `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`). |
-| `viewTransition` | `boolean \| undefined` |  |  | Inertia: run the page swap inside a View Transition, where the browser supports one. |
+| `viewTransition` | `boolean \| undefined` | `false` |  | Inertia: run the page swap inside a View Transition, where the browser supports one. |
+
+## Passthrough parts and states
+
+`pt:<part>="…"` restyles a part; `pt:<part>:<state>="…"` applies only while the state is on. A component-wide state is on for every part at once; a _per node_ state resolves on each node of a broadcast part (one row, one option, one day). Grammar and merge rules: `guides/passthrough.md`. In `<script>`, type a `pt` value as `<Component>Props['pt']` (`<Component>Props<Row>['pt']` on a generic component); `PtValue` is not exported: `guides/passthrough.md` § Typing `pt` in `<script>`.
+
+| Part | What it is |
+| --- | --- |
+| `root` | Whichever element renders — the `<button>`, the `<a>` or the router link. A `class` on the component lands here too. The label is your slot markup. |
+
+States are listed in precedence order: when two are on at once and their entries conflict, the later one wins.
+
+| State | When it is on |
+| --- | --- |
+| `disabled` | Component-wide: the button is `disabled`. |
 
 ## Events
 
@@ -506,8 +575,20 @@ const sent = ref(false);
 
 - `default` — scope: `object` — Primary content rendered inside the button element. Falls back to the `text` prop when empty.
 
+## Component tree
+
+`BbBaseButton` is not one component: rendering it mounts every component below, and each one is live inside it. **Read this before styling, theming or debugging `BbBaseButton`, and before concluding a part, a token or a behaviour does not exist** — it may live on a component further down. How to read it:
+
+- **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbBaseButton`. A pt part listed as landing there is set on `BbBaseButton` (`pt:<part>`).
+- **_public_** nodes are components with their own contract. `BbBaseButton` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbBaseButton`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
+- **CSS custom properties** listed on a node are declared on THAT node's root and read by elements inside it. Set one on that node's root or on the element inside it that reads it — the pt part that lands there is how you reach it (`pt:box="[--border-color:…]"` on a text input) — never on `BbBaseButton`'s root, where the node's own declaration masks it (design-tokens guide, _Overriding one from a consumer app_, rule 0).
+- Listed nodes are the ones `BbBaseButton`'s API reaches or that declare a documented CSS variable; the rest fold into "also mounts". The complete tree, repeats and undocumented locals included, is the `tree` field of this component in `components.json`.
+
+- `BbBaseButton` _(this component)_ — its own template binds: `root` → `RouterComponent`, `root` → `a`, `root` → `component`
+  - Also mounts `RouterComponent`
+
 ## See Also
 
 - [BbButton](./BbButton.md) — Button with loading state, tooltip, and icon support.
 - [BbDropdownButton](./BbDropdownButton.md) — A button with primary action and all other actions collected in a dropdown.
-- [BbDropdown](./BbDropdown.md) — Displays contextual action menus and menu content.
+- [BbDropdown](./BbDropdown.md) — Displays contextual action menus and menu content (includes the co-located BbDropdownGroup export, which is how a selectable group is bound).

package/dist/ai/BbBaseCheckboxIcon.md

@@ -4,7 +4,7 @@
 
 - Safety level: **Consumer API**
 - Group: **Selection**
-- Description: Standalone checkbox glyph (box + checkmark SVG). Presentational only — no input, no events. Compose it into a fully custom checkbox design, or let BbCheckbox/BbBaseCheckbox render it.
+- Description: Standalone checkbox glyph (box + checkmark SVG). Presentational only — no input, no events. Compose it into a fully custom checkbox design, or let BbCheckbox, BbCheckboxGroup or BbTable render it.
 - Usage rule: Prefer this component for consumer-facing implementations.
 - Implementation source (only when the contract below is not enough): [source/BbBaseCheckboxIcon.md](./source/BbBaseCheckboxIcon.md)
 
@@ -13,7 +13,7 @@
 ### What this is (and when to reach for it)
 
 `BbBaseCheckboxIcon` is **only the visual** — the rounded box, the stroke-animated
-checkmark, and the indeterminate dash — extracted from `BbBaseCheckbox`. It has
+checkmark, and the indeterminate dash — the glyph `BbCheckbox` draws. It has
 no native `<input>`, emits no events, and holds no state. You tell it how to
 look through boolean props; it draws that state.
 
@@ -51,12 +51,10 @@ around it.
 
 ```vue
 <template>
-	<div
-		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
-	>
+	<div class="flex max-w-sm flex-col gap-2 rounded-(--bb-radius) border p-3">
 		<div class="flex flex-col gap-0.5">
 			<p class="text-sm font-medium">Invoice alerts</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Northwind · overdue notices for INV-1042 and later
 			</p>
 		</div>
@@ -66,11 +64,11 @@ around it.
 			<label
 				v-for="channel in channels"
 				:key="channel.id"
-				class="flex cursor-pointer items-center gap-2.5 rounded-[var(--bb-radius)] border p-2.5 transition-colors"
+				class="flex cursor-pointer items-center gap-2.5 rounded-(--bb-radius) border p-2.5 transition-colors"
 				:class="
 					selected.includes(channel.id)
-						? 'border-[color:var(--bb-primary)] bg-[color:var(--bb-muted)]'
-						: 'border-[color:var(--bb-border)] hover:bg-[color:var(--bb-surface-hover)]'
+						? 'border-(--bb-primary) bg-(--bb-muted)'
+						: 'border-(--bb-border) hover:bg-(--bb-surface-hover)'
 				"
 			>
 				<!-- Glyph is decorative; the sr-only input owns focus, keyboard, and form state. -->
@@ -83,9 +81,7 @@ around it.
 				<BbBaseCheckboxIcon :checked="selected.includes(channel.id)" />
 				<span class="flex min-w-0 flex-col">
 					<span class="text-sm font-medium">{{ channel.label }}</span>
-					<span class="text-xs text-[color:var(--bb-text-muted)]">{{
-						channel.hint
-					}}</span>
+					<span class="text-xs text-(--bb-text-muted)">{{ channel.hint }}</span>
 				</span>
 			</label>
 		</fieldset>
@@ -110,21 +106,38 @@ const selected = ref<string[]>(['email']);
 
 ### Styling
 
-The glyph owns its own tokens, so restyle it by overriding CSS custom properties
-on the element (or an ancestor — they inherit):
+The glyph owns its own tokens, so restyle it by overriding CSS custom
+properties on it:
 
 - `--size` — box edge length (default `16px`)
 - `--r` — corner radius (default `4px`)
-- `--color` — fill + border when checked/indeterminate (default `--bb-primary`)
+- `--accent` — fill + border when checked/indeterminate (default `--bb-primary`)
 - `--check-color` — checkmark stroke (default `--bb-primary-fg`)
 - `--ring-color` — focus ring color
 
+**On the element itself, not an ancestor.** Each of these is declared on the
+glyph's own class, and a declaration on the element always beats one inherited
+from an ancestor — so `--size` set on a wrapper `div` is simply ignored
+(verified: the glyph stays 16px). Target the glyph class, or pass a `style` /
+`class` that lands on it:
+
+```css
+/* works */
+.bb-base-checkbox-icon {
+	--size: 20px;
+}
+/* does nothing */
+.my-form {
+	--size: 20px;
+}
+```
+
 **Bigger, rounder, recolored**
 
 ```vue
 <BbBaseCheckboxIcon
 	:checked="true"
-	style="--size: 28px; --r: 999px; --color: #16a34a"
+	style="--size: 28px; --r: 999px; --accent: #16a34a"
 />
 ```
 
@@ -141,6 +154,47 @@ on the element (or an ancestor — they inherit):
 - It reflects state, it doesn't manage it: clicking the glyph does nothing by
   itself. Toggle your own state (or the backing input) and pass it back in.
 
+### Restyling with passthrough
+
+`pt` reaches the one part with a class list — or, in the object form, a
+style and attributes. Part: `root` (the drawn glyph). States: `checked`, `indeterminate`, `readonly`, `disabled`, `warnings`, `errors`, `focused`, `focusVisible` — each
+true exactly while the glyph paints it, so they follow its own rules:
+`warnings` is off while `errors` is on.
+
+Restyle by setting the glyph's own tokens (`--accent`, `--size`) on the part, and
+style a state with a state entry instead of a ternary on your own flag —
+the component decides when the state is on, and a global preset can say the
+same thing.
+
+The accent is the glyph's text colour, as on any icon: a `text-*` utility or a
+`color` on the part recolours the checked and indeterminate fill, and `--accent` sets the default. A
+state keeps its own paint — an error, a warning or a disabled glyph is never
+recoloured by a text colour, even one in `pt:root:errors` (the
+`bitboss-ui/no-state-text-color` lint says so). Recolour an error or a warning
+through the accent: `pt:root:errors="[--accent:var(--color-red-800)]"`.
+
+**pt:root and pt:root:disabled — a token, and a state entry**
+
+```vue
+<div class="flex items-center gap-3">
+	<BbBaseCheckboxIcon :pt:root="{ style: { '--accent': 'var(--bb-danger)', '--size': '20px' } }" />
+	<BbBaseCheckboxIcon checked :pt:root="{ style: { '--accent': 'var(--bb-danger)', '--size': '20px' } }" />
+	<BbBaseCheckboxIcon
+		checked
+		disabled
+		:pt:root="{ style: { '--accent': 'var(--bb-danger)', '--size': '20px' } }"
+		:pt:root:disabled="{ style: { opacity: '0.45' } }"
+	/>
+</div>
+```
+
+The full grammar, the merge rules and the global map are in the
+[passthrough guide](./guides/passthrough.md).
+
+A `pt` value written in `<script>` (a constant, a preset, a wrapper's
+`pt` prop) is typed as `BbBaseCheckboxIconProps['pt']`, never an imported `PtValue`: see
+[passthrough § Typing `pt` in `<script>`](./guides/passthrough.md#typing-pt-in-script).
+
 ### Works well with
 
 - [`BbCheckbox`](./BbCheckbox.md) — the batteries-included checkbox; prefer it
@@ -152,13 +206,36 @@ on the element (or an ancestor — they inherit):
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `checked` | `boolean \| undefined` |  |  | Renders the checked state (fills the box and draws the checkmark). |
-| `disabled` | `boolean \| undefined` |  |  | Disables the glyph (muted fill, not-allowed cursor). Purely visual. |
-| `focusVisible` | `boolean \| undefined` |  |  | Whether keyboard focus is visible (`:focus-visible`). Draws the focus ring. |
-| `hasErrors` | `boolean \| undefined` |  |  | Puts the glyph into the error state (danger border and ring color). |
-| `hasWarning` | `boolean \| undefined` |  |  | Puts the glyph into the warning state (warn border and ring color). Errors take priority when both are set. |
-| `indeterminate` | `boolean \| undefined` |  |  | Renders the indeterminate state (filled box with a dash instead of the checkmark). Takes visual precedence over `checked`. |
-| `readonly` | `boolean \| undefined` |  |  | Renders the read-only affordance (default cursor instead of pointer). |
+| `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: `checked`, `disabled`, `errors`, `focused`, `focusVisible`, `indeterminate`, `readonly`, `warnings`. 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 `BbBaseCheckboxIconProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+| `checked` | `boolean \| undefined` | `false` |  | Renders the checked state (fills the box and draws the checkmark). |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the glyph (muted fill, not-allowed cursor). Purely visual. |
+| `focused` | `boolean \| undefined` | `false` |  | Whether the paired native input has focus — any focus, mouse included. Paints `--focused`, the hook the `focused` passthrough state aliases (T19); draws nothing by itself — the ring stays on `focusVisible`. |
+| `focusVisible` | `boolean \| undefined` | `false` |  | Whether keyboard focus is visible (`:focus-visible`). Draws the focus ring. |
+| `hasErrors` | `boolean \| undefined` | `false` |  | Puts the glyph into the error state (danger border and ring color). |
+| `hasWarnings` | `boolean \| undefined` | `false` |  | Puts the glyph into the warning state (warn border and ring color). Errors take priority when both are set. |
+| `indeterminate` | `boolean \| undefined` | `false` |  | Renders the indeterminate state (filled box with a dash instead of the checkmark). Takes visual precedence over `checked`. |
+| `readonly` | `boolean \| undefined` | `false` |  | Renders the read-only affordance (default cursor instead of pointer). |
+
+## Passthrough parts and states
+
+`pt:<part>="…"` restyles a part; `pt:<part>:<state>="…"` applies only while the state is on. A component-wide state is on for every part at once; a _per node_ state resolves on each node of a broadcast part (one row, one option, one day). Grammar and merge rules: `guides/passthrough.md`. In `<script>`, type a `pt` value as `<Component>Props['pt']` (`<Component>Props<Row>['pt']` on a generic component); `PtValue` is not exported: `guides/passthrough.md` § Typing `pt` in `<script>`.
+
+| Part | What it is |
+| --- | --- |
+| `root` | The drawn glyph — the box and its checkmark. Its states are the conditions it paints as it resolves them (`warnings` is off while `errors` is on), not the raw props. |
+
+States are listed in precedence order: when two are on at once and their entries conflict, the later one wins.
+
+| State | When it is on |
+| --- | --- |
+| `checked` | Component-wide: the toggle is on. |
+| `indeterminate` | Component-wide: the mixed state (the `indeterminate` prop) — neither on nor off. |
+| `readonly` | Component-wide: the toggle is `readonly` — focusable, cannot change. |
+| `disabled` | Component-wide: the toggle is `disabled`. |
+| `warnings` | Component-wide: the toggle shows warnings and no errors. |
+| `errors` | Component-wide: the toggle shows errors — the glyph and the message line turn red. |
+| `focused` | Component-wide: the native input has focus — any focus, mouse included, like the `focused` slot prop. |
+| `focusVisible` | Component-wide: that focus is keyboard-visible — where a focus ring belongs. |
 
 ## Events
 
@@ -168,9 +245,24 @@ on the element (or an ancestor — they inherit):
 
 - None.
 
+## CSS custom properties
+
+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 |
+| --- | --- | --- |
+| `--accent` | `var(--bb-primary)` |  |
+| `--check-color` | `var(--bb-primary-fg)` |  |
+| `--size` | `16px` |  |
+| `--r` | `min(4px, var(--bb-radius))` | The checkbox corner, capped by the master radius so a zero- or small-radius theme reaches it. Not `--bb-radius-sm`: that tier is 4.8px at the shipped radius and this glyph ships at 4px. |
+| `--ring-color` | `var(--bb-ring)` | The focus ring's colour, re-pointed by errors and warnings. Both ring declarations read it, so a focused glyph grows its ring in its own colour instead of tweening from a different one. |
+| `--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)` |  |
+
 ## See Also
 
 - [BbCheckbox](./BbCheckbox.md) — Toggles a single boolean option.
-- [BbBaseCheckbox](./BbBaseCheckbox.md) — Internal low-level checkbox primitive.
-- [BbBaseRadioIcon](./BbBaseRadioIcon.md) — Standalone radio glyph (ring + dot). Presentational only — no input, no events. Compose it into a fully custom radio design, or let BbRadio/BbBaseRadio render it.
-- [BbBaseSwitchIcon](./BbBaseSwitchIcon.md) — Standalone switch glyph (track + thumb). Presentational only — no input, no events. Compose it into a fully custom switch design, or let BbSwitch/BbBaseSwitch render it.
+- [BbCheckboxGroup](./BbCheckboxGroup.md) — Manages multiple checkbox options as a group.
+- [BbBaseRadioIcon](./BbBaseRadioIcon.md) — Standalone radio glyph (ring + dot). Presentational only — no input, no events. Compose it into a fully custom radio design, or let BbRadio, BbRadioGroup or BbTable render it.
+- [BbBaseSwitchIcon](./BbBaseSwitchIcon.md) — Standalone switch glyph (track + thumb). Presentational only — no input, no events. Compose it into a fully custom switch design, or let BbSwitch or BbSwitchGroup render it.