bitboss-ui 3.0.0-beta.63 → 3.0.0-beta.65

package/dist/ai/BbHost.md

@@ -143,10 +143,10 @@ without a mismatch.
 - Listed nodes are the ones `BbHost`'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 `manifest/components/BbHost.tree.json`.
 
 - `BbHost` _(this component)_
-  - `BbToast` _(internal — not importable, reach it through `BbToast`)_ — documented CSS variables: `--gap`, `--offset`, `--width`, `--lift`, `--stack-y`, `--stack-scale`, `--enter-y`, `--swipe-amount`, `--z`, `--r`, `--ring-size`, `--bg`, `--border-color`, `--fg`, `--icon-color`
+  - `BbToast` _(internal — not importable, reach it through `BbToast`)_ — documented CSS variables: `--gap`, `--offset`, `--width`, `--lift`, `--stack-y`, `--stack-scale`, `--enter-y`, `--swipe-amount`, `--z`, `--r`, `--ring-size`, `--bg`, `--border-color`, `--bw`, `--fg`, `--icon-color`
     - `BbToastRegion` _(internal — not importable, reach it through `BbToast`)_ — its own pt parts (`BbToast`): `root` → `ol.bb-toast`
       - `BbToastMessage` _(internal — not importable, reach it through `BbToast`)_ — also mounts `BbIcon`, `BbSpinner`
-        - `BbButton` _(public — [contract](./BbButton.md))_ — its own pt parts (`BbButton`): `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `BbIcon`, `text` → `span.bb-button__text`; documented CSS variables: `--h-xs`, `--h`, `--icon-size`, `--px`, `--fs`, `--r`, `--gap`, `--bg`, `--bg-hover`, `--bg-pressed`, `--fg`, `--border-color`, `--ring-color`, `--ring-size`, `--bw`, `--fg-hover`, `--border-hover`, `--fg-pressed`, `--border-pressed`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--opacity-disabled`, `--elev-tier`, `--elev`; also mounts `BbIcon`, `BbSpinner`
+        - `BbButton` _(public — [contract](./BbButton.md))_ — its own pt parts (`BbButton`): `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `span.bb-button__icon`, `icon` → `BbIcon`, `icon` → `span.bb-button__prepend-icon`, `text` → `span.bb-button__text`, `icon` → `span.bb-button__append-icon`; documented CSS variables: `--h-xs`, `--h`, `--icon-size`, `--px`, `--fs`, `--r`, `--gap`, `--bg`, `--bg-hover`, `--bg-pressed`, `--fg`, `--border-color`, `--ring-color`, `--ring-size`, `--bw`, `--fg-hover`, `--border-hover`, `--fg-pressed`, `--border-pressed`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--opacity-disabled`, `--elev-tier`, `--elev`; also mounts `BbIcon`, `BbSpinner`
           - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
 
 ## See Also

package/dist/ai/BbHoverCard.md

@@ -253,7 +253,8 @@ the card. The same holds for `BbTooltip` / `v-bb-tooltip`.
 ### Placement, offset and width
 
 The same props as `BbPopover`, with the same defaults: `placement` (`bottom`,
-auto-flipping near an edge), `offset` (`4`), `padding` (`10`), `boundary`, and
+auto-flipping near an edge, read at open: a change while open applies at the
+next open), `offset` (`4`), `padding` (`10`), `boundary`, and
 `width` in pixels or as a percentage of the activator. A hover card never has an
 arrow. `placement="cursor"` is `BbPopover`'s alone (it anchors at a click
 point).
@@ -432,8 +433,11 @@ value written in `<script>` is typed as `BbHoverCardProps['pt']`.
   wanders off. That is `BbPopover`.
 - **Don't use it for one line of text** — that is `BbTooltip`, which also
   describes the activator to a screen reader.
-- **Don't put it on a non-focusable element** (a bare `<span>`) — keyboard users
-  could never open it. Use a link or a button.
+- **Don't put it on a non-focusable element** (a bare `<span>`, a `BbIcon`, an
+  `<svg>`). It opens there on hover, but keyboard focus never reaches it, so
+  for a keyboard or touch user the card does not exist. Host it on a link (a
+  person's name) or a button (an icon-only ghost `BbButton`, its slot text the
+  name); never add a `tabindex` to an icon instead.
 - **Don't open it from `@click`** — a click never toggles a hover card; bind
   `v-model` if something else must open it.
 

package/dist/ai/BbIcon.md

@@ -441,12 +441,18 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 ### Accessibility
 
 A meaningful icon needs a `label`: it adds `role="img"` and an `aria-label` —
