bitboss-ui 3.0.0-beta.25 → 3.0.0-beta.26

package/dist/ai/BbBadge.md

@@ -8,6 +8,21 @@
 - Usage rule: Prefer this component for consumer-facing implementations.
 - Implementation source (only when the contract below is not enough): [source/BbBadge.md](./source/BbBadge.md)
 
+## Reachable through `BbBadge`
+
+`BbBadge` mounts other components (all of them: _Component tree_, near the end). These are the parts of its API that land inside them. Use them — never `:deep()` on an inner class, never an import of an internal component.
+
+| pt part | Lands on | In |
+| --- | --- | --- |
+| `pt:spinner` | the root of `BbSpinner` | `BbSpinner` ([contract](./BbSpinner.md)) |
+| `pt:icon` | the root of `BbIcon` | `BbIcon` ([contract](./BbIcon.md)) |
+
+**CSS variables you can set through those parts** — declared deeper in the tree, so set one on the part that reads it (`pt:<part>="[--name:value]"`), never on `BbBadge`'s root:
+
+| Variable | Set through | Declared by | What it is |
+| --- | --- | --- | --- |
+| `--w` | `pt:icon` | `BbIcon` | `--w` is set inline by BbIcon from the size prop. The `initial` default seals it: without it an ancestor's `--w` (e.g. a dropdown's width bridge) would inherit in and size the icon. The `--size` indir… |
+
 ## Usage & Guidelines
 
 ### When to use
@@ -651,6 +666,125 @@ glyph. The class hooks above are the supported styling surface —
 `.bb-badge__body` and `.bb-badge__trailing` are new, so avoid direct-child
 selectors like `.bb-badge > .bb-badge__content`, which no longer match.
 
+### Restyling with passthrough
+
+`pt` reaches a named part with a class list — or, in the object form, a
+style and attributes — optionally only while a state is on. Parts: `root`,
+`icon` (every content glyph — the `icon`-mode glyph, `prepend:icon`,
+`append:icon`; a broadcast), `spinner` (the loading glyph, which stands in
+for whichever icon it replaces), `text` (the label span, which owns the
+truncation) and `clear` (the ✕ that removes the badge). The `__body` wrapper
+is layout, not a part. State: `loading`.
+
+Invoice API method pills, restyled through those parts: `pt:icon` is a
+broadcast (prepend, append, and the loading spinner all recede),
+`pt:text` is the method label in mono. Soft method hues are status — see
+[design language](./guides/design-language.md) § Using color — not a pt
+costume.
+
+**pt:icon — method badges, a broadcast**
+
+```vue
+<template>
+	<div class="max-w-2xl">
+		<ul class="flex flex-col gap-1.5 text-sm">
+			<li
+				v-for="endpoint in endpoints"
+				:key="`${endpoint.method}:${endpoint.path}`"
+				class="flex min-w-0 items-center gap-2"
+			>
+				<BbBadge
+					:append:icon="endpoint.append"
+					:prepend:icon="endpoint.icon"
+					pt:icon="opacity-70"
+					pt:text="font-mono"
+					size="lg"
+					:variant="METHOD_VARIANT[endpoint.method]"
+					>{{ endpoint.method }}</BbBadge
+				>
+				<code class="truncate font-mono text-xs">{{ endpoint.path }}</code>
+			</li>
+		</ul>
+		<div class="mt-3 flex items-center gap-2 text-xs text-(--bb-text-muted)">
+			<BbBadge
+				loading
+				prepend:icon="lucide:plus"
+				pt:icon="opacity-40"
+				pt:text="font-mono"
+				size="lg"
+				variant="soft-green"
+				>POST</BbBadge
+			>
+			<span>
+				Saving a draft — the spinner takes the prepend slot, same
+				<code>pt:icon</code>.
+			</span>
+		</div>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbBadge } from 'bitboss-ui';
+import type { BbBadgeProps, IconType } from 'bitboss-ui';
+
+type Method = 'GET' | 'POST' | 'DELETE';
+
+type Endpoint = {
+	method: Method;
+	path: string;
+	icon: IconType;
+	append?: IconType;
+};
+
+// Soft status palette — method hue, not action intent (no primary/destructive).
+const METHOD_VARIANT: Record<Method, BbBadgeProps['variant']> = {
+	GET: 'soft-blue',
+	POST: 'soft-green',
+	DELETE: 'soft-red',
+};
+
+// Invoice API methods, restyled through passthrough: `pt:icon` is a broadcast
+// (prepend, append, and the loading spinner all recede), `pt:text` is the
+// method label in mono. The ✕ of a clearable badge is its own part, `clear`.
+const endpoints: Endpoint[] = [
+	{ method: 'GET', path: '/v1/invoices', icon: 'lucide:download' },
+	{
+		method: 'POST',
+		path: '/v1/invoices',
+		icon: 'lucide:plus',
+		append: 'lucide:arrow-right',
+	},
+	{ method: 'DELETE', path: '/v1/invoices/:id', icon: 'lucide:trash-2' },
+];
+</script>
+
+<!-- Soft status palette — canonical source: ai/guides/design-language.md § Using color.
+     Non-scoped so variant classes on the child badge receive the accents. -->
+<style>
+.bb-badge.bb-badge--soft-blue {
+	--accent: #2563eb;
+}
+.bb-badge.bb-badge--soft-green {
+	--accent: #16a34a;
+}
+.bb-badge.bb-badge--soft-red {
+	--accent: #dc2626;
+}
+.bb-badge.bb-badge--soft-blue,
+.bb-badge.bb-badge--soft-green,
+.bb-badge.bb-badge--soft-red {
+	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
+	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
+	--border-width: 1px;
+	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
+	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
+}
+</style>
+```
+
+The full grammar, the merge rules and the global map are in the
+[passthrough guide](./guides/passthrough.md).
+
 ### Works well with
 
 - `BbBadgeButton` — the companion that makes the badge body a real button/link.
