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

package/dist/ai/composables/useConfirm.md

@@ -69,7 +69,8 @@ declare function close(): void;
 Hides the newest open dialog opened through the same `useConfirm()` (never
 another component's) without resolving anything. Its purpose is multi-step
 flows: with `autoClose: false` the dialog stays open after the promise resolves,
-and you call `close()` when your flow is done. Don't use it as a substitute for
+and you call `close()` when your flow is done. Server work is not such a flow:
+it goes in `yes.onClick` (see **Async work before the dialog closes**). Don't use it as a substitute for
 the buttons — a `confirm()` closed this way before any button ran leaves its
 promise pending.
 
@@ -166,6 +167,43 @@ const post = await confirm({
 // post is the api result, or false when the user declined
 ```
 
+An Inertia visit goes in `onClick` too. It returns no promise, so wrap it (the
+same wrapper as BbDialog's `save()`): Yes spins for the whole visit, and the
+dialog closes when it settles. A failed visit rejects `confirm()` and still
+closes the dialog.
+
+```ts
+import { router } from '@inertiajs/vue3';
+import { useConfirm } from 'bitboss-ui';
+
+const { confirm } = useConfirm();
+
+const destroy = (url: string) =>
+	new Promise<void>((resolve, reject) => {
+		router.delete(url, {
+			onSuccess: () => resolve(),
+			onError: (errors) => reject({ errors }),
+			// Cut short by another visit: resolve. Ended unsettled (a 500, a
+			// network error): reject. Both are no-ops after onSuccess / onError.
+			onFinish: (visit) =>
+				visit.cancelled || visit.interrupted
+					? resolve()
+					: reject(new Error('The delete failed')),
+		});
+	});
+
+const remove = (id: number) =>
+	confirm({
+		title: 'Delete invoice?',
+		variant: 'destructive',
+		yes: { text: 'Delete', onClick: () => destroy(`/invoices/${id}`) },
+	});
+```
+
+Not `autoClose: false` with `close()` called from the visit callbacks: Yes
+never shows busy, and a missed callback leaves the dialog up or closes it
+mid-visit.
+
 ### Custom footer actions — more than yes/no
 
 Pass an `actions` array to replace the Yes/No footer with your own buttons.

package/dist/ai/design-tokens.json

@@ -456,18 +456,18 @@
 				"dark": "#00000080"
 			}
 		},
-		"--bb-overlay-blur": {
-			"css": "--bb-overlay-blur",
-			"light": "2px"
-		},
-		"--bb-overlay-stacked": {
-			"css": "--bb-overlay-stacked",
+		"--bb-overlay-above": {
+			"css": "--bb-overlay-above",
 			"derived": "var(--bb-overlay)",
 			"resolved": {
 				"light": "#0000001a",
 				"dark": "#00000080"
 			}
 		},
+		"--bb-overlay-blur": {
+			"css": "--bb-overlay-blur",
+			"light": "2px"
+		},
 		"--bb-panel": {
 			"css": "--bb-panel",
 			"light": "rgb(255 255 255)",

package/dist/ai/guides/agent-contract.md

@@ -240,8 +240,8 @@ semantic status badges, a brand button tone — **add it, in both halves**:
 
 1. **Register the name** in the build plugin: `badgeVariants`, `buttonVariants`,
    `alertVariants`, `confirmVariants`, `dropdownItemVariants`, `tooltipVariants`,
-   `toastVariants`, `indicatorVariants`, `inputVariants`, `tabsVariants`
-   (`bitboss-ui/vite` or `bitboss-ui/nuxt`).
+   `toastVariants`, `indicatorVariants`, `inputVariants`, `tabsVariants`,
+   `radioVariants`, `checkboxVariants` (`bitboss-ui/vite` or `bitboss-ui/nuxt`).
    The plugin regenerates the typed registry, so the name type-checks.
 2. **Style the class** — `.bb-badge--<name>`, `.bb-button--<name>`, … —
    in a project stylesheet loaded **after** `bitboss-ui/styles.css`. The library

package/dist/ai/guides/ai-router.md

@@ -98,29 +98,30 @@ inline-edit playbook) instead of inventing a new shape.
 
 ## Playbooks (only when the pattern applies)
 
-| Need                                                                                                                 | Guide                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| ⌘K / Ctrl+K global command palette                                                                                   | [BbSelectPopover](../BbSelectPopover.md#a-k-command-palette) § A ⌘K command palette                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| Tied selects / stale model cleanup                                                                                   | [coherence-playbook](./coherence-playbook.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| Async `items` providers / prefill                                                                                    | [fetch-items-playbook](./fetch-items-playbook.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `item-text` / `item-value` / the default `label` / `value` keys / disabled                                           | [options-items-playbook](./options-items-playbook.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| Table cell edit ownership                                                                                            | [inline-edit-playbook](./inline-edit-playbook.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| Table row → detail (identity cells)                                                                                  | [agent-contract](./agent-contract.md) § Inline Links                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| Peek that drills into related records                                                                                | [agent-contract](./agent-contract.md) § Consult-Stack                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| Icons (`lucide:*`, never invent names)                                                                               | [icons-policy](./icons-policy.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| Tokens / styling around components                                                                                   | [design-language](./design-language.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| Inertia app-side helpers (`useProp`, `useQuery`, `useQueryObject`, `useTableContext`, …) the Inertia recipes import  | [inertia-helpers](./inertia-helpers.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| Theming a whole app / retuning a component                                                                           | [design-tokens](./design-tokens.md) — the two tiers, and why most restyling is a component token, not a `--bb-*` one                                                                                                                                                                                                                                                                                                                                                                                              |
-| Paint as data (DESIGN.md, impeccable, design-taste)                                                                  | [design-tokens.json](../design-tokens.json) and [design-tokens.manifest.yaml](../design-tokens.manifest.yaml), generated from `variables.css`. Grep `--bb-*`, not `--color-*` or `--radius-*`. Root `DESIGN.md` is the Inertia fixture, not this library.                                                                                                                                                                                                                                                         |
-| A Tailwind utility on a `Bb*` component does nothing, or half-applies                                                | [installation](./installation-and-plugin-setup.md) § Cascade layers — v4 is layered, we are not by default. It is per PROPERTY: a utility loses only where we declare the same one, and a shorthand like `p-4` can half-apply. `cssLayers: TAILWIND_V4_LAYERS` in the build plugin                                                                                                                                                                                                                                |
-| Restyling ONE part of a component (its icon, its spinner, its field box) — or a `:deep()` you are about to write     | [passthrough](./passthrough.md) — the first choice: `pt:<part>` / `pt:<part>:<state>`, typed and linted; classes append, attributes win, listeners concatenate. A look many places need is a **variant**, not `pt`. No part for it? A CSS override on the internal class is allowed but can break in any release (a part's class is stable within 3.x) — [design-language](./design-language.md) § Hard Rules                                                                                                     |
-| Styling the SELECTED option, the HIGHLIGHTED row, the CURRENT tab — a state a modifier class used to carry           | [passthrough](./passthrough.md) § Parts that resolve per node — `pt:option:selected`, `pt:row:highlighted`, `pt:item:active`; every component's parts and states are in its table                                                                                                                                                                                                                                                                                                                                 |
-| Typing a `pt` value in `<script>` (a const, a preset, a wrapper's `pt` prop, a global map split across files)        | [passthrough](./passthrough.md) § Typing `pt` in `<script>` — `<Component>Props<Row>['pt']` with `satisfies`, `definePt` for map fragments. `PtValue` / `PtMap` are not exported                                                                                                                                                                                                                                                                                                                                  |
-| `InstanceType<typeof BbSelect>` fails, a Storybook `Meta` or `findComponent` won't type, a `ref('')` on a text field | [typescript-generic-components](./typescript-generic-components.md) — the generic components and their four script-side differences                                                                                                                                                                                                                                                                                                                                                                               |
-| Wrapping a `Bb*` component in your own (`MemberSelect`, `PriceListSelect`)                                           | A preset (fixed items, label, option row): [preset-components](./preset-components.md), one `definePreset` call. With its own logic: [options-items-playbook](./options-items-playbook.md) § Wrapping BbSelect in your own component                                                                                                                                                                                                                                                                              |
-| Forms with validation (`BbForm`)                                                                                     | [validated-forms](./validated-forms.md); the schema library (Zod, Valibot, ArkType, Yup, Joi, Effect, string rules) and switching between them: [validation-libraries](./validation-libraries.md); server errors from Inertia, a Laravel 422, Precognition, vee-validate or Nuxt UI into `setErrors`: [validation-providers](./validation-providers.md); porting an Element Plus / Naive UI / Ant Design Vue form (`rules` objects, async-validator): [from-async-validator](./migration/from-async-validator.md) |
-| Upgrading from bitboss-ui 2.x                                                                                        | [migration/v2-to-v3](./migration/v2-to-v3.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| Bumping between two v3 prereleases                                                                                   | `npx bitboss-ui changelog --since <your version>` (MCP `list_changes`) — what BREAKS in the bump, and in which release each break first shipped (`firstReleasedIn`); then `check --manifest` for the files it breaks                                                                                                                                                                                                                                                                                              |
+| Need                                                                                                                    | Guide                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ⌘K / Ctrl+K global command palette                                                                                      | [BbSelectPopover](../BbSelectPopover.md#a-k-command-palette) § A ⌘K command palette                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Tied selects / stale model cleanup                                                                                      | [coherence-playbook](./coherence-playbook.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Async `items` providers / prefill                                                                                       | [fetch-items-playbook](./fetch-items-playbook.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `item-text` / `item-value` / the default `label` / `value` keys / disabled                                              | [options-items-playbook](./options-items-playbook.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Table cell edit ownership                                                                                               | [inline-edit-playbook](./inline-edit-playbook.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Table row → detail (identity cells)                                                                                     | [agent-contract](./agent-contract.md) § Inline Links                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Peek that drills into related records                                                                                   | [agent-contract](./agent-contract.md) § Consult-Stack                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Icons (`lucide:*`, never invent names)                                                                                  | [icons-policy](./icons-policy.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Tokens / styling around components                                                                                      | [design-language](./design-language.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Inertia app-side helpers (`useProp`, `useQuery`, `useQueryObject`, `useTableContext`, …) the Inertia recipes import     | [inertia-helpers](./inertia-helpers.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Theming a whole app / retuning a component                                                                              | [design-tokens](./design-tokens.md) — the two tiers, and why most restyling is a component token, not a `--bb-*` one                                                                                                                                                                                                                                                                                                                                                                                              |
+| Paint as data (DESIGN.md, impeccable, design-taste)                                                                     | [design-tokens.json](../design-tokens.json) and [design-tokens.manifest.yaml](../design-tokens.manifest.yaml), generated from `variables.css`. Grep `--bb-*`, not `--color-*` or `--radius-*`. Root `DESIGN.md` is the Inertia fixture, not this library.                                                                                                                                                                                                                                                         |
+| A Tailwind utility on a `Bb*` component does nothing, or half-applies                                                   | [installation](./installation-and-plugin-setup.md) § Cascade layers — v4 is layered, we are not by default. It is per PROPERTY: a utility loses only where we declare the same one, and a shorthand like `p-4` can half-apply. `cssLayers: TAILWIND_V4_LAYERS` in the build plugin                                                                                                                                                                                                                                |
+| Restyling ONE part of a component (its icon, its spinner, its field box) — or a `:deep()` you are about to write        | [passthrough](./passthrough.md) — the first choice: `pt:<part>` / `pt:<part>:<state>`, typed and linted; classes append, attributes win, listeners concatenate. A look many places need is a **variant**, not `pt`. No part for it? A CSS override on the internal class is allowed but can break in any release (a part's class is stable within 3.x) — [design-language](./design-language.md) § Hard Rules                                                                                                     |
+| Styling the SELECTED option, the HIGHLIGHTED row, the CURRENT tab — a state a modifier class used to carry              | [passthrough](./passthrough.md) § Parts that resolve per node — `pt:option:selected`, `pt:row:highlighted`, `pt:item:active`; every component's parts and states are in its table                                                                                                                                                                                                                                                                                                                                 |
+| Typing a `pt` value in `<script>` (a const, a preset, a wrapper's `pt` prop, a global map split across files)           | [passthrough](./passthrough.md) § Typing `pt` in `<script>` — `<Component>Props<Row>['pt']` with `satisfies`, `definePt` for map fragments. `PtValue` / `PtMap` are not exported                                                                                                                                                                                                                                                                                                                                  |
+| `InstanceType<typeof BbSelect>` fails, a Storybook `Meta` or `findComponent` won't type, a `ref('')` on a text field    | [typescript-generic-components](./typescript-generic-components.md) — the generic components and their four script-side differences                                                                                                                                                                                                                                                                                                                                                                               |
+| Wrapping a `Bb*` component in your own (`MemberSelect`, `PriceListSelect`)                                              | A preset (fixed items, label, option row): [preset-components](./preset-components.md), one `definePreset` call. With its own logic: [options-items-playbook](./options-items-playbook.md) § Wrapping BbSelect in your own component                                                                                                                                                                                                                                                                              |
+| Forms with validation (`BbForm`)                                                                                        | [validated-forms](./validated-forms.md); the schema library (Zod, Valibot, ArkType, Yup, Joi, Effect, string rules) and switching between them: [validation-libraries](./validation-libraries.md); server errors from Inertia, a Laravel 422, Precognition, vee-validate or Nuxt UI into `setErrors`: [validation-providers](./validation-providers.md); porting an Element Plus / Naive UI / Ant Design Vue form (`rules` objects, async-validator): [from-async-validator](./migration/from-async-validator.md) |
+| Finishing a migration (from v2 or another library): the hand-rolled controls to move onto the library, `check --idioms` | [migration/adoption-checklist](./migration/adoption-checklist.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Upgrading from bitboss-ui 2.x                                                                                           | [migration/v2-to-v3](./migration/v2-to-v3.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Bumping between two v3 prereleases                                                                                      | `npx bitboss-ui changelog --since <your version>` (MCP `list_changes`) — what BREAKS in the bump, and in which release each break first shipped (`firstReleasedIn`); then `check --manifest` for the files it breaks                                                                                                                                                                                                                                                                                              |
 
 ---
 

package/dist/ai/guides/app-layout.md

@@ -242,6 +242,11 @@ const footer = [
 	background: color-mix(in oklab, var(--bb-text) 6%, transparent);
 }
 
+/* BbBaseButton drops the native ring: the keyboard focus is drawn here. */
+.layout__nav-item:focus-visible {
+	box-shadow: 0 0 0 var(--bb-ring-size) var(--bb-ring);
+}
+
 .layout__nav-item--active {
 	background: color-mix(in oklab, var(--bb-text) 9%, transparent);
 	font-weight: 500;

package/dist/ai/guides/component-picker.md

@@ -40,6 +40,12 @@ logo — on every `.vue` file it scans. That is the backstop: it fires without
 anyone thinking to ask. The badge case is not decidable from markup (a tinted
 pill is as often decoration as status), so it has no hint and stays your job.
 
+Migrating an app that already built these? The
+[adoption checklist](./migration/adoption-checklist.md) is the same question
+asked of existing code: every hand-rolled pattern the library ships, how to
+find it, and the replacement. `npx bitboss-ui check --idioms` runs its patterns
+over the app (report-only).
+
 ---
 
 ## Text Input
@@ -81,6 +87,7 @@ pill is as often decoration as status), so it has no hint and stays your job.
 - Small static multi-choice submitted with a form → `BbCheckboxGroup`.
 - Each option is a live setting that applies the moment it flips → `BbSwitchGroup`.
 - The trigger is a status pill, avatar stack, or table-cell chip rather than a form field → `BbSelectPopover` (same search/options engine as `BbSelect`, you own the trigger).
+- A segmented control: **switch views → `BbTabs`** (default `pill`), **pick a value → `BbRadioGroup` `variant="pill"`** (or `"line"`; several values → `BbCheckboxGroup` `variant="pill"`): BbTabs' look on a radiogroup ([§ Segmented control](../BbRadioGroup.md#segmented-control)). Decide by the job, not the look: a value a form or a filter submits is a radio group; what the page shows is a tab.
 
 Never hand-assemble a row of `BbCheckbox`/`BbRadio` — the groups give you fieldset semantics, item mapping, and validation for free.
 
@@ -192,7 +199,7 @@ There are also **`v-bb-color`**, **`v-bb-date`**, and **`v-bb-time`** directives
 
 **Offload navigation to the component.** `BbButton`, dropdown items, and breadcrumb items accept `href` (anchor, or Inertia visit with `method`/`data`/`preserveScroll`/…) and `to` (vue-router); tabs items accept `href`; `BbPagination` with `navigation` builds per-page links itself. Never wire `@click="router.push(...)"` for a plain destination.
 
-**Picking the pattern:** `BbTabs` switches peer sections of _one_ subject (Overview / Activity / Settings) — not steps in a flow, not hierarchy. A look the shipped variants don't have (a side nav, a filter row) starts from `variant="none"` plus the strip's tokens in `pt.wrapper.style` (inline, so no stylesheet and no scoped-style trap); the library does not add a variant per need. `BbBreadcrumbs` answers "where am I and how do I get back up". `BbPagination` steps through a paged result set — prefer it over infinite scroll when users need to find their place again.
+**Picking the pattern:** `BbTabs` switches peer sections of _one_ subject (Overview / Activity / Settings) — not steps in a flow, not hierarchy, and not a value: a segmented strip that picks a value a form or a filter submits is a `BbRadioGroup` `variant="pill"` / `"line"`, the same look ([§ Segmented control](../BbRadioGroup.md#segmented-control)). A look the shipped variants don't have (a side nav, a filter row) starts from `variant="none"` plus the strip's tokens in `pt.wrapper.style` (inline, so no stylesheet and no scoped-style trap); the library does not add a variant per need. `BbBreadcrumbs` answers "where am I and how do I get back up". `BbPagination` steps through a paged result set — prefer it over infinite scroll when users need to find their place again.
 
 **Disclosure ladder (BbAccordion vs BbCollapsible vs BbSmoothHeight):**
 
@@ -247,7 +254,7 @@ compose it or write it yourself.
 | `BbModal`                                                                                        | It is [BbDialog](../BbDialog.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `BbDrawer` / `BbSheet`                                                                           | It is [BbOffCanvas](../BbOffCanvas.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `BbCombobox` / `BbAutocomplete`                                                                  | It is [BbSelect](../BbSelect.md) / [BbSelectPopover](../BbSelectPopover.md) — search is built in, see `disable-writing`.                                                                                                                                                                                                                                                                                                                                                               |
-| `BbToggle` / `BbToggleGroup`                                                                     | It is [BbButton](../BbButton.md) with `v-model` (+ `true-value` / `false-value`), which owns `aria-pressed` and the active class. A group is several buttons: a boolean per button for independent toggles, one shared `v-model` with `:false-value="null"` for an optional choice, `group` to fuse them ([BbButton § Toggle buttons](../BbButton.md#toggle-buttons)); exactly one always active is a `BbRadioGroup` segmented control or `BbTabs`.                                    |
+| `BbToggle` / `BbToggleGroup`                                                                     | It is [BbButton](../BbButton.md) with `v-model` (+ `true-value` / `false-value`), which owns `aria-pressed` and the active class. A group is several buttons: a boolean per button for independent toggles, one shared `v-model` with `:false-value="null"` for an optional choice, `group` to fuse them ([BbButton § Toggle buttons](../BbButton.md#toggle-buttons)); exactly one always active is a `BbRadioGroup` `variant="pill"` or `BbTabs`.                                     |
 | `TagChip` / colored, read-only tag chip                                                          | It is [BbBadge](../BbBadge.md) — [BbTag](../BbTag.md) is a tags-_input_ only, not a display component. Use `BbBadge` with a registered `soft-*` variant for a fixed palette, or a one-off `--bg`/`--fg` override per row for arbitrary/data-driven colors (BbBadge.md § One-off colors) — not a registered variant per distinct color.                                                                                                                                                 |
 | `BbTab` (singular)                                                                               | The consumer API is [BbTabs](../BbTabs.md) / `BbTabsRoot`. `BbTab` appears only as the **v2 "before" side** of the migration diffs.                                                                                                                                                                                                                                                                                                                                                    |
 | `BbCard`                                                                                         | Does not exist — a card is a `<div>` with tokens. See [design-language](./design-language.md).                                                                                                                                                                                                                                                                                                                                                                                         |

package/dist/ai/guides/design-language.md

@@ -132,28 +132,28 @@ one renders with no value at all rather than erroring.
 
 ### Surfaces & structure
 
-| Token                  | Meaning                                                                                                                                       |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--bb-panel`           | Surface/background color of panels, popovers, dialogs                                                                                         |
-| `--bb-muted`           | Subtle/disabled surface (derived, neutral)                                                                                                    |
-| `--bb-hover`           | Hover fill for **affordances** (buttons, links, controls)                                                                                     |
-| `--bb-surface-hover`   | Hover fill for **passive surfaces** (rows, cells, days) — fainter                                                                             |
-| `--bb-pressed`         | Neutral pressed/active fill                                                                                                                   |
-| `--bb-border`          | Border color; pair with `--bb-border-w` (1px)                                                                                                 |
-| `--bb-field-border`    | Resting border of every form field (the default input box and the group / rating / slider shells); follows `--bb-border` until set            |
-| `--bb-border-w`        | Hairline thickness — plates **and** internal dividers (dialog/off-canvas footers, menu rules, popover headers)                                |
-| `--bb-border-w-sm`     | Nested / small hairline (xs/sm buttons, badges, glyphs) — half of `--bb-border-w`, floored at 1px and capped by it                            |
-| `--bb-radius`          | Corner radius of controls (8px)                                                                                                               |
-| `--bb-radius-surface`  | Corner radius of large surfaces (derived, ×1.8)                                                                                               |
-| `--bb-radius-sm`       | Corner radius of small nested elements (derived)                                                                                              |
-| `--bb-shadow`          | Overlay elevation (dialogs, popovers, menus, toasts)                                                                                          |
-| `--bb-elev`            | Resting lift on controls — a full `box-shadow`, default a transparent layer. Covers a soft lift and a hard offset alike                       |
-| `--bb-elev-sm`         | The same lift on small chrome (badges, glyphs, xs/sm buttons); inherits `--bb-elev` unless a hard-offset theme splits it                      |
-| `--bb-panel-p`         | Content padding of large surfaces (dialog, off-canvas); axis split via the locals `--px`/`--py` on `.bb-dialog` / `.bb-offcanvas`             |
-| `--bb-overlay-blur`    | Backdrop dim blur (2px) — on the bottom-most open panel's backdrop only                                                                       |
-| `--bb-overlay-stacked` | Dim painted by a panel stacked over another open one (derived, equal to `--bb-overlay`; `transparent` = one dim under the pile)               |
-| `--bb-surface-filter`  | Frost on raised plates — dialog, off-canvas, popover bubble, toast, input shell, alert, table. A full `backdrop-filter` value, default `none` |
-| `--bb-z-overlay`       | Z-index for overlays (10)                                                                                                                     |
+| Token                 | Meaning                                                                                                                                                                                 |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--bb-panel`          | Surface/background color of panels, popovers, dialogs                                                                                                                                   |
+| `--bb-muted`          | Subtle/disabled surface (derived, neutral)                                                                                                                                              |
+| `--bb-hover`          | Hover fill for **affordances** (buttons, links, controls)                                                                                                                               |
+| `--bb-surface-hover`  | Hover fill for **passive surfaces** (rows, cells, days) — fainter                                                                                                                       |
+| `--bb-pressed`        | Neutral pressed/active fill                                                                                                                                                             |
+| `--bb-border`         | Border color; pair with `--bb-border-w` (1px)                                                                                                                                           |
+| `--bb-field-border`   | Resting border of every form field (the default input box and the group / rating / slider shells); follows `--bb-border` until set                                                      |
+| `--bb-border-w`       | Hairline thickness — plates **and** internal dividers (dialog/off-canvas footers, menu rules, popover headers)                                                                          |
+| `--bb-border-w-sm`    | Nested / small hairline (xs/sm buttons, badges, glyphs) — half of `--bb-border-w`, floored at 1px and capped by it                                                                      |
+| `--bb-radius`         | Corner radius of controls (8px)                                                                                                                                                         |
+| `--bb-radius-surface` | Corner radius of large surfaces (derived, ×1.8)                                                                                                                                         |
+| `--bb-radius-sm`      | Corner radius of small nested elements (derived)                                                                                                                                        |
+| `--bb-shadow`         | Overlay elevation (dialogs, popovers, menus, toasts)                                                                                                                                    |
+| `--bb-elev`           | Resting lift on controls — a full `box-shadow`, default a transparent layer. Covers a soft lift and a hard offset alike                                                                 |
+| `--bb-elev-sm`        | The same lift on small chrome (badges, glyphs, xs/sm buttons); inherits `--bb-elev` unless a hard-offset theme splits it                                                                |
+| `--bb-panel-p`        | Content padding of large surfaces (dialog, off-canvas); axis split via the locals `--px`/`--py` on `.bb-dialog` / `.bb-offcanvas`                                                       |
+| `--bb-overlay-blur`   | Backdrop dim blur (2px) — on the bottom-most open panel's backdrop only                                                                                                                 |
+| `--bb-overlay-above`  | Dim painted by a panel stacked over another open one (derived, equal to `--bb-overlay`; `transparent` = one dim under the pile); none on a dialog replacing a member of its own `stack` |
+| `--bb-surface-filter` | Frost on raised plates — dialog, off-canvas, popover bubble, toast, input shell, alert, table. A full `backdrop-filter` value, default `none`                                           |
+| `--bb-z-overlay`      | Z-index for overlays (10)                                                                                                                                                               |
 
 ### Color semantics
 
@@ -240,8 +240,8 @@ What the shared names mean (shadcn-style vocabulary):
 
 Projects can register extra variants through the Vite/Nuxt plugin
 (`buttonVariants`, `badgeVariants`, `alertVariants`, `confirmVariants`,
-`dropdownItemVariants`, `tooltipVariants`, `toastVariants`, `inputVariants`
-options).
+`dropdownItemVariants`, `tooltipVariants`, `toastVariants`, `inputVariants`,
+`tabsVariants`, `radioVariants`, `checkboxVariants` options).
 Registered names become typed values, but the library ships no CSS for them —
 the project styles `.bb-button--<name>` (etc.) itself, following the state
 recipe in [design-tokens.md](./design-tokens.md).

package/dist/ai/guides/design-tokens.md

@@ -373,6 +373,13 @@ ladder formulas instead of these tokens, so a state name never lies.
 | `--bb-elev`           | `0 0 0 0 transparent`             | Resting lift on **controls** (buttons, inputs, badges, alerts, checkbox, slider thumb, tab pill). A full `box-shadow`, composed under the focus ring, so one knob covers a soft lift (`0 1px 2px rgb(0 0 0 / 0.05)`) and a hard offset (`4px 4px 0 0 #111`) alike. The default is a transparent layer, not `none`, so the shadow list keeps a constant length and stays interpolable. `--bb-shadow` is the overlay lift; this is the resting one. Ghost / link / none buttons stay flat whatever the theme sets. Avatar and the Indicator bubble carry it via `--bb-elev-sm`; BbDropzone (no plate of its own — the surface is your content) and BbProgress (a recessed track, not a raised plate) deliberately do not. |
 | `--bb-elev-sm`        | `var(--bb-elev)`                  | The same lift on **small chrome** — badges, checkbox and radio glyphs, the slider thumb, the colour swatch, xs/sm buttons, the active pagination chip. It inherits `--bb-elev`, so a soft shadow needs one knob; only a hard offset needs the second value, because a hard offset has no falloff and its weight is purely relative to the box (a 4px offset is 11% of an xl button and 25% of a 16px glyph). It cannot be derived — CSS cannot halve the offsets inside a shadow string.                                                                                                                                                                                                                                |
 
+**Turn a shadow knob off with `0 0 0 0 transparent`, not `none`.** `--bb-elev`,
+`--bb-elev-sm` and `--bb-shadow-sm` are composed into `box-shadow` lists (the
+tab indicator stacks `--bb-elev` and `--bb-shadow-sm`), and `none` inside a list
+invalidates the whole declaration, taking the other layers with it. The
+transparent layer draws nothing and keeps the list valid. `--bb-shadow` stands
+alone wherever it is used, so `none` works there too.
+
 A four-knob chrome shift is `border-w` + `elev` + `shadow` + `radius`, and
 both nested tiers follow from the first and last, so there is no second pin
 to remember. Loud fills also pin `--bb-primary-border` and `--bb-link-fg`
@@ -476,14 +483,14 @@ to hardcode past it.
 
 ### Overlays
 
-| Token                  | Default                 | Notes                                                                                                                                                                                                                                                      |
-| ---------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--bb-overlay`         | `rgb(0 0 0 / 0.1)`      | Backdrop dim color+opacity in one — the bottom-most open panel's backdrop                                                                                                                                                                                  |
-| `--bb-overlay-stacked` | derived: `--bb-overlay` | Dim painted by a dialog or off-canvas stacked over another open one, on top of everything beneath it (the parent included). Derived, so a theme that only sets `--bb-overlay` gets a matching value; `transparent` gives a single dim under the whole pile |
-| `--bb-overlay-blur`    | `2px`                   | Backdrop blur — only the bottom-most open panel's backdrop carries it, whatever the depth                                                                                                                                                                  |
-| `--bb-surface-filter`  | `none`                  | Frost on raised plates (dialog, sheet, bubble, toast, alert, table, input shell). A full `backdrop-filter` value — `blur(22px) saturate(1.8)` — not a length. Glass themes set it and give `--bb-panel` an alpha.                                          |
-| `--bb-z-overlay`       | `10`                    | Overlay z-index                                                                                                                                                                                                                                            |
-| `--bb-arrow`           | `1`                     | Popover arrows on (`1`) / off (`0`)                                                                                                                                                                                                                        |
+| Token                 | Default                 | Notes                                                                                                                                                                                                                                                                                                                                                                        |
+| --------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--bb-overlay`        | `rgb(0 0 0 / 0.1)`      | Backdrop dim color+opacity in one — the bottom-most open panel's backdrop                                                                                                                                                                                                                                                                                                    |
+| `--bb-overlay-above`  | derived: `--bb-overlay` | Dim painted by a dialog or off-canvas stacked over another open one, on top of everything beneath it (the parent included). A dialog that replaces a member of its own `stack` paints none: the covered member's backdrop stays the only one. Derived, so a theme that only sets `--bb-overlay` gets a matching value; `transparent` gives a single dim under the whole pile |
+| `--bb-overlay-blur`   | `2px`                   | Backdrop blur — only the bottom-most open panel's backdrop carries it, whatever the depth                                                                                                                                                                                                                                                                                    |
+| `--bb-surface-filter` | `none`                  | Frost on raised plates (dialog, sheet, bubble, toast, alert, table, input shell). A full `backdrop-filter` value — `blur(22px) saturate(1.8)` — not a length. Glass themes set it and give `--bb-panel` an alpha.                                                                                                                                                            |
+| `--bb-z-overlay`      | `10`                    | Overlay z-index                                                                                                                                                                                                                                                                                                                                                              |
+| `--bb-arrow`          | `1`                     | Popover arrows on (`1`) / off (`0`)                                                                                                                                                                                                                                                                                                                                          |
 
 ### Input family
 

package/dist/ai/guides/icons-policy.md

@@ -262,8 +262,15 @@ markup) yourself:
   duplicate.
 - Meaningful standalone icon: give `BbIcon` a `label` — it adds `role="img"`
   and `aria-label`. Deliberately **no `title`**: that renders a native browser
-  tooltip, which double-tooltips any icon also carrying `v-bb-tooltip` (owner
-  ruling 2026-07-30, `BbIcon.vue:200`). For a visible tip, add `v-bb-tooltip`.
+  tooltip (owner ruling 2026-07-30). `BbIcon` is never focusable.
+- An info icon with a tip: make it an icon-only ghost `BbButton`, so keyboard
+  focus reaches it and opens the tip; the slot text is its name, the tip its
+  description:
+  `<BbButton variant="ghost" icon="lucide:info" v-bb-tooltip="'Prices include VAT'">About prices</BbButton>`.
+  When the text must be readable on touch, make it a `BbPopover` toggletip
+  (the same button as its activator; see the BbPopover guide, "Inline field
+  help"). `v-bb-tooltip` on a bare `BbIcon` or `<span>` is a pointer-only
+  hint: keyboard and touch never open it.
 - Icon-only `BbButton` (the `icon` prop): supply the accessible name through the
   label (default slot, or `text`) — it renders `sr-only` but is still announced.
   `aria-label` is only an override; the one hard rule is that the button must

package/dist/ai/guides/inertia-helpers.md

@@ -544,7 +544,12 @@ safe to sync from server responses without visit loops.
 // requires: npm i query-string
 import { router, usePage } from '@inertiajs/vue3';
 import qs from 'query-string';
-import { computed, type WritableComputedRef } from 'vue';
+import {
+	computed,
+	toValue,
+	type MaybeRefOrGetter,
+	type WritableComputedRef,
+} from 'vue';
 
 type Options<T> = {
 	/** Parse the raw string (e.g. `Number`). Defaults to identity. */
@@ -555,7 +560,8 @@ type Options<T> = {
 
 export function useRouteQuery<T = string>(
 	key: string,
-	defaultValue: string,
+	/** The value while the key is absent; a ref or getter is read each time. */
+	defaultValue: MaybeRefOrGetter<string>,
 	options: Options<T> = {}
 ): WritableComputedRef<T> {
 	const {
@@ -569,7 +575,7 @@ export function useRouteQuery<T = string>(
 		const [, queryString = ''] = page.url.split('?');
 		const raw = qs.parse(queryString)[key];
 		const single = Array.isArray(raw) ? raw[0] : raw;
-		return single != null ? String(single) : defaultValue;
+		return single != null ? String(single) : toValue(defaultValue);
 	};
 
 	return computed<T>({
@@ -580,7 +586,7 @@ export function useRouteQuery<T = string>(
 
 			const [path = '', queryString = ''] = page.url.split('?');
 			const query = qs.parse(queryString);
-			if (nextRaw === defaultValue) {
+			if (nextRaw === toValue(defaultValue)) {
 				delete query[key]; // keep URLs clean at the default
 			} else {
 				query[key] = nextRaw;
@@ -765,6 +771,14 @@ useQueryObject(filters, { only: ['invoices'], debounce: { search: 300 } });
 // partial reload and the server re-renders the `invoices` prop.
 ```
 
+> **The filters object never carries `page` / `per_page`.** Those keys have
+> their own URL writers (the `page` / `perPage` refs of
+> `usePaginatedResponseContext`, or `useRouteQuery`). Put the page ref in the
+> object too and a pager click visits twice: once through the ref, once
+> through this watcher. And `resetPage` stops working: `navigate()` deletes
+> `page` from the query, then writes the object's value back, so a filter
+> change keeps the old page, possibly past the last one.
+
 > **Typing: debounce the key, not the page.** Without `debounce`, "an
 > Inertia visit per change" is literal: a text field bound straight to
 > `filters.search` fires one `router.visit` per keystroke (the watcher does
@@ -799,9 +813,10 @@ the context, later callers join it — no provider component required.
 ### usePaginatedResponseContext
 
 Wraps a Laravel paginated prop (`PaginatedResponse<T>`) into a shared
-context: `items` (editable until next navigation), `totalItems`,
-`totalPages`, and URL-backed `page` / `perPage` refs. On every successful
-visit the context re-syncs from the fresh prop.
+context: `items` (editable until the prop changes), `totalItems`,
+`totalPages`, and `page` / `perPage` refs that read what the server answered
+and visit when written (`page` at 1 and `per_page` at the server's default
+leave the URL).
 
 ```ts
 // inertia-helpers/usePaginatedResponseContext.ts
@@ -809,9 +824,16 @@ import { useRouteQuery } from './useRouteQuery';
 import type { PaginatedResponse } from './types';
 import { isNotNil } from './utils';
 import type { PageProps } from '@inertiajs/core';
-import { router, usePage } from '@inertiajs/vue3';
+import { usePage } from '@inertiajs/vue3';
 import { injectLocal, provideLocal } from '@vueuse/core';
-import { computed, onScopeDispose, ref, type ComputedRef, type Ref } from 'vue';
+import {
+	computed,
+	ref,
+	watch,
+	watchEffect,
+	type ComputedRef,
+	type Ref,
+} from 'vue';
 
 export type PaginatedResponseContext<T> = {
 	totalItems: ComputedRef<number>;
@@ -868,11 +890,11 @@ export const usePaginatedResponseContext = <T = object>(
 	// `{ [key: string]: PaginatedResponse<T> }` doesn't have and fails
 	// `TS2344`. Intersecting with `PageProps` keeps the constraint satisfied
 	// either way, augmented or not.
+	const inertiaPage = usePage<
+		PageProps & Record<string, PaginatedResponse<T>>
+	>();
 	const paginated = computed(
-		() =>
-			usePage<PageProps & Record<string, PaginatedResponse<T>>>().props[
-				dataKey
-			] as PaginatedResponse<T>
+		() => inertiaPage.props[dataKey] as PaginatedResponse<T>
 	);
 
 	const pagination = computed(() => readPagination(paginated.value));
@@ -880,11 +902,33 @@ export const usePaginatedResponseContext = <T = object>(
 	const totalItems = computed(() => pagination.value.total);
 	const totalPages = computed(() => pagination.value.lastPage);
 
-	const perPage = useRouteQuery('per_page', `${pagination.value.perPage}`, {
-		transform: Number,
+	// A new prop is a new answer (a visit, Back / Forward); a partial reload of
+	// another prop keeps this one, and the edits made to `items`.
+	watch(paginated, (fresh) => (items.value = fresh.data ?? []));
+
+	// The server's default page size is what it answers a URL without
+	// `per_page`. Until such an answer arrives it is unknown (`''` matches no
+	// value), so picking a size never drops the key: a server that capped
+	// `?per_page=500` to 100 would otherwise fall back to its default.
+	const defaultPerPage = ref('');
+	watchEffect(() => {
+		const [, queryString = ''] = inertiaPage.url.split('?');
+		if (!new URLSearchParams(queryString).has('per_page'))
+			defaultPerPage.value = `${pagination.value.perPage}`;
+	});
+	const pageQuery = useRouteQuery('page', '1');
+	const perPageQuery = useRouteQuery('per_page', defaultPerPage);
+
+	// Both read the server's answer, not the URL: a clamped `?page=99`, a
+	// capped `?per_page=500` or a redirect to the bare URL shows what the
+	// server sent. Writing one visits, and only when the URL changes.
+	const page = computed({
+		get: () => pagination.value.current,
+		set: (next: number) => (pageQuery.value = `${next}`),
 	});
-	const page = useRouteQuery('page', `${pagination.value.current}`, {
-		transform: Number,
+	const perPage = computed({
+		get: () => pagination.value.perPage,
+		set: (next: number) => (perPageQuery.value = `${next}`),
 	});
 
 	const context: PaginatedResponseContext<T> = {
@@ -895,20 +939,6 @@ export const usePaginatedResponseContext = <T = object>(
 		items,
 	};
 
-	// Re-sync from the fresh prop after every successful visit.
-	const unbind = router.on('success', (event) => {
-		const props = event.detail.page.props as {
-			[key: string]: PaginatedResponse<T> | undefined;
-		};
-		const data = props[dataKey];
-		if (!data) return;
-		const fresh = readPagination(data);
-		items.value = data.data ?? [];
-		page.value = fresh.current;
-		perPage.value = fresh.perPage;
-	});
-	onScopeDispose(unbind);
-
 	provideLocal(toContextKey(dataKey), context);
 
 	return context;
@@ -933,20 +963,6 @@ return Inertia::render('Admin/Users/Index', [
 one while a next page exists) and `totalPages` ends at the next page, so a
 pager shows "next" until the last page.
 
-> **`router.on(...)` subscribes to a global, module-level event bus — it
-> outlives the component that registered it unless you unbind it.** Inertia
-> page components are destroyed and recreated on every visit, but
-> `router.on()` itself is not scoped to any of them: skip the `unbind` and
-> every past visit's listener is still live, still firing, and still
-> writing into a ref that belongs to a page nobody can see anymore. A
-> hand-rolled `router.on('start'/'finish')` loading flag on three list
-> screens without this call is not three small leaks — it's three
-> permanently-growing sets of listeners, one pair added per visit, for the
-> life of the tab. Always capture the return value and pass it to
-> `onScopeDispose()` — as shown above, and in every `router.on(...)` example
-> in this guide — the same call whether the composable happens to run
-> inside a component's `setup()` or a plain reactive effect scope.
-
 ### useTableSelectionContext
 
 Shared selection state by key, in server terms: `selected` and `unselected`
@@ -1395,10 +1411,10 @@ export const useConfirmOnRouteLeave = ({
 		})();
 	});
 
-	// Same `unbind` contract as `usePaginatedResponseContext` above — see the
-	// warning there. `onScopeDispose` over `onUnmounted`: it fires on
-	// unmount too (`setup()` runs inside a component's own effect scope),
-	// but also works if this composable is ever called from outside one.
+	// `router.on` is a global bus that outlives this component: unbind it.
+	// `onScopeDispose` over `onUnmounted`: it fires on unmount too (`setup()`
+	// runs inside a component's own effect scope), but also works if this
+	// composable is ever called from outside one.
 	onScopeDispose(unbind);
 };
 ```
@@ -1408,6 +1424,20 @@ Inertia's `before` event on hover too, and the guard lets them through (they
 leave nothing). The visit "Discard changes" re-sends is a plain one, never a
 prefetch or an `async` visit.
 
+> **`router.on(...)` subscribes to a global, module-level event bus — it
+> outlives the component that registered it unless you unbind it.** Inertia
+> page components are destroyed and recreated on every visit, but
+> `router.on()` itself is not scoped to any of them: skip the `unbind` and
+> every past visit's listener is still live, still firing, and still
+> writing into a ref that belongs to a page nobody can see anymore. A
+> hand-rolled `router.on('start'/'finish')` loading flag on three list
+> screens without this call is not three small leaks — it's three
+> permanently-growing sets of listeners, one pair added per visit, for the
+> life of the tab. Always capture the return value and pass it to
+> `onScopeDispose()` — as shown above — the same call whether the composable
+> happens to run inside a component's `setup()` or a plain reactive effect
+> scope.
+
 The dialog's words and look are BbConfirm's own options — `title`, `text`,
 `yes`, `no` (a label, or a full button config) and `variant` — defaulting to
 English (`'Discard changes'` / `'Keep editing'`, `variant: 'destructive'`).