-no native `title`, so no browser tooltip ever appears; when a hover tooltip is
-wanted, attach the `v-bb-tooltip` directive. Omit `label` for **decorative** icons that
-sit beside a visible text label, so assistive tech does not announce the same
-thing twice. `BbIcon` is **never focusable** (`focusable="false"` is always set)
-— it is not interactive; interactivity belongs to the `BbButton`/`BbBaseButton`
-wrapping it.
+no native `title`, so no browser tooltip ever appears. Omit `label` for
+**decorative** icons that sit beside a visible text label, so assistive tech
+does not announce the same thing twice. `BbIcon` is **never focusable**
+(`focusable="false"` is always set) — it is not interactive; interactivity
+belongs to the `BbButton`/`BbBaseButton` wrapping it.
+
+An info icon with a tip is therefore a button, not a bare icon: an icon-only
+ghost `BbButton` takes keyboard focus, which opens the tip, and its slot text
+is the name (`<BbButton variant="ghost" icon="lucide:info" v-bb-tooltip="'Prices include VAT'">About prices</BbButton>`).
+For text that must be readable on touch, use a `BbPopover` toggletip. A
+`v-bb-tooltip` on a bare `BbIcon` is a pointer-only hint: keyboard and touch
+never open it.
 
 **Meaningful vs decorative**
 

package/dist/ai/BbIndicator.md

@@ -325,7 +325,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 
 | 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: `bubble`, `root`. States: —. 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 `BbIndicatorProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+| `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: `bubble`, `root`. States: `default`, `destructive`, `info`, `success`, `warning`. 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 `BbIndicatorProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `bottom` | `boolean \| undefined` | `false` |  | Anchors the indicator to the bottom edge of the wrapped element instead of the top. |
 | `dot` | `boolean \| undefined` | `false` |  | Renders a small contentless dot instead of a labelled bubble. Takes precedence over `text`. |
 | `left` | `boolean \| undefined` | `false` |  | Anchors the indicator to the left edge of the wrapped element instead of the right. |
@@ -343,6 +343,16 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `root` | The anchor wrapper the bubble is positioned in. Sizing lives here: `size`, `--fs` and `--offset` (the corner overhang) are tokens on `root`. |
 | `bubble` | The count or dot itself — rendered only while there is a `text` or `dot`. Put the look here, the sizing on `root`. |
 
+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 |
+| --- | --- |
+| `default` | Component-wide: `variant: 'default'`. Merged after the part's base entry and before its states, so the real states still win. |
+| `destructive` | Component-wide: `variant: 'destructive'`. Below the real states, like every variant. |
+| `info` | Component-wide: `variant: 'info'`. Below the real states, like every variant. |
+| `success` | Component-wide: `variant: 'success'`. Below the real states, like every variant. |
+| `warning` | Component-wide: `variant: 'warning'`. Below the real states, like every variant. |
+
 ## Events
 
 - None.

package/dist/ai/BbNumberInput.md

@@ -858,7 +858,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 
 | 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: `box`, `clear`, `description`, `hint`, `icon`, `input`, `label`, `message`, `prefix`, `root`, `spinner`, `suffix`. States: `disabled`, `errors`, `hasValue`, `loading`, `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 `BbNumberInputProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+| `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: `box`, `clear`, `description`, `hint`, `icon`, `input`, `label`, `message`, `prefix`, `root`, `spinner`, `suffix`. States: `disabled`, `errors`, `ghost`, `hasValue`, `loading`, `outline`, `readonly`, `secondary`, `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 `BbNumberInputProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
 | `autocomplete` | `string \| undefined` | `"off"` |  | Guides the browser as to the type of information expected in the field. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Focuses the field when it mounts (a dialog already open included), unless the user is typing in another field. |
@@ -931,6 +931,9 @@ States are listed in precedence order: when two are on at once and their entries
 | `warnings` | Component-wide: the control is in its warning state (`warnings` / `has-warnings`) and not in an error state — errors win, so the two are never on together. |
 | `errors` | Component-wide: the control is in its error state (`errors` / `has-errors`, or its validation) — the message line and the box turn red. |
 | `loading` | Component-wide: `loading` is on; the box shows its `spinner`. |
+| `ghost` | On the field's parts: `variant: 'ghost'`. Below the real states, like every variant. |
+| `outline` | On the field's parts: `variant: 'outline'`. Merged after the part's base entry and before its states, so the real states still win. |
+| `secondary` | On the field's parts: `variant: 'secondary'`. Below the real states, like every variant. |
 
 ## Events
 

package/dist/ai/BbOffCanvas.md

