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

package/dist/ai/BbRadioGroup.md

@@ -8,6 +8,30 @@
 - Usage rule: Prefer this component for consumer-facing implementations.
 - Implementation source (only when the contract below is not enough): [source/BbRadioGroup.md](./source/BbRadioGroup.md)
 
+## Reachable through `BbRadioGroup`
+
+`BbRadioGroup` 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)_ |
+| `pt:list` | `span` | `OptionsContainer` _(internal)_ |
+| `pt:item` | `label` | `OptionsContainer` _(internal)_ |
+| `pt:label` | `span` | `OptionsContainer` _(internal)_ |
+| `pt:itemDescription` | `span` | `OptionsContainer` _(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 `BbRadioGroup`'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
@@ -28,6 +52,20 @@ Choose by shape:
 
 ### Items and value mapping
 
+**Object items need `item-text`.** Without it each label is
+`JSON.stringify(item)`, and without `item-value` the whole object is the value.
+`{ label, value }` items take both:
+
+```vue
+<BbRadioGroup
+	v-model="plan"
+	legend="Plan"
+	:items="plans"
+	item-text="label"
+	item-value="value"
+/>
+```
+
 Pass domain objects to `items` and resolve the display text and stored value
 with `item-text` / `item-value` — a dot-path or a function. The bound model
 holds only the mapped value (an id), which is what you persist. Primitive
@@ -40,9 +78,7 @@ wins) — see the
 
 ```vue
 <template>
-	<div
-		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
-	>
+	<div class="flex max-w-sm flex-col gap-3 rounded-(--bb-radius) border p-4">
 		<BbRadioGroup
 			v-model="plan"
 			compact
@@ -53,7 +89,7 @@ wins) — see the
 			legend="Subscription plan"
 			name="plan"
 		/>
-		<p class="plan-summary text-xs text-[var(--bb-text-muted)]">
+		<p class="plan-summary text-xs text-(--bb-text-muted)">
 			Selected: {{ plan }}
 		</p>
 	</div>
@@ -81,6 +117,84 @@ const plan = ref<string>('pro');
 </script>
 ```
 
+#### Additional row fields: `item-props`
+
+`item-text` and `item-value` are the option's label and identity. Anything
+**additional** about a row comes from `item-props` — for option groups that is
+one field, `description`: a muted line **under** the option's label, beside the
+control.
+
+```vue
+<BbRadioGroup
+	legend="Plan"
+	:items="plans"
+	item-text="name"
+	item-value="id"
+	:item-props="{ description: 'summary' }"
+/>
+```
+
+**Plan tiers described by a function**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-(--bb-radius) border p-3">
+		<BbRadioGroup
+			v-model="tier"
+			:item-props="tierProps"
+			item-text="name"
+			item-value="id"
+			:items="tiers"
+			legend="Plan"
+			list-layout="vertical"
+			name="plan"
+		/>
+		<p class="tier-summary text-xs text-(--bb-text-muted)">
+			Selected: {{ tier }}
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbRadioGroup } from 'bitboss-ui';
+
+type Tier = { id: string; name: string; seats: number; price: number };
+
+const tiers: Tier[] = [
+	{ id: 'free', name: 'Free', seats: 3, price: 0 },
+	{ id: 'team', name: 'Team', seats: 25, price: 12 },
+	{ id: 'business', name: 'Business', seats: 250, price: 29 },
+];
+
+// The FUNCTION form: one function returns every additional field, called once
+// per item. Handy when the text is composed rather than read from one field.
+const tierProps = (item: Tier) => ({
+	description:
+		item.price === 0
+			? `Up to ${item.seats} seats, free forever.`
+			: `Up to ${item.seats} seats, €${item.price} per seat per month.`,
+});
+
+const tier = ref<string | null>('team');
+</script>
+```
+
+Each field takes a dot-path or a getter; or pass one function that returns the
+fields: `:item-props="(plan) => ({ description: plan.summary })"`.
+
+- **Only additional fields.** Text and value never go in `item-props`.
+- **Nothing is read implicitly.** Without `item-props` no description renders,
+  even if your items carry a `description` field. An empty value renders no
+  line for that item.
+- **The line may wrap**, is announced as the option's description (never part of
+  its name), and reaches the `#label` slot as `description`.
+- **No icons here.** An option group has no place for an icon other than the
+  control itself, which the `#icon` slot already replaces.
+- **Disabling individual options is `selectable`'s job** —
+  `:selectable="(plan) => plan.available"` — not a field in `item-props`.
+- The group's own `description` prop is a different thing: it sits under the
+  legend.
+
 ### The model is a single value
 
 Unlike the checkbox and switch groups, `BbRadioGroup` is **single-only** — there
@@ -98,23 +212,29 @@ option for it rather than expecting a cleared model.
 
 ### Layout and density
 