@@ -705,6 +839,7 @@ selectors like `.bb-badge > .bb-badge__content`, which no longer match.
 
 | 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: `clear`, `icon`, `root`, `spinner`, `text`. States: `loading`. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `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 ever… |
@@ -724,26 +859,39 @@ selectors like `.bb-badge > .bb-badge__content`, which no longer match.
 
 ## 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; 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 |
-| --- | --- | --- |
-| `--bg` | `var(--bb-primary)` | pill fill |
-| `--fg` | `var(--bb-primary-fg)` | label, icons and the clear glyph |
-| `--border-width` | `0px` | Pill border. The `border` shorthand is always present, so the width is what turns it on — the filled variants leave it at 0 and the bordered ones (secondary/destructive/outline) step up to `--bb-border-w-sm`. Nothing compensates for it: the… |
-| `--border-color` | `transparent` |  |
-| `--ring` | `var(--bb-primary-ring)` | focus ring, per variant |
-| `--min-size-md` | `16px` | The md value. Only the default --min-size below reads it; the size modifiers set --min-size directly. |
-| `--min-size` | `var(--min-size-md)` | pill min height and min width |
-| `--elev` | `var(--bb-elev-sm)` | Resting lift. Invisible while `--bb-elev` is its default transparent layer. A chip is small enough that a theme wanting a different lift here than on a button sets `--elev` on this class. |
-| `--radius` | `calc(var(--bb-radius) * 0.5)` | Pill corners; the body and trailing wrappers round their outer edges to match |
-| `--font-size` | `10px` | label |
-| `--icon-size` | `12px` | leading/append icons (passed to BbIcon as --size) |
-| `--gap` | `3px` | space between label, icons and the trailing side |
-| `--padding-inline` | `6px` | base side padding; the modifiers below scale it per side |
-| `--clear-size` | `12px` | clear button's glyph box (the circle painted on hover is 2px smaller) |
-| `--pad-left` | `var(--padding-inline)` | 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` | `var(--padding-inline)` |  |
+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 | Set on | Default | What it is |
+| --- | --- | --- | --- |
+| `--bg` | `.bb-badge` | `var(--bb-primary)` | pill fill |
+| `--fg` | `.bb-badge` | `var(--bb-primary-fg)` | label, icons and the clear glyph |
+| `--border-width` | `.bb-badge` | `0px` | Pill border. The `border` shorthand is always present, so the width is what turns it on — the filled variants leave it at 0 and the bordered ones (secondary/destructive/outline) step up to `--bb-border-w-sm`. Nothing compensates for it: the… |
+| `--border-color` | `.bb-badge` | `transparent` |  |
+| `--ring` | `.bb-badge` | `var(--bb-primary-ring)` | focus ring, per variant |
+| `--min-size-md` | `.bb-badge` | `16px` | The md value. Only the default --min-size below reads it; the size modifiers set --min-size directly. |
+| `--min-size` | `.bb-badge` | `var(--min-size-md)` | pill min height and min width |
+| `--elev` | `.bb-badge` | `var(--bb-elev-sm)` | Resting lift. Invisible while `--bb-elev` is its default transparent layer. A chip is small enough that a theme wanting a different lift here than on a button sets `--elev` on this class. |
+| `--radius` | `.bb-badge` | `calc(var(--bb-radius) * 0.5)` | Pill corners; the body and trailing wrappers round their outer edges to match |
+| `--font-size` | `.bb-badge` | `10px` | label |
+| `--icon-size` | `.bb-badge` | `12px` | leading/append icons (passed to BbIcon as --size) |
+| `--gap` | `.bb-badge` | `3px` | space between label, icons and the trailing side |
+| `--padding-inline` | `.bb-badge` | `6px` | base side padding; the modifiers below scale it per side |
+| `--clear-size` | `.bb-badge` | `12px` | clear button's glyph box (the circle painted on hover is 2px smaller) |
+| `--pad-left` | `.bb-badge` | `var(--padding-inline)` | 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(--padding-inline)` |  |
+| `--size` | `.bb-badge__icon` | `var(--icon-size)` |  |
+
+## Component tree
+
+`BbBadge` is not one component: rendering it mounts every component below, and each one is live inside it. **Read this before styling, theming or debugging `BbBadge`, 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 `BbBadge`. A pt part listed as landing there is set on `BbBadge` (`pt:<part>`).
+- **_public_** nodes are components with their own contract. `BbBadge` 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 `BbBadge`'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 `BbBadge`'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 `BbBadge`'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`.
+
+- `BbBadge` _(this component)_ — its own template binds: `spinner` → `BbSpinner`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear-button`
+  - Also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
 
 ## See Also
 

package/dist/ai/BbBadgeButton.md

@@ -12,6 +12,7 @@
 
 | 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: `root`. States: `disabled`. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `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. |