@@ -218,6 +218,40 @@ const { data: side } = useBbOffCanvasContext<Side>('edge-panel');
 </script>
 ```
 
+#### A different side per breakpoint
+
+`side` also takes a per-breakpoint map, the same ladder as `size` and
+BbButton's `size` (`default`, `sm`, `md`, `lg`, `xl`, `2xl`; a breakpoint with
+no entry falls back to the nearest smaller one). The classic case is a bottom
+sheet on a phone that becomes a right drawer on a desktop:
+
+**Bottom on a phone, right from md**
+
+```vue
+<div>
+	<BbButton v-bb-off-canvas="'responsive-side'" variant="outline">Details</BbButton>
+	<BbOffCanvas
+		id="responsive-side"
+		:side="{ default: 'bottom', md: 'right' }"
+		title="Details"
+	>
+		<p class="m-0 text-sm">
+			A sheet below 768px, a drawer from <code>md</code> up. Resize, then
+			close and reopen it.
+		</p>
+	</BbOffCanvas>
+</div>
+```
+
+The side is chosen **when the panel opens** and kept until it closes: an open
+panel never swings to another edge on a resize (or a phone rotation); the
+next opening picks again. Everything that follows the side follows that
+choice: the slide, the drag axis, the safe-area insets, the rounded edge, the
+snap points (bottom only) and stacking. On the server the map resolves at the
+SSR width (`ssrViewportWidth`, desktop by default), like every width-derived
+binding; a panel open on load takes the real width as the page hydrates,
+before it paints.
+
 ### Header, footer and body
 
 A `title` prop renders the standard header (title text + close button) and wires
@@ -842,12 +876,12 @@ drill in: opening a child shifts the parent inward by `stack-gap` (default
 Closing the child brings the parent forward. Panels with **different names (or
 none) are independent** and simply layer by open order.
 
-Each stacked panel dims the panels beneath it (via `--bb-overlay-stacked`, the same
+Each stacked panel dims the panels beneath it (via `--bb-overlay-above`, the same
 dim as `--bb-overlay` by default); only the bottom-most blurs. So a child opening
 over a parent visibly darkens the parent, closing it fades that dim out with it,
 and the bottom panel's blurred backdrop is never handed off — nothing behind
 brightens or re-blurs, and a three-deep stack still costs one blur pass. Set
-`--bb-overlay-stacked: transparent` for a single dim under the whole pile.
+`--bb-overlay-above: transparent` for a single dim under the whole pile.
 Backdrop layering follows **open order across all off-canvases**, whatever their
 `stack` name — the name only controls the step-back. Use a stack for master →
 detail flows where the trail should stay visible; if the parent should be fully
@@ -1388,7 +1422,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `preventClose` | `boolean \| undefined` | ``undefined` (follows a saving form inside)` |  | Refuses every user close (backdrop, Escape, drag, the ✕, the slots' `close`) with the deny nudge; `v-model` still closes. Unset: locked while a `BbForm` inside saves (an async `@submit`). `true`: always; `false`: never, not even mid-save. Beside a form: `busy \|\| undefined`. |
 | `queryKey` | `string \| undefined` | `"offcanvas"` |  | The query key `navigation` writes. |
 | `replace` | `boolean \| undefined` | `false` |  | With `navigation`, replaces the history entry instead of pushing one, so Back leaves the page instead of closing the panel. |
-| `side` | `"left" \| "top" \| "bottom" \| "right" \| undefined` | `"left"` |  | Which viewport edge the offcanvas docks to (and slides in from). |
+| `side` | `Responsive<"left" \| "top" \| "bottom" \| "right"> \| undefined` | `"left"` |  | Which viewport edge the offcanvas docks to (and slides in from). Also a per-breakpoint map (e.g. `{ default: 'bottom', md: 'right' }`), resolved when the panel opens: an open panel keeps its side through a resize. |
 | `size` | `Responsive<OffCanvasSize> \| undefined` | `"sm"` |  | The panel's extent along its axis: a left/right panel's width (shrinks with a narrower viewport) or a top/bottom one's height (capped at the viewport). A preset `'xs'`–`'2xl'`, `'auto'`, a CSS size, a pixel number, or a per-breakpoint map (e.g. `{ default: 'sm', lg: 'lg' }`). |
 | `snap` | `BbSnapPoint \| undefined` |  |  | The snap stop the sheet rests at, written as one of the `snapPoints` entries (Q71.8). Updated once the sheet settles on another stop; setting it moves the sheet there. Unbound, every opening starts at the first stop. |
 | `snapPoints` | `BbSnapPoint[] \| undefined` |  |  | Heights a draggable bottom sheet rests at, smallest first: a fraction of the screen (`0.5`, `1` = full) or `'240px'`. The first is the opening height; `v-model:snap` holds the stop. Ignored on other sides and `fullscreen` (guide § Snap points). |

package/dist/ai/BbPopover.md

@@ -468,7 +468,8 @@ const rename = (report: Report, close: () => void) => {
 `bottom` / `left` families, each with `-start` / `-end` alignment variants
 (e.g. `bottom-start`). It defaults to `bottom`. The panel **auto-flips** to stay
 in view near a viewport edge, so pick the placement that reads best in the
-common case and let it correct itself.
+common case and let it correct itself. `placement` is read at open: a change
+while open applies at the next open.
 
 Fine-tune the geometry with:
 

package/dist/ai/BbRadio.md

@@ -441,7 +441,7 @@ const strategy = ref<MergeMethod>('squash');
 </script>
 ```
 
-An attribute in `attrs` wins over ours. The visually hidden native input is
+An attribute in `attrs` wins over ours. The invisible native input under the glyph 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).

package/dist/ai/BbRadioGroup.md