-`input-direction="horizontal"` lays options in a row for segmented-style
-choices (shipping speed, billing cycle); the default stacks them. `compact`
-tightens spacing. Because a radio group binds a single value, it drives cleanly
+Options flow in a **wrapping row by default** — `list-layout` falls back
+to `'horizontal'`, which suits segmented-style choices (shipping
+speed, billing cycle). Pass `list-layout="vertical"` to stack them one per
+line, which is what you want for long option text or a scannable list;
+`'vertical-stretch'` stacks them at the full width of the list, and `'tiles'`
+makes equal-size boxes that wrap as the field narrows. `item-layout` arranges
+each row's input against its label with the keywords of `layout`, and
+`item-reverse` swaps the two.
+`compact` tightens spacing. Because a radio group binds a single value, it drives cleanly
 from `v-model` inline.
 
 **Horizontal shipping speed**
 
 ```vue
 <template>
-	<div class="max-w-sm rounded-[var(--bb-radius)] border p-4">
+	<div class="max-w-sm rounded-(--bb-radius) border p-4">
 		<BbRadioGroup
 			v-model="speed"
 			compact
 			hint="Express arrives in 1–2 business days."
-			input-direction="horizontal"
 			:items="['Standard', 'Express', 'Overnight']"
 			legend="Shipping speed"
+			list-layout="horizontal"
 			name="shipping-speed"
 			persistent-hint
 		/>
@@ -128,13 +248,113 @@ const speed = ref<string>('Standard');
 </script>
 ```
 
-`direction` splits the legend against the options block (`'auto'`,
+`layout` splits the legend against the options block (`'auto'`,
 `'horizontal'`, `'vertical'`, or a pattern like `'xx xxxxxx'`);
 `input-position` / `legend-position` align options and legend within their
 columns; `reverse` swaps legend and options order (a plain swap here, not
 inverted); `hide-legend` hides the legend visually while keeping it for
 assistive tech.
 
+#### Layout recipes
+
+**Radio cards** — one bordered full-width row per option, the price on the
+trailing edge of the label cell, the delivery time as the row's description:
+
+**Shipping method cards**
+
+```vue
+<template>
+	<div class="max-w-md">
+		<BbRadioGroup
+			v-model="method"
+			item-layout="label-fill"
+			:item-props="{ description: 'eta' }"
+			item-text="name"
+			item-value="id"
+			:items="methods"
+			legend="Shipping"
+			list-layout="vertical-stretch"
+			name="shipping"
+			pt:item="rounded-(--bb-radius) border px-4 py-3"
+			pt:item:checked="border-(--bb-primary) bg-(--bb-muted)"
+			pt:list="[--row-gap:8px]"
+		>
+			<template #label="{ item }">
+				<span class="flex justify-between gap-4">
+					<span>{{ item.name }}</span>
+					<span class="tabular-nums">{{ item.price }}</span>
+				</span>
+			</template>
+		</BbRadioGroup>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbRadioGroup } from 'bitboss-ui';
+
+type Method = { id: string; name: string; price: string; eta: string };
+
+// Radio cards: one full-width bordered row per option
+// (`list-layout="vertical-stretch"`), the radio first and the label cell
+// filling the rest (`item-layout="label-fill"`), so a flex row in `#label`
+// pushes the price to the trailing edge. The delivery time is the row's
+// `itemProps.description`, which sits under the label, beside the radio.
+const methods: Method[] = [
+	{ id: 'standard', name: 'Standard', price: '€4.90', eta: '3–5 working days' },
+	{ id: 'express', name: 'Express', price: '€9.90', eta: 'Next working day' },
+	{
+		id: 'pickup',
+		name: 'Pick up in store',
+		price: 'Free',
+		eta: 'Ready in 2 hours',
+	},
+];
+
+const method = ref<string>('standard');
+</script>
+```
+
+A **segmented control** that is still a radiogroup (arrow keys, "2 of 4"):
+equal tiles, the dot hidden with `pt:icon="hidden"`, the checked label
+recoloured on `pt:label:checked` — the label cell paints its own colour, so a
+colour on `pt:item` never reaches it:
+
+**Segmented range picker**
+
+```vue
+<template>
+	<div class="max-w-sm">
+		<BbRadioGroup
+			v-model="range"
+			item-layout="vertical"
+			:items="['Day', 'Week', 'Month', 'Year']"
+			legend="Range"
+			list-layout="tiles"
+			name="range"
+			pt:icon="hidden"
+			pt:item="justify-items-center gap-0 rounded-[calc(var(--bb-radius)-2px)] py-1.5"
+			pt:item:checked="bg-(--bb-primary)"
+			pt:item:focus-visible="ring-2 ring-(--bb-primary-ring)"
+			pt:label="text-sm"
+			pt:label:checked="text-(--bb-primary-fg)"
+			pt:list="[--gap:2px] [--tile-min-width:0px] rounded-(--bb-radius) border p-0.5"
+		/>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbRadioGroup } from 'bitboss-ui';
+
+// A segmented control that is still a radiogroup: arrow keys move the
+// choice, screen readers announce "radio, 2 of 4". `list-layout="tiles"`
+// with `--tile-min-width: 0` shares the track evenly; `item-layout="vertical"`
+// lets the label centre over the hidden glyph cell. `pt:icon="hidden"` drops
+// the dot (an empty `#icon` slot would fall back to it), and the checked text
+// colour goes on `pt:label:checked` because the label paints its own colour.
+const range = ref<string>('Week');
+</script>
+```
+
 ### Legend, validation and required
 
 The `legend` names the group — always set it. `description` is always-visible
@@ -146,7 +366,7 @@ rendered below the group in its own `aria-live="polite"` region (also
 referenced from `aria-describedby` while displayed) for a
 valid-but-noteworthy choice (unusual, near a limit, soft-flagged), and a
 non-empty `warnings` implies the warning state just as `errors` implies the error
-state; **`has-warning`** forces that amber chrome without a message. Unlike
+state; **`has-warnings`** forces that amber chrome without a message. Unlike
 `has-errors`, neither sets `aria-invalid` — a soft "needs a second look", not an
 invalid value — and `has-errors` wins when both are set, suppressing the warning
 messages so the group never shows amber and red at once. `required` marks the group as required — because these are native radios,
@@ -157,7 +377,7 @@ it participates in native form validation. `legend-mode` places the legend
 
 ```vue
 <template>
