bitboss-ui 3.0.0-beta.52 → 3.0.0-beta.56

package/dist/ai/BbAsterisk.md

@@ -19,8 +19,9 @@ restyle its root), and it does not read
 label content, so the marker matches the library's styling (`--bb-danger`).
 
 Most consumers never place it by hand: the form controls
-render it for you in their `#label` slot when a field is `required`/has rules and
-`config.requiredAsterisk` is enabled. Reach for `BbAsterisk` directly only when
+render it for you in their `#label` slot when a field is required (a
+`required` rule or schema key inside a `BbForm`, the `required` prop outside
+one), unless the app turns `requiredAsterisk` off. Reach for `BbAsterisk` directly only when
 you compose a bespoke label outside those controls.
 
 ```vue
@@ -43,9 +44,9 @@ carries mandatoriness to assistive tech is the **control itself**: the native
 `required` attribute when you set the `required` prop, and
 `aria-required="true"` when a `BbForm` makes the field mandatory (a `required`
 rule or the schema). Inside a form the browser never validates, so there the
-`required` prop is an error (`bitboss-ui/no-required-in-form`): it would mark
-the field with nothing enforcing it; write `rules="required"` or require the
-key in the schema.
+`required` prop is a hint: it marks the field and the server does the
+checking; write `rules="required"` or require the key in the schema to check
+on the client too.
 
 The practical consequence: the marker is a _visual_ affordance only, and the
 control's own required state is the real thing. Never ship a field that shows
@@ -53,9 +54,10 @@ the asterisk without one of them (sighted users see a requirement that
 assistive tech cannot perceive), and never assume the asterisk is doing
 accessibility work.
 
-`showAsterisk` on the form controls is also gated on the plugin option, so
-with `requiredAsterisk: false` there is no way to render the marker through
-them at all — placing `BbAsterisk` by hand is then the only route.
+`showAsterisk` on the form controls is also gated on the plugin option
+(`true` by default), so an app that sets `requiredAsterisk: false` has no way
+to render the marker through them at all — placing `BbAsterisk` by hand is then
+the only route.
 
 ### Restyling with passthrough
 

package/dist/ai/BbAvatar.md

@@ -156,10 +156,9 @@ too, since the dot alone is not announced.
 
 An overlapping stack summarizes a group (reviewers, assignees, attendees); the
 overflow count is just another avatar with the count in its slot. Stacking is
-the one place where overriding avatar internals is warranted — the example's
-scoped CSS pulls each avatar over the previous one with a negative margin and
-separates them with a panel-colored ring (an explicit override of the
-`.bb-avatar` root; keep it in one reusable class).
+a class on each avatar: a negative inline margin pulls every avatar after the
+first over the previous one, and a panel-coloured ring keeps the overlapped
+edges readable (see [Restyling with passthrough](#restyling-with-passthrough)).
 
 **Reviewers stack with overflow**
 
@@ -180,11 +179,14 @@ separates them with a panel-colored ring (an explicit override of the
 			</BbButton>
 		</div>
 
-		<div class="stack">
+		<div class="flex">
 			<BbAvatar
-				v-for="reviewer in visible"
+				v-for="(reviewer, index) in visible"
 				:key="reviewer.name"
 				:alt="reviewer.name"
+				:class="
+					index ? '-ml-3 ring-2 ring-(--bb-panel)' : 'ring-2 ring-(--bb-panel)'
+				"
 				size="40"
 				:src="reviewer.src"
 			>
@@ -193,6 +195,7 @@ separates them with a panel-colored ring (an explicit override of the
 			<BbAvatar
 				v-if="!expanded && hiddenCount > 0"
 				:alt="`${hiddenCount} more reviewers`"
+				class="-ml-3 ring-2 ring-(--bb-panel)"
 				size="40"
 			>
 				+{{ hiddenCount }}
@@ -241,25 +244,6 @@ const visible = computed(() =>
 );
 const hiddenCount = computed(() => reviewers.length - maxVisible);
 </script>
-
-<style scoped>
-/*
- * Deliberate override of the avatar root: stacking needs the negative margin,
- * and the panel-colored ring keeps overlapped edges readable. Keep this in one
- * reusable class — never per-avatar inline styles.
- */
-.stack {
-	display: flex;
-}
-
-.stack :deep(.bb-avatar) {
-	box-shadow: 0 0 0 1px var(--bb-panel);
-}
-
-.stack :deep(.bb-avatar + .bb-avatar) {
-	margin-inline-start: -12px;
-}
-</style>
 ```
 
 ### Team lists