@@ -33,6 +33,27 @@
 | `--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. |
 | `--ctrl-line` | `pt:label` | `CommonField` | Where the control's first line is centred, from the top of the control column (half the box height by default); the label's first line aligns to it in side-by-side layouts. |
+| `--list-bg` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | The strip behind the triggers |
+| `--list-border` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | The strip's edge line, --bb-border-w thick, painted inside the strip: under the triggers (beside them when vertical). `pill` draws none; `line` sets it to --bb-border |
+| `--p` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | strip inner padding — the gutter the indicator sits in, and the scroll inset |
+| `--list-r` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | strip corners |
+| `--list-h` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | strip min height |
+| `--fs` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | trigger label size |
+| `--trigger-gap` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | space between triggers |
+| `--trigger-px` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | trigger side padding |
+| `--trigger-r` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | Trigger corners, concentric inside --list-r |
+| `--trigger-min-h` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | Trigger height inside the padded strip |
+| `--list-fg` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | unchecked trigger label |
+| `--hover-fg` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | hovered trigger label |
+| `--active-fg` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | checked trigger label |
+| `--active-fw` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | checked trigger label weight (unchecked labels are 500) |
+| `--indicator-bg` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | the indicator's fill |
+| `--indicator-border` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | The indicator's edge |
+| `--indicator-r` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | The indicator's corners — the pill's, concentric inside --list-r |
+| `--indicator-h` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | The indicator's thickness: its height, its width on a vertical strip. `initial` fills the whole trigger box — the pill; a bar is `2px`, on the trigger's bottom edge (inline-end edge when vertical) |
+| `--indicator-inset` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | Inset of the indicator from the trigger box — shrinks the pill; a bar keeps its thickness, shortens by it at both ends and floats it above the edge |
+| `--elev` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | The theme's resting lift, composed UNDER the indicator's own shadow |
+| `--indicator-shadow` | `pt:list`, `pt:item`, `pt:label`, `pt:itemDescription` | `OptionsContainer` | Indicator lift, painted on top of --elev |
 
 ## Usage & Guidelines
 
@@ -326,10 +347,68 @@ const method = ref<string>('standard');
 
 #### Segmented control
 
-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:
+Pick a value → `BbRadioGroup`; switch views → `BbTabs`. A strip that picks a
+value a form or a filter submits (a status filter, a period) is still a
+radiogroup (arrow keys, "2 of 4"), so give the group a tab strip's look:
+`variant="pill"` (a muted strip, a raised pill under the pick) or
+`variant="line"` (a baseline across the field, a bar under the pick). The
+strip, its triggers and the indicator measure exactly as BbTabs', and the
+indicator slides as a tab strip's does. The dot is hidden (an `icon` slot
+shows before the label, like a tab's icon) and the strip never wraps (it
+scrolls); `list-layout="vertical"` stacks it into a column (the indicator
+slides on the Y axis), `"vertical-stretch"` spans the field, and the other
+layouts and `item-layout` do not apply. The legend, errors, `compact` and
+`hide-legend` work as on any group. `pt:indicator` reaches the pill or the
+bar, and `pt:<part>:pill` / `pt:<part>:line` style a part in one look only.
+
+**Pick a value with the tabs look**
+
+```vue
+<template>
+	<div class="flex flex-col gap-4">
+		<BbRadioGroup
+			v-model="status"
+			hide-legend
+			:items="statuses"
+			legend="Status"
+			variant="pill"
+		/>
+		<BbRadioGroup
+			v-model="period"
+			hide-legend
+			:items="periods"
+			legend="Period"
+			variant="line"
+		/>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbRadioGroup } from 'bitboss-ui';
+
+// BbTabs' two looks on a value picker: `pill` (a muted strip, a raised pill
+// under the pick) and `line` (a baseline across the field, a bar under the
+// pick). The indicator slides like a tab strip's, and it is still a
+// radiogroup: arrow keys move and pick, a form submits the value.
+const statuses = ['All', 'Open', 'Closed', 'Archived'];
+const status = ref('Open');
+const periods = ['Day', 'Week', 'Month', 'Year'];
+const period = ref('Week');
+</script>
+```
+
+The strip has its own tokens, named and valued as a tab strip's (`--list-bg`,
+`--p`, `--trigger-px`, `--indicator-bg`, `--indicator-h`, `--active-fg`, …):
+set them on `pt:list` to retune one group. A look of your own app-wide is a
+registered variant: `radioVariants: ['brand']` in the build plugin, then the
+same tokens on `.bb-radio-group__list--brand` in your CSS. A tabs theme does
+not reach a choice strip, nor the other way round.
+
+For a look of your own, build the tiles from `pt` instead: 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**
 
@@ -344,7 +423,7 @@ colour on `pt:item` never reaches it:
 			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="justify-items-center 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"
@@ -563,6 +642,15 @@ so without it a keyboard user cannot see which tile has focus.
 slot does not remove it: the default dot is the slot's fallback and renders
 whenever the slot is empty.
 
+A side hidden with the library's or Tailwind's hiding classes takes its gap
+with it: a dot hidden with `pt:icon="hidden"` (or `sr-only`), or a label
+hidden with `hide-label` or `pt:label="sr-only"`, leaves the other side
+centred, no `gap-0` needed. In `list-layout="tiles"` the whole tile is the
+click and hover target, padding included (a tooltip whose activator is the
+row's input shows anywhere on it); a link or a button inside a tile keeps its
+own click. List rows keep the dot as the target, beside a label that selects
+too.
+
 **Theme selection tiles**
 
 ```vue
