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

package/dist/ai/BbRadio.md

@@ -8,6 +8,26 @@
 - Usage rule: Prefer this component for consumer-facing implementations.
 - Implementation source (only when the contract below is not enough): [source/BbRadio.md](./source/BbRadio.md)
 
+## Reachable through `BbRadio`
+
+`BbRadio` 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:icon` | the root of `BbBaseRadioIcon` | `BbBaseRadioIcon` ([contract](./BbBaseRadioIcon.md)) |
+| `pt:root` | `div.bb-field` | `CommonField` _(internal)_ |
+| `pt:label` | `component` | `CommonField` _(internal)_ |
+| `pt:description` | `span.bb-field__description` | `CommonField` _(internal)_ |
+| `pt:hint` | `span.bb-field__hint` | `CommonField` _(internal)_ |
+| `pt:message` | `div.bb-field__message` | `CommonField` _(internal)_ |
+
+**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 `BbRadio`'s root:
+
+| Variable | Set through | Declared by | What it is |
+| --- | --- | --- | --- |
+| `--elev` | `pt:icon` | `BbBaseRadioIcon` | Same resting lift as the checkbox glyph — see BbBaseCheckboxIcon. |
+| `--bg` | `pt:icon` | `BbBaseRadioIcon` | 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. |
+
 ## Usage & Guidelines
 
 ### When to use
@@ -50,18 +70,18 @@ name (see Accessibility).
 	>
 		<div class="flex flex-col gap-0.5">
 			<p class="text-sm font-medium">Workspace plan</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				Billed monthly · cancel anytime
 			</p>
 		</div>
 		<div
 			v-for="plan in plans"
 			:key="plan.value"
-			class="flex items-start justify-between gap-3 rounded-[var(--bb-radius)] border p-2.5"
+			class="flex items-start justify-between gap-3 rounded-(--bb-radius) border p-2.5"
 			:class="
 				selected === plan.value
-					? 'border-[color:var(--bb-primary)]'
-					: 'border-[color:var(--bb-border)]'
+					? 'border-(--bb-primary)'
+					: 'border-(--bb-border)'
 			"
 		>
 			<BbRadio
@@ -75,7 +95,7 @@ name (see Accessibility).
 				{{ plan.price }}
 			</span>
 		</div>
-		<p class="plan-summary text-xs text-[color:var(--bb-text-muted)]">
+		<p class="plan-summary text-xs text-(--bb-text-muted)">
 			Selected plan: {{ selected }}
 		</p>
 	</div>
@@ -138,16 +158,21 @@ amber counterpart of `errors` — a string or array rendered below the button in
 its own `aria-live="polite"` region (also referenced from `aria-describedby`
 while displayed) for a valid-but-noteworthy value where a hard
 error would overstate the problem, and a non-empty `warnings` implies the warning
-state just as `errors` implies the error state; **`has-warning`** forces that
+state just as `errors` implies the error state; **`has-warnings`** forces that
 amber chrome without a message. Unlike `has-errors`, neither sets `aria-invalid` —
 a soft "needs a second look" rather than an invalid state — and `has-errors` wins
 when both are set, suppressing the warning messages so the button never shows
 amber and red at once.
 
+`BbRadio` does **not** join a `BbForm` on its own (BbCheckbox and BbSwitch
+do): validate an exclusive choice with `BbRadioGroup`. For
+radios composed by hand, pass `errors` yourself, or bind the choice with
+`useBbFormField` (see the validated-forms guide).
+
 **Readonly, error and disabled**
 
 ```vue
-<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-3">
+<div class="grid max-w-sm gap-2 rounded-(--bb-radius) border p-3">
 	<BbRadio
 		:model-value="'locked'"
 		value="locked"
@@ -207,12 +232,12 @@ individual `BbRadio` buttons.
 <template>
 	<div
 		aria-label="Merge method"
-		class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-3"
+		class="grid max-w-sm gap-2 rounded-(--bb-radius) border p-3"
 		role="radiogroup"
 	>
 		<div class="flex flex-col gap-0.5">
 			<p class="text-sm font-medium">Merge pull request #482</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				feature/invoice-export → main
 			</p>
 		</div>
@@ -244,7 +269,7 @@ individual `BbRadio` buttons.
 			name="merge-method"
 			value="rebase"
 		/>
-		<p class="merge-summary text-xs text-[color:var(--bb-text-muted)]">
+		<p class="merge-summary text-xs text-(--bb-text-muted)">
 			Pull request #482 will be merged via {{ labels[strategy] }}.
 		</p>
 	</div>
@@ -273,17 +298,21 @@ ring itself.
 
 ### Layout
 