@@ -63,26 +64,40 @@
 
 ## 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; 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 |
-| --- | --- | --- |
-| `--bg` | `var(--bb-primary)` | pill fill |
-| `--fg` | `var(--bb-primary-fg)` | label, icons and the clear glyph |
-| `--border-width` | `0px` | Pill border. The `border` shorthand is always present, so the width is what turns it on — the filled variants leave it at 0 and the bordered ones (secondary/destructive/outline) step up to `--bb-border-w-sm`. Nothing compensates for it: the… |
-| `--border-color` | `transparent` |  |
-| `--ring` | `var(--bb-primary-ring)` | focus ring, per variant |
-| `--min-size-md` | `16px` | The md value. Only the default --min-size below reads it; the size modifiers set --min-size directly. |
-| `--min-size` | `var(--min-size-md)` | pill min height and min width |
-| `--elev` | `var(--bb-elev-sm)` | Resting lift. Invisible while `--bb-elev` is its default transparent layer. A chip is small enough that a theme wanting a different lift here than on a button sets `--elev` on this class. |
-| `--radius` | `calc(var(--bb-radius) * 0.5)` | Pill corners; the body and trailing wrappers round their outer edges to match |
-| `--font-size` | `10px` | label |
-| `--icon-size` | `12px` | leading/append icons (passed to BbIcon as --size) |
-| `--gap` | `3px` | space between label, icons and the trailing side |
-| `--padding-inline` | `6px` | base side padding; the modifiers below scale it per side |
-| `--clear-size` | `12px` | clear button's glyph box (the circle painted on hover is 2px smaller) |
-| `--pad-left` | `var(--padding-inline)` | 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` | `var(--padding-inline)` |  |
+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 | Set on | Default | What it is |
+| --- | --- | --- | --- |
+| `--bg` | `.bb-badge` | `var(--bb-primary)` | pill fill |
+| `--fg` | `.bb-badge` | `var(--bb-primary-fg)` | label, icons and the clear glyph |
+| `--border-width` | `.bb-badge` | `0px` | Pill border. The `border` shorthand is always present, so the width is what turns it on — the filled variants leave it at 0 and the bordered ones (secondary/destructive/outline) step up to `--bb-border-w-sm`. Nothing compensates for it: the… |
+| `--border-color` | `.bb-badge` | `transparent` |  |
+| `--ring` | `.bb-badge` | `var(--bb-primary-ring)` | focus ring, per variant |
+| `--min-size-md` | `.bb-badge` | `16px` | The md value. Only the default --min-size below reads it; the size modifiers set --min-size directly. |
+| `--min-size` | `.bb-badge` | `var(--min-size-md)` | pill min height and min width |
+| `--elev` | `.bb-badge` | `var(--bb-elev-sm)` | Resting lift. Invisible while `--bb-elev` is its default transparent layer. A chip is small enough that a theme wanting a different lift here than on a button sets `--elev` on this class. |
+| `--radius` | `.bb-badge` | `calc(var(--bb-radius) * 0.5)` | Pill corners; the body and trailing wrappers round their outer edges to match |
+| `--font-size` | `.bb-badge` | `10px` | label |
+| `--icon-size` | `.bb-badge` | `12px` | leading/append icons (passed to BbIcon as --size) |
+| `--gap` | `.bb-badge` | `3px` | space between label, icons and the trailing side |
+| `--padding-inline` | `.bb-badge` | `6px` | base side padding; the modifiers below scale it per side |
+| `--clear-size` | `.bb-badge` | `12px` | clear button's glyph box (the circle painted on hover is 2px smaller) |
+| `--pad-left` | `.bb-badge` | `var(--padding-inline)` | 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(--padding-inline)` |  |
+| `--size` | `.bb-badge__icon` | `var(--icon-size)` |  |
+
+## Component tree
+
+`BbBadgeButton` is not one component: rendering it mounts every component below, and each one is live inside it. **Read this before styling, theming or debugging `BbBadgeButton`, 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 `BbBadgeButton`. A pt part listed as landing there is set on `BbBadgeButton` (`pt:<part>`).
+- **_public_** nodes are components with their own contract. `BbBadgeButton` 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 `BbBadgeButton`'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 `BbBadgeButton`'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 `BbBadgeButton`'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`.
+
+- `BbBadgeButton` _(this component)_
+  - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
+  - Also mounts `BadgeBodyContent`
 
 ## See Also
 

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. Use them — never `:deep()` on an inner class, 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
@@ -406,6 +414,30 @@ 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).
+
 ### Works well with
 
 - [`BbButton`](./BbButton.md) — the variant-first sibling built on this