@@ -817,7 +905,7 @@ 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']`
+`pt` prop) is typed as `BbRadioGroupProps<Row>['pt']`, or `BbRadioGroupProps<object>['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).
@@ -881,7 +969,7 @@ for a preset that fits any row type (never `<any>`), not an imported
 
 | 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>`. |
+| `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`, `indicator`, `item`, `itemDescription`, `label`, `legend`, `list`, `message`, `root`. States: `disabled`, `errors`, `hasValue`, `line`, `loading`, `pill`, `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<object>['pt']` for a preset that fits any row type, never `<any>`) (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Focuses the field when it mounts (a dialog already open included), unless the user is typing in another field. |
 | `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. |
@@ -927,6 +1015,7 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `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. |
 | `validationLabel` | `string \| undefined` |  |  | The field's name in validation messages (`{field}`): "Email is not valid". Defaults to the `label` (or `legend`), then "This field"; never the `name`. Set it when the label is hidden or reads badly in a sentence (icon-only, a question). `BbForm` only. |
 | `validationMode` | `'aggressive'` \| `'balanced'` \| `'lazy'` \| `'submit-only'` \| `'submit-live'` |  |  | When the field validates: `aggressive` (each change), `balanced` (on leave, then live while in error), `lazy` (on leave), `submit-only`, `submit-live`. Unset: the `BbForm`'s `validation-mode`, then `formControls.validationMode` (`'balanced'`). `BbForm` only. |
+| `variant` | `'pill'` \| `'line'` |  |  | A tab-strip look (Q76.11 d): `'pill'` (a raised pill under the pick) or `'line'` (a bar on a baseline); the indicator slides like a tab strip's. `list-layout="vertical"` stacks it. Register more with `radioVariants`. Unset: the group's own rows. |
 | `warnings` | `string \| string[] \| undefined` |  |  | Warning messages under the field, a string or array: amber, in their own `aria-live` region and in the control's `aria-describedby` after the errors. Non-empty turns on the warning state; errors win when both are set. |
 
 ## Passthrough parts and states
@@ -940,7 +1029,8 @@ for a preset that fits any row type (never `<any>`), not an imported
 | `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. |
+| `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. With a `variant`, the tab strip. Takes the group-wide states only. |
+| `indicator` | With a `variant`: the shape under the checked option, BbTabs' indicator — the sliding pill or bar of a radio group, a checkbox group's pill per run of adjacent picks (or bar per pick). 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. |
@@ -959,6 +1049,8 @@ States are listed in precedence order: when two are on at once and their entries
 | `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. |
+| `line` | On every part: `variant: 'line'`. Below the real states, like every variant. |
+| `pill` | On every part: `variant: 'pill'`. Merged after the part's base entry and before its states, so the real states still win. |
 
 ## Events
 
@@ -1004,9 +1096,9 @@ Set these on the element, or on a class you put on it, to retune this component
 - **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 `manifest/components/BbRadioGroup.tree.json`.
 
-- `BbRadioGroup` _(this component)_ — its own template binds: `icon` → `BbBaseRadioIcon`
+- `BbRadioGroup` _(this component)_ — its own template binds: `indicator` → `span.bb-radio-group__indicator`, `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`, `counter` → `span.bb-field__counter`, `message` → `div.bb-field__message`; documented CSS variables: `--ctrl-line`; 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`
+  - `OptionsContainer` _(internal — not importable, reach it through `BbRadioGroup`)_ — `BbRadioGroup`'s pt parts land here: `list` → `span`, `item` → `label`, `label` → `span`, `itemDescription` → `span`; documented CSS variables: `--list-bg`, `--list-border`, `--p`, `--list-r`, `--list-h`, `--fs`, `--trigger-gap`, `--trigger-px`, `--trigger-r`, `--trigger-min-h`, `--list-fg`, `--hover-fg`, `--active-fg`, `--active-fw`, `--indicator-bg`, `--indicator-border`, `--indicator-r`, `--indicator-h`, `--indicator-inset`, `--elev`, `--indicator-shadow`
   - Also mounts `BbBaseRadioIcon`
 
 ## See Also

package/dist/ai/BbSelect.md

@@ -972,11 +972,37 @@ Laziness), until the user opens it:
 - **Shape and matching.** A known row is `{ value, label }`: `value` is what
   the `v-model` holds, matched exactly (`"7"` does not name `7`), and `label`
   is its text. `item-value`, `item-text`, `item-props`, `selectable` and