-	<div class="max-w-sm rounded-[var(--bb-radius)] border p-4">
+	<div class="max-w-sm rounded-(--bb-radius) border p-4">
 		<BbRadioGroup
 			v-model="cycle"
 			compact
@@ -210,7 +430,7 @@ Keep the set short enough that arrow-cycling stays quick; past ~6 options prefer
 ### Async items, loading and coherence
 
 `items` accepts a provider function for options fetched from an API;
-`loading-text` / `#loading` and `no-data-text` / `#no-data` cover the loading
+`loading-text` / `#loading` and `empty-text` / `#empty` cover the loading
 and empty states, `dependencies` (+ `deps-debounce-time`) trigger re-fetches,
 and `enforce-coherence` resets the model to `null` when the current value no
 longer matches an available option. See the
@@ -232,17 +452,15 @@ valid yet" and gate the submit on it.
 
 ```vue
 <template>
-	<div
-		class="flex max-w-md flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
-	>
+	<div class="flex max-w-md flex-col gap-3 rounded-(--bb-radius) border p-4">
 		<BbRadioGroup
 			v-model="branch"
 			compact
-			input-direction="horizontal"
 			item-text="label"
 			item-value="id"
 			:items="branches"
 			legend="Target branch"
+			list-layout="horizontal"
 			name="merge-branch"
 		/>
 		<BbRadioGroup
@@ -260,7 +478,7 @@ valid yet" and gate the submit on it.
 			name="merge-strategy"
 			persistent-hint
 		/>
-		<p class="strategy-summary text-xs text-[var(--bb-text-muted)]">
+		<p class="strategy-summary text-xs text-(--bb-text-muted)">
 			Strategy: {{ strategy ?? 'none selected' }}
 		</p>
 	</div>
@@ -313,35 +531,42 @@ const loadStrategies = (
 
 ### Slots
 
-`#label` replaces an option's text (`{ item, text }`); `#icon` replaces the
+`#label` replaces an option's text (`{ item, text, checked }` — `checked` is what tile layouts key off); `#icon` replaces the
 default radio-dot visual for each option (you then own its selected/focus
-styling). `#legend` replaces the fieldset legend (`{ text, hasErrors }`);
+styling). `#legend` replaces the fieldset legend (`{ text, hasErrors, hasWarnings }`; plus `showAsterisk` when the required marker shows);
 `#prepend` / `#append` inject content inside the options container.
 
 ### Selection tiles
 
 For a small set of mutually-exclusive choices that read better as cards than a
 plain list — theme (light/dark/system), an import mode — compose `#icon` +
-`#label` with CSS on `.bb-base-radio-group-option`. Don't reach for a bespoke
+`#label` with `pt:item` on the option row. Don't reach for a bespoke
 tile component or a 2-option `BbSelect`; the semantics (one `<fieldset>`,
 native roving focus, one bound value) are exactly what this component already