@@ -453,6 +485,7 @@ const sent = ref(false);
 
 | 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: `root`. States: `disabled`. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `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. |
@@ -504,6 +537,18 @@ 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.

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.
 
@@ -154,6 +154,43 @@ from an ancestor — so `--size` set on a wrapper `div` is simply ignored
 - 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`, `focus-visible` — 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).
+
 ### Works well with
 
 - [`BbCheckbox`](./BbCheckbox.md) — the batteries-included checkbox; prefer it
@@ -165,11 +202,13 @@ from an ancestor — so `--size` set on a wrapper `div` is simply ignored
 
 | 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: `root`. States: `checked`, `disabled`, `errors`, `focus-visible`, `focused`, `indeterminate`, `readonly`, `warnings`. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `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). |
-| `hasWarning` | `boolean \| undefined` | `false` |  | Puts the glyph into the warning state (warn border and ring color). Errors take priority when both are set. |
+| `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). |
 
@@ -183,7 +222,7 @@ from an ancestor — so `--size` set on a wrapper `div` is simply ignored
 
 ## 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; the global `--bb-*` theme tokens are a separate tier (see the [design-tokens guide](./guides/design-tokens.md), or the MCP `list_tokens` tool).
+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 |
 | --- | --- | --- |
@@ -191,7 +230,7 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--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)` |  |
+| `--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'… |
 | `--border-color` | `var(--bb-border)` |  |