-- `direction` defaults to `'auto'` (label and button size to content, one line);
+- `compact` tightens the field's label spacing (`--bb-label-spacing-y-compact` instead of `--bb-label-spacing-y`), the same as on the groups — for dense forms and settings panels.
+- `layout` defaults to `'auto'` (label and button size to content, one line);
   `'horizontal'` / `'vertical'` / a pattern like `'xx xxxxx'` split them
-  proportionally.
+  proportionally. `'label-fill'` hands the label the free space and keeps the
+  button at its own size (add `reverse` for label-left, button-right);
+  `'input-fill'` is the other way round.
 - `input-position` / `label-position` (`'left' | 'center' | 'right'`) align the
   button and label text within their columns.
 - `hide-label` keeps the label for screen readers but hides it visually.
-- **`reverse` is inverted.** The prop is wired through an internal negation, so a
-  `BbRadio` is "reversed" by default and `:reverse="false"` is identical to
-  omitting it. Treat `reverse` as a swap-order switch you turn **on**, not a
-  boolean you can turn off. (Same quirk as standalone `BbCheckbox`; the _group_
-  components don't have it.)
+- **`reverse`** swaps the label in front of the button. It is an ordinary
+  opt-in boolean: unset and `:reverse="false"` both put the button first,
+  `reverse` puts the label first. (The source negates it internally to cancel
+  `CommonField`'s own polarity; that is invisible from outside.
+  Earlier revisions of this guide called it a consumer-facing quirk — it is
+  not, and the same correction applies to `BbCheckbox` and `BbSwitch`.)
 
 ### Events and focus
 
@@ -292,6 +321,127 @@ only selection-of-truth channel. The native `blur`, `change`, `click`, `focus`,
 `input`, `keydown`, `mousedown`, `mouseup` events re-emit with raw payloads;
 listen to them for side concerns only. `autofocus` focuses the input on mount.
 
+**Controlled or not.** Pass a value — `v-model`, `:model-value` or `checked` —
+and the control shows exactly that value: a click emits `update:modelValue`
+and the control moves only when the parent applies it, so a parent that
+ignores the update never shows a state its data does not hold. Pass neither
+(a plain form field posted by `name`) and it keeps the click itself, like a
+native radio (a controlled radio also puts its same-name siblings back).
+
+### Restyling with passthrough
+
+`pt` reaches a named part of the control with a class list — or, in the
+object form, a style and attributes — optionally only while a state is on. A
+toggle has no box: parts are `root` (the container), `label`, `description`,
+`message`, `hint` (the helper line — shown on focus, or always with `persistent-hint`) and `icon` (the drawn
+glyph — the default one; a consumer `icon` slot replaces it and receives
+nothing). States: `errors`, `warnings`, `disabled`, `readonly`, `checked`
+(checked) and `focused` — true while the native input has focus, ANY focus,
+mouse included, in parity with the `focused` slot prop (keyboard-only styling
+stays on the library's own `--focus-visible` class). A name outside that list
+is a type error and an ESLint error.
+
+The merge-method list above, restyled through those parts: weight on
+`pt:label`, a heavier weight on `pt:label:checked`, the helper line on
+`pt:description`, a focus ring on `pt:icon:focused` (any focus, click
+included). The glyph is `icon` — there is no box.
+
+**pt:label, pt:label:checked, pt:icon:focused — merge method**
+
+```vue
+<template>
+	<div
+		aria-label="Merge method"
+		class="grid max-w-sm gap-2 rounded-(--bb-radius) border p-3"
+		role="radiogroup"
+	>
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Merge pull request #482</p>
+			<p class="text-xs text-(--bb-text-muted)">
+				feature/invoice-export → main
+			</p>
+		</div>
+		<BbRadio
+			v-for="method in methods"
+			:key="method.value"
+			v-model="strategy"
+			:description="method.description"
+			:label="method.label"
+			name="merge-method"
+			pt:description="text-xs"
+			pt:icon:focused="ring-2 ring-(--bb-primary) ring-offset-2"
+			pt:label="font-medium"
+			pt:label:checked="font-semibold"
+			:value="method.value"
+		>
+			<template v-if="method.recommended" #label="{ text }">
+				<span class="inline-flex items-center gap-1.5">
+					{{ text }}
+					<BbBadge size="xs" variant="secondary">Recommended</BbBadge>
+				</span>
+			</template>
+		</BbRadio>
+		<p class="merge-summary text-xs text-(--bb-text-muted)">
+			Pull request #482 will be merged via {{ labels[strategy] }}.
+		</p>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbBadge, BbRadio } from 'bitboss-ui';
+
+type MergeMethod = 'merge' | 'squash' | 'rebase';
+
+type Method = {
+	value: MergeMethod;
+	label: string;
+	description: string;
+	recommended?: boolean;
+};
+
+// Same merge-method list as `MergeStrategy.vue`, restyled through passthrough:
+// weight on `pt:label`, a heavier weight on `pt:label:checked`, the helper
+// line on `pt:description`, a focus ring on `pt:icon:focused`.
+const methods: Method[] = [
+	{
+		value: 'merge',
+		label: 'Create a merge commit',
+		description: 'All commits from the branch are added via a merge commit.',
+	},
+	{
+		value: 'squash',
+		label: 'Squash and merge',
+		description: 'Combine all commits into a single commit on the base branch.',
+		recommended: true,
+	},
+	{
+		value: 'rebase',
+		label: 'Rebase and merge',
+		description:
+			'Reapply each commit on the base branch, without a merge commit.',
+	},
+];
+
+const labels: Record<MergeMethod, string> = {
+	merge: 'a merge commit',
+	squash: 'squash and merge',
+	rebase: 'rebase and merge',
+};
+
+const strategy = ref<MergeMethod>('squash');
+</script>
+```
+
+An attribute in `attrs` wins over ours. The visually hidden native input is
+not a part — plain attributes on the component land on the root. A listener in `attrs` runs after the control's own
+handler, never instead of it. 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 `BbRadioProps['pt']`, never an imported `PtValue`: see
+[passthrough § Typing `pt` in `<script>`](./guides/passthrough.md#typing-pt-in-script).
+
 ### Works well with
 
 - `BbRadioGroup` — the default you should reach for first; this is only the
@@ -309,8 +459,8 @@ listen to them for side concerns only. `autofocus` focuses the input on mount.
   back to its own generated name.
 - Hand-composed groups have **no** fieldset semantics on their own — wrap them in
   a `role="radiogroup"` element with an accessible name (see Accessibility).
-- `reverse` is inverted (see Layout) — don't rely on `:reverse="false"` doing
-  anything.
+- `reverse` is an opt-in, not a toggle you turn off: unset already means
+  button-first. Setting `:reverse="false"` is legal but says nothing.
 - `checked` + `v-model` together fight; pick one.
 - `readonly` still submits and stays focusable; use `disabled` when the value
   must not post.
@@ -343,45 +493,86 @@ listen to them for side concerns only. `autofocus` focuses the input on mount.
 
 | 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: `description`, `hint`, `icon`, `label`, `message`, `root`. States: `checked`, `disabled`, `errors`, `focused`, `focusVisible`, `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 `BbRadioProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
 | `checked` | `boolean \| undefined` | `undefined` |  | Defines the input as checked. |
+| `compact` | `boolean \| undefined` | `false` |  | Compact density. Swaps `--bb-label-spacing-y` for `--bb-label-spacing-y-compact`, so tune a compact field's label gap with the `-compact` token, not the base one (the same meaning as on the checkbox / radio / switch groups, owner ruling Q53.12). |
 | `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
-| `direction` | `InputDirection \| undefined` | `"auto"` |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
-| `disabled` | `boolean \| undefined` |  |  | Disables the component. |
-| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
-| `hasErrors` | `boolean \| undefined` |  |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
-| `hasWarning` | `boolean \| undefined` |  |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
-| `hideLabel` | `boolean \| undefined` |  |  | Visually hides the label of the input while maintaining accessibility. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
+| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby`, so the reason the field is invalid is re-read whenever the control regains focus. |
+| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
+| `hasWarnings` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
+| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
 | `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
-| `id` | `string \| undefined` |  |  | The identifier of the component. |
+| `id` | `string \| undefined` |  |  | The `id` of the native control; the label's `for` and the description and message ids derive from it. Generated when omitted. |
 | `inputPosition` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can. |
 | `label` | `string` |  | yes | Text content of the label of the element. |
 | `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
+| `layout` | `FieldLayout \| undefined` | `"auto"` |  | How the label and the input sit together: `'vertical'`, `'horizontal'` (50/50), `'auto'`, `'label-fill'` (the label takes the free space, the input keeps its size), `'input-fill'` (the other way round), or a two-word ratio pattern like `'xx xxxxx'`. |
 | `modelValue` | `any` |  |  | Used by v-model. Can be any serializable type. |
-| `name` | `string \| undefined` |  |  | Defines the name of the input. Optional: an omitted name falls back to a generated one, unique to this button and stable for its lifetime, so a lone radio needs no name at all. Buttons that must form ONE exclusive group still have to share … |
-| `persistentHint` | `boolean \| undefined` |  |  | Keeps the hint displayed. |
-| `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
-| `required` | `boolean \| undefined` |  |  | Sets the input as required. |
-| `reverse` | `boolean \| undefined` |  |  | Reverses the layout: in every direction the order of the label and the input is swapped from the standard arrangement. |
+| `name` | `string \| undefined` |  |  | Defines the name of the input. Optional: an omitted name falls back to a generated one, unique to this button and stable for its lifetime, so a lone radio needs no name at all. Buttons that must form ONE exclusive group still have to share an explicit `name` — generated names are per-instance, so they would never group. Pass a name too when the value has to be submitted under a known key by a native (non-JS) form post. |
+| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
+| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
+| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
+| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout: in every direction the order of the label and the input is swapped from the standard arrangement. |
 | `value` | `any` |  | yes | Defines the value of the radio input. It can be any serializable value. |
-| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |
+| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are also referenced from the control's `aria-describedby`, after any errors and before the description/hint. |
+
+## 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 toggle's container: the glyph, the label and the lines under them. |
+| `label` | The label text beside the glyph (the `label` prop). |
+| `description` | The muted line under the label (the `description` prop). |
+| `message` | The errors / warnings line. A node of its own: it can show at the same time as `hint`. |
+| `hint` | The helper line (the `hint` prop), shown on focus, or always with `persistent-hint`. |
+| `icon` | The drawn glyph — the box, the dot or the switch track. The default one: a consumer `icon` slot replaces it. The hidden native input is not a part. |
+
+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. |
+| `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
 
-- `blur` — `(event: "blur", event: FocusEvent): void`
-- `change` — `(event: "change", event: Event): void`
-- `click` — `(event: "click", event: MouseEvent): void`
-- `focus` — `(event: "focus", event: FocusEvent): void`
-- `input` — `(event: "input", event: Event): void`
-- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
-- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
-- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
-- `update:modelValue` — `(event: "update:modelValue", value: any): void`
+- `blur` — `(event: FocusEvent): void` — Emitted when the native input loses focus. Forwards the original DOM `FocusEvent`.
+- `change` — `(event: Event): void` — Emitted when the radio selection changes. Forwards the original DOM `Event`.
+- `click` — `(event: MouseEvent): void` — Emitted when the input receives a click interaction. Forwards the original DOM `MouseEvent`.
+- `focus` — `(event: FocusEvent): void` — Emitted when the native input gains focus. Forwards the original DOM `FocusEvent`.
+- `input` — `(event: Event): void` — Emitted on native input events from the radio input. Forwards the original DOM `Event`.
+- `keydown` — `(event: KeyboardEvent): void` — Emitted for keyboard interaction on the input. Forwards the original DOM `KeyboardEvent`.
+- `mousedown` — `(event: MouseEvent): void` — Emitted when a pointing device button is pressed over the input. Forwards the original DOM `MouseEvent`.
+- `mouseup` — `(event: MouseEvent): void` — Emitted when a pointing device button is released over the input. Forwards the original DOM `MouseEvent`.
+- `update:modelValue` — `(value: any): void` — Emitted when the radio becomes selected, carrying the radio's `value` prop.
 
 ## Slots
 
-- `icon` — scope: `BbRadioIconSlotProps` — Replaces the default radio dot visual inside the radio container. Receives `BaseRadio` slot attributes plus the label text.
-- `label` — scope: `BbRadioLabelSlotProps` — Replaces the default label text rendered next to the radio button.
+- `description` — scope: `BbRadioDescriptionSlotProps` `{ text: string; hasErrors: boolean; hasWarnings: boolean }` — Replaces the description text. Provided alone (no `description` prop) it still renders the description region and wires it into `aria-describedby`.
+- `icon` — scope: `BbRadioIconSlotProps` `{ checked: boolean; disabled: boolean; focused: boolean; focusVisible: boolean; hasErrors: boolean; hasWarnings: boolean; id: string; name: string; parsedValue: string; readonly: boolean; value: any; text: string }` — Replaces the default radio dot visual inside the radio container. Receives the radio state plus the label text.
+- `label` — scope: `BbRadioLabelSlotProps` `{ text: string; hasErrors: boolean; hasWarnings: boolean }` — Replaces the default label text rendered next to the radio button.
+
+## Component tree
+
+`BbRadio` is not one component: rendering it mounts every component below, and each one is live inside it. **Read this before styling, theming or debugging `BbRadio`, 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 `BbRadio`. A pt part listed as landing there is set on `BbRadio` (`pt:<part>`).
+- **_public_** nodes are components with their own contract. `BbRadio` 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 `BbRadio`'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 `BbRadio`'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 `BbRadio`'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`.
+
+- `BbRadio` _(this component)_ — its own template binds: `icon` → `BbBaseRadioIcon`
+  - `CommonField` _(internal — not importable, reach it through `BbRadio`)_ — `BbRadio`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint`, `message` → `div.bb-field__message`; also mounts `BbAsterisk`
+  - Also mounts `BbBaseRadioIcon`
 
 ## See Also