-gives you. Each option's `<label>` picks up a `bb-base-radio-group-option--selected`
-modifier class when checked — style off that, not a `:has()` selector.
+gives you. The checked row resolves `pt:item:checked` — style off that, not a
+`:has()` selector.
+
+**Text-only tiles:** hide the dot with `pt:icon="hidden"`. An empty `#icon`
+slot does not remove it: the default dot is the slot's fallback and renders
+whenever the slot is empty.
 
 **Theme selection tiles**
 
 ```vue
 <template>
-	<div class="max-w-md rounded-[var(--bb-radius)] border p-4">
+	<div class="max-w-md rounded-(--bb-radius) border p-4">
 		<BbRadioGroup
 			v-model="theme"
 			class="theme-tiles"
-			input-direction="horizontal"
+			item-layout="vertical"
 			item-text="label"
 			item-value="id"
 			:items="themes"
 			legend="Appearance"
+			list-layout="tiles"
 			name="theme"
+			pt:item="theme-tiles__tile"
+			pt:item:checked="theme-tiles__tile--selected"
 		>
 			<template #icon="{ item }">
 				<BbIcon :icon="item.icon" size="lg" />
@@ -368,25 +593,25 @@ const theme = ref<string>('system');
 </script>
 <style scoped>
 /*
- * Tiles: each option is `display: inline-flex` by default (content-sized),
- * so `flex: 1 1 0` on the option itself is what makes three tiles share the
- * row evenly — the row (`__container`) is a plain wrapping flexbox, not a grid.
+ * The layout is two props: `list-layout="tiles"` makes equal-size boxes that
+ * wrap when the field narrows, `item-layout="vertical"` stacks the glyph over
+ * the caption. What is left here is the tile's look — and centring, since a
+ * stacked row starts its cells at the left edge.
+ *
+ * `pt:item` / `pt:item:checked` hand the rows OUR classes, so nothing below
+ * names a library BEM class; `:deep()` stays because the scope attribute is on
+ * this example's root, not on the nodes.
  */
-.theme-tiles :deep(.bb-base-radio-group__container) {
-	flex-wrap: nowrap;
-}
-
-.theme-tiles :deep(.bb-base-radio-group-option) {
+.theme-tiles :deep(.theme-tiles__tile) {
+	align-content: center;
 	border: var(--bb-border-w) solid var(--bb-border);
 	border-radius: var(--bb-radius);
-	flex: 1 1 0;
-	flex-direction: column;
-	justify-content: center;
+	justify-items: center;
 	padding: 12px;
 	row-gap: 6px;
 }
 
-.theme-tiles :deep(.bb-base-radio-group-option--selected) {
+.theme-tiles :deep(.theme-tiles__tile--selected) {
 	background: color-mix(in oklab, var(--bb-primary) 8%, var(--bb-panel));
 	border-color: var(--bb-primary);
 }
@@ -399,26 +624,185 @@ const theme = ref<string>('system');
 
 Two width facts worth knowing before you reach for `width: 100%` anywhere:
 
-- The options row (`.bb-base-radio-group__container`) is a plain wrapping
-  flexbox and each option is `display: inline-flex` — content-sized by
-  default. `flex: 1 1 0` on the option (as in the example above) is what makes
-  tiles share the row evenly; there's no grid to opt into.
-- The row's own box (`.bb-base-input-container__control`) is `display: grid`
-  with a Vue-computed inline `width`, which defaults to `auto` — it does
-  **not** stretch to fill a wider parent on its own. If you want the tile row
-  to span full width, size the `BbRadioGroup` itself (a wrapping
-  `class="w-full"`, or a container with a set width); don't set
-  `direction="vertical"` just to pick up `width: 100%` — that also stacks the
-  legend above the options, which a tile row usually doesn't want.
+- The options row is ONE node — `.bb-radio-group__list`, the `list`
+  part — a plain wrapping flexbox that holds the rows and lays them out.
+  Each option is a small grid (input cell, label, description), content-sized
+  by default; `list-layout="tiles"` makes them share the row evenly.
+  `pt:list="grid grid-cols-3"` or `pt:list="flex-col"` re-lays the rows
+  outright on a layered build.
+- The list fills its column (`.bb-field__input-wrapper`, the whole field unless
+  `layout` puts the legend beside it): tiles share the field,
+  `list-layout="vertical-stretch"` rows are field-wide, and
+  `pt:list="grid grid-cols-3"` spreads its tracks across it. The exception is
+  `input-position="right"` / `"center"`: there the list shrink-wraps its rows
+  and sits at that edge, so stacked rows keep one shared left edge.
 
 ### Events and focus
 
 `update:modelValue` (the `v-model` channel) carries the single selected value —
 the only source of selection truth. Native `blur`, `change`, `click`, `focus`,
 `input`, `keydown`, `mousedown`, `mouseup` re-emit with raw payloads, plus
-`inactive` when focus leaves the group; use them for side effects, never to
+`active` when focus enters the group (it drives the hint internally) and
+`inactive` when focus leaves; use them for side effects, never to
 compute selection. `autofocus` focuses the first option on mount.
 
+**The group is controlled.** A click emits `update:modelValue` and the rows
+move only when the parent applies the new value: ignore the update and every
+row stays on what the model says.
+
+### Restyling with passthrough
+
+`pt` reaches a named part of the group with a class list — or, in the
+object form, a style and attributes — optionally only while a state is on.
+Parts: `root` (the fieldset), `legend` (the group's heading, after the `legend`
+prop), `description`, `message`, `hint` (the helper line — shown on focus, or
+always with `persistent-hint`), `item` — one option row —, `icon` — that row's glyph —, `label` — that
+option's label text, both as on a standalone control — and `itemDescription` — its
+muted second line (`itemProps.description`), never the group's `description`.
+`item`, `icon`, `label` and `itemDescription` are broadcasts resolved per row. States of the
+whole group, on every part: `hasValue` (something is chosen), `readonly`,
+`loading` (the items are being fetched), `disabled`, `warnings`, `errors`.
+States of one row, on the row parts only: `checked`, `focused` (that row's
+input has focus), `focusVisible` (that focus is keyboard-visible), and the
+row's own `disabled` — the states a standalone control has. A name outside
+that list is a type error and an ESLint error.
+
+The theme tiles above, restyled through those parts. The layout is two props
+— `list-layout="tiles"` for equal boxes, `item-layout="vertical"` to stack the
+glyph over the caption — so `pt:item` is only the tile's look, a broadcast;
+the selected accent is `pt:item:checked`. For full-width tiles stacked one per
+line, flip `list-layout` to `"vertical-stretch"` and change nothing else: the
+list becomes a column and every tile fills it.
+
+**The glyph is the row's input cell** — there is no wrapper around it, so
+whatever you would do to that cell, do on `pt:icon`: `pt:icon="self-start"`
+pins the dot to the top of a label that wraps (by default it centres on the
+whole label; a row with an `itemProps.description` already puts it on the
+label's first line), `pt:icon="mt-0.5"` nudges it, and its size is the glyph's
+own token (see `BbBaseRadioIcon`), never a width on the row. With a custom `#icon`
+slot, your element is the cell: put the classes on it.
+
+A look that depends on the ITEM — a paid tier tinted differently from a free
+one — is a **per-item function** on a row part: `:pt:item="({ item, checked })
+=> …"`, called with the raw item (typed as your item) and every state as a
+boolean for that row, its result merged after `pt:item:checked`. Row parts only
+(`item`, `icon`, `label`, `itemDescription`), on the instance only. `list`
+is the one node that holds the rows and lays them out:
+`pt:list="grid grid-cols-3"` or `pt:list="flex-col"` re-lays them on a
+layered build, `pt:list="[--gap:8px]"` tightens them anywhere.
+
+**pt:item as a function — plan tiles tinted by tier**
+
+```vue
+<template>
+	<div class="w-full max-w-md rounded-(--bb-radius) border p-4">
+		<BbRadioGroup
+			v-model="plan"
+			class="w-full"
+			item-text="name"
+			item-value="id"
+			:items="plans"
+			legend="Plan"
+			list-layout="horizontal"
+			name="plan"
+			:pt="{
+				item: 'flex flex-1 flex-col items-start gap-0.5 rounded-(--bb-radius) border border-(--bb-border) px-3 py-2',
+			}"
+			:pt:item="
+				({ item }) => item.tier === 'paid' && 'border-amber-300 bg-amber-50'
+			"
+			pt:item:checked="ring-2 ring-(--bb-primary)"
+			pt:list="[--gap:8px]"
+		>
+			<template #label="{ item, text }">
+				<span class="text-sm font-medium">{{ text }}</span>
+				<span class="text-xs text-(--bb-text-muted)">{{ item.price }}</span>
+			</template>
+		</BbRadioGroup>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbRadioGroup } from 'bitboss-ui';
+
+type Plan = { id: string; name: string; price: string; tier: 'free' | 'paid' };
+
+// The per-item function receives the raw plan (typed as `Plan` — the group
+// is generic over its items) and every state as a boolean; its result is
+// merged after `pt:item:checked`, so the ring and the tint compose. `list`
+// takes the gap by value through its `--gap` token.
+const plans: Plan[] = [
+	{ id: 'free', name: 'Free', price: '€0', tier: 'free' },
+	{ id: 'pro', name: 'Pro', price: '€12 / mo', tier: 'paid' },
+	{ id: 'team', name: 'Team', price: '€40 / mo', tier: 'paid' },
+];
+
+const plan = ref<string>('pro');
+</script>
+```
+
+**pt:item — appearance tiles, the selected one accented**
+
+```vue
+<template>
+	<div class="max-w-md rounded-(--bb-radius) border p-4">
+		<BbRadioGroup
+			v-model="theme"
+			item-layout="vertical"
+			item-text="label"
+			item-value="id"
+			:items="themes"
+			legend="Appearance"
+			list-layout="tiles"
+			name="theme"
+			pt:item="content-center justify-items-center gap-1.5 rounded-(--bb-radius) border border-(--bb-border) px-3 py-3"
+			pt:item:checked="border-(--bb-primary) bg-(--bb-muted)"
+		>
+			<template #icon="{ item }">
+				<BbIcon :icon="item.icon" size="lg" />
+			</template>
+			<template #label="{ text }">
+				<span class="text-sm">{{ text }}</span>
+			</template>
+		</BbRadioGroup>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbIcon, BbRadioGroup } from 'bitboss-ui';
+
+type Theme = { id: string; label: string; icon: string };
+
+// Same Appearance tiles as `ThemeTiles.vue`, restyled through passthrough.
+// The layout is two props — `list-layout="tiles"` for equal boxes,
+// `item-layout="vertical"` to stack the glyph over the caption — so `pt:item`
+// is only the tile's look (centred, bordered) and `pt:item:checked` the
+// accent. Flip `list-layout` to "vertical-stretch" and the same tiles stack,
+// each as wide as the field — nothing else changes. `#icon` replaces the
+// radio dot.
+const themes: Theme[] = [
+	{ id: 'light', label: 'Light', icon: 'lucide:sun' },
+	{ id: 'dark', label: 'Dark', icon: 'lucide:moon' },
+	{ id: 'system', label: 'System', icon: 'lucide:monitor' },
+];
+
+const theme = ref<string>('system');
+</script>
+```
+
+This is the old `:deep()` reach-in on the selected row's modifier class,
+spelled as a part and a state — your class, our promise. Classes append to
+ours, an attribute in `attrs` wins over ours. 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 `BbRadioGroupProps<Row>['pt']`, or `BbRadioGroupProps['pt']`
+for a preset that fits any row type (never `<any>`), not an imported
+`PtValue`: see
+[passthrough § Typing `pt` in `<script>`](./guides/passthrough.md#typing-pt-in-script).
+
 ### Works well with
 
 - `BbRadio` — the escape hatch when options must be interleaved with other
@@ -477,74 +861,128 @@ compute selection. `autofocus` focuses the first option 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`, `item`, `itemDescription`, `label`, `legend`, `list`, `message`, `root`. States: `disabled`, `errors`, `hasValue`, `loading`, `readonly`, `warnings`, `checked`, `focused`, `focusVisible`. 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 `BbRadioGroupProps<Row>['pt']` (`BbRadioGroupProps['pt']` for a preset that fits any row type, never `<any>`) (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
-| `compact` | `boolean \| undefined` |  |  | Sets the component in a compact state. |
+| `compact` | `boolean \| undefined` | `false` |  | Compact density. Swaps `--bb-label-spacing-y` for `--bb-label-spacing-y-compact`, so tune a compact group's label gap with the `-compact` token, not the base one. |
 | `dependencies` | `unknown[] \| undefined` |  |  | Defines an array of dependencies that will trigger actions in the component upon change. |
 | `depsDebounceTime` | `number \| undefined` |  |  | Timeout used to debounce response to changes to dependencies. |
 | `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` |  |  | 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. |
-| `enforceCoherence` | `boolean \| undefined` |  |  | If coherence is enforced the input cannot have a modelValue that is incoherent with its current items. e.g. You cannot set v-model to a user that is not present in the items passed. modelValue will be reset upon incoherence. |
-| `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. |
-| `hideLegend` | `boolean \| undefined` |  |  | Visually hides the legend of the fieldset while maintaining accessibility. |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
+| `emptyText` | `string \| undefined` |  |  | String displayed when there are no items to display. |
+| `enforceCoherence` | `boolean \| undefined` | `false` |  | If coherence is enforced the input cannot have a modelValue that is incoherent with its current items. e.g. You cannot set v-model to a user that is not present in the items passed. modelValue will be reset upon incoherence. |
+| `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. |
+| `formless` | `boolean \| undefined` | `false` |  | Keep this control out of the enclosing `BbForm` entirely: not submitted, not dirty, not reset, not validated. For a control that is not form data (a filter, a "show advanced" switch). |
+| `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 each option's label text (the text rendered next to every input) while keeping it accessible to screen readers. Does not affect the fieldset legend — use `hideLegend` for that. |
+| `hideLegend` | `boolean \| undefined` | `false` |  | Visually hides the legend of the fieldset 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. |
-| `inputDirection` | `"horizontal" \| "vertical" \| undefined` |  |  | Defines the direction of the inputs in the fieldset. |
+| `id` | `string \| undefined` |  |  | Prefix for the ids of each option's input and of the label, description and message. 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. |
+| `itemLayout` | `FieldLayout \| undefined` | `'auto'` |  | How each row's input and label sit together — the keywords of `layout`: `'auto'`, `'vertical'` (the input above the label), `'horizontal'` (50/50), `'label-fill'` (the label takes the row's free space — pair it with `list-layout="vertical-stretch"` and `item-reverse` for a settings list), `'input-fill'`, or a two-word ratio pattern like `'xx xxxxx'`, read in on-screen order. |
+| `itemProps` | `BbOptionGroupItemProps<T> \| undefined` |  |  | ADDITIONAL row fields resolved from each item — never its text or value (those stay on `itemText` / `itemValue`). Option groups accept one field: - `description` — a muted line under the option label, beside the control; it may wrap. Either an object with a path or getter per field (`{ description: 'email' }`) or a function returning the fields (`(item) => ({ description: item.email })`). Without it no field renders — an item's own `description` is never read implicitly — and an empty value renders nothing for that item. The description is announced as the option's description, never part of its name. To disable individual options use `selectable`. |
+| `itemReverse` | `boolean \| undefined` | `false` |  | Swaps each row's input and label from their natural order (input first), in every `item-layout`. `reverse` swaps the legend and the options instead. |
 | `items` | `T[] \| ((prefill: boolean, modelValue?: any) => T[] \| Promise<T[]>)` |  | yes | Used to retrieve items; can be an array or a function. |
-| `itemText` | `ItemAccessor<T, string> \| undefined` |  |  | Defines a path that returns a property of the object to use as text or a function that returns a string. |
-| `itemValue` | `ItemAccessor<T> \| undefined` |  |  | Defines a path that returns a property of the object to use as value or a function that returns any value. |
+| `itemText` | `ItemAccessor<T, string> \| undefined` | `JSON.stringify(item)` |  | Defines a path that returns a property of the object to use as text or a function that returns a string. |
+| `itemValue` | `ItemAccessor<T> \| undefined` | `the whole item` |  | Defines a path that returns a property of the object to use as value or a function that returns any value. |
+| `layout` | `FieldLayout \| undefined` |  |  | 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'`. |
 | `legend` | `string` |  | yes | Text content of the legend. |
 | `legendMode` | `"outside" \| "inside" \| undefined` |  |  | Legend rendering mode. `'outside'` renders the legend above the fieldset in the normal flow; `'inside'` overlays the legend inside the fieldset border. Floating mode is not supported for radio groups. |
 | `legendPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
+| `listLayout` | `'horizontal'` \| `'vertical'` \| `'vertical-stretch'` \| `'tiles'` | `'horizontal'` |  | How the rows sit inside the list: `'horizontal'` (on a line, wrapping, each row its own size), `'vertical'` (stacked, each row its own size), `'vertical-stretch'` (stacked, each row as wide as the list) or `'tiles'` (equal-size boxes, wrapping onto new lines as the field narrows; `--tile-min-width` on `pt:list` sets how narrow a tile gets). |
 | `loadingText` | `string \| undefined` |  |  | String displayed while items are being loaded. |
-| `modelValue` | `any` |  | yes | Used by v-model. Can be any serializable type. |
+| `modelValue` | `any` |  |  | Used by v-model. Can be any serializable type. |
 | `modelValueDebounceTime` | `number \| undefined` |  |  | Timeout used to debounce response to changes to modelValue. |
-| `name` | `string \| undefined` |  |  | Defines the name of the option inputs. Optional: the options live inside a single component instance, so an omitted name falls back to a generated one that groups them correctly on its own — unique per group, so two groups never clear each … |
-| `noDataText` | `string \| undefined` |  |  | String displayed when there are no items to display. |
-| `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. Applicable in every direction the order of the label and the input is swapped. |
+| `name` | `string \| undefined` |  |  | Defines the name of the option inputs. Optional: the options live inside a single component instance, so an omitted name falls back to a generated one that groups them correctly on its own — unique per group, so two groups never clear each other's selection, and stable for the group's lifetime. Pass a name only 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. Applicable in every direction the order of the label and the input is swapped. |
+| `rules` | `RuleExpression<any>` |  |  | vee-validate rules for this field. Only inside a `BbForm`. |
 | `selectable` | `boolean \| ((item: T) => boolean) \| undefined` | `true` |  | Defines whether options are selectable. Can be a global boolean that affects all options or a function that accepts an item and returns a boolean that only affects that item. Non-selectable options are rendered disabled. |
-| `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… |
+| `validationLabel` | `string \| undefined` |  |  | The field's name in validation messages (`{field}`): "Email is not valid". Defaults to the `label` (or `legend`), then "This field"; the field's `name` never shows. Set it when the label is not a good noun for a sentence (an icon-only label, a question) or is hidden. Only inside a `BbForm`. |
+| `validationMode` | `'aggressive'` \| `'balanced'` \| `'lazy'` \| `'submit-only'` \| `'submit-live'` |  |  | When this field checks itself while the user works: `aggressive` (every change), `balanced` (on leave, then every change while it shows an error), `lazy` (on leave only), `submit-only` (on submit only) or `submit-live` (on submit, then every change while it shows an error). "Leave" is blur for a text-like control, and focus leaving the whole control for a picker or a group; a checkbox or switch commits on click. Unset, the enclosing `BbForm`'s `validation-mode` applies, then the app's `formControls.validationMode` (`'balanced'`). Only inside a `BbForm`. |
+| `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 group's container (the fieldset). |
+| `legend` | The group's heading — the fieldset `<legend>` (the `legend` prop). |
+| `description` | The muted line under the legend (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`. |
+| `list` | The node that lays the rows out (flex + wrap, gaps on `--gap` / `--row-gap`): `pt:list="grid grid-cols-3"` re-lays them, `pt:list="[--gap:8px]"` tightens them. Takes the group-wide states only. |
+| `item` | One option row — a broadcast, resolved per option with its own `checked` / `disabled` / focus. Takes a per-item function. |
+| `icon` | One row's drawn glyph — the default one: a consumer `icon` slot replaces it. Takes a per-item function. |
+| `label` | One option's label text (the `label` slot's default). Takes a per-item function. |
+| `itemDescription` | One option's muted second line, its description. Takes a per-item function. |
+
+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 |
+| --- | --- |
+| `hasValue` | Component-wide: at least one option is chosen. |
+| `checked` | Per row, on `item`, `icon`, `label` and `itemDescription`: that option is chosen. Never on a field part. |
+| `readonly` | Component-wide: the group is `readonly`. |
+| `disabled` | Component-wide while the group is `disabled`; also per row, on the row parts of an option that is disabled on its own. |
+| `warnings` | Component-wide: the group shows warnings and no errors. |
+| `errors` | Component-wide: the group shows errors. |
+| `focused` | Per row, on the row parts: that option's input has focus — any focus, mouse included. |
+| `focusVisible` | Per row, on the row parts: that option's focus is keyboard-visible — where a focus ring belongs. |
+| `loading` | Component-wide: the items are being fetched. |
 
 ## Events
 
-- `active` — `(e: "active"): void` — Emitted when the group becomes active (focus/click enters it).
-- `blur` — `(e: "blur", event: FocusEvent): void` — Emitted when one of the generated radio inputs loses focus. Forwards the original DOM `FocusEvent`.
-- `change` — `(e: "change", event: Event): void` — Emitted when a radio option is selected. Forwards the original DOM `Event` from the radio input.
-- `click` — `(e: "click", event: MouseEvent): void` — Emitted when one of the generated radio inputs is clicked. Forwards the original DOM `MouseEvent`.
-- `focus` — `(e: "focus", event: FocusEvent): void` — Emitted when one of the generated radio inputs receives focus. Forwards the original DOM `FocusEvent`.
-- `inactive` — `(e: "inactive"): void` — Emitted when focus/click moves outside the group after it was active. Useful for validation-on-blur flows at group level.
-- `input` — `(e: "input", event: Event): void` — Emitted on native input events from generated radio inputs. Forwards the original DOM `Event`.
-- `keydown` — `(e: "keydown", event: KeyboardEvent): void` — Emitted for keyboard interaction on generated radio inputs. Forwards the original DOM `KeyboardEvent`.
-- `mousedown` — `(e: "mousedown", event: MouseEvent): void` — Emitted when a pointing device button is pressed over a radio input. Forwards the original DOM `MouseEvent`.
-- `mouseup` — `(e: "mouseup", event: MouseEvent): void` — Emitted when a pointing device button is released over a radio input. Forwards the original DOM `MouseEvent`.
-- `update:modelValue` — `(e: "update:modelValue", value: any): void` — Emitted with the newly selected value when the selection changes.
+- `active` — `(): void` — Emitted when the group becomes active (focus/click enters it).
+- `blur` — `(event: FocusEvent): void` — Emitted when one of the generated radio inputs loses focus. Forwards the original DOM `FocusEvent`.
+- `change` — `(event: Event): void` — Emitted when a radio option is selected. Forwards the original DOM `Event` from the radio input.
+- `click` — `(event: MouseEvent): void` — Emitted when one of the generated radio inputs is clicked. Forwards the original DOM `MouseEvent`.
+- `focus` — `(event: FocusEvent): void` — Emitted when one of the generated radio inputs receives focus. Forwards the original DOM `FocusEvent`.
+- `inactive` — `(): void` — Emitted when focus/click moves outside the group after it was active. Useful for validation-on-blur flows at group level.
+- `input` — `(event: Event): void` — Emitted on native input events from generated radio inputs. Forwards the original DOM `Event`.
+- `keydown` — `(event: KeyboardEvent): void` — Emitted for keyboard interaction on generated radio inputs. Forwards the original DOM `KeyboardEvent`.
+- `mousedown` — `(event: MouseEvent): void` — Emitted when a pointing device button is pressed over a radio input. Forwards the original DOM `MouseEvent`.
+- `mouseup` — `(event: MouseEvent): void` — Emitted when a pointing device button is released over a radio input. Forwards the original DOM `MouseEvent`.
+- `update:modelValue` — `(value: any): void` — Emitted with the newly selected value when the selection changes.
 
 ## Slots
 
 - `append` — scope: `object` — Content rendered after the last option, inside the options container.
-- `icon` — scope: `BaseRadioGroupIconSlotProps<T>` — Replaces the default radio dot icon for each option. Receives all `BaseRadio` slot attributes plus the source item and its display text.
-- `label` — scope: `BaseRadioGroupLabelSlotProps<T>` — Replaces the default label text for each option.
-- `legend` — scope: `BbRadioGroupLegendSlotProps` — Replaces the default fieldset legend text for the group.
+- `description` — scope: `BbRadioGroupDescriptionSlotProps` `{ 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`.
+- `empty` — scope: `object` — Content shown when no options are available (replaces the default "no data" text).
+- `icon` — scope: `BbRadioGroupIconSlotProps<T>` `{ disabled: boolean; readonly: boolean; checked: boolean; focused: boolean; focusVisible: boolean; id: string; name: string; hasErrors: boolean; hasWarnings: boolean; parsedValue: string; value: any; item: T; text: string }` — Replaces the default radio dot icon for each option. Receives the radio state plus the source item and its display text.
+- `label` — scope: `BbRadioGroupLabelSlotProps<T>` `{ item: T; text: string; checked: boolean; description: string }` — Replaces the default label text for each option.
+- `legend` — scope: `BbRadioGroupLegendSlotProps` `{ text: string; hasErrors: boolean; hasWarnings: boolean }` — Replaces the default fieldset legend text for the group.
 - `loading` — scope: `object` — Content shown while options are loading (replaces the default loading text).
-- `no-data` — scope: `object` — Content shown when no options are available (replaces the default "no data" text).
 - `prepend` — scope: `object` — Content rendered before the first option, inside the options container.
 
-## Validated variant
+## CSS custom properties
 
-Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).
+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).
 
-| Prop | Type | Description |
+| Property | Default | What it is |
 | --- | --- | --- |
-| `rules` | `RuleExpression<any>` | vee-validate rules for this field. |
-| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
-| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |
+| `--gap` | `24px` | Space between rows on one line. |
+| `--row-gap` | `10px` | Space between wrapped lines. |
+| `--tile-min-width` | `96px` | How narrow a tile may get before the tiles wrap (`tiles` only). |
+
+## Component tree
+
+`BbRadioGroup` is not one component: rendering it mounts every component below, and each one is live inside it. **Read this before styling, theming or debugging `BbRadioGroup`, 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 `BbRadioGroup`. A pt part listed as landing there is set on `BbRadioGroup` (`pt:<part>`).
+- **_public_** nodes are components with their own contract. `BbRadioGroup` 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 `BbRadioGroup`'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 `BbRadioGroup`'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 `BbRadioGroup`'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`.
+
+- `BbRadioGroup` _(this component)_ — its own template binds: `icon` → `BbBaseRadioIcon`
+  - `CommonField` _(internal — not importable, reach it through `BbRadioGroup`)_ — `BbRadioGroup`'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`
+  - `OptionsContainer` _(internal — not importable, reach it through `BbRadioGroup`)_ — `BbRadioGroup`'s pt parts land here: `list` → `span`, `item` → `label`, `label` → `span`, `itemDescription` → `span`
+  - Also mounts `BbBaseRadioIcon`
 
 ## See Also