-  `group-by` are the options' and never run on it, so until the list brings
-  the real row, slots get the `{ value, label }` row as `item` (read `text`
-  and `value`). A value no row names loads as it would without the prop, so
-  missing or wrong rows are never worse than today; entries without a `value`
-  key (`null`, a record in the options' shape) are skipped.
+  `group-by` are the options' and never run on it. A value no row names loads
+  as it would without the prop, so missing or wrong rows are never worse than
+  today; entries without a `value` key (`null`, a record in the options'
+  shape) are skipped.
+- **Slots: check `known`.** Until the list brings the real row, the `option`
+  and `chip` slots get the `{ value, label }` row as `item`, with
+  `known: true`. On a select that binds `known-items` the slot's `item` is
+  typed `YourRow | BbSelectKnownItem`, so reading an option field straight
+  off it (`item.full_name`) is a type error: it would render blank until the
+  list loads. Test `known` first; `text` and `value` are right on both:
+
+  ```vue
+  <template #option="{ item, known, text }">
+  	{{ text }}
+  	<small v-if="!known">{{ item.email }}</small>
+  </template>
+  ```
+
+  A helper that takes the whole scope is typed with `BbSelectSlotRow<YourRow>`
+  (`row.known ? row.item.label : row.item.full_name`). Selects without
+  `known-items` keep `item: YourRow` and `known: false`; so does a preset
+  made with `definePreset(BbSelect<YourRow>, …)` (rev 4) until its caller
+  binds `known-items`, and then it narrows the same way. A preset's own
+  default `slots` get `known` too, always: it cannot know whether a caller
+  binds them. A `pt` per-item
+  function on the option parts gets the same `{ item, known }`
+  (`option: ({ item, known }) => !known && item.vip && 'font-bold'`). The
+  type alone, `BbSelectProps<YourRow>` (a wrapper's props, a `pt` const), is
+  the bound case, since it cannot know where it lands; write
+  `BbSelectProps<YourRow, undefined>` for code that never binds `known-items`.
+
 - **They are not options.** A known row is listed only while its value is
   selected; the others name a value the model may take later, still with no
   request (after a parent change, see Coherence below).
@@ -1617,11 +1643,11 @@ const createLabel = (text: string) => {
 Set `group-by` to a field path (or a function) to bucket options under headers.
 The `#group` slot styles the header and receives
 `{ text, item, index, length, disabled }` — `length` is the number of options
-in the group, `index` the list index of its first option. A row whose
-`group-by` gives `null` or `undefined` has no group: those rows are listed
-without a header, and `#group` is not called for them (a known row is listed
-the same way). Rows in the middle of the list with no header read as part of
-the group above, so give them a group of their own (`row.team ?? 'Other'`).
+in the group, `index` the list index of its first option. Groups keep the order
+of their first option. A row whose `group-by` gives `null` or `undefined` has
+no group: those rows are listed **first**, before every header, and `#group` is
+not called for them (a known row is listed the same way). `BbDropdown`'s
+`groupBy` follows the same rule.
 
 A grouped list virtualizes **whole groups, not rows**: a group mounts only
 when it scrolls into range, but all of its rows mount together. Many
@@ -1908,7 +1934,13 @@ Shipped behavior — never reimplement it:
 
 - `compact` — denser control and panel (24px options, 24px group headers).
 - The panel width always matches the control; the control fills its container,
-  so size it with layout classes on a wrapper (`class="max-w-xs"` etc.).
+  so size it with layout classes on a wrapper (`class="max-w-xs"` etc.). There
+  is no panel-width prop.
+- **A narrow column with long option labels** (a role in a three-column row):
+  a field that narrow barely shows the picked option, and its panel truncates
+  every row. Use a `BbSelectPopover` on a `BbBadgeButton` instead: the badge is
+  the compact trigger and the panel takes a `width` of its own
+  ([`BbSelectPopover` § A narrow column](./BbSelectPopover.md#a-narrow-column-a-badge-trigger-and-a-panel-of-its-own)).
 - `layout` works whenever the resolved label mode is `'outside'` (the
   library default) — `layout="horizontal"` gives a label-beside-field row,
   and a per-breakpoint map (`{ default: 'vertical', md: 'horizontal' }`)
@@ -2075,7 +2107,7 @@ 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 `BbSelectProps<Row>['pt']`, or `BbSelectProps['pt']`
+`pt` prop) is typed as `BbSelectProps<Row>['pt']`, or `BbSelectProps<object>['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).
@@ -2217,7 +2249,7 @@ it: [passthrough guide § Typing `pt` in `<script>`](./guides/passthrough.md#typ
 
 | 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: `activator`, `badge`, `box`, `clear`, `comma`, `description`, `footer`, `header`, `hint`, `icon`, `input`, `itemDescription`, `itemIcon`, `itemText`, `label`, `list`, `message`, `option`, `panel`, `prefix`, `root`, `sheet`, `spinner`, `suffix`. States: `disabled`, `errors`, `hasValue`, `loading`, `open`, `readonly`, `selected`, `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 `BbSelectProps<Row>['pt']` (`BbSelectProps['pt']` for a preset that fits any row type, never `<any>`) (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+| `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: `activator`, `badge`, `box`, `clear`, `comma`, `description`, `footer`, `header`, `hint`, `icon`, `input`, `itemDescription`, `itemIcon`, `itemText`, `label`, `list`, `message`, `option`, `panel`, `prefix`, `root`, `sheet`, `spinner`, `suffix`. States: `disabled`, `errors`, `ghost`, `hasValue`, `loading`, `open`, `outline`, `readonly`, `secondary`, `selected`, `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 `BbSelectProps<Row>['pt']` (`BbSelectProps<object>['pt']` for a preset that fits any row type, never `<any>`) (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | When `true`, the options panel opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover; on desktop it stays a popover. When unset, falls back to the global `config.adaptive`. |
 | `append:icon` | `string \| undefined` | `the chevron-down glyph` |  | Name of the icon to be added at the end of the input. |
 | `autocomplete` | `string \| undefined` |  |  | Guides to the browser as to the type of information expected in the field. |
@@ -2249,7 +2281,7 @@ it: [passthrough guide § Typing `pt` in `<script>`](./guides/passthrough.md#typ
 | `items` | `T[] \| ((context: BbSelectItemsContext) => T[] \| Promise<T[]>)` |  | yes | The options: an array, or a provider called with a `BbSelectItemsContext` (`query`, `reason`, `modelValue`, `signal`), sync or async. Branch on `reason !== 'search'` to resolve the selection by id. A provider fails by THROWING, never by returning `[]`. |
 | `itemText` | `ItemAccessor<T, string> \| undefined` | `own `label`, else `text`, else `JSON.stringify(item)`` |  | Defines a path that returns a property of the object to use as text or a function that returns a string. Unset: own `label`, else `text` (`{ label, value }` needs no accessor). |
 | `itemValue` | `ItemAccessor<T> \| undefined` | `own `value`, else the whole item` |  | Defines a path that returns a property of the object to use as value or a function that returns any value. Unset: own `value`, even `null`. |
-| `knownItems` | `(BbSelectKnownItem \| null \| undefined)[] \| undefined` |  |  | `{ value, label }` rows naming the value the app already holds, whatever the options' shape: no request until the first open (`prefill: true` still loads). Not options; the options' accessors never run on them; slots get the row as `item` until the list brings its own. |
+| `knownItems` | `([Known] extends [undefined] ? BbSelectKnownItems : Known) \| undefined` |  |  | `{ value, label }` rows naming the value the app already holds, whatever the options' shape: no request until the first open (`prefill: true` still loads). Not options; the options' accessors never run on them; slots get the row as `item`, with `known: true`, until the list brings its own. |
 | `label` | `string` |  | yes | Text content of the label of the element. |
 | `labelAlign` | `'top'` \| `'center'` \| `'bottom'` |  |  | Vertical position of the label block in a side-by-side row; not `labelPosition`, the horizontal one. Omitted, the label's first line meets the control's. |
 | `labelMode` | `"outside" \| "floating" \| "inside" \| undefined` |  |  | Label rendering mode. |
@@ -2325,6 +2357,9 @@ States are listed in precedence order: when two are on at once and their entries
 | `errors` | Component-wide: the control is in its error state (`errors` / `has-errors`, or its validation) — the message line and the box turn red. |
 | `open` | Component-wide: the options surface is showing. |
 | `loading` | Component-wide: `loading` is on; the box shows its `spinner`. |
+| `ghost` | On the field's parts: `variant: 'ghost'`. Below the real states, like every variant. |
+| `outline` | On the field's parts: `variant: 'outline'`. Merged after the part's base entry and before its states, so the real states still win. |
+| `secondary` | On the field's parts: `variant: 'secondary'`. Below the real states, like every variant. |
 
 ## Events
 
@@ -2346,7 +2381,7 @@ States are listed in precedence order: when two are on at once and their entries
 
 - `append` — scope: `{ query: string; focus: () => void; close: () => Promise<void>; }` — Content appended inside the input field, after the value area.
 - `append:outer` — scope: `{ query: string; close: () => Promise<void>; }` — Content appended outside the input field wrapper.
-- `chip` — scope: `BbSelectChipSlotProps<T>` `{ item: T; text: string; value: any; disabled: boolean; deselect: () => void }` — Replaces the default badge rendered for each selection in `multiple` mode. Not called in `comma` mode, nor for the collapsed "+N" summary.
+- `chip` — scope: `BbSelectChipSlotProps<T, Known>` `{ known: boolean; item: BbSelectKnownItem \| T; text: string; value: any; disabled: boolean; deselect: () => void }` — Replaces the default badge rendered for each selection in `multiple` mode. Not called in `comma` mode, nor for the collapsed "+N" summary. With `known-items` bound, `item` is the known `{ value, label }` row (`known: true`) until the list brings the real one.
 - `description` — scope: `BbSelectDescriptionSlotProps` `{ 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: `{ query: string; focus: () => void; error: unknown; }` — Content shown when no options match the query or the list is empty. `error` is what the latest failed load threw, untouched (`null` when none).
 - `footer` — scope: `BbSelectPanelSlotProps` `{ close: () => Promise<void>; clear: () => void; focus: () => void; query: string; selectedOptions: BbSelectResolvedOption[] }` — Content pinned to the bottom of the options panel, below the options list. Rendered in both the desktop popover and the adaptive sheet.
@@ -2354,7 +2389,7 @@ States are listed in precedence order: when two are on at once and their entries
 - `header` — scope: `BbSelectPanelSlotProps` `{ close: () => Promise<void>; clear: () => void; focus: () => void; query: string; selectedOptions: BbSelectResolvedOption[] }` — Content pinned to the top of the options panel, above the search field. Rendered in both the desktop popover and the adaptive sheet.
 - `label` — scope: `BbSelectLabelSlotProps` `{ showAsterisk?: boolean; text: string; hasErrors: boolean; hasWarnings: boolean }` — Replaces the default label text rendered above the input.
 - `loading` — scope: `{ query: string; }` — Content shown inside the options dropdown while items are loading.
-- `option` — scope: `BbSelectOptionSlotProps<T>` `{ disabled: boolean; focused: boolean; index: number; hasErrors?: boolean; item: T; loading: boolean; selected: boolean; text: string; value: any; description: string }` — Replaces the default rendering of each option row in the dropdown.
+- `option` — scope: `BbSelectOptionSlotProps<T, Known>` `{ known: boolean; item: T \| BbSelectKnownItem; disabled: boolean; focused: boolean; index: number; hasErrors?: boolean; loading: boolean; selected: boolean; text: string; value: any; description: string }` — Replaces the default rendering of each option row in the dropdown. With `known-items` bound, a row the list has not brought yet is the known `{ value, label }` row, `known: true`: check `known` before reading an option field off `item`.
 - `prefix` — scope: `object` — Content rendered as an inline prefix inside the input field.
 - `prepend` — scope: `{ query: string; focus: () => void; close: () => Promise<void>; }` — Content prepended inside the input field, before the value area.
 - `prepend:outer` — scope: `{ query: string; close: () => Promise<void>; }` — Content prepended outside the input field wrapper.
@@ -2381,7 +2416,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - `BbSelect` _(this component)_ — its own template binds: `badge` → `CommonField`, `activator` → `input.bb-select__activator`, `badge` → `input.bb-select__activator`, `comma` → `span.bb-select__comma`, `badge` → `span.bb-select__comma`, `badge` → `BbBadge`, `controlAttrs` → `input`, `badge` → `input`; hands `BbSelectPopover` the pt map `{ panel: 'panel', sheet: 'sheet', header: 'header', footer: 'footer', input: 'input', list: 'list', option: 'option', itemText: 'itemText', itemIcon: 'itemIcon', itemDescription: 'itemDescription' }` (ours → theirs)
   - `CommonField` _(internal — not importable, reach it through `BbSelect`)_ — `BbSelect`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint`, `counter` → `span.bb-field__counter`, `message` → `div.bb-field__message`; documented CSS variables: `--ctrl-line`; also mounts `BbAsterisk`
   - `CommonFieldInput` _(internal — not importable, reach it through `BbSelect`)_ — `BbSelect`'s pt parts land here: `box` → `span.bb-field-input__box`, `prefix` → `span.bb-field-input__prefix`, `icon` → `BbIcon`, `clear` → `ClearableButton`, `spinner` → `BbSpinner`, `suffix` → `span.bb-field-input__suffix`; documented CSS variables: `--bg`, `--bg-hover`, `--bg-focus`, `--bg-disabled`, `--fg-disabled`, `--border-color`, `--border-focus`, `--ring-size`, `--ring-color`, `--elev`, `--frost`, `--inside-label-clearance`; also mounts `ErrorIcon`, `WarningIcon`, `ClearableButton`, `BbIcon`, `BbSpinner`
-  - `BbBadge` _(public — [contract](./BbBadge.md))_ — its own pt parts (`BbBadge`): `spinner` → `BbSpinner`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear`; documented CSS variables: `--bg`, `--fg`, `--bw`, `--ring-color`, `--ring-size`, `--min-size-md`, `--min-size`, `--elev`, `--r`, `--fs`, `--icon-size`, `--gap`, `--px`, `--clear-size`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--pad-left`; also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
+  - `BbBadge` _(public — [contract](./BbBadge.md))_ — its own pt parts (`BbBadge`): `spinner` → `BbSpinner`, `icon` → `span.bb-badge__append-icon`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear`; documented CSS variables: `--bg`, `--fg`, `--bw`, `--ring-color`, `--ring-size`, `--min-size-md`, `--min-size`, `--elev`, `--r`, `--fs`, `--icon-size`, `--gap`, `--px`, `--clear-size`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--pad-left`; also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
   - `BbSelectPopover` _(public — [contract](./BbSelectPopover.md))_ — its own pt parts (`BbSelectPopover`): `input` → `input.bb-select-popover__input`, `clear` → `ClearableButton`, `panel` → `CommonPopover`, `root` → `CommonPopover`, `header` → `div.bb-select-popover__header`, `footer` → `div.bb-select-popover__footer`; hands `BbOffCanvas` the pt map `{ header: 'header', footer: 'footer', panel: 'root', sheet: 'root' }` (ours → theirs); also mounts `BbBadge`, `BbIcon`, `ClearableButton`, `CommonPopover`, `ErrorIcon`, `WarningIcon`, `BbSmoothHeight`
     - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__content`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--snap-y`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--handle-w`, `--handle-h`, `--handle-bg`, `--safe-top`, `--close-size`
       - `CloseButton` _(internal — not importable, reach it through `BbOffCanvas`)_ — documented CSS variables: `--size`, `--p`