@@ -199,6 +238,6 @@ Set these on the element, or on a class you put on it, to retune this component
 ## 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.

package/dist/ai/BbBaseRadioIcon.md

@@ -4,7 +4,7 @@
 
 - Safety level: **Consumer API**
 - Group: **Selection**
-- Description: 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.
+- Description: 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.
 - Usage rule: Prefer this component for consumer-facing implementations.
 - Implementation source (only when the contract below is not enough): [source/BbBaseRadioIcon.md](./source/BbBaseRadioIcon.md)
 
@@ -13,7 +13,7 @@
 ### What this is (and when to reach for it)
 
 `BbBaseRadioIcon` is **only the visual** — the bordered ring and the scaling inner
-dot — extracted from `BbBaseRadio`. It has no native `<input>`, emits no events,
+dot — the glyph `BbRadio` 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.
 
@@ -168,6 +168,43 @@ from an ancestor — so `--size` set on a wrapper `div` is simply ignored
 - It reflects state, it doesn't manage it: clicking the glyph does nothing by
   itself. Drive your own state (or the backing inputs) and pass `checked` back.
 
+### 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`, `readonly`, `disabled`, `warnings`, `errors`, `focused`, `focus-visible` — 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 dot, 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">
+	<BbBaseRadioIcon :pt:root="{ style: { '--accent': 'var(--bb-danger)', '--size': '20px' } }" />
+	<BbBaseRadioIcon checked :pt:root="{ style: { '--accent': 'var(--bb-danger)', '--size': '20px' } }" />
+	<BbBaseRadioIcon
+		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).
+
 ### Works well with
 
 - [`BbRadio`](./BbRadio.md) / [`BbRadioGroup`](./BbRadioGroup.md) — the
@@ -180,11 +217,13 @@ from an ancestor — so `--size` set on a wrapper `div` is simply ignored
 
 | 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: `root`. States: `checked`, `disabled`, `errors`, `focus-visible`, `focused`, `readonly`, `warnings`. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `checked` | `boolean \| undefined` | `false` |  | Renders the checked state (grows the inner dot). |
 | `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). |
-| `hasWarning` | `boolean \| undefined` | `false` |  | Puts the glyph into the warning state (warn border and ring color). Errors take priority when both are set. |
+| `hasWarnings` | `boolean \| undefined` | `false` |  | Puts the glyph into the warning state (warn border and ring color). Errors take priority when both are set. |
 | `readonly` | `boolean \| undefined` | `false` |  | Renders the read-only affordance (default cursor instead of pointer). |
 
 ## Events
@@ -197,7 +236,7 @@ from an ancestor — so `--size` set on a wrapper `div` is simply ignored
 
 ## 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; the global `--bb-*` theme tokens are a separate tier (see the [design-tokens guide](./guides/design-tokens.md), or the MCP `list_tokens` tool).
+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 |
 | --- | --- | --- |
@@ -212,6 +251,6 @@ Set these on the element, or on a class you put on it, to retune this component
 ## See Also
 
 - [BbRadio](./BbRadio.md) — Represents a single choice in exclusive options.
-- [BbBaseRadio](./BbBaseRadio.md) — Internal low-level radio primitive.
-- [BbBaseCheckboxIcon](./BbBaseCheckboxIcon.md) — 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.
-- [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.
+- [BbRadioGroup](./BbRadioGroup.md) — Coordinates exclusive selection among radio options.
+- [BbBaseCheckboxIcon](./BbBaseCheckboxIcon.md) — 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.
+- [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.