@@ -584,10 +568,11 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
   exists for that.
 - Don't wrap the avatar in a raw `<span @click>` for menus — put it inside
   `BbBaseButton`/`BbDropdown` so focus and keyboard behavior come for free.
-- **The shape is a circle, and it is not configurable.** `border-radius: 50%`
-  is baked in. A rounded-SQUARE avatar — common in dense tables, where a square
-  reads as "entity" and a circle as "person" — has no answer here; build that
-  one yourself rather than fighting the radius.
+- **The frame is a circle (`border-radius: 50%`), and there is no `shape`
+  prop.** For a rounded-square entity avatar (dense tables), restyle the frame:
+  `class="rounded-(--bb-radius)"` in the layered build (`cssLayers`), or
+  `style="border-radius: var(--bb-radius)"` in any build. The image is clipped
+  by the frame, so it follows.
 - Don't pre-crop sources to circles — the component center-crops; ship square
   or larger originals.
 - Don't leave `alt` empty for meaningful avatars: fallbacks lose their

package/dist/ai/BbBadge.md

@@ -70,7 +70,8 @@ For a small, closed status set (paid / pending / overdue, plan tiers), register
 the soft palette from
 [design language guide](./guides/design-language.md) § Using color
 (`soft-gray` / `soft-blue` / `soft-green` / `soft-amber` / `soft-red`) and style
-`.bb-badge--<name>` in your project stylesheet. Never invent `variant="success"`
+`.bb-badge--<name>` in your project stylesheet. Type a status map as
+`Record<Status, BadgeVariantType>`. Never invent `variant="success"`
 — that name is not built-in and ships no CSS. The example below uses the soft
 names: in your app it type-checks only after the `badgeVariants` registration
 and renders styled only with that CSS — both are in the linked section.
@@ -350,22 +351,9 @@ swap the inputs use); and **`icon`** (icon-only) becomes a removable glyph.
 Active filters are the classic product shape: a chip row, each badge owned by
 your state, cleared one-by-one or all at once.
 
-**Size rule — match the pair, don't memorise a constant.** Badge scale is not
-button scale, so the number that looks right depends on the button standing
-next to it. A rail picks **one matched pair** and uses it for every chip:
-
-| Badge size     | Height | Pairs with button               |
-| -------------- | ------ | ------------------------------- |
-| `md` (default) | ≈16px  | — (inline token, opens nothing) |
-| `lg`           | ≈20px  | `xs`                            |
-| `xl`           | ≈24px  | `sm`                            |
-| `2xl`          | ≈28px  | `md`                            |
-
-So a rail whose Filters trigger is a `sm` button wants `xl` chips; drop the
-trigger to `xs` and the chips go to `lg`. Copying `sm`/`md` from an inline
-example into a rail is what makes chips look toy-sized next to their own
-button. Reserve `sm` for dense in-table status pills, and omit `size`
-(default `md`) only for a plain inline token that opens nothing.
+Size the chips to the button beside them — see
+[Sizes § Beside a control](#beside-a-control-match-the-button): a rail with a
+`sm` Filters button wants `xl` chips.
 
 **A removable filter bar**
 
@@ -449,7 +437,16 @@ const onReset = () => {
 
 A plain badge is inert. To make the badge itself clickable, slot a
 **`BbBadgeButton`** as a **direct child** — it takes over the badge's body and
-renders it as a real `<button>`:
+renders it as a real `<button>`.
+
+**Direct child only.** The badge decides what its body is while it renders,
+by looking at the vnodes in its default slot, before any child exists — so
+it sees a `BbBadgeButton` only when it is right there in the slot. Put it
+inside your own component or a wrapping element, or slot a plain `<button>`,
+and the badge renders its normal body around it: the label shows twice and you
+get a button inside a button. Write the `<BbBadgeButton>` in the badge's slot
+itself; to reuse a configured chip, wrap the whole `<BbBadge>` in your
+component, never the companion alone.
 
 **A clickable pill**
 
@@ -609,6 +606,25 @@ const onPick = (option: Status) => {
 Badges follow the shared `xs → 2xl` scale (default `md`; an invalid size warns
 in dev and falls back to `md`). Keep one size per cluster.
 
+#### Beside a control: match the button
+
+Badge scale is not button scale: the size that looks right depends on the
+button standing next to the badge (a filter rail, a toolbar, a chip row with
+its trigger). Pick **one matched pair** and use it for every chip:
+
+| Badge size     | Height | Pairs with button               |
+| -------------- | ------ | ------------------------------- |
+| `md` (default) | ≈16px  | — (inline token, opens nothing) |
+| `lg`           | ≈20px  | `xs`                            |
+| `xl`           | ≈24px  | `sm`                            |
+| `2xl`          | ≈28px  | `md`                            |
+
+So a rail whose Filters trigger is a `sm` button wants `xl` chips; drop the
+trigger to `xs` and the chips go to `lg`. Copying `sm`/`md` from an inline
+example into a rail is what makes chips look toy-sized next to their own
+button. Reserve `sm` for dense in-table status pills, and omit `size`
+(default `md`) only for a plain inline token that opens nothing.
+
 **The size scale**
 
 ```vue
@@ -812,10 +828,10 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 
 - The label lives in the **default slot** — there is no `text`/`content` prop.
   In button mode it moves to `BbBadgeButton`'s slot; don't write both.
-- **`BbBadgeButton` must be a direct child** of the badge's default slot.
-  Wrapping it in another element or component is undefined behavior — the badge
-  won't hand over its body, and you'll get a duplicated label. Outside a badge
-  entirely, it throws.
+- **`BbBadgeButton` must be a direct child** of the badge's default slot:
+  inside a wrapper element or your own component, the badge keeps its body —
+  a duplicated label and a button inside a button. Wrap the whole `BbBadge`
+  instead. Outside a badge entirely, it throws.
 - One `BbBadgeButton` per badge. There is only one body to take over.
 - A badge **without** the companion stays inert: no events, no `href`. Only
   `clearable` adds behavior (the clear button + `click:clear`).
@@ -863,7 +879,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `loading` | `boolean \| undefined` | `false` |  | Shows a spinner in place of the leftmost icon (`icon` or `prepend:icon`; the `append:icon` when it is the only one; else the leading slot), as `BbButton` does, with a hidden loading announcement. |
 | `prepend:icon` | `string \| undefined` |  |  | Icon rendered before the label. |
 | `size` | `'xs'` \| `'sm'` \| `'md'` \| `'lg'` \| `'xl'` \| `'2xl'` | `"md"` |  | Preset size of the badge. |
-| `variant` | `'outline'` \| `'primary'` \| `'destructive'` \| `'secondary'` \| `'none'` | `"primary"` |  | Visual variant: `primary`, `secondary`, `destructive`, or `outline`. Register more via the vite plugin `badgeVariants` option and style `.bb-badge--<variant>` (set `--bg` / `--fg`). `'none'` renders no variant class — an escape hatch for a one-off look set through `--bg` / `--fg` on the element. |
+| `variant` | `'outline'` \| `'primary'` \| `'destructive'` \| `'secondary'` \| `'none'` | `"primary"` |  | Visual variant: `primary`, `secondary`, `destructive`, or `outline`. Status colours are a registration (vite plugin `badgeVariants`, the `soft-*` palette in design-language.md) styled as `.bb-badge--<variant>`. `'none'` renders no variant class: set `--bg` / `--fg` on the element. |
 
 ## Passthrough parts and states
 

package/dist/ai/BbBaseButton.md

@@ -73,21 +73,21 @@ primitive brings no look of its own):
 	<div class="flex flex-wrap items-center gap-2 text-sm">
 		<!-- No href/to → a native <button>. -->
 		<BbBaseButton
-			class="rounded-(--bb-radius) bg-(--bb-primary) px-3 py-1.5 text-(--bb-primary-fg)"
+			class="rounded-(--bb-radius) bg-(--bb-primary) px-3 py-1.5 text-(--bb-primary-fg) focus-visible:ring-2 focus-visible:ring-(--bb-ring)"
 			@click="pinged = true"
 		>
 			Native button
 		</BbBaseButton>
 		<!-- Same-origin href → an <a>. -->
 		<BbBaseButton
-			class="rounded-(--bb-radius) px-3 py-1.5 text-(--bb-primary) underline"
+			class="rounded-(--bb-radius) px-3 py-1.5 text-(--bb-primary) underline focus-visible:ring-2 focus-visible:ring-(--bb-ring)"
 			href="#docs"
 		>
 			Anchor link
 		</BbBaseButton>
 		<!-- href + target → a plain <a target="_blank"> with rel secured. -->
 		<BbBaseButton
-			class="rounded-(--bb-radius) px-3 py-1.5 underline"
+			class="rounded-(--bb-radius) px-3 py-1.5 underline focus-visible:ring-2 focus-visible:ring-(--bb-ring)"
 			href="https://example.com"
 			target="_blank"
 		>
@@ -111,7 +111,25 @@ const pinged = ref(false);
 
 The only classes it applies are structural: `bb-base-button` (a focus-ring
 scaffold, `cursor` and transitions), `bb-base-button--block` and
-`bb-base-button--disabled`. There is **no padding, background, border, or
+`bb-base-button--disabled`.
+
+**It removes the browser's focus ring, on purpose.** It is the base every
+library button, tab, row and menu item draws on, and each of those paints its
+own focus; a native outline would sit on top of all of them. So a bare
+`BbBaseButton` shows **no keyboard focus until you style it**. Every class you
+give it needs a `:focus-visible` style too; the library's own ring is one
+utility pair:
+
+```vue
+<BbBaseButton
+	class="rounded-(--bb-radius) px-3 py-1.5 focus-visible:ring-2 focus-visible:ring-(--bb-ring)"
+>
+	Save
+</BbBaseButton>
+```
+
+The ring animates in through the base's `box-shadow` transition (that is the
+scaffold). There is **no padding, background, border, or
 variant appearance** — that is the whole point. It sets **no text color**, so a
 `text-*` utility on the element just works with no specificity fight; the text
 inherits from its container (in anchor mode, the browser's blue-and-underlined
@@ -123,12 +141,12 @@ the right base for a clickable card or a bespoke nav item:
 
 ```vue
 <div class="flex items-center gap-2 text-sm">
-	<!-- Untouched: just text with the reset + focus scaffold. -->
+	<!-- Untouched: just text with the reset. No visible focus: style it. -->
 	<BbBaseButton href="#a">Bare</BbBaseButton>
 	<!-- Styled entirely by utility classes — neutral hover chrome. -->
 	<BbBaseButton
 		href="#b"
-		class="rounded-(--bb-radius) border border-(--bb-border) px-3 py-1 font-medium hover:bg-(--bb-hover)"
+		class="rounded-(--bb-radius) border border-(--bb-border) px-3 py-1 font-medium hover:bg-(--bb-hover) focus-visible:ring-2 focus-visible:ring-(--bb-ring)"
 	>
 		Branded pill
 	</BbBaseButton>
@@ -247,15 +265,17 @@ destination onto these props instead of an `@click` handler:
 - **`replace`** — history replacement (`router.replace` under Vue Router, a
   replace visit under Inertia).
 - **Inertia visit options** ride along with `href`: request shape (`method`,
-  `data`, `headers`, `only`, `query-string-array-format`), history & scroll
-  (`preserve-scroll`, `preserve-state`), and lifecycle hooks (`on-before`,
-  `on-start`, `on-progress`, `on-success`, `on-cancel`, `on-finish`,
-  `on-cancel-token`) — bound as props, not `@` listeners.
-
-For the full navigation catalog with per-option detail, see the
-[`BbButton`](./BbButton.md) guide — the surface is identical because it is this
-component's. `to` and Inertia links can't run without their framework, so they
-live in static snippets here:
+  `data`, `headers`, `only`, `except`, `component`,
+  `query-string-array-format`), history & scroll (`preserve-scroll`,
+  `preserve-state`, `preserve-url`, `view-transition`), prefetching
+  (`prefetch`, `cache-for`, `cache-tags`), and lifecycle hooks (`on-before`,
+  `on-start`, `on-progress`, `on-success`, `on-error` (validation errors only),
+  `on-cancel`, `on-finish`, `on-cancel-token`, plus `on-prefetching` /
+  `on-prefetched`) — bound as props, not `@` listeners.
+
+For per-option detail, see the [`BbButton`](./BbButton.md) guide — the surface
+is identical because it is this component's. `to` and Inertia links can't run
+without their framework, so they live in static snippets here:
 
 ```vue
 <!-- Vue Router / Nuxt -->
@@ -403,7 +423,10 @@ When it renders as a native button you can retune the element:
   Because it defaults to `button`, a `BbBaseButton` in a form never submits by
   accident; set `type="submit"` for the one that should.
 - **`block`** — full-width layout (`bb-base-button--block`), for stacked nav
-  items, mobile CTAs, or list rows.
+  items, mobile CTAs, or list rows. A block button centres its label (a plain
+  one stays start-aligned, so a wrapped label reads as text), and an anchor
+  (`href` / `to`) becomes `display: block` so the width applies; your own
+  display classes still win.
 
 **Submit type and block width**
 
@@ -423,7 +446,7 @@ When it renders as a native button you can retune the element:
 		</p>
 		<BbBaseButton
 			block
-			class="rounded-(--bb-radius) bg-(--bb-primary) px-3 py-1.5 text-sm text-(--bb-primary-fg)"
+			class="rounded-(--bb-radius) bg-(--bb-primary) px-3 py-1.5 text-sm text-(--bb-primary-fg) focus-visible:ring-2 focus-visible:ring-(--bb-ring)"
 			type="submit"
 		>
 			Create workspace
@@ -492,9 +515,10 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
   link can't resolve. Use `href` for router-free contexts.
 - `tag="div"`/`tag="span"` throws away native button semantics — only do it when a
   `<button>` is genuinely invalid, and restore keyboard/focus behavior yourself.
-- Style the focus state: the base provides only a ring _scaffold_
-  (`box-shadow`/`outline` transitions). Add a visible `:focus-visible` style in
-  your class so keyboard users can see focus.
+- Style the focus state: the base removes the browser's ring and provides only
+  a _scaffold_ (`box-shadow`/`outline` transitions), so a class without a
+  `:focus-visible` style ships an invisible keyboard focus. See "It removes the
+  browser's focus ring" above.
 
 ### Accessibility
 
@@ -518,7 +542,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `activeClass` | `string \| undefined` | `'router-link-active'` |  | CSS class applied when the component renders as a link and the target of the link is the current route or the url matches partially. Ported for Inertia compatibility. |
 | `ariaCurrentValue` | `"page" \| "step" \| "location" \| "date" \| "time" \| "true" \| "false" \| undefined` | `'page'` |  | Value forwarded to the `aria-current` attribute when the component renders as a router link and the target route is an exact match. Use to communicate the current location to assistive technologies. |
 | `async` | `boolean \| undefined` | `false` |  | Inertia: runs the visit without blocking — the page stays interactive and several async visits can be in flight at once. |
-| `block` | `boolean \| undefined` | `false` |  | Makes the component take the full available width (block-level layout). Adds the `bb-base-button--block` modifier class. |
+| `block` | `boolean \| undefined` | `false` |  | Makes the component take the full available width (block-level layout) and centres its label; an anchor becomes `display: block` so the width applies. Adds the `bb-base-button--block` modifier class. |
 | `cacheFor` | `string \| number \| (string \| number)[] \| undefined` |  |  | Inertia: how long a prefetched response stays fresh before it is re-fetched. A single duration, or `[staleAfter, expiresAfter]`. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be installed. |
 | `cacheTags` | `string \| string[] \| undefined` |  |  | Inertia: tags to file this visit's prefetch cache under, so a later request can invalidate the whole tagged group. |
 | `component` | `string \| undefined` |  |  | Inertia: the page component this visit resolves to. Rarely set by hand — the server normally decides it. |

package/dist/ai/BbBaseCheckboxIcon.md

@@ -286,14 +286,14 @@ Set these on the element, or on a class you put on it, to retune this component
 
 | Property | Default | What it is |
 | --- | --- | --- |
-| `--accent` | `var(--bb-primary)` |  |
-| `--check-color` | `var(--bb-primary-fg)` |  |
-| `--size` | `16px` |  |
+| `--accent` | `var(--bb-primary)` | Fill and border colour when checked or indeterminate. |
+| `--check-color` | `var(--bb-primary-fg)` | Colour of the checkmark / dash drawn on the accent fill. |
+| `--size` | `16px` | Width and height of the glyph box. |
 | `--r` | `min(4px, var(--bb-radius))` | The checkbox corner, capped by the master radius so a zero- or small-radius theme reaches it. Not `--bb-radius-sm`: that tier is 4.8px at the shipped radius and this glyph ships at 4px. |
 | `--ring-color` | `var(--bb-ring)` | The focus ring's colour, re-pointed by errors and warnings. Both ring declarations read it, so a focused glyph grows its ring in its own colour instead of tweening from a different one. |
 | `--elev` | `var(--bb-elev-sm)` | Resting lift; a no-op until a theme pins `--bb-elev`. |
 | `--bg` | `var(--bb-panel)` | The glyph plate. DECLARED here, not consumed bare, because this glyph renders inside surfaces that declare `--bg` themselves — a table row or header cell, a dialog, an off-canvas sheet. Without the declaration it would inherit that surface's fill, which happens to match at the shipped default and would diverge the moment anyone writes `.my-table { --bg: … }`. Identical to the raw tokens it replaces at every theme. |
-| `--border-color` | `var(--bb-border)` |  |
+| `--border-color` | `var(--bb-border)` | Resting border colour of the glyph; re-pointed by error and warning states. |
 
 ## See Also
 

package/dist/ai/BbBreadcrumbs.md

@@ -235,7 +235,7 @@ a status mark, a dynamic icon, or a fixed trail hint — use slots:
 - `item:prepend` / `item:append` — before/after every crumb's label, inside the
   link, replacing that side's `prepend:icon` / `append:icon` (as a form
   control's `prepend` slot replaces its icon); scope is
-  `{ item, index, text, disabled }`. Keep the content non-interactive — it is
+  `{ item, index, label, disabled }`. Keep the content non-interactive — it is
   inside a link — and mark decorative content `aria-hidden="true"`, or it
   becomes part of the link's accessible name.
 - `prepend` / `append` — fixed content on either end of the whole trail; scope

package/dist/ai/BbButton.md

@@ -119,6 +119,41 @@ restate a state:
 }
 ```
 
+**A colour of its own: write all five, picked for that colour.** There is no
+one-colour shorthand on purpose: a yellow and a navy need opposite choices,
+and no colour math serves both. Copy the shape and choose each value:
+
+```css
+/* A light colour (yellow): dark text, and each state goes darker. */
+.bb-button--upgrade {
+	--bg: #facc15;
+	--bg-hover: #eab308;
+	--bg-pressed: #ca8a04;
+	--fg: #422006;
+	--ring-color: #a16207;
+}
+
+/* A dark colour (navy): light text, and each state goes lighter. */
+.bb-button--brand {
+	--bg: #1e3a8a;
+	--bg-hover: #1e40af;
+	--bg-pressed: #1d4ed8;
+	--fg: #ffffff;
+	--ring-color: #60a5fa;
+}
+```
+
+- **`--fg`** is the text: dark on a light `--bg`, light on a dark one. Check
+  it reads at 4.5:1 against `--bg` and both state fills.
+- **`--bg-hover` / `--bg-pressed`** move away from the rest colour, pressed
+  the furthest, so each state is visibly different: darker steps on a light
+  colour, lighter steps on a dark one.
+- **`--ring-color`** must show against the page around the button, not just
+  against the button.
+
+Which colours earn a variant at all, and what they should mean, is in
+[design-language § Using color](./guides/design-language.md#using-color).
+
 The primary's hover is one 1.25:1 luminance step away from the panel
 (darker in light, lighter in dark), turning toward the panel only when the
 primary has no room left, as the default black in light and white in dark
@@ -371,47 +406,18 @@ detected by the model being defined, **seed the model** (`ref(false)`, not an
 undefined `state.*`) — an undefined model is not a toggle yet and the first
 click won't set it.
 
-For an exclusive set, share one `v-model` across the buttons and give each its
-own `true-value`. The `false-value` decides the selection policy:
-
-- `:false-value="null"` — optional: clicking the active button clears the
-  selection.
-- `false-value` **mirroring that same button's own `true-value`** — mandatory:
-  re-clicking the active button re-emits the same value, so one choice is
-  always selected.
-
-**Point every button's `false-value` at its own `true-value`, never at a
-sibling's.** Each button independently answers "what do I emit when I'm
-clicked while I'm not the active one?" — under the mandatory policy the
-answer is always "myself," never "whichever value the other button owns." Get
-this backwards and the control inverts silently: the button that is
-_currently pressed_ is the one whose click now emits the _other_ button's
-value, so clicking the visibly-active segment switches away from it instead
-of re-confirming it. Nothing catches this — both strings are legal
-`false-value`s, so it passes `vue-tsc`, lint, and `bitboss-ui check`, and it
-only shows up when someone clicks the segment that's already selected. A
-two-button segmented toggle, written out explicitly rather than looped, is
-the shape that trips this up most:
-
-```vue
-<!-- Mandatory exclusive set — each button's false-value mirrors ITS OWN
-     true-value. Board's false-value is "board", not "table"; Table's is
-     "table", not "board". Swapping them makes the pressed segment toggle
-     away to its sibling instead of staying selected. -->
-<BbButton v-model="view" group true-value="board" false-value="board">
-	Board
-</BbButton>
-<BbButton v-model="view" group true-value="table" false-value="table">
-	Table
-</BbButton>
-```
+**Exactly one active, always?** That is a radio group, not a set of toggles:
+reach for **`BbRadioGroup`** — a [segmented control](./BbRadioGroup.md#segmented-control)
+or selection tiles, with arrow keys and "2 of 4" for free — or **`BbTabs`**
+(`pill`, the default variant) when the choice switches a view. Neither needs
+a `false-value`.
 
-A `v-for` over an options array gets this correct for free —
-`:true-value="option.value"` and `:false-value="option.value"` both read the
-_same_ loop item, so every rendered button automatically mirrors itself (the
-live example below uses this shape). The mistake above only becomes possible
-once that loop is unrolled into separate elements with their own literal
-strings.
+Toggles that share one `v-model` fit an **optional** choice: give each button
+its own `true-value` and `:false-value="null"`, so clicking the active one
+clears the selection. If you do hand-roll a mandatory set, each button's
+`false-value` must mirror **its own** `true-value` (`true-value="board"
+false-value="board"`), never a sibling's — swapped, the pressed segment
+switches away when clicked, and nothing catches it.
 
 Add `group` to fuse adjacent buttons into one visual segment control (shared
 borders and radius between siblings). Each button keeps its own semantics: a
@@ -423,7 +429,7 @@ the first / last, and Space / Enter toggle. Disabled and loading buttons are
 skipped. Any other element between two buttons splits them into two sets, and
 `group` buttons without a `v-model` keep one Tab stop each.
 
-**Exclusive toggle groups**
+**An optional filter (false-value null) and a mirrored view set**
 
 ```vue
 <template>
@@ -635,8 +641,13 @@ Escape hatches, when the default isn't right:
   a parent-owned request). While loading, the button exposes
   `aria-disabled="true"` and leaves the tab order; it is not natively
   `disabled`.
-- `disable-auto-loading` — opts out of promise tracking entirely (e.g. the
-  handler opens a dialog and you don't want a spinner flash).
+- `disable-auto-loading` — opts out of every spinner the button starts on its
+  own: promise tracking (e.g. the handler opens a dialog and you don't want a
+  spinner flash) and a `type="submit"` button's spin while its `BbForm` saves.
+  Only an explicit `loading` shows the spinner then. A click that awaits a
+  dialog (`await useBbDialogContext(id).show()`, `await confirm()`) spins
+  until the dialog settles, like any async click: that is where this prop
+  goes.
 - `interactive-while-loading` — keeps the button clickable while it shows the
   loading state, for controls that must stay interactive (this is how the
   `BbDropdownButton` caret stays usable while the primary action runs). The
@@ -930,7 +941,7 @@ utility wins. What works in every build:
 - `BbDropdownButton` — escalate to it when a primary action grows close
   alternates; it shares this component's `variant`/`size`/loading language.
 - `useConfirm` — gate every `destructive` button behind a confirm: mount the
-  `<BbConfirm />` host once (app root), `await confirm(...)` in the handler and
+  `<BbHost />` once (app root), `await confirm(...)` in the handler and
   act only on a yes. The dialog's own buttons are `BbButton` configs (see the
   composable doc), so the confirm speaks the same `variant`/icon language:
 
@@ -972,15 +983,15 @@ utility wins. What works in every build:
 
 		<!--
 			Standalone example: it mounts its own host because it has no app root.
-			A real app mounts exactly one <BbConfirm /> at the app root, and pages
+			A real app mounts exactly one <BbHost /> at the app root, and pages
 			mount none. See ai/guides/agent-contract.md § Global Host Rule.
 		-->
-		<BbConfirm />
+		<BbHost />
 	</div>
 </template>
 <script setup lang="ts">
 import { ref } from 'vue';
-import { BbButton, BbConfirm, useConfirm } from 'bitboss-ui';
+import { BbButton, BbHost, useConfirm } from 'bitboss-ui';
 
 type ApiKey = { id: string; label: string; masked: string; created: string };
 
@@ -1122,7 +1133,7 @@ Anti-patterns:
 | `cacheTags` | `string \| string[] \| undefined` |  |  | Inertia: tags to file this visit's prefetch cache under, so a later request can invalidate the whole tagged group. |
 | `component` | `string \| undefined` |  |  | Inertia: the page component this visit resolves to. Rarely set by hand — the server normally decides it. |
 | `data` | `object \| undefined` |  |  | Request payload forwarded to Inertia when navigating via `href` in an Inertia-enabled app. Ignored when not using Inertia. |
-| `disableAutoLoading` | `boolean \| undefined` | `false` |  | Disables the automatic loading state that tracks async click handlers (enabled by default). |
+| `disableAutoLoading` | `boolean \| undefined` | `false` |  | Disables every spinner the button starts on its own: the one that tracks an async click handler, and a `type="submit"` button's spin while its `BbForm` saves. Only an explicit `loading` shows the spinner then. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component: native `disabled` (or `aria-disabled` on a link), muted paint. Beside `loading`, loading wins the look (spinner and variant colours) and this only adds the native blocking — redundant but harmless. |
 | `download` | `string \| boolean \| undefined` |  |  | Marks an `href` link as a download: renders a plain `<a download>` doing a native navigation (never an Inertia/router visit), so file downloads work. Pass a string for the suggested filename. A native-anchor signal alongside `target` and `external`. |
 | `exactActiveClass` | `string \| undefined` |  |  | Class to apply when the link is exact active. |
@@ -1283,4 +1294,4 @@ Set these on the element, or on a class you put on it, to retune this component
 - [BbBaseButton](./BbBaseButton.md) — Unstyled button/link primitive: element resolution (button/anchor/router link) and the full navigation engine, with no visual chrome. Use for any clickable or navigable surface that is not a variant-first BbButton — cards, list rows, custom links.
 - [BbDropdownButton](./BbDropdownButton.md) — A button with primary action and all other actions collected in a dropdown.
 - [BbDropdown](./BbDropdown.md) — Displays contextual action menus and menu content (includes the co-located BbDropdownGroup export, which is how a selectable group is bound).
-- [BbConfirm](./BbConfirm.md) — Prompts users to confirm or cancel critical actions (includes co-located BbConfirmPortal export).
+- [useConfirm](./composables/useConfirm.md)