# bitboss-ui — complete knowledge base

> Vue 3 component library by BitBoss: every guide, recipe, composable and
> component contract concatenated into one file.

**This file is for bulk ingestion — search indexes, embeddings, offline
evaluation. It is far larger than a useful prompt.** If you are an agent
about to write code, do NOT read this. Fetch
`https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/llms-medium.txt` instead, then hop to the one
component contract you need.

Canonical URL: https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/llms-full.txt
Index: https://cdn.jsdelivr.net/npm/bitboss-ui@beta/llms.txt

---

<!-- dist/ai/BbAccordion.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbAccordion.md -->

# BbAccordion

## Agent Contract

- Safety level: **Consumer API**
- Group: **Navigation**
- Description: Expands and collapses a content panel.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbAccordion.md](./source/BbAccordion.md)

## Usage & Guidelines

### When to use

`BbAccordion` is the top of the disclosure ladder: a ready-made panel that pairs
a header **button** with a collapsible body and wires the accessibility for you
(`aria-expanded`, `aria-controls`, `role="region"`, `aria-labelledby`). Reach for
it for FAQs, settings sections, and any "click a title to reveal detail" pattern.

Each `BbAccordion` is **one** panel controlled by a boolean `v-model`. Compose
several for a list; there is no group wrapper. That keeps the model explicit: for
independent panels give each its own boolean, and for single-open behaviour track
one active key yourself (shown below).

Step down the ladder when the composed header doesn't fit:

- Your trigger lives somewhere the header can't (inline link, toolbar, inside
  another component) → **`BbCollapsible`** (`./BbCollapsible.md`), the primitive
  this is built on.
- You only need to animate a height change, with no hide/show state at all →
  **`BbSmoothHeight`** (`./BbSmoothHeight.md`).

The public surface is small on purpose: `v-model` (boolean), `eager`,
`transition-duration`, `id`, two slots, and the `update:modelValue` event.
Everything else is composition.

### Composing an FAQ

The classic pricing-page FAQ is independent panels — each with its own boolean.
The `header` slot is rendered **inside the header button** — so put text and an
indicator there, never a nested `<button>`/`<a>`. Style the body on the slotted
content, not the panel: the underlying collapsible forces a true zero-height
collapsed state and strips padding/borders you put on the panel itself.

**A pricing-page FAQ of independent panels**

```vue
<template>
	<div
		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
	>
		<BbAccordion
			v-for="(faq, index) in faqs"
			:key="faq.question"
			v-model="faq.open"
			:class="index ? 'border-t border-[color:var(--bb-border)]' : ''"
		>
			<template #header="{ value }">
				<div
					class="flex w-full items-center justify-between gap-2 px-3 py-2 text-left text-sm font-medium"
				>
					<span>{{ faq.question }}</span>
					<span
						class="shrink-0 text-[color:var(--bb-text-muted)] transition-transform duration-200"
						:class="value ? 'rotate-180' : ''"
					>
						<BbIcon icon="lucide:chevron-down" size="sm" />
					</span>
				</div>
			</template>

			<p class="px-3 pb-2.5 text-sm text-[color:var(--bb-text-muted)]">
				{{ faq.answer }}
			</p>
		</BbAccordion>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbAccordion, BbIcon } from 'bitboss-ui';

type Faq = { question: string; answer: string; open: boolean };

// Pricing-page FAQ — independent panels, each with its own boolean.
const faqs = ref<Faq[]>([
	{
		question: 'Can I change plans mid-cycle?',
		answer:
			'Yes. Upgrades take effect immediately and are prorated; downgrades apply at the next renewal.',
		open: true,
	},
	{
		question: 'Do you offer annual billing?',
		answer:
			'Annual plans are billed once per year at a 20% discount versus monthly.',
		open: false,
	},
	{
		question: 'What happens when I exceed my seat limit?',
		answer:
			'New invites pause until you add seats or free an existing one. Usage never auto-charges.',
		open: false,
	},
]);
</script>
```

The header button spans the full width and is the only click target: any
non-interactive element you slot into it is made click-transparent
(`pointer-events: none`), so wrappers, icons and badges never swallow the toggle
click.

That click-transparency is what lets headers carry rich, passive metadata. An
API-reference disclosure list leans on it: a soft method `BbBadge` and a
`<code>` path in the header, parameter details in the body — clicking anywhere
on the row, badge included, toggles the panel.

**An API reference disclosure list**

```vue
<template>
	<div
		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
	>
		<BbAccordion
			v-for="(endpoint, index) in endpoints"
			:key="`${endpoint.method}:${endpoint.path}`"
			v-model="endpoint.open"
			:class="index ? 'border-t border-[color:var(--bb-border)]' : ''"
		>
			<template #header="{ value }">
				<div class="flex w-full items-center gap-2 px-3 py-2 text-left">
					<BbBadge size="xs" :variant="METHOD_VARIANT[endpoint.method]">{{
						endpoint.method
					}}</BbBadge>
					<code class="truncate font-mono text-xs">{{ endpoint.path }}</code>
					<span
						class="ml-auto shrink-0 text-[color:var(--bb-text-muted)] transition-transform duration-200"
						:class="value ? 'rotate-180' : ''"
					>
						<BbIcon icon="lucide:chevron-down" size="sm" />
					</span>
				</div>
			</template>

			<div class="flex flex-col gap-1.5 px-3 pb-2.5">
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					{{ endpoint.summary }}
				</p>
				<dl class="flex flex-col gap-1 text-xs">
					<div
						v-for="param in endpoint.params"
						:key="param.name"
						class="flex items-baseline gap-2"
					>
						<dt class="shrink-0 font-mono">{{ param.name }}</dt>
						<dd class="text-[color:var(--bb-text-muted)]">
							{{ param.type }} · {{ param.description }}
						</dd>
					</div>
				</dl>
			</div>
		</BbAccordion>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbAccordion, BbBadge, BbIcon } from 'bitboss-ui';
import type { BbBadgeProps } from 'bitboss-ui';

type Endpoint = {
	method: 'GET' | 'POST' | 'DELETE';
	path: string;
	summary: string;
	params: Array<{ name: string; type: string; description: string }>;
	open: boolean;
};

// Soft status palette — method hue, not action intent (no primary/destructive).
const METHOD_VARIANT: Record<Endpoint['method'], BbBadgeProps['variant']> = {
	GET: 'soft-blue',
	POST: 'soft-green',
	DELETE: 'soft-red',
};

const endpoints = ref<Endpoint[]>([
	{
		method: 'GET',
		path: '/v1/invoices',
		summary: 'List invoices, most recent first. Paginated by cursor.',
		params: [
			{ name: 'status', type: 'string', description: 'draft, open or paid' },
			{ name: 'limit', type: 'integer', description: '1–100, default 25' },
		],
		open: true,
	},
	{
		method: 'POST',
		path: '/v1/invoices',
		summary: 'Create a draft invoice for a customer.',
		params: [
			{
				name: 'customer',
				type: 'string',
				description: 'customer id, required',
			},
			{ name: 'due_date', type: 'string', description: 'ISO date, optional' },
		],
		open: false,
	},
	{
		method: 'DELETE',
		path: '/v1/invoices/:id',
		summary: 'Delete a draft invoice. Finalized invoices cannot be deleted.',
		params: [
			{ name: 'id', type: 'string', description: 'invoice id, in path' },
		],
		open: false,
	},
]);
</script>

<!-- Soft status palette — canonical source: ai/guides/design-language.md § Using color.
     Non-scoped so variant classes on the child badge receive the accents. -->
<style>
.bb-badge.bb-badge--soft-blue {
	--accent: #2563eb;
}
.bb-badge.bb-badge--soft-green {
	--accent: #16a34a;
}
.bb-badge.bb-badge--soft-red {
	--accent: #dc2626;
}
.bb-badge.bb-badge--soft-blue,
.bb-badge.bb-badge--soft-green,
.bb-badge.bb-badge--soft-red {
	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
	--border-width: 1px;
	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
}
</style>
```

### Slot scope: the open flag and the toggle handle

Both slots — `header` and the default (body) slot — receive the same scope,
`{ value, toggle }`:

- `value` mirrors the open state (one-way — assigning to it does nothing). Use
  it to spin a chevron or swap header copy.
- `toggle()` flips the panel. In the header it is redundant (the button already
  toggles); its real use is in the **body**, for a "Show less" affordance that
  collapses the panel without reaching back to the header. Writing to your own
  `v-model` ref is equivalent — pick one style.

**A body action that closes the panel**

```vue
<template>
	<div
		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
	>
		<BbAccordion v-model="notes">
			<template #header="{ value }">
				<div
					class="flex w-full items-center justify-between gap-2 px-3 py-2 text-left text-sm font-medium"
				>
					<span>Release notes</span>
					<span
						class="shrink-0 text-[color:var(--bb-text-muted)] transition-transform duration-200"
						:class="value ? 'rotate-180' : ''"
					>
						<BbIcon icon="lucide:chevron-down" size="sm" />
					</span>
				</div>
			</template>
			<template #default="{ toggle }">
				<div class="flex flex-col items-start gap-1.5 px-3 pb-2.5">
					<p class="text-sm text-[color:var(--bb-text-muted)]">
						Dropdown keyboard navigation, smoother select popovers, and a new
						color picker.
					</p>
					<BbButton variant="link" @click="toggle">Show less</BbButton>
				</div>
			</template>
		</BbAccordion>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbAccordion, BbButton, BbIcon } from 'bitboss-ui';

// Panel starts open so the in-body "Show less" affordance is visible.
const notes = ref(true);
</script>
```

`update:modelValue` fires on every toggle (header click or `toggle()` call) with
the new boolean — listen to it only for side effects (analytics, lazy-fetch on
first open); the open/close itself needs no handler.

### Single-open (exclusive) accordions

Track the open index/key and derive
each panel's state from it; opening one closes the rest, and clicking the open
header closes all (the `update:modelValue` payload is `false`, so the key resets
to `null`). Prefer a stable key over an index when the list can reorder.

**Only one plan expanded at a time**

```vue
<template>
	<div
		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
	>
		<BbAccordion
			v-for="(plan, index) in plans"
			:key="plan.name"
			:class="index ? 'border-t border-[color:var(--bb-border)]' : ''"
			:model-value="openIndex === index"
			@update:model-value="openIndex = $event ? index : null"
		>
			<template #header="{ value }">
				<div
					class="flex w-full items-center justify-between gap-2 px-3 py-2 text-left text-sm"
				>
					<span class="font-medium">{{ plan.name }}</span>
					<span
						class="flex items-center gap-1.5 text-[color:var(--bb-text-muted)]"
					>
						{{ plan.price }}
						<span
							class="shrink-0 transition-transform duration-200"
							:class="value ? 'rotate-180' : ''"
						>
							<BbIcon icon="lucide:chevron-down" size="sm" />
						</span>
					</span>
				</div>
			</template>

			<ul
				class="flex flex-col gap-1 px-3 pb-2.5 text-sm text-[color:var(--bb-text-muted)]"
			>
				<li v-for="feature in plan.features" :key="feature">{{ feature }}</li>
			</ul>
		</BbAccordion>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbAccordion, BbIcon } from 'bitboss-ui';

type Plan = { name: string; price: string; features: string[] };

const plans: Plan[] = [
	{
		name: 'Starter',
		price: 'Free',
		features: ['1 project', 'Community support', '7-day history'],
	},
	{
		name: 'Team',
		price: '$29 / mo',
		features: ['Unlimited projects', 'Priority support', 'SSO'],
	},
	{
		name: 'Enterprise',
		price: 'Custom',
		features: ['Dedicated success manager', 'Audit logs', 'Custom SLAs'],
	},
];

// Only one panel open at a time — a plain index keeps them mutually exclusive.
const openIndex = ref<number | null>(0);
</script>
```

### Nesting accordions

Panels nest without extra wiring: the body animates with CSS grid rows, so an
inner panel opening simply grows the outer one. Keep the hierarchy readable with
padding on the nested body content.

**A settings section with a nested advanced panel**

```vue
<template>
	<div
		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
	>
		<BbAccordion v-model="notifications">
			<template #header="{ value }">
				<div
					class="flex w-full items-center justify-between gap-2 px-3 py-2 text-left text-sm font-medium"
				>
					<span>Notifications</span>
					<span
						class="shrink-0 text-[color:var(--bb-text-muted)] transition-transform duration-200"
						:class="value ? 'rotate-180' : ''"
					>
						<BbIcon icon="lucide:chevron-down" size="sm" />
					</span>
				</div>
			</template>
			<div class="flex flex-col gap-2 px-3 pb-2.5 text-sm">
				<BbCheckbox v-model="mentions" label="Mentions" />
				<BbCheckbox v-model="digests" label="Weekly digest" />
				<BbAccordion v-model="advanced">
					<template #header="{ value }">
						<div
							class="flex w-full items-center justify-between gap-2 py-1 text-left text-sm text-[color:var(--bb-text-muted)]"
						>
							<span>Advanced</span>
							<span
								class="shrink-0 transition-transform duration-200"
								:class="value ? 'rotate-180' : ''"
							>
								<BbIcon icon="lucide:chevron-down" size="sm" />
							</span>
						</div>
					</template>
					<div class="pb-1 pt-1">
						<BbCheckbox v-model="quiet" label="Quiet hours (22:00–08:00)" />
					</div>
				</BbAccordion>
			</div>
		</BbAccordion>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbAccordion, BbCheckbox, BbIcon } from 'bitboss-ui';

const notifications = ref(true);
const mentions = ref(true);
const digests = ref(false);
const advanced = ref(false);
const quiet = ref(false);
</script>
```

### Deferred vs eager mounting, and timing

The body is **not rendered until the first open** — no wasted work for panels
the user never touches. Once opened it stays mounted, so state inside the body
survives close/reopen. While closed, mounted content is `aria-hidden` and
`inert`: it leaves the tab order and cannot be focused or clicked.

Pass `eager` to mount the body immediately — needed when the content must exist
up front: searchable/indexable text, form fields that register or validate
before the panel is ever opened, anything you measure on mount.

`transition-duration` (ms, default 250) tunes the open/close animation — one
value drives both the height and the fade. Users with `prefers-reduced-motion`
get a near-instant transition automatically.

**Eager body with a slower transition**

```vue
<BbAccordion v-model="state.shipping" eager :transition-duration="350">
	<template #header>
		<span class="px-3 py-2 text-sm font-medium">Shipping details</span>
	</template>
	<p class="px-3 pb-3 text-sm text-[color:var(--bb-text-muted)]">
		Rendered up front so its text is present even while collapsed.
	</p>
</BbAccordion>
```

### Stable ids

Pass `id` when you need deterministic markup (tests, external `aria-*`
references): the body region gets your id and the header gets `<id>_header`,
already cross-wired via `aria-controls`/`aria-labelledby`. Omitted, a unique id
is generated for you.

### Works well with

- `BbIcon` — a rotating chevron in the header, driven by the slot's `value` (see
  the FAQ example).
- `BbBadge` — counts or soft method/status pills in the header (see the API
  reference example); non-interactive content stays click-transparent.
- `BbCollapsible` / `BbSmoothHeight` — the rungs to step down to when the
  composed header doesn't fit (see When to use).
- Form components (`BbCheckbox`, `BbTextInput`…) in the body for progressive
  disclosure of settings — add `eager` when those fields must exist on mount.

### Gotchas & anti-patterns

- **Don't nest interactive elements in the header** — it is already a `<button>`;
  a nested button/link is invalid HTML and splits the click target. Actions
  belong in the body.
- **Don't build a group wrapper** with watchers that force-close siblings —
  derive `model-value` from one active key instead (single-open above).
- **Don't put padding/borders on the panel itself** expecting them to collapse —
  the collapsed state zeroes them; style the slotted content.
- **Don't add `v-if`/`v-show` around the body** to "optimize" — deferred
  mounting is already the default; `eager` is the explicit opt-out.
- **Hover styles on non-interactive header children won't fire** (they are
  `pointer-events: none` by design) — style hover states on the header button
  via the wrapper instead.

### Accessibility

- The header is a real `button` with `aria-expanded`/`aria-controls`; the body
  is a `role="region"` labelled by the header via `aria-labelledby`. You add
  nothing — and you must not wrap the header slot in another interactive
  element.
- Keyboard comes free with the native button: Tab to the header, Enter/Space
  toggles. Closed content is `inert`, so it can never be tabbed into.
- Provide a visible, meaningful header label; the chevron is decorative (mark
  custom SVGs `aria-hidden`).
- Honours `prefers-reduced-motion` via the underlying `BbCollapsible`.

## v-model

- `v-model` — type: `boolean \| undefined`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to trigger opening / closing the collapsible. An accordion with no `v-model` starts closed. |
| `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds |

## Events

- `update:modelValue` — `(event: "update:modelValue", value: boolean): void`

## Slots

- `default` — scope: `BbAccordionToggleSlotProps` — The collapsible body content shown when the accordion is open.
- `header` — scope: `BbAccordionToggleSlotProps` — Content rendered inside the accordion header button.

## See Also

- [BbCollapsible](./BbCollapsible.md) — Toggles visibility of collapsible content blocks.
- [BbTabs](./BbTabs.md) — Switches between tabbed content views (shadcn-like strip; the co-located BbTabsRoot / BbTabsList / BbTabsPanes exports enable split layouts).

---

<!-- dist/ai/BbAlert.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbAlert.md -->

# BbAlert

## Agent Contract

- Safety level: **Consumer API**
- Group: **Feedback**
- Description: Shows contextual status messages.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbAlert.md](./source/BbAlert.md)

## Usage & Guidelines

### When to use

Reach for `BbAlert` when a message belongs _to the page_ and must remain
visible until the user reads or dismisses it: a form-level error summary, a
plan/quota warning, an inline "changes saved" confirmation on a settings panel.

Choose a sibling when the shape is different:

- Transient, floating, self-dismissing feedback after an action → `BbToast`
  (paired with `useToast`).
- A small count or status marker _on_ another element → `BbBadge`.
- A yes/no decision the user must take → `BbConfirm` + `useConfirm`, not an
  alert with buttons.

`BbAlert` renders in normal document flow (no portal, no fixed position, no
teleport), so it pushes surrounding content, reads top-to-bottom like the rest
of the page, and is safe to server-render as-is in Nuxt/Inertia apps. It has no
size prop: it fills its container's width, so control width with the layout
around it (`max-w-md` etc.).

### The variant ladder

Pick a variant by intent, not decoration. `outline` is the quietest (neutral
info); `primary` carries a branded, actionable note; `warning` flags something
the user should attend to; `destructive` reports a failure or dangerous state.
An alert reads far better with a matching leading `icon`, so treat variant and
icon as a pair.

**Semantic variants, each with a fitting icon**

```vue
<div class="flex max-w-md flex-col gap-3">
	<BbAlert
		variant="outline"
		icon="lucide:info"
		title="Note"
		text="Outline is the quietest variant — use it for neutral info."
		hide-close
	/>
	<BbAlert
		variant="primary"
		icon="lucide:rocket"
		title="Update available"
		text="Version 2.4.0 is ready to install."
		hide-close
	/>
	<BbAlert
		variant="warning"
		icon="lucide:triangle-alert"
		title="Storage almost full"
		text="You have used 92% of your quota."
		hide-close
	/>
	<BbAlert
		variant="destructive"
		icon="lucide:circle-x"
		title="Payment failed"
		text="Your card was declined. Try another method."
		hide-close
	/>
</div>
```

The default variant is `outline`. `warning` and `destructive` are treated as
high-priority for accessibility (see below).

There is no `success` (or `positive`) variant, and it will not be added — the
shared status vocabulary is closed to `danger`/`warn` by ruling, see
[Design Tokens § Brand knobs](./guides/design-tokens.md#brand-knobs-what-a-theme-builder-sets)
("state colors are project-owned"). Reach for `primary` for a positive
confirmation, or register your own variant (below) if the project needs a
distinct success tone.

#### Registering project variants

Variants are an open registry, not a closed enum. The vite/nuxt plugin's
`alertVariants` option appends names to the typed union
(`outline | primary | destructive | warning` by default), and each variant
renders a `bb-alert--<name>` class hook. Registered custom variants ship **no
styles** — you provide the CSS, setting the same tokens the built-ins use:

```ts
// vite.config.ts
bitbossUi({
	iconDir: './src/icons',
	alertVariants: ['success'],
});
```

```css
.bb-alert--success {
	--main-color: #15803d; /* title + icon */
	--muted-color: color-mix(
		in oklab,
		var(--main-color) 75%,
		transparent
	); /* body + close */
	background-color: transparent;
	border-color: var(--bb-border);
}
```

One a11y catch: only `warning` and `destructive` are hard-coded as
high-priority. A custom variant — however alarming its name — announces as
`role="status"` / `aria-live="polite"` unless you also pass `role="alert"` /
`aria-live="assertive"` on urgent instances.

### Dismissal and v-model

The close button is rendered by default. Clicking it sets the model to `false`
(emitting `update:modelValue`) and the alert animates out. Note that this works
_even without a `v-model`_ — the internal model defaults to `true`, so an
unbound alert can still be dismissed; you just can't observe or restore it.
Bind `v-model` when the visibility matters to you:

**Dismiss and restore a banner**

```vue
<template>
	<div
		class="flex max-w-md flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Account</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Confirm your email to invite teammates and manage billing.
			</p>
		</div>

		<!--
			`v-model` alone owns the dismissal, so the alert plays its own leave
			transition. Pairing it with a `v-if` on the SAME element unmounts the
			node the instant the model flips and the animation never runs.
		-->
		<BbAlert
			v-model="showBanner"
			close-label="Dismiss email verification reminder"
			icon="lucide:mail"
			text="We sent a link to alex@northwind.co. Confirm within 24 hours or the invite link expires."
			title="Verify your email"
			variant="primary"
		/>
		<BbButton
			v-if="!showBanner"
			prepend:icon="lucide:mail"
			variant="ghost"
			@click="showBanner = true"
		>
			Show the reminder again
		</BbButton>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbAlert, BbButton } from 'bitboss-ui';

const showBanner = ref(true);
</script>
```

- `hide-close` removes the close button entirely — the only way to make an
  alert truly permanent (e.g. a blocking error that clears itself when the
  underlying condition resolves).
- `close-label` overrides the close button's accessible name (it defaults to a
  localised "Close"/"Chiudi" from the plugin `locale`).
- `transition-duration` (ms, default 250) tunes the enter/leave fade+slide;
  `prefers-reduced-motion` collapses it automatically. Setting the model back
  to `true` re-enters with the same transition, so a restored banner doesn't
  pop.

### Icons

`icon` renders a leading icon tinted with the variant's main colour; `iconSize`
(default `'16'`, any `BbIcon` size) scales it. No variant implies an icon —
always pass one explicitly and keep it semantically aligned with the variant
(see the ladder example above). The icon is reinforcement only: the message
must read correctly from `title`/`text` alone.

### Rich content with slots

`title` and `text` cover the common case. When the body needs emphasis, a link,
or inline markup, use the `title` / `text` slots. Each slot receives
`{ text }` — the corresponding prop's value — so a slot can decorate the plain
prop instead of replacing it. Offload navigation to a real anchor; never wire a
click handler for something a link can do.

**Custom body with an inline link**

```vue
<div class="max-w-md">
	<BbAlert variant="primary" icon="lucide:sparkles" hide-close>
		<template #title>You're on the <strong>Free</strong> plan</template>
		<template #text>
			Upgrade to unlock unlimited projects.
			<a href="#pricing" class="font-medium underline">Compare plans</a>
		</template>
	</BbAlert>
</div>
```

**The default slot is the text slot.** `<BbAlert>Something went wrong</BbAlert>`
is the shortest form and the one to reach for; `text` as a prop is for when a
string is all you have (an `:items` loop, a server message). When more than one
is present the most specific wins: `#text` > children > `text`.

There is no `actions` slot. A short inline link in the text (as above) is fine;
anything more interactive belongs outside the alert, or in a `BbDialog`.

#### Brand art via a raw SVG

When the message concerns a third-party product — an integration that broke,
an app that needs reauthorising — the alert reads faster with that product's
logomark inline. Keep the `icon` prop for the semantic status glyph and place
the brand art in the `#title` slot as a standalone `BbIcon`: its `icon` prop
also accepts a full raw `<svg>` string, so a `?raw` import of the asset feeds
it directly, no icon-registry entry needed. Reserve this escape hatch for
genuine brand art; everything semantic stays a provider icon.

**Integration incident notice with a brand mark**

```vue
<template>
	<div
		class="flex max-w-md flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Integrations</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Connected payment providers for Northwind Billing.
			</p>
		</div>

		<BbAlert hide-close icon="lucide:triangle-alert" variant="warning">
			<template #title>
				<span class="inline-flex items-center gap-1.5">
					<BbIcon :icon="acmeMark" label="Acme Payments" size="sm" />
					Acme Payments needs to be reconnected
				</span>
			</template>
			<template #text>
				The OAuth token expired on 8 Jul, so payment webhooks are paused.
				<a class="font-medium underline" href="#integrations">
					Reconnect in Integrations
				</a>
			</template>
		</BbAlert>
	</div>
</template>

<script setup lang="ts">
import { BbAlert, BbIcon } from 'bitboss-ui';
import acmeMark from './acme-mark.svg?raw';
</script>
```

### Validation summaries

The classic form pattern: a `destructive` alert above the form that appears on
a failed submit and lists what's missing. Use `hide-close` — the user clears it
by fixing the input, not by dismissing the message. Because `destructive`
defaults to `role="alert"`, showing it interrupts the screen reader
appropriately, and `aria-atomic` re-announces the whole message whenever the
list of problems changes.

**Publish blocked until the checklist passes**

```vue
<template>
	<div
		class="flex max-w-md flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Publish checklist</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Northwind Q3 release notes — blocked until both items are done.
			</p>
		</div>

		<BbAlert
			v-if="attempted && missing.length"
			hide-close
			icon="lucide:circle-x"
			title="Can't publish yet"
			variant="destructive"
		>
			<template #text>
				Fix these before publishing:
				<ul class="mt-1 list-inside list-disc text-sm">
					<li v-for="step in missing" :key="step">{{ step }}</li>
				</ul>
			</template>
		</BbAlert>

		<div class="flex flex-col gap-2">
			<BbCheckbox v-model="hasTitle" label="Add a release title" />
			<BbCheckbox v-model="hasCover" label="Attach the hero screenshot" />
		</div>

		<BbButton
			class="self-start"
			prepend:icon="lucide:send"
			variant="primary"
			@click="publish"
		>
			Publish
		</BbButton>

		<BbAlert
			v-if="published"
			v-model="published"
			icon="lucide:circle-check"
			text="Release notes are live on the changelog."
			title="Published"
			variant="primary"
		/>
	</div>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbAlert, BbButton, BbCheckbox } from 'bitboss-ui';

const hasTitle = ref(false);
const hasCover = ref(false);
const attempted = ref(false);
const published = ref(false);

const missing = computed(() => [
	...(hasTitle.value ? [] : ['Add a release title']),
	...(hasCover.value ? [] : ['Attach the hero screenshot']),
]);

const publish = () => {
	attempted.value = true;
	published.value = missing.value.length === 0;
};
</script>
```

### Works well with

- `BbToast` — pair them: the toast confirms _the action_ ("Saved"), the alert
  reflects _the resulting page state_ (an unresolved quota warning stays).
- `BbConfirm` / `useConfirm` — when the message is really a decision, ask;
  don't display an alert and hope.
- Form components (`BbTextInput`, `BbCheckbox`, …) — alert above the form for
  the summary, per-field errors on the inputs themselves.

### Gotchas & anti-patterns

- **Omitting `v-model` does not make an alert permanent** — the close button
  still dismisses it locally. Use `hide-close` for that.
- Don't rebuild dismissal with your own button + `v-if`; the built-in close
  button gives you the transition, the localised label, and the event.
- Don't stack several `assertive` alerts that appear together — they talk over
  each other. One summary alert beats five fragments.
- A custom registered variant is polite by default; pass `role="alert"` on the
  instances that are genuinely urgent.
- `modelValue` is typed `any` on purpose (so Vue doesn't coerce an absent
  binding to `false`); treat it as a boolean in your own state.

### Accessibility

- The container's ARIA role and live-region politeness derive from the
  variant: `warning` / `destructive` announce as `role="alert"` /
  `aria-live="assertive"`; every other variant (built-in or custom) uses
  `role="status"` / `aria-live="polite"`. Override per instance with the
  `role` / `aria-live` props only with a specific reason.
- The alert is `aria-atomic`, so updating its text re-announces the whole
  message rather than a fragment.
- The close button ships with a localised label (plugin `locale`); pass
  `close-label` to override it per alert.
- Reserve `assertive`/`role="alert"` for genuinely urgent messages so you
  don't talk over the user's screen reader.

## v-model

- `v-model` — type: `any`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `ariaLive` | `"off" \| "polite" \| "assertive" \| undefined` |  |  | ARIA live region politeness. Defaults to `'assertive'` for destructive/warning variants, otherwise `'polite'`. |
| `closeLabel` | `string \| undefined` |  |  | Visually hidden string used to label the close button. |
| `hideClose` | `boolean \| undefined` | `false` |  | Defines whether to hide the close button. |
| `icon` | `string \| undefined` |  |  | Name of a registered icon to use, or a full raw `<svg>` string (e.g. an SVG file imported with `?raw`). |
| `iconSize` | `number \| ({ size?: any; } & string) \| keyof Sizes \| undefined` | `"16"` |  | Size of the icon to use. |
| `modelValue` | `any` | `true` |  | Used by v-model, set type to any to avoid Vue casting it as false. Alerts are visible on mount; the model dismisses them. |
| `role` | `"alert" \| "status" \| undefined` |  |  | Accessibility role for the alert container. Defaults to `'alert'` for destructive/warning variants, otherwise `'status'`. |
| `text` | `string \| undefined` |  |  | Text content of the alert body. |
| `title` | `string \| undefined` |  |  | Text content of the alert title. |
| `transitionDuration` | `number \| undefined` | `250` |  | Transition duration in milliseconds for enter/leave. |
| `variant` | `keyof AlertVariantRegistry \| undefined` | `"outline"` |  | Visual variant of the alert. |

## Events

- `update:modelValue` — `(event: "update:modelValue", value: boolean): void`

## Slots

- `default` — scope: `any` — The alert body — the shortest form, and the one to reach for: `<BbAlert>Something went wrong</BbAlert>`. Same idiom as the rest of the `text`-prop family (BbButton, BbBaseButton, BbTooltip, BbIndicator). When more than one source is present…
- `text` — scope: `BbAlertTextSlotProps` — Replaces the default alert body text. Wins over children and `text`.
- `title` — scope: `BbAlertTitleSlotProps` — Replaces the default alert title text.

## See Also

- [BbToast](./BbToast.md) — Shows transient notification messages (includes the co-located BbToastPortal export).

---

<!-- dist/ai/BbAsterisk.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbAsterisk.md -->

# BbAsterisk

## Agent Contract

- Safety level: **Consumer API**
- Group: **Other**
- Description: Presentational required-field marker (red "*"). No props/slots/events; placed in custom label content.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbAsterisk.md](./source/BbAsterisk.md)

## Usage & Guidelines

### When to use

`BbAsterisk` is the small red `*` that marks a field as required. It is purely
presentational — it has no props, slots, or events, and it does not read
`required` or drive validation. You render it yourself wherever you build custom
label content, so the marker matches the library's styling (`--bb-danger`).

Most consumers never place it by hand: the `bitboss-ui/validated` 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
you compose a bespoke label outside those controls.

```vue
<BbTextInput label="Email">
	<template #label="{ text }">
		{{ text }}<BbAsterisk />
	</template>
</BbTextInput>
```

Wrap it in an element with your own spacing if the default `margin-inline-start`
doesn't suit the layout; the glyph inherits nothing else from its surroundings.

### It is `aria-hidden` — the control carries the requirement

The span renders `aria-hidden="true"`, so **screen readers never announce it**.
That is deliberate: an asterisk read aloud as "star" is noise, and a marker
placed in a label is not a reliable way to convey a requirement. What actually
carries mandatoriness to assistive tech is the **`required` attribute on the
control** — which the library sets from your `required` prop.

The practical consequence: the marker is a _visual_ affordance only, and
`required` is the real thing. Never ship a field that shows the asterisk
without `required` (sighted users see a requirement that assistive tech cannot
perceive), and never assume the asterisk is doing accessibility work.

`showAsterisk` on the validated 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.

## Props

- None.

## Events

- None.

## Slots

- None.

---

<!-- dist/ai/BbAvatar.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbAvatar.md -->

# BbAvatar

## Agent Contract

- Safety level: **Consumer API**
- Group: **Data Display**
- Description: Displays an avatar and has a fallback content slot.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbAvatar.md](./source/BbAvatar.md)

## Usage & Guidelines

### When to use

Use `BbAvatar` wherever a person or entity needs a visual identity — member
lists, comment threads, assignee cells, account menus. It is display-only: it
has no events and never becomes interactive by itself. For a status or count
riding on it, anchor a floating `BbIndicator`; for a clickable avatar (account
menu, profile link) put it _inside_ the interactive component — a `BbBaseButton`'s
default slot, a `BbDropdown` trigger — and for a selectable person, put the
avatar inside the control (e.g. a `BbSelect` option slot), not the other way
around.

### The fallback chain

The avatar resolves what to show in a fixed order:

1. **Image** — when `src` (or `srcset`) is set and loads correctly.
2. **Default slot** — when there is no source or the image fails: put initials
   (or any markup) here.
3. **Built-in user icon** — when you supply no slot either.

A failed load flips to the fallback automatically, and changing `src`/`srcset`
resets the attempt — so swapping users in place retries the new photo. Always
set `alt`: it labels the photo, and for a fallback it becomes the avatar's
accessible name.

**Photo, initials, and the built-in fallback**

```vue
<div class="flex items-center gap-3">
	<BbAvatar
		size="56"
		src="https://images.unsplash.com/photo-1494790108377-be9c29b29330?w=256&h=256&fit=crop&crop=faces&auto=format"
		:timeout="4000"
		alt="Ada Lovelace"
	/>
	<BbAvatar size="56" alt="Grace Hopper">GH</BbAvatar>
	<BbAvatar size="56" alt="Unknown user" />
</div>
```

### Responsive images

`srcset` + `sizes` pass straight through to the underlying `<img>`, so
high-density screens can pull a sharper asset while everyone else gets the
small one. The image is center-cropped (`object-fit: cover`) into a circle —
sources don't need to be pre-cropped square.

**Density-aware avatar**

```vue
<BbAvatar
	size="56"
	srcset="https://images.unsplash.com/photo-1580489944761-15a19d654956?w=128&h=128&fit=crop&crop=faces&auto=format 128w, https://images.unsplash.com/photo-1580489944761-15a19d654956?w=256&h=256&fit=crop&crop=faces&auto=format 256w"
	sizes="56px"
	:timeout="4000"
	alt="Margaret Hamilton"
/>
```

### Sizing and the fallback surface

`size` follows the icon scale (`xs–2xl`, 12–40 px by default — remapped
library-wide by the `iconDefaultSizes` plugin option), a number (px), a CSS
dimension string (`"3rem"`), or a percentage (`"100%"` fills a square parent).
The built-in fallback icon scales with the avatar automatically.

Composed demos below use the larger end of that range (and a few explicit px
sizes) so faces stay readable in Storybook — `xs`/`sm` are for dense chrome,
not hero examples.

The fallback surface is **always painted with the primary design token** —
`--bb-primary` behind, `--bb-primary-fg` for the initials/icon, the same
pairing as a primary button — so initials stay legible in light and dark and
every avatar matches your theme automatically.

There is no tinting **prop**, but there are three component locals on
`.bb-avatar` for the cases the theme cannot cover — a per-tenant or
per-user colour: `--bg-color` (fallback surface, defaults to `--bb-primary`),
`--text-color` (initials, `--bb-primary-fg`) and `--default-icon-color` (the
placeholder glyph). Set them on the avatar or on a class you put on it:

```vue
<BbAvatar text="Acme Studio" :style="{ '--bg-color': tenant.color }" />
```

**The size scale**

```vue
<div class="flex items-end gap-3">
	<BbAvatar size="md" src="https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=256&h=256&fit=crop&crop=faces&auto=format" :timeout="4000" alt="Joan Clarke" />
	<BbAvatar size="lg" src="https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=256&h=256&fit=crop&crop=faces&auto=format" :timeout="4000" alt="Joan Clarke" />
	<BbAvatar size="xl" src="https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=256&h=256&fit=crop&crop=faces&auto=format" :timeout="4000" alt="Joan Clarke" />
	<BbAvatar size="2xl" src="https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=256&h=256&fit=crop&crop=faces&auto=format" :timeout="4000" alt="Joan Clarke" />
	<BbAvatar size="56" src="https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=256&h=256&fit=crop&crop=faces&auto=format" :timeout="4000" alt="Joan Clarke" />
</div>
```

### Presence with a floating dot

Wrap an avatar in [`BbIndicator`](./BbIndicator.md) with `dot` to show status —
`BbIndicator` positions and clips the marker for you, so you never hand-place an
absolutely-positioned dot. Prefer a status `variant` (`success` for online);
for offline / away override `--bg` with a muted token. Convey the state in text
too, since the dot alone is not announced.

**Online and offline presence**

```vue
<div class="flex items-center gap-3">
	<BbIndicator bottom dot variant="success">
		<BbAvatar
			size="40"
			src="https://images.unsplash.com/photo-1494790108377-be9c29b29330?w=256&h=256&fit=crop&crop=faces&auto=format"
			:timeout="4000"
			alt="Ada Lovelace — online"
		/>
	</BbIndicator>
	<BbIndicator bottom dot :style="{ '--bg': 'var(--bb-text-muted)' }">
		<BbAvatar size="40" alt="Grace Hopper — away">GH</BbAvatar>
	</BbIndicator>
</div>
```

### Avatar stacks

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).

**Reviewers stack with overflow**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3 text-sm"
	>
		<div class="flex items-center justify-between gap-2">
			<div class="flex flex-col gap-0.5">
				<span class="font-medium">Design review</span>
				<span class="text-xs text-[color:var(--bb-text-muted)]">
					PR #842 · {{ reviewers.length }} reviewers
				</span>
			</div>
			<BbButton size="sm" variant="ghost" @click="expanded = !expanded">
				{{ expanded ? 'Collapse' : 'Show all' }}
			</BbButton>
		</div>

		<div class="stack">
			<BbAvatar
				v-for="reviewer in visible"
				:key="reviewer.name"
				:alt="reviewer.name"
				size="40"
				:src="reviewer.src"
				:timeout="demoAvatarTimeout"
			>
				{{ reviewer.initials }}
			</BbAvatar>
			<BbAvatar
				v-if="!expanded && hiddenCount > 0"
				:alt="`${hiddenCount} more reviewers`"
				size="40"
			>
				+{{ hiddenCount }}
			</BbAvatar>
		</div>
	</div>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbAvatar, BbButton } from 'bitboss-ui';
import { demoAvatarTimeout, demoFaces } from './demoAvatars';

type Reviewer = {
	name: string;
	src?: string;
	initials?: string;
};

// The overflow indicator is just another avatar with the count in its slot —
// same size, same ring, no special markup.
const reviewers: Reviewer[] = [
	{ name: 'Ada Lovelace', src: demoFaces.ada },
	{ name: 'Grace Hopper', initials: 'GH' },
	{ name: 'Alan Turing', src: demoFaces.alan },
	{ name: 'Katherine Johnson', initials: 'KJ' },
	{ name: 'Margaret Hamilton', src: demoFaces.margaret },
];
const maxVisible = 3;

const expanded = ref(false);
const visible = computed(() =>
	expanded.value ? reviewers : reviewers.slice(0, maxVisible)
);
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-left: -12px;
}
</style>
```

### Team lists

Avatars, presence, initials fallback and filtering compose into a typical member
list — the row markup stays identical whether a member has a photo or not.

**A filterable team roster**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3 text-sm"
	>
		<div class="flex items-center justify-between gap-2">
			<div class="flex flex-col gap-0.5">
				<span class="font-medium">Team</span>
				<span class="text-xs text-[color:var(--bb-text-muted)]">
					{{ visible.length }} of {{ members.length }} members
				</span>
			</div>
			<BbButton size="sm" variant="outline" @click="onlineOnly = !onlineOnly">
				{{ onlineOnly ? 'Show all' : 'Online only' }}
			</BbButton>
		</div>

		<ul class="flex flex-col gap-2">
			<li
				v-for="member in visible"
				:key="member.name"
				class="flex items-center gap-2"
			>
				<BbIndicator
					bottom
					dot
					:style="
						member.online ? undefined : { '--bg': 'var(--bb-text-muted)' }
					"
					:variant="member.online ? 'success' : 'default'"
				>
					<BbAvatar
						:alt="member.name"
						size="40"
						:src="member.src"
						:timeout="demoAvatarTimeout"
					>
						{{ member.initials }}
					</BbAvatar>
				</BbIndicator>
				<span class="flex min-w-0 flex-1 flex-col">
					<span class="truncate font-medium">{{ member.name }}</span>
					<span class="truncate text-xs text-[color:var(--bb-text-muted)]">
						{{ member.role }} · {{ member.online ? 'Online' : 'Away' }}
					</span>
				</span>
			</li>
		</ul>
	</div>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbAvatar, BbIndicator, BbButton } from 'bitboss-ui';
import { demoAvatarTimeout, demoFaces } from './demoAvatars';

type Member = {
	name: string;
	role: string;
	online: boolean;
	src?: string;
	initials?: string;
};

// Some members have a photo; others fall back to initials on the
// primary-token surface — both flow through the same row markup.
const members: Member[] = [
	{
		name: 'Ada Lovelace',
		role: 'Engineering',
		online: true,
		src: demoFaces.ada,
	},
	{
		name: 'Grace Hopper',
		role: 'Design',
		online: true,
		initials: 'GH',
	},
	{
		name: 'Alan Turing',
		role: 'Research',
		online: false,
		src: demoFaces.alan,
	},
	{
		name: 'Katherine Johnson',
		role: 'Data',
		online: true,
		initials: 'KJ',
	},
	{
		name: 'Linus Torvalds',
		role: 'Platform',
		online: false,
		initials: 'LT',
	},
];

const onlineOnly = ref(false);
const visible = computed(() =>
	onlineOnly.value ? members.filter((member) => member.online) : members
);
</script>
```

### Bots and brand marks

Not every actor has a photo. Service accounts, integrations and in-product
assistants get a **brand mark** instead: put a [`BbIcon`](./BbIcon.md) in the
fallback slot. Hand-placing `BbIcon` is sanctioned here — `BbAvatar` has no
icon prop — and `BbIcon`'s `icon` prop accepts a raw `<svg>` string (import
the asset with `?raw`), so one-off brand art needs no icon collection. The
mark paints in `currentColor`, inheriting the fallback surface's
`--bb-primary-fg`, so it stays legible in both themes. Keep the icon
unlabeled and put the actor's name in `alt` as usual — the fallback announces
it for you.

**A release feed with a bot actor**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3 text-sm"
	>
		<div class="flex items-center justify-between gap-2">
			<span class="font-medium">Release activity</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]"
				>main · production</span
			>
		</div>

		<ul class="flex flex-col gap-2">
			<li v-for="entry in feed" :key="entry.id" class="flex items-center gap-2">
				<BbAvatar
					:alt="entry.actor"
					size="40"
					:src="entry.src"
					:timeout="demoAvatarTimeout"
				>
					<BbIcon v-if="entry.bot" :icon="releaseBotMark" size="sm" />
					<template v-else>{{ entry.initials }}</template>
				</BbAvatar>
				<span class="flex min-w-0 flex-1 flex-col">
					<span class="truncate">
						<span class="font-medium">{{ entry.actor }}</span>
						{{ entry.action }}
					</span>
					<span class="text-xs text-[color:var(--bb-text-muted)]">{{
						entry.time
					}}</span>
				</span>
			</li>
		</ul>
	</div>
</template>

<script setup lang="ts">
import { BbAvatar, BbIcon } from 'bitboss-ui';
// A raw `<svg>` string is a valid `icon` for BbIcon — the escape hatch for
// brand art that lives in no icon collection. It paints in `currentColor`,
// so on the avatar's fallback surface it inherits `--bb-primary-fg`.
import releaseBotMark from '@/assets/icons/sparkles.svg?raw';
import { demoAvatarTimeout, demoFaces } from './demoAvatars';

type FeedEntry = {
	id: number;
	actor: string;
	action: string;
	time: string;
	bot?: boolean;
	src?: string;
	initials?: string;
};

// The bot row hand-places a BbIcon in the fallback slot — sanctioned here,
// because BbAvatar has no icon prop. Human rows keep the exact same markup.
const feed: FeedEntry[] = [
	{
		id: 1,
		actor: 'Acme Releases',
		action: 'deployed v2.14.0 to production',
		time: '2 minutes ago',
		bot: true,
	},
	{
		id: 2,
		actor: 'Ada Lovelace',
		action: 'approved the release',
		time: '14 minutes ago',
		src: demoFaces.ada,
		initials: 'AL',
	},
	{
		id: 3,
		actor: 'Grace Hopper',
		action: 'tagged v2.14.0',
		time: '25 minutes ago',
		initials: 'GH',
	},
];
</script>
```

### Slow networks, SSR and the timeout prop

Load failures are normally caught by the image's `error` event. As a safety
net — mainly for SSR/hydrated pages where the events fired before hydration —
the component also checks the image `timeout` ms after mount (default `400`)
and switches to the fallback if it hasn't loaded correctly by then. The
`<img>` stays mounted (visually hidden) through that switch, so the deadline
is **not** terminal: a slow image shows the fallback at `timeout` and swaps
itself back in the moment it finishes loading. Only a real `error` is
permanent until `src` changes. If your avatars come from a slow origin, raise
`timeout` rather than accepting a visible fallback-then-photo flip.

Platform notes: the component is SSR-safe (Nuxt/Inertia) with no client-only
markup; the only global config it reads is `iconDefaultSizes` for the size
keys.

### Works well with

- [`BbIndicator`](./BbIndicator.md) — floating presence dots and counts (see above).
- `BbTable` — avatar cells pair with the built-in loading skeleton styles
  `skeleton="avatar"` / `"avatar-text"`.
- `BbDropdown` / `BbButton` — wrap the avatar in these for account menus and
  profile links; the avatar itself never handles clicks.
- `BbSelect` — render avatars in option slots for people pickers.
- [`BbIcon`](./BbIcon.md) — brand marks for bots and integrations in the
  fallback slot, including raw `?raw` SVG imports (see above).

### Gotchas & anti-patterns

- **There is no `color` prop, and no `variant` either.** The fallback is always
  primary-token colored; don't reach for per-avatar inline backgrounds. If the
  palette is wrong, retheme `--bb-primary` / `--bb-primary-fg` — theming here
  happens through the tokens, not a prop.
- **Default `timeout` can false-fallback slow images** (see above) — tune it,
  don't reimplement image loading around the component.
- Don't hand-position presence dots with absolute CSS — `BbIndicator dot`
  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.
- 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
  accessible name entirely.

### Accessibility

Always set `alt`. With an image it labels the photo; with a fallback the
component adds `role="img"` + `aria-label` (from `alt`) to the fallback, so
assistive tech announces the person, not the raw initials. If `alt` is empty,
the fallback renders with no role and no name — acceptable only for purely
decorative avatars. A presence dot is decorative — make the same status
available in visible text or an adjacent label.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `alt` | `string \| undefined` | `""` |  | Alternative text for the image, used for accessibility. |
| `size` | `number \| ({ size?: any; } & string) \| keyof Sizes \| undefined` | `"md"` |  | Defines the component size. Accepted values: - A key from the provided size map (`keyof T`), e.g. `'sm' \| 'md' \| 'lg'` - A custom CSS size string (e.g. `'20px'`, `'1.5rem'`, `'2em'`) - A number, typically interpreted as pixels by size par… |
| `sizes` | `string \| undefined` |  |  | Sizes attribute for the image, used with `srcset`. |
| `src` | `string \| undefined` |  |  | Source URL of the avatar image. |
| `srcset` | `string \| undefined` |  |  | Responsive image source set. |
| `timeout` | `number \| undefined` | `400` |  | Milliseconds to wait after mount before checking whether the image loaded correctly (SSR fallback). |

## Events

- None.

## Slots

- `default` — scope: `Record<string, never>` — Fallback content shown when no image source is provided or when the image fails to load. Typically used to render initials or a placeholder icon.

## See Also

- [BbBadge](./BbBadge.md) — Displays a compact inline status counter or label. It sits in the flow — for a bubble or dot anchored OVER another element, use BbIndicator (includes the co-located BbBadgeButton export).

---

<!-- dist/ai/BbBadge.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBadge.md -->

# BbBadge

## Agent Contract

- Safety level: **Consumer API**
- Group: **Feedback**
- Description: Displays a compact inline status counter or label. It sits in the flow — for a bubble or dot anchored OVER another element, use BbIndicator (includes the co-located BbBadgeButton export).
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbBadge.md](./source/BbBadge.md)

## Usage & Guidelines

### When to use

`BbBadge` is a small inline pill. Use it for a status label ("Active", "Beta"),
a short count, a removable token (`clearable`), a clickable chip (slot a
`BbBadgeButton`), or all three at once. The label always goes in the **default
slot**; there is no `text`/`content` prop.

Pick a sibling when the marker should do more:

- It's pinned over another element (an unread count on a bell, a presence dot on
  an avatar) → `BbIndicator`.
- The token is an _input_ for entering free-form values → `BbTag`.
- A standalone action that looks like a button → `BbButton`. Reach for
  `BbBadgeButton` only when the control should look like a **pill**.

### Status labels

Drive the look with the `variant` ladder; put the copy in the default slot.

**The variant ladder**

```vue
<div class="flex flex-wrap items-center gap-2">
	<BbBadge variant="primary">New</BbBadge>
	<BbBadge variant="secondary">Draft</BbBadge>
	<BbBadge variant="outline">v2.4.0</BbBadge>
	<BbBadge variant="destructive">Overdue</BbBadge>
</div>
```

The built-ins are `primary`, `secondary`, `destructive`, and `outline` — a floor,
not the whole vocabulary. Projects register extra tones via the plugin's
`badgeVariants` option; registration extends the TypeScript union and yields a
`bb-badge--<name>` class hook — you own the CSS (`--bg` and `--color` are the
tokens to set). **If your page needs a tone that isn't in the list, register it
and style it** — that is the sanctioned path, not a reason to force the design
into `secondary`/`outline`. For a genuinely one-off accent, override `--bg`
inline (see One-off colors).

#### Soft status pills

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"`
— that name is not built-in and ships no CSS.

**Invoice status pills + plan tiers**

```vue
<template>
	<div
		class="flex max-w-md flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Invoice status</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Soft accents for a small, fixed status set — not every row color.
			</p>
		</div>

		<ul class="flex flex-col gap-2 text-sm">
			<li
				v-for="row in invoices"
				:key="row.id"
				class="flex items-center justify-between gap-3"
			>
				<span class="min-w-0 truncate">
					<span class="font-medium">{{ row.number }}</span>
					<span class="text-[color:var(--bb-text-muted)]">
						· {{ row.client }}</span
					>
				</span>
				<BbBadge size="sm" :variant="row.variant">{{ row.status }}</BbBadge>
			</li>
		</ul>

		<div class="flex flex-wrap items-center gap-1.5 border-t pt-3">
			<span class="mr-1 text-xs text-[color:var(--bb-text-muted)]">Plan</span>
			<BbBadge size="sm" variant="soft-gray">Free</BbBadge>
			<BbBadge size="sm" variant="soft-blue">Pro</BbBadge>
			<BbBadge size="sm" variant="soft-amber">Enterprise</BbBadge>
		</div>
	</div>
</template>

<script setup lang="ts">
import { BbBadge } from 'bitboss-ui';
import type { BadgeVariantType } from 'bitboss-ui';

type InvoiceRow = {
	id: string;
	number: string;
	client: string;
	status: string;
	variant: BadgeVariantType;
};

const invoices: InvoiceRow[] = [
	{
		id: 'inv-1041',
		number: 'INV-1041',
		client: 'Northwind',
		status: 'Paid',
		variant: 'soft-green',
	},
	{
		id: 'inv-1042',
		number: 'INV-1042',
		client: 'Globex',
		status: 'Pending',
		variant: 'soft-amber',
	},
	{
		id: 'inv-1043',
		number: 'INV-1043',
		client: 'Initech',
		status: 'Overdue',
		variant: 'soft-red',
	},
	{
		id: 'inv-1044',
		number: 'INV-1044',
		client: 'Umbrella',
		status: 'Draft',
		variant: 'soft-gray',
	},
];
</script>

<!-- Soft status palette — canonical source: ai/guides/design-language.md § Using color.
     Non-scoped so variant classes on the child badge receive the accents. -->
<style>
.bb-badge.bb-badge--soft-gray {
	--accent: #64748b;
}
.bb-badge.bb-badge--soft-blue {
	--accent: #2563eb;
}
.bb-badge.bb-badge--soft-green {
	--accent: #16a34a;
}
.bb-badge.bb-badge--soft-amber {
	--accent: #d97706;
}
.bb-badge.bb-badge--soft-red {
	--accent: #dc2626;
}

.bb-badge.bb-badge--soft-gray,
.bb-badge.bb-badge--soft-blue,
.bb-badge.bb-badge--soft-green,
.bb-badge.bb-badge--soft-amber,
.bb-badge.bb-badge--soft-red {
	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
	--border-width: 1px;
	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
}
</style>
```

#### Counts on nav items

A count in a sidebar row is a standalone badge, right-aligned inside the row.
The row's `<a>` owns the navigation; the badge stays inert. Format overflow
yourself (`99+`) — there is no `max` prop.

**Unread counts in a mail sidebar**

```vue
<template>
	<nav
		aria-label="Mail folders"
		class="flex max-w-56 flex-col gap-0.5 rounded-[var(--bb-radius)] border p-1.5 text-sm"
	>
		<a
			v-for="folder in folders"
			:key="folder.href"
			:aria-current="folder.active ? 'page' : undefined"
			class="flex items-center justify-between gap-2 rounded-[var(--bb-radius-sm)] px-2 py-1"
			:class="
				folder.active
					? 'bg-[color:var(--bb-muted)] font-medium'
					: 'text-[color:var(--bb-text)]'
			"
			:href="folder.href"
		>
			<span class="truncate">{{ folder.label }}</span>
			<BbBadge
				v-if="folder.count"
				size="sm"
				:variant="folder.active ? 'primary' : 'secondary'"
				>{{ folder.count }}</BbBadge
			>
		</a>
	</nav>
</template>

<script setup lang="ts">
import { BbBadge } from 'bitboss-ui';

type Folder = {
	label: string;
	href: string;
	count?: number;
	active?: boolean;
};

const folders: Folder[] = [
	{ label: 'Inbox', href: '#inbox', count: 24, active: true },
	{ label: 'Starred', href: '#starred', count: 3 },
	{ label: 'Drafts', href: '#drafts', count: 2 },
	{ label: 'Sent', href: '#sent' },
	{ label: 'Spam', href: '#spam', count: 11 },
];
</script>
```

### Icons and icon-only badges

Add `prepend:icon` / `append:icon` to a labelled badge, or `icon` for an
icon-only badge. `icon` takes precedence: when set, `prepend:icon` /
`append:icon` are ignored, and the default slot becomes the badge's visually
hidden accessible label — always supply it.

**Leading icon, trailing icon, and icon-only**

```vue
<div class="flex flex-wrap items-center gap-2">
	<BbBadge variant="primary" prepend:icon="lucide:credit-card">Paid</BbBadge>
	<BbBadge variant="outline" append:icon="lucide:arrow-right">Continue</BbBadge>
	<BbBadge variant="secondary" icon="lucide:badge-check">Verified</BbBadge>
</div>
```

### Loading state

Add `loading` to show a spinner on the badge. It takes the place of the
leftmost icon, the same convention as `BbButton`: it replaces the icon-only
glyph or the `prepend:icon`; when the `append:icon` is the _sole_ icon it
replaces that instead; and with no icons at all it occupies the leading slot.
Whichever slot it lands in, the swap is same-size, so nothing shifts. A
visually hidden loading announcement is added for screen readers.

The chevron swap is the signature use: a badge acting as a select activator
(e.g. an inline-editable table cell) shows the chevron at rest and the spinner
while the picked value saves.

**Where the spinner lands**

```vue
<div class="flex flex-wrap items-center gap-2">
	<BbBadge append:icon="lucide:chevron-down" variant="secondary">
		In progress
	</BbBadge>
	<BbBadge append:icon="lucide:chevron-down" loading variant="secondary">
		In progress
	</BbBadge>
	<BbBadge loading prepend:icon="lucide:credit-card" variant="outline">
		Paying
	</BbBadge>
	<BbBadge
		append:icon="lucide:chevron-down"
		loading
		prepend:icon="lucide:user"
		variant="secondary"
	>
		Both icons
	</BbBadge>
	<BbBadge loading variant="outline">Syncing</BbBadge>
	<BbBadge icon="lucide:badge-check" loading variant="secondary">
		Verifying
	</BbBadge>
</div>
```

### Removable tokens (`clearable`)

Add `clearable` to render a trailing clear button; the badge emits `click:clear`
when it's pressed. This is the dismissible-token pattern (an applied filter, a
selected value) — the badge is controlled, so remove the item from your own
state in the handler. Prefer `secondary` / `outline` for filter chips; reserve
`destructive` for tokens that already mean danger.

**Clearable badges across the variants**

```vue
<div class="flex flex-wrap items-center gap-2">
	<BbBadge clearable variant="primary">Primary</BbBadge>
	<BbBadge clearable variant="secondary">Secondary</BbBadge>
	<BbBadge clearable variant="destructive">Destructive</BbBadge>
	<BbBadge clearable variant="outline">Outline</BbBadge>
</div>
```

The clear button inherits the variant's foreground, so it reads on every surface
— light on a filled `primary`, dark on a `secondary`/`outline`. By default its
accessible name composes the localized verb with the badge's own text — a chip
reading "Italy" announces "Remove Italy", with no per-chip wiring. Set
`clearable-label` only when that composition is wrong for the context (it
replaces the whole name). With a `BbBadgeButton` body the composition is
skipped and the button falls back to the bare localized `badge.clearLabel`.

Icons combine with `clearable`: a **`prepend:icon`** stays (it leads the label);
an **`append:icon`** shares the trailing slot with the clear button — the icon
shows at rest and the clear button reveals over it on **hover/focus** (the same
swap the inputs use); and **`icon`** (icon-only) becomes a removable glyph.

**Clearable with icons (hover the middle one)**

```vue
<div class="flex flex-wrap items-center gap-2">
	<BbBadge clearable prepend:icon="lucide:tag" variant="secondary">Frontend</BbBadge>
	<BbBadge clearable append:icon="lucide:chevron-down" variant="secondary">Priority</BbBadge>
	<BbBadge clearable icon="lucide:user" variant="secondary">Ada Lovelace</BbBadge>
</div>
```

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.

**A removable filter bar**

```vue
<template>
	<div
		class="flex max-w-md flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex items-center justify-between gap-2">
			<p class="text-sm font-medium">Invoices</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">{{ resultLabel }}</p>
		</div>

		<div class="flex flex-wrap items-center gap-1.5">
			<span class="text-xs text-[color:var(--bb-text-muted)]">Filtered by</span>
			<BbBadge
				v-for="filter in filters"
				:key="filter.id"
				clearable
				:clearable-label="`Remove ${filter.label}`"
				:prepend:icon="filter.icon"
				size="lg"
				variant="secondary"
				@click:clear="onClear(filter.id)"
				>{{ filter.label }}</BbBadge
			>
			<BbButton
				v-if="filters.length"
				size="sm"
				variant="ghost"
				@click="onClearAll"
			>
				Clear all
			</BbButton>
			<BbButton v-else size="sm" variant="outline" @click="onReset">
				Restore filters
			</BbButton>
		</div>
	</div>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbBadge, BbButton } from 'bitboss-ui';
import type { IconType } from 'bitboss-ui';

type FilterChip = {
	id: string;
	label: string;
	icon: IconType;
};

const initial: FilterChip[] = [
	{ id: 'status', label: 'Status: Open', icon: 'lucide:circle-dot' },
	{ id: 'assignee', label: 'Assignee: Me', icon: 'lucide:user' },
	{ id: 'priority', label: 'Priority: High', icon: 'lucide:flag' },
];

const filters = ref<FilterChip[]>([...initial]);

const resultLabel = computed(() =>
	filters.value.length
		? `${filters.value.length} active filter${filters.value.length === 1 ? '' : 's'}`
		: 'Showing all invoices'
);

/** Drop one chip; the badge is controlled, so state lives here. */
const onClear = (id: string) => {
	filters.value = filters.value.filter((filter) => filter.id !== id);
};

const onClearAll = () => {
	filters.value = [];
};

const onReset = () => {
	filters.value = [...initial];
};
</script>
```

### Interactive badges (`BbBadgeButton`)

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>`:

**A clickable pill**

```vue
<div class="flex flex-wrap items-center gap-2">
	<BbBadge variant="secondary">
		<BbBadgeButton @click="() => {}">Assign reviewer</BbBadgeButton>
	</BbBadge>
	<BbBadge prepend:icon="lucide:filter" variant="outline">
		<BbBadgeButton @click="() => {}">Status: open</BbBadgeButton>
	</BbBadge>
</div>
```

The companion owns the element, so **everything binds where you'd expect**:
attributes and listeners (`@click`, `disabled`, `aria-pressed`, `data-*`) land
on the button, a template `ref` resolves to it (so it works directly as a
popover/tooltip anchor), and directives apply to it.

Three structural rules follow from the takeover:

- **The badge's icons move inside the button.** `prepend:icon`, `icon` and the
  `loading` spinner render within the hit target, so clicking the icon fires the
  action — they are part of the control, not decoration beside it.
- **The label is the companion's slot**, not the badge's. Write
  `<BbBadge><BbBadgeButton>Text</BbBadgeButton></BbBadge>`, not both.
- **`append:icon` and the clear button stay outside** it, on the badge's
  trailing side. That is what keeps `clearable` compatible (below).

#### Full `BbBaseButton` parity

`BbBadgeButton` composes `BbBaseButton`, so the badge body accepts that
component's whole prop surface: `href` / `to` (rendering an `<a>` or
router-link), the Inertia visit options, `target` / `rel` / `download`,
`active-class`, `disabled`, `type`, and `tag`. Only `block` (meaningless on an
inline pill) and `text` (the label comes from the slot) are excluded.

**Badges that navigate**

```vue
<div class="flex flex-wrap items-center gap-2">
	<BbBadge prepend:icon="lucide:external-link" variant="outline">
		<BbBadgeButton href="https://example.com" target="_blank" rel="noopener">
			Docs
		</BbBadgeButton>
	</BbBadge>
	<BbBadge prepend:icon="lucide:link" variant="secondary">
		<BbBadgeButton href="#anchor">Jump to section</BbBadgeButton>
	</BbBadge>
	<BbBadge variant="secondary">
		<BbBadgeButton disabled href="https://example.com">Unavailable</BbBadgeButton>
	</BbBadge>
</div>
```

A `disabled` link renders the `<a>` without an `href`, so it can't be
activated — the same rule `BbBaseButton` applies everywhere.

#### Clickable **and** removable

Because the clear control is a sibling of the body rather than nested inside
it, the two compose — this is the classic filter chip: press the body to edit,
press the × to remove. The two actions are two tab stops, which is correct.

**The filter-chip pattern**

```vue
<div class="flex flex-wrap items-center gap-2">
	<BbBadge clearable prepend:icon="lucide:tag" size="xl" variant="secondary">
		<BbBadgeButton @click="() => {}">Label: frontend</BbBadgeButton>
	</BbBadge>
	<BbBadge clearable append:icon="lucide:chevron-down" size="xl" variant="secondary">
		<BbBadgeButton @click="() => {}">Priority: high</BbBadgeButton>
	</BbBadge>
</div>
```

Clicking the clear button never fires the body's `@click`.

#### Icon-only, interactive

With `icon`, the glyph and the visually hidden label both move inside the
button — so the slot text becomes the button's accessible name. Never leave it
empty here: an icon-only interactive badge with no label is an unnamed control.

**An icon-only action pill**

```vue
<BbBadge icon="lucide:bell" variant="outline">
	<BbBadgeButton @click="() => {}">Notification settings</BbBadgeButton>
</BbBadge>
```

#### As a popover activator

A template ref on `BbBadgeButton` resolves to the rendered element, so it can
anchor an overlay directly — no wrapper element, no `defineExpose`:

**A badge that opens a popover**

```vue
<template>
	<div
		class="flex max-w-sm flex-wrap items-center gap-2 rounded-[var(--bb-radius)] border p-3"
	>
		<span class="text-xs text-[color:var(--bb-text-muted)]">Filters</span>

		<BbBadge
			append:icon="lucide:chevron-down"
			clearable
			clearable-label="Remove status filter"
			prepend:icon="lucide:circle-dot"
			size="lg"
			variant="secondary"
			@click:clear="status = 'Open'"
		>
			<BbBadgeButton ref="statusChip">Status: {{ status }}</BbBadgeButton>
		</BbBadge>

		<!-- The ref resolves to the rendered button element, so it anchors the
		popover directly — no wrapper, no imperative handle. -->
		<BbPopover v-model="open" :activator="statusChip" placement="bottom-start">
			<div class="flex min-w-36 flex-col p-1">
				<BbButton
					v-for="option in options"
					:key="option"
					size="sm"
					variant="ghost"
					@click="onPick(option)"
					>{{ option }}</BbButton
				>
			</div>
		</BbPopover>
	</div>
</template>

<script setup lang="ts">
import { ref, useTemplateRef } from 'vue';
import { BbBadge, BbBadgeButton, BbButton, BbPopover } from 'bitboss-ui';

const options = ['Open', 'In review', 'Done'] as const;
type Status = (typeof options)[number];

const status = ref<Status>('Open');
const open = ref(false);
const statusChip = useTemplateRef('statusChip');

const onPick = (option: Status) => {
	status.value = option;
	open.value = false;
};
</script>
```

### Sizes

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.

**The size scale**

```vue
<div class="flex flex-wrap items-center gap-3">
	<BbBadge size="xs" variant="destructive">9</BbBadge>
	<BbBadge size="sm" variant="destructive">9</BbBadge>
	<BbBadge size="md" variant="destructive">9</BbBadge>
	<BbBadge size="lg" variant="destructive">9</BbBadge>
	<BbBadge size="xl" variant="destructive">9</BbBadge>
	<BbBadge size="2xl" variant="destructive">9</BbBadge>
</div>
```

### One-off colors

There is no `color` prop. To paint a single badge outside the variant system,
override the CSS custom properties the variants drive — `--bg` for the
background, `--color` for the text — inline:

**A one-off accent via the --bg token**

```vue
<div class="flex flex-wrap items-center gap-2">
	<BbBadge variant="primary" :style="{ '--bg': '#16a34a' }">Sales</BbBadge>
	<BbBadge variant="primary" :style="{ '--bg': '#7c3aed' }">Design</BbBadge>
</div>
```

Pair a dark custom `--bg` with a light-text variant (`primary`), or set
`--color` too, and check contrast yourself. For anything recurring, register a
variant instead so the styling stays in the design system.

### Anatomy and CSS hooks

A badge renders two sides inside the pill wrapper, which is what lets the body
and the clear control be independent controls:

```html
<span class="bb-badge bb-badge--md bb-badge--secondary">
	<span class="bb-badge__body">
		<!-- <button>/<a> in button mode -->
		<svg class="bb-badge__prepend-icon" />
		<!-- or __icon / BbSpinner -->
		<span class="bb-badge__content">label</span>
	</span>
	<span class="bb-badge__trailing">
		<!-- only when needed -->
		<svg class="bb-badge__append-icon" />
		<button class="bb-badge__clear-button">…</button>
	</span>
</span>
```

Both sides carry the pill's radius and inline padding, so each hit area runs
**flush to the border** — clicking the extreme left edge presses the body, the
extreme right edge presses the clear. The clear button's hit region spans the
full pill height even though only the glyph's circle looks interactive.

Focus is always ringed on the **whole pill** (never on the inner control), for
the body and the clear button alike; the clear button additionally lights its
glyph. The class hooks above are the supported styling surface —
`.bb-badge__body` and `.bb-badge__trailing` are new, so avoid direct-child
selectors like `.bb-badge > .bb-badge__content`, which no longer match.

### Works well with

- `BbBadgeButton` — the companion that makes the badge body a real button/link.
- `BbIndicator` — the anchored sibling: counts and dots pinned over a bell,
  button, or avatar.
- `BbTable` / `BbTabs` — standalone badges as status pills in cells and tab
  labels.
- `BbSelect` / `ChipsBox` — a `clearable` `secondary` badge is exactly how
  multi-selects render their removable selections.
- `BbPopover` / `BbDropdown` — a `BbBadgeButton` ref is a ready-made activator
  for an inline-edit chip.

### Gotchas & anti-patterns

- 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.
- 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`).
- Don't nest your own `<button>`/`<a>` in a badge's default slot to make it
  clickable — with `clearable` that's invalid markup (a `<button>` may not
  contain interactive content). That's precisely what `BbBadgeButton` exists to
  solve.
- To pin a marker over another element (notification dot/count), use
  `BbIndicator`, not a badge.
- No `max`/overflow prop: format big counts yourself (`99+`).

### Accessibility

- A plain badge is inline text to assistive tech (no live region) — fine for
  static pills. For an announced dynamic count pinned to a control, use
  `BbIndicator` (which is a `role="status"` live region).
- An icon-only badge (`icon`) has no visible text; the default slot is rendered
  as a screen-reader-only label — never leave it empty. In button mode that
  label is also the **button's accessible name**, so it is doubly required.
- The `clearable` button's accessible name is composed by default: the
  localized `badge.clearLabel` verb plus the badge body's text ("Remove
  Italy"). `clearable-label` replaces the whole name; with a `BbBadgeButton`
  body the composition is skipped (bare verb only).
- A clickable **and** clearable badge is two tab stops (body, then clear). That
  is intended: two actions, two controls.
- Keyboard focus on either control rings the whole pill, so the focused target
  is visible at pill scale rather than as a ring around a 12px glyph.
- Prefer a registered `variant` over a one-off inline `--bg`; a bare color
  carries no semantic meaning and no guaranteed contrast.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `append:icon` | `string \| undefined` |  |  | Icon rendered after the label. On a `clearable` badge it shares the trailing slot with the clear button: the icon shows at rest and the clear button reveals over it on hover/focus. |
| `clearable` | `boolean \| undefined` | `false` |  | Renders a trailing clear button and emits `click:clear` when pressed — turns the badge into a dismissible token (the pattern formerly served by `BbChip`). |
| `clearableLabel` | `string \| undefined` |  |  | Accessible label for the clear button. Rarely needed: unset, the name is **composed** from the localized `badge.clearLabel` verb and the badge's own text — "Remove Italy", not a bare "Remove" — which is already the right name in almost ever… |
| `icon` | `string \| undefined` |  |  | Renders an icon-only badge. When set, `prepend:icon` / `append:icon` are ignored and the default slot becomes the badge's visually hidden accessible label — always provide it. |
| `loading` | `boolean \| undefined` | `false` |  | Shows a spinner in place of the leftmost icon, mirroring `BbButton`: it replaces the `icon` glyph or the `prepend:icon` when one is set; when the `append:icon` is the sole icon it replaces that instead (e.g. a select-activator chevron while… |
| `prepend:icon` | `string \| undefined` |  |  | Icon rendered before the label. |
| `size` | `keyof Sizes \| undefined` | `"md"` |  | Preset size of the badge. |
| `variant` | `keyof BadgeVariantRegistry \| undefined` | `"primary"` |  | Visual variant: `primary`, `secondary`, `destructive`, or `outline`. Register more via the vite plugin `badgeVariants` option and style `.bb-badge--<variant>` (set `--bg` / `--color`). |

## Events

- `click:clear` — `(event: "click:clear", event: MouseEvent): void`

## Slots

- `default` — scope: `object` — The badge's label content. When `icon` is set this becomes the visually hidden accessible label. Render a `BbBadgeButton` here to make the badge body interactive (the wrapper stays a passive `<span>`).

## See Also

- [BbIndicator](./BbIndicator.md) — Anchors a notification bubble (count/short text) or a dot over a wrapped element.
- [BbAvatar](./BbAvatar.md) — Displays an avatar and has a fallback content slot.
- [BbBadgeButton](./BbBadgeButton.md) — Makes a badge's body interactive: slotted as a direct child of BbBadge it renders the badge body as a real button/link with full BbBaseButton parity, leaving `clearable` free to remain a separate control.

---

<!-- dist/ai/BbBadgeButton.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBadgeButton.md -->

# BbBadgeButton

## Agent Contract

- Safety level: **Consumer API**
- Group: **Feedback**
- Description: Makes a badge's body interactive: slotted as a direct child of BbBadge it renders the badge body as a real button/link with full BbBaseButton parity, leaving `clearable` free to remain a separate control.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbBadgeButton.md](./source/BbBadgeButton.md)

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `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. |
| `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 in… |
| `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. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables user interaction. - When rendering as a native button, sets the `disabled` attribute. - When rendering as a link (anchor/Inertia), removes `href`, adds `aria-disabled="true"`, and prevents navigation while keeping focusable semanti… |
| `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 (including same-origin, `blob:` and `data:` URLs) work. Pass a string to set the suggested file… |
| `exactActiveClass` | `string \| undefined` | `'router-link-exact-active'` |  | CSS class applied when the component renders as a link and the target of the link and the url matches exactly. Ported for Inertia compatibility. |
| `except` | `string[] \| undefined` |  |  | Inertia: the inverse of `only` — properties to EXCLUDE from a partial reload. Pass one or the other, not both. |
| `external` | `boolean \| undefined` | `false` |  | Forces an `href` link to render as a plain `<a>` (native navigation), bypassing Inertia/router interception — the same intent as Nuxt's `NuxtLink` `external`. Use for links outside the SPA. One of the native-anchor signals alongside `target… |
| `headers` | `object \| undefined` |  |  | Additional HTTP headers forwarded to Inertia when navigating via `href` in an Inertia-enabled app. |
| `href` | `string \| undefined` |  |  | Hyperlink reference used when rendering as an anchor (or as an Inertia link in Inertia-enabled apps). If provided and not disabled, the component renders as an anchor/Inertia link. |
| `instant` | `boolean \| undefined` | `false` |  | Inertia: navigate optimistically on click and reconcile when the response lands, instead of waiting for the round trip. |
| `method` | `"get" \| "post" \| "put" \| "patch" \| "delete" \| undefined` |  |  | HTTP method used for Inertia navigation when `href` is provided in an Inertia-enabled app. Ignored otherwise. |
| `onBefore` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia right before the request is sent. |
| `onCancel` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request is cancelled. |
| `onCancelToken` | `((cancelToken: unknown) => void) \| undefined` |  |  | Receives the Inertia cancel token source when a request is initiated. Can be used to cancel the request. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be installed. |
| `onError` | `((errors: Record<string, string>) => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when the server responds with VALIDATION errors — the ordinary 422 path. This is the only failure callback Inertia's `Link` accepts. `onHttpException` (server answered 5xx) and `onNetworkError` (the request… |
| `onFinish` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia after the request has finished (regardless of success or error). |
| `only` | `string[] \| undefined` |  |  | Limits the properties that are preserved in Inertia partial reloads. |
| `onPrefetched` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a prefetch for this link has completed and is cached. |
| `onPrefetching` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a prefetch for this link starts. |
| `onProgress` | `((progress: { percentage: number \| undefined; }) => void) \| undefined` |  |  | Progress callback invoked by Inertia with the upload/download percentage when available. |
| `onStart` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request starts. |
| `onSuccess` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request succeeds. |
| `pageProps` | `Record<string, unknown> \| ((currentProps: Record<string, unknown>, sharedProps: Record<string, unknown>) => Record<string, unknown>) \| null \| undefined` |  |  | Inertia: props to merge into the next page optimistically, before the server responds. Either an object or a function of the current props. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue… |
| `prefetch` | `string \| boolean \| string[] \| undefined` |  |  | Inertia: fetch and cache this link's page ahead of the click. `true` uses the default trigger; a string or list of strings picks them (`'mount'`, `'hover'`, `'click'`). |
| `preserveScroll` | `boolean \| ((props: Record<string, unknown>) => boolean) \| undefined` | `false` |  | Controls whether Inertia should preserve the current scroll position after navigation. Can be a boolean or a predicate receiving the visit props. |
| `preserveState` | `boolean \| ((props: Record<string, unknown>) => boolean) \| null \| undefined` | `false` |  | Controls whether Inertia should preserve the current state after navigation. Can be a boolean or a predicate receiving the visit props. |
| `preserveUrl` | `boolean \| undefined` | `false` |  | Inertia: keep the current URL in the address bar even though the page content changes. |
| `queryStringArrayFormat` | `"brackets" \| "indices" \| undefined` | `'brackets'` |  | Format to use when serializing array values into the query string for Inertia requests. |
| `rel` | `string \| undefined` |  |  | Relationship between the current document and the linked resource. Useful for security when opening new tabs (e.g. `noopener noreferrer`). |
| `replace` | `boolean \| undefined` | `false` |  | Uses history replacement instead of push navigation. - With Vue Router (`to`), calls `router.replace`. - With Inertia (`href`), performs a replace visit. |
| `tag` | `ButtonTag \| undefined` | `'button'` |  | Element to render for the plain (non-link, non-router) button: - `'button'` (default) — real button semantics and keyboard behavior - `'div'` / `'span'` — a clickable box nested inside another button or link, where a nested `<button>` would… |
| `target` | `string \| undefined` |  |  | Target browsing context for anchor/Inertia links (e.g. `_self`, `_blank`). Ignored when rendering as a native button. |
| `to` | `string \| wt \| bt \| undefined` |  |  | Route location to navigate to. When provided (and not disabled), the component renders as a Vue Router link. |
| `type` | `"button" \| "submit" \| "reset" \| undefined` | `'button'` |  | Native `type` attribute used when rendering as a button (e.g. `button`, `submit`, `reset`). |
| `viewTransition` | `boolean \| undefined` | `false` |  | Inertia: run the page swap inside a View Transition, where the browser supports one. |

## Events

- None.

## Slots

- `default` — scope: `object` — The action's label — what the badge displays as its body.

## See Also

- [BbBadge](./BbBadge.md) — Displays a compact inline status counter or label. It sits in the flow — for a bubble or dot anchored OVER another element, use BbIndicator (includes the co-located BbBadgeButton export).
- [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.

---

<!-- dist/ai/BbBaseButton.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseButton.md -->

# BbBaseButton

## Agent Contract

- Safety level: **Consumer API**
- Group: **Inputs**
- Description: 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.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbBaseButton.md](./source/BbBaseButton.md)

## Usage & Guidelines

### When to use

`BbBaseButton` is a first-class component, not an internal detail. It does two
things and nothing else: it **resolves the right element** (native `<button>`,
`<a>`, or a router link) and it runs the **navigation engine** (`href`/`to`,
Inertia visits, active classes) — with **no visual styling** of its own.

Split the two button components by nature:

- **`BbButton`** — the self-contained, **variant-first** button: a discrete,
  recognizable button/link with `primary`/`outline`/`ghost`/… chrome, sizes,
  loading and icons baked in. Use it when you want _a button that looks like a
  button_.
- **`BbBaseButton`** — **any other clickable or navigable surface**, especially
  when it must navigate. Reach for it whenever the thing you're making is _not_ a
  variant button:
  - a rich clickable region — a card, a list row, a tile, a media thumbnail —
    that should be one real navigable element;
  - a bespoke link or button whose look comes entirely from your own CSS /
    design system, not from a `BbButton` variant;
  - any "random" clickable that needs correct navigation (`href`/`to`, Inertia,
    active state) but no button styling.

Rule of thumb: **if it navigates and it isn't a `BbButton` variant, it's a
`BbBaseButton`** — don't wrap your own `@click`/`router.push` around a plain
`<div>` or `<a>`. `BbButton` itself is built on this primitive, and the
dropdown, breadcrumb and tab items reuse the very same navigation prop surface.

### What it renders — element resolution

The one feature to understand. `BbBaseButton` picks its element from the props,
in this priority order:

1. **Router link** — when `to` is set, or an internal (same-origin) `href` is set
   in an Inertia app without a `target`. Renders `RouterLink` (Vue Router),
   `NuxtLink` (Nuxt), or the Inertia `Link` — resolved for you from the active
   framework.
2. **Anchor `<a>`** — when `href` is set but the above doesn't apply: external or
   cross-origin URLs, any `href` with a `target`, or a disabled `to` link (kept
   as an anchor for correct link semantics).
3. **Native `<button>`** — the default when there is no `href`/`to`. Polymorphic
   via `tag` (below), but a real `<button>` unless you say otherwise.

You never toggle this by hand — pass the navigation intent and the element
follows. The example below renders a `<button>`, an `<a href>`, and an
`<a href target="_blank">` from three prop shapes (all Tailwind-styled, since the
primitive brings no look of its own):

**Same component, three elements**

```vue
<template>
	<div class="flex flex-wrap items-center gap-2 text-sm">
		<!-- No href/to → a native <button>. -->
		<BbBaseButton
			class="rounded-[var(--bb-radius)] bg-[var(--bb-primary)] px-3 py-1.5 text-[var(--bb-primary-fg)]"
			@click="pinged = true"
		>
			Native button
		</BbBaseButton>
		<!-- Same-origin href → an <a>. -->
		<BbBaseButton
			class="rounded-[var(--bb-radius)] px-3 py-1.5 text-[color:var(--bb-primary)] underline"
			href="#docs"
		>
			Anchor link
		</BbBaseButton>
		<!-- href + target → a plain <a target="_blank"> with rel secured. -->
		<BbBaseButton
			class="rounded-[var(--bb-radius)] px-3 py-1.5 underline"
			href="https://example.com"
			target="_blank"
		>
			External ↗
		</BbBaseButton>
		<span class="text-xs text-[color:var(--bb-text-muted)]">{{
			pinged ? 'button clicked' : ''
		}}</span>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbBaseButton } from 'bitboss-ui';

const pinged = ref(false);
</script>
```

### It ships no chrome — you style it

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
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
link chrome is neutralized so it inherits too). Give it a class (your own, or
Tailwind utilities) and it looks like whatever you draw. This is what makes it
the right base for a clickable card or a bespoke nav item:

**From bare to branded**

```vue
<div class="flex items-center gap-2 text-sm">
	<!-- Untouched: just text with the reset + focus scaffold. -->
	<BbBaseButton href="#a">Bare</BbBaseButton>
	<!-- Styled entirely by utility classes — neutral hover chrome. -->
	<BbBaseButton
		href="#b"
		class="rounded-[var(--bb-radius)] border border-[var(--bb-border)] px-3 py-1 font-medium hover:bg-[color:var(--bb-hover)]"
	>
		Branded pill
	</BbBaseButton>
</div>
```

A whole card as a single navigable element — the primitive's signature use:

**A clickable card built on the primitive**

```vue
<template>
	<div class="grid max-w-md gap-2 sm:grid-cols-2">
		<!-- The whole card is ONE navigable element — a BbBaseButton rendered as an
		     anchor, styled entirely by these utility classes. No wrapper <a>, no
		     @click; navigation rides on `href` (a `to`/Inertia target works the same). -->
		<BbBaseButton
			v-for="project in projects"
			:key="project.name"
			class="project-card flex flex-col items-start gap-1.5 rounded-[var(--bb-radius)] border border-[var(--bb-border)] bg-[var(--bb-panel)] p-3 text-left hover:bg-[color:var(--bb-surface-hover)]"
			:href="project.href"
		>
			<span class="flex w-full items-center justify-between gap-2">
				<span
					class="flex size-7 shrink-0 items-center justify-center rounded-[var(--bb-radius-sm)] bg-[color:var(--bb-muted)] text-[color:var(--bb-text-muted)]"
				>
					<BbIcon :icon="project.icon" size="sm" />
				</span>
				<BbBadge variant="secondary">{{ project.status }}</BbBadge>
			</span>
			<span class="text-sm font-medium">{{ project.name }}</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">{{
				project.meta
			}}</span>
		</BbBaseButton>
	</div>
</template>

<script setup lang="ts">
import { BbBaseButton, BbBadge, BbIcon } from 'bitboss-ui';

type Project = {
	name: string;
	meta: string;
	status: string;
	icon: 'lucide:receipt' | 'lucide:folder-kanban';
	href: string;
};

const projects: Project[] = [
	{
		name: 'Northwind Billing',
		meta: '12 open invoices · updated Jul 18',
		status: 'Active',
		icon: 'lucide:receipt',
		href: '#northwind-billing',
	},
	{
		name: 'Acme Studio',
		meta: '3 members · updated Jul 12',
		status: 'Paused',
		icon: 'lucide:folder-kanban',
		href: '#acme-studio',
	},
];
</script>

<style scoped>
/* Visible focus uses the base ring scaffold (box-shadow / --bb-ring). */
.project-card:focus-visible {
	box-shadow: 0 0 0 var(--bb-ring-size) var(--bb-ring);
}
</style>
```

### Label

Same as `BbButton`: **prefer the default slot** (`<BbBaseButton>Label</BbBaseButton>`);
the `text` prop is a string-only fallback for `:items`-style loops that spread a
config object. Slot content wins when both are present.

### Navigation

This is where the library's navigation surface actually lives — `BbButton` and
the item-driven components just forward to it. Push any click whose result is a
destination onto these props instead of an `@click` handler:

- **`href`** — renders an `<a>`; in an Inertia app a same-origin `href` (no
  `target`) upgrades to an Inertia visit. `target` forces a plain anchor, and
  any target other than `_self` (`_blank`, named windows, …) automatically
  merges `noopener noreferrer` into `rel`.
- **`to`** — a Vue Router `RouteLocationRaw`, rendered as a router/Nuxt link.
- **`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:

```vue
<!-- Vue Router / Nuxt -->
<BbBaseButton
	:to="{ name: 'invoices.show', params: { id } }"
>Open</BbBaseButton>

<!-- Inertia: href becomes a visit; options ride along as props -->
<BbBaseButton
	href="/invoices"
	method="post"
	:data="{ customerId }"
	preserve-scroll
	:on-success="() => drawer.close()"
>
	Create invoice
</BbBaseButton>
```

#### Active state

When a link points at the current location the component adds a **class name** to
the element — a hook you style; it applies no styling itself. `active-class` is
added on a path-prefix match, `exact-active-class` on an exact match (defaults
`router-link-active` / `router-link-exact-active`, or the plugin's
`linkActiveClass` / `linkExactActiveClass`). Matching is native under Vue Router
(`to`), and ported by the library for `href` links — against the Inertia page
under Inertia, or `window.location` in a plain app. On every platform the
exact-active link also gets `aria-current` (default `page`, tune
with `aria-current-value`). The [`BbButton` active-state
section](./BbButton.md) covers the matching rules in depth.

Because the primitive attaches only the class name, an unstyled nav item is a
two-line affair: name the hook with `exact-active-class` (or `active-class` for
a section link that should stay lit on child pages) and write the CSS yourself.
The classic home for this is a settings sidebar — every item is a bare
`BbBaseButton`, and the one pointing at the current page lights up:

**Settings sidebar with an active nav item**

```vue
<template>
	<nav
		aria-label="Settings"
		class="grid w-full max-w-xs gap-0.5 rounded-[var(--bb-radius)] border border-[var(--bb-border)] bg-[var(--bb-panel)] p-1.5"
	>
		<!-- Each nav item is a bare BbBaseButton: element resolution and active
		     matching come from the primitive, the entire look comes from these
		     classes. `exact-active-class` names the hook; the scoped style below
		     decides what "active" looks like. -->
		<BbBaseButton
			v-for="item in items"
			:key="item.label"
			block
			class="settings-nav-item flex items-center gap-2 rounded-[var(--bb-radius-sm)] px-2 py-1.5 text-left text-sm text-[color:var(--bb-text-muted)] hover:bg-[color:var(--bb-hover)] hover:text-[color:var(--bb-text)]"
			exact-active-class="settings-nav-active"
			:href="item.href"
		>
			<BbIcon :icon="item.icon" size="sm" />
			{{ item.label }}
		</BbBaseButton>
	</nav>
</template>

<script setup lang="ts">
import { BbBaseButton, BbIcon } from 'bitboss-ui';

type NavItem = {
	label: string;
	icon:
		| 'lucide:settings'
		| 'lucide:users'
		| 'lucide:credit-card'
		| 'lucide:key-round';
	href: string;
};

// This demo runs router-free, so the matcher compares each href against
// `window.location` — exactly what the library does in a plain app. "General"
// points at the page you are viewing right now, so it is the exact-active
// link; in your app the items would be real sibling paths
// ('/settings', '/settings/members', …). The hash hrefs keep the preview from
// navigating — fragment-only links are same-page by definition, so the
// matcher deliberately never marks them active.
const here =
	typeof window !== 'undefined' ? window.location.pathname : '/settings';

const items: NavItem[] = [
	{ label: 'General', icon: 'lucide:settings', href: here },
	{ label: 'Members', icon: 'lucide:users', href: '#members' },
	{ label: 'Billing', icon: 'lucide:credit-card', href: '#billing' },
	{ label: 'API keys', icon: 'lucide:key-round', href: '#api-keys' },
];
</script>

<style scoped>
/* Nothing highlights until you style the class the component attached. */
.settings-nav-active {
	background: var(--bb-muted);
	color: var(--bb-text);
	font-weight: 500;
}

.settings-nav-item:focus-visible {
	box-shadow: 0 0 0 var(--bb-ring-size) var(--bb-ring);
}
</style>
```

#### Disabled links

`disabled` adapts to the element. On a native button it sets the `disabled`
attribute. On a link it keeps the element in place but strips navigation: the
`href` is dropped and it renders `role="link"`, `aria-disabled="true"`,
`tabindex="-1"` — focus-inert and unfollowable, without collapsing the layout.

**Disabled adapts to button vs link**

```vue
<div class="flex items-center gap-2 text-sm">
	<BbBaseButton
		disabled
		class="rounded-[var(--bb-radius)] bg-[var(--bb-primary)] px-3 py-1.5 text-[var(--bb-primary-fg)] opacity-50"
	>
		Disabled button
	</BbBaseButton>
	<BbBaseButton disabled href="#nope" class="px-3 py-1.5 underline opacity-50">
		Disabled link
	</BbBaseButton>
</div>
```

### The plain element: tag, type and block

When it renders as a native button you can retune the element:

- **`tag`** — render the plain (non-link) case as `button` (default), `div`,
  `span` or `label`, for contexts where a `<button>` is invalid (e.g. nested
  inside another interactive element, or a clickable `<label>` wrapping a hidden
  file input). A non-`button` tag **drops the native `type`/`disabled`
  attributes** (invalid there) — disabled state is then conveyed only by the
  `bb-base-button--disabled` class, and you lose native keyboard/focus semantics,
  so keep the default `<button>` unless you truly can't.
- **`type`** — the native button type (`button` default, `submit`, `reset`).
  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.

**Submit type and block width**

```vue
<template>
	<form
		class="grid max-w-xs gap-2 rounded-[var(--bb-radius)] border border-[var(--bb-border)] bg-[var(--bb-panel)] p-3"
		@submit.prevent="sent = true"
	>
		<p class="text-sm font-medium">New workspace</p>
		<p class="text-xs text-[color:var(--bb-text-muted)]">
			{{
				sent
					? 'Submitted via the native form event.'
					: 'Submits the form — the default type="button" never would.'
			}}
		</p>
		<BbBaseButton
			block
			class="rounded-[var(--bb-radius)] bg-[var(--bb-primary)] px-3 py-1.5 text-sm text-[var(--bb-primary-fg)]"
			type="submit"
		>
			Create workspace
		</BbBaseButton>
	</form>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbBaseButton } from 'bitboss-ui';

const sent = ref(false);
</script>
```

### Works well with

- [`BbButton`](./BbButton.md) — the variant-first sibling built on this
  primitive (variants, sizes, loading, toggle, icons). Use it when you want a
  discrete button; use `BbBaseButton` for every other clickable surface.
- [`BbDropdown`](./BbDropdown.md) / [`BbBreadcrumbs`](./BbBreadcrumbs.md) /
  [`BbTabs`](./BbTabs.md) — their items expose this same navigation prop surface,
  so links there behave exactly like a `BbBaseButton`.
- Your design system — when a control must look nothing like `BbButton`, build it
  on `BbBaseButton` to inherit correct element resolution, link semantics and
  active state for free.

### Gotchas & anti-patterns

- Don't use it just to get a plain-looking **standalone** button among other
  buttons — that's `variant="ghost"` / `variant="link"` on `BbButton`. But **do**
  use it for an **inline** link — a record-identity cell, an in-text link, a
  property-grid value: `variant="link"` keeps the button box (height + padding)
  and breaks the line, whereas `BbBaseButton` + your own link class (e.g.
  `.plain-link`) flows inline. Reach for the base to escape button chrome
  entirely — including whenever the link must sit inline in text.
- `to` and Inertia links need their framework present; without a router a `to`
  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.

### Accessibility

- **Element choice carries the semantics** — a real `<button>` and a real `<a>`
  come with the correct role, keyboard behavior and focus for free. Preserve them
  by keeping `href`/`to` for navigation and the default tag for actions.
- **Disabled links** render `role="link"`, `aria-disabled="true"`, no `href`, and
  leave the tab order — communicated to assistive tech without vanishing.
- **Exact-active** links expose `aria-current` (default `page`) on every
  platform — Vue Router, Inertia, and plain apps.
- **Any `target` other than `_self`** (`_blank`, named windows, …) is secured
  with `rel="noopener noreferrer"` automatically.
- **Provide a visible focus style** and, if you use a non-`button` `tag`, restore
  the keyboard interaction the native element would have given you.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `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. |
| `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 in… |
| `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. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables user interaction. - When rendering as a native button, sets the `disabled` attribute. - When rendering as a link (anchor/Inertia), removes `href`, adds `aria-disabled="true"`, and prevents navigation while keeping focusable semanti… |
| `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 (including same-origin, `blob:` and `data:` URLs) work. Pass a string to set the suggested file… |
| `exactActiveClass` | `string \| undefined` | `'router-link-exact-active'` |  | CSS class applied when the component renders as a link and the target of the link and the url matches exactly. Ported for Inertia compatibility. |
| `except` | `string[] \| undefined` |  |  | Inertia: the inverse of `only` — properties to EXCLUDE from a partial reload. Pass one or the other, not both. |
| `external` | `boolean \| undefined` | `false` |  | Forces an `href` link to render as a plain `<a>` (native navigation), bypassing Inertia/router interception — the same intent as Nuxt's `NuxtLink` `external`. Use for links outside the SPA. One of the native-anchor signals alongside `target… |
| `headers` | `object \| undefined` |  |  | Additional HTTP headers forwarded to Inertia when navigating via `href` in an Inertia-enabled app. |
| `href` | `string \| undefined` |  |  | Hyperlink reference used when rendering as an anchor (or as an Inertia link in Inertia-enabled apps). If provided and not disabled, the component renders as an anchor/Inertia link. |
| `instant` | `boolean \| undefined` | `false` |  | Inertia: navigate optimistically on click and reconcile when the response lands, instead of waiting for the round trip. |
| `method` | `"get" \| "post" \| "put" \| "patch" \| "delete" \| undefined` |  |  | HTTP method used for Inertia navigation when `href` is provided in an Inertia-enabled app. Ignored otherwise. |
| `onBefore` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia right before the request is sent. |
| `onCancel` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request is cancelled. |
| `onCancelToken` | `((cancelToken: unknown) => void) \| undefined` |  |  | Receives the Inertia cancel token source when a request is initiated. Can be used to cancel the request. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be installed. |
| `onError` | `((errors: Record<string, string>) => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when the server responds with VALIDATION errors — the ordinary 422 path. This is the only failure callback Inertia's `Link` accepts. `onHttpException` (server answered 5xx) and `onNetworkError` (the request… |
| `onFinish` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia after the request has finished (regardless of success or error). |
| `only` | `string[] \| undefined` |  |  | Limits the properties that are preserved in Inertia partial reloads. |
| `onPrefetched` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a prefetch for this link has completed and is cached. |
| `onPrefetching` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a prefetch for this link starts. |
| `onProgress` | `((progress: { percentage: number \| undefined; }) => void) \| undefined` |  |  | Progress callback invoked by Inertia with the upload/download percentage when available. |
| `onStart` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request starts. |
| `onSuccess` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request succeeds. |
| `pageProps` | `Record<string, unknown> \| ((currentProps: Record<string, unknown>, sharedProps: Record<string, unknown>) => Record<string, unknown>) \| null \| undefined` |  |  | Inertia: props to merge into the next page optimistically, before the server responds. Either an object or a function of the current props. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue… |
| `prefetch` | `string \| boolean \| string[] \| undefined` |  |  | Inertia: fetch and cache this link's page ahead of the click. `true` uses the default trigger; a string or list of strings picks them (`'mount'`, `'hover'`, `'click'`). |
| `preserveScroll` | `boolean \| ((props: Record<string, unknown>) => boolean) \| undefined` | `false` |  | Controls whether Inertia should preserve the current scroll position after navigation. Can be a boolean or a predicate receiving the visit props. |
| `preserveState` | `boolean \| ((props: Record<string, unknown>) => boolean) \| null \| undefined` | `false` |  | Controls whether Inertia should preserve the current state after navigation. Can be a boolean or a predicate receiving the visit props. |
| `preserveUrl` | `boolean \| undefined` | `false` |  | Inertia: keep the current URL in the address bar even though the page content changes. |
| `queryStringArrayFormat` | `"brackets" \| "indices" \| undefined` | `'brackets'` |  | Format to use when serializing array values into the query string for Inertia requests. |
| `rel` | `string \| undefined` |  |  | Relationship between the current document and the linked resource. Useful for security when opening new tabs (e.g. `noopener noreferrer`). |
| `replace` | `boolean \| undefined` | `false` |  | Uses history replacement instead of push navigation. - With Vue Router (`to`), calls `router.replace`. - With Inertia (`href`), performs a replace visit. |
| `tag` | `ButtonTag \| undefined` | `'button'` |  | Element to render for the plain (non-link, non-router) button: - `'button'` (default) — real button semantics and keyboard behavior - `'div'` / `'span'` — a clickable box nested inside another button or link, where a nested `<button>` would… |
| `target` | `string \| undefined` |  |  | Target browsing context for anchor/Inertia links (e.g. `_self`, `_blank`). Ignored when rendering as a native button. |
| `text` | `string \| undefined` |  |  | Fallback text content rendered when no default slot is provided. |
| `to` | `string \| wt \| bt \| undefined` |  |  | Route location to navigate to. When provided (and not disabled), the component renders as a Vue Router link. |
| `type` | `"button" \| "submit" \| "reset" \| undefined` | `"button"` |  | Native `type` attribute used when rendering as a button (e.g. `button`, `submit`, `reset`). |
| `viewTransition` | `boolean \| undefined` | `false` |  | Inertia: run the page swap inside a View Transition, where the browser supports one. |

## Events

- None.

## Slots

- `default` — scope: `object` — Primary content rendered inside the button element. Falls back to the `text` prop when empty.

## See Also

- [BbButton](./BbButton.md) — Button with loading state, tooltip, and icon support.
- [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).

---

<!-- dist/ai/BbBaseCheckbox.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseCheckbox.md -->

# BbBaseCheckbox

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Reference Only - Base Primitive**
- Description: Internal low-level checkbox primitive.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/BbBaseCheckbox.md](./source/BbBaseCheckbox.md)

## v-model

- `v-model` — type: `any`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `ariaDescribedby` | `string \| undefined` |  |  | ID of the element that describes this checkbox for assistive technologies. Forwarded to the input as `aria-describedby`. |
| `autofocus` | `Booleanish \| undefined` | `false` |  | Automatically focuses the checkbox when the page/component loads. Use sparingly to avoid usability issues. |
| `checked` | `boolean \| undefined` | `undefined` |  | Forces the checkbox checked state (controlled prop). When omitted, the checked state is derived from `modelValue === trueValue`. Deliberately `undefined` rather than `false`, so "unset" stays distinguishable from an explicit `:checked="fals… |
| `disabled` | `boolean \| undefined` | `false` |  | Disables user interaction. Also applied when `readonly` is set, since native checkboxes do not support `readonly`. |
| `falseValue` | `any` | `false` |  | Value submitted/emitted when the checkbox is unchecked. Accepts any serializable value. Serialized to a string for form submission. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Puts the component into an error state (adds error styling class `bb-base-checkbox--errors`). |
| `hasWarning` | `boolean \| undefined` | `false` |  | Puts the component into a warning state (adds `bb-base-checkbox--warnings`). Errors take priority when both are set. |
| `id` | `string \| undefined` |  |  | Identifier forwarded to the input. |
| `indeterminate` | `boolean \| undefined` | `false` |  | Renders the checkbox in the indeterminate state (neither checked nor unchecked). Note: the native `indeterminate` state resets on user click; this component re-applies it to keep UI and prop aligned. |
| `modelValue` | `any` |  |  | Bound value for `v-model`. When it equals `trueValue` the checkbox is considered checked, otherwise unchecked. |
| `name` | `string \| undefined` |  |  | Name attribute of the input, used during form submission. |
| `readonly` | `boolean \| undefined` | `false` |  | Puts the input in a read-only state. Since checkboxes do not support native `readonly`, the input is disabled while styled as read-only. |
| `required` | `boolean \| undefined` | `false` |  | Marks the input as required for form validation. |
| `submitWhenFalse` | `boolean \| undefined` | `false` |  | When unchecked, submits a hidden input with `falseValue` so that a value is still posted with the form. When checked, the visible input submits `trueValue` as usual. |
| `trueValue` | `any` | `true` |  | Value submitted/emitted when the checkbox is checked. Accepts any serializable value. Serialized to a string for form submission. |

## Events

- `blur` — `(event: "blur", event: FocusEvent): void`
- `change` — `(event: "change", event: Event): void`
- `click` — `(event: "click", event: MouseEvent): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `input` — `(event: "input", event: Event): void`
- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
- `update:modelValue` — `(event: "update:modelValue", value: any): void`

## Slots

- `icon` — scope: `BaseCheckboxIconSlotProps` — Replaces the default checkmark SVG rendered inside the checkbox box.

---

<!-- dist/ai/BbBaseCheckboxGroup.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseCheckboxGroup.md -->

# BbBaseCheckboxGroup

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Reference Only - Base Primitive**
- Description: Internal low-level grouped checkbox primitive.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/BbBaseCheckboxGroup.md](./source/BbBaseCheckboxGroup.md)

## v-model

- `v-model` — type: `any`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `ariaDescribedby` | `string \| undefined` |  |  | ID of the element that describes the entire checkbox group for assistive technologies. Forwarded to each generated input as `aria-describedby`. |
| `autofocus` | `Booleanish \| undefined` | `false` |  | Automatically focuses the first checkbox on mount when true. Applied only to the first option. |
| `dependencies` | `unknown[] \| undefined` | `[]` |  | List of reactive values which, when changed, trigger items re-fetching. Useful to reload options based on external inputs. |
| `depsDebounceTime` | `number \| undefined` | `0` |  | Debounce delay (ms) applied when reacting to `dependencies` changes. |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `"horizontal"` |  | Direction of the group layout. - `horizontal`: options flow in rows - `vertical`: options stack in a column |
| `disabled` | `boolean \| undefined` | `false` |  | Disables interaction for the whole group. |
| `enforceCoherence` | `boolean \| undefined` | `false` |  | Enforces that `modelValue` contains only values present in `items`. Incoherent values are removed and `update:modelValue` is emitted with a coherent array. Please check out {@link https://ui-components-docs.vercel.app/it/guides/coherence th… |
| `hasErrors` | `boolean \| undefined` | `false` |  | Puts the component into an error state adds the error styling class. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Puts the component into a warning state. Errors take priority when both are set. |
| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides each option's label text (the text rendered next to every input) while keeping it accessible to screen readers. |
| `id` | `string \| undefined` |  |  | Identifier of the group. Used to derive per-option IDs for accessible labeling. |
| `items` | `T[] \| ((prefill: boolean, modelValue?: any) => T[] \| Promise<T[]>)` | `[]` | yes | Items provider. Can be: - An array of items - A sync/async function `(prefill, modelValue) => items` When a function is provided, it is invoked on prefill and when dependencies change to load options dynamically. |
| `itemText` | `(T extends object ? string \| ((item: T) => string) : (item: T) => string) \| undefined` | `JSON.stringify(item)` |  | Defines how to derive the display text from an item. Accepts a nested key path into the item or a function `(item) => string`. |
| `itemValue` | `(T extends object ? string \| ((item: T) => string) : (item: T) => any) \| undefined` | `JSON.stringify(item)` |  | Defines how to derive the value from an item. Accepts a nested key path into the item or a function `(item) => any`. |
| `loadingText` | `string \| undefined` | `'Loading...'` |  | Text displayed while items are loading. |
| `max` | `number \| undefined` | `Infinity` |  | Maximum number of selectable items. |
| `modelValue` | `any` |  | yes | Selected values for the group. Used with `v-model`. Single value when `multiple` is false, array when `multiple` is true. |
| `modelValueDebounceTime` | `number \| undefined` | `0` |  | Debounce delay (ms) applied when reacting to `modelValue` changes. |
| `multiple` | `boolean \| undefined` | `true` |  | Enables multi-selection behavior. When `true`, `modelValue` must be an array and emitted updates are arrays. When `false`, `modelValue` must be a single value (or `null`) and emitted updates are single values. |
| `name` | `string \| undefined` |  |  | Name attribute applied to each input for form submission. |
| `noDataText` | `string \| undefined` | `'No data to display'` |  | Text displayed when there are no items to show. |
| `readonly` | `boolean \| undefined` | `false` |  | Makes all checkboxes read-only. Since checkboxes do not support native `readonly`, inputs are disabled while styled as read-only. |
| `selectable` | `boolean \| ((item: T) => boolean) \| undefined` | `true` |  | Defines whether options are selectable. Can be a global boolean that affects all options or a function that accepts an item and returns a boolean that only affects that item. Non-selectable options are rendered disabled. |

## Events

- `active` — `(e: "active"): void` — Emitted when the group becomes active (focus/click enters it).
- `blur` — `(e: "blur", event: FocusEvent): void` — Emitted when one of the generated checkbox inputs loses focus. Forwards the original DOM `FocusEvent`.
- `change` — `(e: "change", event: Event): void` — Emitted when an option is toggled. Forwards the original DOM `Event` from the checkbox input.
- `click` — `(e: "click", event: MouseEvent): void` — Emitted when one of the generated checkbox inputs is clicked. Forwards the original DOM `MouseEvent`.
- `focus` — `(e: "focus", event: FocusEvent): void` — Emitted when one of the generated checkbox inputs receives focus. Forwards the original DOM `FocusEvent`.
- `inactive` — `(e: "inactive"): void` — Emitted when focus/click moves outside the group after it was active. Useful for validation-on-blur flows at group level.
- `input` — `(e: "input", event: Event): void` — Emitted on native input events from generated checkbox inputs. Forwards the original DOM `Event`.
- `keydown` — `(e: "keydown", event: KeyboardEvent): void` — Emitted for keyboard interaction on generated checkbox inputs. Forwards the original DOM `KeyboardEvent`.
- `mousedown` — `(e: "mousedown", event: MouseEvent): void` — Emitted when a pointing device button is pressed over a checkbox input. Forwards the original DOM `MouseEvent`.
- `mouseup` — `(e: "mouseup", event: MouseEvent): void` — Emitted when a pointing device button is released over a checkbox input. Forwards the original DOM `MouseEvent`.
- `update:modelValue` — `(e: "update:modelValue", value: any): void` — Emitted with the coherent next selection array whenever selection changes.

## Slots

- `append` — scope: `BaseCheckboxGroupEmptySlotProps` — Content rendered after the last option, inside the options container.
- `icon` — scope: `BaseCheckboxGroupIconSlotProps<T>` — Replaces the default checkmark icon for each checkbox option. Receives all `BaseCheckbox` slot attributes plus the source item and its display text.
- `label` — scope: `BaseCheckboxGroupLabelSlotProps<T>` — Replaces the default label text for each option.
- `loading` — scope: `BaseCheckboxGroupEmptySlotProps` — Content shown while options are loading (replaces the default loading text).
- `no-data` — scope: `BaseCheckboxGroupEmptySlotProps` — Content shown when no options are available (replaces the default "no data" text).
- `prepend` — scope: `BaseCheckboxGroupEmptySlotProps` — Content rendered before the first option, inside the options container.

---

<!-- dist/ai/BbBaseCheckboxIcon.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseCheckboxIcon.md -->

# BbBaseCheckboxIcon

## Agent Contract

- Safety level: **Consumer API**
- Group: **Selection**
- Description: Standalone checkbox glyph (box + checkmark SVG). Presentational only — no input, no events. Compose it into a fully custom checkbox design, or let BbCheckbox/BbBaseCheckbox render it.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbBaseCheckboxIcon.md](./source/BbBaseCheckboxIcon.md)

## Usage & Guidelines

### What this is (and when to reach for it)

`BbBaseCheckboxIcon` is **only the visual** — the rounded box, the stroke-animated
checkmark, and the indeterminate dash — extracted from `BbBaseCheckbox`. It has
no native `<input>`, emits no events, and holds no state. You tell it how to
look through boolean props; it draws that state.

For virtually every form you should use [`BbCheckbox`](./BbCheckbox.md) (or
[`BbCheckboxGroup`](./BbCheckboxGroup.md)) — they wire up the input, `v-model`,
label, validation and accessibility for you. Reach for `BbBaseCheckboxIcon` only
when the surrounding design is so different that a labelled checkbox row can't
express it: a selectable card grid, a toolbar toggle, a bespoke list row. In
those cases you own the real control (a native input or an ARIA widget) and drop
the glyph in for the visuals.

**Every visual state**

```vue
<div class="flex items-center gap-4">
	<BbBaseCheckboxIcon :checked="false" />
	<BbBaseCheckboxIcon :checked="true" />
	<BbBaseCheckboxIcon :indeterminate="true" />
	<BbBaseCheckboxIcon :checked="true" :disabled="true" />
	<BbBaseCheckboxIcon :checked="true" :has-errors="true" />
	<BbBaseCheckboxIcon :checked="true" :focus-visible="true" />
</div>
```

### Compose it into a custom control

The glyph is decorative (`aria-hidden`), so it **must** be paired with a real
control. The reliable pattern: a `<label>` wrapping a visually-hidden native
`<input type="checkbox">` (keep it in the a11y tree with `sr-only`, never
`display:none`) plus the glyph reflecting `checked`. You get native keyboard
support, focus, and form submission for free, and total freedom over the layout
around it.

**Invoice alert channel cards**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Invoice alerts</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Northwind · overdue notices for INV-1042 and later
			</p>
		</div>

		<fieldset class="flex flex-col gap-1.5 border-0 p-0">
			<legend class="sr-only">Notification channels</legend>
			<label
				v-for="channel in channels"
				:key="channel.id"
				class="flex cursor-pointer items-center gap-2.5 rounded-[var(--bb-radius)] border p-2.5 transition-colors"
				:class="
					selected.includes(channel.id)
						? 'border-[color:var(--bb-primary)] bg-[color:var(--bb-muted)]'
						: 'border-[color:var(--bb-border)] hover:bg-[color:var(--bb-surface-hover)]'
				"
			>
				<!-- Glyph is decorative; the sr-only input owns focus, keyboard, and form state. -->
				<input
					v-model="selected"
					class="sr-only"
					type="checkbox"
					:value="channel.id"
				/>
				<BbBaseCheckboxIcon :checked="selected.includes(channel.id)" />
				<span class="flex min-w-0 flex-col">
					<span class="text-sm font-medium">{{ channel.label }}</span>
					<span class="text-xs text-[color:var(--bb-text-muted)]">{{
						channel.hint
					}}</span>
				</span>
			</label>
		</fieldset>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbBaseCheckboxIcon } from 'bitboss-ui';

type Channel = { id: string; label: string; hint: string };

const channels: Channel[] = [
	{ id: 'email', label: 'Email digest', hint: 'Morning summary · weekdays' },
	{ id: 'sms', label: 'SMS', hint: 'Urgent overdue only' },
	{ id: 'push', label: 'Slack #billing', hint: 'Posts to the shared channel' },
];

const selected = ref<string[]>(['email']);
</script>
```

### Styling

The glyph owns its own tokens, so restyle it by overriding CSS custom
properties on it:

- `--size` — box edge length (default `16px`)
- `--r` — corner radius (default `4px`)
- `--color` — fill + border when checked/indeterminate (default `--bb-primary`)
- `--check-color` — checkmark stroke (default `--bb-primary-fg`)
- `--ring-color` — focus ring color

**On the element itself, not an ancestor.** Each of these is declared on the
glyph's own class, and a declaration on the element always beats one inherited
from an ancestor — so `--size` set on a wrapper `div` is simply ignored
(verified: the glyph stays 16px). Target the glyph class, or pass a `style` /
`class` that lands on it:

```css
/* works */
.bb-base-checkbox-icon {
	--size: 20px;
}
/* does nothing */
.my-form {
	--size: 20px;
}
```

**Bigger, rounder, recolored**

```vue
<BbBaseCheckboxIcon
	:checked="true"
	style="--size: 28px; --r: 999px; --color: #16a34a"
/>
```

### Gotchas & anti-patterns

- **Don't ship it as the whole control.** It is `aria-hidden` and non-focusable;
  on its own it is invisible to keyboard and screen-reader users. Always back it
  with a real `<input>` (or a proper ARIA checkbox widget).
- **Don't reach for it when `BbCheckbox` fits.** If you need a labelled checkbox
  in a form, `BbCheckbox` already does everything — the glyph is for designs the
  wrapper genuinely can't express.
- `indeterminate` wins over `checked` visually — a glyph that is both renders the
  dash, matching native checkbox behavior.
- It reflects state, it doesn't manage it: clicking the glyph does nothing by
  itself. Toggle your own state (or the backing input) and pass it back in.

### Works well with

- [`BbCheckbox`](./BbCheckbox.md) — the batteries-included checkbox; prefer it
  unless you truly need the bare glyph.
- [`BbBaseRadioIcon`](./BbBaseRadioIcon.md) / [`BbBaseSwitchIcon`](./BbBaseSwitchIcon.md) — the
  matching standalone glyphs for radios and switches.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `checked` | `boolean \| undefined` | `false` |  | Renders the checked state (fills the box and draws the checkmark). |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the glyph (muted fill, not-allowed cursor). Purely visual. |
| `focusVisible` | `boolean \| undefined` | `false` |  | Whether keyboard focus is visible (`:focus-visible`). Draws the focus ring. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Puts the glyph into the error state (danger border and ring color). |
| `hasWarning` | `boolean \| undefined` | `false` |  | Puts the glyph into the warning state (warn border and ring color). Errors take priority when both are set. |
| `indeterminate` | `boolean \| undefined` | `false` |  | Renders the indeterminate state (filled box with a dash instead of the checkmark). Takes visual precedence over `checked`. |
| `readonly` | `boolean \| undefined` | `false` |  | Renders the read-only affordance (default cursor instead of pointer). |

## Events

- None.

## Slots

- None.

## See Also

- [BbCheckbox](./BbCheckbox.md) — Toggles a single boolean option.
- [BbBaseCheckbox](./BbBaseCheckbox.md) — Internal low-level checkbox primitive.
- [BbBaseRadioIcon](./BbBaseRadioIcon.md) — Standalone radio glyph (ring + dot). Presentational only — no input, no events. Compose it into a fully custom radio design, or let BbRadio/BbBaseRadio render it.
- [BbBaseSwitchIcon](./BbBaseSwitchIcon.md) — Standalone switch glyph (track + thumb). Presentational only — no input, no events. Compose it into a fully custom switch design, or let BbSwitch/BbBaseSwitch render it.

---

<!-- dist/ai/BbBaseColorInput.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseColorInput.md -->

# BbBaseColorInput

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Reference Only - Base Primitive**
- Description: Internal low-level color input primitive.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/BbBaseColorInput.md](./source/BbBaseColorInput.md)

## v-model

- `v-model` — type: `string \| null`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | When `true`, the palette opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover. Forwarded to `BbColorPalette`, which resolves the fallback. When unset, falls back to the global `config.adaptive`. |
| `alpha` | `boolean \| undefined` | `false` |  | Enable the alpha channel. When true the picker shows an opacity slider and emits / accepts `#RRGGBBAA` hex8 values. |
| `append:icon` | `string \| undefined` |  |  | Name of the icon to render at the right hand side of the input. |
| `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of element(s) describing this input for assistive tech (space-separated). Typically includes the container hint id if used within a BaseInputContainer. |
| `autocomplete` | `string \| undefined` | `"off"` |  | Autocomplete hint for the browser. |
| `autofocus` | `Booleanish \| undefined` |  |  | Focus the input on mount. |
| `clearable` | `boolean \| undefined` | `false` |  | Show a clear button when the input has a value. |
| `compact` | `boolean \| undefined` | `false` |  | Display the component in a compact layout. |
| `disabled` | `boolean \| undefined` | `false` |  | Disable all interactions. |
| `eyeDropper` | `boolean \| undefined` | `false` |  | Show an eyedropper button to sample any color on screen. Uses the native EyeDropper API — hidden automatically on unsupported browsers. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Visually mark the component as invalid (also sets aria-invalid on the input). |
| `hasWarning` | `boolean \| undefined` | `false` |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
| `id` | `string \| undefined` |  |  | The id attribute for the input element. Defaults to a generated `bb_<unique>` id when omitted. |
| `loading` | `boolean \| undefined` | `false` |  | Display the loading state. |
| `modelValue` | `string \| null` |  | yes | v-model value: `#RRGGBB` hex string or `null` when empty. Example: `#1A2B3C` |
| `name` | `string \| undefined` |  |  | Name attribute of the input. |
| `placeholder` | `string \| undefined` |  |  | Placeholder text when there is no value. |
| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to render at the start of the input. |
| `readonly` | `boolean \| undefined` | `false` |  | Make the input read-only. |
| `required` | `boolean \| undefined` | `false` |  | Mark the input as required. |
| `swatches` | `boolean \| string[][] \| undefined` |  |  | Controls swatches display in the picker: - `true` — show the built-in Material-palette swatches - `string[][]` — show custom swatches (each inner array = a column of shades) - `false` / omitted — no swatches section |
| `transitionDuration` | `number \| undefined` | `250` |  | Transition duration (ms) of the palette popover. Forwarded to `BbColorPalette`, which supplies the default. |

## Events

- `blur` — `(event: "blur", event: FocusEvent): void`
- `change` — `(event: "change", event: Event): void`
- `click` — `(event: "click", event: MouseEvent): void`
- `compositionend` — `(event: "compositionend", event: CompositionEvent): void`
- `compositionstart` — `(event: "compositionstart", event: CompositionEvent): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `input` — `(event: "input", event: Event): void`
- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
- `keyup` — `(event: "keyup", event: KeyboardEvent): void`
- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
- `paste` — `(event: "paste", event: ClipboardEvent): void`
- `update:modelValue` — `(event: "update:modelValue", value: string \| null): void`

## Slots

- `append` — scope: `Record<string, never>` — Content rendered after the color picker indicator button, at the end of the inner container. Mutually exclusive with `suffix`: the `suffix` slot renders inside this slot's default content, so providing `append` replaces the suffix rendering…
- `append-outer` — scope: `Record<string, never>` — Content rendered after the entire input control, outside the input chrome. This slot receives no scoped props.
- `prefix` — scope: `Record<string, never>` — Inline content rendered at the start of the input field area, before the typed text. This slot receives no scoped props.
- `prepend` — scope: `Record<string, never>` — Content rendered before the text input, at the start of the inner container. This slot receives no scoped props.
- `prepend-outer` — scope: `Record<string, never>` — Content rendered before the entire input control, outside the input chrome. This slot receives no scoped props.
- `suffix` — scope: `Record<string, never>` — Inline content rendered at the end of the input field area, after the typed text. Renders inside the default `append` area's suffix wrapper — mutually exclusive with `append`: if an `append` slot is provided it replaces this wrapper and the…

---

<!-- dist/ai/BbBaseColorPalette.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseColorPalette.md -->

# BbBaseColorPalette

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Inputs**
- Description: Internal low-level color palette panel used by BbColorPalette and BbColorInput.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/BbBaseColorPalette.md](./source/BbBaseColorPalette.md)

## v-model

- `v-model` — type: `string \| null`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `alpha` | `boolean \| undefined` | `false` |  | Enable alpha channel support. When true, an alpha slider is shown and emitted values include alpha as hex8. |
| `eyeDropper` | `boolean \| undefined` | `false` |  | Show an eyedropper button that lets the user sample any color on screen. Uses the native EyeDropper API — hidden automatically on unsupported browsers. |
| `modelValue` | `string \| null` |  | yes | Current color value bound via `v-model`. Accepts `#RRGGBB` and `#RRGGBBAA` (alpha) formats, or `null` for no value. |
| `swatches` | `boolean \| string[][] \| undefined` |  |  | Controls swatches display: - `true` — show the built-in Material-palette swatches - `string[][]` — show custom swatches (each inner array = a column of shades) - `false` / omitted — no swatches section |

## Events

- `update:modelValue` — `(event: "update:modelValue", value: string): void`

## Slots

- None.

## Exposed (template ref)

- `el`: `HTMLDivElement \| null`

## See Also

- [BbColorPalette](./BbColorPalette.md) — Opens an anchored popover color palette for color picking interactions.
- [BbColorInput](./BbColorInput.md) — Captures color values through input controls.

---

<!-- dist/ai/BbBaseDatePicker.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseDatePicker.md -->

# BbBaseDatePicker

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Reference Only - Base Primitive**
- Description: Internal low-level date picker primitive.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/BbBaseDatePicker.md](./source/BbBaseDatePicker.md)

## v-model

- `v-model` — type: `string \| string[] \| null`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
| `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` | `1` |  | Defines the first day of the week with `0` meaning Sunday and `6` meaning Saturday. |
| `floating` | `boolean \| undefined` | `false` |  | If true the value is a plain calendar string (`YYYY-MM-DD`, or the shape `type` dictates) instead of the default ISO instant. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `max` | `string \| undefined` |  |  | Maximum selectable date. |
| `min` | `string \| undefined` |  |  | Minimum selectable date. |
| `modelValue` | `string \| string[] \| null` |  | yes | Used by v-model. Can be null, a single string, or an array of strings based on whether a range or single date is needed. |
| `multiple` | `boolean \| undefined` | `false` |  | Allows the selection of multiple items. |
| `range` | `boolean \| undefined` | `false` |  | Selects a range of dates between two dates. It selects all of the days between start and end. |
| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
| `selectable` | `((date: string) => boolean) \| undefined` |  |  | Function that accepts a date string and returns a boolean. Returning `false` means the date cannot be selected. The string is shaped by `type`: `YYYY-MM` under `month`, `YYYY` under `year`. |
| `type` | `DatePickerType \| undefined` | `"date"` |  | What the grid selects: a day (`date`/`datetime`), a month, or a year. The coarse types make the month/year panel terminal instead of a navigation step, and emit `YYYY-MM` / `YYYY`. |
| `utc` | `boolean \| undefined` | `false` |  | Emits values as UTC ISO strings (`...Z`) instead of ISO strings carrying the local offset (`...+01:00`). Emission-only: incoming values are parsed identically either way, so the prop can be added or removed without touching stored values. I… |

## Events

- `update:modelValue` — `(event: "update:modelValue", value: string \| string[] \| null): void`

## Slots

- None.

## Exposed (template ref)

- `resetStatus`: `() => void`

---

<!-- dist/ai/BbBaseDatePickerInput.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseDatePickerInput.md -->

# BbBaseDatePickerInput

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Reference Only - Base Primitive**
- Description: Internal low-level date-picker input primitive.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/BbBaseDatePickerInput.md](./source/BbBaseDatePickerInput.md)

## v-model

- `v-model` — type: `string \| string[] \| null`
- `v-model:time` — type: `string \| string[] \| null \| undefined`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile the calendar opens inside a bottom off-canvas sheet instead of a floating popover, mirroring the adaptive behaviour of `BbPopover`/`BbSelectPopover`. When unset, falls back to the global `config.adaptive`. |
| `ampm` | `boolean \| undefined` | `false` |  | 12-hour display with an AM/PM segment (requires `type="datetime"`). Purely a field-composition concern: `modelValue` and the `time` model stay 24-hour regardless. Type `A`/`P` (or ArrowUp/Down) to set the meridiem. |
| `append:icon` | `string \| undefined` |  |  | Name of the icon to render at the right hand side of the input. |
| `ariaDescribedby` | `string \| undefined` |  |  | Additional description id(s) announced by assistive technologies. Usually provided by an outer input container to link hint/error text. |
| `autocomplete` | `string \| undefined` | `"off"` |  | Browser autocomplete hint for the input. |
| `autofocus` | `Booleanish \| undefined` |  |  | Focus the first text field automatically when the component mounts. |
| `clearable` | `boolean \| undefined` | `false` |  | Displays a clear button whenever a value is present and the control is interactive. |
| `compact` | `boolean \| undefined` | `false` |  | Applies the compact density styles to the control. |
| `disableCalendar` | `boolean \| "mobile" \| "desktop" \| undefined` | `false` |  | Disables the calendar: hides the trigger button and prevents the popover from opening. Use `'desktop'` to disable it on desktop only (keyboard-first there, calendar-first on mobile — complementing `disableWriting: 'mobile'`) or `'mobile'` t… |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the input, calendar trigger, and popover. |
| `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` | `false` |  | Controls whether manual typing is disabled inside the text fields. Use `'mobile'` to disable typing only on mobile, `'desktop'` to disable typing only on desktop. Applies to both single and range modes. |
| `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` |  |  | Sets the first day of the week for the calendar (0 = Sunday, 6 = Saturday). |
| `floating` | `boolean \| undefined` | `false` |  | Emit dates formatted as `YYYY-MM-DD` instead of ISO strings. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Marks the control as invalid, applying error styles and setting `aria-invalid`. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
| `id` | `string \| undefined` |  |  | Explicit id for the input element. Falls back to an auto-generated `bdpi-<uid>` value. |
| `loading` | `boolean \| undefined` | `false` |  | Shows loading visuals on the input. |
| `max` | `string \| undefined` |  |  | Maximum selectable date in `YYYY-MM-DD` format — or, with `type="datetime"`, `YYYY-MM-DDTHH:mm` to tighten the boundary day to a minute. Values outside both patterns throw during setup to surface configuration mistakes. |
| `min` | `string \| undefined` |  |  | Minimum selectable date in `YYYY-MM-DD` format — or, with `type="datetime"`, `YYYY-MM-DDTHH:mm` to tighten the boundary day to a minute. Values outside both patterns throw during setup to surface configuration mistakes. |
| `modelValue` | `string \| string[] \| null` |  | yes | v-model value. Use `null` for empty, a single string for single selection, or a two-element string array (`[start, end]`) when `range` is true. |
| `name` | `string \| undefined` |  |  | Name attribute forwarded to the native inputs. In single mode fields are named `${name}-day`, `${name}-month`, `${name}-year`; in range mode they are prefixed with the segment (`${name}-start-day`, `${name}-end-day`, …). |
| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile (e.g. `title`, `size`, `persistent`). |
| `placeholder` | `string \| undefined` |  |  | Placeholder text displayed when no value is present. Defaults to the localized format hint (`baseDatePickerInput.dateFormatSingle` / `dateFormatRange` — e.g. `MM/DD/YYYY` for `en`, `GG/MM/AAAA` for `it`). |
| `prepend:icon` | `string \| undefined` |  |  | Icon name rendered before the input field. |
| `range` | `boolean \| undefined` | `false` |  | Enables range selection. When active, v-model expects a two-element array `[start, end]`. Users can still type into the start and end segments unless `disableWriting` disables typing. |
| `readonly` | `boolean \| undefined` | `false` |  | Makes the text fields read-only and prevents opening the calendar. |
| `required` | `boolean \| undefined` | `false` |  | Marks the inputs as required to the browser. |
| `seconds` | `boolean \| undefined` | `false` |  | Adds the seconds segment (requires `type="datetime"`). Without it, an incoming value carrying seconds displays truncated and is left untouched until the user commits an edit, at which point seconds zero out. |
| `selectable` | `((date: string) => boolean) \| undefined` |  |  | Predicate invoked for each candidate date. Return `false` to disable selection for that value. |
| `step` | `number \| undefined` | `1` |  | Minute granularity for the calendar's minute column and arrow stepping (requires `type="datetime"`). Constrains what the component produces, never what it accepts: a typed off-grid value (e.g. `10:07` with `step: 15`) is emitted verbatim, a… |
| `time` | `string \| string[] \| null \| undefined` |  |  | Companion model for the time part (`v-model:time`), always 24-hour `HH:mm` / `HH:mm:ss` regardless of display. With `floating` it is the only carrier of the time; otherwise it mirrors the time inside `modelValue` (same digits) and writing i… |
| `transitionDuration` | `number \| undefined` |  |  | Transition duration, in milliseconds, for the popover appearance. |
| `type` | `DatePickerType \| undefined` | `"date"` |  | What the field edits, and therefore its segments and emitted shape. - `date` (default) — `DD/MM/YYYY`. - `datetime` — adds the time segments and the calendar's time rail. - `month` — `MM/YYYY`, emitting `YYYY-MM`. - `year` — `YYYY`, emittin… |
| `utc` | `boolean \| undefined` | `false` |  | Emits values as UTC ISO strings (`...Z`) instead of ISO strings carrying the local offset (`...+01:00`). Emission-only: incoming values are parsed identically either way, so the prop can be added or removed without touching stored values. F… |

## Events

- `active` — `(event: "active"): void`
- `error` — `(event: "error", error: DatePickerInputError): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `inactive` — `(event: "inactive"): void`
- `update:modelValue` — `(event: "update:modelValue", value: string \| string[] \| null): void`
- `update:time` — `(event: "update:time", value: string \| string[] \| null): void`

## Slots

- `append` — scope: `object` — Content rendered after the date fields, at the end of the inner container (before the calendar toggle button).
- `append-outer` — scope: `object` — Content rendered after the entire input control, outside the input chrome.
- `append:day` — scope: `{ first: boolean; highlighted: boolean; item: any; label: string; last: boolean; middle: boolean; selected: boolean; }` — Appends content below each calendar day.
- `day` — scope: `{ first: boolean; highlighted: boolean; item: any; label: string; last: boolean; middle: boolean; selected: boolean; }` — Replaces the day button label inside each calendar day.
- `prefix` — scope: `object` — Inline content rendered at the start of the input field area, before the date fields.
- `prepend` — scope: `object` — Content rendered before the date fields, at the start of the inner container.
- `prepend-outer` — scope: `object` — Content rendered before the entire input control, outside the input chrome.
- `suffix` — scope: `object` — Inline content rendered at the end of the input field area, after the date fields.

---

<!-- dist/ai/BbBaseInputContainer.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseInputContainer.md -->

# BbBaseInputContainer

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Reference Only - Base Primitive**
- Description: Internal wrapper for labels, hints, validation, and shared input layout.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/BbBaseInputContainer.md](./source/BbBaseInputContainer.md)

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `clearable` | `boolean \| undefined` | `false` |  | Whether the inner control exposes a clear action. |
| `compact` | `boolean \| undefined` | `false` |  | Apply the compact density variant to the container. |
| `description` | `string \| undefined` |  |  | Always-visible descriptive text rendered below the label and above the input, in muted foreground color. When present, its id is exposed to the input slot via `ariaDescribedby`, after any error/warning ids and before the hint id. In `floati… |
| `direction` | `InputDirection \| undefined` | `"vertical"` |  | Controls label/input layout. Accepts `'vertical'`, `'horizontal'`, `'auto'`, or a two-token ratio pattern such as `"xx xxxxx"` that sizes the label/input columns by token length. An unrecognized value warns and falls back to `'auto'`. |
| `disabled` | `boolean \| undefined` | `false` |  | Whether the inner control is disabled. |
| `errors` | `string \| string[] \| undefined` |  |  | Messages displayed beneath the input. Accepts a string or array; values are rendered one per line. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, their container id is also expos… |
| `hasErrors` | `boolean \| undefined` | `false` |  | Forces the error state independently of `errors`, useful to pre-style the container. |
| `hasValue` | `boolean \| undefined` | `false` |  | Whether the inner control currently contains a value. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Forces the warning state independently of `warnings`. Same chrome as errors but with `--bb-warn`; errors take priority when both are set. |
| `hideLabel` | `boolean \| undefined` | `false` |  | Hide the visual label while keeping it available to assistive technology. |
| `hint` | `string \| undefined` |  |  | Hint text rendered below the input. While shown, its id is exposed to the input slot via `ariaDescribedby` — last in the list, after any error/warning ids and the description id. |
| `id` | `string \| undefined` |  |  | Explicit id for the container and associated input. Falls back to an auto-generated id when omitted. |
| `inputPosition` | `"left" \| "center" \| "right" \| undefined` | `'left'` |  | Horizontal alignment of the input column when direction is horizontal or custom. Unset, it follows the layout: `'right'` in a horizontal/ratio split (beside the left-hand label), `'left'` otherwise — and `direction` is `'vertical'` by defau… |
| `label` | `string` |  | yes | Visible label text for the field. Also used to derive a fallback name. |
| `labelMode` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Label rendering mode. |
| `labelPosition` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Horizontal alignment for the label column. |
| `labelTag` | `LabelTag \| undefined` | `"label"` |  | Element used for the label: `label` (default), `legend` inside a `fieldset` container, or `span` when the text must not steal the click because the control already carries its own label. |
| `loading` | `boolean \| undefined` | `false` |  | Whether the inner control is in a loading state. |
| `mobile` | `boolean \| undefined` | `false` |  | Whether the inner control is in mobile viewport mode. |
| `name` | `string \| undefined` |  |  | Explicit name attribute forwarded to the input. When omitted, a slug derived from `label` is used. |
| `readonly` | `boolean \| undefined` | `false` |  | Whether the inner control is readonly. |
| `reverse` | `boolean \| undefined` | `false` |  | Swap the label and input columns. |
| `showHint` | `boolean \| undefined` | `false` |  | Keep the hint permanently visible, regardless of focus. |
| `tag` | `ContainerTag \| undefined` | `"span"` |  | Element used for the inner wrapper: `span` (default) to remain inline, `div` for a block wrapper, `fieldset` for grouped controls (pair it with `labelTag="legend"`), or `label` to make the whole wrapper activate the control. |
| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages displayed beneath the input, in their own `aria-live` region. Accepts a string or array; values are rendered one per line, in `--bb-text-warn` amber (the text-contrast half of the warning pair — the chrome stays on `--bb-wa… |

## Events

- None.

## Slots

- `input` — scope: `BaseInputContainerInputSlotProps` — The form control to render, positioned in the input column. Receives pre-computed wiring attributes so the inner input can be correctly associated with the label and hint.
- `label` — scope: `BaseInputContainerLabelSlotProps` — Replaces the default label text. The outer label element and its `for` association are always rendered.

---

<!-- dist/ai/BbBaseNumberInput.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseNumberInput.md -->

# BbBaseNumberInput

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Reference Only - Base Primitive**
- Description: Internal low-level numeric input primitive.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/BbBaseNumberInput.md](./source/BbBaseNumberInput.md)

## v-model

- `v-model` — type: `string \| number \| null`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `append:icon` | `string \| undefined` |  |  | Name of the icon to render at the right hand side of the input. |
| `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of descriptive elements announced by screen readers. |
| `autocomplete` | `string \| undefined` | `"off"` |  | Browser autocomplete hint for the field. |
| `autofocus` | `Booleanish \| undefined` |  |  | Focus the input automatically after mount. |
| `clearable` | `boolean \| undefined` | `false` |  | Show a clear button whenever a value is present and the control is interactive. |
| `compact` | `boolean \| undefined` | `false` |  | Apply the compact density variant. |
| `disabled` | `boolean \| undefined` | `false` |  | Disable manual input and the exposed increase/decrease helpers. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Force the error state; also toggles `aria-invalid`. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
| `id` | `string \| undefined` |  |  | Explicit id forwarded to the native input. |
| `loading` | `boolean \| undefined` | `false` |  | Display the loading state styles. |
| `max` | `number \| undefined` | `Number.MAX_SAFE_INTEGER` |  | Upper bound for clamping user input and helper increments. |
| `maxPrecision` | `number \| undefined` | `8` |  | Maximum number of decimal digits retained after processing. |
| `min` | `number \| undefined` | `Number.MIN_SAFE_INTEGER` |  | Lower bound for clamping user input and helper decrements. |
| `modelValue` | `string \| number \| null` |  | yes | v-model value. Accepts numbers, numeric strings, or null when empty. |
| `name` | `string \| undefined` |  |  | Name attribute forwarded to the native input. |
| `placeholder` | `string \| undefined` |  |  | Placeholder text when no value is present. |
| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to render at the left hand side of the input. |
| `readonly` | `boolean \| undefined` | `false` |  | Make the input read-only while keeping its value visible. |
| `required` | `boolean \| undefined` | `false` |  | Mark the input as required for form validation. |
| `step` | `number \| undefined` | `1` |  | Increment used by the `increase`/`decrease` helpers. Manual typing is never forced to this step. |

## Events

- `blur` — `(event: "blur", event: FocusEvent): void`
- `change` — `(event: "change", event: Event): void`
- `click` — `(event: "click", event: MouseEvent): void`
- `compositionend` — `(event: "compositionend", event: CompositionEvent): void`
- `compositionstart` — `(event: "compositionstart", event: CompositionEvent): void`
- `decrease` — `(event: "decrease", value: number): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `increase` — `(event: "increase", value: number): void`
- `input` — `(event: "input", event: Event): void`
- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
- `keyup` — `(event: "keyup", event: KeyboardEvent): void`
- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
- `paste` — `(event: "paste", event: ClipboardEvent): void`
- `update:modelValue` — `(event: "update:modelValue", value: number \| null): void`

## Slots

- `append` — scope: `BaseNumberInputStepSlotProps` — Content rendered after the number input, at the end of the inner container. Typically used to place increment/decrement buttons next to the input.
- `append-outer` — scope: `BaseNumberInputStepSlotProps` — Content rendered after the entire input control, outside the input chrome.
- `prefix` — scope: `BaseNumberInputStepSlotProps` — Inline content rendered at the start of the input field area, before the typed number.
- `prepend` — scope: `BaseNumberInputStepSlotProps` — Content rendered before the number input, at the start of the inner container.
- `prepend-outer` — scope: `BaseNumberInputStepSlotProps` — Content rendered before the entire input control, outside the input chrome.
- `suffix` — scope: `BaseNumberInputStepSlotProps` — Inline content rendered at the end of the input field area, after the typed number.

## Exposed (template ref)

- `decrease`: `() => void`
- `increase`: `() => void`

---

<!-- dist/ai/BbBaseRadio.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseRadio.md -->

# BbBaseRadio

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Reference Only - Base Primitive**
- Description: Internal low-level radio primitive.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/BbBaseRadio.md](./source/BbBaseRadio.md)

## v-model

- `v-model` — type: `any`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of descriptive elements associated with the radio. |
| `autofocus` | `Booleanish \| undefined` |  |  | Focus the control automatically after mount. |
| `checked` | `boolean \| undefined` | `undefined` |  | Force the radio into a checked state regardless of `modelValue`. |
| `disabled` | `boolean \| undefined` | `false` |  | Disable the radio. When combined with `readonly`, the control is also disabled to mimic native behaviour. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Apply the error styling class. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Apply the warning styling class. Errors take priority when both are set. |
| `id` | `string \| undefined` |  |  | Explicit id for the underlying input element. |
| `modelValue` | `any` |  |  | Current v-model value used to determine checked state. |
| `name` | `string \| undefined` |  | yes | Shared group name for the radio input (required to join options). |
| `readonly` | `boolean \| undefined` | `false` |  | Treat the radio as read-only. Implemented by disabling the input while preserving styling hooks. |
| `required` | `boolean \| undefined` | `false` |  | Mark the radio as required within its group. |
| `value` | `any` |  | yes | Value emitted when the radio becomes checked. Accepts any serializable value. |

## Events

- `blur` — `(event: "blur", event: FocusEvent): void`
- `change` — `(event: "change", event: Event): void`
- `click` — `(event: "click", event: MouseEvent): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `input` — `(event: "input", event: Event): void`
- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
- `update:modelValue` — `(event: "update:modelValue", value: any): void`

## Slots

- `icon` — scope: `BaseRadioIconSlotProps` — Replaces the default radio dot visual rendered inside the radio container.

---

<!-- dist/ai/BbBaseRadioGroup.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseRadioGroup.md -->

# BbBaseRadioGroup

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Reference Only - Base Primitive**
- Description: Internal low-level radio-group primitive.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/BbBaseRadioGroup.md](./source/BbBaseRadioGroup.md)

## v-model

- `v-model` — type: `any`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of elements describing this group for assistive technologies. |
| `ariaLabelledby` | `string \| undefined` |  |  | Id(s) of the element(s) that NAME this radio group. Supplying one (or a fallthrough `aria-label`/`aria-labelledby`) is what promotes the options container to `role="radiogroup"`: an unnamed `radiogroup` is not an improvement over no role at… |
| `autofocus` | `Booleanish \| undefined` |  |  | Focus the first radio on mount. |
| `dependencies` | `unknown[] \| undefined` |  |  | Additional dependencies that trigger item reloading when changed. |
| `depsDebounceTime` | `number \| undefined` | `0` |  | Debounce delay (ms) for dependency-triggered reloads. |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `"horizontal"` |  | Direction of the layout of the inputs inside the fieldset. |
| `disabled` | `boolean \| undefined` | `false` |  | Disable all radios in the group. |
| `enforceCoherence` | `boolean \| undefined` | `false` |  | Reset modelValue to `null` if it no longer matches available items (enforces coherence). |
| `hasErrors` | `boolean \| undefined` | `false` |  | Apply error styling to the group. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Apply warning styling to the group. Errors take priority when both are set. |
| `hideLabel` | `boolean \| undefined` | `false` |  | Hide the visual label while keeping it accessible. |
| `id` | `string \| undefined` |  |  | Explicit id for the fieldset. Used to generate ids for individual radios. |
| `items` | `T[] \| ((prefill: boolean, modelValue?: any) => T[] \| Promise<T[]>)` | `[]` | yes | Array of items or function to load them asynchronously. |
| `itemText` | `(T extends object ? NestedKeyOf<T> \| ((item: T) => string) : ((item: T) => string) \| undefined) \| undefined` |  |  | Path to item property for display text or function to extract it. |
| `itemValue` | `(T extends object ? NestedKeyOf<T> \| ((item: T) => string) : ((item: T) => any) \| undefined) \| undefined` |  |  | Path to item property for value or function to extract it. |
| `loadingText` | `string \| undefined` |  |  | Message shown while items are loading. |
| `modelValue` | `any` |  | yes | Used by v-model. Can be any serializable type. |
| `modelValueDebounceTime` | `number \| undefined` | `0` |  | Debounce delay (ms) for modelValue change handling. |
| `name` | `string \| undefined` |  | yes | Shared name for all radios in the group (required for grouping). |
| `noDataText` | `string \| undefined` |  |  | Message displayed when no items are available. |
| `readonly` | `boolean \| undefined` | `false` |  | Make all radios read-only. |
| `required` | `boolean \| undefined` | `false` |  | Mark at least one radio as required. |
| `selectable` | `boolean \| ((item: T) => boolean) \| undefined` | `true` |  | Defines whether options are selectable. Can be a global boolean that affects all options or a function that accepts an item and returns a boolean that only affects that item. Non-selectable options are rendered disabled. |

## Events

- `active` — `(e: "active"): void` — Emitted when the group becomes active (focus/click enters it).
- `blur` — `(e: "blur", event: FocusEvent): void` — Emitted when one of the generated radio inputs loses focus. Forwards the original DOM `FocusEvent`.
- `change` — `(e: "change", event: Event): void` — Emitted when a radio option is selected. Forwards the original DOM `Event` from the radio input.
- `click` — `(e: "click", event: MouseEvent): void` — Emitted when one of the generated radio inputs is clicked. Forwards the original DOM `MouseEvent`.
- `focus` — `(e: "focus", event: FocusEvent): void` — Emitted when one of the generated radio inputs receives focus. Forwards the original DOM `FocusEvent`.
- `inactive` — `(e: "inactive"): void` — Emitted when focus/click moves outside the group after it was active. Useful for validation-on-blur flows at group level.
- `input` — `(e: "input", event: Event): void` — Emitted on native input events from generated radio inputs. Forwards the original DOM `Event`.
- `keydown` — `(e: "keydown", event: KeyboardEvent): void` — Emitted for keyboard interaction on generated radio inputs. Forwards the original DOM `KeyboardEvent`.
- `mousedown` — `(e: "mousedown", event: MouseEvent): void` — Emitted when a pointing device button is pressed over a radio input. Forwards the original DOM `MouseEvent`.
- `mouseup` — `(e: "mouseup", event: MouseEvent): void` — Emitted when a pointing device button is released over a radio input. Forwards the original DOM `MouseEvent`.
- `update:modelValue` — `(e: "update:modelValue", value: any): void` — Emitted with the newly selected value when the selection changes.

## Slots

- `append` — scope: `object` — Content rendered after the last option, inside the options container.
- `icon` — scope: `BaseRadioGroupIconSlotProps<T>` — Replaces the default radio dot icon for each option. Receives all `BaseRadio` slot attributes plus the source item and its display text.
- `label` — scope: `BaseRadioGroupLabelSlotProps<T>` — Replaces the default label text for each option.
- `loading` — scope: `object` — Content shown while options are loading (replaces the default loading text).
- `no-data` — scope: `object` — Content shown when no options are available (replaces the default "no data" text).
- `prepend` — scope: `object` — Content rendered before the first option, inside the options container.

---

<!-- dist/ai/BbBaseRadioIcon.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseRadioIcon.md -->

# BbBaseRadioIcon

## Agent Contract

- Safety level: **Consumer API**
- Group: **Selection**
- Description: Standalone radio glyph (ring + dot). Presentational only — no input, no events. Compose it into a fully custom radio design, or let BbRadio/BbBaseRadio render it.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbBaseRadioIcon.md](./source/BbBaseRadioIcon.md)

## Usage & Guidelines

### What this is (and when to reach for it)

`BbBaseRadioIcon` is **only the visual** — the bordered ring and the scaling inner
dot — extracted from `BbBaseRadio`. It has no native `<input>`, emits no events,
and holds no state. You tell it how to look through boolean props; it draws that
state.

For virtually every form you should use [`BbRadio`](./BbRadio.md) or
[`BbRadioGroup`](./BbRadioGroup.md) — they wire up the input, `v-model`, roving
focus, label, validation and accessibility for you. Reach for `BbBaseRadioIcon` only
when the surrounding design can't be expressed as a labelled radio row: a
plan-picker card grid, a segmented option list, a bespoke selection surface. In
those cases you own the real control (native radios sharing a `name`) and drop
the glyph in for the visuals.

**Every visual state**

```vue
<div class="flex items-center gap-4">
	<BbBaseRadioIcon :checked="false" />
	<BbBaseRadioIcon :checked="true" />
	<BbBaseRadioIcon :checked="true" :disabled="true" />
	<BbBaseRadioIcon :checked="true" :has-errors="true" />
	<BbBaseRadioIcon :checked="true" :focus-visible="true" />
</div>
```

### Compose it into a custom control

The glyph is decorative (`aria-hidden`), so it **must** be paired with a real
control. The reliable pattern: a `<label>` wrapping a visually-hidden native
`<input type="radio">` (keep it in the a11y tree with `sr-only`, never
`display:none`), all radios in the group sharing one `name`, plus the glyph
reflecting `checked`. Native radios give you exclusive selection, roving focus
and arrow-key navigation for free.

**Workspace plan cards**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Workspace plan</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Billed monthly · cancel anytime
			</p>
		</div>

		<fieldset class="flex flex-col gap-1.5 border-0 p-0">
			<legend class="sr-only">Billing plan</legend>
			<label
				v-for="plan in plans"
				:key="plan.id"
				class="flex cursor-pointer items-center gap-2.5 rounded-[var(--bb-radius)] border p-2.5 transition-colors"
				:class="
					selected === plan.id
						? 'border-[color:var(--bb-primary)] bg-[color:var(--bb-muted)]'
						: 'border-[color:var(--bb-border)] hover:bg-[color:var(--bb-surface-hover)]'
				"
			>
				<!-- Native radios sharing `name` give exclusive selection + arrow keys. -->
				<input
					v-model="selected"
					class="sr-only"
					name="plan"
					type="radio"
					:value="plan.id"
				/>
				<BbBaseRadioIcon :checked="selected === plan.id" />
				<span class="flex min-w-0 flex-1 items-start justify-between gap-3">
					<span class="flex min-w-0 flex-col">
						<span class="text-sm font-medium">{{ plan.label }}</span>
						<span class="text-xs text-[color:var(--bb-text-muted)]">{{
							plan.hint
						}}</span>
					</span>
					<span class="shrink-0 text-xs font-medium tabular-nums">
						{{ plan.price }}
					</span>
				</span>
			</label>
		</fieldset>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbBaseRadioIcon } from 'bitboss-ui';

type Plan = { id: string; label: string; hint: string; price: string };

const plans: Plan[] = [
	{
		id: 'starter',
		label: 'Starter',
		hint: 'Solo operators · 1 seat',
		price: '€0 / mo',
	},
	{
		id: 'team',
		label: 'Team',
		hint: 'Shared inbox · 10 seats',
		price: '€24 / mo',
	},
	{
		id: 'scale',
		label: 'Scale',
		hint: 'SSO + audit log · unlimited',
		price: '€96 / mo',
	},
];

const selected = ref('team');
</script>
```

### Styling

Restyle by overriding the glyph's CSS custom properties on it:

- `--size` — ring diameter (default `16px`)
- `--space` — gap between ring and dot when checked (default `2px`)
- `--color` — dot color (default `--bb-primary`)
- `--ring-color` — focus ring color

**On the element itself, not an ancestor.** Each of these is declared on the
glyph's own class, and a declaration on the element always beats one inherited
from an ancestor — so `--size` set on a wrapper `div` is simply ignored
(verified: the glyph stays at its 16px default). Target the glyph class, or pass a `style` /
`class` that lands on it:

```css
/* works */
.bb-base-radio-icon {
	--size: 20px;
}
/* does nothing */
.my-form {
	--size: 20px;
}
```

**Bigger and recolored**

```vue
<BbBaseRadioIcon :checked="true" style="--size: 24px; --color: #16a34a" />
```

### Gotchas & anti-patterns

- **Don't ship it as the whole control.** It is `aria-hidden` and non-focusable;
  on its own it is invisible to keyboard and screen-reader users. Always back it
  with real native radios (sharing a `name`) or a proper ARIA radiogroup.
- **Don't reach for it when `BbRadio` fits.** If you need a labelled radio in a
  form, `BbRadio`/`BbRadioGroup` already do everything.
- Unlike the checkbox glyph, there is no `indeterminate` state — radios are
  binary per option.
- It reflects state, it doesn't manage it: clicking the glyph does nothing by
  itself. Drive your own state (or the backing inputs) and pass `checked` back.

### Works well with

- [`BbRadio`](./BbRadio.md) / [`BbRadioGroup`](./BbRadioGroup.md) — the
  batteries-included radios; prefer them unless you truly need the bare glyph.
- [`BbBaseCheckboxIcon`](./BbBaseCheckboxIcon.md) /
  [`BbBaseSwitchIcon`](./BbBaseSwitchIcon.md) — the matching standalone glyphs for
  checkboxes and switches.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `checked` | `boolean \| undefined` | `false` |  | Renders the checked state (grows the inner dot). |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the glyph (muted fill, not-allowed cursor). Purely visual. |
| `focusVisible` | `boolean \| undefined` | `false` |  | Whether keyboard focus is visible (`:focus-visible`). Draws the focus ring. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Puts the glyph into the error state (danger border and ring color). |
| `hasWarning` | `boolean \| undefined` | `false` |  | Puts the glyph into the warning state (warn border and ring color). Errors take priority when both are set. |
| `readonly` | `boolean \| undefined` | `false` |  | Renders the read-only affordance (default cursor instead of pointer). |

## Events

- None.

## Slots

- None.

## See Also

- [BbRadio](./BbRadio.md) — Represents a single choice in exclusive options.
- [BbBaseRadio](./BbBaseRadio.md) — Internal low-level radio primitive.
- [BbBaseCheckboxIcon](./BbBaseCheckboxIcon.md) — Standalone checkbox glyph (box + checkmark SVG). Presentational only — no input, no events. Compose it into a fully custom checkbox design, or let BbCheckbox/BbBaseCheckbox render it.
- [BbBaseSwitchIcon](./BbBaseSwitchIcon.md) — Standalone switch glyph (track + thumb). Presentational only — no input, no events. Compose it into a fully custom switch design, or let BbSwitch/BbBaseSwitch render it.

---

<!-- dist/ai/BbBaseRating.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseRating.md -->

# BbBaseRating

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Reference Only - Base Primitive**
- Description: Internal low-level rating primitive.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/BbBaseRating.md](./source/BbBaseRating.md)

## v-model

- `v-model` — type: `number \| null`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of elements describing this rating input for assistive technologies. |
| `ariaLabelledby` | `string \| undefined` |  |  | Id(s) of the element(s) that NAME this rating group. Supplying one is what promotes the inner container to `role="radiogroup"` (Q4.5): an unnamed `radiogroup` announces as a bare "radio group" and is no better than the role-less `<span>` it… |
| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
| `clearable` | `boolean \| undefined` | `false` |  | Allows clearing the selected rating by clicking the current value. |
| `disabled` | `boolean \| undefined` | `false` |  | Disable all interactions with the rating. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Apply error styling to the rating. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
| `id` | `string \| undefined` |  |  | Explicit id for the rating container. Used to generate ids for individual stars. |
| `modelValue` | `number \| null` |  | yes | v-model value: the selected rating (1 to `stars`) or `null` for no selection. |
| `name` | `string` |  | yes | Shared name attribute for all star radio inputs (required for grouping). |
| `readonly` | `boolean \| undefined` | `false` |  | Make the rating read-only while keeping it visible. |
| `required` | `boolean \| undefined` | `false` |  | Mark the rating as required. |
| `size` | `number \| ({ size?: any; } & string) \| keyof Sizes \| undefined` |  |  | Rating icon size. Accepts preset keys or any custom CSS length unit (e.g. `56ch`, `2rem`, `48px`) — applied verbatim, percentages included. |
| `stars` | `number \| undefined` | `5` |  | Maximum number of stars to render and maximum selectable rating value. |

## Events

- `active` — `(event: "active"): void`
- `blur` — `(event: "blur", event: FocusEvent): void`
- `change` — `(event: "change", event: Event): void`
- `click` — `(event: "click", event: MouseEvent): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `inactive` — `(event: "inactive"): void`
- `input` — `(event: "input", event: Event): void`
- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
- `update:modelValue` — `(event: "update:modelValue", value: number \| null): void`

## Slots

- `append` — scope: `object` — Content rendered after the row of rating stars.
- `icon` — scope: `BaseRatingIconSlotProps` — Replaces the default star SVG for each rating option.
- `prepend` — scope: `object` — Content rendered before the row of rating stars.

---

<!-- dist/ai/BbBaseSelect.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseSelect.md -->

# BbBaseSelect

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Reference Only - Base Primitive**
- Description: Internal low-level select/listbox primitive.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/BbBaseSelect.md](./source/BbBaseSelect.md)

## v-model

- `v-model` — type: `any`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | When `true`, the options panel opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover; on desktop it stays a popover. When unset, falls back to the global `config.adaptive`. |
| `append:icon` | `string \| undefined` |  |  | Name of the icon to render at the right hand side of the control. |
| `ariaDescribedby` | `string \| string[] \| undefined` |  |  | Id(s) of elements describing this select for assistive technologies. |
| `autocomplete` | `string \| undefined` | `'off'` |  | Browser autocomplete hint forwarded to the search input inside the dropdown. |
| `autofocus` | `Booleanish \| undefined` |  |  | Focuses the activator button on page load. |
| `clearable` | `boolean \| undefined` | `false` |  | Show a clear button whenever a value is present and the control is interactive. |
| `comma` | `boolean \| undefined` | `false` |  | Display selected values as a comma-separated string instead of individual chips. |
| `compact` | `boolean \| undefined` | `false` |  | Apply the compact density variant. |
| `dependencies` | `any[] \| undefined` | `[]` |  | Additional dependencies that trigger item reloading when changed. |
| `depsDebounceTime` | `number \| undefined` | `0` |  | Debounce delay (ms) for dependency-triggered reloads. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
| `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` | `false` |  | Controls whether the search input is shown inside the dropdown panel. Use `'mobile'` to hide it only on mobile, `'desktop'` to hide it only on desktop. |
| `enforceCoherence` | `boolean \| undefined` | `false` |  | Reset modelValue to `null` or empty array if it no longer matches available items. |
| `filterBy` | `string[] \| undefined` | `[]` |  | Property paths used to filter options when the user types in the search input. When empty (default) options are matched against their display text. When non-empty the provided paths are searched instead of the display text. To disable filte… |
| `groupBy` | `string \| ((item: Item) => string \| number \| symbol) \| undefined` |  |  | Path or function used to group options. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Apply error styling to the select. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
| `headerHeight` | `number \| undefined` |  |  | Height of group headers in the listbox (px). |
| `id` | `string \| undefined` |  |  | Explicit id for the control element. Also used to generate listbox and search input ids. |
| `itemHeight` | `number \| undefined` |  |  | Height of options in the listbox (px). |
| `items` | `Item[] \| ((query: string, prefill: boolean, modelValue: any) => Promise<Item[]>) \| ((query: string, prefill: boolean, modelValue: any) => Item[])` |  | yes | Array of items or async loader function. Loader functions receive `(query, prefill, modelValue)`; `modelValue` is the raw v-model: an array in `multiple` mode, the raw model value (possibly `null`) in single mode. |
| `itemText` | `string \| ((item: Item) => string) \| undefined` |  |  | Path or function to extract display text from an item. |
| `itemValue` | `string \| ((item: Item) => string) \| undefined` |  |  | Path or function to extract a value from an item. |
| `loading` | `boolean \| undefined` | `false` |  | Display the loading state. |
| `loadingText` | `string \| undefined` |  |  | Message shown while items are loading. |
| `max` | `number \| undefined` | `Infinity` |  | Maximum number of selectable items. |
| `maxSelectedLabels` | `number \| undefined` | `Infinity` |  | Maximum number of labels shown before collapsing to a count summary. When set, this takes precedence over width-based overflow detection. |
| `modelValue` | `any` |  | yes | v-model value. Array when `multiple` is true. |
| `modelValueDebounceTime` | `number \| undefined` | `0` |  | Debounce delay (ms) for modelValue change handling. |
| `multiple` | `boolean \| undefined` | `false` |  | Enable multiple item selection. Requires modelValue to be an array. |
| `name` | `string \| undefined` |  |  | Name attribute forwarded to hidden inputs for form submission. |
| `noDataText` | `string \| undefined` |  |  | Message displayed when no options match. |
| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile. |
| `placeholder` | `string \| undefined` |  |  | Placeholder text shown when no value is selected. |
| `prefill` | `boolean \| "interaction" \| undefined` | `"interaction"` |  | Controls when items are pre-loaded. `'interaction'` loads on first user interaction, `true` loads immediately, `false` is *search-first*: with a provider, nothing loads until the user types (opening alone does not), and the panel shows a "s… |
| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to render at the left hand side of the control. |
| `queryDebounceTime` | `number \| undefined` | `500` |  | Debounce delay (ms) before triggering search queries after user input. |
| `readonly` | `boolean \| undefined` | `false` |  | Make the control read-only while keeping the dropdown accessible. |
| `required` | `boolean \| undefined` | `false` |  | Marks the field as required for form validation. A visually-hidden sentinel input is used so native browser constraint validation fires. |
| `selectable` | `boolean \| ((item: Item) => boolean) \| undefined` | `true` |  | Defines whether options are selectable. Can be a global boolean that affects all options or a function that accepts an item and returns a boolean that only affects that item. Non-selectable options are rendered disabled. |
| `selectedLabelsFn` | `((count: number) => string) \| undefined` |  |  | Function to generate a summary label when selected items exceed `maxSelectedLabels` or overflow the control width. |
| `stash` | `boolean \| undefined` | `false` |  | Accumulate selected items across searches. |
| `transitionDuration` | `number \| undefined` | `250` |  | Transition duration (ms) for dropdown animations. Forwarded to `BbSelectPopover`, which supplies the default. |

## Events

- `active` — `(e: "active"): void`
- `blur` — `(e: "blur", event: FocusEvent): void`
- `change` — `(e: "change", event: Event): void`
- `click` — `(e: "click", event: MouseEvent): void`
- `focus` — `(e: "focus", event: FocusEvent): void`
- `inactive` — `(e: "inactive"): void`
- `input` — `(e: "input", event: Event): void`
- `option:add` — `(e: "option:add", text: string): void`
- `update:modelValue` — `(e: "update:modelValue", value: any): void`

## Slots

- `append` — scope: `BaseSelectActivatorSlotProps`
- `append-outer` — scope: `BaseSelectOuterSlotProps`
- `chip` — scope: `BaseSelectChipSlotProps<Item>` — Replaces the default badge rendered for each selection in `multiple` mode.
- `footer` — scope: `BaseSelectPanelSlotProps` — Content pinned to the bottom of the panel, below the options list.
- `group` — scope: `BaseSelectGroupSlotProps<Item>`
- `header` — scope: `BaseSelectPanelSlotProps` — Content pinned to the top of the panel, above the search field.
- `loading` — scope: `{ query: string; }`
- `no-data` — scope: `{ query: string; focus: () => void; }`
- `option` — scope: `BaseSelectOptionSlotProps<Item>`
- `prefix` — scope: `object`
- `prepend` — scope: `BaseSelectActivatorSlotProps`
- `prepend-outer` — scope: `BaseSelectOuterSlotProps`
- `suffix` — scope: `object`

---

<!-- dist/ai/BbBaseSlider.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseSlider.md -->

# BbBaseSlider

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Reference Only - Base Primitive**
- Description: Internal low-level slider primitive.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/BbBaseSlider.md](./source/BbBaseSlider.md)

## v-model

- `v-model` — type: `number \| number[] \| null`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of elements describing this slider for assistive technologies. |
| `autofocus` | `Booleanish \| undefined` |  |  | Focus the slider on mount. |
| `compact` | `boolean \| undefined` | `false` |  | Apply the compact density variant. |
| `disabled` | `boolean \| undefined` | `false` |  | Disable all interactions with the slider. |
| `disableThumbTranslate` | `boolean \| undefined` | `false` |  | Disables the proportional thumb translation that keeps thumbs centered on the track (enabled by default). Set it when displaying ticks for better alignment. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Apply error styling to the slider. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
| `id` | `string \| undefined` |  |  | Explicit id for the slider container. Used to generate ids for thumbs. |
| `max` | `number \| undefined` | `100` |  | Upper bound for slider values. |
| `maxPrecision` | `number \| undefined` | `2` |  | Maximum decimal places to retain in emitted values. |
| `min` | `number \| undefined` | `0` |  | Lower bound for slider values. |
| `modelValue` | `number \| number[] \| null` | `0` | yes | v-model value. Single number for single slider, two-element array for range. |
| `name` | `string \| undefined` |  |  | Defines the name of the input. |
| `range` | `boolean \| undefined` | `false` |  | Enable range selection with two thumbs. When true, modelValue must be an array. |
| `readonly` | `boolean \| undefined` | `false` |  | Make the slider read-only while keeping it visible. |
| `required` | `boolean \| undefined` | `false` |  | Mark the slider as required. |
| `step` | `number \| undefined` | `1` |  | Granularity step for value changes via keyboard or pointer interaction. |
| `ticks` | `boolean \| undefined` | `false` |  | Show tick marks at each step interval. |

## Events

- `active` — `(event: "active"): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `inactive` — `(event: "inactive"): void`
- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
- `pointerdown` — `(event: "pointerdown", event: PointerEvent): void`
- `pointermove` — `(event: "pointermove", event: PointerEvent): void`
- `pointerup` — `(event: "pointerup", event: PointerEvent): void`
- `update:modelValue` — `(event: "update:modelValue", value: number \| number[]): void`

## Slots

- `append` — scope: `BaseSliderStepSlotProps` — Content rendered after the slider track, typically used to add a max-value label or button.
- `prepend` — scope: `BaseSliderStepSlotProps` — Content rendered before the slider track, typically used to add a min-value label or button.
- `thumb` — scope: `BaseSliderThumbSlotProps` — Fallback thumb used for non-range sliders (or inside `thumb:higher`/`thumb:lower` when not overridden separately).
- `thumb:higher` — scope: `BaseSliderThumbSlotProps` — Replaces the default higher-value thumb in range mode (`range: true`).
- `thumb:lower` — scope: `BaseSliderThumbSlotProps` — Replaces the default lower-value thumb in range mode (`range: true`).
- `tick` — scope: `BaseSliderTickSlotProps` — Replaces the default tick mark rendered at each step when ticks are enabled.

---

<!-- dist/ai/BbBaseSwitch.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseSwitch.md -->

# BbBaseSwitch

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Reference Only - Base Primitive**
- Description: Internal low-level switch primitive.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/BbBaseSwitch.md](./source/BbBaseSwitch.md)

## v-model

- `v-model` — type: `any`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `ariaDescribedby` | `string \| undefined` |  |  | ID of the element that describes this checkbox for assistive technologies. Forwarded to the input as `aria-describedby`. |
| `autofocus` | `Booleanish \| undefined` | `false` |  | Automatically focuses the checkbox when the page/component loads. Use sparingly to avoid usability issues. |
| `checked` | `boolean \| undefined` | `undefined` |  | Forces the checkbox checked state (controlled prop). When omitted, the checked state is derived from `modelValue === trueValue`. Deliberately `undefined` rather than `false`, so "unset" stays distinguishable from an explicit `:checked="fals… |
| `disabled` | `boolean \| undefined` | `false` |  | Disables user interaction. Also applied when `readonly` is set, since native checkboxes do not support `readonly`. |
| `falseValue` | `any` | `false` |  | Value submitted/emitted when the checkbox is unchecked. Accepts any serializable value. Serialized to a string for form submission. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Puts the component into an error state (adds error styling class `bb-base-checkbox--errors`). |
| `hasWarning` | `boolean \| undefined` | `false` |  | Puts the component into a warning state (adds `bb-base-checkbox--warnings`). Errors take priority when both are set. |
| `id` | `string \| undefined` |  |  | Identifier forwarded to the input. |
| `indeterminate` | `boolean \| undefined` | `false` |  | Renders the checkbox in the indeterminate state (neither checked nor unchecked). Note: the native `indeterminate` state resets on user click; this component re-applies it to keep UI and prop aligned. |
| `modelValue` | `any` |  |  | Bound value for `v-model`. When it equals `trueValue` the checkbox is considered checked, otherwise unchecked. |
| `name` | `string \| undefined` |  |  | Name attribute of the input, used during form submission. |
| `readonly` | `boolean \| undefined` | `false` |  | Puts the input in a read-only state. Since checkboxes do not support native `readonly`, the input is disabled while styled as read-only. |
| `required` | `boolean \| undefined` | `false` |  | Marks the input as required for form validation. |
| `submitWhenFalse` | `boolean \| undefined` | `false` |  | When unchecked, submits a hidden input with `falseValue` so that a value is still posted with the form. When checked, the visible input submits `trueValue` as usual. |
| `trueValue` | `any` | `true` |  | Value submitted/emitted when the checkbox is checked. Accepts any serializable value. Serialized to a string for form submission. |

## Events

- `blur` — `(event: "blur", event: FocusEvent): void`
- `change` — `(event: "change", event: Event): void`
- `click` — `(event: "click", event: MouseEvent): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `input` — `(event: "input", event: Event): void`
- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
- `update:modelValue` — `(event: "update:modelValue", value: any): void`

## Slots

- `icon` — scope: `BaseCheckboxIconSlotProps`

---

<!-- dist/ai/BbBaseSwitchGroup.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseSwitchGroup.md -->

# BbBaseSwitchGroup

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Reference Only - Base Primitive**
- Description: Internal low-level grouped switch primitive.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/BbBaseSwitchGroup.md](./source/BbBaseSwitchGroup.md)

## v-model

- `v-model` — type: `any`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `ariaDescribedby` | `string \| undefined` |  |  | ID of the element that describes the entire checkbox group for assistive technologies. Forwarded to each generated input as `aria-describedby`. |
| `autofocus` | `Booleanish \| undefined` | `false` |  | Automatically focuses the first checkbox on mount when true. Applied only to the first option. |
| `dependencies` | `unknown[] \| undefined` | `[]` |  | List of reactive values which, when changed, trigger items re-fetching. Useful to reload options based on external inputs. |
| `depsDebounceTime` | `number \| undefined` | `0` |  | Debounce delay (ms) applied when reacting to `dependencies` changes. |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `"horizontal"` |  | Direction of the group layout. - `horizontal`: options flow in rows - `vertical`: options stack in a column |
| `disabled` | `boolean \| undefined` | `false` |  | Disables interaction for the whole group. |
| `enforceCoherence` | `boolean \| undefined` | `false` |  | Enforces that `modelValue` contains only values present in `items`. Incoherent values are removed and `update:modelValue` is emitted with a coherent array. Please check out {@link https://ui-components-docs.vercel.app/it/guides/coherence th… |
| `hasErrors` | `boolean \| undefined` | `false` |  | Puts the component into an error state adds the error styling class. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Puts the component into a warning state. Errors take priority when both are set. |
| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides each option's label text (the text rendered next to every input) while keeping it accessible to screen readers. |
| `id` | `string \| undefined` |  |  | Identifier of the group. Used to derive per-option IDs for accessible labeling. |
| `items` | `T[] \| ((prefill: boolean, modelValue?: any) => T[] \| Promise<T[]>)` | `[]` | yes | Items provider. Can be: - An array of items - A sync/async function `(prefill, modelValue) => items` When a function is provided, it is invoked on prefill and when dependencies change to load options dynamically. |
| `itemText` | `(T extends object ? string \| ((item: T) => string) : (item: T) => string) \| undefined` | `JSON.stringify(item)` |  | Defines how to derive the display text from an item. Accepts a nested key path into the item or a function `(item) => string`. |
| `itemValue` | `(T extends object ? string \| ((item: T) => string) : (item: T) => any) \| undefined` | `JSON.stringify(item)` |  | Defines how to derive the value from an item. Accepts a nested key path into the item or a function `(item) => any`. |
| `loadingText` | `string \| undefined` | `'Loading...'` |  | Text displayed while items are loading. |
| `max` | `number \| undefined` | `Infinity` |  | Maximum number of selectable items. |
| `modelValue` | `any` |  | yes | Selected values for the group. Used with `v-model`. Single value when `multiple` is false, array when `multiple` is true. |
| `modelValueDebounceTime` | `number \| undefined` | `0` |  | Debounce delay (ms) applied when reacting to `modelValue` changes. |
| `multiple` | `boolean \| undefined` | `true` |  | Enables multi-selection behavior. When `true`, `modelValue` must be an array and emitted updates are arrays. When `false`, `modelValue` must be a single value (or `null`) and emitted updates are single values. |
| `name` | `string \| undefined` |  |  | Name attribute applied to each input for form submission. |
| `noDataText` | `string \| undefined` | `'No data to display'` |  | Text displayed when there are no items to show. |
| `readonly` | `boolean \| undefined` | `false` |  | Makes all checkboxes read-only. Since checkboxes do not support native `readonly`, inputs are disabled while styled as read-only. |
| `selectable` | `boolean \| ((item: T) => boolean) \| undefined` | `true` |  | Defines whether options are selectable. Can be a global boolean that affects all options or a function that accepts an item and returns a boolean that only affects that item. Non-selectable options are rendered disabled. |

## Events

- `active` — `(e: "active"): void` — Emitted when the group becomes active (focus/click enters it).
- `blur` — `(e: "blur", event: FocusEvent): void` — Emitted when one of the generated checkbox inputs loses focus. Forwards the original DOM `FocusEvent`.
- `change` — `(e: "change", event: Event): void` — Emitted when an option is toggled. Forwards the original DOM `Event` from the checkbox input.
- `click` — `(e: "click", event: MouseEvent): void` — Emitted when one of the generated checkbox inputs is clicked. Forwards the original DOM `MouseEvent`.
- `focus` — `(e: "focus", event: FocusEvent): void` — Emitted when one of the generated checkbox inputs receives focus. Forwards the original DOM `FocusEvent`.
- `inactive` — `(e: "inactive"): void` — Emitted when focus/click moves outside the group after it was active. Useful for validation-on-blur flows at group level.
- `input` — `(e: "input", event: Event): void` — Emitted on native input events from generated checkbox inputs. Forwards the original DOM `Event`.
- `keydown` — `(e: "keydown", event: KeyboardEvent): void` — Emitted for keyboard interaction on generated checkbox inputs. Forwards the original DOM `KeyboardEvent`.
- `mousedown` — `(e: "mousedown", event: MouseEvent): void` — Emitted when a pointing device button is pressed over a checkbox input. Forwards the original DOM `MouseEvent`.
- `mouseup` — `(e: "mouseup", event: MouseEvent): void` — Emitted when a pointing device button is released over a checkbox input. Forwards the original DOM `MouseEvent`.
- `update:modelValue` — `(e: "update:modelValue", value: any): void` — Emitted with the coherent next selection array whenever selection changes.

## Slots

- `append` — scope: `BaseCheckboxGroupEmptySlotProps` — Content rendered after the last option, inside the options container.
- `icon` — scope: `BaseCheckboxGroupIconSlotProps<T>` — Replaces the default checkmark icon for each checkbox option. Receives all `BaseCheckbox` slot attributes plus the source item and its display text.
- `label` — scope: `BaseCheckboxGroupLabelSlotProps<T>` — Replaces the default label text for each option.
- `loading` — scope: `BaseCheckboxGroupEmptySlotProps` — Content shown while options are loading (replaces the default loading text).
- `no-data` — scope: `BaseCheckboxGroupEmptySlotProps` — Content shown when no options are available (replaces the default "no data" text).
- `prepend` — scope: `BaseCheckboxGroupEmptySlotProps` — Content rendered before the first option, inside the options container.

---

<!-- dist/ai/BbBaseSwitchIcon.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseSwitchIcon.md -->

# BbBaseSwitchIcon

## Agent Contract

- Safety level: **Consumer API**
- Group: **Selection**
- Description: Standalone switch glyph (track + thumb). Presentational only — no input, no events. Compose it into a fully custom switch design, or let BbSwitch/BbBaseSwitch render it.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbBaseSwitchIcon.md](./source/BbBaseSwitchIcon.md)

## Usage & Guidelines

### What this is (and when to reach for it)

`BbBaseSwitchIcon` is **only the visual** — the pill track and the thumb that slides
across it — extracted from `BbBaseSwitch`. It has no native `<input>`, emits no
events, and holds no state. You tell it how to look through boolean props; it
draws that state.

For virtually every form you should use [`BbSwitch`](./BbSwitch.md) or
[`BbSwitchGroup`](./BbSwitchGroup.md) — they wire up the input, `v-model`,
label, `role="switch"` semantics, validation and accessibility for you. Reach
for `BbBaseSwitchIcon` only when the surrounding design can't be expressed as a
labelled switch row: a settings list with a bespoke layout, a toolbar toggle, a
compact inline control. In those cases you own the real control (a native
checkbox with `role="switch"`) and drop the glyph in for the visuals.

**Every visual state**

```vue
<div class="flex items-center gap-4">
	<BbBaseSwitchIcon :checked="false" />
	<BbBaseSwitchIcon :checked="true" />
	<BbBaseSwitchIcon :indeterminate="true" />
	<BbBaseSwitchIcon :checked="true" :disabled="true" />
	<BbBaseSwitchIcon :checked="true" :has-errors="true" />
	<BbBaseSwitchIcon :checked="true" :focus-visible="true" />
</div>
```

### Compose it into a custom control

The glyph is decorative (`aria-hidden`), so it **must** be paired with a real
control. The reliable pattern: a `<label>` wrapping a visually-hidden native
`<input type="checkbox" role="switch">` (keep it in the a11y tree with `sr-only`,
never `display:none`) plus the glyph reflecting `checked`. You get native
keyboard support, focus, and switch semantics for free.

**Feature flag rows**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Workspace experiments</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Northwind Billing · flags apply to every seat
			</p>
		</div>

		<div class="flex flex-col divide-y rounded-[var(--bb-radius)] border">
			<label
				v-for="flag in flags"
				:key="flag.id"
				class="flex cursor-pointer items-center justify-between gap-3 px-2.5 py-2 hover:bg-[color:var(--bb-surface-hover)]"
			>
				<span class="flex min-w-0 flex-col">
					<span class="text-sm font-medium">{{ flag.label }}</span>
					<span class="text-xs text-[color:var(--bb-text-muted)]">{{
						flag.hint
					}}</span>
				</span>
				<!-- Glyph tracks state; the checkbox + role="switch" owns a11y. -->
				<input
					v-model="state[flag.id]"
					class="sr-only"
					role="switch"
					type="checkbox"
				/>
				<BbBaseSwitchIcon :checked="state[flag.id]" />
			</label>
		</div>
	</div>
</template>

<script setup lang="ts">
import { reactive } from 'vue';
import { BbBaseSwitchIcon } from 'bitboss-ui';

type Flag = { id: string; label: string; hint: string };

const flags: Flag[] = [
	{
		id: 'editor',
		label: 'New invoice editor',
		hint: 'Block editor with slash commands',
	},
	{
		id: 'summaries',
		label: 'AI thread summaries',
		hint: 'Condense long invoice threads',
	},
	{
		id: 'analytics',
		label: 'Usage analytics',
		hint: 'Anonymized retention metrics',
	},
];

// Keep one flag on so the guide test’s checked-count contract stays stable.
const state = reactive<Record<string, boolean>>({
	editor: true,
	summaries: false,
	analytics: false,
});
</script>
```

### Styling

Restyle by overriding the glyph's CSS custom properties on it:

- `--w` / `--h` — track width / height (default `32px` / `18px`)
- `--thumb` — thumb diameter (default `16px`)
- `--color` — track fill when checked (default `--bb-primary`)
- `--bg-color` — track fill when off (default `--bb-track`)
- `--radius` — track/thumb rounding (default `999px`)

**On the element itself, not an ancestor.** Each of these is declared on the
glyph's own class, and a declaration on the element always beats one inherited
from an ancestor — so `--w` set on a wrapper `div` is simply ignored
(verified: the glyph keeps its shipped size). Target the glyph class, or pass a `style` /
`class` that lands on it:

```css
/* works */
.bb-base-switch-icon {
	--w: 40px;
	--h: 22px;
	--thumb: 18px;
}
/* does nothing */
.my-form {
	--w: 40px;
}
```

**Larger and recolored**

```vue
<BbBaseSwitchIcon
	:checked="true"
	style="--w: 48px; --h: 26px; --thumb: 22px; --color: #16a34a"
/>
```

### Gotchas & anti-patterns

- **Don't ship it as the whole control.** It is `aria-hidden` and non-focusable;
  on its own it is invisible to keyboard and screen-reader users. Always back it
  with a real `<input>` (ideally `role="switch"`).
- **Don't reach for it when `BbSwitch` fits.** If you need a labelled switch in a
  form, `BbSwitch`/`BbSwitchGroup` already do everything.
- `indeterminate` wins over `checked` visually — a glyph that is both parks the
  thumb at the midpoint of its travel, matching `BbBaseSwitch`.
- It reflects state, it doesn't manage it: clicking the glyph does nothing by
  itself. Toggle your own state (or the backing input) and pass `checked` back.

### Works well with

- [`BbSwitch`](./BbSwitch.md) / [`BbSwitchGroup`](./BbSwitchGroup.md) — the
  batteries-included switches; prefer them unless you truly need the bare glyph.
- [`BbBaseCheckboxIcon`](./BbBaseCheckboxIcon.md) /
  [`BbBaseRadioIcon`](./BbBaseRadioIcon.md) — the matching standalone glyphs for
  checkboxes and radios.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `checked` | `boolean \| undefined` | `false` |  | Renders the checked state (fills the track and slides the thumb to the end). |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the glyph (muted track, not-allowed cursor). Purely visual. |
| `focusVisible` | `boolean \| undefined` | `false` |  | Whether keyboard focus is visible (`:focus-visible`). Draws the focus ring. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Puts the glyph into the error state (danger border and ring color). |
| `hasWarning` | `boolean \| undefined` | `false` |  | Puts the glyph into the warning state (warn border and ring color). Errors take priority when both are set. |
| `indeterminate` | `boolean \| undefined` | `false` |  | Renders the indeterminate state (filled track with the thumb parked at the midpoint of its travel). Takes visual precedence over `checked`. |
| `readonly` | `boolean \| undefined` | `false` |  | Renders the read-only affordance. Reserved for parity with the other glyphs; currently has no distinct visual. |

## Events

- None.

## Slots

- None.

## See Also

- [BbSwitch](./BbSwitch.md) — Toggles two-state values with switch semantics.
- [BbBaseSwitch](./BbBaseSwitch.md) — Internal low-level switch primitive.
- [BbBaseCheckboxIcon](./BbBaseCheckboxIcon.md) — Standalone checkbox glyph (box + checkmark SVG). Presentational only — no input, no events. Compose it into a fully custom checkbox design, or let BbCheckbox/BbBaseCheckbox render it.
- [BbBaseRadioIcon](./BbBaseRadioIcon.md) — Standalone radio glyph (ring + dot). Presentational only — no input, no events. Compose it into a fully custom radio design, or let BbRadio/BbBaseRadio render it.

---

<!-- dist/ai/BbBaseTag.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseTag.md -->

# BbBaseTag

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Reference Only - Base Primitive**
- Description: Internal low-level tag input primitive.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/BbBaseTag.md](./source/BbBaseTag.md)

## v-model

- `v-model` — type: `string[]`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `append:icon` | `string \| undefined` |  |  | Name of the icon to render at the right hand side of the input. |
| `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of elements describing this tag input for assistive technologies. |
| `autocomplete` | `string \| undefined` | `"off"` |  | Browser autocomplete hint for the input field. |
| `autofocus` | `Booleanish \| undefined` |  |  | Focus the input automatically on mount. |
| `caseSensitive` | `boolean \| undefined` | `false` |  | Compare tags case-sensitively when rejecting duplicates, so `Vue` and `vue` can both exist. By default matching folds case, because two chips differing only in case read as duplicates to a user. Either way the tag is stored with the casing … |
| `clearable` | `boolean \| undefined` | `false` |  | Show a clear button whenever tags are present and the control is interactive. |
| `comma` | `boolean \| undefined` | `false` |  | Display selected tags as a comma-separated string instead of individual chips. When enabled, tags cannot be deselected by clicking individual chips. |
| `compact` | `boolean \| undefined` | `false` |  | Apply the compact density variant. |
| `disabled` | `boolean \| undefined` | `false` |  | Disable all interactions with the tag input. |
| `divider` | `string \| string[] \| undefined` | `"Enter"` |  | Keyboard key that triggers tag creation from current input value. Accepts a single key or an array of keys (e.g. `['Enter', ',']`) — any of them commits the current text. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Apply error styling to the tag input. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
| `id` | `string \| undefined` |  |  | Explicit id for the input element. |
| `loading` | `boolean \| undefined` | `false` |  | Display the loading state styles. |
| `max` | `number \| undefined` |  |  | Maximum number of tags that can be created. |
| `modelValue` | `string[]` |  | yes | v-model value for selected tags. |
| `name` | `string \| undefined` |  |  | Name attribute forwarded to the input element. |
| `placeholder` | `string \| undefined` |  |  | Placeholder text when no tags are present. |
| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to render at the left hand side of the input. |
| `readonly` | `boolean \| undefined` | `false` |  | Make the input read-only while keeping tags visible. |
| `required` | `boolean \| undefined` | `false` |  | Mark the input as required for form validation. |

## Events

- `active` — `(event: "active"): void`
- `blur` — `(event: "blur", event: FocusEvent): void`
- `change` — `(event: "change", event: Event): void`
- `click` — `(event: "click", event: MouseEvent): void`
- `compositionend` — `(event: "compositionend", event: CompositionEvent): void`
- `compositionstart` — `(event: "compositionstart", event: CompositionEvent): void`
- `duplicate` — `(event: "duplicate", string: string): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `inactive` — `(event: "inactive"): void`
- `input` — `(event: "input", event: Event): void`
- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
- `keyup` — `(event: "keyup", event: KeyboardEvent): void`
- `max` — `(event: "max", string: string): void`
- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
- `paste` — `(event: "paste", event: ClipboardEvent): void`
- `update:modelValue` — `(event: "update:modelValue", value: string[]): void`

## Slots

- `append` — scope: `Record<string, never>` — Content rendered after the tag input, at the end of the inner container.
- `append-outer` — scope: `Record<string, never>` — Content rendered after the entire tag input control, outside the input chrome.
- `prefix` — scope: `Record<string, never>` — Inline content rendered at the start of the input field area, before the typed text.
- `prepend` — scope: `Record<string, never>` — Content rendered before the tag input, at the start of the inner container.
- `prepend-outer` — scope: `Record<string, never>` — Content rendered before the entire tag input control, outside the input chrome.
- `suffix` — scope: `Record<string, never>` — Inline content rendered at the end of the input field area, after the typed text.

---

<!-- dist/ai/BbBaseTextarea.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseTextarea.md -->

# BbBaseTextarea

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Reference Only - Base Primitive**
- Description: Internal low-level textarea primitive.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/BbBaseTextarea.md](./source/BbBaseTextarea.md)

## v-model

- `v-model` — type: `string \| null`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `append:icon` | `string \| undefined` |  |  | Name of the icon to render at the right hand side of the textarea. |
| `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of elements describing this textarea for assistive technologies. |
| `autocomplete` | `string \| undefined` |  |  | Browser autocomplete hint for the textarea. |
| `autofocus` | `Booleanish \| undefined` |  |  | Focus the textarea automatically on mount. |
| `autoGrow` | `boolean \| undefined` | `false` |  | Automatically expand the textarea height to fit its content. Composes with `rows`: when both are set, `rows` acts as the minimum-height floor the field grows past but never shrinks below. |
| `clearable` | `boolean \| undefined` | `false` |  | Show a clear button whenever text is present and the control is interactive. |
| `compact` | `boolean \| undefined` | `false` |  | Apply the compact density variant. |
| `disabled` | `boolean \| undefined` | `false` |  | Disable all interactions with the textarea. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Apply error styling to the textarea. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
| `id` | `string \| undefined` |  |  | Explicit id for the textarea element. |
| `loading` | `boolean \| undefined` | `false` |  | Display the loading state styles. |
| `modelValue` | `string \| null` |  | yes | v-model value: the text content, or `null` when empty. |
| `name` | `string \| undefined` |  |  | Name attribute forwarded to the textarea element. |
| `placeholder` | `string \| undefined` |  |  | Placeholder text when no value is present. |
| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to render at the left hand side of the textarea. |
| `readonly` | `boolean \| undefined` | `false` |  | Make the textarea read-only while keeping it visible. |
| `required` | `boolean \| undefined` | `false` |  | Mark the textarea as required for form validation. |
| `rows` | `string \| number \| undefined` |  |  | Number of visible rows. Without `autoGrow` this is the fixed height; with `autoGrow` it becomes the minimum-height floor the field grows past but never shrinks below. |

## Events

- `blur` — `(event: "blur", event: FocusEvent): void`
- `change` — `(event: "change", event: Event): void`
- `click` — `(event: "click", event: MouseEvent): void`
- `compositionend` — `(event: "compositionend", event: CompositionEvent): void`
- `compositionstart` — `(event: "compositionstart", event: CompositionEvent): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `input` — `(event: "input", event: Event): void`
- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
- `keyup` — `(event: "keyup", event: KeyboardEvent): void`
- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
- `paste` — `(event: "paste", event: ClipboardEvent): void`
- `update:modelValue` — `(event: "update:modelValue", value: string \| null): void`

## Slots

- `append` — scope: `Record<string, never>` — Content rendered after the textarea, at the end of the inner container.
- `append-outer` — scope: `Record<string, never>` — Content rendered after the entire textarea control, outside the input chrome.
- `prefix` — scope: `Record<string, never>` — Inline content rendered at the start of the textarea field area, before the text.
- `prepend` — scope: `Record<string, never>` — Content rendered before the textarea, at the start of the inner container.
- `prepend-outer` — scope: `Record<string, never>` — Content rendered before the entire textarea control, outside the input chrome.
- `suffix` — scope: `Record<string, never>` — Inline content rendered at the end of the textarea field area, after the text.

---

<!-- dist/ai/BbBaseTextInput.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseTextInput.md -->

# BbBaseTextInput

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Reference Only - Base Primitive**
- Description: Internal low-level text input primitive.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/BbBaseTextInput.md](./source/BbBaseTextInput.md)

## v-model

- `v-model` — type: `string \| null`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `append:icon` | `string \| undefined` |  |  | Name of the icon to render at the right hand side of the input. |
| `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of elements describing this input for assistive technologies. |
| `autocomplete` | `string \| undefined` |  |  | Browser autocomplete hint for the input field. |
| `autofocus` | `Booleanish \| undefined` |  |  | Focus the input automatically on mount. |
| `clearable` | `boolean \| undefined` | `false` |  | Show a clear button whenever a value is present and the control is interactive. |
| `compact` | `boolean \| undefined` | `false` |  | Apply the compact density variant. |
| `disabled` | `boolean \| undefined` | `false` |  | Disable all interactions with the input. |
| `emitMasked` | `boolean \| undefined` | `false` |  | When using a mask, emit the formatted (masked) value instead of the raw input. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Apply error styling to the input and set `aria-invalid`. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
| `id` | `string \| undefined` |  |  | Explicit id for the input element. |
| `inputMode` | `"text" \| "search" \| "email" \| "url" \| "tel" \| "none" \| "numeric" \| "decimal" \| undefined` |  |  | Input mode hint for mobile keyboards. |
| `labelMode` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Label rendering mode, forwarded by wrapper components. |
| `loading` | `boolean \| undefined` | `false` |  | Display the loading state styles. |
| `mask` | `MaskInputOptions \| undefined` |  |  | Input mask configuration. When provided, enables formatted input with validation. |
| `max` | `string \| undefined` |  |  | Maximum value for numeric and date inputs. |
| `maxlength` | `number \| undefined` |  |  | Maximum number of characters the input will accept. |
| `min` | `string \| undefined` |  |  | Minimum value for numeric and date inputs. |
| `modelValue` | `string \| null` |  | yes | v-model value: the input text, or `null` when empty. |
| `name` | `string \| undefined` |  |  | Name attribute forwarded to the input element. |
| `placeholder` | `string \| undefined` |  |  | Placeholder text when no value is present. |
| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to render at the left hand side of the input. |
| `readonly` | `boolean \| undefined` | `false` |  | Make the input read-only while keeping it visible. |
| `required` | `boolean \| undefined` | `false` |  | Mark the input as required for form validation. |
| `step` | `string \| undefined` |  |  | Stepping interval for numeric and date inputs. |
| `type` | `"text" \| "search" \| "email" \| "url" \| "tel" \| "password" \| undefined` | `"text"` |  | HTML input type attribute. Restricted to the textual input types this component supports — use `BbNumberInput` for numbers and `BbDatePickerInput` for dates. |

## Events

- `blur` — `(event: "blur", event: FocusEvent): void`
- `change` — `(event: "change", event: Event): void`
- `click` — `(event: "click", event: MouseEvent): void`
- `compositionend` — `(event: "compositionend", event: CompositionEvent): void`
- `compositionstart` — `(event: "compositionstart", event: CompositionEvent): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `input` — `(event: "input", event: Event): void`
- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
- `keyup` — `(event: "keyup", event: KeyboardEvent): void`
- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
- `paste` — `(event: "paste", event: ClipboardEvent): void`
- `update:modelValue` — `(event: "update:modelValue", value: string \| null): void`

## Slots

- `append` — scope: `object` — Content rendered after the text input, at the end of the inner container.
- `append-outer` — scope: `object` — Content rendered after the entire text input control, outside the input chrome.
- `prefix` — scope: `object` — Inline content rendered at the start of the input field area, before the typed text.
- `prepend` — scope: `object` — Content rendered before the text input, at the start of the inner container.
- `prepend-outer` — scope: `object` — Content rendered before the entire text input control, outside the input chrome.
- `suffix` — scope: `object` — Inline content rendered at the end of the input field area, after the typed text.

## Exposed (template ref)

- `blur`: `() => void \| undefined`
- `focus`: `() => void \| undefined`
- `select`: `() => void \| undefined`

---

<!-- dist/ai/BbBaseTimePickerInput.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBaseTimePickerInput.md -->

# BbBaseTimePickerInput

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Reference Only - Base Primitive**
- Description: Internal low-level time-picker input primitive.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/BbBaseTimePickerInput.md](./source/BbBaseTimePickerInput.md)

## v-model

- `v-model` — type: `string \| string[] \| null`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile the time columns open inside a bottom off-canvas sheet instead of a floating popover. When unset, falls back to the global `config.adaptive`. |
| `ampm` | `boolean \| undefined` | `false` |  | 12-hour display with an AM/PM segment. Purely a field-composition concern: the model stays 24-hour. Type `A`/`P` (or ArrowUp/Down) to set the meridiem. |
| `append:icon` | `string \| undefined` |  |  | Name of the icon to render at the right hand side of the input. |
| `ariaDescribedby` | `string \| undefined` |  |  | Additional description id(s) announced by assistive technologies. |
| `autocomplete` | `string \| undefined` | `"off"` |  | Browser autocomplete hint for the input. |
| `autofocus` | `Booleanish \| undefined` |  |  | Focus the first text field automatically when the component mounts. |
| `clearable` | `boolean \| undefined` | `false` |  | Displays a clear button whenever a value is present and the control is interactive. |
| `compact` | `boolean \| undefined` | `false` |  | Applies the compact density styles to the control. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the input, clock trigger, and popover. |
| `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` | `false` |  | Controls whether manual typing is disabled inside the text fields. Use `'mobile'` / `'desktop'` to disable typing on one platform only. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Marks the control as invalid, applying error styles and `aria-invalid`. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Apply warning styling (same chrome as errors, `--bb-warn` color). Suppressed when `hasErrors` is also set. |
| `id` | `string \| undefined` |  |  | Explicit id for the input element. Falls back to an auto-generated value. |
| `loading` | `boolean \| undefined` | `false` |  | Shows loading visuals on the input. |
| `max` | `string \| undefined` |  |  | Maximum selectable time in `HH:mm` format. Values outside the pattern throw during setup to surface configuration mistakes. |
| `min` | `string \| undefined` |  |  | Minimum selectable time in `HH:mm` format. Values outside the pattern throw during setup to surface configuration mistakes. |
| `modelValue` | `string \| string[] \| null` |  | yes | v-model value: `null` for empty, a 24-hour `HH:mm` (or `HH:mm:ss` with `seconds`) string, or a two-element array when `range` is true. |
| `name` | `string \| undefined` |  |  | Name attribute forwarded to the native inputs (suffixed per field). |
| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile (e.g. `title`, `size`, `persistent`). |
| `placeholder` | `string \| undefined` |  |  | Placeholder shown when empty; defaults to the localized format hint. |
| `prepend:icon` | `string \| undefined` |  |  | Icon name rendered before the input field. |
| `range` | `boolean \| undefined` | `false` |  | Range selection: v-model expects a two-element array `[start, end]`. An inverted pair swaps on finalize with an `end_before_start` error. |
| `readonly` | `boolean \| undefined` | `false` |  | Makes the text fields read-only and prevents opening the popover. |
| `required` | `boolean \| undefined` | `false` |  | Marks the inputs as required to the browser. |
| `seconds` | `boolean \| undefined` | `false` |  | Adds the seconds segment. Without it an incoming value carrying seconds displays truncated and zeroes out on the next user commit. |
| `step` | `number \| undefined` | `1` |  | Minute granularity for the minute column and its arrow stepping. Constrains what the columns produce, never what typing accepts. |
| `transitionDuration` | `number \| undefined` |  |  | Transition duration, in milliseconds, for the popover appearance. |

## Events

- `active` — `(event: "active"): void`
- `error` — `(event: "error", error: TimePickerInputError): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `inactive` — `(event: "inactive"): void`
- `update:modelValue` — `(event: "update:modelValue", value: string \| string[] \| null): void`

## Slots

- `append` — scope: `object` — Content rendered after the time fields (before the clock button).
- `append-outer` — scope: `object` — Content rendered after the entire control, outside the input chrome.
- `prefix` — scope: `object` — Inline content at the start of the field area.
- `prepend` — scope: `object` — Content rendered before the time fields, at the start of the inner container.
- `prepend-outer` — scope: `object` — Content rendered before the entire control, outside the input chrome.
- `suffix` — scope: `object` — Inline content at the end of the field area.

---

<!-- dist/ai/BbBreadcrumbs.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbBreadcrumbs.md -->

# BbBreadcrumbs

## Agent Contract

- Safety level: **Consumer API**
- Group: **Navigation**
- Description: Renders hierarchical navigation paths.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbBreadcrumbs.md](./source/BbBreadcrumbs.md)

## Usage & Guidelines

### When to use

Reach for `BbBreadcrumbs` to show the user's position inside a hierarchy and to
let them jump back up it: `Workspace → Project → Invoice #1042`. It answers
"where am I and how do I get back", so put it at the top of a detail view.

It is not a content switcher — for peer views of the _same_ page (Overview /
Activity / Settings) use `BbTabs`, and for stepping through a paged result set
use `BbPagination`. Show at most one breadcrumb trail per view.

### Build the trail from `items`

Each item is `{ key, text }` plus a navigation target. `key` must be unique (it
also becomes the crumb's named-slot name and the label fallback when `text` is
missing). Navigation is always the item's job — give a crumb an `href` (or
`to`, or an `onClick`) and it renders as a real link; **never** wrap a crumb in
your own click-to-route handler. Leave the **last** item without a target: it
is the current page, and the component marks it `aria-current="page"`
automatically.

**A page location trail**

```vue
<BbBreadcrumbs
	:items="[
		{ key: 'dashboard', text: 'Dashboard', href: '#dashboard' },
		{ key: 'billing', text: 'Billing', href: '#billing' },
		{ key: 'invoices', text: 'Invoices', href: '#invoices' },
		{ key: 'invoice', text: 'Invoice #1042' },
	]"
/>
```

A crumb accepts the standard `BbBaseButton` navigation surface: `href`, `to`,
`target`/`rel`, `replace`, `activeClass`/`exactActiveClass`, the Inertia visit
options (`method`, `data`, `headers`, `only`, `preserveScroll`,
`preserveState`, lifecycle hooks), plus `onClick` and a per-item `disabled`.
Three base-button props are deliberately **not** part of the item grammar:
`block`, `tag`, and `type`. Per-crumb icons use the item fields `prepend:icon`
and `append:icon` (rendered outside the link); reach for slots only when the
icon needs to vary beyond a static name.

`disabled` works at two levels: on one item (that crumb loses its `href` and
gains `aria-disabled`) or on the whole component (every crumb and the overflow
button freeze). Use it for trails pointing into content the user can no longer
open — never ship a dead link.

#### Settings › Team › Members

The classic product trail is a settings hierarchy with real links on every
ancestor. Hash `href`s keep the example from navigating away; in an app use
route paths or `to`.

**Settings › Team › Members**

```vue
<template>
	<div
		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
	>
		<div class="space-y-2 border-b border-[color:var(--bb-border)] p-3">
			<BbBreadcrumbs :items="trail" :offset-width="54" />
			<div class="flex flex-col gap-0.5">
				<p class="text-sm font-medium">Members</p>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					Northwind Billing · invite and manage workspace access.
				</p>
			</div>
		</div>

		<ul class="divide-y divide-[color:var(--bb-border)] px-3">
			<li
				v-for="member in members"
				:key="member.email"
				class="flex items-center justify-between gap-2 py-2 text-sm"
			>
				<span class="min-w-0 truncate">
					<span class="font-medium">{{ member.name }}</span>
					<span class="text-xs text-[color:var(--bb-text-muted)]">
						· {{ member.email }}</span
					>
				</span>
				<span class="shrink-0 text-xs text-[color:var(--bb-text-muted)]">{{
					member.role
				}}</span>
			</li>
		</ul>
	</div>
</template>

<script setup lang="ts">
import { BbBreadcrumbs } from 'bitboss-ui';
import type { BbBreadcrumbsItem } from 'bitboss-ui';

// Settings › Team › Members — routed trail. Ancestors use hash `href` so the
// crumb is a real link; the current page stays without a target.
const trail: BbBreadcrumbsItem[] = [
	{
		key: 'settings',
		text: 'Settings',
		href: '#settings',
		'prepend:icon': 'lucide:settings',
	},
	{
		key: 'team',
		text: 'Team',
		href: '#team',
		'prepend:icon': 'lucide:users',
	},
	{
		key: 'members',
		text: 'Members',
		'prepend:icon': 'lucide:user-round',
	},
];

const members = [
	{ name: 'Alex Rivera', email: 'alex@northwind.io', role: 'Owner' },
	{ name: 'Sam Chen', email: 'sam@northwind.io', role: 'Admin' },
	{ name: 'Jordan Lee', email: 'jordan@northwind.io', role: 'Editor' },
];
</script>
```

### Long trails collapse on their own

You do not manage overflow. When the trail is wider than its container the
**earliest** crumbs fold, root-first, into an ellipsis menu (a `BbDropdown`)
that lists the hidden levels — the current page and its nearest ancestors stay
visible. Hidden crumbs keep their full navigation target inside the menu, so
nothing becomes unreachable. Just pass the full `items` array and let the
component measure — narrow the frame below to watch it collapse.

**Overflow folds into an ellipsis menu**

```vue
<div class="max-w-xs">
	<BbBreadcrumbs
		:items="[
			{ key: 'workspace', text: 'Workspace', href: '#workspace' },
			{ key: 'engineering', text: 'Engineering', href: '#engineering' },
			{ key: 'frontend', text: 'Frontend', href: '#frontend' },
			{ key: 'design-system', text: 'Design System', href: '#design-system' },
			{ key: 'components', text: 'Components', href: '#components' },
			{ key: 'breadcrumbs', text: 'Breadcrumbs' },
		]"
	/>
</div>
```

The collapse math is an **estimate**, not a DOM measurement: item widths are
derived from their label text at the component's built-in type scale, then
compared with the observed container width on every resize (coalesced to one
recompute per frame). Estimation-side props tune it when reality diverges:

- `offset-width` — extra one-off pixels the estimator can't see: your
  `prepend`/`append`/per-item slot content. The single most common knob.
- `estimation-bias` — multiplier on every estimated item width; raise it if
  crumbs clip before collapsing (e.g. a wider custom font), lower it if the
  trail collapses too eagerly.
- `divider-width` / `gap-width` — tell the estimator about a resized divider
  slot or a changed gap (`gap-width` also drives the rendered gap).
- `ellipsis-width` — explicit reserved width when you replace the `ellipsis`
  slot with something wider than the default `…`.

Leave them all at their defaults until you see a wrong fold; then reach for the
one matching what you changed. There is no "max visible items" prop — the fold
point is always width-driven.

#### Give it a stable basis in a flex row

The component measures its own width to decide the fold, so in a flex parent —
a topbar with the trail on the left and a search/actions cluster on the right is
the classic case — hand it a **stable basis** and let the siblings hold their
size:

```vue
<div class="flex items-center justify-between gap-4">
	<!-- Takes the row's slack and shrinks/overflows on a stable basis. -->
	<BbBreadcrumbs class="min-w-0 flex-auto" :items="trail" />
	<div class="flex shrink-0 items-center gap-2"><!-- search, actions --></div>
</div>
```

Without `flex-auto` (`flex: 1 1 auto`) the trail is **content-sized**: every
overflow toggle changes its width, the resize observer sees the change and
recomputes, and the recompute toggles the width again — a per-frame feedback
loop that glitches visibly. `min-w-0` lets it actually shrink to trigger the
overflow menu; `shrink-0` on the sibling keeps the search/actions from being
squeezed first. The component now detects and aborts a runaway loop (and warns
in dev — `"BbBreadcrumbs: aborted a runaway resize→recompute loop"`), but that
warning is a smell: fix the container instead of relying on the guard.

### Leading icons and edge regions

Prefer the item fields `prepend:icon` / `append:icon` for a static glyph per
crumb (see Settings › Team › Members above). When you need richer edge content —
a status mark, a dynamic icon, or a fixed trail hint — use slots:

- `item:prepend` / `item:append` — before/after every crumb's label; scope is
  `{ item, index, text, disabled }`.
- `prepend` / `append` — fixed content on either end of the whole trail; scope
  is `{ disabled }`.

When slot (or icon) content adds width the estimator cannot see, set
`offset-width` so the collapse math stays honest.

**Trail hint via prepend + per-item icons**

```vue
<BbBreadcrumbs
	:offset-width="96"
	:items="[
		{ key: 'settings', text: 'Settings', href: '#settings' },
		{ key: 'notifications', text: 'Notifications' },
	]"
>
	<template #prepend>
		<span class="text-xs text-[color:var(--bb-text-muted)]">You are here</span>
	</template>
	<template #item:prepend="{ item }">
		<BbIcon
			class="mr-1"
			:icon="item.key === 'settings' ? 'lucide:settings' : 'lucide:bell'"
			size="14"
		/>
	</template>
</BbBreadcrumbs>
```

The `append` edge is the natural home for compact page actions on a detail
header — the trail says where you are, the actions act on what you're looking
at. Keep them `size="xs"` and account for them with `offset-width`:

**File header with trailing actions**

```vue
<template>
	<div
		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
	>
		<div
			class="flex items-center gap-2 border-b border-[color:var(--bb-border)] px-2.5 py-1.5"
		>
			<span
				class="min-w-0 flex-auto truncate text-xs text-[color:var(--bb-text-muted)]"
			>
				acme-ui / src / components
			</span>
			<span class="shrink-0 text-xs text-[color:var(--bb-text-muted)]"
				>12.4 KB · TSX</span
			>
		</div>

		<div class="p-3">
			<BbBreadcrumbs :items="items" :offset-width="130">
				<template #append>
					<span class="flex shrink-0 items-center gap-1.5">
						<BbButton href="#raw" size="xs" variant="outline">Raw</BbButton>
						<BbButton size="xs" variant="outline" @click="onCopyPath">
							{{ copied ? 'Copied' : 'Copy path' }}
						</BbButton>
					</span>
				</template>
			</BbBreadcrumbs>
		</div>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbBreadcrumbs, BbButton } from 'bitboss-ui';
import type { BbBreadcrumbsItem } from 'bitboss-ui';

// File-view header: trail says where you are; compact `append` actions act on
// the file. Declare their width with `offset-width` so overflow stays honest.
const items: BbBreadcrumbsItem[] = [
	{ key: 'repo', text: 'acme-ui', href: '#repo' },
	{ key: 'src', text: 'src', href: '#src' },
	{ key: 'components', text: 'components', href: '#components' },
	{ key: 'button', text: 'Button.tsx' },
];

const copied = ref(false);

/** Brief copy affordance; no clipboard write in the guide harness. */
const onCopyPath = () => {
	copied.value = true;
	setTimeout(() => {
		copied.value = false;
	}, 900);
};
</script>
```

### Own one crumb's label with its named slot

Every item also gets a slot named after its `key`, replacing that crumb's
default text (same scope as `item:prepend`). Use it when a single crumb needs
richer content — a status dot on the current record, a badge on one level —
while the rest of the trail stays plain. Because keys become slot names, avoid
keys that collide with the reserved slots (`prepend`, `append`, `divider`,
`ellipsis`, `item:prepend`, `item:append`).

**A status dot on the current record**

```vue
<BbBreadcrumbs
	:items="[
		{ key: 'deployments', text: 'Deployments', href: '#deployments' },
		{ key: 'release', text: 'v2.4.0' },
	]"
>
	<template #release="{ text }">
		<span class="inline-flex items-center gap-1.5">
			<span
				class="size-2 rounded-full bg-[color:var(--bb-primary)]"
			></span>
			{{ text }}
		</span>
	</template>
</BbBreadcrumbs>
```

### Custom divider and overflow button

The `divider` slot replaces the separator between crumbs (the default is a
small chevron icon — there is **no** `divider` prop). Dividers are decorative
and stay `aria-hidden`. The `ellipsis` slot replaces the content of the
overflow button; its scope includes `overflowCount` (how many crumbs are
hidden), so the trigger can say how much is folded. If your replacement is
wider than `…`, pair it with `ellipsis-width`.

**Slash dividers and a counting overflow button**

```vue
<div class="max-w-56">
	<BbBreadcrumbs
		:ellipsis-width="40"
		:items="[
			{ key: 'library', text: 'Library', href: '#library' },
			{ key: 'photos', text: 'Photos', href: '#photos' },
			{ key: 'albums', text: 'Albums', href: '#albums' },
			{ key: 'summer', text: 'Summer 2026' },
		]"
	>
		<template #divider>
			<span class="text-[color:var(--bb-text-muted)]">/</span>
		</template>
		<template #ellipsis="{ overflowCount }">
			<span class="text-xs font-medium">+{{ overflowCount }}</span>
		</template>
	</BbBreadcrumbs>
</div>
```

### In-app trails without URLs

When the hierarchy lives in client state (a file browser, a nested picker)
rather than in routes, give **ancestor** crumbs an `onClick` and leave the
current level without a target. The component still renders proper buttons and
keeps `aria-current` on the last crumb — you only supply the handler. Crumbs
folded into the overflow menu keep their `onClick` too.

**File-browser path**

```vue
<template>
	<div
		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
	>
		<div
			class="flex items-center gap-1.5 border-b border-[color:var(--bb-border)] px-2.5 py-1.5"
		>
			<BbIcon
				class="text-[color:var(--bb-text-muted)]"
				icon="lucide:folder"
				size="sm"
			/>
			<span class="text-xs font-medium">Files</span>
			<span class="ml-auto text-xs text-[color:var(--bb-text-muted)]"
				>northwind-docs</span
			>
		</div>

		<div class="space-y-2 p-3">
			<BbBreadcrumbs :items="items" :offset-width="iconOffset" />
			<ul class="divide-y divide-[color:var(--bb-border)] text-sm">
				<li
					v-for="entry in entries"
					:key="entry.name"
					class="flex items-center gap-1.5 py-1.5"
				>
					<BbIcon
						class="shrink-0 text-[color:var(--bb-text-muted)]"
						:icon="entry.kind === 'folder' ? 'lucide:folder' : 'lucide:file'"
						size="sm"
					/>
					<span class="min-w-0 truncate">{{ entry.name }}</span>
					<span
						class="ml-auto shrink-0 text-xs text-[color:var(--bb-text-muted)]"
						>{{ entry.meta }}</span
					>
				</li>
			</ul>
		</div>
	</div>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbBreadcrumbs, BbIcon } from 'bitboss-ui';
import type { BbBreadcrumbsItem } from 'bitboss-ui';

// File-browser trail: hierarchy lives in client state, so ancestors use
// `onClick` (not `href`/`to`). The current folder stays target-less.
type Folder = 'Documents' | 'Brand' | 'Icons';

const path = ref<Folder[]>(['Documents', 'Brand', 'Icons']);

const catalog: Record<
	Folder,
	Array<{ name: string; kind: 'folder' | 'file'; meta: string }>
> = {
	Documents: [
		{ name: 'Brand', kind: 'folder', meta: '12 items' },
		{ name: 'Contracts', kind: 'folder', meta: '4 items' },
		{ name: 'Q2 summary.pdf', kind: 'file', meta: '240 KB' },
	],
	Brand: [
		{ name: 'Icons', kind: 'folder', meta: '48 items' },
		{ name: 'Logos', kind: 'folder', meta: '6 items' },
		{ name: 'guidelines.md', kind: 'file', meta: '18 KB' },
	],
	Icons: [
		{ name: 'mark.svg', kind: 'file', meta: '2 KB' },
		{ name: 'favicon.ico', kind: 'file', meta: '4 KB' },
		{ name: 'wordmark.svg', kind: 'file', meta: '3 KB' },
	],
};

const current = computed(() => path.value[path.value.length - 1]!);
const entries = computed(() => catalog[current.value]);
const iconOffset = computed(() => path.value.length * 18);

const items = computed<BbBreadcrumbsItem[]>(() =>
	path.value.map((name, index) => {
		const isCurrent = index === path.value.length - 1;
		return {
			key: `${index}-${name}`,
			text: name,
			'prepend:icon': 'lucide:folder',
			...(isCurrent
				? {}
				: {
						onClick: () => {
							path.value = path.value.slice(0, index + 1) as Folder[];
						},
					}),
		};
	})
);
</script>
```

### Router and Inertia links

The crumb's target is the standard navigation surface, so the same trail works
across platforms. With Vue Router or Nuxt, pass a route location to `to` — the
active-class props are wired for you:

```vue
<BbBreadcrumbs
	:items="[
		{ key: 'home', text: 'Home', to: { name: 'index' } },
		{ key: 'team', text: 'Team', to: '/team' },
		{ key: 'member', text: 'Ada Lovelace' },
	]"
/>
```

In an Inertia app a crumb's `href` renders an Inertia link; attach `method`,
`data`, `headers` or `preserveScroll` per item when a crumb triggers a non-GET
visit:

```vue
<BbBreadcrumbs
	:items="[
		{ key: 'dashboard', text: 'Dashboard', href: '/dashboard' },
		{ key: 'orders', text: 'Orders', href: '/orders', preserveScroll: true },
		{ key: 'order', text: 'Order #8842' },
	]"
/>
```

The component is SSR-safe: the full trail renders on the server, and the
overflow calculation runs after hydration once real widths exist.

### Works well with

- `BbTabs` — breadcrumbs above, tabs below is the canonical detail-page header:
  the trail answers "where am I", the tabs switch peer views of the record.
- `BbTable` + `BbPagination` — a listing page links each row to a detail view
  whose breadcrumb trail leads back to the (paged) list.
- `BbButton` page actions — keep the trail on its own line, or put compact
  actions in the `append` slot and declare their width via `offset-width`.

### Gotchas and anti-patterns

- **Don't give the last item a target.** It always carries
  `aria-current="page"` and the theme makes it inert (`pointer-events: none`),
  so an `href` on it renders a link nobody can click.
- **The divider is slot-only.** A `divider` prop does not exist (older versions
  had one); passing it just leaks an attribute onto the markup. The default is
  a chevron icon, not a `/` glyph.
- **Don't pre-slice `items` to "manage" overflow** — you would fight the
  built-in estimator and lose the accessible overflow menu.
- **Keys are slot names.** Duplicate keys break rendering; keys equal to
  reserved slot names collide with them.
- **Slot content is invisible to the estimator.** If crumbs start clipping
  after you add icons or edge content, set `offset-width` — don't shrink the
  trail with CSS overrides.
- **In a flex row, give it `min-w-0 flex-auto`.** A content-sized trail whose
  width the overflow toggle changes will fight its own resize observer every
  frame. Put the trail on a stable basis and keep siblings `shrink-0` — see
  "Give it a stable basis in a flex row" above.
- **One trail per view.** Multiple breadcrumb landmarks on a page confuse
  screen-reader landmark navigation and users alike.

### Accessibility

- The trail is a `nav` landmark labelled from the active locale
  (`breadcrumbs.label`; set `locale` in the plugin config). There is no
  per-instance label prop.
- The last item is the current page: leave it without a navigation target so it
  renders as plain, non-interactive text with `aria-current="page"`. Do not
  link the page the user is already on.
- The overflow button is a real `button` with a localized, count-aware label
  ("Show N hidden breadcrumbs"); its menu is a `BbDropdown` with full keyboard
  support — nothing to add on your side.
- The dividers are decorative (`aria-hidden`); never encode meaning in them.
- `disabled` on the component (or an item) removes `href` and exposes
  `aria-disabled` instead of shipping a dead link.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
| `dividerWidth` | `number \| undefined` | `16` |  | Width of the divider in pixels. |
| `ellipsisWidth` | `number \| undefined` |  |  | Explicit width used by the estimator for the ellipsis activator. |
| `estimationBias` | `number \| undefined` | `1.12` |  | Multiplier applied to each estimated item width. A higher value will result in more over-estimation. |
| `gapWidth` | `number \| undefined` | `4` |  | Horizontal gap between breadcrumb elements in pixels. |
| `items` | `Item[]` |  | yes | Array of items that describe how the breadcrumbs should behave. Compatible with navigating through `a` or `router-link`. |
| `offsetWidth` | `number \| undefined` | `0` |  | Extra one-off width in pixels added to the total estimate (e.g. prepend/append/item slot content). |

## Events

- None.

## Slots

- `append` — scope: `BbBreadcrumbsEdgeSlotProps` — Content rendered after the breadcrumb list, in a dedicated append region.
- `divider` — scope: `Record<string, never>` — Replaces the default separator rendered between breadcrumb items.
- `ellipsis` — scope: `BbBreadcrumbsEllipsisSlotProps` — Replaces the default `…` overflow button shown when items overflow.
- `item:append` — scope: `BbBreadcrumbsItemSlotProps` — Content rendered after **every** breadcrumb item's link/button. Generic fallback below a per-item `<key>:append` slot and above the item's `append:icon`.
- `item:prepend` — scope: `BbBreadcrumbsItemSlotProps` — Content rendered before **every** breadcrumb item's link/button, in the leading edge region. Generic fallback: a per-item `<key>:prepend` slot takes precedence, and the item's `prepend:icon` is used when neither slot is present.
- `prepend` — scope: `BbBreadcrumbsEdgeSlotProps` — Content rendered before the breadcrumb list, in a dedicated prepend region.

## See Also

- [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.
- [BbDropdown](./BbDropdown.md) — Displays contextual action menus and menu content (includes the co-located BbDropdownGroup export, which is how a selectable group is bound).

---

<!-- dist/ai/BbButton.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbButton.md -->

# BbButton

## Agent Contract

- Safety level: **Consumer API**
- Group: **Inputs**
- Description: Button with loading state, tooltip, and icon support.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbButton.md](./source/BbButton.md)

## Usage & Guidelines

### When to use

Reach for `BbButton` for any action the user _performs_ (submit, save, delete,
toggle) and for any navigation that must look like a button — including
`variant="link"`, which recolors a button rather than turning it into text.
Decision rules:

- One action, nothing else → `BbButton`.
- One dominant action plus close alternates (_Save / Save as draft_) →
  `BbDropdownButton`.
- A menu with no dominant action (overflow "…", account menu) → `BbDropdown`.
- A completely unstyled clickable/navigable element → `BbBaseButton` (same
  navigation surface, zero chrome).

`BbButton` is a thin wrapper over `BbBaseButton` — variant/size/loading/toggle
chrome on top of the base's element-resolution and **navigation** engine. That
navigation surface (`href`, `to`, Inertia visits, active classes — see below)
lives on `BbBaseButton`, so **every** control built on it navigates the same
way: `BbButton`, `BbDropdownButton`, dropdown/breadcrumb/tab items, and
`BbBaseButton` itself. Whenever a click should end in navigation, hand it to one
of these via `href`/`to` rather than an `@click` handler — the rule below is
library-wide, not `BbButton`-specific.

### Choosing a variant

Start with the built-in ladder: `primary`, `secondary`, `outline`, `ghost`,
`destructive`, and `link`. Use exactly one `variant="primary"` per view region;
everything else is `secondary`, `outline` or `ghost`. Reserve `destructive` for
irreversible actions (and gate them behind `useConfirm`). `link` is navigation
disguised as text — pair it with `href`/`to`, not with heavy actions.
`variant="none"` renders structure with no variant styling — an escape hatch,
avoid it.

**`link` changes color, not layout.** It keeps the button box: the size scale's
height and horizontal padding still apply, so it occupies button space and never
flows inline. That is right for a standalone navigation control sitting among
other buttons — chrome and auth text actions ("See pricing", "Forgot
password?"). It is **wrong for a table/peek entity-identity cell**: a row's
name column is text that must truncate and flow inline at cell width, and
`link`'s fixed height/padding fights that (as does any button chrome). For a
clickable record name — or any inline text link in a table, peek, or property
grid — use `BbBaseButton` with the project `.plain-link` class instead (see
[design language guide](./guides/design-language.md) § Guide helper): it
renders the same `href`/`to`/`@click` surface with no button chrome at all. More
generally, for genuinely inline navigation anywhere, reach for `BbBaseButton`
with your own link class rather than `variant="link"`.

**The variant ladder**

```vue
<div class="flex flex-wrap items-center gap-2">
	<BbButton variant="primary">Save</BbButton>
	<BbButton variant="secondary">Duplicate</BbButton>
	<BbButton variant="outline">Export</BbButton>
	<BbButton variant="ghost">Cancel</BbButton>
	<BbButton variant="destructive">Delete</BbButton>
	<BbButton variant="link" href="#pricing">See pricing</BbButton>
</div>
```

If your product needs another semantic style, register it in the plugin config
instead of shipping one-off inline styling — registered names become typed
values of `variant`:

```ts
// vite.config.ts
bitbossUi({ buttonVariants: ['upgrade'] });

// nuxt.config.ts
export default defineNuxtConfig({ bitboss: { buttonVariants: ['upgrade'] } });
```

The library ships **no CSS for registered variants**: style
`.bb-button--upgrade` yourself, following the built-in state recipe (neutral
hover, `aria-pressed` for pressed, `--bb-ring` for focus):

```css
.bb-button.bb-button--upgrade {
	background-color: var(--bb-primary);

	&:hover:not(.bb-base-button--disabled) {
		background-color: color-mix(in oklab, var(--bb-primary) 90%, black);
	}

	&:focus-visible {
		box-shadow: 0 0 0 var(--bb-ring-size) var(--bb-ring);
	}
}
```

Never use a variant name that is neither built-in nor registered in the
project's `vite.config.*` / `nuxt.config.*`. Unsure what's currently legal in
a given project (built-ins plus whatever it has registered)? Don't guess from
an example — the plugin regenerates
`node_modules/bitboss-ui/button-variants.d.ts` on every build; that file
**is** the closed, machine-readable list of every legal `variant` value for
that project, registrations included (see
[Installation and Plugin Setup](./guides/installation-and-plugin-setup.md) §
variants).

### Label, tag and type

**Prefer the default slot for the label** — write `<BbButton>Save</BbButton>`,
not `:text="'Save'"`. The `text` prop renders identically (`<slot>{{ text }}</slot>`
under the hood) and exists mainly for `:items`-style loops that spread a config
object; when both are present the slot wins. Reach for `text` only when a string
is all you have; otherwise the slot reads cleaner and lets you compose markup.
`type` defaults to `'button'`, so a `BbButton` inside a form never submits by
accident; set `type="submit"` for the one that should, and let the form's
`@submit` handler own the logic:

**Submitting a form via type, not @click**

```vue
<form
	class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	@submit.prevent="state.sent = true"
>
	<div class="flex flex-col gap-0.5">
		<span class="text-sm font-medium">Request workspace access</span>
		<span class="text-xs text-[color:var(--bb-text-muted)]">Acme Studio · billing team</span>
	</div>
	<div class="flex items-center gap-2">
		<BbButton type="submit" variant="primary">Request access</BbButton>
		<span class="text-xs text-[color:var(--bb-text-muted)]">
			{{ state.sent ? 'Request sent — check your email.' : 'Owner will approve by email.' }}
		</span>
	</div>
</form>
```

`tag` renders the button as one of `button` (default), `div`, `span` or `label`,
for the rare case where a native `<button>` is invalid in context (e.g. inside
another interactive element, or a `<label>` wrapping a hidden file input).
Non-`button` tags drop the native `type` and
`disabled` attributes (invalid there); disabled state is then conveyed only by
the `bb-base-button--disabled` class, so you lose native form/keyboard
semantics — keep the default unless you must not.

### Sizes and layout

Six sizes, `xs`–`2xl` (default `md`), derived from the global `--bb-control-h`
scale — height, padding, font, radius and icon size move together. **Prefer
`md`**: at 28px it sits one step under the 32px input height and exactly
matches a `compact` input, so an `md` button aligns flush beside compact
fields — and being the default, you simply omit the `size` prop. Use
`sm`/`xs` inside genuinely dense surfaces (table row actions, toolbars,
bulk-action bars) and `lg`+ only for a rare hero action. `block` stretches
the button to its container's width (e.g. mobile CTAs, dialog footers).

**Stretch ≠ `block`.** A flex-column parent (`flex flex-col`) stretches its
children on the cross axis by default, so a bare `BbButton` dropped into one
looks exactly as wide as a `block` button even though `block` was never set —
that's the parent's `align-items: stretch`, not the button. Don't "fix" it by
setting `align-self: flex-start` globally on `.bb-button` — that breaks
vertical centering in row toolbars, where stretch-to-height is wanted. Instead:
put CTAs in an actions row (`class="flex justify-end"`, content-sized buttons
stay content-sized), or set `block` explicitly on the one button that should
genuinely fill the width.

**The size scale**

```vue
<div class="flex flex-wrap items-center gap-2">
	<BbButton size="xs" variant="outline">xs</BbButton>
	<BbButton size="sm" variant="outline">sm</BbButton>
	<BbButton size="md" variant="outline">md</BbButton>
	<BbButton size="lg" variant="outline">lg</BbButton>
	<BbButton size="xl" variant="outline">xl</BbButton>
	<BbButton size="2xl" variant="outline">2xl</BbButton>
</div>
```

`size` also accepts a responsive map keyed by breakpoint (`default` plus
Tailwind's `sm` 640 / `md` 768 / `lg` 1024 / `xl` 1280 / `2xl` 1536). It is
purely CSS-driven — no runtime breakpoint watching, so it is SSR-safe. Note:
breakpoint entries switch height, font size and content gap; horizontal
padding, icon size and radius stay at the `default` entry's values.

**Responsive size — resize the preview**

```vue
<BbButton :size="{ default: 'sm', lg: 'lg' }" variant="primary">
	Start free trial
</BbButton>
```

### Icons

Use `prepend:icon` / `append:icon` for labelled buttons, and `icon` for
icon-only buttons. Accessibility here is **symmetric**: the label content still
matters, it is just rendered `sr-only` when `icon` is set. So give an icon-only
button its accessible name the same way as any other — through the default slot
(or `text`): `<BbButton icon="lucide:settings">Settings</BbButton>` renders no
visible text but announces "Settings". `aria-label` is plan B — an override for
when the accessible name must differ from (or you can't supply) slot content.
Just don't ship an icon-only button with neither. When `icon` is set,
`append:icon` is ignored. Icons scale with the button's `size`; names come from
the `lucide:*` set (see the icons policy).

**Icons and icon-only**

```vue
<div
	class="flex max-w-sm items-center justify-between gap-2 rounded-[var(--bb-radius)] border p-3"
>
	<span class="text-sm font-medium">Invoices</span>
	<div class="flex items-center gap-1.5">
		<BbButton variant="primary" prepend:icon="lucide:plus">New invoice</BbButton>
		<BbButton variant="outline" append:icon="lucide:download">Export</BbButton>
		<!-- Label comes from slot content, rendered sr-only — no aria-label needed. -->
		<BbButton variant="ghost" icon="lucide:settings">Settings</BbButton>
	</div>
</div>
```

### Toggle buttons

Binding `v-model` turns the button into a toggle: each click flips the model
between `true-value` and `false-value` (defaults `true`/`false`), and the
component manages `aria-pressed` plus the pressed styling for you. Values are
compared structurally, so object `true-value`s work. Because toggle mode is
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>
```

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.

Add `group` to fuse adjacent buttons into one visual segment control. It is
purely visual (shared borders/radius between siblings) — each button keeps its
own semantics, and there is no arrow-key roving between them.

**Exclusive toggle groups**

```vue
<template>
	<div
		class="flex max-w-md flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">Issues</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				Acme workspace ·
				{{
					statusFilter
						? statuses.find((s) => s.value === statusFilter)?.label
						: 'All statuses'
				}}
				· {{ views.find((v) => v.value === activeView)?.label }} view
			</span>
		</div>

		<div class="flex flex-col gap-1.5">
			<span class="text-xs text-[color:var(--bb-text-muted)]">Status</span>
			<div>
				<BbButton
					v-for="status in statuses"
					:key="status.value"
					v-model="statusFilter"
					:false-value="null"
					group
					size="sm"
					:true-value="status.value"
					variant="outline"
				>
					{{ status.label }}
				</BbButton>
			</div>
		</div>

		<div class="flex flex-col gap-1.5">
			<span class="text-xs text-[color:var(--bb-text-muted)]">View</span>
			<div>
				<BbButton
					v-for="view in views"
					:key="view.value"
					v-model="activeView"
					:false-value="view.value"
					group
					:prepend:icon="view.icon"
					size="sm"
					:true-value="view.value"
					variant="outline"
				>
					{{ view.label }}
				</BbButton>
			</div>
		</div>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, type IconType } from 'bitboss-ui';

type IssueStatus = 'open' | 'in-progress' | 'done';
type IssueView = 'list' | 'board' | 'timeline';

const statuses: Array<{ label: string; value: IssueStatus }> = [
	{ label: 'Open', value: 'open' },
	{ label: 'In progress', value: 'in-progress' },
	{ label: 'Done', value: 'done' },
];

const views: Array<{ label: string; value: IssueView; icon: IconType }> = [
	{ label: 'List', value: 'list', icon: 'lucide:list' },
	{ label: 'Board', value: 'board', icon: 'lucide:kanban' },
	{ label: 'Timeline', value: 'timeline', icon: 'lucide:calendar-range' },
];

const statusFilter = ref<IssueStatus | null>('open');
const activeView = ref<IssueView>('list');
</script>
```

Listen to `update:modelValue` only if you need side effects; state itself is
handled. For form-ish multi-selection prefer `BbCheckboxGroup` /
`BbRadioGroup`; toggle buttons are for immediate, tool-bar-like state.

Toggles don't have to be exclusive. Give each button its own seeded boolean
model for independent on/off state — the classic formatting toolbar. Combine
with `icon` and `size="xs"` for the dense icon-only look; the slot content
stays on as the accessible name:

**Icon-only formatting toolbar**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex items-center justify-between gap-2">
			<span class="text-xs font-medium text-[color:var(--bb-text-muted)]"
				>Format</span
			>
			<span class="text-xs text-[color:var(--bb-text-muted)]">{{
				summary
			}}</span>
		</div>
		<div>
			<BbButton
				v-model="bold"
				group
				icon="lucide:bold"
				size="xs"
				variant="outline"
			>
				Bold
			</BbButton>
			<BbButton
				v-model="italic"
				group
				icon="lucide:italic"
				size="xs"
				variant="outline"
			>
				Italic
			</BbButton>
			<BbButton
				v-model="underline"
				group
				icon="lucide:underline"
				size="xs"
				variant="outline"
			>
				Underline
			</BbButton>
		</div>
		<p
			class="text-sm"
			:class="{
				'font-bold': bold,
				italic: italic,
				underline: underline,
			}"
		>
			Q3 billing note for Acme Studio
		</p>
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbButton } from 'bitboss-ui';

// Independent toggles: each button owns its own seeded boolean model.
const bold = ref(false);
const italic = ref(true);
const underline = ref(false);

const summary = computed(() => {
	const active = [
		bold.value && 'bold',
		italic.value && 'italic',
		underline.value && 'underline',
	].filter(Boolean);
	return active.length ? active.join(' + ') : 'plain text';
});
</script>
```

### Loading and async actions

Return a promise from `@click` and the button tracks it automatically: a
spinner appears, the label announces loading to screen readers, and the button
blocks re-clicks (for `type="submit"`, `href` and `to` the click is also
prevented) until the promise settles. Concurrent handlers are counted, so the
spinner stays until the last one resolves — no manual `isSaving` flag, no
hand-placed `BbSpinner`.

**An async save, tracked automatically**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">Invoice INV-1042</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				Acme Studio · draft · due Jul 31, 2026
			</span>
		</div>
		<div class="flex items-center gap-2">
			<BbButton prepend:icon="lucide:save" variant="primary" @click="save">
				Save changes
			</BbButton>
			<span class="text-xs text-[color:var(--bb-text-muted)]">{{
				status
			}}</span>
		</div>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton } from 'bitboss-ui';

const status = ref('Unsaved changes');

/** Stand-in mutation; the button spins until the promise settles. */
const save = async () => {
	await new Promise((resolve) => setTimeout(resolve, 900));
	status.value = `Saved at ${new Date().toLocaleTimeString()}`;
};
</script>
```

Escape hatches, when the default isn't right:

- `loading` — bind it when the pending state lives elsewhere (a store mutation,
  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).
- `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 sr-only loading announcement is localized via the plugin's `locale`
option. `disabled` and `loading` are independent: `disabled` wins the muted
styling and native blocking; don't set both.

**Externally-owned loading state**

```vue
<div
	class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
>
	<div class="flex flex-col gap-0.5">
		<span class="text-sm font-medium">Release notes</span>
		<span class="text-xs text-[color:var(--bb-text-muted)]">v2.4.0 · draft in review</span>
	</div>
	<div class="flex items-center gap-2">
		<BbButton :loading="state.publishing" variant="primary">Publish</BbButton>
		<BbButton variant="outline" @click="state.publishing = !state.publishing">
			{{ state.publishing ? 'Stop simulating' : 'Simulate pending' }}
		</BbButton>
	</div>
</div>
```

### Links and navigation

Navigation comes from `BbBaseButton`, the primitive `BbButton` wraps — so this
whole surface works identically on `BbButton`, `BbDropdownButton`, and the base
itself, and item-driven components (dropdowns, breadcrumbs, tabs) expose the
same fields on their items. The rule is absolute: whenever a click should end in
navigation, offload it to `href`/`to` — **never** write
`@click="router.push(...)"` or touch `window.location`. The rendered element
adapts to what you pass:

- `href` → a real `<a>`; in an Inertia app a same-origin `href` upgrades to an
  Inertia link automatically (hash-only, protocol-relative and cross-origin
  URLs stay plain anchors).
- `to` → `RouterLink` (or `NuxtLink` in Nuxt).
- `target` set → always a plain anchor, even under Inertia (Inertia can't open
  new tabs); any target other than `_self` (`_blank`, named windows, …)
  automatically merges `noopener noreferrer` into `rel`.
- `disabled` on a link → the `href` is dropped and the element gets
  `role="link"`, `aria-disabled="true"` and `tabindex="-1"`, so it cannot be
  followed or tabbed to but keeps its place in the layout.

**Buttons that are links**

```vue
<div
	class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
>
	<div class="flex flex-col gap-0.5">
		<span class="text-sm font-medium">Q2 revenue report</span>
		<span class="text-xs text-[color:var(--bb-text-muted)]">Ready · exported Jul 12, 2026</span>
	</div>
	<div class="flex flex-wrap items-center gap-1.5">
		<BbButton variant="outline" href="#reports">View report</BbButton>
		<BbButton
			variant="ghost"
			href="#help"
			target="_blank"
			append:icon="lucide:external-link"
		>
			Help center
		</BbButton>
		<BbButton variant="outline" href="#archive" disabled>
			Archive (soon)
		</BbButton>
	</div>
</div>
```

#### Active state — highlighting the current page

The goal here is the "you are here" affordance: in a sidebar, tab bar, or nav
menu, the link pointing at the page you're on should stand out. This is exactly
what vue-router's `RouterLink` does with its `active-class` — and the library
**ports that same behavior to Inertia and to plain apps with no router at all**,
so one navigation link gets consistent active styling on every platform.

How it works: when a link's target matches the current location, the component
adds a **class name** to the rendered element. It attaches only the hook — it
ships **no styling of its own** — so you decide what "active" looks like by
writing CSS for that class. "Current location" comes from whichever model is in
play: vue-router computes it natively for `to` links; for an `href` link the
library matches against the Inertia page (under Inertia) or `window.location`
(a plain app). There are two classes, for two kinds of match:

- **`router-link-active`** — added when the current page is at or _below_ the target
  (a path-prefix match). Good for a section link that should stay lit on child
  pages (`/invoices` highlighted while on `/invoices/42`).
- **`router-link-exact-active`** — added only on an _exact_ match. Good for a specific
  page link that should light up on that page alone.

Name them per link, or set project-wide defaults once via the plugin's
`linkActiveClass` / `linkExactActiveClass` options (defaults
`router-link-active` / `router-link-exact-active`). The library papers over the
platform differences — the same `active-class` works whether the link navigates
by `to`, by Inertia `href`, or by a plain `href`.

```vue
<template>
	<!-- vue-router / Nuxt: active state computed natively from the route. -->
	<BbButton
		variant="ghost"
		:to="{ name: 'invoices.index' }"
		active-class="nav-active"
	>
		Invoices
	</BbButton>
	<!-- Inertia (or a plain app): the library matches the href against the
	     current URL and applies the same `nav-active` hook. -->
	<BbButton
		variant="ghost"
		:href="route('invoices.index')"
		active-class="nav-active"
	>
		Invoices
	</BbButton>
</template>

<style scoped>
/* Nothing highlights until you style the class the component attached. */
.nav-active {
	font-weight: 600;
	color: var(--bb-primary);
}
</style>
```

#### Inertia visits

Under Inertia, `href` accepts the full visit surface as props, grouped by
concern:

- **Request shape** — `method` (`get`…`delete`), `data`, `headers`, `only`
  (partial reloads), `except` (the inverse of `only` — pass one or the other),
  `query-string-array-format`, `component`.
- **History & scroll** — `replace`, `preserve-scroll`, `preserve-state` (each
  also accepts a callback form), `preserve-url` (change the page, keep the
  address bar), `view-transition`.
- **Prefetching** — `prefetch` (`true`, or `'mount'`/`'hover'`/`'click'`),
  `cache-for` (a duration, or `[staleAfter, expiresAfter]`), `cache-tags` for
  group invalidation.
- **Speed** — `async` (don't block the page), `instant` (navigate optimistically
  and reconcile on response), `page-props` (props to merge before the server
  answers).
- **Lifecycle hooks** — `onBefore`, `onStart`, `onProgress`, `onSuccess`,
  `onError`, `onCancel`, `onFinish`, plus `onCancelToken` to capture a cancel
  handle and `onPrefetching`/`onPrefetched` for the prefetch pair. Bind them as
  props (`:on-success="..."`), not `@` listeners.

**`onError` here means VALIDATION errors** — the ordinary 422 — and it is the
only failure callback `<Link>` accepts. Inertia's other two,
`onHttpException` (the server answered 5xx) and `onNetworkError` (the request
never arrived — offline, DNS, connection reset), are **`router.visit()` /
`useForm()` options, not Link props**; passing them to a link-shaped button
does nothing. Reach for a form or an explicit visit when you need to tell those
apart — see the Inertia helpers guide.

Every prop Inertia's own `<Link>` accepts is forwarded, and
`npm run check:inertia-props` fails the build both when Inertia adds one we
don't forward and when we declare a callback `<Link>` never accepted. The list
has to be hand-written, because `@inertiajs/vue3` is an optional peer the
library's public types are not allowed to import.

```vue
<!-- Inertia: href becomes a visit; the whole option set rides along -->
<BbButton
	href="/invoices"
	method="post"
	:data="{ customerId }"
	preserve-scroll
	:only="['invoices']"
	:on-success="() => drawer.close()"
	:on-error="(errors) => (formErrors = errors)"
>
	Create invoice
</BbButton>
```

```vue
<!-- Prefetch on hover so the detail page is already cached by the click -->
<BbButton href="/invoices/42" prefetch="hover" cache-for="30s" variant="link">
	Invoice #42
</BbButton>
```

### Works well with

- `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
  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:

**Destructive action gated behind useConfirm**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">API keys</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				<span data-count>{{ keys.length }}</span> active · revoking is immediate
			</span>
		</div>
		<div
			v-for="key in keys"
			:key="key.id"
			class="flex items-center gap-2"
			data-key-row
		>
			<div class="flex min-w-0 flex-1 flex-col">
				<span class="truncate text-sm font-medium">{{ key.label }}</span>
				<span class="font-mono text-xs text-[color:var(--bb-text-muted)]">
					{{ key.masked }} · created {{ key.created }}
				</span>
			</div>
			<BbButton
				prepend:icon="lucide:trash-2"
				size="xs"
				variant="destructive"
				@click="revoke(key)"
			>
				Revoke
			</BbButton>
		</div>
		<p
			v-if="keys.length === 0"
			class="text-xs text-[color:var(--bb-text-muted)]"
		>
			No active keys.
		</p>

		<!--
			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
			mount none. See ai/guides/agent-contract.md § Global Host Rule.
		-->
		<BbConfirm />
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbConfirm, useConfirm } from 'bitboss-ui';

type ApiKey = { id: string; label: string; masked: string; created: string };

const keys = ref<ApiKey[]>([
	{
		id: 'key_prod',
		label: 'Production',
		masked: 'sk-live-…9f2c',
		created: '2026-03-14',
	},
	{
		id: 'key_stg',
		label: 'Staging',
		masked: 'sk-test-…41ab',
		created: '2026-05-02',
	},
]);

const { confirm } = useConfirm();

/** Gate the destructive action: await the decision, act only on a yes. */
const revoke = async (key: ApiKey) => {
	const ok = await confirm({
		title: `Revoke "${key.label}"?`,
		text: 'Integrations using this key will stop working immediately. This cannot be undone.',
		variant: 'destructive',
		yes: { text: 'Revoke key', 'prepend:icon': 'lucide:trash-2' },
		no: 'Keep key',
	});
	if (ok) keys.value = keys.value.filter((k) => k.id !== key.id);
};
</script>
```

- `BbIndicator` — wrap the button to anchor a count or a status dot to its
  corner (the pinned-over-another-element sibling of `BbBadge`).
- `BbTooltip` / `v-bb-tooltip` — give an icon-only button a _visible_ name on
  hover; the tooltip complements the accessible name (from slot content), it
  does not replace it.

**Indicator count and tooltip on icon-only buttons**

```vue
<div
	class="flex max-w-sm items-center justify-between gap-2 rounded-[var(--bb-radius)] border p-3"
>
	<span class="text-sm font-medium">Acme Studio</span>
	<div class="flex items-center gap-1.5">
		<BbIndicator :text="3" variant="destructive">
			<!-- Accessible name from slot content, rendered sr-only. -->
			<BbButton variant="outline" icon="lucide:bell">Notifications</BbButton>
		</BbIndicator>
		<BbButton
			v-bb-tooltip="'Workspace settings'"
			variant="ghost"
			icon="lucide:settings"
		>
			Workspace settings
		</BbButton>
	</div>
</div>
```

### Gotchas & anti-patterns

Gotchas (real behavior, verified against source):

- A `v-model` bound to an undefined value is not a toggle yet — the first click
  won't set it. Seed the model.
- Every default-slot child lands inside one `.bb-button__content` span, so
  sibling elements sit inline with no gap and the button's own flex layout
  cannot space them — `class="justify-between"` on the button reaches the
  content span, not its children, and `Label` + `142` renders as `Label142`.
  Put the count in a `BbBadge`, or use `append:icon`, rather than two bare
  spans.
- Binding `aria-pressed` yourself does nothing: the component owns that
  attribute and drops yours. A hand-rolled toggle (`:aria-pressed` plus a
  `variant` swap) therefore looks right and is invisible to assistive tech.
  Use `v-model` — see [Toggle buttons](#toggle-buttons). Dev builds warn.
- `group` fuses looks only; it adds no radio semantics or arrow-key navigation.
- Responsive `size` maps change height/font/gap per breakpoint; padding, icon
  size and radius follow the `default` entry.
- Auto-loading tracks the promise **returned** from `@click`; a handler that
  fires work without returning it shows no spinner.
- Registered custom variants ship no CSS — unstyled until you write
  `.bb-button--<name>`.

Anti-patterns:

- `@click` + `router.push`/`window.location` for plain navigation — use
  `to`/`href`.
- Hand-rolling the pending state: `BbSpinner` in the slot or manual `isSaving`
  flags — return the promise instead.
- More than one `variant="primary"` in a view region.
- A disabled button with no nearby explanation of how to enable it.
- Faking a split button with a flex row of `BbButton` + `BbDropdown` — that is
  `BbDropdownButton`.

### Accessibility

- Icon-only buttons still need an accessible name, but it works like any other
  button: put it in the default slot (or `text`) and it renders `sr-only` when
  `icon` is set — not removed. Use `aria-label` only to override that name, not
  as the default mechanism. Never ship an icon-only button with no name at all.
- Toggles expose `aria-pressed` (`true`/`false`) automatically — never add your
  own.
- While loading: `aria-disabled="true"`, `tabindex="-1"`, and a localized
  sr-only loading announcement.
- Disabled links render with `role="link"`, `aria-disabled="true"`, no `href`,
  and leave the tab order.
- The exact-active link gets `aria-current` (default `"page"`) on every
  platform — vue-router, Inertia, and plain apps alike.
- Links with any `target` other than `_self` (`_blank`, named windows, …) are
  secured with `rel="noopener noreferrer"` automatically.
- Prefer real actions over disabled buttons; when disabled, explain why nearby.

## v-model

- `v-model` — type: `any`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activeClass` | `string \| undefined` |  |  | Class to apply when the link is active. |
| `append:icon` | `string \| undefined` |  |  | Icon to be added on the right of the text. |
| `ariaCurrentValue` | `"page" \| "step" \| "location" \| "date" \| "time" \| "true" \| "false" \| undefined` | `'page'` |  | Value passed to the attribute `aria-current` when the link is exact active. |
| `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` |  | Displays the component as full width. |
| `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 in… |
| `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` |  |  |  |
| `disableAutoLoading` | `boolean \| undefined` | `false` |  | Disables the automatic loading state that tracks async click handlers (enabled by default). |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
| `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 `e… |
| `exactActiveClass` | `string \| undefined` |  |  | Class to apply when the link is exact active. |
| `except` | `string[] \| undefined` |  |  | Inertia: the inverse of `only` — properties to EXCLUDE from a partial reload. Pass one or the other, not both. |
| `external` | `boolean \| undefined` | `false` |  | Forces an `href` link to render as a plain `<a>` (native navigation), bypassing Inertia/router interception — same intent as Nuxt's `external`. A native-anchor signal alongside `target` and `download`. |
| `falseValue` | `any` | `false` |  | Value emitted when the toggle is deactivated. |
| `group` | `boolean \| undefined` | `false` |  | Identifies the button as part of a button group. |
| `headers` | `object \| undefined` |  |  |  |
| `href` | `string \| undefined` |  |  | Returns the hyperlink's URL. Can be set, to change the URL. |
| `icon` | `string \| undefined` |  |  | Used when only an icon with no text should be displayed. |
| `instant` | `boolean \| undefined` | `false` |  | Inertia: navigate optimistically on click and reconcile when the response lands, instead of waiting for the round trip. |
| `interactiveWhileLoading` | `boolean \| undefined` | `false` |  | Keeps the button clickable while it is loading. Buttons are disabled while loading by default; this escape hatch exists for toggles that must stay interactive (e.g. the dropdown-button caret). |
| `loading` | `boolean \| undefined` | `false` |  | Triggers a loading indicator. |
| `method` | `"get" \| "post" \| "put" \| "patch" \| "delete" \| undefined` |  |  |  |
| `modelValue` | `any` |  |  |  |
| `onBefore` | `(() => void) \| undefined` |  |  |  |
| `onCancel` | `(() => void) \| undefined` |  |  |  |
| `onCancelToken` | `((cancelToken: unknown) => void) \| undefined` |  |  |  |
| `onError` | `((errors: Record<string, string>) => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when the server responds with VALIDATION errors — the ordinary 422 path. This is the only failure callback Inertia's `Link` accepts. `onHttpException` (server answered 5xx) and `onNetworkError` (the request… |
| `onFinish` | `(() => void) \| undefined` |  |  |  |
| `only` | `string[] \| undefined` |  |  |  |
| `onPrefetched` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a prefetch for this link has completed and is cached. |
| `onPrefetching` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a prefetch for this link starts. |
| `onProgress` | `((progress: { percentage: number \| undefined; }) => void) \| undefined` |  |  |  |
| `onStart` | `(() => void) \| undefined` |  |  |  |
| `onSuccess` | `(() => void) \| undefined` |  |  |  |
| `pageProps` | `Record<string, unknown> \| ((currentProps: Record<string, unknown>, sharedProps: Record<string, unknown>) => Record<string, unknown>) \| null \| undefined` |  |  | Inertia: props to merge into the next page optimistically, before the server responds. Either an object or a function of the current props. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue… |
| `prefetch` | `string \| boolean \| string[] \| undefined` |  |  | Inertia: fetch and cache this link's page ahead of the click. `true` uses the default trigger; a string or list of strings picks them (`'mount'`, `'hover'`, `'click'`). |
| `prepend:icon` | `string \| undefined` |  |  | Icon to be added on the left of the text. |
| `preserveScroll` | `boolean \| ((props: Record<string, unknown>) => boolean) \| undefined` |  |  |  |
| `preserveState` | `boolean \| ((props: Record<string, unknown>) => boolean) \| null \| undefined` |  |  |  |
| `preserveUrl` | `boolean \| undefined` | `false` |  | Inertia: keep the current URL in the address bar even though the page content changes. |
| `queryStringArrayFormat` | `"brackets" \| "indices" \| undefined` |  |  |  |
| `replace` | `boolean \| undefined` | `false` |  | Calls `router.replace` instead of `router.push`. |
| `size` | `Responsive<Sizes> \| undefined` | `"md"` |  | Sets the size of the button. A single value applies at every breakpoint; a per-breakpoint map (e.g. `{ default: 'sm', lg: 'md' }`) switches responsively. Purely CSS-driven — no runtime breakpoint watching. |
| `tag` | `ButtonTag \| undefined` | `'button'` |  | Element to render for the plain (non-link, non-router) button: `'button'` (default), `'div'`/`'span'` when nesting inside another button or link, or `'label'` for a file-upload trigger. Ignored when `href`/`to` make the button render as a l… |
| `target` | `string \| undefined` |  |  | Sets or retrieves the window or frame at which to target content. |
| `text` | `string \| undefined` |  |  | Text content of the component. |
| `to` | `string \| wt \| bt \| undefined` |  |  | Route Location the link should navigate to when clicked on. |
| `trueValue` | `any` | `true` |  | Value emitted when the toggle is activated. |
| `type` | `"button" \| "submit" \| "reset" \| undefined` |  |  | Gets the classification and default behavior of the button. |
| `variant` | `ButtonVariantType \| undefined` | `"primary"` |  | Visual variant of the button. Controls colors and surface style while keeping spacing and sizing unchanged. |
| `viewTransition` | `boolean \| undefined` | `false` |  | Inertia: run the page swap inside a View Transition, where the browser supports one. |

## Events

- `update:modelValue` — `(event: "update:modelValue", value: any): void`

## Slots

- `default` — scope: `object` — Primary content rendered inside the button. Falls back to the `text` prop when empty.

## See Also

- [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).

---

<!-- dist/ai/BbCheckbox.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbCheckbox.md -->

# BbCheckbox

## Agent Contract

- Safety level: **Consumer API**
- Group: **Selection**
- Description: Toggles a single boolean option.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbCheckbox.md](./source/BbCheckbox.md)

## Usage & Guidelines

### When to use

Reach for `BbCheckbox` when the answer is a single yes/no on its own: accept the
terms, subscribe to the newsletter, remember this device. One box, one boolean.

Pick the right sibling instead when the shape changes:

- Several **non-exclusive** choices from a small, fixed set → `BbCheckboxGroup`
  (one fieldset, one bound array — never a hand-rolled row of `BbCheckbox`).
- Several **exclusive** choices → `BbRadioGroup`.
- A large or dynamic option set → `BbSelect` (it adds search and async fetch).
- The on/off **state of a thing** (notifications, dark mode, "anyone with the
  link can view") → `BbSwitch`. Decide on meaning, not on timing: a checkbox is
  an answer or a selection, a switch is a state. A switch is correct inside a
  submit-gated form too, so the presence of a Save button is **not** a reason to
  pick `BbCheckbox`.

### States, hint and validation

`BbCheckbox` carries the full form-field surface: `label`, `hint`,
`description`, `errors` / `has-errors`, plus `readonly` and `disabled`. Keep the
`label` short and affirmative — the box already implies the question.

**The states you'll actually ship**

```vue
<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-3">
	<BbCheckbox label="Email me product updates" name="s-on" checked />
	<BbCheckbox
		label="Send a weekly digest"
		name="s-hint"
		hint="At most one email every Monday."
		persistent-hint
	/>
	<BbCheckbox
		label="I accept the terms of service"
		name="s-err"
		has-errors
		errors="You must accept the terms to continue."
	/>
	<BbCheckbox label="Managed by your admin" name="s-ro" checked readonly />
	<BbCheckbox label="Unavailable on your plan" name="s-dis" disabled />
</div>
```

How the pieces behave:

- `hint` stays hidden until the field is focused unless you set
  `persistent-hint`; `description` is always-visible helper text rendered above
  the box. Both are linked to the input via `aria-describedby`.
- `errors` accepts one string or an array; messages render in an
  `aria-live="polite"` region, are referenced first from the input's
  `aria-describedby` while present, and a **non-empty `errors` puts the field in the
  error state by itself** — `has-errors` exists for styling the invalid state
  without (or before) showing messages.
- `warnings` is the amber counterpart of `errors`: one string or an array,
  rendered in its own `aria-live="polite"` region (also referenced from
  `aria-describedby` while displayed) for a valid-but-noteworthy
  value (unusual, near a limit, soft-flagged) where a hard error would overstate
  the problem. A **non-empty `warnings` puts the field in the warning state by
  itself** — mirroring how `errors` implies the error state — and `has-warning`
  forces that amber chrome without a message. `has-errors` wins when both are
  set (the warning messages are then suppressed), and unlike the error state
  neither warning prop sets `aria-invalid` — it's a soft "needs a second look",
  not an invalid one.
- `required` sets the native attribute, so the checkbox participates in native
  form validation. For app-driven validation prefer `errors` / `has-errors`
  over the browser bubble.

#### `readonly` is not `disabled`

The two states differ in more than styling — choose deliberately:

- `disabled` sets the **native** `disabled` attribute: the box leaves the tab
  order and its value is never submitted with a form.
- `readonly` does **not** set the native `disabled` attribute (checkboxes have
  no native readonly). The input stays focusable, announces
  `aria-readonly` / `aria-disabled`, still submits its value, and the component
  blocks every change (clicks and Space/Enter are swallowed,
  `update:modelValue` never fires). Use it for values the user may see — and
  that must still post — but not change.

### The value contract: booleans, domain values, form posts

By default the model is `true` / `false`. Map it to your own domain values with
`true-value` / `false-value` — any serializable value works, and checked-ness is
derived by **deep equality** (`modelValue` vs `true-value`), so object values
match structurally. `update:modelValue` always emits `true-value` when checking
and `false-value` when unchecking.

**Terms consent with domain values**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Privacy consent</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Posted as a domain value — not a raw boolean.
			</p>
		</div>
		<BbCheckbox
			v-model="consent"
			false-value="declined"
			label="I accept the privacy policy"
			name="consent"
			submit-when-false
			true-value="accepted"
		/>
		<p class="text-xs text-[color:var(--bb-text-muted)]">
			Submitted value:
			<span class="font-medium text-[color:var(--bb-text)]">{{ consent }}</span>
		</p>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbCheckbox } from 'bitboss-ui';

// The model holds a domain value, not a raw boolean — checked-ness is derived
// by deep equality against `true-value`, so it starts on the false value.
const consent = ref<'accepted' | 'declined'>('declined');
</script>
```

For classic (non-XHR) form posts the native input carries `name` and a
serialized value — strings are posted as-is, everything else is
`JSON.stringify`-ed:

- Checked → `name=trueValue` is posted.
- Unchecked → **nothing is posted** (standard HTML behavior), unless you set
  `submit-when-false`, which renders a hidden input posting `false-value`
  instead — so the server always receives a value for the field.
- `name` is only what you pass; set it whenever the checkbox lives in a real
  `<form>`.

```vue
<!-- Native post: the server always receives digest=weekly or digest=off -->
<form action="/preferences" method="post">
	<BbCheckbox
		false-value="off"
		label="Weekly digest"
		name="digest"
		submit-when-false
		true-value="weekly"
	/>
</form>
```

In an Inertia or SPA app skip the form-post surface entirely and bind into your
form state:

```vue
<!-- Inertia: v-model into useForm state; no name/submit-when-false needed -->
<BbCheckbox v-model="form.newsletter" label="Subscribe to the newsletter" />
```

#### Forcing the displayed state with `checked`

`checked` (booleanish: `true`/`false` or `'true'`/`'false'`) overrides the
model-derived display: when set, the box shows that state regardless of
`modelValue`, and re-syncs whenever the prop changes. Interaction still emits
`update:modelValue`. Use it when the checked display is derived from elsewhere
(server state, a parent aggregate) and you handle updates through events rather
than `v-model` — the select-all master below is the canonical case.

### Rich labels and custom icons

For consent rows that must link to legal copy, use the `label` slot instead of
the `label` prop. The whole control stays one clickable `<label>`, so keep
interactive children (links) as real anchors — clicks on them navigate rather
than toggling. The slot receives `{ text, hasErrors }`.

**Terms label with inline links**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Accept terms</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Links stay real anchors — clicks navigate instead of toggling.
			</p>
		</div>
		<BbCheckbox
			v-model="agree"
			label="I agree to the terms and privacy policy"
			name="tos"
		>
			<template #label>
				<span>
					I agree to the
					<a class="font-medium underline" href="#terms">Terms of Service</a>
					and
					<a class="font-medium underline" href="#privacy">Privacy Policy</a>
				</span>
			</template>
		</BbCheckbox>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbCheckbox } from 'bitboss-ui';

const agree = ref(false);
</script>
```

The `icon` slot replaces the **entire box visual** — border, background and
checkmark all come from the default SVG, so your slot content must communicate
both states itself (the state-driven classes below are exactly that
consumer-owned visual, called out on purpose). The payload carries everything
needed: `checked`, `indeterminate`, `disabled`, `readonly`, `hasErrors`,
`focused`, `focusVisible`, `trueValue` / `falseValue`, the current `value`, and
the label `text`.

**Custom icon for a critical-alert opt-in**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Critical alerts</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Custom icon owns both states — checked and unchecked.
			</p>
		</div>
		<BbCheckbox
			v-model="alerts"
			label="Wake me for critical alerts"
			name="alerts"
		>
			<template #icon="{ checked, focusVisible }">
				<span
					class="inline-flex h-5 w-5 items-center justify-center rounded-[var(--bb-radius-sm)]"
					:class="[
						checked
							? 'bg-[color:var(--bb-primary)] text-[color:var(--bb-primary-fg)]'
							: 'border border-[color:var(--bb-border)] text-[color:var(--bb-text-muted)]',
						focusVisible
							? 'ring-2 ring-[color:var(--bb-ring)] ring-offset-1'
							: '',
					]"
				>
					<BbIcon icon="lucide:bell" size="xs" />
				</span>
			</template>
		</BbCheckbox>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbCheckbox, BbIcon } from 'bitboss-ui';

const alerts = ref(true);
</script>
```

### Notification preferences that save with the form

Each row here is an **opt-in** — an answer the user gives — so it is a checkbox,
and the primary button posts the whole set. Had the same rows been framed as the
state of each channel ("Email notifications: on/off"), `BbSwitch` would be right
even though a Save button posts them; the Save button is not what decides it.

**Email notification preferences**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Email notifications</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Saved with your account — nothing changes until you hit Save.
			</p>
		</div>
		<div class="grid gap-2">
			<BbCheckbox
				v-model="prefs.product"
				description="New features and changelog highlights."
				label="Product updates"
				name="notify-product"
			/>
			<BbCheckbox
				v-model="prefs.billing"
				description="Invoices, failed charges, and plan changes."
				label="Billing receipts"
				name="notify-billing"
			/>
			<BbCheckbox
				v-model="prefs.digest"
				hint="At most one email every Monday."
				label="Weekly digest"
				name="notify-digest"
				persistent-hint
			/>
		</div>
		<div class="flex items-center gap-2">
			<BbButton variant="primary" @click="save">Save preferences</BbButton>
			<span class="text-xs text-[color:var(--bb-text-muted)]">{{
				status
			}}</span>
		</div>
	</div>
</template>

<script setup lang="ts">
import { reactive, ref } from 'vue';
import { BbButton, BbCheckbox } from 'bitboss-ui';

const prefs = reactive({
	product: true,
	billing: true,
	digest: false,
});

const status = ref('Unsaved changes');

/** Stand-in save; the button spins until the promise settles. */
const save = async () => {
	await new Promise((resolve) => setTimeout(resolve, 600));
	status.value = 'Preferences saved';
};
</script>
```

### Gating the next step on consent

The most famous checkbox pattern of all: the "I agree" box that unlocks the
primary action. Bind the button's `disabled` to the model — don't intercept the
click and check the box's state by hand, and don't validate after the fact when
the disabled state can simply tell the truth up front.

**Consent gates account creation**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Create your account</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Last step — accept the terms to unlock Create account.
			</p>
		</div>
		<div class="grid gap-2">
			<BbCheckbox
				v-model="tos"
				label="I agree to the Terms of Service"
				name="signup-tos"
				required
			/>
			<BbCheckbox
				v-model="digest"
				label="Email me product updates (optional)"
				name="signup-digest"
			/>
		</div>
		<BbButton class="self-start" :disabled="!tos" variant="primary">
			Create account
		</BbButton>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbCheckbox } from 'bitboss-ui';

const tos = ref(false);
const digest = ref(true);
</script>
```

### Indeterminate: the "select all" master

`indeterminate` is a purely visual third state (a dash, not a check) — it does
**not** change the model, and the component re-applies it after user clicks
(natively the state would reset on interaction). Assistive tech announces the
native mixed state. Use it for a parent checkbox that summarises a group:
checked when all children are on, indeterminate when only some are. Drive the
displayed state with `checked` from the child selection and handle
`update:modelValue` to toggle the whole set; pair it with a `BbCheckboxGroup`
for the children.

**Select-all master over token scopes**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Token permissions</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Scopes this personal access token can use.
			</p>
		</div>
		<fieldset class="m-0 grid gap-2 border-0 p-0">
			<BbCheckbox
				:checked="allSelected"
				:indeterminate="someSelected"
				label="All scopes"
				name="scope-all"
				@update:model-value="toggleAll"
			/>
			<BbCheckboxGroup
				v-model="granted"
				class="pl-5"
				hide-legend
				item-text="label"
				item-value="value"
				:items="scopes"
				legend="Scopes"
				name="scope-list"
			/>
			<p class="selection-summary text-xs text-[color:var(--bb-text-muted)]">
				{{ granted.length }} of {{ scopes.length }} scopes granted
			</p>
		</fieldset>
	</div>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbCheckbox, BbCheckboxGroup } from 'bitboss-ui';

type Scope = { label: string; value: string };

const scopes: Scope[] = [
	{ label: 'Read repository contents', value: 'repo:read' },
	{ label: 'Write and push commits', value: 'repo:write' },
	{ label: 'Manage webhooks', value: 'admin:hooks' },
];

const granted = ref<string[]>(['repo:read']);

const allSelected = computed(() => granted.value.length === scopes.length);
const someSelected = computed(
	() => granted.value.length > 0 && !allSelected.value
);

const toggleAll = (checked: boolean) => {
	granted.value = checked ? scopes.map((scope) => scope.value) : [];
};
</script>
```

### Layout: direction, alignment, `reverse`

- `direction` defaults to `'auto'` (label and box size to their content, on one
  line). `'horizontal'` splits label/box 50-50; `'vertical'` stacks them; a
  two-token pattern like `"x xxxxxxx"` splits proportionally by token length —
  the first token sizes the **visually first** element, the second the other.
- The box renders **before** the label by default — the conventional checkbox
  arrangement. Setting `reverse` swaps the label in front of the box. It is an
  ordinary opt-in boolean: unset and `:reverse="false"` both give box-first,
  `reverse` gives label-first. (There _is_ an internal negation in the source,
  but it exists to cancel `BbBaseInputContainer`'s own polarity, so it is
  invisible from outside. Earlier revisions of this guide described that
  negation as a consumer-facing quirk — it is not.)
- `input-position` / `label-position` (`'left' | 'center' | 'right'`) align box
  and label text inside their columns — useful with percentage directions.
- `hide-label` keeps the label for screen readers but hides it visually — only
  for dense composites where visible text lives elsewhere.
- `id` is auto-generated for the label→input wiring; pass your own only when
  external markup must reference the input.

### Events and focus

`v-model` (`update:modelValue`) is the state channel — payload `true-value` /
`false-value`, nothing else. The native `blur`, `change`, `click`, `focus`,
`input`, `keydown`, `mousedown`, `mouseup` events are forwarded with their raw
DOM payloads; listen to them only for side concerns (analytics, focus
tracking) — never to compute the checked state yourself. Keyboard support is
native: the box is one tab stop and Space toggles it. `autofocus` focuses the
input on mount — use sparingly.

### Works well with

- `BbCheckboxGroup` — the children under a select-all master
  (`./BbCheckboxGroup.md`).
- `BbSwitch` — swap to it when the control is a state rather than an answer,
  whether it commits instantly or on save.
- `BbButton` — gate a submit's `disabled` on the model for agree-to-continue
  flows.
- `BbDialog` — a consent checkbox inside the dialog body that unlocks the
  confirm action.

### Gotchas and anti-patterns

- Don't hand-roll a stack of `BbCheckbox` for a multi-choice set — that's
  `BbCheckboxGroup` (fieldset semantics, item mapping, `max` for free).
- Don't toggle via `@click` handlers mutating your own ref — bind `v-model` and
  let the component emit.
- `indeterminate` never appears in the model; if your server needs a tri-state
  value, model it explicitly (e.g. `true-value` / `false-value` plus a separate
  "unset" representation).
- `readonly` still submits and stays focusable — if the value must not post,
  use `disabled` (see the readonly-vs-disabled section).
- Unchecked boxes post nothing in classic forms; use `submit-when-false` when
  the backend expects an explicit "no".
- `reverse` is an opt-in, not a toggle you turn off: unset already means
  box-first. Setting `:reverse="false"` is legal but says nothing.
- `checked` + `v-model` together fight each other; pick one source of truth.

### Accessibility

- Always pass a `label` (or `label` slot) — never rely on nearby text alone.
- `errors`, `warnings`, `description` and `hint` are all wired to the input through
  `aria-describedby`, in that order: the reason the field is invalid is spoken
  first when it regains focus, and a channel is referenced only while it
  actually has copy. Messages _also_ render in an `aria-live="polite"` region,
  so they are announced the moment they appear — announced on change, re-read
  on focus.
- Prefer offering a real choice over a `disabled` box; when you must disable,
  explain why in adjacent `description` text.
- `readonly` communicates via `aria-readonly` / `aria-disabled`; it does not set
  the native `disabled` attribute, so the input remains focusable and the value
  still submits with the form.
- With a custom `icon` slot, all state styling is yours — make sure `checked`,
  `focusVisible` and `hasErrors` remain visually distinguishable.

## v-model

- `v-model` — type: `any`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
| `checked` | `boolean \| undefined` | `undefined` |  | Defines the input as checked. |
| `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
| `direction` | `InputDirection \| undefined` | `"auto"` |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
| `falseValue` | `any` |  |  | Value of the input when unchecked. It handles any kind of serializable object. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `indeterminate` | `boolean \| undefined` | `false` |  | Sets the input in an indeterminate state. |
| `inputPosition` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can. |
| `label` | `string` |  | yes | Text content of the label of the element. |
| `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
| `modelValue` | `any` |  |  | Used by v-model. Can be any serializable type. |
| `name` | `string \| undefined` |  |  | Defines the name of the input. |
| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout: in every direction the order of the label and the input is swapped from the standard arrangement. |
| `submitWhenFalse` | `boolean \| undefined` | `false` |  | Will submit "falseValue" if the input is not checked. Otherwise "trueValue" will be submitted. |
| `trueValue` | `any` |  |  | Value of the input when checked. It handles any kind of serializable object. |
| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |

## Events

- `blur` — `(event: "blur", event: FocusEvent): void`
- `change` — `(event: "change", event: Event): void`
- `click` — `(event: "click", event: MouseEvent): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `input` — `(event: "input", event: Event): void`
- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
- `update:modelValue` — `(event: "update:modelValue", value: any): void`

## Slots

- `icon` — scope: `BbCheckboxIconSlotProps` — Replaces the default checkmark SVG inside the checkbox box. Receives `BaseCheckbox` slot attributes plus the label text.
- `label` — scope: `BbCheckboxLabelSlotProps` — Replaces the default label text rendered next to the checkbox.

## Validated variant

Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).

| Prop | Type | Description |
| --- | --- | --- |
| `rules` | `RuleExpression<any>` | vee-validate rules for this field. |
| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |

## See Also

- [BbCheckboxGroup](./BbCheckboxGroup.md) — Manages multiple checkbox options as a group.
- [BbSwitch](./BbSwitch.md) — Toggles two-state values with switch semantics.

---

<!-- dist/ai/BbCheckboxGroup.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbCheckboxGroup.md -->

# BbCheckboxGroup

## Agent Contract

- Safety level: **Consumer API**
- Group: **Selection**
- Description: Manages multiple checkbox options as a group.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbCheckboxGroup.md](./source/BbCheckboxGroup.md)

## Usage & Guidelines

### When to use

Use `BbCheckboxGroup` when the user may pick **several** options from a short,
always-visible list — notification channels, interests, permissions. It renders
one `<fieldset>` with a `<legend>`, binds a single **array**, and derives each
box from your `items`. Never hand-assemble a row of `BbCheckbox`: the group
gives you the fieldset semantics, item mapping, a selection `max`, and validation
for free.

Reach elsewhere when the shape differs:

- Exactly one choice from the set → `BbRadioGroup`.
- A large or dynamic/async option set → `BbSelect` (adds search + fetch); past
  ~8 checkboxes the list becomes a wall to scan.
- Rows that read as the on/off **state of a thing** rather than options to pick
  → `BbSwitchGroup` (whether they commit live or on submit).
- A single standalone boolean (accept terms, one opt-in) → `BbCheckbox`.

### Items are your domain objects

Pass backend rows straight to `items` and select the display text and stored
value declaratively with `item-text` / `item-value` — never pre-map into
`{ label, value }` objects. The bound array then holds just the values you
mapped (here, channel ids), which is what you send back to the server.

**Notification channels from objects**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
		<div>
			<h3 class="text-sm font-medium">Notification preferences</h3>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				We only send what you opt into.
			</p>
		</div>
		<BbCheckboxGroup
			v-model="selected"
			compact
			hint="Choose one or more channels."
			item-text="label"
			item-value="id"
			:items="channels"
			legend="Channels"
			name="channels"
			persistent-hint
		/>
		<p class="channel-summary text-xs text-[color:var(--bb-text-muted)]">
			{{ selected.length }} channel{{ selected.length === 1 ? '' : 's' }} on
		</p>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbCheckboxGroup } from 'bitboss-ui';

type Channel = {
	id: string;
	label: string;
};

const channels: Channel[] = [
	{ id: 'email', label: 'Email' },
	{ id: 'sms', label: 'SMS' },
	{ id: 'push', label: 'Push notifications' },
	{ id: 'slack', label: 'Slack' },
];

const selected = ref<string[]>(['email']);
</script>
```

The mapping grammar (shared by every items-driven component — see the
[options & items playbook](../../ai/guides/options-items-playbook.md)):

- **Primitive `items`** (`string[]` / `number[]`): omit both props; the value is
  the primitive itself.
- **Dot path**: `item-value="id"`, `item-text="profile.fullName"`.
- **Extractor function** when a path can't express it:
  `:item-text="(c) => c.label + ' (' + c.region + ')'"`.

Selection is matched by **deep value equality** (`hash(item-value)` vs each
array entry), not reference identity — object values match structurally, but
prefer stable primitive ids: they survive refetches and are cheap to submit.
Two items that resolve to the **same** `item-value` collapse to one option
(first wins), so keep values unique.

### The array model is mandatory

`multiple` defaults to **`true`**, so `modelValue` **must be an array** — seed
your ref with `ref([])`, never a bare `ref()`. A non-array model in multiple
mode **throws at setup** (`"multiple is set to true but modelValue is not an
array"`); this is deliberate, to catch the mistake early rather than silently
mis-binding.

```ts
const channels = ref<string[]>([]); // correct — seeded array
const channels = ref(); // throws at setup
```

Checking a box appends its value to the array; unchecking removes it. The whole
array is re-emitted each time, so treat `v-model` as immutable and never splice
it yourself. For the rare "pick zero or one, but from a checkbox-styled list"
case, set `:multiple="false"` — then the model is a single value (seed `null`)
and picking a second box replaces the first.

**Single-select mode via :multiple=false**

```vue
<BbCheckboxGroup
	v-model="state.pick"
	legend="Preferred contact time"
	:items="['Morning', 'Afternoon', 'Evening']"
	:multiple="false"
	name="contact-time"
/>
```

### Cap the selection with `max`

`max` limits how many boxes can be checked at once. Once the cap is reached the
remaining **unchecked** options disable automatically — no custom logic — while
**already-checked options stay toggleable**, so the user can always swap a
choice out. Pair it with a `hint` that states the limit.

**Pick up to three, laid out horizontally**

```vue
<template>
	<div class="grid max-w-md gap-3 rounded-[var(--bb-radius)] border p-3">
		<div>
			<h3 class="text-sm font-medium">Personalize your feed</h3>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Pick up to three topics to follow.
			</p>
		</div>
		<BbCheckboxGroup
			v-model="topics"
			compact
			hint="You can change these anytime."
			input-direction="horizontal"
			:items="allTopics"
			legend="Topics"
			:max="3"
			name="topics"
			persistent-hint
		/>
		<p class="text-xs text-[color:var(--bb-text-muted)]">
			{{ topics.length }} / 3 selected
		</p>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbCheckboxGroup } from 'bitboss-ui';

const allTopics = [
	'Design',
	'Engineering',
	'Product',
	'Marketing',
	'Sales',
	'Support',
];

const topics = ref<string[]>(['Design']);
</script>
```

### Gate individual options with `selectable`

`selectable` controls which options can be picked: a global boolean (`false`
disables every box — rare; prefer the `disabled` prop) or a predicate
`(item) => boolean` evaluated per option. Options the predicate rejects render
disabled while the rest stay interactive. A `disabled` field on the item object
itself has **no effect** — items are plain domain data; when availability lives
on the row, feed that field to the predicate.

**Unconfigured channels can't be picked**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
		<div>
			<h3 class="text-sm font-medium">Delivery channels</h3>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Unconfigured channels stay unavailable until setup finishes.
			</p>
		</div>
		<BbCheckboxGroup
			v-model="selected"
			compact
			hint="SMS unlocks once a sender number is configured."
			item-text="label"
			item-value="id"
			:items="channels"
			legend="Channels"
			name="available-channels"
			persistent-hint
			:selectable="(channel) => channel.configured"
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbCheckboxGroup } from 'bitboss-ui';

type Channel = {
	id: string;
	label: string;
	configured: boolean;
};

const channels: Channel[] = [
	{ id: 'email', label: 'Email', configured: true },
	{ id: 'sms', label: 'SMS', configured: false },
	{ id: 'push', label: 'Push notifications', configured: true },
	{ id: 'slack', label: 'Slack', configured: true },
];

const selected = ref<string[]>(['email']);
</script>
```

When a dead row would only add noise, filter the item out of `items` instead of
disabling it.

### Layout and density

- `input-direction` (`'horizontal' | 'vertical'`) arranges the **options**
  within the fieldset — a row for compact filter bars, a stack for readability.
- `direction` arranges the **legend against the options block** (the outer
  label/control split): `'auto'`, `'horizontal'`, `'vertical'`, or a
  proportional pattern like `'xx xxxxxx'`.
- `compact` tightens per-option spacing for dense groups.
- `input-position` / `legend-position` (`'left' | 'center' | 'right'`) align the
  options and the legend text within their columns.
- `reverse` swaps the legend and options order. (Unlike standalone `BbRadio` /
  `BbCheckbox`, the group's `reverse` is **not** inverted — it behaves as a
  plain on/off swap.)
- `hide-legend` keeps the legend for assistive tech but hides it visually;
  `hide-label` hides the individual option labels (dense composites only).

### Legend, description and validation

The `legend` is the group's accessible name — always set it. `description` is
always-visible helper text above the options; `hint` shows on focus unless you
pin it with `persistent-hint`; both are wired to the group via
`aria-describedby`. `errors` (string or array) renders messages and, when
non-empty, puts the group in the error state on its own; `has-errors` toggles
the invalid styling without (or before) messages. `warnings` is the amber
counterpart of `errors` — one string or an array, rendered in its own
`aria-live="polite"` region (also referenced from `aria-describedby` while
displayed) for a valid-but-noteworthy selection where a hard
error would overstate the problem; a non-empty `warnings` implies the warning
state (just as `errors` implies the error state), while `has-warning` forces
that amber chrome without a message. `has-errors` wins when both are set (the
warning messages are then suppressed), and unlike it neither warning prop sets
`aria-invalid` — a soft "needs a second look" rather than an invalid state.
`legend-mode` places the
legend `'outside'` (default, above the fieldset) or `'inside'` (overlaid on the
border) — floating mode is not supported for checkbox groups.

**Consent group with an error**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
		<div>
			<h3 class="text-sm font-medium">Privacy & contact</h3>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Choose how we may reach you about your account.
			</p>
		</div>
		<BbCheckboxGroup
			v-model="consents"
			compact
			description="Required to finish onboarding."
			:errors="
				consents.length === 0
					? 'Select at least one contact method.'
					: undefined
			"
			item-text="label"
			item-value="id"
			:items="options"
			legend="Contact permissions"
			legend-mode="inside"
			name="consents"
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbCheckboxGroup } from 'bitboss-ui';

type Consent = {
	id: string;
	label: string;
};

const options: Consent[] = [
	{ id: 'transactional', label: 'Transactional emails' },
	{ id: 'product', label: 'Product announcements' },
	{ id: 'research', label: 'Research invitations' },
];

const consents = ref<string[]>([]);
</script>
```

Note there is **no `required` prop** on `BbCheckboxGroup` (unlike `BbRadioGroup`):
"at least one" is an app rule, so drive it through `errors` / `has-errors` as
above.

### Async items, loading and coherence

`items` also accepts a provider function (`(prefill, modelValue) => T[] |
Promise<T[]>`) for options fetched from an API. The group calls it on mount with
`prefill = true`; every dependency-driven refetch passes `prefill = false`.
While it resolves, `loading-text` (or the `#loading` slot) shows; `no-data-text`
(or `#no-data`) covers the empty result. Loading and race protection are
built in — don't wrap the provider in your own `loading` ref or debounce.

Tie the option set to external state with `dependencies` (debounced by
`deps-debounce-time`) instead of a manual watcher, and set `enforce-coherence`
so any model entry that no longer matches an available option is dropped
automatically after a reload. Here the scopes a token may request depend on its
role: switching the role re-runs the provider and prunes granted scopes the new
role doesn't offer — `repo:write` vanishes from the model when you drop to
Read-only, with no cleanup code.

**Token scopes constrained by role (fetch + coherence)**

```vue
<template>
	<div class="grid max-w-md gap-3 rounded-[var(--bb-radius)] border p-3">
		<div>
			<h3 class="text-sm font-medium">Create access token</h3>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Scopes stay coherent with the selected role.
			</p>
		</div>
		<BbRadioGroup
			v-model="role"
			compact
			input-direction="horizontal"
			item-text="label"
			item-value="id"
			:items="roles"
			legend="Token role"
			name="token-role"
		/>
		<BbCheckboxGroup
			v-model="scopes"
			compact
			:dependencies="[role]"
			:deps-debounce-time="150"
			enforce-coherence
			hint="Scopes outside the selected role are removed automatically."
			item-text="label"
			item-value="id"
			:items="loadScopes"
			legend="Scopes"
			loading-text="Loading scopes…"
			name="token-scopes"
			persistent-hint
		/>
		<p class="scope-summary text-xs text-[color:var(--bb-text-muted)]">
			{{ scopes.length }} scope{{ scopes.length === 1 ? '' : 's' }} granted
		</p>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbCheckboxGroup, BbRadioGroup } from 'bitboss-ui';

type Role = 'read' | 'developer' | 'admin';

type Scope = {
	id: string;
	label: string;
	roles: Role[];
};

const roles: Array<{ id: Role; label: string }> = [
	{ id: 'read', label: 'Read-only' },
	{ id: 'developer', label: 'Developer' },
	{ id: 'admin', label: 'Admin' },
];

const allScopes: Scope[] = [
	{
		id: 'repo:read',
		label: 'Read repositories',
		roles: ['read', 'developer', 'admin'],
	},
	{
		id: 'repo:write',
		label: 'Write repositories',
		roles: ['developer', 'admin'],
	},
	{
		id: 'workflows:run',
		label: 'Run workflows',
		roles: ['developer', 'admin'],
	},
	{ id: 'members:manage', label: 'Manage members', roles: ['admin'] },
];

const role = ref<Role>('developer');
const scopes = ref<string[]>(['repo:read', 'repo:write']);

// Non-query group provider: (prefill, modelValue). Groups always pass
// `prefill = true` — mount load and dependency refetches alike.
const loadScopes = (
	_prefill: boolean,
	_modelValue?: string[]
): Promise<Scope[]> =>
	new Promise((resolve) => {
		setTimeout(
			() =>
				resolve(allScopes.filter((scope) => scope.roles.includes(role.value))),
			300
		);
	});
</script>
```

See the [fetch-items](../../ai/guides/fetch-items-playbook.md) and
[coherence](../../ai/guides/coherence-playbook.md) playbooks for the full call
matrix and reconciliation rules. An empty selection is always coherent, so
enforcement can empty the array but never throws.

### Slots

Per-option, `#label` replaces an option's text (receives `{ item, text, checked }`)
and `#icon` replaces the **entire box visual** for that option (you then own its
checked/focus/error styling). `#legend` replaces the fieldset legend
(`{ text, hasErrors, hasWarning }`; the validated wrapper adds `showAsterisk`). `#prepend` / `#append` inject content inside the options
container, before the first / after the last box.

### Events and focus

`update:modelValue` (the `v-model` channel) carries the full array — it is the
only source of selection truth. The native `blur`, `change`, `click`, `focus`,
`input`, `keydown`, `mousedown`, `mouseup` events are re-emitted with their raw
payloads, plus the pair `active` (focus enters the group — it is what drives
the hint's show/hide internally) and `inactive` (focus leaves); listen to those
for analytics or side effects, never to compute selection yourself. `autofocus`
focuses the first option on mount — use sparingly.

### Works well with

- `BbCheckbox` — a select-all master above the group, driven by `indeterminate`
  (`./BbCheckbox.md`).
- `BbSwitchGroup` — the same items-driven group when each row is a live setting
  rather than a form answer (`./BbSwitchGroup.md`).
- `BbRadioGroup` — the single-choice sibling; an upstream radio choice driving
  this group via `dependencies` is the classic pairing (`./BbRadioGroup.md`).
- `BbSelect` — swap to it when the option set grows past a scannable list or
  needs async search.
- `BbButton` — gate a form submit's `disabled` on the bound array length.

### Gotchas and anti-patterns

- Don't hand-roll a stack of `BbCheckbox` for a multi-choice set — that's this
  component (fieldset semantics, item mapping, `max`, validation for free).
- Don't seed the `v-model` ref with a non-array in multiple mode — it **throws**
  at setup. Use `ref([])`.
- Don't mutate the bound array in place; bind `v-model` and let the group
  re-emit the whole array.
- At `max`, checked boxes deliberately stay enabled so the user can swap — don't
  add logic that disables them.
- A `disabled` field on an item object does nothing — it is inert data. Gate
  options with the `selectable` predicate, or disable the whole group with
  `disabled`.
- `readonly` still submits its values and stays focusable; use `disabled` only
  for choices that genuinely don't apply.
- Don't pre-map `items` into `{ label, value }` — pass raw rows and resolve with
  `item-text` / `item-value`.

### Accessibility

- Always provide a `legend` — it names the group for screen readers. Use
  `hide-legend` (not omission) when a visible heading already labels it.
- The group is a real `<fieldset>`; don't nest it inside another `<label>` or a
  `BbCheckbox`.
- `errors`, `warnings`, `description` and `hint` are all wired to the group through
  `aria-describedby`, in that order: the reason the field is invalid is spoken
  first when it regains focus, and a channel is referenced only while it
  actually has copy. Messages _also_ render in an `aria-live="polite"` region,
  so they are announced the moment they appear — announced on change, re-read
  on focus. Keep messages meaningful, not decorative.
- `readonly` communicates via `aria-readonly` and still submits; prefer it (with
  a nearby explanation) over a silent `disabled` for admin-locked groups.
- With a custom `#icon` slot the option's state styling is yours — keep
  `checked`, `focusVisible` and `hasErrors` visually distinct.

## v-model

- `v-model` — type: `any`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
| `compact` | `boolean \| undefined` | `false` |  | Displays the component in a compact version. |
| `dependencies` | `unknown[] \| undefined` |  |  | Defines an array of dependencies that will trigger actions in the component upon change. |
| `depsDebounceTime` | `number \| undefined` |  |  | Timeout used to debounce response to changes to dependencies. |
| `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
| `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
| `enforceCoherence` | `boolean \| undefined` | `false` |  | If coherence is enforced the input cannot have a modelValue that is incoherent with its current items. e.g. You cannot set v-model to a user that is not present in the items passed. modelValue will be reset upon incoherence. |
| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides each option's label text (the text rendered next to every input) while keeping it accessible to screen readers. Does not affect the fieldset legend — use `hideLegend` for that. |
| `hideLegend` | `boolean \| undefined` | `false` |  | Visually hides the legend of the fieldset while maintaining accessibility. |
| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `inputDirection` | `"horizontal" \| "vertical" \| undefined` |  |  | Defines the direction of the inputs in the fieldset. |
| `inputPosition` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can. |
| `items` | `T[] \| ((prefill: boolean, modelValue?: any) => T[] \| Promise<T[]>)` |  | yes | Used to retrieve items; can be an array or a function. |
| `itemText` | `ItemAccessor<T, string> \| undefined` |  |  | Defines a path that returns a property of the object to use as text or a function that returns a string. |
| `itemValue` | `ItemAccessor<T> \| undefined` |  |  | Defines a path that returns a property of the object to use as value or a function that returns any value. |
| `legend` | `string` |  | yes | Text content of the legend. |
| `legendMode` | `"outside" \| "inside" \| undefined` |  |  | Legend rendering mode. `'outside'` renders the legend above the fieldset in the normal flow; `'inside'` overlays the legend inside the fieldset border. Floating mode is not supported for option groups (checkbox, radio or switch) — there is … |
| `legendPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
| `loadingText` | `string \| undefined` |  |  | String displayed while items are being loaded. |
| `max` | `number \| undefined` |  |  | Maximum number of selected items. |
| `modelValue` | `any` |  | yes | Used by v-model. Can be an array of any serializable type. |
| `modelValueDebounceTime` | `number \| undefined` |  |  | Timeout used to debounce response to changes to modelValue. |
| `multiple` | `boolean \| undefined` | `true` |  | Enables multi-selection behavior. When true, `modelValue` must be an array. When false, `modelValue` should be a single value. |
| `name` | `string \| undefined` |  |  | Defines the name of the input. |
| `noDataText` | `string \| undefined` |  |  | String displayed when there are no items to display. |
| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
| `selectable` | `boolean \| ((item: T) => boolean) \| undefined` | `true` |  | Defines whether options are selectable. Can be a global boolean that affects all options or a function that accepts an item and returns a boolean that only affects that item. Non-selectable options are rendered disabled. |
| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |

## Events

- `active` — `(e: "active"): void` — Emitted when the group becomes active (focus/click enters it).
- `blur` — `(e: "blur", event: FocusEvent): void` — Emitted when one of the generated checkbox inputs loses focus. Forwards the original DOM `FocusEvent`.
- `change` — `(e: "change", event: Event): void` — Emitted when an option is toggled. Forwards the original DOM `Event` from the checkbox input.
- `click` — `(e: "click", event: MouseEvent): void` — Emitted when one of the generated checkbox inputs is clicked. Forwards the original DOM `MouseEvent`.
- `focus` — `(e: "focus", event: FocusEvent): void` — Emitted when one of the generated checkbox inputs receives focus. Forwards the original DOM `FocusEvent`.
- `inactive` — `(e: "inactive"): void` — Emitted when focus/click moves outside the group after it was active. Useful for validation-on-blur flows at group level.
- `input` — `(e: "input", event: Event): void` — Emitted on native input events from generated checkbox inputs. Forwards the original DOM `Event`.
- `keydown` — `(e: "keydown", event: KeyboardEvent): void` — Emitted for keyboard interaction on generated checkbox inputs. Forwards the original DOM `KeyboardEvent`.
- `mousedown` — `(e: "mousedown", event: MouseEvent): void` — Emitted when a pointing device button is pressed over a checkbox input. Forwards the original DOM `MouseEvent`.
- `mouseup` — `(e: "mouseup", event: MouseEvent): void` — Emitted when a pointing device button is released over a checkbox input. Forwards the original DOM `MouseEvent`.
- `update:modelValue` — `(e: "update:modelValue", value: any): void` — Emitted with the coherent next selection array whenever selection changes.

## Slots

- `append` — scope: `object` — Content rendered after the last option, inside the options container.
- `icon` — scope: `BaseCheckboxGroupIconSlotProps<T>` — Replaces the default checkmark icon for each checkbox option.
- `label` — scope: `BaseCheckboxGroupLabelSlotProps<T>` — Replaces the default label text for each option.
- `legend` — scope: `BbCheckboxGroupLegendSlotProps` — Replaces the default fieldset legend text for the group.
- `loading` — scope: `object` — Content shown while options are loading (replaces the default loading text).
- `no-data` — scope: `object` — Content shown when no options are available (replaces the default "no data" text).
- `prepend` — scope: `object` — Content rendered before the first option, inside the options container.

## Validated variant

Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).

| Prop | Type | Description |
| --- | --- | --- |
| `rules` | `RuleExpression<any>` | vee-validate rules for this field. |
| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |

## See Also

- [BbCheckbox](./BbCheckbox.md) — Toggles a single boolean option.
- [BbRadioGroup](./BbRadioGroup.md) — Coordinates exclusive selection among radio options.
- [BbSwitchGroup](./BbSwitchGroup.md) — Manages grouped switch options with shared behavior.
- [BbSelect](./BbSelect.md) — Selects one or many options from structured data.

---

<!-- dist/ai/BbCollapsible.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbCollapsible.md -->

# BbCollapsible

## Agent Contract

- Safety level: **Consumer API**
- Group: **Navigation**
- Description: Toggles visibility of collapsible content blocks.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbCollapsible.md](./source/BbCollapsible.md)

## Usage & Guidelines

### When to use

`BbCollapsible` is the middle rung of the disclosure ladder: a boolean-driven
region that animates open and closed. Unlike `BbAccordion` it ships **no header
button** — you bring your own trigger. Use it when the trigger lives somewhere
the accordion's composed header can't reach: a form's "Advanced options"
control, a changelog "Show more" link, a filter toggle in a toolbar, or an item
inside another component.

Pick the neighbour that fits instead when you can:

- Standard header-over-body accordion UX → **`BbAccordion`**
  (`./BbAccordion.md`) — wraps this component and wires all the ARIA for you.
- Content whose height changes for reasons _other_ than open/close (lists,
  async panels, wizard steps) → **`BbSmoothHeight`** (`./BbSmoothHeight.md`) —
  it has no hidden state, it only animates height.

The whole API: `modelValue` (boolean, defaults `false`), `eager`, `transition-duration`,
and one default slot. There are no events — see "You own the state" below.

### Advanced options in a form

Wire any control as the trigger and bind the same state. When the trigger is a
real disclosure, put `aria-expanded` on it and `aria-controls` pointing at the
collapsible's `id` — `BbAccordion` does exactly this internally. Keep the primary
fields visible; tuck rarely-needed controls behind the disclosure.

**Advanced options in a create-webhook form**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Create webhook</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Northwind Billing · deliver invoice events to your endpoint.
			</p>
		</div>

		<BbTextInput
			v-model="endpoint"
			compact
			label="Endpoint URL"
			placeholder="https://hooks.acme.com/invoices"
		/>

		<div class="flex flex-col gap-1.5">
			<BbButton
				append:icon="lucide:chevron-down"
				aria-controls="advanced-options"
				:aria-expanded="open"
				class="self-start"
				variant="ghost"
				@click="open = !open"
			>
				Advanced options
			</BbButton>

			<BbCollapsible id="advanced-options" v-model="open">
				<div class="flex flex-col gap-3 pt-1">
					<BbTextInput
						v-model="secret"
						compact
						hint="Sent as X-Webhook-Secret on every delivery."
						label="Signing secret"
						placeholder="whsec_…"
						type="password"
					/>
					<div class="flex gap-3">
						<BbNumberInput
							v-model="maxRetries"
							compact
							label="Max retries"
							:max="10"
							:min="0"
						/>
						<BbNumberInput
							v-model="timeoutSec"
							compact
							label="Timeout (s)"
							:max="60"
							:min="1"
						/>
					</div>
					<BbCheckbox v-model="includeDrafts" label="Include draft invoices" />
				</div>
			</BbCollapsible>
		</div>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import {
	BbButton,
	BbCheckbox,
	BbCollapsible,
	BbNumberInput,
	BbTextInput,
} from 'bitboss-ui';

const open = ref(false);
const endpoint = ref<string | null>('https://hooks.acme.com/invoices');
const secret = ref<string | null>(null);
const maxRetries = ref<number | null>(3);
const timeoutSec = ref<number | null>(10);
const includeDrafts = ref(false);
</script>
```

### You own the state (one-way model)

`modelValue` is a **one-way** prop and the component never writes it back:
`BbCollapsible` emits no events and has nothing to emit — it cannot close or
open itself. `v-model` works purely as a prop binding; every change comes from
your trigger. Two consequences:

- Initialize the boolean explicitly (`const open = ref(false)`). Omitting the
  binding is legal — it defaults to `false`, i.e. closed, and **nothing warns**
  — so a forgotten `v-model` looks like a collapsible that will not open.
- Don't listen for `update:modelValue` on it; put side effects on the trigger
  that flips the state.

### A form control as the trigger

Because the state is yours, the "trigger" doesn't have to be a button — any
control's model can drive the reveal. The classic settings-panel pattern binds
a `BbSwitch` and the collapsible to the **same ref**, so enabling the option
reveals its dependent fields with zero extra wiring. No `aria-expanded` here:
the switch's checked state already conveys it.

**A switch revealing dependent settings**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Custom domain</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Acme Docs · serve from your domain instead of *.bitdocs.app.
			</p>
		</div>

		<BbSwitch
			v-model="customDomain"
			description="Point a CNAME at edge.bitdocs.app before verifying."
			label="Use a custom domain"
		/>

		<BbCollapsible v-model="customDomain">
			<div class="flex flex-col gap-3 pt-1">
				<BbTextInput
					v-model="domain"
					compact
					hint="Example: docs.acme.com"
					label="Domain"
					placeholder="docs.acme.com"
				/>
				<div>
					<BbButton
						prepend:icon="lucide:globe"
						variant="outline"
						@click="verifyDns"
					>
						Verify DNS
					</BbButton>
				</div>
			</div>
		</BbCollapsible>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbCollapsible, BbSwitch, BbTextInput } from 'bitboss-ui';

const customDomain = ref(false);
const domain = ref<string | null>(null);

/** Simulated DNS check — BbButton tracks the returned promise as loading. */
const verifyDns = () =>
	new Promise<void>((resolve) => setTimeout(resolve, 600));
</script>
```

### Inline “show more”

The component renders as a `span` (with its own layout), so it is valid inside
a paragraph or next to prose. Keep spacing, borders and padding **on the
slotted content**, not on the collapsible itself: it forces a true
zero-footprint collapsed state and would strip them. Classic use: a changelog
entry that reveals the full bullet list on demand.

**Changelog entry with show more**

```vue
<template>
	<div
		class="flex max-w-md flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex items-baseline gap-2">
			<p class="text-sm font-medium">v3.2.0</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">Jul 18, 2026</p>
		</div>

		<p class="text-sm leading-relaxed">
			Billing exports now include tax breakdowns, and webhook deliveries retry
			with exponential backoff by default.
		</p>

		<BbCollapsible id="changelog-more" v-model="more">
			<ul
				class="flex flex-col gap-1.5 pt-1 text-sm text-[color:var(--bb-text-muted)]"
			>
				<li v-for="note in notes" :key="note">{{ note }}</li>
			</ul>
		</BbCollapsible>

		<BbButton
			aria-controls="changelog-more"
			:aria-expanded="more"
			class="self-start"
			variant="link"
			@click="more = !more"
		>
			{{ more ? 'Show less' : 'Show more' }}
		</BbButton>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbCollapsible } from 'bitboss-ui';

const more = ref(false);

const notes = [
	'Invoice PDF footer shows PO number when set on the draft.',
	'Member invites expire after 7 days; resend from Settings → Members.',
	'CSV import accepts up to 5,000 rows and reports row-level errors.',
	'API keys can be scoped to read-only billing endpoints.',
];
</script>
```

### Deferred vs eager mounting, and timing

The slot content is **not rendered until the first open**; after that it stays
mounted forever (internal state in the content survives close/reopen). Pass
`eager` to mount it up front when the content must exist in the DOM immediately:
SEO/searchable text, form fields that register or validate before the first
reveal, anything measured on mount.

Whether deferred or eager, **closed content is `aria-hidden` and `inert`** —
unfocusable, unclickable, out of the tab order. You never need `v-if` around it.

`transition-duration` (ms, default 250) drives both the height animation (a CSS
grid-rows transition) and the opacity/visibility fade. Under
`prefers-reduced-motion` both collapse to near-instant automatically.

**Eager refund policy with a slower transition**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Checkout · Acme Pro</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				$29 / month · billed annually
			</p>
		</div>

		<BbButton
			aria-controls="refund-policy"
			:aria-expanded="policyOpen"
			class="self-start"
			variant="outline"
			@click="policyOpen = !policyOpen"
		>
			{{ policyOpen ? 'Hide refund policy' : 'Refund policy' }}
		</BbButton>

		<!-- eager: policy text is in the DOM for search/SEO before first open.
		     transition-duration: 350ms (default 250). -->
		<BbCollapsible
			id="refund-policy"
			v-model="policyOpen"
			eager
			:transition-duration="350"
		>
			<p class="pt-1 text-sm text-[color:var(--bb-text-muted)]">
				Refunds return to the original payment method within 5–10 business days.
				Annual plans are refundable in full within 30 days of purchase.
			</p>
		</BbCollapsible>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbCollapsible } from 'bitboss-ui';

const policyOpen = ref(false);
</script>
```

### Exclusive-open groups

Several collapsibles become an exclusive group the same way accordions do: one
active key, each `model-value` derived from it. This is the pattern when the
triggers live in a segmented control or toolbar rather than stacked headers.

**One product-detail panel at a time**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Studio Display</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				INV-1042 · Acme Studio · $1,599.00
			</p>
		</div>

		<div class="flex gap-1.5">
			<BbButton
				v-for="tab in tabs"
				:key="tab.id"
				:aria-controls="tab.panelId"
				:aria-expanded="active === tab.id"
				size="sm"
				:variant="active === tab.id ? 'secondary' : 'outline'"
				@click="active = active === tab.id ? null : tab.id"
			>
				{{ tab.label }}
			</BbButton>
		</div>

		<BbCollapsible :id="tabs[0].panelId" :model-value="active === 'specs'">
			<p class="text-sm text-[color:var(--bb-text-muted)]">
				Aluminium body · 1.2&nbsp;kg · USB-C · 14&quot; matte display · 60 Hz.
			</p>
		</BbCollapsible>
		<BbCollapsible :id="tabs[1].panelId" :model-value="active === 'shipping'">
			<p class="text-sm text-[color:var(--bb-text-muted)]">
				Ships in 2–3 business days. Free returns within 30 days of delivery.
			</p>
		</BbCollapsible>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbCollapsible } from 'bitboss-ui';

type DetailTab = 'specs' | 'shipping';

const tabs: Array<{ id: DetailTab; label: string; panelId: string }> = [
	{ id: 'specs', label: 'Specs', panelId: 'detail-specs' },
	{ id: 'shipping', label: 'Shipping', panelId: 'detail-shipping' },
];

const active = ref<DetailTab | null>('specs');
</script>
```

### Works well with

- `BbAccordion` — reach for it first; it is this component plus a wired header.
- `BbButton` with `aria-expanded`/`aria-controls` — the canonical trigger.
- `BbSwitch`/`BbCheckbox` — reveal dependent fields when an option is enabled
  (bind the collapsible to the same model as the switch).
- `BbSmoothHeight` — the no-state sibling for pure height animation.

### Gotchas & anti-patterns

- **Don't put padding/border/gap on the collapsible or its direct wrapper** —
  the collapsed state forcibly zeroes them (that's what guarantees a
  zero-footprint collapse). Space the inner content instead.
- **Don't add `v-if` on the collapsible or its content** — you'd lose the
  animation and re-mount state; deferred mounting already handles the "don't
  render until needed" case.
- **Don't skip the trigger ARIA** — the component only manages
  `aria-hidden`/`inert` on its content; `aria-expanded`/`aria-controls` on the
  trigger (and a `role="region"` if you want one) are yours — or use
  `BbAccordion`, which wires all of it.
- **Don't use it as a pure height animator** — if nothing is ever hidden,
  `BbSmoothHeight` is the right tool.
- **Initialize the model** — an omitted or `undefined` binding silently
  behaves as closed and does **not** warn, so a missing `v-model` presents as
  "the collapsible is broken" rather than as a mistake.

### Accessibility

- Collapsed content is automatically `aria-hidden` and `inert`, so hidden
  controls leave the tab order — you get this for free, even with `eager`.
- You own the **trigger** semantics: give it `aria-expanded` and point
  `aria-controls` at the collapsible's `id`. Reach for `BbAccordion` when you'd
  rather not wire this yourself.
- Respects `prefers-reduced-motion` — the height and fade transitions collapse
  to near-instant automatically.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
| `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to trigger opening / closing the collapsible. Optional, matching the runtime: `withDefaults` supplies `false`, so an omitted binding renders closed and Vue never warns. It was typed required while carrying that default, whic… |
| `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds |

## Events

- None.

## Slots

- `default` — scope: `any` — The collapsible body content that is shown or hidden based on `modelValue`. When `eager` is false, the content is not rendered until the first open.

## See Also

- [BbAccordion](./BbAccordion.md) — Expands and collapses a content panel.
- [BbSmoothHeight](./BbSmoothHeight.md) — Animates height transitions for dynamic content.

---

<!-- dist/ai/BbColorInput.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbColorInput.md -->

# BbColorInput

## Agent Contract

- Safety level: **Consumer API**
- Group: **Inputs**
- Description: Captures color values through input controls.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbColorInput.md](./source/BbColorInput.md)

## Usage & Guidelines

### When to use

`BbColorInput` is a **form field** for a color value. It sits on the common input
wrapper, so it speaks the same language as every other field: `label`, `hint`,
`description`, `errors`, `disabled`, `compact`, prefix/suffix slots. The value is
a hex string bound with `v-model` (`string | null`), and the field ships a
built-in swatch dot that opens the color-picker popover.

Choose between the two color components by _what you are collecting_:

- Capturing a **typed value in a form** (brand color, theme setting, a row in a
  settings page) → **`BbColorInput`**. You get a label, a validatable hex field,
  and the picker in one control.
- Letting the user **pick a color off a trigger you own** (a color dot next to a
  calendar category, a label swatch in a menu) with no text field → reach for
  **`BbColorPalette`** (`./BbColorPalette.md`), the popover this field embeds.

`label` is required — it is the field's accessible name.

### Value format and typing behaviour

The model is hex-only: `#RRGGBB`, or `#RRGGBBAA` when `alpha` is set (values the
component emits are lowercase). There is no rgb()/hsl() mode — convert at the
edge if your backend stores another format. Typing is masked: a leading `#` is
enforced and only hex digits are accepted, capped at 6 (or 8) digits.
`update:modelValue` fires only when the text becomes a **complete valid hex**
(or `null` when the field is emptied/cleared) — partial input leaves the model
at its last valid value, so you never observe half-typed colors. Picking from
the palette emits the same normalized hex, continuously while dragging.

Initialize the model explicitly (`ref<string | null>(null)`) — `modelValue` is a
required prop, and an `undefined` binding warns in dev.

### A color field in a form

Drop it into a form like any input. `swatches` shows presets in the picker, and
users can type or pick — both paths land in the same `v-model`.

**Workspace brand & accent colors**

```vue
<template>
	<form
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
		@submit.prevent
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">Workspace appearance</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				Brand and accent colors for buttons, links, and chrome.
			</span>
		</div>

		<div
			class="flex items-center gap-2 rounded-[var(--bb-radius)] border bg-[color:var(--bb-muted)] px-3 py-2"
		>
			<span
				class="rounded-full px-2.5 py-0.5 text-xs font-medium"
				:style="{
					backgroundColor: brand ?? 'transparent',
					color: contrastOn(brand),
				}"
			>
				Primary
			</span>
			<span
				v-if="accent"
				class="rounded-full px-2.5 py-0.5 text-xs font-medium"
				:style="{
					backgroundColor: accent,
					color: contrastOn(accent),
				}"
			>
				Accent
			</span>
			<span v-else class="text-xs text-[color:var(--bb-text-muted)]"
				>No accent yet</span
			>
		</div>

		<BbColorInput
			v-model="brand"
			compact
			description="Used for primary buttons and links across the app."
			label="Brand color"
			placeholder="#RRGGBB"
			swatches
		/>
		<BbColorInput
			v-model="accent"
			clearable
			compact
			hint="Optional — falls back to the brand color."
			label="Accent color"
			placeholder="#RRGGBB"
			swatches
		/>

		<div class="flex justify-end">
			<BbButton variant="outline" @click="resetToDefaults">
				Reset to defaults
			</BbButton>
		</div>
	</form>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbColorInput } from 'bitboss-ui';

const DEFAULT_BRAND = '#4f46e5';
const DEFAULT_ACCENT = '#f59e0b';

const brand = ref<string | null>('#111827');
const accent = ref<string | null>(null);

/** Contrast-aware label on a dynamic swatch fill. */
const contrastOn = (hex: string | null) => {
	if (!hex || hex.length < 7) return 'var(--bb-text)';
	const r = parseInt(hex.slice(1, 3), 16);
	const g = parseInt(hex.slice(3, 5), 16);
	const b = parseInt(hex.slice(5, 7), 16);
	const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
	return luminance > 0.6 ? 'var(--bb-text)' : 'var(--bb-panel)';
};

const resetToDefaults = () => {
	brand.value = DEFAULT_BRAND;
	accent.value = DEFAULT_ACCENT;
};
</script>
```

### Presets, alpha and the eyedropper

- `swatches` controls the preset grid inside the picker: `true` shows the
  built-in palette (6 hue columns × 5 shades, red → purple); `string[][]` shows
  your own, where each inner array is a **column** of shades (design your ramps
  vertically); `false`/omitted hides the section. The swatch matching the
  current value is highlighted (compared on the `#RRGGBB` part,
  case-insensitively).
- `alpha` adds an opacity slider and switches the value format to `#RRGGBBAA`
  (the mask then accepts 8 digits).
- `eyeDropper` adds an eyedropper button to sample any pixel on screen. It relies on
  the native `EyeDropper` API (Chromium-based browsers): where unsupported the
  button simply doesn't render — treat it as an enhancement, never the only way
  to reach a color. A sampled color is opaque (alpha resets to full).

**Label color, overlay tint, eyedropper**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">Label & overlay</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				Custom swatch columns, optional alpha, and eyedropper when available.
			</span>
		</div>

		<BbColorInput
			v-model="labelColor"
			compact
			label="Label color"
			:swatches="SWATCH_COLUMNS"
		/>
		<BbColorInput
			v-model="overlay"
			alpha
			compact
			eye-dropper
			hint="Stored as #RRGGBBAA"
			label="Overlay tint"
			swatches
		/>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbColorInput } from 'bitboss-ui';

// Each inner array is a COLUMN of shades, one hue per column.
const SWATCH_COLUMNS: string[][] = [
	['#ef4444', '#f97316', '#f59e0b'],
	['#22c55e', '#10b981', '#14b8a6'],
	['#3b82f6', '#6366f1', '#8b5cf6'],
];

const labelColor = ref<string | null>('#f97316');
// alpha mode: the model carries an 8-digit #RRGGBBAA value.
const overlay = ref<string | null>('#6366f199');
</script>
```

### A label editor with live preview

`update:modelValue` fires continuously while the user drags inside the picker,
so live previews cost nothing — bind the model straight into a `:style`. This
is the GitHub-style "new label" pattern: a name, a color field with custom
swatch columns, and a pill that repaints as you drag. Because the model is
always a complete `#RRGGBB` hex, derived values (like contrast-aware text
color) can parse it without guards.

**New label with live preview**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">New label</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				GitHub-style — name a label and paint it as you drag.
			</span>
		</div>

		<span
			class="label-editor__preview self-start rounded-full px-2.5 py-0.5 text-xs font-medium"
			:style="{
				backgroundColor: color ?? 'var(--bb-muted)',
				color: textColor,
			}"
		>
			{{ name || 'label preview' }}
		</span>

		<BbTextInput
			v-model="name"
			compact
			label="Label name"
			placeholder="e.g. needs-triage"
		/>
		<BbColorInput
			v-model="color"
			compact
			label="Color"
			:swatches="SWATCH_COLUMNS"
		/>

		<div class="flex justify-end">
			<BbButton :disabled="!name || !color" variant="primary">
				Create label
			</BbButton>
		</div>
	</div>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbButton, BbColorInput, BbTextInput } from 'bitboss-ui';

// Each inner array is a COLUMN of shades (dark → light), one hue per column.
const SWATCH_COLUMNS: string[][] = [
	['#7f1d1d', '#b91c1c', '#ef4444'],
	['#78350f', '#b45309', '#f59e0b'],
	['#14532d', '#15803d', '#22c55e'],
	['#1e3a8a', '#1d4ed8', '#3b82f6'],
	['#4c1d95', '#6d28d9', '#8b5cf6'],
];

const name = ref<string | null>('bug');
const color = ref<string | null>('#b91c1c');

// The model is always a complete `#RRGGBB` hex, so parsing is safe.
const textColor = computed(() => {
	if (!color.value) return 'var(--bb-text)';
	const r = parseInt(color.value.slice(1, 3), 16);
	const g = parseInt(color.value.slice(3, 5), 16);
	const b = parseInt(color.value.slice(5, 7), 16);
	const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
	return luminance > 0.6 ? 'var(--bb-text)' : 'var(--bb-panel)';
});
</script>
```

### Label modes, help text and validation

`labelMode` (`outside` | `floating` | `inside`) positions the label, and
`labelPosition` (`left` | `center` | `right`) aligns it; `hide-label` keeps the
accessible name while hiding it visually. `description` is always-visible helper
text below the label; `hint` shows while the field is focused (or always with
`persistent-hint`). Drive the error state with `has-errors` + `errors` (string
or array — errors render below and the input gets `aria-invalid`), and add
`clearable` to let users empty the field (model becomes `null`). For a
valid-but-noteworthy value (unusual, near a limit, soft-flagged), `warnings` is
the amber counterpart of `errors` — a string or array rendered below the field
in its own `aria-live="polite"` region — and referenced from
`aria-describedby` while displayed — in amber (`--bb-text-warn`), with a warning
icon in the append stack; a non-empty `warnings` implies the warning state, so
`has-warning` is just the flag that forces the same chrome without a message.
Unlike `errors` it sets no `aria-invalid` — a soft "needs a second look" state,
not an invalid one. `has-errors` takes priority, so a field with both shows only
the error state and suppresses the warning messages.

Because the mask blocks invalid characters, client-side "not a color" errors are
rare — validation typically means **required** (`null` check on submit) or
server-side rules, surfaced through `errors`.

**Theme colors — floating label & errors**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">Theme colors</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				Floating label, always-visible description, and a required-field error.
			</span>
		</div>

		<BbColorInput
			v-model="theme"
			clearable
			compact
			description="Applied to the sidebar and active nav items."
			label="Theme color"
			label-mode="floating"
			swatches
		/>
		<BbColorInput
			v-model="accent"
			compact
			errors="Enter a valid hex color."
			has-errors
			label="Accent"
		/>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbColorInput } from 'bitboss-ui';

const theme = ref<string | null>('#4f46e5');
const accent = ref<string | null>(null);
</script>
```

### States, layout and input chrome

The full common-field surface applies:

- **States** — `disabled` (blocks input and the picker dot), `readonly` (value
  visible, no edits, picker blocked), `loading` (progress styling on the
  wrapper), `required`, `autofocus`, `placeholder`, `name` and `autocomplete`
  (defaults to `off`) for form plumbing.
- **Layout** — `compact` for a denser control; `direction`
  (`horizontal` | `vertical` | `auto`, or a pattern like `xx xxxxx` splitting
  label/input columns) and `reverse` to swap label and input order.
- **Icons & slots** — `prepend:icon`/`append:icon` add `lucide:*` icons inside
  the field. Slots: `prefix`/`suffix` for inline text at the edges of the typed
  value, `prepend`/`append` inside the field chrome, and
  `prepend-outer`/`append-outer` outside it. `label` is a scoped slot
  (`{ text, hasErrors }`) to enrich the label itself. Note the picker dot lives
  in the append area — an `append` slot renders after it, and replaces the
  default suffix wrapper.

**Chart series — compact with icon & suffix**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">Chart series</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				Compact field with a palette icon and a hex suffix.
			</span>
		</div>

		<BbColorInput
			v-model="chart"
			compact
			label="Series color"
			prepend:icon="lucide:palette"
			swatches
		>
			<template #suffix>
				<span class="text-xs text-[color:var(--bb-text-muted)]">hex</span>
			</template>
		</BbColorInput>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbColorInput } from 'bitboss-ui';

const chart = ref<string | null>('#3b82f6');
</script>
```

### Adaptive mobile sheet

With `adaptive` (default: global `config.adaptive`, which is `true`), the
picker opened from the swatch dot becomes a **bottom off-canvas sheet** on
mobile viewports (below `config.mobileMaxWidth`) instead of a floating popover
— same canvas, sliders, swatches and eyedropper, stretched to the sheet's
width. On desktop it stays a popover, and the surface is latched per open
cycle: a mid-open resize never swaps popover ↔ sheet. Set `:adaptive="false"`
to keep a floating popover everywhere. The sheet dismisses via backdrop tap or
Escape (no drag-to-dismiss — the palette body is made of drag surfaces); the
typed hex field is untouched by all of this.

### Events

Beyond `update:modelValue` (see value format above), the native input events are
forwarded with their original DOM payloads: `focus`, `blur`, `input`, `change`,
`keydown`, `keyup`, `click`, `mousedown`, `mouseup`, `paste`,
`compositionstart`, `compositionend`. Use `blur` for "validate on leave";
don't parse `input` yourself — the model already delivers only valid hex.

### Nuxt & Inertia

Nothing platform-specific: `BbColorInput` is a controlled field, so bind it to
your form state and submit however the platform expects. The picker's built-in
labels ("Open color picker", the dialog title, slider descriptions) follow the
plugin's `locale` config (`en`/`it`).

```vue
<script setup lang="ts">
import { useForm } from '@inertiajs/vue3';

const form = useForm({ brandColor: '#4f46e5' });
</script>

<template>
	<BbColorInput
		v-model="form.brandColor"
		label="Brand color"
		:errors="form.errors.brandColor"
		:has-errors="!!form.errors.brandColor"
		:swatches="true"
	/>
</template>
```

### Works well with

- `BbColorPalette` — the same picker on your own trigger, when there's no form.
- `useToast` — confirm a saved theme/brand color after submit.
- `BbButton` reset/apply actions alongside the field (see the form example).

### Gotchas & anti-patterns

- **Don't watch `input` to react to typing** — the model only changes on
  complete valid hex; that's the event to trust.
- **Don't roll a regex validator for the typed value** — the mask already
  guarantees shape; validate presence (`null`) and business rules instead.
- **Don't rely on the eyedropper** as the primary affordance — it's absent
  outside Chromium-based browsers.
- **Don't pass swatches as a flat array** — the type is `string[][]`; each
  inner array is one column.
- **Alpha mismatch**: without `alpha`, an incoming `#RRGGBBAA` value isn't
  representable in the mask — enable `alpha` wherever 8-digit values can occur.

### Accessibility

- `label` is mandatory and is the accessible name; use `hide-label` (not an
  empty label) if it must be visually hidden.
- `errors`, `warnings`, `description` and `hint` are all linked to the input
  via `aria-describedby`, in that order: the reason the field is invalid is
  spoken first when it regains focus, and a channel is referenced only while it
  actually has copy. Messages _also_ render in an `aria-live="polite"` region,
  so they are announced the moment they appear. The error state sets
  `aria-invalid` on the input automatically.
- The picker dot carries a localized `aria-label` (including the current value
  when set), plus `aria-haspopup="dialog"`/`aria-expanded` — you don't wire the
  popup yourself. Inside the palette, the gradient canvas and sliders are
  keyboard-operable (arrow keys; Shift for coarse steps).

## v-model

- `v-model` — type: `string \| null`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | When `true`, the color palette opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover; on desktop it stays a popover. Mirrors the adaptive behaviour of `BbSelect`/`BbDatePickerInput`. When unset, falls back to … |
| `alpha` | `boolean \| undefined` | `false` |  | Enable the alpha channel. Shows an opacity slider and uses `#RRGGBBAA` hex8 format. |
| `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
| `autocomplete` | `string \| undefined` |  |  | Guides the browser as to the type of information expected in the field. |
| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
| `clearable` | `boolean \| undefined` | `false` |  | Displays a clear button when the input has a value and is being interacted with. |
| `compact` | `boolean \| undefined` | `false` |  | Displays the component in a compact version. |
| `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
| `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
| `eyeDropper` | `boolean \| undefined` | `false` |  | Show an eyedropper button to sample any color on screen. Uses the native EyeDropper API — hidden automatically on unsupported browsers. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `label` | `string` |  | yes | Text content of the label of the element. |
| `labelMode` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Label rendering mode: `outside` places the label above the input, `floating` overlays it on the field and shrinks it when a value is set, `inside` keeps it inside the field. |
| `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
| `loading` | `boolean \| undefined` | `false` |  | Sets the component in a loading state, usually triggering some visual styles. |
| `modelValue` | `string \| null` | `null` | yes | Used by v-model. |
| `name` | `string \| undefined` |  |  | Defines the name of the input. |
| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
| `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
| `swatches` | `boolean \| string[][] \| undefined` |  |  | Controls swatches display in the picker: - `true` — show the built-in Material-palette swatches - `string[][]` — show custom swatches (each inner array = a column of shades) - `false` / omitted — no swatches section |
| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |

## Events

- `blur` — `(event: "blur", event: FocusEvent): void`
- `change` — `(event: "change", event: Event): void`
- `click` — `(event: "click", event: MouseEvent): void`
- `compositionend` — `(event: "compositionend", event: CompositionEvent): void`
- `compositionstart` — `(event: "compositionstart", event: CompositionEvent): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `input` — `(event: "input", event: Event): void`
- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
- `keyup` — `(event: "keyup", event: KeyboardEvent): void`
- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
- `paste` — `(event: "paste", event: ClipboardEvent): void`
- `update:modelValue` — `(event: "update:modelValue", value: string \| null): void`

## Slots

- `append` — scope: `Record<string, never>` — Content rendered after the color picker indicator button, at the end of the inner container. Mutually exclusive with `suffix`: the `suffix` slot renders inside this slot's default content, so providing `append` replaces the suffix rendering…
- `append-outer` — scope: `Record<string, never>` — Content rendered after the entire input control, outside the input chrome. This slot receives no scoped props.
- `label` — scope: `BbColorInputLabelSlotProps` — Replaces the default label text rendered above the color input.
- `prefix` — scope: `Record<string, never>` — Inline content rendered at the start of the input field area, before the typed text. This slot receives no scoped props.
- `prepend` — scope: `Record<string, never>` — Content rendered before the text input, at the start of the inner container. This slot receives no scoped props.
- `prepend-outer` — scope: `Record<string, never>` — Content rendered before the entire input control, outside the input chrome. This slot receives no scoped props.
- `suffix` — scope: `Record<string, never>` — Inline content rendered at the end of the input field area, after the typed text. Renders inside the default `append` area's suffix wrapper — mutually exclusive with `append`: if an `append` slot is provided it replaces this wrapper and the…

## Validated variant

Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).

| Prop | Type | Description |
| --- | --- | --- |
| `rules` | `RuleExpression<string \| null>` | vee-validate rules for this field. |
| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |

## See Also

- [BbColorPalette](./BbColorPalette.md) — Opens an anchored popover color palette for color picking interactions.
- [BbTextInput](./BbTextInput.md) — Captures single-line text values.

---

<!-- dist/ai/BbColorPalette.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbColorPalette.md -->

# BbColorPalette

## Agent Contract

- Safety level: **Consumer API**
- Group: **Overlay**
- Description: Opens an anchored popover color palette for color picking interactions.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbColorPalette.md](./source/BbColorPalette.md)

## Usage & Guidelines

### When to use

`BbColorPalette` is a **picker popover**, not a form field. It renders an
activator _you_ supply and opens a floating palette — a gradient canvas, hue
slider, optional swatches, optional alpha slider and optional eyedropper. The
value is a hex string via `v-model` (`string | null`). Reach for it wherever a
color is _chosen off a trigger you control_: a color dot beside a calendar
category, a label swatch in a context menu, a brand-accent chip in a toolbar.

Choose between the two color components by _what the color is_:

- A **typed value in a form** — a settings row, a brand color, anything with a
  label, hint, validation and a text representation the user can read and edit →
  **`BbColorInput`** (`./BbColorInput.md`). It embeds this exact palette as its
  swatch dot and adds the whole labelled-input surface around it.
- A color **assigned to an entity off your own trigger**, no text field, no
  wrapper chrome, no validation → **`BbColorPalette`** (here). Think "paint this
  thing", not "fill in this field".

Give it a `label`: it becomes the activator's `aria-label`, essential because
your trigger is often an unlabelled color dot.

> Swatch dots in these examples bind their fill with `:style="{ backgroundColor }"`
> because the color is a runtime value — the one place a static utility class
> cannot express what you need. Everything else is layout-only Tailwind.

### The value: hex in, hex out

The model is hex-only and lowercase on emit: `#RRGGBB`, or `#RRGGBBAA` when
`alpha` is enabled. There is no rgb()/hsl() mode — convert at the edges if your
store uses another format. Unlike `BbColorInput` (which only commits a
_complete, valid_ hex and never surfaces half-typed values), the palette has no
text field, so **`update:modelValue` fires continuously** as the user drags the
gradient, hue or alpha handle, and once per swatch/eyedropper pick. Treat it
like an `input`-frequency event: cheap handlers, or debounce your own
persistence.

`modelValue` is **required** — seed it explicitly as `ref<string | null>(null)`.
Leaving it `undefined` is a real omission (Vue warns about the missing required
prop), so always initialise it; `null` is the correct "no color yet" value.
`null` renders an "empty" trigger (nothing painted) and is what you get when
nothing is chosen yet.

**The palette never emits `null`** — every selection is a concrete hex — so
`null` is an _inbound_ value only. Once the user picks a colour there is no
built-in way back to empty: clearing is the consumer's job (set the model to
`null` yourself from a Clear button). Don't write an `update:modelValue`
handler that branches on `null`; that branch is dead code.

The label manager below embraces the emit frequency instead of fighting it: the
chip repaints on every drag frame (cheap — it's one style binding), while the
_persistence_ is debounced behind a short timer, so only the trailing edge of a
drag would hit your backend.

**Issue labels — live repaint, debounced save**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex items-center justify-between gap-3">
			<div class="flex flex-col gap-0.5">
				<span class="text-sm font-medium">Repository labels</span>
				<span class="text-xs text-[color:var(--bb-text-muted)]"
					>bitboss/ui · paint from the row</span
				>
			</div>
			<span class="shrink-0 text-xs text-[color:var(--bb-text-muted)]">
				{{ pending ? 'Saving…' : 'All changes saved' }}
			</span>
		</div>

		<ul class="flex flex-col gap-0.5">
			<li
				v-for="label in labels"
				:key="label.name"
				class="flex items-center gap-2 rounded-[var(--bb-radius)] px-1 py-1 hover:bg-[color:var(--bb-surface-hover)]"
			>
				<span
					class="shrink-0 rounded-full px-2 py-0.5 text-xs font-medium"
					:style="{
						backgroundColor: label.color,
						color: contrastOn(label.color),
					}"
				>
					{{ label.name }}
				</span>
				<span
					class="mr-auto truncate text-xs text-[color:var(--bb-text-muted)]"
				>
					{{ label.description }}
				</span>

				<BbColorPalette
					v-model="label.color"
					:label="`Color for ${label.name}`"
					placement="bottom-end"
					:swatches="labelSwatches"
					@update:model-value="queueSave"
				>
					<template #activator="{ props, value, open }">
						<button
							v-bind="props"
							class="h-4 w-4 shrink-0 rounded-full border border-[color:var(--bb-border)] outline-none ring-offset-1 focus-visible:ring-2 focus-visible:ring-[color:var(--bb-ring)]"
							:class="open ? 'ring-2 ring-[color:var(--bb-ring)]' : ''"
							:style="{ backgroundColor: value ?? 'transparent' }"
							type="button"
						/>
					</template>
				</BbColorPalette>
			</li>
		</ul>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbColorPalette } from 'bitboss-ui';

type Label = { name: string; description: string; color: string };

const labels = ref<Label[]>([
	{ name: 'bug', description: "Something isn't working", color: '#d73a4a' },
	{
		name: 'enhancement',
		description: 'New feature or request',
		color: '#2563eb',
	},
	{
		name: 'documentation',
		description: 'Improvements to the docs',
		color: '#0e8a16',
	},
]);

// Each inner array is a COLUMN of shades.
const labelSwatches: string[][] = [
	['#d73a4a', '#b91c1c', '#7f1d1d'],
	['#0e8a16', '#047857', '#065f46'],
	['#2563eb', '#4f46e5', '#6d28d9'],
];

const pending = ref(false);
let saveTimer: ReturnType<typeof setTimeout> | undefined;

/** Contrast-aware text on a label chip fill. */
const contrastOn = (hex: string) => {
	const r = parseInt(hex.slice(1, 3), 16);
	const g = parseInt(hex.slice(3, 5), 16);
	const b = parseInt(hex.slice(5, 7), 16);
	const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
	return luminance > 0.6 ? 'var(--bb-text)' : 'var(--bb-panel)';
};

/**
 * `update:modelValue` fires on every drag frame — the chip repaints from the
 * model for free, but the (simulated) persistence only runs on the trailing
 * edge of the stream.
 */
const queueSave = () => {
	pending.value = true;
	clearTimeout(saveTimer);
	saveTimer = setTimeout(() => {
		pending.value = false;
	}, 600);
};
</script>
```

### The activator contract

Provide your trigger through the `#activator` slot. The scope hands you
everything to render and wire it:

- `props` — **spread onto your clickable element** (`v-bind="props"`). This
  registers the element as the popover reference and lets the component attach
  the click handler and the ARIA attributes (`aria-haspopup="dialog"`,
  `aria-expanded`, `aria-label`) directly to it.
- `anchorProps` — spread onto a _wrapping_ element when the popover should align
  to something larger than the click target (next section). When unused, the
  activator is also the anchor.
- `open` — whether the palette is currently shown (read-only; drive a caret or a
  focus ring from it).
- `value` — the current color, mirroring `modelValue` (use it to paint the dot).
- `disabled` — mirrors the `disabled` prop, for styling the trigger's inert
  state.

Each `BbColorPalette` instance owns exactly one value, so per-entity assignment
is one instance per row.

**Per-category color dots (a calendar's legend)**

```vue
<template>
	<div
		class="flex max-w-xs flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">My calendars</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				Dot triggers — one palette instance per category.
			</span>
		</div>

		<ul class="flex flex-col gap-0.5">
			<li
				v-for="category in categories"
				:key="category.name"
				class="flex items-center justify-between gap-3 rounded-[var(--bb-radius)] px-1 py-1 hover:bg-[color:var(--bb-surface-hover)]"
			>
				<span class="text-sm">{{ category.name }}</span>

				<BbColorPalette
					v-model="category.color"
					:label="`Choose a color for ${category.name}`"
					placement="bottom-end"
					:swatches="calendarSwatches"
				>
					<template #activator="{ props, value, open }">
						<button
							v-bind="props"
							class="h-4 w-4 shrink-0 rounded-full border border-[color:var(--bb-border)] outline-none ring-offset-1 focus-visible:ring-2 focus-visible:ring-[color:var(--bb-ring)]"
							:class="open ? 'ring-2 ring-[color:var(--bb-ring)]' : ''"
							:style="{ backgroundColor: value ?? 'transparent' }"
							type="button"
						/>
					</template>
				</BbColorPalette>
			</li>
		</ul>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbColorPalette } from 'bitboss-ui';

type Category = { name: string; color: string | null };

const categories = ref<Category[]>([
	{ name: 'Work', color: '#3b82f6' },
	{ name: 'Personal', color: '#22c55e' },
	{ name: 'Focus time', color: '#f59e0b' },
	{ name: 'Travel', color: '#8b5cf6' },
]);

const calendarSwatches: string[][] = [
	['#ef4444', '#f97316', '#f59e0b'],
	['#22c55e', '#10b981', '#14b8a6'],
	['#3b82f6', '#6366f1', '#8b5cf6'],
];
</script>
```

#### Attaching to an element you already have

When the trigger is an existing element or component (not markup you author in
the slot), pass it to the `activator` prop instead of using the slot — the same
click and ARIA wiring is attached programmatically, mirroring the `BbDropdown`
activator API. `anchor` does the same for the positioning element. This is the
escape hatch for composing the palette onto a third-party control or a ref you
hold.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { BbColorPalette, BbButton } from 'bitboss-ui';

const color = ref<string | null>('#4f46e5');
const triggerRef = ref();
</script>

<template>
	<BbButton ref="triggerRef" variant="outline">Accent color</BbButton>
	<BbColorPalette
		v-model="color"
		label="Accent color"
		:activator="triggerRef"
		:swatches="true"
	/>
</template>
```

#### The `v-bb-color` directive

For the leanest case — a color dot in a table cell, a swatch you don't want to
wrap in a component per row — attach the `v-bb-color` directive to the element
instead of importing `BbColorPalette`. It is registered globally by the plugin
(`injectDirectives`, on by default) and renders no wrapper; click and ARIA wire
onto the host directly, exactly like the `activator` prop above.

The value is the palette's **props bag**, spread straight onto the component
(same model as `v-bb-dropdown`). A directive has no `v-model`, so bind write-back
with an `onUpdate:modelValue` callback — the palette always emits a concrete hex,
never `null`. A directive argument sets placement (`v-bb-color:top`); a nullish
value attaches nothing, so it is safe to bind conditionally.

```vue
<span
	class="dot"
	:style="{ background: row.color ?? 'transparent' }"
	v-bb-color="{
		modelValue: row.color,
		'onUpdate:modelValue': (c) => patch(row, { color: c }),
		alpha: true,
	}"
/>
```

Reach for the **component** (slot or `activator` prop) when you want the
`#activator` slot's scope (`open`/`value`/`disabled` for styling the trigger) or
a separate `anchor`. The directive is the shortcut for the bare-trigger cell
case, not a replacement for the component's `v-model` in a form.

### Swatches, alpha and the eyedropper

Three independent enrichments to the palette body:

- **`swatches`** — the preset grid. `true` shows the built-in Material palette;
  `string[][]` shows your own, where **each inner array is a column of shades**
  (design ramps vertically); `false`/omitted hides the section. The swatch
  matching the current value is highlighted, compared on the `#RRGGBB` part
  case-insensitively (so alpha doesn't break the highlight).
- **`alpha`** — adds an opacity slider and switches the emitted format to
  `#RRGGBBAA`. Enable it wherever 8-digit values can occur, or an incoming
  `#RRGGBBAA` won't round-trip.
- **`eye-dropper`** — adds a native **eyedropper** to sample any on-screen pixel. It
  is guarded by `'EyeDropper' in window`: on browsers without the API (anything
  non-Chromium) the button simply **does not render** — treat it as an
  enhancement, never the only path to a color. A cancelled sample (user presses
  Esc) is swallowed silently, and a sampled color is always **opaque** (alpha
  resets to full, since the API returns a 6-digit sRGB hex).

**Overlay tint — alpha, swatches, eyedropper**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">Overlay tint</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				Custom columns, alpha channel, and eyedropper when the browser supports
				it.
			</span>
		</div>

		<div
			class="flex h-16 items-end overflow-hidden rounded-[var(--bb-radius)] border"
			style="
				background-image:
					linear-gradient(45deg, var(--bb-muted) 25%, transparent 25%),
					linear-gradient(-45deg, var(--bb-muted) 25%, transparent 25%),
					linear-gradient(45deg, transparent 75%, var(--bb-muted) 75%),
					linear-gradient(-45deg, transparent 75%, var(--bb-muted) 75%);
				background-position:
					0 0,
					0 6px,
					6px -6px,
					-6px 0;
				background-size: 12px 12px;
			"
		>
			<div
				class="h-full w-full"
				:style="{ backgroundColor: overlay ?? 'transparent' }"
			/>
		</div>

		<BbColorPalette
			v-model="overlay"
			alpha
			eye-dropper
			label="Overlay color"
			:swatches="overlaySwatches"
		>
			<template #activator="{ props, value, open }">
				<button
					v-bind="props"
					class="inline-flex w-full items-center gap-2 rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] px-3 py-1.5 text-sm outline-none focus-visible:ring-2 focus-visible:ring-[color:var(--bb-ring)]"
					type="button"
				>
					<span
						class="h-4 w-4 shrink-0 rounded-full border border-[color:var(--bb-border)]"
						:style="{ backgroundColor: value ?? 'transparent' }"
					/>
					<span class="mr-auto tabular-nums">{{
						value ?? 'Pick a color'
					}}</span>
					<BbIcon
						:icon="open ? 'lucide:chevron-up' : 'lucide:chevron-down'"
						size="sm"
					/>
				</button>
			</template>
		</BbColorPalette>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbColorPalette, BbIcon } from 'bitboss-ui';

// With `alpha` enabled the model round-trips 8-digit #RRGGBBAA values.
const overlay = ref<string | null>('#1d4ed8cc');

// Each inner array is a column of shades (design ramps vertically).
const overlaySwatches: string[][] = [
	['#fef3c7', '#f59e0b', '#b45309'],
	['#fee2e2', '#ef4444', '#b91c1c'],
	['#dbeafe', '#3b82f6', '#1d4ed8'],
];
</script>
```

### Anchoring and positioning the popover

The click target and the element the popover aligns to can differ. Spread
`anchorProps` onto a wrapping element and `props` onto the small trigger inside
it — the palette positions against the wrapper while only the dot is clickable.

The float itself is tuned with the popover props:

- `placement` (`'bottom'`, `'bottom-start'`, `'top-end'`, …) — the preferred
  side; the popover **auto-flips** to the opposite side when it would overflow,
  unless you set `disable-flip`.
- `offset` (default 4) — gap between anchor and popover; `padding` (default 6) —
  minimum space kept from the viewport edge.
- `boundary` — constrain the popover inside an element (ref or CSS selector),
  e.g. a scrolling panel.
- `transition-duration` (default 250ms) and `eager` — render the palette content
  before it is first shown (useful for SSR/measurement; off by default so the
  body mounts lazily).

**Brand accent row — anchor vs click target**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">Brand settings</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				Row anchors the popover; only the swatch is clickable.
			</span>
		</div>

		<BbColorPalette
			v-model="brand"
			label="Brand accent"
			placement="bottom-start"
			swatches
		>
			<template #activator="{ props, anchorProps, value, open }">
				<span
					v-bind="anchorProps"
					class="flex items-center justify-between gap-3 rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] px-3 py-2 hover:bg-[color:var(--bb-surface-hover)]"
				>
					<span class="flex min-w-0 flex-col gap-0.5">
						<span class="text-sm font-medium">Brand accent</span>
						<span
							class="truncate text-xs tabular-nums text-[color:var(--bb-text-muted)]"
						>
							{{ value ?? 'No color' }}
						</span>
					</span>
					<button
						v-bind="props"
						class="h-5 w-5 shrink-0 rounded-full border border-[color:var(--bb-border)] outline-none ring-offset-1 focus-visible:ring-2 focus-visible:ring-[color:var(--bb-ring)]"
						:class="open ? 'ring-2 ring-[color:var(--bb-ring)]' : ''"
						:style="{ backgroundColor: value ?? 'transparent' }"
						type="button"
					/>
				</span>
			</template>
		</BbColorPalette>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbColorPalette } from 'bitboss-ui';

// The whole row is the anchor (anchorProps); only the dot is the click target.
const brand = ref<string | null>('#4f46e5');
</script>
```

### Adaptive mobile sheet

With `adaptive` (default: global `config.adaptive`, which is `true`), the
palette opens as a **bottom off-canvas sheet** on mobile viewports (below
`config.mobileMaxWidth`) instead of a floating popover — same canvas, sliders,
swatches and eyedropper, stretched to the sheet's width. On desktop it stays a
popover. The surface is latched per open cycle: a mid-open resize never swaps
popover ↔ sheet.

- Set `:adaptive="false"` to keep a floating popover everywhere.
- The sheet is labelled after the activator (its `aria-label`, i.e. your
  `label` prop), so screen readers announce it as the control that opened it.
- Placement/anchoring props (`placement`, `anchor`, `offset`, `boundary`, …)
  are floating-popover concerns; the sheet ignores it and spans the viewport
  bottom.
- The sheet dismisses via backdrop tap or Escape — deliberately **no
  drag-to-dismiss**, since the palette body is made of drag surfaces (canvas
  and sliders).

### Open state, disabled and readonly

The palette **owns its open state** — there is no `open` prop or `v-model:open`
to force it. Clicking the activator toggles it; a click on the dialog backdrop or
outside closes it; you _observe_ the state through the slot's `open` flag for
styling (a caret, a highlight). Two props gate interaction:

- `disabled` — blocks the activator entirely (no open) and marks it inert; the
  slot's `disabled` flag lets you grey the trigger out.
- `readonly` — keeps the activator visible and focusable but the palette never
  opens. Use it for review states where the color is shown but not editable.

### Config and platform

- **Locale** — the palette's built-in strings (the dialog's accessible label,
  the default "Open color picker" `aria-label` when you omit `label`, and the
  eyedropper's label) follow the plugin's `config.locale` — the library ships
  22 built-in dictionaries (see
  [Installation and Plugin Setup](./guides/installation-and-plugin-setup.md) §
  locale).
- **Overlay mechanics** — the popover renders as a `<dialog>` via `CommonPopover`
  and is **not teleported to `<body>`**: it lives in the component's own subtree,
  so it inherits your CSS context and is queryable in tests without a portal
  hop.
- **Adaptive defaults** — `config.adaptive` is the fallback for the `adaptive`
  prop and `config.mobileMaxWidth` the viewport threshold for "mobile" (see the
  adaptive section above).
- **SSR / Nuxt** — nothing platform-specific; `eager` pre-renders the body on the
  server if you need it warm on hydration. The palette itself carries no
  navigation, so there is no `href`/`to` surface here.

### Works well with

- `BbColorInput` — the same palette wrapped in a full form field; switch to it
  the moment you need a label, a readable/editable text value, or validation.
- `useToast` — confirm a saved entity color after you persist the change.
- Calendars, label/tag managers, chart legends — the canonical hosts: one
  palette instance per entity row, the model bound to the entity's color.

### Gotchas and anti-patterns

- **Don't collect form values with it** — a color that submits with a form wants
  a label and validation; that is `BbColorInput`.
- **Don't treat `update:modelValue` as a commit** — it fires continuously while
  dragging. Debounce your own persistence; don't write to a backend on every
  emit.
- **Don't pass swatches as a flat array** — the type is `string[][]`; each inner
  array is one _column_ of shades.
- **Don't rely on the eyedropper** — it is absent outside Chromium; keep the
  swatches/gradient as the primary path.
- **Alpha mismatch** — without `alpha`, an incoming `#RRGGBBAA` value can't be
  represented; enable `alpha` wherever 8-digit values occur.
- **Don't forget to seed the model** — `modelValue` is required; an `undefined`
  binding warns in dev. Start it at `null`.
- **Don't try to force it open via a prop** — the open state is internal; gate
  with `disabled`/`readonly`, observe with the slot's `open`.

### Accessibility

- Always pass `label`. It is applied to the activator as `aria-label` (the only
  accessible name when the trigger is a bare color dot); `aria-haspopup="dialog"`
  and a live `aria-expanded` are set for you on the element you spread `props`
  onto.
- Focus moves into the palette when it opens (to the first focusable control) and
  is **restored to the activator** on close — you don't manage focus yourself.
- Inside the palette, the gradient canvas and the hue/alpha sliders are
  keyboard-operable (arrow keys; Shift for coarse steps).
- Use `readonly` (not a disabled-looking custom style) when the color must be
  shown but not changed, so the activator stays in the reading order.

## v-model

- `v-model` — type: `string \| null`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activator` | `ElementOrComponentRef \| undefined` |  |  | External activator element or component ref. When provided, the `activator` slot is not rendered and click listeners are attached programmatically to the referenced element — mirroring the BbDropdown activator API. |
| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | When `true`, the palette opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover; on desktop it stays a popover. Mirrors the adaptive behaviour of `BbPopover`/`BbDropdown`/`BbDatePicker`. When unset, falls back … |
| `alpha` | `boolean \| undefined` | `false` |  | Enable the alpha channel. The picker shows an opacity slider and emits `#RRGGBBAA` hex8 values. |
| `anchor` | `ElementOrComponentRef \| undefined` |  |  | Element or component ref the popover positions itself relative to. Defaults to the activator element when omitted, allowing the popover to be anchored to a larger container (e.g. the full input row) while a smaller element (e.g. a color dot… |
| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the popover within a bounding element. Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
| `disabled` | `boolean \| undefined` | `false` |  | Disable all interaction (activator and palette). |
| `disableFlip` | `boolean \| undefined` | `false` |  | Disables the automatic flip to the opposite side when the popover would overflow (flipping is on by default). |
| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
| `eyeDropper` | `boolean \| undefined` | `false` |  | Show an eyedropper button inside the palette to sample any color on screen. Uses the native EyeDropper API — hidden automatically on unsupported browsers. |
| `label` | `string \| undefined` |  |  | Accessible label applied to the activator element via `aria-label`. Defaults to the locale string for "Open color picker" when omitted. |
| `modelValue` | `string \| null` |  | yes | v-model: the current color as a `#RRGGBB` hex string (or `#RRGGBBAA` when `alpha` is enabled), or `null` when empty. |
| `offset` | `number \| undefined` | `4` |  | Space the floating container will maintain from the activator. |
| `padding` | `number \| undefined` | `6` |  | Minimum empty space to keep from the edge of the page |
| `placement` | `Placement \| undefined` |  |  | Position of the overlay in respect to the related activator. |
| `readonly` | `boolean \| undefined` | `false` |  | Prevent opening the palette while keeping the activator visible. |
| `swatches` | `boolean \| string[][] \| undefined` |  |  | Controls swatches display in the picker: - `true` — show the built-in Material-palette swatches - `string[][]` — show custom swatches (each inner array = a column of shades) - `false` / omitted — no swatches section |
| `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds |

## Events

- `update:modelValue` — `(event: "update:modelValue", value: string): void`

## Slots

- `activator` — scope: `BbColorPaletteActivatorSlotProps` — Custom activator element. Apply `v-bind="props"` to the element you want to use as the trigger — this wires up the ref callback that lets BbColorPalette track the element.

## See Also

- [BbColorInput](./BbColorInput.md) — Captures color values through input controls.
- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements.

---

<!-- dist/ai/BbConfirm.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbConfirm.md -->

# BbConfirm

## Agent Contract

- Safety level: **Consumer API**
- Group: **Overlay**
- Description: Prompts users to confirm or cancel critical actions (includes co-located BbConfirmPortal export).
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbConfirm.md](./source/BbConfirm.md)

## Usage & Guidelines

### When to use

Use `BbConfirm` whenever an action is **destructive or irreversible** — delete,
overwrite, publish, sign out — or otherwise deserves a deliberate second step.
You don't render it inline: mount the host once, then call
[`useConfirm().confirm(...)`](./composables/useConfirm.md) wherever the action
lives and `await` the boolean it resolves to. The dialog is the render target;
the composable is the API.

Reach for a sibling instead when:

- you need a **rich, multi-field modal** (a form, a wizard) → use
  [BbDialog](./BbDialog.md) directly.
- the message is **informational, not a decision** → use
  [BbAlert](./BbAlert.md) or [BbToast](./BbToast.md).

Per the design language, every `destructive` action must pass through a confirm
first — this is that gate.

### Setup

Mount `<BbConfirm />` **exactly once, at the app root** (`App.vue` under Vue,
`app.vue` under Nuxt, the `createInertiaApp` render root under Inertia) — a
single instance serves the whole app, and `confirm()` can then be called from
anywhere, components and stores alike. **Calls do not queue — a new
`confirm()` supersedes the open one**, and the superseded promise settles
`false` (an implicit dismiss; no callback runs). So two `confirm()` calls in a
row show only the second, and the first silently answers "no". If you need both
questions asked, `await` the first before opening the second.
Mounting a second host renders every dialog twice
(nothing warns you). Mounting none is worse: `await confirm(...)` never settles
and the caller hangs.

```vue
<template>
	<RouterView />
	<BbConfirm />
</template>

<script setup lang="ts">
import { BbConfirm } from 'bitboss-ui';
</script>
```

**Every example on this page mounts its own `<BbConfirm />` only because a
standalone example has no app root to mount it in.** In a real app the host is
already mounted at the root; a page that calls `confirm()` mounts nothing.

The component itself takes no props: everything — content, buttons, size,
behavior — travels in the message you pass to `confirm()`. At least one of
`title`, `text`, `portal` should be set (dev warning otherwise).

### The destructive flow

The canonical pattern: `await confirm(...)`, then act only on a truthy result.
Set `variant: 'destructive'` so the dialog reads as dangerous and the Yes button
inherits the destructive button style automatically. Everything after the
`await` is your normal code — the dialog has already resolved.

**Revoke an API key, end to end**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">API keys</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				<span data-count>{{ keys.length }}</span> active · revoking is immediate
			</span>
		</div>
		<div v-for="key in keys" :key="key.id" class="flex items-center gap-2">
			<div class="flex min-w-0 flex-1 flex-col">
				<span class="truncate text-sm font-medium">{{ key.label }}</span>
				<span class="text-xs text-[color:var(--bb-text-muted)]">
					{{ key.masked }} · created {{ key.created }}
				</span>
			</div>
			<BbButton
				prepend:icon="lucide:trash-2"
				size="xs"
				variant="destructive"
				@click="revoke(key)"
			>
				Revoke
			</BbButton>
		</div>
		<p
			v-if="keys.length === 0"
			class="text-xs text-[color:var(--bb-text-muted)]"
		>
			No active keys.
		</p>

		<!--
			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
			mount none. See ai/guides/agent-contract.md § Global Host Rule.
		-->
		<BbConfirm />
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbConfirm, useConfirm } from 'bitboss-ui';

type ApiKey = { id: string; label: string; masked: string; created: string };

const keys = ref<ApiKey[]>([
	{
		id: 'key_prod',
		label: 'Production',
		masked: 'sk-live-…9f2c',
		created: '2026-03-14',
	},
	{
		id: 'key_ci',
		label: 'CI pipeline',
		masked: 'sk-test-…41ab',
		created: '2026-05-02',
	},
]);

const { confirm } = useConfirm();

/** Gate the destructive action: await the decision, act only on a yes. */
const revoke = async (key: ApiKey) => {
	const ok = await confirm({
		title: 'Revoke API key?',
		text: `${key.label} (${key.masked}) stops working immediately. This cannot be undone.`,
		variant: 'destructive',
		yes: { text: 'Revoke', 'prepend:icon': 'lucide:trash-2' },
		no: 'Cancel',
	});
	if (ok) keys.value = keys.value.filter((k) => k.id !== key.id);
};
</script>
```

`variant` also lands on the dialog root as a `bb-confirm--<name>` class.
`default` and `destructive` ship with the library; the vite/nuxt plugin's
`confirmVariants` option registers additional names as a typed union (any
plain string still works for one-offs) — you provide the
`.bb-confirm--<name>` CSS yourself.

### Async actions and busy state

For work that should finish _before_ the dialog closes, put it in the button's
`onClick` instead of after the `await`: the button shows a spinner while the
promise runs, the opposite button is disabled, the X is hidden and dismissal
is blocked until it settles. Add `returning: true` to resolve with the
callback's own return value rather than a plain boolean. One sharp edge:
`confirm()` **rejects** when a button's `onClick` throws — wrap the await in
`try/catch` when the work can fail.

**Async publish with a spinner**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">Changelog — week 28</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				Status: <span data-status>{{ status }}</span>
			</span>
		</div>
		<div class="flex items-center gap-2">
			<BbButton prepend:icon="lucide:rocket" variant="primary" @click="publish">
				Publish article
			</BbButton>
		</div>
		<!--
			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
			mount none. See ai/guides/agent-contract.md § Global Host Rule.
		-->
		<BbConfirm />
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbConfirm, useConfirm } from 'bitboss-ui';

const status = ref('Draft');

const { confirm } = useConfirm();

/**
 * Put slow work in the button's `onClick`: it shows a spinner while the promise
 * runs, and `returning: true` resolves with the callback's own return value.
 */
const publish = async () => {
	const result = await confirm({
		title: 'Publish article?',
		text: 'It becomes visible to everyone with the link.',
		returning: true,
		yes: {
			text: 'Publish',
			'prepend:icon': 'lucide:rocket',
			onClick: async () => {
				await new Promise((resolve) => setTimeout(resolve, 700));
				return 'Published';
			},
		},
		no: { text: 'Keep as draft', onClick: () => 'Draft' },
	});
	status.value = result;
};
</script>
```

### Customising the buttons

`yes` and `no` each accept three forms: `false` hides the button, a string
relabels it, and a full `ConfirmButtonConfig` object gives complete control —
`text`, `variant`, `size` (default `'md'`), `prepend:icon` / `append:icon`,
`icon` (standalone icon button, no label), `block` (fill the footer width),
and the `onClick` described above. Defaults: Yes is the `confirm.ok` locale
string (`'OK'` with the default `'it'` locale), `primary` (`destructive` when
the dialog variant is); No is the `confirm.cancel` locale string (`'Annulla'`
with the default `'it'` locale), `outline`. Prefer your own verb-first labels
over the generic defaults.

```ts
// Acknowledgement — one button.
await confirm({ title: 'Saved', text: 'Your changes are live.', no: false });

// Full control over each button.
await confirm({
	title: 'Archive project?',
	text: 'You can restore it later from the archive.',
	yes: { text: 'Archive', 'prepend:icon': 'lucide:archive' },
	no: { text: 'Cancel', variant: 'ghost' },
});
```

### More than yes/no: custom actions

When the decision has more than two outcomes, pass an `actions` array — it
replaces the Yes/No footer entirely (`yes` / `no` are ignored, with a dev
warning). Each entry is the same `ConfirmButtonConfig` shape as above; defaults
per button are `variant: 'outline'`, `size: 'md'`. Clicking any action resolves
the promise `true`; every implicit dismissal still resolves `false` without
running a callback. While one action's `onClick` runs, it spins and the others
are disabled.

Combine with `returning: true` to learn which button was clicked — the promise
resolves with the clicked handler's return value, typed as the union across
the array (`as const` keeps the literal types; without it each handler infers
`string`):

**Three-way unsaved-changes decision**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">Post editor</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				Last decision: <span data-decision>{{ decision }}</span>
			</span>
		</div>
		<div class="flex items-center gap-2">
			<BbButton prepend:icon="lucide:x" variant="outline" @click="closeEditor">
				Close editor
			</BbButton>
		</div>
		<!--
			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
			mount none. See ai/guides/agent-contract.md § Global Host Rule.
		-->
		<BbConfirm />
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbConfirm, useConfirm } from 'bitboss-ui';

const decision = ref('none yet');

const { confirm } = useConfirm();

/**
 * An `actions` array replaces the Yes/No footer. With `returning: true` the
 * promise resolves with the clicked handler's return value — `as const` keeps
 * the literals, so `res` is 'discard' | 'draft' | 'publish' | false.
 */
const closeEditor = async () => {
	const res = await confirm({
		title: 'Unsaved changes',
		text: 'Save your edits before leaving?',
		returning: true,
		actions: [
			{
				text: 'Discard',
				variant: 'destructive',
				onClick: () => 'discard' as const,
			},
			{ text: 'Save draft', onClick: () => 'draft' as const },
			{
				text: 'Save & publish',
				variant: 'primary',
				onClick: async () => {
					await new Promise((resolve) => setTimeout(resolve, 700));
					return 'publish' as const;
				},
			},
		],
	});
	decision.value = res === false ? 'dismissed' : res;
};
</script>
```

The rest of the contract carries over from yes/no unchanged:

- A **throwing handler rejects** the `confirm()` promise and closes the dialog
  — wrap multi-outcome confirms in `try/catch` when a handler can fail.
- **`duration` still works**: if nobody picks in time, the promise resolves
  `false`, exactly like a dismissal.
- While any handler runs, `persistent` and `hideClose` are forced on — there
  is no way out of the dialog mid-flight.
- `actions: false` still hides the footer entirely — the
  portal-owns-the-buttons pattern in the portals section below.

### Dismissal, persistence and timing

A confirm can end without a button click — backdrop click, `Escape`, the X,
a `duration` timeout, or the owning component unmounting. All of these resolve
the promise `false`, so your `if (ok)` branch is never reached accidentally.
`false` therefore means _not confirmed_, not necessarily _declined_ — put
decline-only behavior in `no.onClick`, not in the `if (!ok)` branch. The rule
that decides whether `no.onClick` runs: **user-initiated** dismissals
(backdrop, `Escape`, the X) honor `dismissAsNo`; **system-initiated** ones
(`duration` timeout, owner unmount, a superseding `confirm()`, `dismissAll()`)
always resolve quietly, never running any callback. The knobs:

- `dismissAsNo` (default `true`) — user-initiated implicit dismissals also run
  `no.onClick` (and, with `returning`, resolve with its return value). Set
  `false` to resolve `false` quietly without running the callback; an explicit
  No click always runs it.
- `persistent` blocks backdrop/Escape/X dismissal; `hideClose` hides the X.
  Combine them (with explicit `yes`/`no`) to force a real choice. Both are
  forced on automatically while a button callback runs.
- `duration: ms` auto-dismisses after a timeout, resolving `false` quietly —
  useful for self-expiring prompts. It implies `autoClose: true`.

### Ownership: dialogs die with the scope that created them

A confirm lives as long as the component (strictly: the effect scope) that
called `useConfirm()`. If that component unmounts while its dialog is open —
the user pressed the browser Back button, a route change swapped the page, a
wizard swapped the step — the dialog is dismissed quietly: the promise
resolves `false` and no callback runs, because the handlers close over state
that no longer exists. The usual `if (!ok) return` continuation makes this
invisible.

Granularity is a composition choice: call `useConfirm()` at page level (the
typical context-module pattern) and dialogs survive child re-renders but die
with the page; call it inside a peek/drawer component and its dialogs die when
the peek closes. For app-lifetime confirms that survive any unmount, call
`useConfirm()` outside a component scope (app setup, a store, module level).

`useConfirm()` also returns `dismissAll()` — an imperative escape hatch that
quietly dismisses the open dialog regardless of owner, for
app-level events like logout or a global error boundary.

The classic case for `persistent` is the unsaved-changes prompt: an accidental
`Escape` or backdrop click must not silently discard (or silently keep) the
edits, so every implicit way out is blocked and the user answers with a button.

**Force an explicit choice on unsaved changes**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">Profile</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				Saved as: <span data-saved>{{ saved }}</span>
			</span>
		</div>
		<BbTextInput v-model="draft" compact label="Display name" />
		<div class="flex items-center gap-2">
			<BbButton variant="primary" @click="save">Save</BbButton>
			<BbButton variant="ghost" @click="cancel">Cancel</BbButton>
		</div>
		<!--
			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
			mount none. See ai/guides/agent-contract.md § Global Host Rule.
		-->
		<BbConfirm />
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbConfirm, BbTextInput, useConfirm } from 'bitboss-ui';

const saved = ref('Ada Lovelace');
const draft = ref<string | null>(saved.value);

const { confirm } = useConfirm();

const save = () => {
	saved.value = draft.value ?? '';
};

/**
 * `persistent` + `hideClose` remove every implicit way out — backdrop, Escape,
 * and the X — so the unsaved-changes prompt always gets an explicit answer.
 */
const cancel = async () => {
	if (draft.value === saved.value) return;
	const ok = await confirm({
		title: 'Discard unsaved changes?',
		text: 'Your edits to this profile will be lost.',
		variant: 'destructive',
		persistent: true,
		hideClose: true,
		yes: 'Discard',
		no: 'Keep editing',
	});
	if (ok) draft.value = saved.value;
};
</script>
```

### Multi-step flows: autoClose and close()

By default the dialog closes as soon as the promise settles. Set
`autoClose: false` to keep it open — for flows that continue after the choice
(progress feedback, a follow-up step) — and end the flow yourself with
`useConfirm().close()`. Two things to internalize, for **either** outcome:

- `autoClose: false` applies to No/dismiss too — call `close()` on both
  branches.
- `close()` only hides the dialog; **it never resolves anything**. Calling it
  on a dialog whose buttons haven't run yet leaves that `confirm()` promise
  pending forever — it is a flow terminator, not a substitute for the buttons.

**Keep the dialog open across steps**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">Workspace backup</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]" data-status>{{
				status
			}}</span>
		</div>
		<div class="flex items-center gap-2">
			<BbButton
				prepend:icon="lucide:archive"
				variant="outline"
				@click="exportWorkspace"
			>
				Export workspace
			</BbButton>
		</div>

		<!-- The named portal reads local reactive state, so the open dialog's
		body updates live between the steps of the flow. -->
		<BbConfirmPortal name="export-flow">
			<template #default>
				<p class="text-center text-sm">{{ progressText }}</p>
			</template>
		</BbConfirmPortal>
		<!--
			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
			mount none. See ai/guides/agent-contract.md § Global Host Rule.
		-->
		<BbConfirm />
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbConfirm, BbConfirmPortal, useConfirm } from 'bitboss-ui';

const status = ref('No export yet');
const progressText = ref('Everything in this workspace is bundled into a ZIP.');

const { confirm, close } = useConfirm();

/**
 * `autoClose: false` keeps the dialog open after EITHER choice resolves.
 * End the flow with `close()` — it only hides the dialog; it never resolves
 * the promise itself.
 */
const exportWorkspace = async () => {
	progressText.value = 'Everything in this workspace is bundled into a ZIP.';
	const ok = await confirm({
		title: 'Export workspace?',
		portal: 'export-flow',
		autoClose: false,
		yes: 'Export',
		no: 'Cancel',
	});
	if (!ok) {
		status.value = 'Cancelled';
		close();
		return;
	}
	progressText.value = 'Preparing your download…';
	status.value = 'Exporting…';
	await new Promise((resolve) => setTimeout(resolve, 400));
	status.value = 'Ready';
	close();
};
</script>
```

### Rich content with portals

When plain `text` isn't enough, render custom content in the dialog body via a
**portal**. A named portal is declared inline with `<BbConfirmPortal>` and
activated by name — its slot receives `{ yes, no, props }`, where `props` is
your `portalProps` and `yes`/`no` resolve the dialog from inside the slot.
Named-portal content is a live closure over your component's state (the
multi-step example above exploits exactly that). For reusable bodies, pass a
component as `portal` instead; `portalProps` are then forwarded to it as real
props via `v-bind`. Note that `text` takes priority: when both are set, the
portal never renders.

**Named portal with portalProps**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex items-center gap-2">
			<div class="flex min-w-0 flex-1 flex-col">
				<span class="truncate text-sm font-medium">Sofia Esposito</span>
				<span class="text-xs text-[color:var(--bb-text-muted)]"
					>Editor · sofia@acme.dev</span
				>
			</div>
			<BbButton size="xs" variant="destructive" @click="removeMember">
				Remove
			</BbButton>
		</div>
		<p class="text-xs text-[color:var(--bb-text-muted)]" data-result>
			{{ result }}
		</p>

		<!-- Register named content anywhere in the tree. The slot receives
		`{ yes, no, props }`; `props` is whatever `portalProps` was passed. -->
		<BbConfirmPortal name="remove-member">
			<template #default="{ props }">
				<div class="flex flex-col items-center gap-1 text-center">
					<p class="text-sm font-medium">{{ props.name }}</p>
					<p class="text-xs text-[color:var(--bb-text-muted)]">
						{{ props.role }}
					</p>
					<p class="mt-1 text-xs text-[color:var(--bb-text-muted)]">
						They lose access to every shared resource.
					</p>
				</div>
			</template>
		</BbConfirmPortal>
		<!--
			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
			mount none. See ai/guides/agent-contract.md § Global Host Rule.
		-->
		<BbConfirm />
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbConfirm, BbConfirmPortal, useConfirm } from 'bitboss-ui';

const result = ref('Member of Acme since 2024');

const { confirm } = useConfirm();

const removeMember = async () => {
	const ok = await confirm({
		title: 'Remove member?',
		portal: 'remove-member',
		portalProps: { name: 'Sofia Esposito', role: 'Editor' },
		variant: 'destructive',
		yes: 'Remove',
		no: 'Cancel',
	});
	result.value = ok
		? 'Removed from the workspace'
		: 'Member of Acme since 2024';
};
</script>
```

When the portal owns its own action buttons, pass `actions: false` to hide the
standard footer and resolve from inside the slot with its `yes` / `no` helpers.

### Size, fullscreen and focus

- `size` picks a maximum-width preset (`'xs'` … `'2xl'`, resolvable through
  the plugin config's `dialogDefaultSizes`); default confirms are compact.
- `fullscreen: true` takes over the whole screen; `fullscreen: 'mobile'`
  restricts that to small viewports.
- `focusTarget` is a CSS selector focused after opening (default: the first
  tabbable element) — point it at an input inside a portal body.
- On mobile viewports the dialog follows the global `config.adaptive` and
  renders as a bottom sheet; there is no per-call override for this, so test
  overlay assertions against both surfaces (or pin the viewport).

### Works well with

- `BbButton variant="destructive"` — the trigger; the confirm is its gate.
- `BbDropdown` / `BbDropdownButton` — gate a destructive menu item inside its
  `onClick`.
- [useToast](./composables/useToast.md) — announce the outcome after the
  confirm resolves ("Invoice deleted").
- [BbDialog](./BbDialog.md) — the underlying surface; switch to it directly
  when the "confirm" grows fields.

### Gotchas and anti-patterns

- **Don't hand-build a yes/no dialog** out of `BbDialog` + buttons — busy
  states, dismissal semantics, ownership and focus handling already live here.
- **Don't fire two `confirm()` calls without awaiting the first.** The second
  supersedes the first, which settles `false` — so a "delete these two things"
  flow written as two un-awaited confirms deletes nothing and asks once.
- **Don't forget the `await`** — `confirm(...)` without it never gates
  anything.
- **Don't call `close()` to "cancel"** a dialog whose buttons haven't run —
  the promise stays pending (see multi-step section).
- A confirm with neither `title`, `text` nor `portal` renders empty (dev
  warning).
- `text` beats `portal` — remove `text` when you want the portal body.
- With `returning: true`, an implicit dismiss under the default
  `dismissAsNo: true` resolves with `no.onClick`'s return value — give No a
  callback that returns a sensible "declined" value.

### Accessibility

- Keep `title` and `text` specific — name the object and the consequence
  ("Delete invoice INV-2048? This cannot be undone."), not a generic "Are you
  sure?".
- The Yes button label should be a verb that matches the action (_Delete_,
  _Publish_), not "OK" — the defaults are placeholders, not recommendations.
- Focus is trapped in the dialog and returns to the trigger on close; `Escape`
  and the backdrop dismiss it (as a No) unless you set `persistent`. Use
  `focusTarget` to focus a specific element (e.g. an input in a portal).
- While a callback runs, the dialog blocks every escape hatch by design —
  keep those callbacks short or show progress in a portal body.

## Props

- None.

## Events

- None.

## Slots

- None.

## See Also

- [BbDialog](./BbDialog.md) — Presents modal dialogs for focused user interactions.
- [BbButton](./BbButton.md) — Button with loading state, tooltip, and icon support.
- [useConfirm](./composables/useConfirm.md)

---

<!-- dist/ai/BbConfirmPortal.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbConfirmPortal.md -->

# BbConfirmPortal

## Agent Contract

- Safety level: **Consumer API**
- Group: **Overlay**
- Description: Registers named slot content that confirm() renders via `portal`.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbConfirmPortal.md](./source/BbConfirmPortal.md)

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `name` | `string` |  | yes |  |

## Events

- None.

## Slots

- `default` — scope: `{ yes: () => void; no: () => void; props: Record<string, unknown>; }`

## See Also

- [BbConfirm](./BbConfirm.md) — Prompts users to confirm or cancel critical actions (includes co-located BbConfirmPortal export).
- [useConfirm](./composables/useConfirm.md)

---

<!-- dist/ai/BbDatePicker.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbDatePicker.md -->

# BbDatePicker

## Agent Contract

- Safety level: **Consumer API**
- Group: **Overlay**
- Description: Opens an anchored calendar (and optional time rail) popover on a trigger you own — the date analog of BbColorPalette; also the v-bb-date directive.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbDatePicker.md](./source/BbDatePicker.md)

## Usage & Guidelines

### When to use

`BbDatePicker` is a **picker popover**, not a form field. It renders an activator
_you_ supply and opens a floating calendar — with an adaptive bottom sheet on
mobile, optional range selection, and a time rail under `type="datetime"`. The
value is an ISO string (or `YYYY-MM-DD` when `floating`) via `v-model`.

Choose between the two date components by _what the control is_:

- A **typed field in a form** — a labelled row where the user reads and edits the
  date as text, with validation and hint/error chrome → **`BbDatePickerInput`**
  (`./BbDatePickerInput.md`). It embeds this exact picker as its calendar and
  adds the whole segmented text-input surface around it.
- A date **assigned off your own trigger** — a cell in a table, a chip, a button
  — no text field, no wrapper chrome → **`BbDatePicker`** (here). Think "set the
  due date on this row", not "fill in this field".

For the leanest case, skip the component entirely and use the
[`v-bb-date` directive](#the-v-bb-date-directive).

### The value: ISO in, ISO out

`modelValue` is `null` (empty), a single ISO string, or a two-element
`[start, end]` array when `range` is true. `floating` emits plain `YYYY-MM-DD`
(no time, no zone); `utc` emits `…Z` instead of the local offset. These are the
same value rules as the whole date family — see `./BbDatePickerInput.md` for the
full contract.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { BbDatePicker, BbButton } from 'bitboss-ui';

const due = ref<string | null>(null);
</script>

<template>
	<BbDatePicker v-model="due" floating>
		<template #activator="{ props, value }">
			<button v-bind="props" type="button">
				{{ value ?? 'Set due date' }}
			</button>
		</template>
	</BbDatePicker>
</template>
```

### The activator contract

Provide your trigger through the `#activator` slot. The scope hands you
everything to render and wire it:

- `props` — **spread onto your clickable element** (`v-bind="props"`). This
  registers the element as the popover reference and attaches the click handler
  and ARIA (`aria-haspopup="dialog"`, `aria-expanded`, `aria-label`) to it.
- `anchorProps` — spread onto a _wrapping_ element when the popover should align
  to something larger than the click target. When unused, the activator is also
  the anchor.
- `open` — whether the calendar is currently shown (read-only).
- `value` — the current value, mirroring `modelValue`.
- `disabled` — mirrors the `disabled` prop.

Give it a `label`: it becomes the activator's `aria-label`, essential when your
trigger is an unlabelled cell or icon.

#### Attaching to an element you already have

When the trigger is an existing element or component (not markup you author in
the slot), pass it to the `activator` prop instead of using the slot — the same
click and ARIA wiring is attached programmatically, mirroring `BbColorPalette`
and `BbDropdown`. `anchor` does the same for the positioning element.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { BbDatePicker, BbButton } from 'bitboss-ui';

const date = ref<string | null>('2026-01-15');
const triggerRef = ref();
</script>

<template>
	<BbButton ref="triggerRef" variant="outline">Pick a date</BbButton>
	<BbDatePicker v-model="date" floating :activator="triggerRef" />
</template>
```

### `type` — what you are picking

One prop decides both the terminal grid and the shape of the emitted string.
It mirrors `<input type="…">`, so the names should already be familiar:

| `type`             | the panel shows      | emits (floating)      | emits (zoned) |
| ------------------ | -------------------- | --------------------- | ------------- |
| `date` _(default)_ | the day grid         | `2026-08-14`          | ISO instant   |
| `datetime`         | day grid + time rail | `2026-08-14` + `time` | ISO instant   |
| `month`            | the 12-month grid    | `2026-08`             | —             |
| `year`             | the year list        | `2026`                | —             |

`month` and `year` are **calendar labels, not instants**. A month has no
timezone, and pinning one to an instant is how you lose it: the start of August
in Rome is the 31st of July in UTC, so a value stored that way reads back as the
wrong month. They force `floating`, ignore `utc`, and warn if you pass it.

```vue
<BbDatePicker v-model="period" type="month">
	<template #activator="{ props }">
		<button v-bind="props">{{ period ?? 'Pick a month' }}</button>
	</template>
</BbDatePicker>
<!-- period === '2026-08' -->
```

Everything else composes unchanged: `range` gives you `['2026-01', '2026-03']`,
`multiple` a sorted list of labels, `min`/`max` take the same shape as the value
(`min="2026-03"`), and `selectable` receives that shape too. A bound finer than
the unit is accepted and rounded outward with a DEV warning, so
`min="2026-03-15"` under `type="month"` still leaves the whole of March
selectable — it cannot silently delete the month you named.

The month grid pages by year and the year list by decade; arrows, Home/End and
PageUp/PageDown all keep working, one unit up.

### Multi-selection

`multiple` turns every pick into a toggle: the value is a **sorted array** and
picking a selected cell removes it. It works in whatever `type` selects — a set
of days, of months, or of years — and the panel **stays open** while you build
the set, since the next pick is the point.

```vue
<BbDatePicker v-model="months" multiple type="month">
	<template #activator="{ props }">
		<button v-bind="props">{{ months.length }} selected</button>
	</template>
</BbDatePicker>
<!-- months === ['2026-02', '2026-06'] -->
```

The model must be an **array** — `[]` for empty, never `null` (a `null` is
tolerated and read as empty, but bind an array and the type stays honest).

Two combinations throw rather than guess:

- **`multiple` + `range`** — two different selection models.
- **`multiple` + `type="datetime"`** — the time rail edits one value, and with
  a set of them there is no value it could mean.

`BbDatePickerInput` has no `multiple`: a segmented text field renders one value
(or two, for a range), so a set has nowhere to live. Multi-selection is a
picker-surface feature.

### Range and datetime

`range` turns the value into `[start, end]`; the panel stays open until both ends
are picked. `datetime` adds a time rail beside the calendar (a bottom row in the
mobile sheet) and a companion `v-model:time` (`HH:mm` / `HH:mm:ss`), with `ampm`,
`seconds`, and `step` shaping the columns. With `floating` the date stays plain
and the time travels only through `v-model:time`; otherwise the time lives inside
`modelValue`.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { BbDatePicker } from 'bitboss-ui';

const when = ref<string | null>(null);
const time = ref<string | null>(null);
</script>

<template>
	<BbDatePicker v-model="when" v-model:time="time" type="datetime" seconds>
		<template #activator="{ props, value }">
			<button v-bind="props" type="button">{{ value ?? 'Schedule' }}</button>
		</template>
	</BbDatePicker>
</template>
```

### Adaptive and positioning

On mobile the calendar opens in a bottom off-canvas sheet instead of a floating
popover (`adaptive`, on by default via `config.adaptive`; forward extra sheet
props with `offCanvasProps`). Position the desktop popover with `placement`,
`offset`, `padding`, `boundary`, and `disableFlip` — the same knobs as the other
overlays. Escape and backdrop clicks close it; focus returns to the activator.

### The `v-bb-date` directive

For the leanest case — a date cell in a table where you don't want a component
wrapper per row — attach the `v-bb-date` directive to the element instead of
importing `BbDatePicker`. It is registered globally by the plugin
(`injectDirectives`, on by default) and renders no wrapper.

The value is the picker's **props bag**, spread straight onto the component (same
model as `v-bb-color` / `v-bb-dropdown`). A directive has no `v-model`, so bind
write-back with an `onUpdate:modelValue` callback (and `onUpdate:time` for
`datetime`). A directive argument sets placement (`v-bb-date:top`); a nullish
value attaches nothing, so it is safe to bind conditionally.

```vue
<template>
	<span
		v-bb-date="{
			modelValue: row.due,
			'onUpdate:modelValue': (d) => patch(row, { due: d }),
			floating: true,
		}"
	>
		{{ row.due ?? 'Set date' }}
	</span>
</template>
```

Reach for the **component** (slot or `activator` prop) when you want the
`#activator` slot's scope or a separate `anchor`. Like the other value pickers,
the directive is the shortcut for the bare-trigger cell case, not a replacement
for the component's `v-model` in a form.

### Relationship to BbDatePickerInput

`BbDatePickerInput` _is_ a `BbDatePicker` with a segmented text field wrapped
around it: the input owns the typing/validation engine and drives this picker for
its calendar, adaptive surface, and time rail. Anything you can select here you
can also select there — pick `BbDatePicker` when there is no text field to type
into, `BbDatePickerInput` when there is.

### Accessibility

The activator carries `aria-haspopup="dialog"`, `aria-expanded`, and an
`aria-label` (from `label`, falling back to a localized "Open date picker"). The
calendar grid is a `role="grid"` with a roving tabindex, arrow-key navigation,
and digit typeahead; the time rail exposes labelled columns. Always pass a
`label` when the trigger is an unlabelled cell or icon.

## v-model

- `v-model:activeSegment` — type: `BbDatePickerSegment \| undefined`
- `v-model` — type: `string \| string[] \| null`
- `v-model:time` — type: `string \| string[] \| null \| undefined`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activator` | `ElementOrComponentRef \| undefined` |  |  | External activator element or component ref. When provided, the `activator` slot is not rendered and click + ARIA are attached programmatically to the referenced element — mirroring the `BbColorPalette` activator API. |
| `activeSegment` | `BbDatePickerSegment \| undefined` |  |  | Which end the time rail edits in range + `type="datetime"` (`v-model:active-segment`). Standalone use manages this internally; an embedding host (the date input) drives it from its focused field. Ignored outside range + datetime. |
| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile, open in a bottom off-canvas sheet instead of a floating popover. When unset, falls back to the global `config.adaptive`. |
| `ampm` | `boolean \| undefined` | `false` |  | 12-hour display with an AM/PM column (requires `type="datetime"`); emits stay 24h. |
| `anchor` | `ElementOrComponentRef \| undefined` |  |  | Element or component ref the popover positions itself relative to. Defaults to the activator when omitted (anchor to a larger row while a smaller element stays the click target). |
| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the popover within a bounding element or CSS selector. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the activator and the calendar. |
| `disableFlip` | `boolean \| undefined` | `false` |  | Disable the automatic flip to the opposite side on overflow. |
| `eager` | `boolean \| undefined` | `false` |  | Render popover content before it is first shown. |
| `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` |  |  | First day of the week (0 = Sunday … 6 = Saturday). |
| `floating` | `boolean \| undefined` | `false` |  | Emit plain calendar strings instead of zoned ISO instants. Implied (and forced) by `type="month"` and `type="year"`. |
| `label` | `string \| undefined` |  |  | Accessible label applied to the activator via `aria-label`. |
| `max` | `string \| undefined` |  |  | Maximum selectable value, in this `type`'s shape. A finer bound is accepted and ceiled to the unit, with a warning. |
| `min` | `string \| undefined` |  |  | Minimum selectable value, in this `type`'s shape — `YYYY-MM-DD` (`YYYY-MM-DDTHH:mm` with `datetime`, `YYYY-MM` with `month`, `YYYY` with `year`). A finer bound is accepted and floored to the unit, with a warning. |
| `modelValue` | `string \| string[] \| null` |  | yes | v-model value. `null` for empty, a single string for single selection, or a two-element `[start, end]` array when `range` is true. The string shape follows `type`: `YYYY-MM-DD` when `floating` (`YYYY-MM` for `month`, `YYYY` for `year`), oth… |
| `multiple` | `boolean \| undefined` | `false` |  | Enables multi-selection: every pick toggles a value in or out of a sorted array, and the panel stays open until it is dismissed. Works in whatever `type` selects — days, months or years — and requires an array `modelValue` (use `[]` for emp… |
| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when adaptive on mobile. |
| `offset` | `number \| undefined` | `4` |  | Space the popover keeps from the activator. |
| `padding` | `number \| undefined` |  |  | Minimum empty space to keep from the edge of the page. |
| `placement` | `Placement \| undefined` |  |  | Position of the popover relative to the activator/anchor. |
| `range` | `boolean \| undefined` | `false` |  | Enables range selection (`[start, end]`). |
| `readonly` | `boolean \| undefined` | `false` |  | Prevents opening while keeping the activator visible. |
| `seconds` | `boolean \| undefined` | `false` |  | Adds the seconds column (requires `type="datetime"`). |
| `selectable` | `((date: string) => boolean) \| undefined` |  |  | Predicate invoked per candidate; return `false` to disable it. Receives the value in this `type`'s shape — `YYYY-MM` under `month`, `YYYY` under `year`. |
| `step` | `number \| undefined` | `1` |  | Minute-column granularity and arrow stepping (requires `type="datetime"`). |
| `time` | `string \| string[] \| null \| undefined` |  |  | Companion time model (`v-model:time`), 24-hour `HH:mm` / `HH:mm:ss`. With `floating` it is the only carrier of the time; otherwise it mirrors the time inside `modelValue`. Requires `type="datetime"`. |
| `transitionDuration` | `number \| undefined` | `250` |  | Popover/sheet transition duration in milliseconds. |
| `type` | `DatePickerType \| undefined` | `"date"` |  | What the picker selects, and therefore what it emits. - `date` (default) — a day. - `datetime` — a day plus a time rail beside the calendar. Non-floating values carry the time inside `modelValue`; with `floating` the time travels only throu… |
| `utc` | `boolean \| undefined` | `false` |  | Emit UTC (`...Z`) instead of the local offset. Ignored with `floating`, and therefore with `type="month"`/`type="year"`. |

## Events

- `grid-pick` — `(event: "grid-pick", value: string \| string[] \| null): void`
- `time-pick` — `(event: "time-pick", payload: { unit: TimeUnit; value: string; }): void`
- `update:activeSegment` — `(event: "update:activeSegment", value: BbDatePickerSegment): void`
- `update:modelValue` — `(event: "update:modelValue", value: string \| string[] \| null): void`
- `update:time` — `(event: "update:time", value: string \| string[] \| null): void`

## Slots

- `activator` — scope: `BbDatePickerActivatorSlotProps` — Custom activator element. Apply `v-bind="props"` to your trigger.
- `append:day` — scope: `BbDatePickerDaySlotProps` — Appends content below each calendar day.
- `day` — scope: `BbDatePickerDaySlotProps` — Replaces the day button label inside each calendar day.

## Exposed (template ref)

- `calendarEl`: `HTMLElement \| null`

## See Also

- [BbDatePickerInput](./BbDatePickerInput.md) — Combines date selection with text input behavior.
- [BbColorPalette](./BbColorPalette.md) — Opens an anchored popover color palette for color picking interactions.
- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements.

---

<!-- dist/ai/BbDatePickerInput.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbDatePickerInput.md -->

# BbDatePickerInput

## Agent Contract

- Safety level: **Consumer API**
- Group: **Inputs**
- Description: Combines date selection with text input behavior.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbDatePickerInput.md](./source/BbDatePickerInput.md)

## Usage & Guidelines

### When to use

Use `BbDatePickerInput` for any calendar date the user picks — invoice due dates,
report / filter ranges, appointments, trip windows. It renders a **segmented**
day / month / year text field plus a calendar popover, parses and formats with
[dayjs](https://day.js.org), and keeps the two in sync — typing a date moves the
calendar and vice versa. It shares the input-family chrome (`label`,
`description`, `hint`, `errors`, affixes, `clearable`, `loading`) with the rest
of the form.

Prefer it over a raw `<input type="date">` for consistent styling, range
selection, per-day gating and mobile behaviour. If you only need a
month/quarter/year from a short fixed list, a `BbSelect` is simpler.

By default `v-model` holds a full **ISO string with the local offset**
(`2026-07-02T00:00:00+02:00`); set `floating` to store the shorter `YYYY-MM-DD`
form instead (see _Output format_). Set `datetime` to pick a time alongside the
date (see _Time selection_). `label` is required.

### Label & messaging

The shared surface applies:

- **`label`** (required) names the field for display and accessibility only —
  it has **no** effect on the native `name` attribute of the segment inputs.
  Leave `name` unset and the rendered segments carry none at all, so a plain
  form post silently drops the value; pass `name` explicitly whenever it's
  submitted via a native form or read from `FormData`. **`hideLabel`** hides
  it visually while keeping the accessible name; **`labelPosition`** aligns
  it; the **`label` slot** replaces it with `{ text, hasErrors }`.
- **`labelMode`** — `outside` / `floating` / `inside`. When unset it falls back
  to the project-wide `config.defaultInputLabelMode` (library default:
  `outside`), the same resolution as `BbTextInput` and `BbNumberInput`.
- **`description`** (always visible), **`hint`** (shows while the control is
  active; `persistentHint` pins it), and **`errors`** + **`hasErrors`**
  (`aria-live` region, `aria-describedby`, `aria-invalid`) behave as everywhere
  else. The segment inputs merge the container's ids with their own format
  description, so nothing is dropped or duplicated.
- **`warnings`** is the amber counterpart of `errors`: a string or string array
  rendered below the field in its own `aria-live="polite"` region — and
  referenced from `aria-describedby` while displayed — for a
  valid-but-noteworthy value. A non-empty `warnings` implies the warning state
  (just as `errors` implies the error state), painting the same chrome as
  `hasErrors` but in amber (`--bb-warn`, a warning icon in the append stack).
  **`hasWarning`** forces that chrome without a message, the parallel of
  `hasErrors`. Unlike `hasErrors`, neither sets `aria-invalid` — a soft "needs a
  second look" state. `hasErrors` wins when both are set, and the warning
  messages are suppressed, so the field never shows amber while it has an error.
- **`required`** marks the segment inputs required to the browser.

**Label, description and a persistent hint**

```vue
<BbDatePickerInput
	v-model="state.issuedAt"
	label="Issue date"
	description="When the invoice is issued."
	hint="Type it or pick from the calendar."
	persistentHint
	prepend:icon="lucide:calendar"
/>
```

### Single date vs range

Bind a `string | null` for a single date. Set `range` and bind a `string[]`
(`[start, end]`) to pick a window — the calendar highlights every day between the
two clicks, and the field grows a second day/month/year trio joined by an
en-dash.

> **`range` requires an array modelValue.** In range mode the value must always
> be an array — use `[]` for "no selection", never `null` or `undefined`.
> Binding a non-array throws _"Date picker is set to select multiple dates but
> modelValue is not an array."_ at setup. If you model an empty filter as `null`
> elsewhere, seed and clear this field to `[]` instead (and test emptiness with
> `value.length === 0`). Clearing the field emits `[]`, so the array shape round-trips. The classic case is a stay or trip window: bound below by `min` so past
> check-ins can't be picked, with a nights summary derived from the two dates.

**Stay dates — range with a nights summary**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Book your stay</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Seaside Loft · Lisbon
			</p>
		</div>
		<BbDatePickerInput
			v-model="stay"
			compact
			floating
			label="Stay dates"
			:min="today"
			placeholder="Check-in → check-out"
			prepend:icon="lucide:calendar"
			range
		/>
		<p class="text-xs text-[color:var(--bb-text-muted)]">
			<template v-if="stay.length === 2">
				{{ stay[0] }} → {{ stay[1] }} · {{ nights }} night{{
					nights === 1 ? '' : 's'
				}}
			</template>
			<template v-else>No dates selected</template>
		</p>
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import dayjs from 'dayjs';
import { BbDatePickerInput } from 'bitboss-ui';

const stay = ref<string[]>([]);
const today = dayjs().format('YYYY-MM-DD');

const nights = computed(() =>
	stay.value.length === 2
		? dayjs(stay.value[1]).diff(dayjs(stay.value[0]), 'day')
		: 0
);
</script>
```

Range mode still lets the user **type** both the start and end dates directly —
it does not force the field read-only. If a range comes in reversed (end before
start) it is swapped for you on commit (see _Invalid input_). To prevent typing
entirely, reach for `disableWriting` (below), not `range`.

### The segmented field & typing

The value is edited as three separate inputs — day, month, year — not one free
string. Their **order follows `config.locale`**: `en` renders `MM / DD / YYYY`,
every other locale (e.g. `it`) renders `DD / MM / YYYY`. Typing is forgiving:

- digits **auto-advance** to the next segment when a segment fills (or can't
  take another digit — e.g. `4` in a day segment becomes `04` and moves on);
- `/`, `-` or space also advances; **Backspace** at the start of a segment (and
  **←** / **→** at the edges) moves between segments;
- **↑** / **↓** step the focused segment by one, wrapping at its bounds (day
  `31` → `01`, month `12` → `01`, a 24-hour `23` → `00` — and back the other
  way); an empty segment starts from its smallest value;
- focusing a segment selects it for quick replacement;
- **pasting** `01/02/2024` (or a whole `01/02/2024 - 03/04/2025` range)
  distributes the digits across the remaining segments regardless of separators;
- impossible dates self-correct — typing Feb 31 snaps to Feb 28/29 on commit.

An incomplete date is never emitted: the model updates only once a segment
parses to a real date, and a half-typed segment is restored to the last coherent
value when focus leaves the control.

### Bounds & per-day gating

`min` and `max` (each a `YYYY-MM-DD` string) constrain the selectable window;
days outside it render disabled in the calendar, and a typed out-of-range date is
snapped back on commit. **Malformed `min`/`max` throw during setup** on purpose,
to catch config mistakes early — always pass the `YYYY-MM-DD` shape.

For non-contiguous rules (no weekends, no holidays, only in-stock slots), pass a
`selectable` predicate: it receives each date string and returns `false` to
disable that day. `firstDayOfWeek` shifts the calendar grid (`0` = Sunday …
`6` = Saturday).

The example below combines a rolling `min`/`max` window, a weekdays-only
predicate, `floating` output, and the `append:day` slot to dot specific days.

**Bounded, weekdays-only, with event dots**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Book a demo</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				30 minutes. Dotted days still have open slots.
			</p>
		</div>
		<BbDatePickerInput
			v-model="appointment"
			compact
			floating
			hint="Weekdays only, within the next 30 days."
			label="Demo date"
			:max="max"
			:min="min"
			persistent-hint
			placeholder="YYYY-MM-DD"
			prepend:icon="lucide:calendar-check"
			:selectable="isWeekday"
		>
			<template #append:day="{ item }">
				<span
					v-if="hasOpenSlots(item)"
					class="mx-auto mt-0.5 block h-1 w-1 rounded-full bg-current opacity-70"
				/>
			</template>
		</BbDatePickerInput>
		<p class="text-xs text-[color:var(--bb-text-muted)]">
			{{ appointment ? `Booked for ${appointment}` : 'No date chosen yet.' }}
		</p>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import dayjs, { type Dayjs } from 'dayjs';
import { BbDatePickerInput } from 'bitboss-ui';

const appointment = ref<string | null>(null);

const min = dayjs().format('YYYY-MM-DD');
const max = dayjs().add(30, 'day').format('YYYY-MM-DD');

// Days that still have open demo slots — dotted via the `append:day` slot.
const openSlots = [3, 5, 8, 12].map((offset) =>
	dayjs().add(offset, 'day').format('YYYY-MM-DD')
);
const hasOpenSlots = (item: Dayjs) =>
	openSlots.includes(item.format('YYYY-MM-DD'));

const isWeekday = (date: string) => {
	const day = dayjs(date).day();
	return day !== 0 && day !== 6;
};
</script>
```

### Output format

By default the model is a full ISO timestamp **carrying the local offset**
(`2026-07-02T00:00:00+02:00`) — the emitted digits always match what the user
sees in the fields. If your backend expects UTC `Z` strings, add `utc`: it
switches emission to `toISOString()` and changes nothing else. Reading accepts
both forms (and naked local strings) either way, so adding or removing `utc`
never requires migrating stored values.

When you only care about the calendar day — and want a value that's trivial to
compare, store or send to an API — set `floating` and the model becomes a plain
`YYYY-MM-DD` string (as in the appointment example above). `floating` + `utc`
is incoherent (a plain date has no zone) and `utc` is ignored with a DEV
warning. Pick one format per field and stick to it; `min` / `max` are
`YYYY-MM-DD` regardless of `floating` (plus an optional `THH:mm` with
`type="datetime"`, and the unit's own shape under `type="month"`/`year` — see
below).

Floating output shines in filters. The invoice issue-date bar below — the shape
every records workspace uses — stores plain `YYYY-MM-DD` strings, so the preset
buttons can write straight into the model and the values go into an API query
untouched. `max` pins the window to today, and `hideLabel` keeps the accessible
name while the field reads as toolbar chrome.

**Issue-date range filter with presets**

```vue
<template>
	<div class="grid max-w-md gap-3 rounded-[var(--bb-radius)] border p-4">
		<div class="flex flex-wrap items-center justify-between gap-2">
			<div>
				<p class="text-sm font-medium">Issue date</p>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					Filter the invoice list
				</p>
			</div>
			<div class="flex gap-1.5">
				<BbButton size="xs" variant="outline" @click="setPreset(7)">
					Last 7 days
				</BbButton>
				<BbButton size="xs" variant="outline" @click="setPreset(30)">
					Last 30 days
				</BbButton>
				<BbButton size="xs" variant="outline" @click="setPreset(90)">
					Last quarter
				</BbButton>
			</div>
		</div>
		<BbDatePickerInput
			v-model="period"
			clearable
			compact
			floating
			hide-label
			label="Issue date range"
			:max="today"
			placeholder="Start → end"
			prepend:icon="lucide:calendar-range"
			range
		/>
		<p class="text-xs text-[color:var(--bb-text-muted)]">
			{{
				period.length === 2
					? `Showing invoices from ${period[0]} to ${period[1]}`
					: 'Pick a period or use a preset.'
			}}
		</p>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import dayjs from 'dayjs';
import { BbButton, BbDatePickerInput } from 'bitboss-ui';

const today = dayjs().format('YYYY-MM-DD');
const period = ref<string[]>([]);

// `floating` keeps the model as plain YYYY-MM-DD strings, so presets can
// write straight into it — no ISO conversion on either side.
const setPreset = (days: number) => {
	period.value = [
		dayjs()
			.subtract(days - 1, 'day')
			.format('YYYY-MM-DD'),
		today,
	];
};
</script>
```

### `type` — day, month, year, or day + time

`type` decides which segments the field renders and what it emits. It mirrors
`<input type="…">`:

| `type`             | segments       | emits                 | range emits              |
| ------------------ | -------------- | --------------------- | ------------------------ |
| `date` _(default)_ | `DD/MM/YYYY`   | ISO / `YYYY-MM-DD`    | `[start, end]`           |
| `datetime`         | + `HH:mm(:ss)` | ISO carrying the time | `[start, end]`           |
| `month`            | `MM/YYYY`      | `2026-08`             | `['2026-01', '2026-03']` |
| `year`             | `YYYY`         | `2026`                | `['2026', '2028']`       |

```vue
<BbDatePickerInput v-model="period" label="Reporting period" type="month" />
<!-- period === '2026-08' -->
```

There is no day segment to tab through under `month`, no month segment under
`year`, and the placeholder/format hint follows suit (`MM/YYYY`, localized) —
promising `DD/MM/YYYY` to a two-segment field would be worse than no hint at
all. The calendar button opens the matching terminal grid, so typing and
picking always produce the same shape.

`month` and `year` are **calendar labels, not instants**: they force `floating`,
ignore `utc`, and make the time props inert. This is deliberate rather than
squeamish — the start of August in Rome is the 31st of July in UTC, so a month
stored as an instant reads back as the wrong month for half the world.

`min`/`max` take the value's own shape (`min="2026-03"`). A finer bound is
accepted and rounded **outward** to the unit — `min` floors, `max` ceils — with
a DEV warning, so `min="2026-03-15"` under `type="month"` leaves the whole of
March selectable instead of quietly deleting it. `selectable` receives the same
shape it emits.

### Time selection

Set `type="datetime"` and the field grows 24-hour `HH:mm` segments after the date
(auto-advance, paste distribution and ↑/↓ stepping included), and the calendar gains hour /
minute columns beside the grid. A picked or typed date with a blank time
commits at `00:00` — the panel stays open after a day click so the user can
still pick a time, and the time columns stay disabled until a date exists.

**Date and time**

```vue
<BbDatePickerInput
	v-model="state.startsAt"
	type="datetime"
	label="Starts at"
	prepend:icon="lucide:calendar-clock"
/>
```

Tuning knobs, all inert without `datetime` (DEV warning):

- **`seconds`** adds the `:ss` segment. Without it, an incoming value carrying
  seconds displays truncated and zeroes out on the next user commit — precision
  never rides along invisibly.
- **`step`** (minutes, default `1`) shapes the minute column — `:step="15"`
  renders 00/15/30/45 — and constrains what the panel _produces_, never what
  the field _accepts_: a typed `10:07` is emitted verbatim, and no column row
  highlights for it.
- **`ampm`** switches the display to 12-hour with an AM/PM segment (type `A` /
  `P`, or cycle with ArrowUp/Down). Purely visual: the model stays 24-hour.
- **`min` / `max`** additionally accept `YYYY-MM-DDTHH:mm` to tighten the
  boundary day to a minute; date-only bounds keep working day-granular, so any
  time inside the boundary day is fine.

#### The `time` companion model

`v-model:time` carries the time part as a 24-hour `HH:mm` (or `HH:mm:ss`)
string — an array in range mode. It emits alongside every value change:

- **Non-floating**: the time already lives inside `modelValue`; the mirror has
  the _same digits_, and writing to it rewrites the model's time part. Bind it
  only if you want the time as a separate piece of state.
- **`floating`**: the date string stays plain `YYYY-MM-DD`, so `v-model:time`
  is the **only** carrier of the time — bind it or the time is lost.

**Floating date + separate time**

```vue
<BbDatePickerInput
	v-model="state.reminderDate"
	v-model:time="state.reminderTime"
	type="datetime"
	floating
	label="Reminder"
/>
```

In `range` mode each end has its own time; a same-day range whose end time
precedes its start swaps on blur (the usual `end_before_start` error fires).
The panel's time columns edit the segment whose fields you focused last.

### Invalid input & the error event

Typing (not calendar-clicking, which can only pick valid days) can produce a
date that's disabled or a reversed range. On commit the component **normalises**
the value and emits an `error` event describing what it did, so you can surface a
message. It never silently keeps an invalid value.

The payload is a discriminated union on `code`:

| `code`                 | Trigger                       | `normalized`                                                      |
| ---------------------- | ----------------------------- | ----------------------------------------------------------------- |
| `disabled_date`        | Typed single date is disabled | Snapped to `min`/`max`, or `null` if only `selectable` blocked it |
| `disabled_range_start` | Typed range start is disabled | Snapped range, or `null`                                          |
| `disabled_range_end`   | Typed range end is disabled   | Range with end snapped, or `[start]`                              |
| `end_before_start`     | Typed end is before start     | `[end, start]` — the swapped pair                                 |

Each payload also carries `original` (what the user typed). Turn it into a
user-visible message via `errors` + `hasErrors`. The invoice due-date card below
bounds the field with `:min="issuedAt"` — typing an earlier day snaps to the
issue date and surfaces the normalisation.

**Invoice due date with bounds error**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div class="flex items-start justify-between gap-3">
			<div>
				<p class="text-sm font-medium">INV-2048</p>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					Acme Studio · $2,400.00
				</p>
			</div>
			<p class="text-xs text-[color:var(--bb-text-muted)]">Draft</p>
		</div>
		<BbDatePickerInput
			v-model="dueDate"
			compact
			:errors="dueError"
			floating
			:has-errors="!!dueError"
			hint="Must be on or after the issue date."
			label="Due date"
			:min="issuedAt"
			persistent-hint
			placeholder="YYYY-MM-DD"
			prepend:icon="lucide:calendar"
			@error="onError"
			@update:model-value="dueError = ''"
		/>
		<p class="text-xs text-[color:var(--bb-text-muted)]">
			Issued {{ issuedAt }} · Net 30 from issue
		</p>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbDatePickerInput, type DatePickerInputError } from 'bitboss-ui';

const issuedAt = '2026-03-01';
const dueDate = ref<string | null>('2026-03-31');
const dueError = ref('');

// Typing a day before the issue date snaps to `min` and fires `error` —
// surface that normalisation through `errors` + `hasErrors`.
const onError = (error: DatePickerInputError) => {
	dueError.value =
		error.code === 'disabled_date'
			? "Due date can't be before the issue date — adjusted."
			: 'That date was adjusted to stay valid.';
};
</script>
```

### Platform-aware interaction

The picker adapts to touch vs pointer, and you can steer that explicitly:

- **`adaptive`** (defaults to the project's `config.adaptive`): on mobile the
  calendar opens in a bottom `BbOffCanvas` sheet instead of a floating popover.
  The surface is **latched** when the panel opens, so a mid-session resize never
  swaps a live popover into a sheet. Forward sheet options via `offCanvasProps`
  (e.g. `title`, `size`, `persistent`, `draggable`). Set `:adaptive="false"` to
  force the floating popover on every viewport (deterministic in tests).
- **`disableWriting`**: block typing so the calendar is the only way in. Use
  `'mobile'` / `'desktop'` to disable typing on just one platform.
- **`disableCalendar`**: hide the calendar trigger entirely. Use `'mobile'` /
  `'desktop'` to disable it on just one platform. Pair
  `disableWriting: 'mobile'` with `disableCalendar: 'desktop'` to get "type on
  desktop, tap the calendar on mobile".

Guard rail: a configuration that leaves a platform with **no** way to enter a
date (e.g. `disableWriting: true` **and** `disableCalendar: true`) **throws
during setup** — every platform must keep at least one interaction method.

**Typed-only on desktop**

```vue
<BbDatePickerInput
	v-model="state.dueDate"
	label="Due date"
	disableWriting="mobile"
	hint="Type it, or pick from the calendar."
	persistentHint
	prepend:icon="lucide:calendar"
	placeholder="YYYY-MM-DD"
/>
```

### Decorating days

The `day` slot **replaces** a day's contents; the `append:day` slot **adds**
below it (badges, event dots, price tags). Both receive the day's state — `label`
(the day number), `selected`, `highlighted`, `first` / `middle` / `last` (range
edges) and `item` (the underlying dayjs object, for formatting or lookups). Keep
decorations lightweight; they render for every visible cell. The appointment
example above uses `append:day` for event dots.

### Calendar keyboard navigation

The calendar grid is a `role="grid"` with a roving tabindex (the current day is
the single tab stop). Once focused:

- **arrow keys** move by day (←/→) and week (↑/↓);
- **Home** / **End** jump to the week's edges, **PageUp** / **PageDown** change
  month, and type-ahead jumps within the visible month;
- **Enter** / **Space** select the focused day and close the surface;
- the month and year headings open their own pick panels (Enter toggles them).

Today carries `aria-current="date"`, the selection carries `aria-selected`, and
each day button has a full spoken date label — so don't add your own key
handlers.

### Icons, affixes, clearable, loading & states

`prepend:icon` / `append:icon`, and the `prefix` / `suffix` / `prepend` /
`append` / `prepend-outer` / `append-outer` slots work as across the family. The
append slot sits alongside the calendar trigger button.

`clearable` shows a clear button when a value is present and interactive; it
emits `null` for a single field and `[]` for a range. `loading` shows a spinner
(visual only). `disabled` blocks everything including the calendar trigger
(`aria-disabled`); `readonly` keeps the value readable and copyable but blocks
typing and the calendar (`aria-readonly`).

**Clearable contract start and a readonly created stamp**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Contract dates</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Clear the start date, or copy the locked created stamp.
			</p>
		</div>
		<BbDatePickerInput
			v-model="from"
			clearable
			compact
			floating
			label="Contract start"
			placeholder="YYYY-MM-DD"
			prepend:icon="lucide:calendar"
		/>
		<BbDatePickerInput
			compact
			floating
			label="Created"
			model-value="2026-06-02"
			prepend:icon="lucide:calendar"
			readonly
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbDatePickerInput } from 'bitboss-ui';

// Clearable emits `null` when the user hits the clear button.
const from = ref<string | null>('2026-05-01');
</script>
```

### Events & v-model

Because the control is a composite (segmented fields + calendar + optional
sheet), its events differ from a plain input:

- `update:modelValue` — `null` / single string / `[start, end]` per mode and
  `floating`.
- `error` — a `DatePickerInputError` on every normalisation (see _Invalid
  input_).
- `active` / `inactive` — fire when focus enters / leaves the whole control
  (not per-field); these gate the `hint`'s show-on-focus behaviour. Use them
  instead of `blur`, which is not forwarded at this level.
- `focus` — forwarded when a segment input gains focus.

### Density, layout, config & platforms

- `compact` reduces height; `direction` works whenever the resolved label mode
  is `'outside'` (the config default) — `direction="horizontal"` lays the label
  beside the field. With `labelMode="floating"` or `"inside"` (prop or
  `config.defaultInputLabelMode`) the label is embedded in the field, so the
  layout is forced vertical and `direction` is ignored — same rule as
  `BbTextInput`/`BbSelect`/`BbNumberInput`.
- **`config.locale`** drives both the segment order (`en` → month-first) and the
  calendar's month/weekday names via dayjs (a dayjs pack is bundled for each of
  your `enabledLocales` — see
  [Installation and Plugin Setup](./guides/installation-and-plugin-setup.md) §
  locale).
- The calendar popover / sheet is **teleported** to the top layer, so its DOM
  isn't a child of the field — account for that in tests (query `document.body`)
  and z-index reasoning. The field itself is SSR-safe; the popover mounts client
  side.

```vue
<!-- Inertia: bind server validation; store the floating YYYY-MM-DD form -->
<BbDatePickerInput
	v-model="form.dueDate"
	label="Due date"
	floating
	:min="today"
	:errors="form.errors.dueDate"
	:has-errors="!!form.errors.dueDate"
/>
```

### Works well with

- `BbTextInput` / `BbTextarea` / `BbNumberInput` — same chrome; mix in one form.
  The `BbTextInput` invoice example composes all four, including a `range` date
  field for a service period and a `min`-bounded due date.
- `BbSelect` — when a date is really a choice from a short fixed list
  (month, quarter), a select is simpler.
- `BbOffCanvas` — the adaptive mobile surface; tune it through `offCanvasProps`.
- `useToast` — confirm a booking once the date is committed.

### Gotchas & anti-patterns

- `min` / `max` must be `YYYY-MM-DD` — other shapes **throw at setup**.
- Disabling _both_ typing and the popover on a platform **throws** — always
  leave one interaction path.
- Don't gate dates with a custom click handler on top of `selectable`/`min`/`max`
  — disabled days are already communicated to assistive tech; a parallel handler
  desyncs them.
- Don't listen for `blur` here — use `inactive` (the composite tracks focus
  across its fields and teleported calendar manually).
- Range mode requires an **array** modelValue (`[start, end]`, or `[]` when
  empty). Binding `null`/`undefined` or a bare string throws at setup — model the
  empty state as `[]`, not `null`.
- Pick one of ISO or `floating` per field and store it consistently; don't mix
  formats for the same value.

### Accessibility

- Always provide `label`; hide it visually with `hideLabel` rather than dropping
  it.
- Keep `min` / `max` and `selectable` authoritative — disabled days are exposed
  to assistive tech; don't also gate via custom handlers.
- The `error` event fires when a typed value is invalid or out of bounds; surface
  that through `errors` + `hasErrors` rather than failing silently.
- The calendar exposes `role="grid"`, `aria-current="date"` on today,
  `aria-selected` on the selection and spoken date labels on each day; the
  trigger button carries `aria-haspopup="dialog"` and `aria-expanded`.
- **Driving this field from a test:** each segment input carries its own
  localized `aria-label` ("Month"/"Day"/"Year", …) that overrides the field's
  own `label` for the accessible-name computation — `getByLabel('<field
label>')` matches nothing; query each segment by its own label instead. See
  [Agent Contract](./guides/agent-contract.md) § Testing Against bitboss-ui.

## v-model

- `v-model` — type: `string \| string[] \| null`
- `v-model:time` — type: `string \| string[] \| null \| undefined`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile the calendar opens inside a bottom off-canvas sheet instead of a floating popover, mirroring the adaptive behaviour of `BbPopover`/`BbSelect`. When unset, falls back to the global `config.adaptive`. |
| `ampm` | `boolean \| undefined` | `false` |  | 12-hour display with an AM/PM segment (requires `type="datetime"`). Purely a field-composition concern: `modelValue` and the `time` model stay 24-hour regardless. Type `A`/`P` (or ArrowUp/Down) to set the meridiem. |
| `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
| `autocomplete` | `string \| undefined` |  |  | Guides the browser as to the type of information expected in the field. |
| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
| `clearable` | `boolean \| undefined` | `false` |  | Displays a clear button when the input has a value and is being interacted with. |
| `compact` | `boolean \| undefined` | `false` |  | Sets the component in a compact state. |
| `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
| `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
| `disableCalendar` | `boolean \| "mobile" \| "desktop" \| undefined` |  |  | Disables the calendar: hides the trigger button and prevents the popover from opening. Use `'desktop'` to disable it on desktop only (keeping the calendar for mobile, complementing `disableWriting: 'mobile'`) or `'mobile'` to disable it on … |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
| `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` | `false` |  | Disables typing into the input. Use `'mobile'` to disable typing only on mobile, `'desktop'` to disable typing only on desktop. |
| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
| `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` |  |  | Defines the first day of the week with `0` meaning Sunday and `6` meaning Saturday. |
| `floating` | `boolean \| undefined` | `false` |  | If true the date will have a format YYYY-MM-DD instead of the default ISO string. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `label` | `string` |  | yes | Text content of the label of the element. |
| `labelMode` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Label rendering mode. |
| `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
| `loading` | `boolean \| undefined` | `false` |  | Sets the component in a loading state, usually triggering some visual styles. |
| `max` | `string \| undefined` |  |  | Maximum selectable date in `YYYY-MM-DD` format — or, with `type="datetime"`, `YYYY-MM-DDTHH:mm` to tighten the boundary day to a minute. Values outside both patterns throw during setup to surface configuration mistakes. |
| `min` | `string \| undefined` |  |  | Minimum selectable date in `YYYY-MM-DD` format — or, with `type="datetime"`, `YYYY-MM-DDTHH:mm` to tighten the boundary day to a minute. Values outside both patterns throw during setup to surface configuration mistakes. |
| `modelValue` | `string \| string[] \| null` |  | yes | Used by v-model. Can be null, a single string, or an array of strings based on whether a range or single date is needed. |
| `name` | `string \| undefined` |  |  | Defines the name of the input. |
| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile (e.g. `title`, `size`, `persistent`). |
| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
| `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
| `range` | `boolean \| undefined` | `false` |  | Selects a range of dates between two dates. It selects all of the days between start and end. |
| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
| `seconds` | `boolean \| undefined` | `false` |  | Adds the seconds segment (requires `type="datetime"`). Without it, an incoming value carrying seconds displays truncated and is left untouched until the user commits an edit, at which point seconds zero out. |
| `selectable` | `((date: string) => boolean) \| undefined` |  |  | Function that accepts a `string` object and returns a boolean. `false` meaning the date cannot be selected. |
| `step` | `number \| undefined` | `1` |  | Minute granularity for the calendar's minute column and arrow stepping (requires `type="datetime"`). Constrains what the component produces, never what it accepts: a typed off-grid value (e.g. `10:07` with `step: 15`) is emitted verbatim, a… |
| `time` | `string \| string[] \| null \| undefined` |  |  | Companion model for the time part (`v-model:time`), always 24-hour `HH:mm` / `HH:mm:ss` regardless of display. With `floating` it is the only carrier of the time; otherwise it mirrors the time inside `modelValue` (same digits) and writing i… |
| `transitionDuration` | `number \| undefined` |  |  | Transition duration, in milliseconds, for the popover appearance. |
| `type` | `DatePickerType \| undefined` | `'date'` |  | What the field edits, and therefore its segments and emitted shape. - `date` (default) — `DD/MM/YYYY`. - `datetime` — adds the time segments and the calendar's time rail. - `month` — `MM/YYYY`, emitting `YYYY-MM`. - `year` — `YYYY`, emittin… |
| `utc` | `boolean \| undefined` | `false` |  | Emits values as UTC ISO strings (`...Z`) instead of ISO strings carrying the local offset (`...+01:00`). Emission-only: incoming values are parsed identically either way, so the prop can be added or removed without touching stored values. F… |
| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |

## Events

- `active` — `(event: "active"): void`
- `error` — `(event: "error", error: DatePickerInputError): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `inactive` — `(event: "inactive"): void`
- `update:modelValue` — `(event: "update:modelValue", value: string \| string[] \| null): void`
- `update:time` — `(event: "update:time", value: string \| string[] \| null): void`

## Slots

- `append` — scope: `object` — Content rendered after the date fields, at the end of the inner container (before the calendar toggle button).
- `append-outer` — scope: `object` — Content rendered after the entire date picker control, outside the input chrome.
- `append:day` — scope: `{ first: boolean; highlighted: boolean; item: Dayjs; label: string; last: boolean; middle: boolean; selected: boolean; }` — Appends content below each calendar day.
- `day` — scope: `{ first: boolean; highlighted: boolean; item: Dayjs; label: string; last: boolean; middle: boolean; selected: boolean; }` — Replaces the day button label inside each calendar day.
- `label` — scope: `BbDatePickerInputLabelSlotProps` — Replaces the default label text rendered above the date picker.
- `prefix` — scope: `object` — Inline content rendered at the start of the input field area, before the date fields.
- `prepend` — scope: `object` — Content rendered before the date fields, at the start of the inner container.
- `prepend-outer` — scope: `object` — Content rendered before the entire date picker control, outside the input chrome.
- `suffix` — scope: `object` — Inline content rendered at the end of the input field area, after the date fields.

## Validated variant

Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).

| Prop | Type | Description |
| --- | --- | --- |
| `rules` | `RuleExpression<string \| string[] \| null>` | vee-validate rules for this field. |
| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |

## See Also

- [BbDatePicker](./BbDatePicker.md) — Opens an anchored calendar (and optional time rail) popover on a trigger you own — the date analog of BbColorPalette; also the v-bb-date directive.
- [BbTextInput](./BbTextInput.md) — Captures single-line text values.
- [BbTimePickerInput](./BbTimePickerInput.md) — Segmented time field with hour/minute columns; 24-hour string model.

---

<!-- dist/ai/BbDialog.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbDialog.md -->

# BbDialog

## Agent Contract

- Safety level: **Consumer API**
- Group: **Overlay**
- Description: Presents modal dialogs for focused user interactions.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbDialog.md](./source/BbDialog.md)

## Usage & Guidelines

### When to use

Reach for `BbDialog` when the user must **complete one focused task** without
losing the context behind it: an edit form, a create step, a blocking
announcement. It renders on top of the page with a backdrop and takes focus,
so everything else is inert until it closes.

Pick a sibling instead when the shape fits it better:

- Supplementary content that sits _beside_ the page (filters, a detail panel,
  settings) → `BbOffCanvas`.
- A plain yes/no — especially a destructive confirm → `BbConfirm` with
  `useConfirm`, not a hand-built dialog.
- A small anchored menu or bit of interactive content → `BbPopover`.

`BbDialog` and `BbOffCanvas` share most of their API (v-model, `title`, the
`default`/`footer` slots, `persistent`, `focus-target`, `eager`, `stack`,
`transition-duration`), so moving a surface between them is mostly a tag swap.

### Open and close with v-model

`v-model` owns visibility — there is no imperative `open()`. Bind a boolean and
flip it. The dialog dismisses itself on the header close button, the `Escape`
key, and a backdrop click; the `default` slot also receives a `close` callback
for buttons inside the body. Footer buttons simply set the model back to
`false`.

**A create-record dialog**

```vue
<template>
	<div
		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
	>
		<div>
			<p class="m-0 text-sm font-medium">Issue labels</p>
			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
				12 labels · used across Northwind issues
			</p>
		</div>
		<div>
			<BbButton
				prepend:icon="lucide:plus"
				variant="primary"
				@click="open = true"
			>
				New label
			</BbButton>
		</div>
	</div>
	<BbDialog v-model="open" title="Create label" @show="reset">
		<div class="grid gap-3">
			<BbTextInput
				v-model="name"
				compact
				label="Label name"
				placeholder="e.g. Priority"
			/>
			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
				Names are unique per workspace and show up in filters.
			</p>
		</div>
		<template #footer>
			<div class="flex justify-end gap-2">
				<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
				<BbButton :disabled="!name.trim()" variant="primary" @click="create">
					Create
				</BbButton>
			</div>
		</template>
	</BbDialog>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbDialog, BbTextInput } from 'bitboss-ui';

const open = ref(false);
const name = ref('');

// Re-seed on `@show`, not on close — a dismissed dialog may be reopened.
const reset = () => {
	name.value = '';
};

const create = () => {
	// Persist the new label here, then close.
	open.value = false;
};
</script>
```

### Header, footer and body

A `title` prop renders the standard header (title text + close button) and wires
`aria-labelledby` for you. Put form fields in the `default` slot and actions in
the `footer` slot — keep exactly one primary action there and align the group to
the end. The body area scrolls internally when content overflows; header and
footer stay pinned. This edit-record dialog re-seeds a typed draft from the
record on `@show` — so a canceled edit never leaks into the next session — and
copies it back on save.

**Edit-record dialog with a footer action**

```vue
<template>
	<div
		class="flex w-full max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-4"
	>
		<div class="min-w-0">
			<p class="m-0 truncate text-sm font-medium">{{ contact.name }}</p>
			<p class="m-0 truncate text-xs text-[color:var(--bb-text-muted)]">
				{{ contact.email }}
			</p>
		</div>
		<BbButton
			prepend:icon="lucide:pencil"
			variant="outline"
			@click="open = true"
		>
			Edit contact
		</BbButton>
	</div>
	<BbDialog v-model="open" size="md" title="Edit contact" @show="seedDraft">
		<div class="grid gap-3">
			<BbTextInput v-model="draft.name" compact label="Full name" />
			<BbTextInput v-model="draft.email" compact label="Email" type="email" />
			<BbSwitch v-model="draft.subscribed" label="Subscribed to updates" />
		</div>
		<template #footer>
			<div class="flex justify-end gap-2">
				<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
				<BbButton variant="primary" @click="save">Save changes</BbButton>
			</div>
		</template>
	</BbDialog>
</template>

<script setup lang="ts">
import { reactive, ref } from 'vue';
import { BbButton, BbDialog, BbSwitch, BbTextInput } from 'bitboss-ui';

type Contact = {
	name: string;
	email: string;
	subscribed: boolean;
};

// The record being edited — in a real app this comes from your store/API.
const contact = reactive<Contact>({
	name: 'Ada Lovelace',
	email: 'ada@analytical.co',
	subscribed: true,
});

const open = ref(false);
const draft = reactive<Contact>({ ...contact });

// Re-seed on every open: a canceled edit must not leak into the next session.
const seedDraft = () => {
	Object.assign(draft, contact);
};

const save = () => {
	// Persist here, then dismiss.
	Object.assign(contact, draft);
	open.value = false;
};
</script>
```

Use the `title` slot to restyle just the title text — it stays wired to
`aria-labelledby` and receives the `title` prop as `text`. Omitting `title`
removes the whole header (the close button then floats over the body corner
unless `hide-close`), and you own the accessible name.

Prefer `title` (or the `title` slot) for the standard header. The `header` slot
replaces the entire header on both surfaces — you own the close control and must
wire `titleId` for `aria-labelledby`. Give your root element `flex-1` so it fills
the header row.

### Forms in a dialog

The most common dialog is a small form: validate in place, keep the primary
action disabled until the input is usable, and close only on success. Cancel
must always work — never gate it on validity. This companion disables **Send
invite** until the email is plausible, and resets the draft on `@show` so a
dismissed invite doesn't resurface half-typed:

**Invite a teammate**

```vue
<template>
	<div
		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
	>
		<div>
			<p class="m-0 text-sm font-medium">Team · Northwind Labs</p>
			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
				4 members · 1 pending invite
			</p>
		</div>
		<div>
			<BbButton
				prepend:icon="lucide:user-plus"
				variant="primary"
				@click="open = true"
			>
				Invite teammate
			</BbButton>
		</div>
	</div>
	<BbDialog v-model="open" title="Invite a teammate" @show="reset">
		<div class="grid gap-3">
			<BbTextInput
				v-model="email"
				compact
				label="Email address"
				placeholder="teammate@company.com"
				type="email"
			/>
			<BbSelect
				v-model="role"
				compact
				item-text="label"
				item-value="value"
				:items="roles"
				label="Role"
			/>
			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
				They'll get an email with a link that expires in 7 days.
			</p>
		</div>
		<template #footer>
			<div class="flex justify-end gap-2">
				<!-- Cancel is never gated on validity. -->
				<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
				<BbButton
					:disabled="!canSend"
					prepend:icon="lucide:send"
					variant="primary"
					@click="send"
				>
					Send invite
				</BbButton>
			</div>
		</template>
	</BbDialog>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbButton, BbDialog, BbSelect, BbTextInput } from 'bitboss-ui';

const roles = [
	{ label: 'Member', value: 'member' },
	{ label: 'Admin', value: 'admin' },
	{ label: 'Viewer', value: 'viewer' },
];

const open = ref(false);
const email = ref('');
const role = ref('member');

// Re-seed on `@show`, not on close — a dismissed dialog may be reopened.
const reset = () => {
	email.value = '';
	role.value = 'member';
};

// Primary action stays disabled until the email is plausible.
const canSend = computed(() => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email.value));

const send = () => {
	// Send the invite here, then close only on success.
	open.value = false;
};
</script>
```

Two rules keep dialog forms honest:

- Reset or re-seed the draft when the dialog opens (`@show` is the hook), not
  when it closes — a dismissed dialog may be reopened with stale state.
- On success, do the work first, then set the model to `false`; the close
  transition runs while your toast/refresh happens.

### Lifecycle events and lazy content

Four events bracket the transitions — `show` fires as the model turns `true`,
`shown` after the native `showModal()` call and initial focus, `hide` as the
model turns `false`, and `hidden` after the close transition completes. Use
`@show` to (re)seed form state, `@hidden` to tear down expensive content.

Body content is **lazy**: nothing inside the dialog renders until the first
open. Set `eager` to render it immediately (e.g. so a chart can pre-measure, or
tests can query content before opening). `transition-duration` (ms, default
`250`) times both the open/close animation and when `hidden` fires — reopening
during the close transition keeps the dialog open instead of snapping shut.

### Size

`size` runs the shared `xs`–`2xl` scale and controls the dialog's **max width**
(height always hugs content). The presets map to `config.dialogDefaultSizes`
(384px for the default `sm`, up to 672px for `2xl`, overridable in the plugin
options); a number is pixels and a string passes through as a CSS width. Give it
a per-breakpoint map to widen responsively — narrow on phones, roomier on
desktop — without media queries of your own. A bare size is resolved once; only
the map form reacts to live resizes.

**Responsive width**

```vue
<div>
	<BbButton variant="outline" @click="state.open = true">
		Release notes
	</BbButton>
	<BbDialog
		v-model="state.open"
		:size="{ default: 'sm', lg: 'xl' }"
		title="What's new"
	>
		<p class="m-0 text-sm">
			<strong>sm</strong> on phones, <strong>xl</strong> from the
			<code>lg</code> breakpoint up — resize to see it switch.
		</p>
	</BbDialog>
</div>
```

`fullscreen` overrides the scale and fills the viewport (minus the standard page
padding — it is intentionally not edge-to-edge). Pass `fullscreen="mobile"` to
go fullscreen only below the mobile breakpoint while keeping the sized modal on
desktop.

### Controlling dismissal

Every dismissal path is governed by two props:

- `persistent` — backdrop click and `Escape` no longer close; the dialog plays a
  short "deny" nudge instead. Your own buttons (and the model) still work. Use
  it when the user must make an explicit choice.
- `disabled` — same guard, different intent: the surface is busy (a save in
  flight). Combine with disabling your footer actions.

The header **close button bypasses `persistent`, but respects `disabled`**
(`BbDialog.vue:471-477`): while `disabled` is set the × plays the same deny
nudge as the backdrop and does not close. So for the common case — a dialog
that must stay put while a save is in flight — `disabled` alone is enough and
you keep the ×. Reach for `hide-close` only when the dialog must be resolved
from the footer _permanently_; pair it with `persistent` and keep a visible
Cancel so users are never trapped.

Backdrop clicks are drag-protected: a text selection that starts inside the
dialog and releases over the backdrop does not close it — only a genuine click
that starts and ends on the backdrop (≤4px travel) does.

`focus-target` (a CSS selector resolved inside the dialog) moves initial focus
to a specific element; otherwise the browser gives it to the first tabbable
element.

**Persistent — must be resolved with a button**

```vue
<template>
	<div
		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
	>
		<div>
			<p class="m-0 text-sm font-medium">Finish setting up</p>
			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
				Add your company so invoices and invites look right.
			</p>
		</div>
		<div>
			<BbButton variant="outline" @click="open = true">Finish setup</BbButton>
		</div>
	</div>
	<BbDialog
		v-model="open"
		focus-target="input"
		hide-close
		persistent
		title="Complete your profile"
		@show="reset"
	>
		<div class="grid gap-3">
			<BbTextInput
				v-model="displayName"
				compact
				label="Display name"
				placeholder="Ada Lovelace"
			/>
			<BbTextInput
				v-model="company"
				compact
				label="Company"
				placeholder="Acme Inc."
			/>
		</div>
		<template #footer>
			<div class="flex justify-end gap-2">
				<!-- Keep a visible way out — never trap the user. -->
				<BbButton variant="ghost" @click="open = false">Skip</BbButton>
				<BbButton :disabled="!company.trim()" variant="primary" @click="save">
					Save
				</BbButton>
			</div>
		</template>
	</BbDialog>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbDialog, BbTextInput } from 'bitboss-ui';

const open = ref(false);
const displayName = ref('');
const company = ref('');

// Re-seed on `@show` so a dismissed step reopens clean.
const reset = () => {
	displayName.value = '';
	company.value = '';
};

const save = () => {
	// Persist the profile here, then close.
	open.value = false;
};
</script>
```

The busy case in practice: while a save is in flight, `disabled` denies
backdrop and `Escape`, but it does **not** touch the dialog's content — pair
it with `:disabled` on your inputs and Cancel. Return the promise from the
primary button's `@click` and `BbButton` shows its loading state
automatically; close only once the work resolves:

**Async save — dismissal denied while in flight**

```vue
<template>
	<div
		class="flex w-full max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-4"
	>
		<div class="min-w-0">
			<p class="m-0 truncate text-sm font-medium">{{ projectName }}</p>
			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
				Project · private
			</p>
		</div>
		<BbButton
			prepend:icon="lucide:pencil"
			variant="outline"
			@click="open = true"
		>
			Rename project
		</BbButton>
	</div>
	<BbDialog
		v-model="open"
		:disabled="saving"
		title="Rename project"
		@show="seed"
	>
		<div class="grid gap-3">
			<BbTextInput
				v-model="draft"
				compact
				:disabled="saving"
				label="Project name"
				placeholder="acme-storefront"
			/>
		</div>
		<template #footer>
			<div class="flex justify-end gap-2">
				<!-- Disable your own actions too — `disabled` only guards dismissal. -->
				<BbButton :disabled="saving" variant="ghost" @click="open = false">
					Cancel
				</BbButton>
				<!-- Returning the promise lets BbButton run its own loading state. -->
				<BbButton :disabled="!draft.trim()" variant="primary" @click="save">
					Rename
				</BbButton>
			</div>
		</template>
	</BbDialog>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbDialog, BbTextInput } from 'bitboss-ui';

// The record being renamed — in a real app this comes from your store/API.
const projectName = ref('acme-storefront');

const open = ref(false);
const draft = ref('');
const saving = ref(false);

// Re-seed on `@show` so a dismissed rename never resurfaces half-typed.
const seed = () => {
	draft.value = projectName.value;
	saving.value = false;
};

const save = async () => {
	saving.value = true;
	try {
		// Simulated request — replace with your API call.
		await new Promise((resolve) => setTimeout(resolve, 600));
		projectName.value = draft.value.trim();
		// Work first, then close: the transition runs while your UI refreshes.
		open.value = false;
	} finally {
		saving.value = false;
	}
};
</script>
```

### Stacked dialogs (drill-in flows)

Dialogs sharing a `stack` name **replace** one another: only the most recently
opened member is visible, the ones beneath are hidden until it closes — the
stack reads as a single surface whose content swaps as you drill in. Dialogs
with different names (or none) are independent and simply layer by open order.
Use a stack for a two-step flow that should not read as two boxes piling up.

**Drill into advanced options**

```vue
<template>
	<div
		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
	>
		<div>
			<p class="m-0 text-sm font-medium">Workspace settings</p>
			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
				Storage, backups, retention
			</p>
		</div>
		<div>
			<BbButton variant="outline" @click="first = true">
				Storage settings
			</BbButton>
		</div>
	</div>
	<BbDialog v-model="first" stack="settings" title="Storage">
		<div class="grid gap-3">
			<BbSwitch v-model="autoBackup" label="Automatic backups" />
			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
				Nightly snapshots keep the last 30 days of changes.
			</p>
			<BbButton
				append:icon="lucide:chevron-right"
				variant="outline"
				@click="second = true"
			>
				Advanced retention…
			</BbButton>
		</div>
	</BbDialog>
	<BbDialog v-model="second" stack="settings" title="Advanced retention">
		<div class="grid gap-3">
			<BbSwitch v-model="keepForever" label="Keep monthly snapshots" />
			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
				Monthly snapshots stay available for 12 months after creation.
			</p>
		</div>
		<template #footer>
			<div class="flex justify-end">
				<BbButton variant="primary" @click="second = false">Done</BbButton>
			</div>
		</template>
	</BbDialog>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbDialog, BbSwitch } from 'bitboss-ui';

// Two dialogs sharing a `stack` name swap in place as you drill in.
const first = ref(false);
const second = ref(false);

const autoBackup = ref(true);
const keepForever = ref(false);
</script>
```

### Top layer: what's above, what's inert

The dialog is a native `<dialog>` opened with `showModal()`. That has concrete
consequences an agent should design around:

- It renders in the browser **top layer** — above every `z-index`, sticky
  header, or transformed ancestor. There is nothing to z-index-manage.
- The element stays where you declared it in the DOM (no teleport), so scoped
  styles and provide/inject work normally; in tests, query the panel via
  `document.body` (e.g. `.bb-dialog--open`) after `attachTo: document.body`.
- Everything outside the dialog is **inert** while it is open: no hover, click,
  or tab reaches the page behind.
- Later top-layer surfaces paint above earlier ones: a `BbPopover`, `BbSelect`,
  `BbTooltip` or nested `BbDialog`/`BbConfirm` opened from inside a dialog
  appears above it and works — no special wiring. `BbToast` regions re-home
  themselves into the open modal so toasts fired from a dialog stay clickable.

Nested overlays are fine in moderation (a select, a confirm on top of a form
dialog). A second full dialog on top of another usually means the flow wants a
`stack` (above) or a page of its own.

### Navigating from a dialog

When a dialog's action leads somewhere, let the button navigate — never wire a
click handler to `router.push` or `window.location`. `BbButton` accepts `href`
(or an Inertia visit) and `to` (a vue-router target), so the action stays a real
link.

**Upgrade prompt whose primary action navigates**

```vue
<template>
	<div
		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
	>
		<div>
			<p class="m-0 text-sm font-medium">Projects</p>
			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
				Free plan · {{ used }} of {{ limit }} used
			</p>
		</div>
		<div>
			<BbButton
				prepend:icon="lucide:plus"
				variant="outline"
				@click="open = true"
			>
				New project
			</BbButton>
		</div>
	</div>
	<BbDialog v-model="open" title="Project limit reached">
		<div class="grid gap-3">
			<p class="m-0 text-sm">
				The <strong>Free</strong> plan includes {{ limit }} projects and you're
				using all of them. Upgrade to <strong>Pro</strong> for unlimited
				projects and priority support.
			</p>
			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
				Billing starts when you confirm — you can cancel anytime.
			</p>
		</div>
		<template #footer>
			<div class="flex justify-end gap-2">
				<BbButton variant="ghost" @click="open = false">Maybe later</BbButton>
				<!-- A navigating action is a real link — never `@click` + router.push. -->
				<BbButton
					append:icon="lucide:arrow-right"
					href="#settings-billing"
					variant="primary"
				>
					Upgrade to Pro
				</BbButton>
			</div>
		</template>
	</BbDialog>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbDialog } from 'bitboss-ui';

const used = 3;
const limit = 3;
const open = ref(false);
</script>
```

On Nuxt or Inertia the same button carries a platform-native navigation:

```vue
<!-- Inertia: href becomes an Inertia visit -->
<BbButton href="/settings/billing" method="get">Upgrade to Pro</BbButton>

<!-- Nuxt / vue-router: navigate with `to` -->
<BbButton :to="{ name: 'settings-billing' }">Upgrade to Pro</BbButton>
```

Because a modal dialog is client-side UI, SSR (Nuxt) renders it closed and
empty; content appears on first open (or immediately with `eager`).

### Adaptive: a bottom sheet on mobile

By default (`config.adaptive`, `true` out of the box) a dialog opened on a small
viewport (below `config.mobileMaxWidth`, 768px) renders as a `BbOffCanvas`
bottom sheet instead of a centered modal — better ergonomics for thumbs. The
surface is **latched when the dialog opens** and stays fixed for that session,
so a mid-flow resize never swaps modal ↔ sheet.

- The sheet defaults to a bottom, draggable, content-sized drawer
  (`direction: 'bottom'`, `draggable: true`, `size: 'auto'`); the dialog's
  `size` is intentionally **not** forwarded (width and drawer extent mean
  different things).
- `title`, `persistent`, `disabled`, `hide-close`, `focus-target`, `eager`,
  `fullscreen`, `stack` and `transition-duration` carry over; the four
  lifecycle events fire the same either way.
- `off-canvas-props` merges last over the sheet's props — use it to change
  direction, size, `stack-gap`, or disable dragging on the mobile surface only.
- `:adaptive="false"` keeps the centered dialog everywhere; a bare `adaptive`
  forces the sheet behavior on regardless of the global config.

Leave `adaptive` unset unless the project asks otherwise — the tri-state
default falls back to `config.adaptive`.

### Works well with

- `BbConfirm` + `useConfirm` — a destructive action inside your dialog should
  raise a confirm on top, not a second hand-built dialog.
- `BbToast` + `useToast` — fire the success toast right before closing; it
  stays interactive above the modal.
- `BbSelect`, `BbDatePicker`-style poppers inside the body: they open in the
  top layer above the dialog with no extra wiring.
- `BbOffCanvas` — the same content as a side panel when it is supplementary
  rather than blocking; the shared API keeps the swap cheap.

### Gotchas & anti-patterns

- **Don't rely on the close (x) button respecting `persistent`** — it doesn't;
  hide it (`hide-close`) when the dialog must be resolved explicitly.
- **Don't build a yes/no dialog** — that's `BbConfirm` with `useConfirm`.
- **Don't wire `@click` + `router.push`** for a navigating action — pass
  `href`/`to` to the button.
- **Don't toggle `v-model` from `@hide`/`@hidden` handlers** to "cancel" a
  close — use `persistent` instead; the close paths already guard correctly.
- **Don't leave the `header` slot without a close control** — it replaces the
  default ×, so you must render your own wired to `close`.
- **Don't query dialog content before it has opened** unless you set `eager` —
  the body renders lazily.
- A dialog is not a router surface: if the task grows tabs, lists and
  sub-navigation, it wants a page (or an `BbOffCanvas` detail panel), not a
  bigger modal.

### Accessibility

- Prefer passing `title` — it labels the dialog via `aria-labelledby`. If you
  omit it (no header) you own the accessible name: label a heading in the body
  and wire it yourself.
- The dialog is a true modal (`showModal()`): the browser contains focus within
  it, the page behind is inert, and focus returns to the trigger when it
  closes. `focus-target` only chooses where focus **starts**.
- The header close button carries a localized `aria-label` out of the box
  (`config.locale`).
- Don't lean on `persistent` to trap users. Keep a visible way out (a Cancel or
  Close button) even when backdrop/`Escape` dismissal is disabled.

## v-model

- `v-model` — type: `boolean \| undefined`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | Adapt the surface to the viewport: render as a `BbOffCanvas` drawer on mobile instead of a centered dialog. The surface is resolved when the dialog opens and stays fixed for that session: resizing across the mobile breakpoint while open nev… |
| `disabled` | `boolean \| undefined` | `false` |  | Disable EVERY user-initiated dismissal: backdrop click, Escape AND the header close (×) button (denied attempts play the deny nudge). Use it while an operation is in flight (e.g. a save) so the dialog cannot be dismissed mid-work. Compare `… |
| `eager` | `boolean \| undefined` | `false` |  | Render dialog content immediately instead of waiting for the first open. |
| `focusTarget` | `string \| undefined` |  |  | CSS selector of the element to focus after opening. Defaults to the first tabbable element. |
| `fullscreen` | `boolean \| "mobile" \| undefined` |  |  | Display the dialog fullscreen. Use `'mobile'` to restrict fullscreen to small devices. |
| `hideClose` | `boolean \| undefined` | `false` |  | Hide the default close (×) button. The button is shown by default; set this to remove it (e.g. for a `persistent` dialog you don't want dismissible — the × otherwise still closes a persistent dialog). |
| `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to open / close the dialog. A dialog with no `v-model` starts closed. |
| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Overrides merged over the offcanvas (mobile) surface's props. The drawer defaults to a bottom, draggable, content-sized sheet (`side: 'bottom'`, `draggable: true`, `size: 'auto'`); use this to override those, set other drawer-only options (… |
| `persistent` | `boolean \| undefined` | `false` |  | Prevent closing via outside clicks or Escape key. The header close (×) button STILL closes a persistent dialog — that is the documented escape hatch; combine with `hideClose` to remove it, or use `disabled` to block every dismissal. Program… |
| `size` | `Responsive<NonNullable<number \| ({ size?: any; } & string) \| keyof Sizes \| undefined>> \| undefined` | `"sm"` |  | Controls the maximum width of the dialog. Accepts named presets from `'xs'` to `'2xl'`, a custom CSS width string, or a numeric pixel value — or a per-breakpoint map (e.g. `{ default: 'sm', lg: 'lg' }`) to switch width responsively. |
| `stack` | `string \| undefined` |  |  | Name of the stack this dialog belongs to. Dialogs sharing the same `stack` value replace one another: only the most recently opened stays visible while the others in the stack are hidden beneath it. Dialogs in different stacks — or with no … |
| `title` | `string \| undefined` |  |  | Title text announced to assistive technologies. If omitted, no header is rendered (unless a `header` slot is supplied) and accessibility must be handled manually. |
| `transitionDuration` | `number \| undefined` | `250` |  | Controls the duration of the open and close animations. |

## Events

- `hidden` — `(event: "hidden"): void`
- `hide` — `(event: "hide"): void`
- `show` — `(event: "show"): void`
- `shown` — `(event: "shown"): void`
- `update:modelValue` — `(event: "update:modelValue", value: boolean): void`

## Slots

- `default` — scope: `BbDialogDefaultSlotProps` — Primary body content of the dialog, rendered in the scrollable body area.
- `footer` — scope: `object` — Content rendered in the dialog footer, below the body area. Typically used for action buttons.
- `header` — scope: `BbDialogHeaderSlotProps` — Replaces the entire dialog header section (title + close button) on both surfaces — the desktop `<dialog>` and the mobile off-canvas. Because it replaces the default close (✕), the slot owns closing: render your own control wired to the `cl…
- `title` — scope: `BbDialogTitleSlotProps` — Replaces the default title text inside the header. Remains linked to the dialog through `aria-labelledby`. Providing this slot renders the header even when `title` is unset — a slotted title is a title.

## See Also

- [BbOffCanvas](./BbOffCanvas.md) — Shows side-panel overlay content outside normal layout flow.
- [BbConfirm](./BbConfirm.md) — Prompts users to confirm or cancel critical actions (includes co-located BbConfirmPortal export).
- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements.

---

<!-- dist/ai/BbDropdown.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbDropdown.md -->

# BbDropdown

## Agent Contract

- Safety level: **Consumer API**
- Group: **Overlay**
- Description: Displays contextual action menus and menu content (includes the co-located BbDropdownGroup export, which is how a selectable group is bound).
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbDropdown.md](./source/BbDropdown.md)

## Usage & Guidelines

### When to use

Reach for `BbDropdown` to collect **actions** (and navigation) behind a single
trigger: an overflow "…" menu on a row, an account menu, a context menu. You
describe the menu declaratively through `items` and spread the `activator`
slot's `props` onto your own trigger (or attach the menu with the
`v-bb-dropdown` directive — see below).

Pick a sibling instead when:

- the menu has **one obvious primary action** plus a few alternates → use
  [BbDropdownButton](./BbDropdownButton.md) (a split button).
- the user is **choosing a value for a field** (searchable, form-bound) → use
  [BbSelect](./BbSelect.md), not a menu.
- the action is **destructive and needs confirmation** → trigger it, then gate
  with [useConfirm](./composables/useConfirm.md).

Everything is driven by data: never rebuild rows, dividers, checks, or keyboard
handling in markup — hand `BbDropdown` an `items` array.

### The items grammar

An `items` entry is one of three shapes, and you can mix them freely:

- a **menu item** — an object with a `key` and a `text`;
- a **separator section** — a nested `[ … ]` array, rendered as its own
  divider-separated anonymous group;
- a **group object** — `{ key, label?, items, selectable?, … }`, a titled and/or
  selectable section (next sections). A group's heading is `label` (not `text`);
  add `hideLabel` to keep the `label` for the adaptive sheet title / chips /
  `useBbDropdownContext` while rendering no heading in the menu.

Each item extends `BbBaseButton`'s prop surface, so an item is an action, a
link, or a submenu opener depending on which fields it carries:

- `key` (required) — stable identity; also the selection token in selectable
  groups and the base name for per-item slots.
- `text` — the label; `description` adds a muted second line (the row grows,
  icons stay aligned with the title line).
- `onClick` — makes it an **action**. Never navigate from here.
- `href` (anchor / Inertia visit, with `method`/`data`) or `to` (vue-router) —
  makes it a **navigation link**; the dropdown renders an `<a>` / router link,
  and any other BbBaseButton nav prop (`target`, active-class props) passes
  through.
- `items` — makes it a **submenu opener** (see Nested submenus).
- `prepend:icon` / `append:icon` — leading/trailing icons. The trailing icon is
  ignored when the row shows a submenu chevron or a selection check.
- `variant` — visual tone. Only `destructive` is styled out of the box; the
  `dropdownItemVariants` plugin option registers more typed names, each
  rendering a `bb-dropdown__item--variant-<name>` class hook you style yourself.
- `disabled` — non-interactive row, skipped by keyboard navigation.

Note how the destructive item below follows the design rule end to end: its
`onClick` awaits [useConfirm](./composables/useConfirm.md) and acts only on a
yes (the `<BbConfirm>` host mounts once per app, e.g. in the root layout).

**A mixed action menu**

```vue
<template>
	<div
		class="flex max-w-sm items-center gap-2 rounded-[var(--bb-radius)] border p-2"
	>
		<div
			aria-hidden="true"
			class="flex size-8 shrink-0 items-center justify-center rounded-[var(--bb-radius-sm)] bg-[color:var(--bb-muted)] text-[color:var(--bb-text-muted)]"
		>
			<span class="text-xs font-medium">PDF</span>
		</div>
		<div class="min-w-0 flex-1">
			<p class="truncate text-sm font-medium">Q3-report.pdf</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				248 KB · <span data-last>{{ last }}</span>
			</p>
		</div>
		<BbDropdown :items="items" placement="bottom-end">
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="File actions"
					icon="lucide:ellipsis"
					size="xs"
					variant="ghost"
				/>
			</template>
		</BbDropdown>

		<!--
			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
			mount none. See ai/guides/agent-contract.md § Global Host Rule.
		-->
		<BbConfirm />
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbConfirm, BbDropdown, useConfirm } from 'bitboss-ui';
import type { BbDropdownItem } from 'bitboss-ui';

const last = ref('No action yet');
const { confirm } = useConfirm();

const items: BbDropdownItem[] = [
	// Plain leaf actions carry an `onClick`.
	{
		key: 'rename',
		text: 'Rename',
		'prepend:icon': 'lucide:pencil',
		onClick: () => (last.value = 'Renamed'),
	},
	{
		key: 'duplicate',
		text: 'Duplicate',
		'prepend:icon': 'lucide:copy',
		onClick: () => (last.value = 'Duplicated'),
	},
	// A navigation item: the dropdown renders an <a>. Never wire navigation
	// through onClick — pass href (or `to` in a router app) instead.
	{
		key: 'preview',
		text: 'Open preview',
		'prepend:icon': 'lucide:external-link',
		href: '#preview',
		target: '_blank',
	},
	// A nested array becomes its own divider-separated section. A destructive
	// item never acts directly: its onClick awaits useConfirm and only
	// proceeds on a yes.
	[
		{
			key: 'delete',
			text: 'Delete file',
			description: 'This cannot be undone',
			'prepend:icon': 'lucide:trash-2',
			variant: 'destructive',
			onClick: async () => {
				const ok = await confirm({
					title: 'Delete "Q3-report.pdf"?',
					text: 'The file will be removed for everyone in the workspace.',
					variant: 'destructive',
					yes: { text: 'Delete file', 'prepend:icon': 'lucide:trash-2' },
					no: 'Keep file',
				});
				if (ok) last.value = 'Deleted';
			},
		},
	],
];
</script>
```

In a Nuxt or Inertia app, the same items navigate through the platform — pass
`to` for a router route, or `href` with an Inertia `method`/`data`:

```vue
<script setup lang="ts">
import type { BbDropdownItem } from 'bitboss-ui';

const items: BbDropdownItem[] = [
	// Nuxt / vue-router route
	{ key: 'settings', text: 'Settings', to: { name: 'settings' } },
	// Inertia visit
	{ key: 'logout', text: 'Log out', href: '/logout', method: 'post' },
];
</script>
```

### Async actions and the loading flag

Clicking a plain action closes the menu immediately and returns focus to the
trigger (unless the action moved focus elsewhere, e.g. opened a dialog). When
the `onClick` returns a promise, the dropdown keeps tracking it after the menu
has closed: the `activator` slot's `loading` flag stays `true` until it
settles, and re-clicks on that item are ignored while it's in flight. Reflect
`loading` on your trigger and you get a busy state for free. Inside a
selectable group the menu stays open instead, and the row itself carries
`aria-busy` while its handler runs.

**Background sync with a busy trigger**

```vue
<template>
	<div
		class="flex max-w-sm items-center gap-2 rounded-[var(--bb-radius)] border p-2"
	>
		<div class="min-w-0 flex-1">
			<p class="truncate text-sm font-medium">bitboss/storefront</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]" data-sync>
				{{ status }}
			</p>
		</div>
		<!-- `adaptive` is pinned off so the demo behaves identically on any
		viewport; leave it at the project default in real apps. -->
		<BbDropdown :adaptive="false" :items="items">
			<template #activator="{ props, loading }">
				<!-- The slot's `loading` flag is true while any item's async
				`onClick` is in flight — even after the menu has closed. -->
				<BbButton
					v-bind="props"
					append:icon="lucide:chevron-down"
					:loading="loading"
					size="xs"
					variant="outline"
				>
					Sync
				</BbButton>
			</template>
		</BbDropdown>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbDropdown } from 'bitboss-ui';
import type { BbDropdownItem } from 'bitboss-ui';

const status = ref('Idle');

// A plain action closes the menu the moment it's clicked; when its `onClick`
// returns a promise the dropdown keeps tracking it until it settles, so the
// activator can stay busy while the work runs in the background.
const items: BbDropdownItem[] = [
	{
		key: 'sync',
		text: 'Sync now',
		'prepend:icon': 'lucide:refresh-cw',
		onClick: async () => {
			status.value = 'Syncing…';
			await new Promise((resolve) => setTimeout(resolve, 400));
			status.value = 'Synced';
		},
	},
	{
		key: 'history',
		text: 'View sync history',
		'prepend:icon': 'lucide:history',
		href: '#history',
	},
];
</script>
```

### Nested submenus

Give an item its own `items` array and it opens a submenu — recursively, to any
depth. A chevron is shown automatically (it replaces any `append:icon`). On
desktop, submenus are hover-intent flyouts (opening waits for the parent
panel's transition; leaving tolerates a short diagonal move); clicking a parent
row opens its submenu and never closes the menu. On the mobile sheet the same
items **drill down** one level at a time with a back control instead. Use
submenus to group rarely-used options without crowding the top level; keep the
nesting shallow (two levels is plenty).

**Submenus to any depth**

```vue
<template>
	<div
		class="flex max-w-xs items-center justify-between gap-2 rounded-[var(--bb-radius)] border p-2"
	>
		<span class="text-sm font-medium">Acme Studio</span>
		<BbDropdown :items="items" placement="bottom-end">
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Account menu"
					class="gap-1.5"
					size="sm"
					variant="ghost"
				>
					<BbAvatar size="28">SE</BbAvatar>
					<span class="hidden sm:inline">Sofia</span>
				</BbButton>
			</template>
		</BbDropdown>
	</div>
</template>
<script setup lang="ts">
import { BbAvatar, BbButton, BbDropdown } from 'bitboss-ui';
import type { BbDropdownItem } from 'bitboss-ui';

// An item with its own `items` opens a submenu. Submenus nest to any depth —
// a chevron replaces the item's own `append:icon`.
const items: BbDropdownItem[] = [
	{
		key: 'account',
		text: 'Account',
		'prepend:icon': 'lucide:user',
		items: [
			{ key: 'profile', text: 'View profile', href: '#profile' },
			{ key: 'billing', text: 'Billing & plans', href: '#billing' },
			{
				key: 'security',
				text: 'Security',
				items: [
					{ key: '2fa', text: 'Two-factor auth', href: '#2fa' },
					{ key: 'sessions', text: 'Active sessions', href: '#sessions' },
				],
			},
		],
	},
	{
		key: 'help',
		text: 'Help & support',
		'prepend:icon': 'lucide:life-buoy',
		href: '#help',
	},
	[
		{
			key: 'signout',
			text: 'Sign out',
			'prepend:icon': 'lucide:log-out',
			href: '#signout',
		},
	],
];
</script>
```

### Selectable groups

Turn a group into a chooser by marking it `selectable` (single choice, radio
semantics) or `selectable` + `multiple` (many choices, checkbox semantics).
Selected rows render a check on the right (replacing any `append:icon`).
Behavior you can rely on:

- a **single** selection re-clicked clears itself; when the group is the sole
  top-level selectable group, picking a value also closes the menu;
- a **multiple** group keeps the menu open while you toggle;
- the dropdown emits `item:selected` / `item:unselected` with the changed item's
  **value** (its `item-value` for pipeline groups, else its `key`) whenever any
  selectable group changes — the same value shape `BbTable` emits.

Selection state lives on the dropdown; a companion `<BbDropdownGroup>` in the
default slot binds to it. The companion is intentionally minimal — it takes
only the group's `id` (which must match the group's `key` in `items`) and a
`v-model`; the options themselves stay declared in the host's `items`. Its
`v-model` seeds the initial selection before the menu ever opens, and it emits
the same `item:selected` / `item:unselected` pair. Two hard rules, enforced
with thrown errors: a `multiple` group's model must be an array, and the `id`
must point at a _group_ (not a plain item, not a missing key).

**Radio and checkbox groups**

```vue
<template>
	<div
		class="flex max-w-md flex-wrap items-center gap-2 rounded-[var(--bb-radius)] border p-2"
	>
		<span class="pr-1 text-xs font-medium text-[color:var(--bb-text-muted)]"
			>Invoices</span
		>
		<BbDropdown :adaptive="false" :items="items" :width="200">
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					append:icon="lucide:chevron-down"
					size="xs"
					variant="outline"
				>
					View
				</BbButton>
			</template>
			<!-- Companions bind to a group by `id`; the group itself is declared
			in `items`. They only need an `id` and a `v-model`. -->
			<BbDropdownGroup id="sort" v-model="sortBy" />
			<BbDropdownGroup id="tags" v-model="tags" />
		</BbDropdown>
		<span class="text-xs text-[color:var(--bb-text-muted)]">
			Sort: <span data-sort>{{ sortBy }}</span> · Tags:
			<span data-tags>{{ tags.join(', ') || 'none' }}</span>
		</span>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbDropdown, BbDropdownGroup } from 'bitboss-ui';
import type { BbDropdownItem } from 'bitboss-ui';

// `selectable` → single choice (radio semantics, closes on pick).
// `multiple` → many choices (checkbox semantics, stays open while toggling).
const items: BbDropdownItem[] = [
	{
		key: 'sort',
		label: 'Sort by',
		selectable: true,
		items: [
			{ key: 'recent', text: 'Most recent' },
			{ key: 'name', text: 'Name (A–Z)' },
			{ key: 'amount', text: 'Amount (high → low)' },
		],
	},
	{
		key: 'tags',
		label: 'Tags',
		selectable: true,
		multiple: true,
		items: [
			{ key: 'overdue', text: 'Overdue' },
			{ key: 'vip', text: 'VIP' },
			{ key: 'review', text: 'Needs review' },
		],
	},
];

const sortBy = ref('recent');
const tags = ref<string[]>(['overdue']);
</script>
```

### Loading options on demand

For options that come from an API, make the group a **pipeline group**: pass an
(async) getter as `items` and an `item-text` / `item-value` pair. This mirrors
`BbSelect`'s fetch model, so the same data source drops into either component.
The full grammar:

- `items: (prefill, modelValue) => raw[] | Promise<raw[]>` — called lazily on
  the menu's **first open**, never on mount, and again whenever `dependencies`
  change. `modelValue` is the group's current selection. A plain raw array also
  works when you just need the mapping.
  On a **`searchable`** group the signature gains a leading query argument —
  `(query, prefill, modelValue)`, identical to `BbSelect`'s — which is why the
  same provider drops into both.
- `itemText` / `itemValue` — a path string or getter producing each raw item's
  label and value. `v-model` on the companion surfaces the selected value(s);
  internally the selection key is a hash of the value. BbBaseButton props on the
  raw items (`href`, `disabled`, icons, `variant`, `onClick`, …) pass through
  to the rendered rows.
- `max` — caps a multiple selection; once reached, unselected rows render
  disabled.
- `loadingText` / `noDataText` — placeholder row text per group; the
  dropdown-level `loading-text` / `no-data-text` props set the default for all
  groups, and the `#loading` / `#no-data` slots (payload: `{ text, groupKey }`)
  replace the placeholder rows entirely.
- `dependencies: [...]` + `depsDebounceTime` — re-run the getter (debounced)
  when any dependency changes, e.g. a search field feeding the fetch.
- `enforceCoherence` — after a re-fetch, drop selected values that no longer
  exist in the items (and update `v-model`). Settable per group or as a
  dropdown-level default.

**Async assignee picker**

```vue
<template>
	<div
		class="flex max-w-sm flex-wrap items-center gap-2 rounded-[var(--bb-radius)] border p-2"
	>
		<div class="min-w-0 flex-1">
			<p class="truncate text-sm font-medium">INV-2048 · Northwind</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Assignees ·
				<span data-count>{{ assignees.length }} selected</span>
			</p>
		</div>
		<BbDropdown :items="items" loading-text="Loading team…" :width="240">
			<template #activator="{ props, loading }">
				<BbButton
					v-bind="props"
					append:icon="lucide:chevron-down"
					:loading="loading"
					size="xs"
					variant="outline"
				>
					Assign
				</BbButton>
			</template>
			<BbDropdownGroup id="assignees" v-model="assignees" />
		</BbDropdown>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbDropdown, BbDropdownGroup } from 'bitboss-ui';
import type { BbDropdownItem } from 'bitboss-ui';

type Member = { id: string; name: string };

const team: Member[] = [
	{ id: 'u1', name: 'Sofia Esposito' },
	{ id: 'u2', name: 'Marco Bianchi' },
	{ id: 'u3', name: 'Aisha Khan' },
	{ id: 'u4', name: 'Leo Rossi' },
];

// A pipeline group: `items` is an async getter resolved through
// `itemText` / `itemValue`. It runs lazily on the menu's first open, never on
// mount, and again whenever `dependencies` change. `v-model` surfaces the
// selected `itemValue`s. Signature matches the non-query provider shape
// (prefill is always `true` here — menus have no search field).
const items: BbDropdownItem[] = [
	{
		key: 'assignees',
		label: 'Assign to',
		selectable: true,
		multiple: true,
		max: 3,
		itemText: 'name',
		itemValue: 'id',
		items: async (_prefill: boolean, _modelValue?: string[]) => {
			await new Promise((resolve) => setTimeout(resolve, 400));
			return team;
		},
	},
];

const assignees = ref<string[]>([]);
</script>
```

Tie a pipeline group to other state with `dependencies`: when any entry
changes, the getter re-runs (debounced by `depsDebounceTime`), and with
`enforceCoherence` any pick missing from the fresh items is dropped from the
selection and the companion's `v-model`. Because `dependencies` lives inside
the group's config, declare the `items` array as a `computed` so it
re-evaluates when the source state changes. Coherence stays lazy — a group
that was never opened never fetches, and never prunes; pruning also never
runs against an empty or still-loading item set, so a slow refetch can't wipe
a valid selection.

**Dependent options that stay coherent**

```vue
<template>
	<div
		class="flex max-w-md flex-wrap items-center gap-2 rounded-[var(--bb-radius)] border p-2"
	>
		<span class="pr-1 text-xs font-medium text-[color:var(--bb-text-muted)]"
			>Board</span
		>
		<BbDropdown
			:adaptive="false"
			:items="menu"
			loading-text="Loading members…"
			:width="200"
		>
			<template #activator="{ props, loading }">
				<BbButton
					v-bind="props"
					append:icon="lucide:list-filter"
					:loading="loading"
					size="xs"
					variant="outline"
				>
					Filter
				</BbButton>
			</template>
			<BbDropdownGroup id="board" v-model="board" />
			<BbDropdownGroup id="assignees" v-model="assignees" />
		</BbDropdown>
		<span class="text-xs text-[color:var(--bb-text-muted)]">
			<span data-board>{{ board ?? 'all boards' }}</span> ·
			<span data-assignees>{{ assigneeNames || 'anyone' }}</span>
		</span>
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbButton, BbDropdown, BbDropdownGroup } from 'bitboss-ui';
import type { BbDropdownItem } from 'bitboss-ui';

type Member = { id: string; name: string; boards: string[] };

const members: Member[] = [
	{ id: 'u1', name: 'Sofia Esposito', boards: ['website'] },
	{ id: 'u2', name: 'Marco Bianchi', boards: ['website', 'mobile-app'] },
	{ id: 'u3', name: 'Aisha Khan', boards: ['mobile-app'] },
	{ id: 'u4', name: 'Leo Rossi', boards: ['mobile-app'] },
];

const board = ref<string | null>('website');
const assignees = ref<string[]>([]);

// Dropdown pipeline getter signature: `(prefill, modelValue)` — the non-query
// provider shape, shared with BbTable and the checkbox/radio/switch groups.
// `prefill` is `true` on every fetch (only a user-typed query reads `false`,
// and a menu has no search field); `modelValue` is the group's selection. Read
// anything else (the board) from your own refs.
const loadMembers = (
	_prefill: boolean,
	_modelValue?: string[]
): Promise<Member[]> =>
	new Promise((resolve) => {
		setTimeout(
			() =>
				resolve(
					members.filter((member) => member.boards.includes(board.value ?? ''))
				),
			300
		);
	});

// `items` is a computed so the assignee group's `dependencies` re-evaluates
// when the board changes — that change is what schedules the debounced
// refetch. `enforceCoherence` then drops picks missing from the fresh items.
const menu = computed<BbDropdownItem[]>(() => [
	{
		key: 'board',
		label: 'Board',
		selectable: true,
		items: [
			{ key: 'website', text: 'Website' },
			{ key: 'mobile-app', text: 'Mobile app' },
		],
	},
	{
		key: 'assignees',
		label: 'Assignee',
		selectable: true,
		multiple: true,
		itemText: 'name',
		itemValue: 'id',
		items: loadMembers,
		dependencies: [board.value],
		depsDebounceTime: 150,
		enforceCoherence: true,
	},
]);

const assigneeNames = computed(() =>
	members
		.filter((member) => assignees.value.includes(member.id))
		.map((member) => member.name.split(' ')[0])
		.join(', ')
);
</script>
```

### Searchable groups

A group can render **its own search field**, scoped to itself alone — the
nested "category › searchable options" pattern. Set `searchable` on the group,
not on the dropdown: there is no dropdown-level search, and each searchable
group owns an independent query.

```vue
<BbDropdown
	:items="[
		{
			id: 'assignee',
			label: 'Assignee',
			searchable: true,
			searchPlaceholder: 'Find a teammate…',
			selectable: true,
			multiple: true,
			stash: true,
			prefill: false,
			items: (query, prefill, modelValue) => api.users({ q: query }),
			itemText: 'name',
			itemValue: 'id',
		},
	]"
/>
```

What each knob does:

- **`searchable`** puts the field at the top of that group — inside its submenu
  when the group is nested. Typing narrows the group's rows by case-insensitive
  substring, and on an async group passes the query to the getter as the
  **leading** argument: `(query, prefill, modelValue)`, the same shape
  `BbSelect` uses, so one provider serves both.
- **`filterBy`** picks which raw fields the local substring match reads. Empty
  (the default) matches the resolved display text.
- **`searchPlaceholder`** overrides the field's placeholder; it defaults to the
  localized label.
- **`prefill: false`** means _search-first_ — nothing loads until the user
  types, and the group shows a hint row until then. It **requires**
  `searchable`, which is the one place the three-state `prefill` differs from a
  plain menu group (`'interaction'`, the default, fetches when the group is
  first reached; `true` fetches on mount).
- **`stash`** accumulates the items behind _selected_ keys so they stay
  resolvable after the query changes. Without it, selecting in one search and
  then searching for something else leaves the earlier selection unresolvable
  and breaks the `v-model` round-trip. **Recommended for every `multiple`
  searchable group.**
- **`maxHeight`** defaults to `280` (≈ 10 rows) on a searchable group, because a
  searched list should scroll rather than grow. Non-searchable groups are
  uncapped unless you set it.

Two knobs live on the **dropdown**, not the group, because they apply to every
searchable group in the menu:

- **`queryDebounceTime`** (default `300`) debounces the async re-fetch a
  searchable group fires as the user types. Distinct from the per-group
  `depsDebounceTime`, which debounces refetches caused by `dependencies`
  changing.
- **`compact`** tightens the rows, search field included.

A searchable surface is a `role="dialog"`, not a `menu` — see Accessibility.

### Reading a dropdown from anywhere: `useBbDropdownContext`

Give the dropdown an explicit `id` and any component — no shared parent needed —
can read its live state. This is how you render **filter chips outside the menu
without a second fetch**: the dropdown already resolved each pick's label when
the user chose it, so the context hands it back.

```ts
const { isReady, open, groups } = useBbDropdownContext('invoice-filters');
```

- `isReady` — a dropdown with that id is mounted.
- `open` — the panel/sheet is open.
- `groups` — one entry per **selectable** group, keyed by group key.

Each entry is **the group exactly as you declared it, with live state on top**,
so a chip can be driven entirely from the group config:

| From your config                                                             | Added live                                                                      |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `key`, `label`, `hideLabel`, `max`, `filterBy`, `prepend:icon`, `variant`, … | `value` (the `v-model`), `selectedOptions`, `multiple`, `selectable`, `loading` |

`selectedOptions` is `{ value, text?, original? }[]`. `value` is always there;
`text`/`original` fill in once the owning group has the item — so use
`hideLabel` when a group's name is already shown by its parent category but you
still want a chip prefix.

Two rules worth knowing:

- **It is read-only.** To change a selection, write to that group's own
  `v-model` — the context never mutates.
- **It is lazy.** Reading never triggers a fetch, so a seeded value in a
  search-first group stays `{ value }` (no label) until that group loads. Set
  `prefill: true` on the group to resolve a seeded selection eagerly.

`items` is the one field not carried through: on a pipeline group it is a
fetcher, and a state snapshot must never invite a fetch. `selectedOptions` is
its resolved counterpart.

### Per-item and per-group slots

Every row (and every titled group header) can be customized without leaving
the config-driven model:

- `item:prepend` / `item:append` — generic edge slots rendered before/after
  **every** row's content, and inside group headers too (there the payload's
  `item` is the group descriptor).
- `#<key>` — a named slot for one specific entry, matched by its `key`
  (sanitized: non-alphanumeric runs become underscores, dashes are kept,
  lowercased — key `"Delete file"` → slot `#delete_file`, key `"delete-file"`
  → slot `#delete-file`). It replaces the entry's label
  region; `#<key>:prepend` / `#<key>:append` replace just its leading/trailing
  region. Per-key slots win over the generic ones, which win over
  `prepend:icon` / `append:icon`. In pipeline groups the slot name derives
  from the item's resolved `item-value` instead.

The payload is one-way: `{ item, index, text, description, selected, loading,
disabled, open, placement }`. There are no callbacks in it — clicks and
selection stay wired by the dropdown itself, so keep slot content
presentational. There is **no** generic `#item` slot; to restyle every row use
the edge slots, to replace one row's content use its key.

**Status dots and a per-row badge**

```vue
<template>
	<div
		class="flex max-w-xs items-center gap-2 rounded-[var(--bb-radius)] border p-2"
	>
		<span class="text-xs font-medium text-[color:var(--bb-text-muted)]"
			>Workspace</span
		>
		<!-- `adaptive` is pinned off so the demo behaves identically on any
		viewport; leave it at the project default in real apps. -->
		<BbDropdown :adaptive="false" :items="items">
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					append:icon="lucide:chevron-down"
					size="xs"
					variant="outline"
				>
					Acme Inc
				</BbButton>
			</template>

			<!-- Generic edge slot: rendered before EVERY row's content
			(and inside group headers). Payload is read-only. -->
			<template #item:prepend="{ item }">
				<BbIcon
					class="text-[color:var(--bb-text-muted)]"
					data-env-dot
					:icon="envIcon(item.key)"
					size="xs"
				/>
			</template>

			<!-- Per-key slot: replaces just this row's label region. The name is
			the item's `key` (sanitized: non-alphanumerics become underscores). -->
			<template #billing="{ text }">
				<span class="flex flex-1 items-center justify-between gap-2 text-left">
					{{ text }}
					<BbBadge variant="soft-amber">3 due</BbBadge>
				</span>
			</template>
		</BbDropdown>
	</div>
</template>
<script setup lang="ts">
import { BbBadge, BbButton, BbDropdown, BbIcon } from 'bitboss-ui';
import type { BbDropdownItem, IconType } from 'bitboss-ui';

const items: BbDropdownItem[] = [
	{ key: 'production', text: 'Production', href: '#production' },
	{ key: 'staging', text: 'Staging', href: '#staging' },
	[{ key: 'billing', text: 'Billing', href: '#billing' }],
];

/** Status glyph per workspace row — color inherits via currentColor. */
const envIcon = (key: string): IconType => {
	if (key === 'production') return 'lucide:circle-check';
	if (key === 'staging') return 'lucide:circle-dashed';
	return 'lucide:circle';
};
</script>

<!-- Non-scoped on purpose: styles the child badge's soft variant (scoped CSS
     can't reach it without :deep). Canonical palette:
     ai/guides/design-language.md § Using color. -->
<style>
.bb-badge.bb-badge--soft-amber {
	--accent: #d97706;
	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
	--border-width: 1px;
	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
}
</style>
```

### Header and footer

`header` and `footer` slots (payload: `{ open, disabled, placement }`) pin
content above and below the scrolling items, each separated by a divider. Use
the header for a title or a filter field and the footer for a persistent
action — they stay put while the list scrolls. On the mobile sheet they become
the sheet's pinned header and footer.

**Pinned header and footer**

```vue
<BbDropdown
	:items="[
		{ key: 'jan', text: 'January', href: '#jan' },
		{ key: 'feb', text: 'February', href: '#feb' },
		{ key: 'mar', text: 'March', href: '#mar' },
	]"
	:width="240"
>
	<template #activator="{ props }">
		<BbButton
			v-bind="props"
			append:icon="lucide:chevron-down"
			variant="outline"
		>
			Period
		</BbButton>
	</template>
	<template #header>
		<div class="px-3 py-2 text-xs font-semibold text-[color:var(--bb-text-muted)]">
			Jump to month
		</div>
	</template>
	<template #footer>
		<div class="p-2">
			<BbButton block href="#calendar" size="sm" variant="ghost">
				Open calendar
			</BbButton>
		</div>
	</template>
</BbDropdown>
```

### Right-click and cursor menus

Set `trigger` to `'contextMenu'` (or an array like `['click', 'contextMenu']`)
for an OS-style menu that opens on right-click — on touch devices the
equivalent is a **long-press** (about half a second, cancelled if the finger
drifts). Pair it with `placement="cursor"` to anchor the panel at the pointer
coordinates instead of the activator; right-clicking again while open moves
the menu to the new position. Everything else — items, selection, slots —
behaves exactly as with a click menu.

**Context menu at the cursor**

```vue
<template>
	<div
		class="flex max-w-sm items-center gap-2 rounded-[var(--bb-radius)] border p-2"
	>
		<div class="min-w-0 flex-1">
			<p class="truncate text-sm font-medium">INV-2048</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Northwind · €1,240.00 ·
				<span data-last>{{ last }}</span>
			</p>
		</div>
		<!-- `trigger: 'contextMenu'` opens on right-click / long-press;
		`placement: 'cursor'` anchors the panel at the pointer. -->
		<BbDropdown
			:items="items"
			placement="cursor"
			:trigger="['click', 'contextMenu']"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Invoice actions"
					icon="lucide:ellipsis"
					size="xs"
					variant="ghost"
				/>
			</template>
		</BbDropdown>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbDropdown } from 'bitboss-ui';
import type { BbDropdownItem } from 'bitboss-ui';

const last = ref('Right-click the row');

const items: BbDropdownItem[] = [
	{
		key: 'download',
		text: 'Download PDF',
		'prepend:icon': 'lucide:download',
		onClick: () => (last.value = 'Downloading'),
	},
	{
		key: 'share',
		text: 'Share link',
		'prepend:icon': 'lucide:link',
		href: '#share',
	},
	// A real delete would be `variant: 'destructive'` with an onClick that
	// awaits useConfirm — see the mixed action menu example.
	[
		{
			key: 'trash',
			text: 'Move to trash',
			'prepend:icon': 'lucide:trash-2',
			onClick: () => (last.value = 'Moved to trash'),
		},
	],
];
</script>
```

### Placement, width and boundaries

- `placement` (default `'bottom'`) accepts every floating-UI placement
  (`top`, `bottom-start`, `right-end`, …) plus `'cursor'`; the panel flips
  automatically when there's no room, and the item list caps its height to the
  available space (scrolling inside).
- `width` — `'auto'` (default) sizes to content with a 128px floor; a number
  is pixels; a percentage is relative to the **anchor's width**, so
  `width="100%"` makes the menu match its trigger.
- `anchor` — an element or component ref the panel positions against instead of
  the activator, for when the trigger is only part of a larger control: a split
  button whose right half opens a menu aligned to (and as wide as) the pair.
  `placement` and a percentage `width` both resolve against it. Ignored when
  `placement` is `'cursor'`.
- `offset` (gap from the anchor), `padding` (minimum space kept from the
  viewport edge), and `boundary` (an element, component ref, or CSS selector
  that confines the panel) tune positioning; `eager` pre-renders the panel
  before first open; `transitionDuration` controls the open/close animation.
- The menu closes itself on outside click/focus, on `Escape`, when another
  dropdown opens, and when the activator scrolls out of view. `disabled`
  freezes the whole component.

**Menu as wide as its trigger**

```vue
<BbDropdown
	placement="bottom-start"
	width="100%"
	:items="[
		{
			key: 'starter',
			text: 'Starter',
			description: 'For side projects',
			href: '#starter',
		},
		{ key: 'pro', text: 'Pro', description: 'For growing teams', href: '#pro' },
		{
			key: 'enterprise',
			text: 'Enterprise',
			description: 'Custom contracts',
			href: '#enterprise',
		},
	]"
>
	<template #activator="{ props }">
		<BbButton
			v-bind="props"
			append:icon="lucide:chevrons-up-down"
			block
			class="w-72"
			variant="outline"
		>
			Choose a plan
		</BbButton>
	</template>
</BbDropdown>
```

### The v-bb-dropdown directive

**Default to the directive.** When the menu is just an `items` array on a
trigger you already have, attach the `v-bb-dropdown` directive instead of
importing `BbDropdown` and wiring an activator — no import, no wrapper element.
It is registered globally while the plugin config's `injectDirectives` stays on
(the default; otherwise register it with `app.use(BbDropdownDirectivePlugin)`,
optionally passing a custom name). The value is either:

- an **items array** — used directly as the menu's items, or
- an **object of `BbDropdown` props** with a required `items` — e.g.
  `{ items, trigger: 'contextMenu', placement: 'cursor', width: 240 }`.

The directive argument is a placement shorthand (`v-bb-dropdown:bottom-end`)
and wins over a `placement` in the object. Trigger, ARIA and keyboard wiring
attach to the host element directly, so use it on a real focusable element.
Reach for the full component when you need `header`/`footer` slots, per-item
slots, or `<BbDropdownGroup>` companions — the directive can't express those.
(The component's `activator` prop offers the same "no wrapper" wiring when you
already hold an element or component ref: the activator slot is skipped and
listeners attach to the referenced element. ARIA — `aria-haspopup`,
`aria-expanded`, `aria-controls` — attaches programmatically to that element
too, the same as it would to the slot's `props`; don't hand-write your own
`aria-*` attributes on it, or you get a double-set conflict.)

**Menu on any element, no wrapper**

```vue
<BbButton
	v-bb-dropdown="[
		{ key: 'profile', text: 'View profile', href: '#profile' },
		{
			key: 'settings',
			text: 'Settings',
			'prepend:icon': 'lucide:settings',
			href: '#settings',
		},
		{
			key: 'signout',
			text: 'Sign out',
			variant: 'destructive',
			href: '#signout',
		},
	]"
	append:icon="lucide:chevron-down"
	variant="outline"
>
	Account
</BbButton>
```

### Density: `compact`

`compact` walks the same ladder `BbSelect` does, so a dense toolbar can hold a
select and a menu that agree: flyout rows go 28px → 24px, sheet rows 44px →
36px. The label does not shrink — density here is height, exactly as it is for a
select.

The sheet stops at 36px and never follows the flyout down to 24px. A menu row is
a touch target whose mis-tap fires the neighbouring **command**, where a
mis-tapped option merely picks the wrong value and can be picked again; 36px is
the same floor the select's own sheet holds.

**A compact menu beside a compact select**

```vue
<div class="flex items-center gap-2">
	<BbSelect
		v-model="state.owner"
		compact
		hide-label
		label="Owner"
		:items="['Ada', 'Grace', 'Alan']"
		placeholder="Owner"
	/>
	<BbButton
		v-bb-dropdown="{
			compact: true,
			items: [
				{ key: 'rename', text: 'Rename' },
				{ key: 'duplicate', text: 'Duplicate' },
			],
		}"
		size="sm"
		variant="outline"
	>
		Actions
	</BbButton>
</div>
```

### Mobile: the adaptive sheet

On viewports below the config's `mobileMaxWidth`, the menu renders as a
bottom-anchored, draggable, auto-sized off-canvas sheet instead of a flyout.
Nested submenus become drill-down levels with a back control (the parent
item's text becomes the level title); selection, slots and events behave
exactly as on desktop. The surface is **latched per open**: resizing
mid-session never swaps a live menu between flyout and sheet.

- The default comes from the global `config.adaptive` (`true`); the `adaptive`
  prop overrides it per component. Pin `:adaptive="false"` when a menu must
  stay a flyout everywhere — e.g. deterministic UI tests or dense desktop-only
  tooling.
- `offCanvasProps` forwards overrides to the underlying `BbOffCanvas` (merged
  over `direction: 'bottom'`, `size: 'auto'`, `draggable: true`); it is
  ignored when `adaptive` resolves to `false`.

### Works well with

- `BbDropdownButton` — the same `items` model behind a split button when one
  action dominates.
- [useConfirm](./composables/useConfirm.md) — a `variant: 'destructive'`
  item's `onClick` should `await confirm(...)` before acting.
- `BbTable` — a per-row overflow "…" menu (icon-only `BbButton` activator) or
  a `trigger="contextMenu"` menu on the row itself.
- `BbAvatar` in the activator for account menus; `BbBadge` in per-item slots
  for counts (see the slots example).
- [useToast](./composables/useToast.md) — fire a toast from an item's
  `onClick` once background work settles.

### Gotchas and anti-patterns

- **Don't navigate from `onClick`** (`router.push`, `window.location`) — give
  the item `href`/`to` and let it render a real link.
- **Don't rebuild selection** with `onClick` + your own state — mark the group
  `selectable` and bind a `<BbDropdownGroup v-model>`.
- **There is no `#item` slot** — a template slot named `item` renders nothing.
  Use `item:prepend`/`item:append` or a per-key slot.
- `width` defaults to `'auto'` (content-sized, ≥128px) — not a fixed pixel
  width; pass a number when menus must align across rows.
- Item `variant`s other than `destructive` render only a class hook — register
  names via the `dropdownItemVariants` plugin option and ship their CSS.
- `<BbDropdownGroup>` must sit in a `BbDropdown` (or `BbDropdownButton`)
  default slot, its `id` must match a group `key`, and a `multiple` group's
  model must be an array — all three misuses throw.
- Placeholder texts default to the config locale's "Loading…" / "No results"
  strings (`locale` plugin option) unless you set `loading-text` /
  `no-data-text`.

### Accessibility

- The activator gets `aria-haspopup` (`"menu"`, or `"dialog"` when the panel
  has a search field), `aria-expanded` and (once opened)
  `aria-controls` wired automatically — always spread the slot `props` onto a
  real focusable element (a `<button>`; `BbButton` qualifies). An existing
  `id` on your element is adopted, never overwritten. The `activator` **prop**
  path gets the same three attributes, attached programmatically to the
  referenced element — don't hand-write your own `aria-*` there either; it's
  the same double-set conflict as skipping the slot `props`.
- An icon-only trigger still needs an `aria-label` (see the nested-menu
  example).
- The panel is a `role="menu"` labelled by the activator; rows render as
  `menuitem`, or `menuitemradio` / `menuitemcheckbox` with `aria-checked` in
  selectable groups; submenu openers carry their own `aria-haspopup` /
  `aria-expanded`.
- A menu owns items and groups only, so the tree stays that honest: a titled
  group's rows sit in a `role="group"` labelled by the heading; a **clickable**
  group title (`onClick`) is itself a `menuitem`, a non-clickable one is
  `role="presentation"` and only names the group; every layout box around them
  (row containers, the search row, the submenu surface) is `role="none"`.
- A surface that renders a **search field** (any `searchable` group) is a
  `role="dialog"` instead — a menu may not own a searchbox — labelled by the
  activator exactly as the menu was, with the `menu` role moved down onto each
  group's rows (named by their heading). The activator's `aria-haspopup` and
  `aria-controls` follow it to `dialog`; a searchable submenu is a dialog named
  after the row that opened it; and the adaptive sheet, already a `<dialog>`,
  just steps its menu container aside rather than nesting a second dialog.
  Surfaces with no search field are unchanged.
- Keyboard is fully handled — don't add your own handlers: `ArrowDown` /
  `ArrowUp` on the trigger open the menu focusing the first/last item; inside,
  arrows rove (skipping disabled rows, wrapping), `Home`/`End` jump,
  `ArrowRight` enters a submenu, `ArrowLeft` closes the level (or navigates
  back in the sheet), `Escape` closes and refocuses the trigger. The menu is a
  single tab stop (rows are `tabindex="-1"` per the ARIA menu pattern): `Tab`
  leaves the menu and closes it. Focus returns to the activator after an
  action unless the action moved it (e.g. opened a dialog).
- The focused row's highlight is keyboard-only (`:focus-visible`). The mobile
  sheet always places real focus on the level's first row when it opens — a
  modal dialog would otherwise skip the `tabindex="-1"` rows — but a menu
  opened by tap or click paints nothing, so it never looks pre-selected.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activator` | `Record<string, any> \| HTMLElement \| null \| undefined` |  |  | External activator element or component ref. When provided, the activator slot is not rendered and event listeners are attached programmatically to the referenced element. ARIA (`aria-haspopup`/`aria-expanded`/`aria-controls`) is attached p… |
| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile viewports (below `config.mobileMaxWidth`), render the dropdown as a bottom-anchored, auto-sized off-canvas sheet that **navigates** through nested submenus (drilling one level at a time with a back control) instead of showing hove… |
| `anchor` | `Record<string, any> \| HTMLElement \| null \| undefined` | `the activator element` |  | Element the panel positions itself against, when it should differ from the activator — e.g. a wrapper that the activator is only a part of, so the menu aligns to the whole control while a single button opens it. Accepts an HTMLElement or a … |
| `boundary` | `string \| Record<string, any> \| HTMLElement \| null \| undefined` |  |  | Constrains the dropdown within a bounding element. Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
| `compact` | `boolean \| undefined` | `false` |  | Apply the compact density variant — the same ladder `BbSelect` uses, on both surfaces: flyout rows go 28px → 24px, sheet rows 44px → 36px. The label size does not change; density here is height, as it is for a select. A menu row is a touch … |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
| `enforceCoherence` | `boolean \| undefined` | `false` |  | Default for pipeline groups: drop selections that are no longer present in a group's current items (e.g. after a `dependencies` re-fetch) from the selection and `v-model`. A group's own `enforceCoherence` overrides this. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `items` | `Item[]` | `[]` | yes | Array used to render each dropdown button. They can act as `button`, as `a`, or as `router-link` as they are based on the functionality provided by `BbBaseButton`. Pass a flat array for a single group, nest arrays for divider-separated grou… |
| `loadingText` | `string \| undefined` |  |  | Default placeholder text shown while a pipeline group's async items load. A group's own `loadingText` overrides this; both fall back to the localized `common.loadingText` (`'Loading...'`). |
| `noDataText` | `string \| undefined` |  |  | Default placeholder text shown when a pipeline group resolves to no items. A group's own `noDataText` overrides this; both fall back to the localized `common.noDataText` (`'No data to display'`). |
| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Overrides forwarded to the underlying `BbOffCanvas` when `adaptive` renders the sheet on mobile. Merged over the adaptive defaults (`direction: 'bottom'`, `size: 'auto'`, `draggable: true`). Ignored when `adaptive` is `false`. |
| `offset` | `number \| undefined` | `3` |  | Space the floating container will maintain from the activator. |
| `padding` | `number \| undefined` | `10` |  | Minimum empty space to keep from the edge of the page |
| `placement` | `Placement \| "cursor" \| undefined` | `"bottom"` |  | Position of the dropdown relative to the activator. Use `'cursor'` to anchor at the mouse/touch coordinates. (No arrow is drawn either way — arrows are tooltip-only in v3.) |
| `queryDebounceTime` | `number \| undefined` | `300` |  | Debounce (ms) applied to the async re-fetch a `searchable` group fires as the user types. Applies to every searchable group in the menu. |
| `transitionDuration` | `number \| undefined` | `150` |  | How long the transition has to last in milliseconds. Menus use the fast transition rather than the medium one the other popovers default to. |
| `trigger` | `DropdownTrigger \| DropdownTrigger[] \| undefined` | `"click"` |  | Interaction(s) that open the dropdown. Accepts a single trigger or an array to combine them. - `'click'` — left-click / tap (default) - `'contextMenu'` — right-click on desktop, long-press on mobile |
| `width` | `string \| number \| undefined` | `"auto"` |  | Width of the dropdown in pixels, percentage, or 'auto' to fit content. |

## Events

- `item:selected` — `(event: "item:selected", value: any): void`
- `item:unselected` — `(event: "item:unselected", value: any): void`

## Slots

- `activator` — scope: `BbDropdownActivatorSlotProps` — The element that triggers the dropdown to open. Spread `props` onto your trigger element.
- `default` — scope: `any` — Hosts `<BbDropdownGroup>` companions. They register their group with the dropdown and render nothing themselves.
- `footer` — scope: `BbDropdownEdgeSlotProps` — Content pinned to the bottom of the dropdown panel, outside the scroll area. Stays visible while the items scroll and is separated from them by a divider — for action buttons.
- `header` — scope: `BbDropdownEdgeSlotProps` — Content pinned to the top of the dropdown panel, outside the scroll area. Stays visible while the items scroll and is separated from them by a divider — for a title or a filter field.
- `item:append` — scope: `BbDropdownItemSlotProps` — Content rendered after each dropdown item's default button content.
- `item:prepend` — scope: `BbDropdownItemSlotProps` — Content rendered before each dropdown item's default button content.
- `loading` — scope: `BbDropdownPlaceholderSlotProps` — Replaces the default loading placeholder row shown in a pipeline group while its async items load. Rendered once per loading group.
- `no-data` — scope: `BbDropdownPlaceholderSlotProps` — Replaces the default "no data" placeholder row shown in a pipeline group that resolved to no items. Rendered once per empty group.

## See Also

- [BbDropdownButton](./BbDropdownButton.md) — A button with primary action and all other actions collected in a dropdown.
- [BbButton](./BbButton.md) — Button with loading state, tooltip, and icon support.
- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements.
- [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.

---

<!-- dist/ai/BbDropdownButton.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbDropdownButton.md -->

# BbDropdownButton

## Agent Contract

- Safety level: **Consumer API**
- Group: **Overlay**
- Description: A button with primary action and all other actions collected in a dropdown.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbDropdownButton.md](./source/BbDropdownButton.md)

## Usage & Guidelines

### When to use

Use `BbDropdownButton` when there is **one obvious primary action** and a short
list of variations on it: _Save_ / Save as draft / Save as template, _Export_ /
Export as CSV, _Merge_ / Squash and merge. The primary action is one tap away;
the alternates hide behind a chevron.

Choose between the three action components by intent:

- **[BbButton](./BbButton.md)** — a single action, nothing else.
- **BbDropdownButton** — a dominant action _plus_ a few close alternates.
- **[BbDropdown](./BbDropdown.md)** — a menu with **no** single dominant action
  (an overflow "…" menu, an account menu, a context menu).

If your "alternates" are unrelated commands, that's a plain menu — reach for
`BbDropdown` instead.

### The split pattern

`items[0]` is the primary action, rendered as the left-hand `BbButton` —
everything from its BbBaseButton surface passes straight through: `onClick`,
`href` / `to` (with Inertia `method`/`data`, `target`, active-class props),
and `disabled`. Every later item opens from the chevron toggle on the right.
It's the same item model as `BbDropdown`, so submenus, links, descriptions and
groups all work in the menu.

Two deliberate exceptions on the primary item: its `variant` and
`prepend:icon` / `append:icon` are ignored — the split control's look comes
from the component's own `variant` and icon props, so the two halves always
match. And keep `items[0]` a **plain leaf item**: if the first entry is a
group or nested array, only its first leaf is promoted to the button and the
entry's remaining rows are dropped from the menu.

**Save / Save as draft**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">Invoice INV-2048</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				Acme Studio · due Jul 31, 2026
			</span>
		</div>
		<div class="flex items-center gap-2">
			<BbDropdownButton :items="items" prepend:icon="lucide:check" />
			<span class="text-xs text-[color:var(--bb-text-muted)]" data-last>{{
				last
			}}</span>
		</div>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbDropdownButton } from 'bitboss-ui';
import type { BbDropdownItem } from 'bitboss-ui';

const last = ref('Unsaved changes');

/** `items[0]` is the primary action; later rows open from the chevron. */
const items: BbDropdownItem[] = [
	{ key: 'save', text: 'Save', onClick: () => (last.value = 'Saved') },
	{
		key: 'draft',
		text: 'Save as draft',
		'prepend:icon': 'lucide:pencil',
		onClick: () => (last.value = 'Saved as draft'),
	},
	{
		key: 'template',
		text: 'Save as template',
		'prepend:icon': 'lucide:copy',
		onClick: () => (last.value = 'Saved as template'),
	},
];
</script>
```

### Export formats

The same shape covers download menus: one default Export on the main button,
format alternates behind the chevron. Prefer `href` / `to` on the format rows
so each export is a real navigation, not an `@click` that fakes a download.

**Export as CSV / JSON / PDF**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">Q2 revenue report</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				Acme Studio · Jul 1 – Sep 30, 2026
			</span>
		</div>
		<div class="flex items-center gap-2">
			<BbDropdownButton
				:items="items"
				prepend:icon="lucide:download"
				variant="outline"
			/>
			<span class="text-xs text-[color:var(--bb-text-muted)]" data-export>{{
				last
			}}</span>
		</div>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbDropdownButton } from 'bitboss-ui';
import type { BbDropdownItem } from 'bitboss-ui';

const last = ref('Not exported yet');

/** Primary Export (default CSV) plus format alternates via `href`. */
const items: BbDropdownItem[] = [
	{
		key: 'export',
		text: 'Export',
		onClick: () => (last.value = 'Exported as CSV'),
	},
	{
		key: 'csv',
		text: 'Export as CSV',
		'prepend:icon': 'lucide:file-spreadsheet',
		href: '#export-csv',
	},
	{
		key: 'json',
		text: 'Export as JSON',
		'prepend:icon': 'lucide:braces',
		href: '#export-json',
	},
	{
		key: 'pdf',
		text: 'Export as PDF',
		'prepend:icon': 'lucide:file-text',
		href: '#export-pdf',
	},
];
</script>
```

### Variants and size

`variant` and `size` are shared across both halves of the control, so it always
reads as one button. Stay on the shadcn ladder (`primary`, `secondary`,
`outline`, `ghost`); omit `size` for the default `md` (28px, flush beside
`compact` inputs). `size` also takes the responsive map form
(`{ sm: 'sm', lg: 'md' }`) — reach for `sm` only in dense toolbars. Use `block`
to stretch the control full-width in a narrow column, and `disabled` to freeze
both halves at once.

**Shared variant and size**

```vue
<div class="flex flex-wrap items-center gap-2">
	<BbDropdownButton
		variant="outline"
		:items="[
			{ key: 'export', text: 'Export', href: '#export' },
			{ key: 'csv', text: 'Export as CSV', href: '#csv' },
			{ key: 'json', text: 'Export as JSON', href: '#json' },
		]"
	/>
	<BbDropdownButton
		:size="{ sm: 'sm', lg: 'md' }"
		variant="secondary"
		:items="[
			{ key: 'invite', text: 'Invite member', href: '#invite' },
			{ key: 'link', text: 'Copy invite link', href: '#link' },
		]"
	/>
</div>
```

### Automatic loading — on both halves

When the primary action's `onClick` returns a promise, the main button shows a
spinner and blocks re-entry until it settles — you don't wire `loading`
yourself. The **toggle half does the same for menu actions**: while any menu
item's async `onClick` is in flight, the chevron button shows the busy state.
This keeps async submits honest with zero boilerplate. `disable-auto-loading`
opts the **main button** out of the automatic tracking (the toggle keeps
reflecting menu-action state), and the `loading` prop drives the main button
manually.

**Async primary action**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">July product changelog</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				bitboss-ui · ready to publish
			</span>
		</div>
		<div class="flex items-center gap-2">
			<BbDropdownButton :items="items" prepend:icon="lucide:rocket" />
			<span class="text-xs text-[color:var(--bb-text-muted)]" data-status>{{
				status
			}}</span>
		</div>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbDropdownButton } from 'bitboss-ui';
import type { BbDropdownItem } from 'bitboss-ui';

const status = ref('Draft');

/**
 * Returning a promise from the primary `onClick` auto-spins the main button.
 * Icons for `items[0]` are ignored — set `prepend:icon` on the control instead.
 */
const items: BbDropdownItem[] = [
	{
		key: 'publish',
		text: 'Publish',
		onClick: async () => {
			status.value = 'Publishing…';
			await new Promise((resolve) => setTimeout(resolve, 700));
			status.value = 'Published';
		},
	},
	{
		key: 'schedule',
		text: 'Schedule…',
		'prepend:icon': 'lucide:clock',
		href: '#schedule',
	},
	{
		key: 'draft',
		text: 'Revert to draft',
		onClick: () => (status.value = 'Draft'),
	},
];
</script>
```

### A destructive alternate, gated

A split button often hides its one dangerous variation behind the chevron —
delete the deployment, discard the draft. Mark that menu item with
`variant: 'destructive'` (the only item variant styled out of the box) and gate
its `onClick` behind [useConfirm](./composables/useConfirm.md): `await` the
decision and act only on a yes. The destructive entry never belongs in the
primary slot — the main button is for the action people reach for constantly,
not the one that needs a second thought.

**Destructive alternate behind useConfirm**

```vue
<template>
	<div
		class="flex max-w-md flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex items-center justify-between gap-3">
			<div class="flex min-w-0 flex-col gap-0.5">
				<span class="text-sm font-medium">acme-web · production</span>
				<span
					class="text-xs text-[color:var(--bb-text-muted)]"
					data-deploy-status
				>
					{{ status }}
				</span>
			</div>
			<BbDropdownButton
				:items="items"
				placement="bottom-end"
				size="sm"
				variant="outline"
			/>
		</div>

		<!--
			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
			mount none. See ai/guides/agent-contract.md § Global Host Rule.
		-->
		<BbConfirm />
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbConfirm, BbDropdownButton, useConfirm } from 'bitboss-ui';
import type { BbDropdownItem } from 'bitboss-ui';

const status = ref('dpl_7k2f · deployed 2026-07-08 14:32');

const { confirm } = useConfirm();

/** Dangerous alternate stays behind the chevron, gated by `useConfirm`. */
const items: BbDropdownItem[] = [
	{
		key: 'redeploy',
		text: 'Redeploy',
		onClick: async () => {
			status.value = 'Rebuilding…';
			await new Promise((resolve) => setTimeout(resolve, 700));
			status.value = 'dpl_9m4a · deployed just now';
		},
	},
	{ key: 'logs', text: 'View build logs', href: '#logs' },
	{
		key: 'delete',
		text: 'Delete deployment',
		variant: 'destructive',
		'prepend:icon': 'lucide:trash-2',
		onClick: async () => {
			const ok = await confirm({
				title: 'Delete this deployment?',
				text: 'The deployment and its build logs are removed permanently. This cannot be undone.',
				variant: 'destructive',
				yes: { text: 'Delete deployment', 'prepend:icon': 'lucide:trash-2' },
				no: 'Keep it',
			});
			if (ok) status.value = 'Deployment deleted';
		},
	},
];
</script>
```

### Swapping the toggle icon

The right-hand toggle shows a chevron by default. `right:icon` swaps just that
glyph — a deliberately narrow alternative to a slot, so the toggle keeps its
button semantics. Use it for an overflow "…" affordance. There is **no**
activator slot: the toggle button is part of the component's contract.

**Overflow-style toggle glyph**

```vue
<BbDropdownButton
	right:icon="lucide:ellipsis"
	variant="outline"
	:items="[
		{ key: 'open', text: 'Open', href: '#open' },
		{ key: 'rename', text: 'Rename', href: '#rename' },
		{ key: 'archive', text: 'Archive', href: '#archive' },
	]"
/>
```

### Selectable groups in a split button

Because it shares `BbDropdown`'s items, a split button can also host a
`selectable` group bound to a `<BbDropdownGroup>` companion placed in the
default slot — a primary action with a configuration chooser tucked into the
menu. The canonical shape is a merge button: the menu picks the merge method,
and because `items` is a `computed`, the selection re-labels `items[0]` — the
main button itself — so the control always announces exactly what it will do.

**Merge pull request**

```vue
<template>
	<div
		class="flex max-w-md flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">Add usage-based billing #482</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]" data-merge-status>
				{{ status }}
			</span>
		</div>
		<BbDropdownButton :items="items" prepend:icon="lucide:git-merge">
			<BbDropdownGroup id="method" v-model="method" />
		</BbDropdownButton>
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbDropdownButton, BbDropdownGroup } from 'bitboss-ui';
import type { BbDropdownItem } from 'bitboss-ui';

type MergeMethod = 'merge' | 'squash' | 'rebase';

const labels: Record<MergeMethod, string> = {
	merge: 'Merge pull request',
	squash: 'Squash and merge',
	rebase: 'Rebase and merge',
};

const method = ref<MergeMethod>('squash');
const status = ref('2 approvals · all checks passed');

/**
 * Selectable group parameterizes the primary action: `items` is a computed, so
 * picking a method re-labels `items[0]` — the main button itself.
 */
const items = computed<BbDropdownItem[]>(() => [
	{
		key: 'merge-pr',
		text: labels[method.value],
		onClick: () => (status.value = `Merged into main (${method.value})`),
	},
	{
		key: 'method',
		label: 'Merge method',
		selectable: true,
		items: [
			{ key: 'merge', text: 'Create a merge commit' },
			{ key: 'squash', text: 'Squash and merge' },
			{ key: 'rebase', text: 'Rebase and merge' },
		],
	},
]);
</script>
```

### Menu slots and positioning

Every slot except `activator` is forwarded into the inner `BbDropdown`:
`header` / `footer` pin content around the scrolling items, `item:prepend` /
`item:append` decorate every row, and per-key named slots replace a single
row's label (see the [BbDropdown guide](./BbDropdown.md) for payloads and
naming rules). One caveat: a per-key slot for `items[0]` does nothing — that
item is promoted into the main button and never renders as a menu row.

The dropdown's positioning surface passes through as props: `placement`,
`width` (default `'auto'`, sizes to menu content), `offset`, `padding`,
`eager`, `transition-duration` and `id`. The toggle opens the menu, but the menu
aligns to the **whole split control**: the default `bottom` centres it under the
pair rather than under the toggle half, and a percentage `width` resolves against
the pair's width (still floored at the menu's 128px minimum). What is **not** exposed: `trigger` (the toggle always opens on
click), `adaptive` / `offCanvasProps` (the menu follows the global
`config.adaptive`, becoming a bottom sheet on mobile), `anchor` (hard-wired to
the split control) and `boundary`.

**Forwarded menu slots**

```vue
<BbDropdownButton
	placement="bottom-end"
	variant="outline"
	:width="230"
	:items="[
		{ key: 'new-doc', text: 'New document', href: '#new' },
		{ key: 'from-template', text: 'From template…', href: '#template' },
		{ key: 'import', text: 'Import file', href: '#import' },
	]"
>
	<template #item:prepend>
		<BbIcon icon="lucide:file-text" />
	</template>
	<template #footer>
		<div class="p-2">
			<BbButton block href="#drafts" size="sm" variant="ghost">
				Browse drafts
			</BbButton>
		</div>
	</template>
</BbDropdownButton>
```

### Works well with

- [useConfirm](./composables/useConfirm.md) — gate a destructive alternate
  inside its `onClick` before acting (see the deployment example above).
- [useToast](./composables/useToast.md) — confirm the async primary action's
  outcome after the spinner settles.
- `BbDropdownGroup` — a chooser in the menu (see above); the selection can
  then parameterize the primary action.

### Gotchas and anti-patterns

- **Don't put the most common action inside the menu** — that's the whole
  point of the split; if no action dominates, use `BbDropdown`.
- **Don't style the halves apart** — one `variant`/`size` pair is the
  contract; two visually different halves read as two controls.
- `items[0]`'s `variant` and icons are ignored — set `prepend:icon` /
  `append:icon` / `variant` on the component instead.
- Keep `items[0]` a plain leaf item; a leading group/array silently loses its
  remaining rows.
- Navigation belongs on the items (`href`/`to`), never in `onClick`.
- A `variant: 'destructive'` menu item without a `useConfirm` gate is a
  one-tap disaster — always `await` the confirmation in its `onClick`.

### Accessibility

- The chevron toggle carries its own localized `aria-label` (from the
  `locale` config) and reflects open state via `aria-expanded` — no extra
  wiring needed.
- Keep the primary action's label a real verb; don't hide the most common
  action inside the menu.
- The menu's keyboard model (arrows to rove, `ArrowDown`/`ArrowUp` on the
  toggle to open, `Escape`, focus return) is inherited from `BbDropdown` —
  don't reimplement it.
- While an async action runs, the busy half blocks re-entry automatically;
  don't disable the other half yourself.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `append:icon` | `string \| undefined` |  |  | Icon to be added on the right of the text. |
| `block` | `boolean \| undefined` | `false` |  | Displays the component as full width. |
| `disableAutoLoading` | `boolean \| undefined` | `false` |  | Disables the automatic loading state that tracks async actions (enabled by default). Only affects the main action button: the split toggle half still mirrors the dropdown's internal async-action loading state. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `items` | `Item[]` | `[]` | yes | Array used to render each dropdown button. They can act as `button`, as `a`, or as `router-link` as they are based on the functionality provided by `BbBaseButton`. Pass a flat array for a single group, nest arrays for divider-separated grou… |
| `loading` | `boolean \| undefined` | `false` |  | Triggers a loading indicator. |
| `offset` | `number \| undefined` | `3` |  | Space the floating container will maintain from the activator. |
| `padding` | `number \| undefined` | `10` |  | Minimum empty space to keep from the edge of the page |
| `placement` | `Placement \| "cursor" \| undefined` | `'bottom'` |  | Position of the dropdown relative to the activator. Use `'cursor'` to anchor at the mouse/touch coordinates. (No arrow is drawn either way — arrows are tooltip-only in v3.) |
| `prepend:icon` | `string \| undefined` |  |  | Icon to be added on the left of the text. |
| `right:icon` | `string \| undefined` |  |  | Replaces the chevron shown inside the right-side dropdown toggle button. A constrained alternative to a slot: only the toggle's icon changes, so the button keeps its semantics. Named for consistency with `prepend:icon` / `append:icon`. |
| `size` | `Responsive<Sizes> \| undefined` | `"md"` |  | Sets the size of the button. When the value is a string, it will be applied to all screen sizes. Otherwise, it will be applied to the screen size specified by the object. |
| `transitionDuration` | `number \| undefined` | `150` |  | How long the transition has to last in milliseconds. Menus use the fast transition rather than the medium one the other popovers default to. |
| `variant` | `ButtonVariantType \| undefined` | `"primary"` |  | Visual variant shared by both buttons of the split control. |
| `width` | `string \| number \| undefined` | `'auto'` |  | Width of the dropdown in pixels, percentage, or 'auto' to fit content. |

## Events

- None.

## Slots

- `default` — scope: `any` — Companion content forwarded into the dropdown (e.g. `<BbDropdownGroup>`).
- `footer` — scope: `BbDropdownButtonEdgeSlotProps` — Content pinned to the bottom of the dropdown panel, outside the scroll area.
- `header` — scope: `BbDropdownButtonEdgeSlotProps` — Content pinned to the top of the dropdown panel, outside the scroll area.
- `item:append` — scope: `BbDropdownButtonItemSlotProps` — Content rendered after each dropdown item's default content.
- `item:prepend` — scope: `BbDropdownButtonItemSlotProps` — Content rendered before each dropdown item's default content.
- `loading` — scope: `BbDropdownPlaceholderSlotProps` — Replaces the default loading placeholder row shown in a pipeline group while its async items load. Rendered once per loading group. Forwarded to the underlying `BbDropdown`.
- `no-data` — scope: `BbDropdownPlaceholderSlotProps` — Replaces the default "no data" placeholder row shown in a pipeline group that resolved to no items. Rendered once per empty group. Forwarded to the underlying `BbDropdown`.

## See Also

- [BbButton](./BbButton.md) — Button with loading state, tooltip, and icon support.
- [BbDropdown](./BbDropdown.md) — Displays contextual action menus and menu content (includes the co-located BbDropdownGroup export, which is how a selectable group is bound).
- [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.

---

<!-- dist/ai/BbDropdownGroup.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbDropdownGroup.md -->

# BbDropdownGroup

## Agent Contract

- Safety level: **Consumer API**
- Group: **Overlay**
- Description: Renderless v-model companion for a group declared in BbDropdown.items, bound by id.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbDropdownGroup.md](./source/BbDropdownGroup.md)

## v-model

- `v-model` — type: `any`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | `string` |  | yes | Identifier of the group to bind to — must match the `key` of a group declared in the host `BbDropdown`'s `items`. |
| `modelValue` | `any` |  |  |  |

## Events

- `item:selected` — `(event: "item:selected", value: any): void`
- `item:unselected` — `(event: "item:unselected", value: any): void`
- `update:modelValue` — `(event: "update:modelValue", value: any): void`

## Slots

- `default` — scope: `{}`

## See Also

- [BbDropdown](./BbDropdown.md) — Displays contextual action menus and menu content (includes the co-located BbDropdownGroup export, which is how a selectable group is bound).

---

<!-- dist/ai/BbDropzone.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbDropzone.md -->

# BbDropzone

## Agent Contract

- Safety level: **Consumer API**
- Group: **Inputs**
- Description: Supports drag-and-drop file input flows.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbDropzone.md](./source/BbDropzone.md)

## Usage & Guidelines

### When to use

Reach for `BbDropzone` whenever the user hands you files: avatars, receipts,
attachments, imports, galleries. It captures files both by drag-and-drop and by
the native picker, validates them against the limits you set, and hands you back
a `File | File[] | null` through `v-model`.

- **A single hidden `<input type="file">` with no drop target and no previews?**
  A bare input is enough — `BbDropzone` earns its keep when you want a drop
  surface, live validation (type, size, count, duplicates), a rendered list of
  what was picked, and an accessible labelled control for free.
- **It captures and validates; it does _not_ upload.** There is no request,
  progress, or completion surface inside the component. Pair it with your own
  request layer plus [`BbProgress`](./BbProgress.md) and `useToast` — see
  _Uploading the captured files_.
- For a free-form token/tag entry (skills, recipients the user invents) that is
  not about files, use [`BbTag`](./BbTag.md), not this.

### The drop area and its slot

`BbDropzone` renders **no visible surface of its own** — the `default` slot _is_
the drop area. It renders inside the `<label>` that wraps a visually-hidden
`<input type="file">`, so a click, tap, or keyboard activation anywhere in your
slot opens the native picker, and the whole area is a single focusable, labelled
control with no extra work.

The slot scope carries five things:

- `dragging: boolean` — a file is being dragged over this zone. Style your
  drag-over affordance off it. (There is a 100 ms debounce on drag-leave so the
  highlight doesn't flicker as the pointer crosses child elements.)
- `focused: boolean` — the input has keyboard focus. Use it to paint a focus
  ring on your custom surface, since the real input is visually hidden.
- `id: string` — the id of the interactive file input, for associating an
  _external_ `<label :for="id">` elsewhere on the page. Do **not** wrap another
  `<label for>` _inside_ the slot — you'd be nesting labels.
- `labelId: string` — put it on the one element whose text should be the
  control's accessible name (see _Accessibility_). Optional; omit it and the
  localized default names the field.
- `open: () => void` — opens the native file dialog programmatically (a no-op
  while `disabled`). Wire it to your own "Browse" button.

**Drag-and-drop or click to browse**

```vue
<template>
	<BbDropzone v-model="file">
		<template #default="{ dragging, focused, labelId, open }">
			<div
				class="drag-or-browse"
				:class="{
					'drag-or-browse--dragging': dragging,
					'drag-or-browse--focused': focused,
				}"
			>
				<BbIcon class="drag-or-browse__icon" icon="lucide:upload" size="lg" />
				<!-- `labelId` goes on the headline ALONE: its text joins the input's
				     accessible name ("Drag a file here Select files"). Putting it on
				     the wrapper would drag the browse button and the filename in. -->
				<p :id="labelId" class="text-sm font-medium">
					{{ dragging ? 'Drop to upload' : 'Drag a file here' }}
				</p>
				<BbButton variant="ghost" @click="open">or browse</BbButton>
				<p v-if="file" class="text-xs text-[color:var(--bb-text-muted)]">
					Selected: {{ file.name }}
				</p>
			</div>
		</template>
	</BbDropzone>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbDropzone, BbIcon } from 'bitboss-ui';

// Single mode: the model is File | null and each pick REPLACES it.
const file = ref<File | null>(null);
</script>

<style scoped>
/* Solid sheet hairline at rest; mark wash only while dragging. */
.drag-or-browse {
	align-items: center;
	background: var(--bb-panel);
	border: var(--bb-border-w) solid var(--bb-border);
	border-radius: var(--bb-radius);
	display: flex;
	flex-direction: column;
	gap: 0.5rem;
	max-width: 28rem;
	padding: 1rem;
	text-align: center;
	transition:
		border-color var(--bb-transition-fast) var(--bb-ease),
		background-color var(--bb-transition-fast) var(--bb-ease);
}

.drag-or-browse--dragging {
	background: color-mix(in oklab, var(--bb-primary) 8%, var(--bb-panel));
	border-color: var(--bb-primary);
}

.drag-or-browse--focused {
	box-shadow: 0 0 0 var(--bb-ring-size) var(--bb-ring);
}

.drag-or-browse__icon {
	color: var(--bb-text-muted);
}
</style>
```

You never _need_ your own button — the whole area already opens the picker — but
a visible affordance like the one above is good practice.

### Single vs. multiple, and the model shape

`multiple` decides both the input mode and the `v-model` shape:

- **Off (default):** the model is `File | null`. Each new selection **replaces**
  the previous file. Bind a `ref<File | null>(null)`.
- **On:** the model is `File[]`. New selections are **appended** to the array
  (validated first). Bind a `ref<File[]>([])` — an array model needs a typed,
  seeded ref, so use a companion SFC, not an inline `state.*`.

Single mode is the profile-photo shape: replace-on-select means "upload a new
photo" needs no clear-first step, and the preview is just an object URL created
from the model (revoke the stale one when it changes) handed to
[`BbAvatar`](./BbAvatar.md):

**Profile photo — single file, replace-on-select, avatar preview**

```vue
<template>
	<div class="avatar-uploader">
		<div class="avatar-uploader__identity">
			<BbAvatar alt="Profile photo" size="56" :src="preview">
				<BbIcon icon="lucide:user-round" size="lg" />
			</BbAvatar>
			<div class="min-w-0 flex-1">
				<p class="text-sm font-medium">Ada Moreau</p>
				<p class="truncate text-xs text-[color:var(--bb-text-muted)]">
					ada.moreau@acme.dev
				</p>
			</div>
			<BbButton
				v-if="photo"
				aria-label="Remove photo"
				icon="lucide:trash-2"
				size="sm"
				variant="ghost"
				@click="photo = null"
			/>
		</div>

		<BbDropzone
			v-model="photo"
			:accept="['image/png', '.png', 'image/jpeg', '.jpg', '.jpeg']"
			:errors="errors"
			:max-size="2 * 1024 * 1024"
			@error="onError"
		>
			<template #default="{ dragging, focused, labelId, open }">
				<div
					class="avatar-uploader__drop"
					:class="{
						'avatar-uploader__drop--dragging': dragging,
						'avatar-uploader__drop--focused': focused,
					}"
				>
					<BbIcon
						class="avatar-uploader__icon"
						icon="lucide:image-plus"
						size="sm"
					/>
					<span :id="labelId" class="text-sm">{{
						dragging
							? 'Drop to set photo'
							: photo
								? 'Drop a new photo to replace it'
								: 'Drag a photo here'
					}}</span>
					<BbButton variant="ghost" @click="open">Browse</BbButton>
				</div>
			</template>
		</BbDropzone>

		<p class="avatar-uploader__hint">
			PNG or JPG · up to 2 MB · square images crop best
		</p>
	</div>
</template>

<script setup lang="ts">
import { onBeforeUnmount, ref, watch } from 'vue';
import { BbAvatar, BbButton, BbDropzone, BbIcon } from 'bitboss-ui';
import type { DropZoneError } from 'bitboss-ui';

const photo = ref<File | null>(null);
const preview = ref<string>();
const errors = ref<string[]>([]);

/* Single mode: each selection REPLACES the model. Mirror that in the
   object URL feeding the avatar preview, and revoke the stale one. */
watch(photo, (next) => {
	if (preview.value) URL.revokeObjectURL(preview.value);
	preview.value = next ? URL.createObjectURL(next) : undefined;
	errors.value = [];
});

onBeforeUnmount(() => {
	if (preview.value) URL.revokeObjectURL(preview.value);
});

const onError = (error: DropZoneError) => {
	errors.value = [
		error.type === 'maxSize'
			? `"${error.filename}" is larger than ${error.formattedMaxSize} — pick a smaller image.`
			: error.type === 'accept'
				? `"${error.filename}" is not a PNG or JPG image.`
				: `"${error.filename}" could not be used.`,
	];
};
</script>

<style scoped>
.avatar-uploader {
	border: var(--bb-border-w) solid var(--bb-border);
	border-radius: var(--bb-radius);
	display: flex;
	flex-direction: column;
	gap: 0.75rem;
	max-width: 28rem;
	padding: 0.75rem;
	width: 100%;
}

.avatar-uploader__identity {
	align-items: center;
	display: flex;
	gap: 0.75rem;
}

/* Solid sheet hairline at rest; mark wash only while dragging. */
.avatar-uploader__drop {
	align-items: center;
	background: var(--bb-panel);
	border: var(--bb-border-w) solid var(--bb-border);
	border-radius: var(--bb-radius);
	display: flex;
	gap: 0.5rem;
	justify-content: center;
	padding-bottom: 0.5rem;
	padding-left: 0.75rem;
	padding-right: 0.75rem;
	padding-top: 0.5rem;
	transition:
		border-color var(--bb-transition-fast) var(--bb-ease),
		background-color var(--bb-transition-fast) var(--bb-ease);
}

.avatar-uploader__drop--dragging {
	background: color-mix(in oklab, var(--bb-primary) 8%, var(--bb-panel));
	border-color: var(--bb-primary);
}

.avatar-uploader__drop--focused {
	box-shadow: 0 0 0 var(--bb-ring-size) var(--bb-ring);
}

.avatar-uploader__icon {
	color: var(--bb-text-muted);
}

.avatar-uploader__hint {
	color: var(--bb-text-muted);
	font-size: 0.75rem;
}
</style>
```

Because the model only ever holds files that **passed validation**, listing the
selection — and removing from it — is just rendering the array and filtering it;
there is no separate "selected files" API. Removal is a plain
`files = files.filter(f => f !== target)`.

**Receipt uploader — multiple, limits, listing and removal**

```vue
<template>
	<div class="receipt-uploader">
		<BbDropzone
			v-model="receipts"
			:accept="[
				'image/png',
				'.png',
				'image/jpeg',
				'.jpg',
				'.jpeg',
				'application/pdf',
				'.pdf',
			]"
			:errors="errors"
			:max-files="5"
			:max-size="5 * 1024 * 1024"
			multiple
			@error="onError"
		>
			<template #default="{ dragging, focused, labelId, open }">
				<div
					class="receipt-uploader__drop"
					:class="{
						'receipt-uploader__drop--dragging': dragging,
						'receipt-uploader__drop--focused': focused,
					}"
				>
					<BbIcon
						class="receipt-uploader__icon"
						icon="lucide:receipt"
						size="lg"
					/>
					<p :id="labelId" class="text-sm font-medium">
						{{ dragging ? 'Drop to attach' : 'Drag receipts here' }}
					</p>
					<p class="text-xs text-[color:var(--bb-text-muted)]">
						PNG, JPG or PDF · up to 5 files · 5 MB each
					</p>
					<BbButton variant="outline" @click="open">Browse files</BbButton>
				</div>
			</template>
		</BbDropzone>

		<ul v-if="receipts.length" class="receipt-uploader__list">
			<li
				v-for="file in receipts"
				:key="fileKey(file)"
				class="receipt-uploader__item"
			>
				<BbIcon
					class="receipt-uploader__icon"
					icon="lucide:file-text"
					size="sm"
				/>
				<span class="min-w-0 flex-1 truncate text-sm font-medium">{{
					file.name
				}}</span>
				<span class="shrink-0 text-xs text-[color:var(--bb-text-muted)]">{{
					formatSize(file.size)
				}}</span>
				<BbButton
					:aria-label="`Remove ${file.name}`"
					icon="lucide:x"
					size="sm"
					variant="ghost"
					@click="remove(file)"
				/>
			</li>
		</ul>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbDropzone, BbButton, BbIcon } from 'bitboss-ui';
import type { DropZoneError } from 'bitboss-ui';

const receipts = ref<File[]>([]);
const errors = ref<string[]>([]);

const fileKey = (file: File) =>
	`${file.name}-${file.size}-${file.lastModified}`;

const formatSize = (bytes: number) =>
	bytes < 1024 * 1024
		? `${Math.max(1, Math.round(bytes / 1024))} KB`
		: `${(bytes / 1024 / 1024).toFixed(1)} MB`;

/* Translate the typed DropZoneError union into a human message. */
const onError = (error: DropZoneError) => {
	const message =
		error.type === 'maxSize'
			? `"${error.filename}" is larger than ${error.formattedMaxSize}.`
			: error.type === 'maxFiles'
				? `You can attach at most ${error.maxFiles} receipts.`
				: error.type === 'accept'
					? `"${error.filename}" is not a receipt (PNG, JPG or PDF only).`
					: `"${error.filename}" is already attached.`;
	errors.value = [message];
};

const remove = (file: File) => {
	receipts.value = receipts.value.filter((entry) => entry !== file);
	errors.value = [];
};
</script>

<style scoped>
.receipt-uploader {
	display: flex;
	flex-direction: column;
	gap: 0.75rem;
	max-width: 28rem;
	width: 100%;
}

/* Solid sheet hairline at rest; mark wash only while dragging. */
.receipt-uploader__drop {
	align-items: center;
	background: var(--bb-panel);
	border: var(--bb-border-w) solid var(--bb-border);
	border-radius: var(--bb-radius);
	display: flex;
	flex-direction: column;
	gap: 0.5rem;
	padding: 1rem;
	text-align: center;
	transition:
		border-color var(--bb-transition-fast) var(--bb-ease),
		background-color var(--bb-transition-fast) var(--bb-ease);
}

.receipt-uploader__drop--dragging {
	background: color-mix(in oklab, var(--bb-primary) 8%, var(--bb-panel));
	border-color: var(--bb-primary);
}

.receipt-uploader__drop--focused {
	box-shadow: 0 0 0 var(--bb-ring-size) var(--bb-ring);
}

.receipt-uploader__icon {
	color: var(--bb-text-muted);
}

.receipt-uploader__list {
	display: flex;
	flex-direction: column;
	gap: 0.375rem;
	list-style: none;
	margin: 0;
	padding: 0;
}

.receipt-uploader__item {
	align-items: center;
	background: var(--bb-muted);
	border: var(--bb-border-w) solid var(--bb-border);
	border-radius: var(--bb-radius);
	display: flex;
	gap: 0.5rem;
	padding-bottom: 0.375rem;
	padding-left: 0.75rem;
	padding-right: 0.75rem;
	padding-top: 0.375rem;
}
</style>
```

Duplicate files (identical `name`, `size`, `lastModified` and `type`) are
rejected automatically with a `uniqueness` error, so re-dropping the same
receipt never double-counts.

### Restricting what's accepted — `accept`, `maxSize`, `maxFiles`

Constrain the input with four independent rules. Every rule is enforced on
**both** paths — the native picker _and_ drag-drop — because the browser's
`accept` attribute is only an advisory filter in the picker and does nothing for
dropped files; the component re-validates everything itself.

- **`accept: string[]`** — the type allow-list. Three grammars are supported:
  - **MIME type** — `'image/png'`, `'application/pdf'`. Matched against the
    file's `type`.
  - **Wildcard** — `'image/*'`, `'video/*'`. Matches any file whose major type
    is `image`, `video`, etc.
  - **Extension** — `'.pdf'`, `'.csv'`. Matched by filename suffix
    (case-insensitive `endsWith`).

  A `.ext` entry is rendered **verbatim** on the native input's `accept` and is
  matched **by filename**, not resolved to a MIME type — so on a drag-drop where
  the OS leaves `file.type` empty, the extension rule is what still catches it.
  For robustness, **pair each extension with its explicit MIME type**
  (`['application/pdf', '.pdf']`): the MIME rule matches by content type, the
  `.ext` rule matches by name, and together they cover both browsers that set
  `file.type` and those that don't.

  A **bare token** like `'pdf'` (no dot, no slash) gets that pairing built for
  it: it upgrades to its extension (`.pdf`) instantly, and to the matching MIME
  type (`application/pdf`, via the lazily-imported `mime` database) as soon as
  the database loads at mount. A drop or pick that lands before the database
  resolves is **queued and validated against the complete rule set** — never a
  partial one. A token the database doesn't know keeps its extension upgrade
  and logs a dev warning (use a `.ext` or `type/subtype` entry to silence it).
  Explicit entries never load the database.

- **`maxSize: number`** — per-file ceiling in **bytes** (`5 * 1024 * 1024` = 5 MB).
- **`maxFiles: number`** — cap on the total selection (existing + new). Only
  meaningful with `multiple`.

Anything failing a rule is **rejected before it reaches `v-model`** and surfaces
as one `@error` event per rejected file (see the next section). Validation runs
per file in order: size → duplicate → type → count.

The MIME + extension pairing matters most for formats browsers report
inconsistently — CSV is the classic case (Excel exports often carry
`application/vnd.ms-excel` or an empty `type`, so `'text/csv'` alone would
reject them; the `'.csv'` rule is what actually admits the file). A
contacts-import flow shows the pairing plus a header-row preview read straight
from the validated model:

**CSV contact import — MIME + extension pairing**

```vue
<template>
	<div class="csv-import">
		<div class="csv-import__header">
			<p class="text-sm font-medium">Import contacts</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				CSV export from your previous CRM · a header row is required
			</p>
		</div>

		<BbDropzone
			v-model="csv"
			:accept="['text/csv', '.csv']"
			:errors="errors"
			:max-size="1024 * 1024"
			@error="onError"
		>
			<template #default="{ dragging, focused, labelId, open }">
				<div
					class="csv-import__drop"
					:class="{
						'csv-import__drop--dragging': dragging,
						'csv-import__drop--focused': focused,
					}"
				>
					<BbIcon
						class="csv-import__icon"
						icon="lucide:file-spreadsheet"
						size="lg"
					/>
					<p :id="labelId" class="text-sm font-medium">
						{{ dragging ? 'Drop your CSV' : 'Drag a CSV export here' }}
					</p>
					<p class="text-xs text-[color:var(--bb-text-muted)]">
						.csv only · up to 1 MB
					</p>
					<BbButton variant="outline" @click="open">Choose file</BbButton>
				</div>
			</template>
		</BbDropzone>

		<div v-if="csv" class="csv-import__preview">
			<div class="csv-import__file">
				<BbIcon class="csv-import__icon" icon="lucide:file-text" size="sm" />
				<span class="min-w-0 flex-1 truncate text-sm font-medium">{{
					csv.name
				}}</span>
				<span
					v-if="columns.length"
					class="shrink-0 text-xs text-[color:var(--bb-text-muted)]"
				>
					{{ columns.length }} columns detected
				</span>
			</div>
			<div v-if="columns.length" class="csv-import__columns">
				<span
					v-for="column in columns"
					:key="column"
					class="csv-import__column"
				>
					{{ column }}
				</span>
			</div>
			<div class="csv-import__actions">
				<BbButton :disabled="!columns.length" variant="primary">
					Import contacts
				</BbButton>
				<BbButton variant="ghost" @click="csv = null">Clear</BbButton>
			</div>
		</div>
	</div>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue';
import { BbButton, BbDropzone, BbIcon } from 'bitboss-ui';
import type { DropZoneError } from 'bitboss-ui';

const csv = ref<File | null>(null);
const columns = ref<string[]>([]);
const errors = ref<string[]>([]);

/* Read the header row to preview the columns the import would map.
   The model only ever holds a file that already passed accept/maxSize. */
watch(csv, async (next) => {
	errors.value = [];
	columns.value = [];
	if (!next) return;
	const text = await next.text();
	columns.value = (text.split(/\r?\n/)[0] ?? '')
		.split(',')
		.map((column) => column.trim())
		.filter(Boolean);
});

const onError = (error: DropZoneError) => {
	errors.value = [
		error.type === 'accept'
			? `"${error.filename}" is not a .csv file — export your contacts as CSV first.`
			: error.type === 'maxSize'
				? `"${error.filename}" is larger than ${error.formattedMaxSize}. Split the export and import in batches.`
				: `"${error.filename}" could not be used.`,
	];
};
</script>

<style scoped>
.csv-import {
	border: var(--bb-border-w) solid var(--bb-border);
	border-radius: var(--bb-radius);
	display: flex;
	flex-direction: column;
	gap: 0.75rem;
	max-width: 28rem;
	padding: 0.75rem;
	width: 100%;
}

.csv-import__header {
	display: flex;
	flex-direction: column;
	gap: 0.125rem;
}

/* Solid sheet hairline at rest; mark wash only while dragging. */
.csv-import__drop {
	align-items: center;
	background: var(--bb-panel);
	border: var(--bb-border-w) solid var(--bb-border);
	border-radius: var(--bb-radius);
	display: flex;
	flex-direction: column;
	gap: 0.375rem;
	padding: 1rem;
	text-align: center;
	transition:
		border-color var(--bb-transition-fast) var(--bb-ease),
		background-color var(--bb-transition-fast) var(--bb-ease);
}

.csv-import__drop--dragging {
	background: color-mix(in oklab, var(--bb-primary) 8%, var(--bb-panel));
	border-color: var(--bb-primary);
}

.csv-import__drop--focused {
	box-shadow: 0 0 0 var(--bb-ring-size) var(--bb-ring);
}

.csv-import__icon {
	color: var(--bb-text-muted);
}

.csv-import__preview {
	display: flex;
	flex-direction: column;
	gap: 0.5rem;
}

.csv-import__file {
	align-items: center;
	display: flex;
	gap: 0.5rem;
}

.csv-import__columns {
	display: flex;
	flex-wrap: wrap;
	gap: 0.375rem;
}

.csv-import__column {
	border: var(--bb-border-w) solid var(--bb-border);
	border-radius: var(--bb-radius-sm);
	color: var(--bb-text-muted);
	font-size: 0.75rem;
	padding-bottom: 0.125rem;
	padding-left: 0.375rem;
	padding-right: 0.375rem;
	padding-top: 0.125rem;
}

.csv-import__actions {
	display: flex;
	gap: 0.5rem;
}
</style>
```

### Rejections and how you display them

Rejects never mutate the model — instead each one emits an `@error` carrying a
typed `DropZoneError`. The union is discriminated by `type`, and every variant
carries the offending `file` and its `filename`:

| `type`         | Extra payload                                        | Fires when                              |
| -------------- | ---------------------------------------------------- | --------------------------------------- |
| `'maxSize'`    | `formattedSize`, `formattedMaxSize` (human-readable) | a file is larger than `maxSize`         |
| `'uniqueness'` | —                                                    | an identical file is already selected   |
| `'accept'`     | `mimeType`, `acceptedMimeTypes: string[]`            | the file's type/extension isn't allowed |
| `'maxFiles'`   | `maxFiles`, `totalFiles`                             | adding the file would exceed `maxFiles` |

The component does **not** self-populate its own error display from these — the
`errors` prop is the round-trip. Listen to `@error`, turn the typed error into a
human message, and feed it back through `errors` (a `string | string[]`), which
the component renders inside its built-in `aria-live` region and points the
input's `aria-describedby` at. Use `hasErrors`
(boolean) when you only want the error _styling_ (the `bb-dropzone--errors`
class and `aria-invalid`) driven by your own validity state — e.g. a form-level
"this field is required" from your schema — without a message string. `warnings`
is the amber counterpart of `errors`: a `string | string[]` rendered in its own
`aria-live="polite"` region (also `aria-describedby`-referenced while shown)
for a valid-but-noteworthy selection, and a
non-empty `warnings` implies the warning state just as `errors` implies the
error state. Use `hasWarning` (boolean) to force that same amber chrome without a
message. `hasErrors` takes priority when both are set (the warning messages are
then suppressed), and unlike it neither warning prop sets `aria-invalid` — a soft
"needs a second look", not a validation failure.

Because a batch drop emits one error per rejected file, decide whether to show
the last message (simplest — what the example does), accumulate them, or count
them ("3 files were too large"). The `ReceiptUploader` above shows the map from
each `DropZoneError` variant to a sentence.

The map from variant to sentence is deliberately **project-level code** — the
wording, tone and i18n belong to your app, not the library. The exhaustive
`switch` below is the whole pattern; copy it once per project and route the
string wherever you display errors (the `errors` round-trip, a `toast()`, a
custom node):

```ts
// dropzone-errors.ts — project-level: your wording, your i18n.
import type { DropZoneError } from 'bitboss-ui';

export const formatDropzoneError = (error: DropZoneError): string => {
	switch (error.type) {
		case 'accept':
			return `${error.filename} is not an accepted file type (accepted: ${error.acceptedMimeTypes.join(', ')}).`;
		case 'maxFiles':
			return `${error.filename} exceeds the maximum of ${error.maxFiles} files.`;
		case 'maxSize':
			return `${error.filename} is ${error.formattedSize}, over the ${error.formattedMaxSize} limit.`;
		case 'uniqueness':
			return `${error.filename} has already been added.`;
	}
};
```

The union is closed, so the `switch` is exhaustive — if a future version adds a
variant, TypeScript flags the missing branch here.

### States

- **`disabled`** — disables both inputs, blanks the drag-over highlight and
  focus flag, sets `cursor: not-allowed` / `pointer-events: none` on the label,
  and makes `open()`, drop, and change no-ops. Disable the zone while an upload
  is in flight so the selection can't change mid-transfer.
- **Error** — driven by `errors` / `hasErrors` as above.
- **Empty** — the natural initial state; render your own placeholder/hint text
  in the slot. There is no built-in empty illustration.

There is no `readonly` or `loading` state — model a busy upload with `disabled`
plus a `BbProgress` bar you drive yourself.

### Uploading the captured files

`BbDropzone` stops at "these files are valid" — driving the upload is yours.
Reflect the transfer with [`BbProgress`](./BbProgress.md) (a plain `v-model`
number), confirm the result with `useToast`, and disable the zone while the
transfer is in flight.

**Upload with BbProgress, cancel/retry and a completion toast**

```vue
<template>
	<div class="upload-progress">
		<BbDropzone
			v-model="file"
			:accept="['image/*', '.pdf']"
			:disabled="uploading"
		>
			<template #default="{ dragging, focused, labelId, open }">
				<div
					class="upload-progress__drop"
					:class="{
						'upload-progress__drop--dragging': dragging,
						'upload-progress__drop--focused': focused,
					}"
				>
					<BbIcon
						class="upload-progress__icon"
						icon="lucide:upload"
						size="lg"
					/>
					<p :id="labelId" class="text-sm font-medium">
						{{ dragging ? 'Drop to upload' : 'Drag a document here' }}
					</p>
					<BbButton :disabled="uploading" variant="outline" @click="open">
						Choose file
					</BbButton>
				</div>
			</template>
		</BbDropzone>

		<div v-if="file" class="upload-progress__status">
			<div class="upload-progress__meta">
				<span class="min-w-0 truncate text-sm font-medium">{{
					file.name
				}}</span>
				<span class="shrink-0 text-xs text-[color:var(--bb-text-muted)]">{{
					statusLabel
				}}</span>
			</div>
			<BbProgress v-model="progress" />
			<div class="upload-progress__actions">
				<BbButton v-if="uploading" variant="ghost" @click="cancel">
					Cancel
				</BbButton>
				<BbButton v-else-if="!done" variant="outline" @click="startUpload">
					Retry
				</BbButton>
			</div>
		</div>
	</div>
</template>

<script setup lang="ts">
import { computed, ref, watch } from 'vue';
import { BbDropzone, BbProgress, BbButton, BbIcon, useToast } from 'bitboss-ui';

const { toast } = useToast();

const file = ref<File | null>(null);
const progress = ref(0);
const uploading = ref(false);
const done = ref(false);

let timer: ReturnType<typeof setInterval> | undefined;

const statusLabel = computed(() =>
	uploading.value ? `${progress.value}%` : done.value ? 'Done' : 'Cancelled'
);

/* Fake an upload: BbProgress reflects the transfer, useToast confirms the
   completion. In a real app this drives off your XHR/fetch progress events,
   and Cancel calls an AbortController's abort() instead of clearing a timer. */
const startUpload = () => {
	const current = file.value;
	if (!current) return;
	clearInterval(timer);
	progress.value = 0;
	done.value = false;
	uploading.value = true;
	timer = setInterval(() => {
		progress.value = Math.min(100, progress.value + 20);
		if (progress.value >= 100) {
			clearInterval(timer);
			uploading.value = false;
			done.value = true;
			toast({
				text: `"${current.name}" uploaded.`,
				variant: 'success',
				duration: 3000,
			});
		}
	}, 250);
};

const cancel = () => {
	clearInterval(timer);
	uploading.value = false;
	done.value = false;
};

/* A fresh selection restarts the transfer; clearing the file resets state. */
watch(file, (next) => {
	clearInterval(timer);
	progress.value = 0;
	done.value = false;
	uploading.value = false;
	if (next) startUpload();
});
</script>

<style scoped>
.upload-progress {
	display: flex;
	flex-direction: column;
	gap: 0.75rem;
	max-width: 28rem;
	width: 100%;
}

/* Solid sheet hairline at rest; mark wash only while dragging. */
.upload-progress__drop {
	align-items: center;
	background: var(--bb-panel);
	border: var(--bb-border-w) solid var(--bb-border);
	border-radius: var(--bb-radius);
	display: flex;
	flex-direction: column;
	gap: 0.5rem;
	padding: 1rem;
	text-align: center;
	transition:
		border-color var(--bb-transition-fast) var(--bb-ease),
		background-color var(--bb-transition-fast) var(--bb-ease);
}

.upload-progress__drop--dragging {
	background: color-mix(in oklab, var(--bb-primary) 8%, var(--bb-panel));
	border-color: var(--bb-primary);
}

.upload-progress__drop--focused {
	box-shadow: 0 0 0 var(--bb-ring-size) var(--bb-ring);
}

.upload-progress__icon {
	color: var(--bb-text-muted);
}

.upload-progress__status {
	border: var(--bb-border-w) solid var(--bb-border);
	border-radius: var(--bb-radius);
	display: flex;
	flex-direction: column;
	gap: 0.5rem;
	padding: 0.75rem;
}

.upload-progress__meta {
	align-items: center;
	display: flex;
	gap: 0.5rem;
	justify-content: space-between;
}

.upload-progress__actions {
	display: flex;
	gap: 0.5rem;
	justify-content: flex-end;
}
</style>
```

`useToast` needs `<BbToast />` mounted once in your app layout — without it,
toasts are enqueued but never shown. This demo fakes the transfer with a timer;
the wiring is identical against real `XHR`/`fetch` progress events. **Abort and
retry live in your request layer, not in `BbDropzone`** — the component has no
cancel/retry API. Use an `AbortController` for cancellation and re-issue the
request to retry:

```ts
const progress = ref(0);
let controller: AbortController | null = null;

async function upload(file: File) {
	controller = new AbortController();
	const body = new FormData();
	body.append('file', file);
	await axios.post('/uploads', body, {
		signal: controller.signal,
		onUploadProgress: (e) =>
			(progress.value = Math.round((e.loaded / (e.total ?? 1)) * 100)),
	});
}

function cancel() {
	controller?.abort();
}
```

### Form integration

The validated files reach your submit **straight from the model** — hold the
`v-model` in your form state and assemble a `FormData` when you send. The
component also forwards the input's native `focus` / `blur` `FocusEvent`s, so a
form library can mark the field touched and run blur-time validation.

**A form that assembles a multipart payload**

```vue
<template>
	<form class="document-form" @submit.prevent="submit">
		<BbTextInput
			v-model="title"
			compact
			label="Request title"
			placeholder="e.g. Q3 expense report"
		/>

		<BbDropzone
			v-model="documents"
			:accept="['application/pdf', '.pdf']"
			:errors="errors"
			:max-files="4"
			:max-size="10 * 1024 * 1024"
			multiple
			name="documents"
			@error="onError"
		>
			<template #default="{ dragging, focused, labelId, open }">
				<div
					class="document-form__drop"
					:class="{
						'document-form__drop--dragging': dragging,
						'document-form__drop--focused': focused,
					}"
				>
					<BbIcon class="document-form__icon" icon="lucide:file-up" size="lg" />
					<p :id="labelId" class="text-sm font-medium">
						{{ dragging ? 'Drop to attach' : 'Attach supporting PDFs' }}
					</p>
					<p class="text-xs text-[color:var(--bb-text-muted)]">
						PDF only · up to 4 files · 10 MB each
					</p>
					<BbButton variant="outline" @click="open">Browse</BbButton>
				</div>
			</template>
		</BbDropzone>

		<ul v-if="documents.length" class="document-form__list">
			<li
				v-for="file in documents"
				:key="fileKey(file)"
				class="document-form__item"
			>
				<BbIcon class="document-form__icon" icon="lucide:file" size="sm" />
				<span class="min-w-0 flex-1 truncate text-sm font-medium">{{
					file.name
				}}</span>
				<BbButton
					:aria-label="`Remove ${file.name}`"
					icon="lucide:x"
					size="sm"
					variant="ghost"
					@click="remove(file)"
				/>
			</li>
		</ul>

		<BbButton :disabled="!documents.length || !title" type="submit">
			Submit request
		</BbButton>

		<p v-if="submitted" class="document-form__result">
			Prepared multipart POST with {{ submitted.fileCount }} file(s) under
			<code>documents[]</code> plus the request title.
		</p>
	</form>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbDropzone, BbButton, BbIcon, BbTextInput } from 'bitboss-ui';
import type { DropZoneError } from 'bitboss-ui';

const title = ref('');
const documents = ref<File[]>([]);
const errors = ref<string[]>([]);
const submitted = ref<{ field: string; fileCount: number } | null>(null);

const fileKey = (file: File) =>
	`${file.name}-${file.size}-${file.lastModified}`;

const onError = (error: DropZoneError) => {
	errors.value = [
		error.type === 'maxSize'
			? `"${error.filename}" exceeds ${error.formattedMaxSize}.`
			: error.type === 'maxFiles'
				? `Attach at most ${error.maxFiles} documents.`
				: error.type === 'accept'
					? `"${error.filename}" must be a PDF.`
					: `"${error.filename}" is already attached.`,
	];
};

const remove = (file: File) => {
	documents.value = documents.value.filter((entry) => entry !== file);
	errors.value = [];
};

/* The captured, already-validated files reach your submit straight from the
   model — assemble a FormData and hand it to your request layer. */
const submit = () => {
	const body = new FormData();
	body.append('title', title.value);
	documents.value.forEach((file) => body.append('documents[]', file));
	submitted.value = { field: 'documents[]', fileCount: documents.value.length };
};
</script>

<style scoped>
.document-form {
	display: flex;
	flex-direction: column;
	gap: 0.75rem;
	max-width: 28rem;
	width: 100%;
}

/* Solid sheet hairline at rest; mark wash only while dragging. */
.document-form__drop {
	align-items: center;
	background: var(--bb-panel);
	border: var(--bb-border-w) solid var(--bb-border);
	border-radius: var(--bb-radius);
	display: flex;
	flex-direction: column;
	gap: 0.5rem;
	padding: 1rem;
	text-align: center;
	transition:
		border-color var(--bb-transition-fast) var(--bb-ease),
		background-color var(--bb-transition-fast) var(--bb-ease);
}

.document-form__drop--dragging {
	background: color-mix(in oklab, var(--bb-primary) 8%, var(--bb-panel));
	border-color: var(--bb-primary);
}

.document-form__drop--focused {
	box-shadow: 0 0 0 var(--bb-ring-size) var(--bb-ring);
}

.document-form__icon {
	color: var(--bb-text-muted);
}

.document-form__list {
	display: flex;
	flex-direction: column;
	gap: 0.375rem;
	list-style: none;
	margin: 0;
	padding: 0;
}

.document-form__item {
	align-items: center;
	background: var(--bb-muted);
	border: var(--bb-border-w) solid var(--bb-border);
	border-radius: var(--bb-radius);
	display: flex;
	gap: 0.5rem;
	padding-bottom: 0.375rem;
	padding-left: 0.75rem;
	padding-right: 0.75rem;
	padding-top: 0.375rem;
}

.document-form__result {
	color: var(--bb-text-muted);
	font-size: 0.875rem;
}
</style>
```

On Inertia, bind the model into a `useForm` and let it serialize the `File[]` as
multipart automatically:

```ts
import { useForm } from '@inertiajs/vue3';

const form = useForm({ title: '', documents: [] as File[] });
// <BbDropzone v-model="form.documents" multiple :accept="['application/pdf', '.pdf']" name="documents" />
form.post('/documents'); // File[] is sent as multipart/form-data
```

On Nuxt, build the `FormData` yourself and `$fetch` it:

```ts
const documents = ref<File[]>([]);

async function submit() {
	const body = new FormData();
	documents.value.forEach((file) => body.append('documents[]', file));
	await $fetch('/api/documents', { method: 'POST', body });
}
```

There is also a lighter path for **classic server-rendered forms**: set `name`
and the component mirrors the model into a single hidden
`<input type="file" :name>`, so a plain
`<form method="post" enctype="multipart/form-data">` submit posts the files
under that name with no JS. The mirror tracks `v-model` exactly — a model
seeded before mount, files added by drag & drop (which never touch a native
FileList), and every later mutation all land in it; without `name` the input
is not rendered at all, and it is never focusable, so it adds nothing to the
tab order. Building `FormData` from the model stays the idiomatic path for
SPA/Inertia/Nuxt flows — `name` is for genuinely no-JS forms.

### Layout, `tag`, and global config

- **No size, `block`, or `compact` props.** The drop area is entirely your slot
  markup — size and lay it out with Tailwind utilities as any other block.
- **`tag`** picks the wrapper element — `div` (default) or `span` when the
  surrounding markup only accepts phrasing content; it does not change behavior.
- **`autofocus`** focuses the input on mount — reserve it for a page whose sole
  purpose is the upload; don't steal focus inside a larger form.
- **`locale`** (plugin config) supplies the input's accessible name
  (`"Select files"`) and the hidden submittable label (`"Files to send to the
server"`); both are translated via the library's i18n, so set `locale` rather
  than hard-coding an `aria-label`.
- **No `adaptive` mobile-sheet behavior** — this is a native file input, so on
  mobile a tap opens the OS picker (and the camera/photo library when the
  accepted types allow it) for free. No teleport or top-layer concerns.
- **Nested dropzones** are handled: on drag-over only the innermost
  `.bb-dropzone` under the pointer highlights, so a zone inside a zone won't both
  light up.

### Works well with

- [`BbProgress`](./BbProgress.md) — reflect the transfer you drive; pair it with
  [`BbSpinner`](./BbSpinner.md) for the server-side processing phase you can't
  measure.
- `useToast` (`<BbToast />`) — announce completion or a failed upload; the bar
  alone is silent.
- [`BbButton`](./BbButton.md) — the "Browse" trigger wired to `open()`; carries
  the usual `href`/`to` nav surface for links elsewhere in the flow.
- `useConfirm` / [`BbConfirm`](./BbConfirm.md) — gate a destructive "remove all
  attachments" before clearing the model.
- [`BbAvatar`](./BbAvatar.md) — the natural preview target for a single-image
  profile-photo dropzone; the _Profile photo_ example wires the object-URL
  round-trip.

### Gotchas & anti-patterns

- **`.ext` is not resolved to a MIME type.** `accept: ['.pdf']` renders `.pdf`
  verbatim on the input and matches by filename, not `application/pdf` — pair
  the extension with its explicit MIME for content-type matching.
- **`errors` does not auto-fill from `@error`.** You must map the typed error to
  a message and feed it back — the display is a round-trip, not automatic.
- **The model holds only valid files.** Don't build your own accept/size gate in
  the slot; rejects never reach `v-model`. Read the array to know what's in.
- **Don't rebuild removal/listing** — it's `filter` over the model array; there
  is no dedicated files API to call.
- **Don't expect upload/progress/cancel from the component** — capture only.
  Drive the request, bar, and abort yourself.
- **Bare type tokens are shorthand, not precision.** `'png'` expands to
  `.png` + `image/png` for you, but an explicit `'image/png'` / `'.png'` pair
  says exactly what you mean, skips the `mime` database import entirely, and
  can't hit the unknown-token dev warning.
- **Don't nest a `<label for>` inside the slot** — the drop area is already a
  label; use the `id` slot prop for an external label instead.
- **Don't put `labelId` on the slot wrapper.** Every descendant's text is
  concatenated into the accessible name, so a wrapper drags the hints, the Browse
  button and the file list in with it. It belongs on the headline alone.

### Accessibility

- The control is the real `<input type="file">`, visually hidden inside the
  `<label>` that is your drop area — Tab focuses it, Space/Enter opens the
  picker, with no extra work. The label carries **no** `role="button"` and no
  `aria-roledescription`: the label isn't focusable, so the role was a phantom,
  and the roledescription announced English in every locale.

**The naming contract.** The slot is a _region_, not a label — it holds
drag-state copy, hints, a Browse button and often the list of picked files.
Naming the input from that whole subtree would give it a name that repeats the
button, grows with every file added, and changes mid-drag. So:

- **By default** the accessible name is the localized `dropzone.selectFiles`
  string ("Select files" / "Seleziona file"), carried on the input's
  `aria-label`. Your slot copy is not part of it.
- **To make your visible copy the name** — which is what WCAG 2.5.3 _Label in
  Name_ asks for once the zone has a visible headline — put the `labelId` slot
  prop on the one element that carries it. The input is then `aria-labelledby`-ed
  to that element **plus** an sr-only copy of the localized instruction, in that
  order, so the computed name is e.g. `"Drag your invoices here Select files"`:
  the visible copy first (speech input matches what the user reads), and the name
  still says the control takes files.

  ```vue
  <BbDropzone v-model="files" multiple>
  	<template #default="{ labelId, open }">
  		<div class="zone">
  			<!-- Only this element's text joins the name. -->
  			<h3 :id="labelId">Drag your invoices here</h3>
  			<p>PDF or PNG · up to 10 MB</p>
  			<BbButton variant="ghost" @click="open">Browse files</BbButton>
  		</div>
  	</template>
  </BbDropzone>
  ```

- **Everything inside the element you tag ends up in the name.** Put `labelId` on
  the headline, never on a wrapper that also contains the hints, the Browse
  button or the file list.
- Leave `labelId` unused and **no `aria-labelledby` is emitted at all** — there
  is no dangling IDREF for axe's `aria-valid-attr-value` to flag.

- Messages passed via `errors` (and, when no errors win, `warnings`) render
  inside an `aria-live="polite"` region and are referenced from the input's
  `aria-describedby` — errors first — but only while that channel actually has
  copy, so a clean dropzone carries no `aria-describedby` at all. The input gets
  `aria-invalid="true"` in the error state — surface validation failures there rather than in a
  detached toast so assistive tech announces them in context. `disabled` is
  carried by the native `disabled` on that same input.
- Give your slot content that reads as an action ("Drag a file here", "Browse
  files") — activating anywhere in the zone opens the picker, so the visible text
  should describe what that does.
- Icon-only controls inside your slot (e.g. a remove button) still need an
  `aria-label`; the examples label each with the file it removes.

## v-model

- `v-model` — type: `File \| File[] \| null`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `accept` | `string[] \| undefined` |  |  | Array of MIME types (`'image/png'`), wildcards (`'image/*'`), extensions (`'.png'`) or bare tokens (`'png'`) to filter selectable files. A bare token upgrades to its extension instantly and is enriched with its MIME type from the lazily-imp… |
| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `maxFiles` | `number \| undefined` |  |  | Maximum number of acceptable files. |
| `maxSize` | `number \| undefined` |  |  | Max size of the files in bytes. |
| `modelValue` | `File \| File[] \| null` |  | yes | Used by v-model. |
| `multiple` | `boolean \| undefined` | `false` |  | Allows the selection of multiple items. |
| `name` | `string \| undefined` |  |  | Defines the name of the input. |
| `tag` | `LayoutTag \| undefined` | `"div"` |  | Element rendered as the component's wrapper. |
| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the dropzone, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they … |

## Events

- `blur` — `(event: "blur", event: FocusEvent): void`
- `error` — `(event: "error", data: DropZoneError): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `update:modelValue` — `(event: "update:modelValue", value: File \| File[] \| null): void`

## Slots

- `default` — scope: `BbDropzoneDefaultSlotProps` — The drop zone area content. Renders inside the `<label>` that captures drag and file input events. It is a region, not a label: its text does not name the input unless you mark one node with the `labelId` slot prop.

## Validated variant

Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).

| Prop | Type | Description |
| --- | --- | --- |
| `rules` | `RuleExpression<File \| File[] \| null>` | vee-validate rules for this field. |
| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |

---

<!-- dist/ai/BbForm.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbForm.md -->

# BbForm

## Agent Contract

- Safety level: **Consumer API**
- Group: **Inputs**
- Description: Form host for `bitboss-ui/validated`: owns the vee-validate form (useForm), validates every field on submit, and emits `submit` with the collected values only when the form is valid.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbForm.md](./source/BbForm.md)

## Usage & Guidelines

### When to use

`BbForm` is the host every `bitboss-ui/validated` control expects. It calls
vee-validate's `useForm()` once and provides the field context those controls
bind to, so a validated `BbTextInput` inside it needs nothing but a `label` and
its `rules`.

Reach for it whenever a screen collects input that must be valid before it is
sent. Do **not** reach for it to lay out a form — it renders a bare `<form>` and
nothing else; spacing, columns and section headings stay yours.

Two things it is not:

- **Not needed for unvalidated forms.** Controls imported from `bitboss-ui`
  carry no field binding, so a plain `<form>` is enough. Mixing is fine: only
  the controls you import from `bitboss-ui/validated` participate.
- **Not a submit button.** It has no built-in actions; put your own
  `<BbButton type="submit">` in the slot.

Setup (the peer dependency, defining rules once, the whole control list) lives
in [Validated Forms](./guides/validated-forms.md). This page is only about the
host.

### Submit is the gate

The one event is `submit`, and it fires **only when every field passes**. The
native submission is always prevented, so there is no navigation to suppress and
no `@submit.prevent` to remember — an invalid form simply surfaces its messages
and stays put.

```vue
<script setup lang="ts">
import { BbButton } from 'bitboss-ui';
import { BbForm, BbTextInput } from 'bitboss-ui/validated';

// Just await the work — no `saving` ref. The form tracks it (see below).
const save = async (values: Record<string, unknown>) => {
	await api.contacts.create(values);
};
</script>

<template>
	<BbForm v-slot="{ isSubmitting }" @submit="save">
		<BbTextInput label="Full name" rules="required" />
		<BbTextInput label="Email" rules="required|email" type="email" />
		<BbButton :loading="isSubmitting" type="submit" variant="primary">
			Save
		</BbButton>
	</BbForm>
</template>
```

The payload is the collected form values, keyed by each field's name — derived
from the control's `label` unless you set `vid`. `Full name` above arrives as
`fullname`; when two fields in one form would collide (rows in a `v-for`), give
those a `vid`.

### `isSubmitting` covers your submit, not just validation

Bind a button's `loading` to `isSubmitting` (or to `submitting` from
`useBbFormContext`) and it stays on for as long as your handler is actually
working — **return the promise** and the form waits for it:

```vue
<!-- the spinner runs until save() settles -->
<BbForm
	@submit="
		async (values) => {
			await api.save(values);
		}
	"
/>
```

A synchronous handler resolves immediately, as you would expect. If your
handler throws or rejects, the flag still clears (so the button never spins
forever) and the error is routed to `app.config.errorHandler`, the same place
Vue sends any other event-handler failure — so a global reporter keeps seeing
it.

> Fixed in 3.0.0-beta.15 (Q18.3). Before that, `isSubmitting` cleared as soon
> as _validation_ resolved, so the spinner flashed for a frame and the user
> could double-submit a save still in flight. If you worked around it with your
> own `saving` ref, you can drop it.

### `resetForm()` clears the fields, and your model

Resetting publishes the new value back through `update:modelValue`, so the
control, the form's own state and whatever ref you bound all agree afterwards.
The same holds for vee-validate's `resetField` and `setFieldValue`.

> Fixed in 3.0.0-beta.15 (Q18.4). Before that the value pipe only ran one way:
> a reset moved the form's internal value but never told your model, so the
> form reported itself pristine while the user's text was still on screen.

### Reading form state in the slot

The default slot is scoped, so the chrome around the fields can react without
lifting state into the page. It carries `values`, `isSubmitting`, `submitCount`,
`validate`, `resetForm`, plus vee-validate's own `meta` flags (`valid`, `dirty`,
`touched`, `pending`).

```vue
<template>
	<BbForm v-slot="{ dirty, valid, isSubmitting, resetForm }" @submit="save">
		<BbTextInput label="Display name" rules="required" />
		<BbTextarea label="Bio" rules="max:280" />

		<footer>
			<BbButton :disabled="!dirty" variant="ghost" @click="resetForm()">
				Discard
			</BbButton>
			<BbButton
				:disabled="!valid"
				:loading="isSubmitting"
				type="submit"
				variant="primary"
			>
				Save changes
			</BbButton>
		</footer>
	</BbForm>
</template>
```

Disabling submit on `!valid` is a choice, not a default: vee-validate marks a
pristine form invalid until its fields have been validated once, so a
disabled-until-valid button can read as broken on first paint. Leaving the
button enabled and letting the failed submit surface the messages is usually the
kinder flow — `valid` is there for wizards and dialogs where a dead-end step is
worse.

### Driving it from outside

When the submit action lives outside the form — a dialog footer, a page toolbar,
a leave guard — give the form an **explicit `id`** and read it with
`useBbFormContext(id)`. Same pattern as `useBbTableContext` /
`useBbDropdownContext`: no template ref, no shared subtree, no props threaded
through the layout.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbDialog } from 'bitboss-ui';
import { BbForm, BbTextInput, useBbFormContext } from 'bitboss-ui/validated';

const open = ref(false);
const invite = useBbFormContext('invite-teammate');
</script>

<template>
	<BbDialog v-model="open" title="Invite teammate">
		<BbForm id="invite-teammate" @submit="sendInvite">
			<BbTextInput label="Email" rules="required|email" type="email" />
		</BbForm>

		<template #footer>
			<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
			<BbButton
				:loading="invite.submitting.value"
				variant="primary"
				@click="invite.submit()"
			>
				Invite
			</BbButton>
		</template>
	</BbDialog>
</template>
```

The handle carries `valid`, `dirty`, `touched`, `pending`, `submitting`,
`submitCount`, `values` and `errors` as computeds, plus `submit()`, `reset()`
and `validate()`. It is callable **before** the form mounts — every field reads a
stable baseline and every action is a no-op until `isReady` flips — so a footer
that renders ahead of its dialog's content is fine.

Keep `@submit` as the place the work happens even then: `submit()` routes
through the same handler the button inside would, so validation gates the
request once and there is one code path, not two.

The id must be one you set. An auto-generated id cannot be targeted, and a form
with no `id` simply has no outside handle — which is the right default for a
self-contained form, where the slot scope already carries the same state.

### One validator, one set of messages

The rendered `<form>` carries **`novalidate`**. That is not a licence to skip
validation — it hands validation to vee-validate exclusively.

Without it the browser's own constraint validation runs first: a field with
`required`, `type="email"`, `pattern`, `maxlength` or `min`/`max` blocks the
submit event before `BbForm` ever sees it, shows a native bubble in the
browser's wording, and the form's real messages never render. The attributes
themselves are worth setting — `type="email"` gets the right mobile keyboard and
autofill, `required` is announced by screen readers — so the fix is not to drop
them; it is to stop the browser from gating submission. `novalidate` leaves
every attribute in the DOM and changes only who decides.

The consequence to know: a field inside `<BbForm>` that is **not** a
`bitboss-ui/validated` control is not validated at all — vee-validate only
knows about registered fields, and the browser has stepped aside. Import the
controls from `bitboss-ui/validated`, or give a bespoke field its own rule
through `useValidatedField`.

#### There is no template-ref handle

`BbForm` exposes exactly one thing — `$el`, the native `<form>` — and nothing
else, so a template ref gives you no `form.value.submitForm()` / `.isValid` /
`.validate()` / `.reset()`. That is deliberate, not an oversight: state and
actions live on `useBbFormContext(id)`, so there is no second,
instance-shaped API to keep in step with it. Use the context for all four.

The native form element is still right there, though — `$el` is public-instance
API and unaffected:

```vue
<script setup lang="ts">
import { useTemplateRef } from 'vue';

const form = useTemplateRef('form');
// The ref is the COMPONENT; requestSubmit is a DOM method, so it lives on $el.
const submitNatively = () =>
	(form.value?.$el as HTMLFormElement).requestSubmit();
</script>
```

`requestSubmit()` dispatches a real submit event, which the component handles
through the same `handleSubmit` — so validation still gates it and `@submit`
still fires only when every field passes. (`form.submit()`, the other native
method, bypasses event handlers entirely and would skip validation _and_ reload
the page. Never use it here.)

Prefer `useBbFormContext(id).submit()` anyway: it says what you mean, needs no
cast, and does not depend on the root element staying a `<form>`.

### Required markers

A field whose rules include `required` renders a red asterisk beside its label
automatically ([`BbAsterisk`](./BbAsterisk.md) does the drawing). You only place
that component yourself when you have replaced a control's `label` slot with
custom content — the wrapper hands you `showAsterisk` in the slot scope so the
marker stays consistent with the rules.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | `string \| undefined` |  |  | Explicit id, so anything outside the form can read and drive it through `useBbFormContext(id)` — a dialog footer's submit button, a page toolbar, a leave guard. Omit it when the form is self-contained: the slot scope already carries the sam… |

## Events

- `submit` — `(event: "submit", values: Record<string, unknown>): void`

## Slots

- `default` — scope: `{ touched: boolean; dirty: boolean; valid: boolean; pending: boolean; initialValues?: Partial<GenericObject> \| undefined; isSubmitting: boolean; resetForm: (st…`

## See Also

- [BbTextInput](./BbTextInput.md) — Captures single-line text values.
- [BbSelect](./BbSelect.md) — Selects one or many options from structured data.
- [BbCheckbox](./BbCheckbox.md) — Toggles a single boolean option.

---

<!-- dist/ai/BbIcon.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbIcon.md -->

# BbIcon

## Agent Contract

- Safety level: **Consumer API**
- Group: **Data Display**
- Description: Renders an icon either from the local icon folder or from a provider.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbIcon.md](./source/BbIcon.md)

## Usage & Guidelines

### When to reach for BbIcon

Most components render icons for you through props — `BbButton` and `BbBadge`
take `prepend:icon` / `append:icon` / `icon`; every batteries-included input
takes `prepend:icon` / `append:icon`; `BbAlert`, `BbToast` take `icon`;
`BbDropdown` items carry `'prepend:icon'` / `'append:icon'` fields. **Prefer
those** — they place, size and color the glyph to match the control, and keep the
markup declarative.

A handful of components have **no icon prop** and take icons through **slots**
instead — you place a `BbIcon` (or richer markup) yourself: `BbTabs` per-tab
`label-{key}` (or the generic `label` fallback), `BbBreadcrumbs` `item:prepend` /
`item:append` (or a per-`key` slot), `BbRating`'s `icon` slot, `BbSwitch`'s
`icon` slot. These have no `icon` _field_ on their items — the slot is the seam.

Reach for `BbIcon` **directly** only for standalone iconography the design owns:
a status glyph in a table cell, empty-state art, a custom list marker, or a
control you are composing yourself. Never wrap a `BbIcon` in your own `<button>`
to rebuild a button — use `BbButton` with `icon` plus a label (slot or `text`).
The full catalog of every icon-accepting surface lives in the **Icons Policy**
(`./icons-policy.md`); this guide is the primitive itself.

**Status glyph legend**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">API status</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Last checked 2 minutes ago
			</p>
		</div>
		<ul class="flex flex-col gap-1.5 text-sm">
			<li
				v-for="row in rows"
				:key="row.label"
				class="flex items-center gap-2"
				:class="row.tone"
			>
				<BbIcon :icon="row.icon" size="sm" />
				<span class="min-w-0 flex-1 truncate font-medium">{{ row.host }}</span>
				<span class="shrink-0 text-xs">{{ row.label }}</span>
			</li>
		</ul>
	</div>
</template>

<script setup lang="ts">
import { BbIcon, type IconType } from 'bitboss-ui';

type StatusRow = {
	host: string;
	label: string;
	icon: IconType;
	tone: string;
};

// Status glyph legend: each row owns a lucide literal and paints via
// `currentColor` on the parent — the design-owned BbIcon case. Glyphs are
// decorative (label sits beside them), so no `label` prop.
const rows: StatusRow[] = [
	{
		host: 'api.northwind.co',
		label: 'Operational',
		icon: 'lucide:circle-check',
		tone: 'status--ok',
	},
	{
		host: 'billing.northwind.co',
		label: 'Degraded',
		icon: 'lucide:triangle-alert',
		tone: 'status--warn',
	},
	{
		host: 'webhooks.northwind.co',
		label: 'Major outage',
		icon: 'lucide:circle-x',
		tone: 'status--danger',
	},
	{
		host: 'sandbox.northwind.co',
		label: 'No data',
		icon: 'lucide:circle-dashed',
		tone: 'status--muted',
	},
];
</script>

<style scoped>
/* Soft status accents mirror design-language.md § Using color (BbIndicator
   hues). Local --accent only — never mint --bb-* tokens from examples. */
.status--ok {
	--accent: #16a34a;
	color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
}

.status--warn {
	--accent: #d97706;
	color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
}

.status--danger {
	color: var(--bb-danger);
}

.status--muted {
	color: var(--bb-text-muted);
}
</style>
```

### Names: collections, local icons and the resolution grammar

The `icon` prop takes a name in one of three forms:

- **`provider:name`** — a glyph from an installed Iconify collection. This project
  ships no icon package of its own — install the ones you want. Prefer `lucide:`
  for UI glyphs when no direction is given, so one visual language stays
  consistent.
- **`local:name`** — an SVG in the configured `iconDir` (brand marks, custom
  illustrations). Each `.svg` file becomes `local:<basename>`.
- **bare `name`** — an unprefixed name **normalizes to `local:`**; it never
  searches provider sets. Prefer writing the prefix anyway: the Iconify editor
  extension keys off `prefix:name`, so `local:user-circle` gets an inline
  preview and name autocomplete in the template while a bare `user-circle`
  reads as an ordinary string and gets neither. It also puts your own art in
  the same shape as `mdi:home` / `lucide:check`, so the source of every icon is
  legible without inferring it from a missing prefix.

Discovery-first: **only use names you have verified exist** — a missing icon
**throws at mount** (dev shows an actionable Vite overlay with the exact
`npm install` fix). Never guess a name. See the Icons Policy for the discovery
workflow and the heroicons `-20-`/`-16-` size-variant caveat.

**The same glyph across collections, plus a local icon**

```vue
<div class="flex items-center gap-3">
	<div class="flex flex-col items-center gap-1">
		<BbIcon icon="lucide:heart" size="lg" />
		<span class="text-xs text-[color:var(--bb-text-muted)]">lucide</span>
	</div>
	<div class="flex flex-col items-center gap-1">
		<BbIcon icon="heroicons:heart" size="lg" />
		<span class="text-xs text-[color:var(--bb-text-muted)]">heroicons</span>
	</div>
	<div class="flex flex-col items-center gap-1">
		<BbIcon icon="mdi:heart" size="lg" />
		<span class="text-xs text-[color:var(--bb-text-muted)]">mdi</span>
	</div>
	<div class="flex flex-col items-center gap-1">
		<BbIcon icon="local:sparkles" size="lg" />
		<span class="text-xs text-[color:var(--bb-text-muted)]">local</span>
	</div>
</div>
```

`local:*` is for brand art in `iconDir`. The deploy card below cycles stages
with full `local:` literals from that folder — the canonical brand-mark demo.

**Every `local:` name in this guide is one of _this repository's_ fixture SVGs**
(`clock`, `loader`, `check_circle`, `alert_circle`, …). They are illustrative,
not a shipped set: copy the pattern, not the names. In your project a
`local:` name resolves only if `<name>.svg` exists in your own `iconDir`, and a
missing one throws at mount.

**Brand marks via local: — deploy stages**

```vue
<template>
	<div class="max-w-sm rounded-[var(--bb-radius)] border p-3">
		<div class="flex items-center justify-between gap-3">
			<div class="min-w-0">
				<p class="truncate text-sm font-medium">acme/storefront</p>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					Deploy #482 · production · {{ index + 1 }}/{{ stages.length }}
				</p>
			</div>
			<BbButton size="xs" variant="outline" @click="onAdvance"
				>Advance</BbButton
			>
		</div>
		<div class="mt-2 flex items-center gap-1.5 text-sm" :class="current.tone">
			<BbIcon :icon="current.icon" size="sm" />
			<span class="font-medium">{{ current.label }}</span>
		</div>
	</div>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbButton, BbIcon, type IconType } from 'bitboss-ui';

type Stage = {
	label: string;
	icon: IconType;
	tone: string;
};

// Brand marks via `local:*` (files in iconDir). Each stage owns a full static
// literal so the production scanner bundles it — never `local:${name}`. The
// glyph is decorative beside the stage label, so no `label` prop.
const stages: Stage[] = [
	{ label: 'Queued', icon: 'local:clock', tone: 'stage--muted' },
	{ label: 'Building', icon: 'local:loader', tone: 'stage--active' },
	{ label: 'Deployed', icon: 'local:check_circle', tone: 'stage--active' },
	{ label: 'Failed', icon: 'local:alert_circle', tone: 'stage--danger' },
];

const index = ref(0);
const current = computed(() => stages[index.value]);

const onAdvance = () => {
	index.value = (index.value + 1) % stages.length;
};
</script>

<style scoped>
.stage--muted {
	color: var(--bb-text-muted);
}

.stage--active {
	color: var(--bb-primary);
}

.stage--danger {
	color: var(--bb-danger);
}
</style>
```

#### The static-literal production constraint

Icon names **must be static string literals**. Production builds scan source for
`provider:name` literals and bundle only those — a name assembled at runtime
(`` `lucide:${kind}` ``) is invisible to the scanner and **missing in
production**. Map dynamic state to full literals instead — a lookup object of
complete names, exactly as the deploy-stages companion does (`stages[i].icon`
holds `'local:clock'`, not a concatenation). An icon used only in a
`.stories.ts` / `.test.ts` must also appear as a literal in a scanned source
file, since those are excluded from the scan.

```vue
<script setup lang="ts">
// Correct: full literals behind a lookup — the scanner sees each one.
const STATUS_ICON = {
	paid: 'lucide:circle-check',
	pending: 'lucide:clock',
	failed: 'lucide:circle-x',
} as const;
// Wrong: `lucide:${status}` — never bundled, broken in production.
</script>

<template>
	<BbIcon :icon="STATUS_ICON[status]" size="sm" />
</template>
```

#### Raw-SVG escape hatch

The `icon` prop **also accepts a full `<svg>…</svg>` string** — a public escape
hatch for a one-off brand mark that lives in no collection. Import the asset with
`?raw` and pass it straight through; `BbIcon` detects the SVG payload (it skips
the icon registry entirely), strips the outer `<svg>`/XML/doctype wrapper, and
re-renders the paths inside its own sized element, inheriting the source SVG's
`viewBox`. Use it sparingly — a real `local:` asset is preferable when the mark
will be reused. Here an empty state renders an app-bundled member mark (the
same asset `BbAvatar` uses as its fallback) at `2xl`; sizing and `currentColor`
behave exactly as with registry icons.

**Raw-SVG import as empty-state art**

```vue
<template>
	<div
		class="flex max-w-sm flex-col items-center gap-2 rounded-[var(--bb-radius)] border p-4 text-center"
	>
		<span class="text-[color:var(--bb-text-muted)]">
			<BbIcon :icon="memberMark" size="2xl" />
		</span>
		<p class="text-sm font-medium">No members yet</p>
		<p class="text-xs text-[color:var(--bb-text-muted)]">
			Invite your team to start assigning issues on Northwind.
		</p>
		<BbButton variant="primary">Invite member</BbButton>
	</div>
</template>

<script setup lang="ts">
import { BbButton, BbIcon } from 'bitboss-ui';
// One-off brand art outside any collection: `?raw` yields a full `<svg>`
// string that BbIcon accepts on `icon`. Outer wrapper is stripped; viewBox
// and `currentColor` still apply (muted parent here). Decorative under the
// headline — no `label`.
import memberMark from '@/assets/svgs/user.svg?raw';
</script>
```

### Sizing

`size` takes the icon scale `xs`–`2xl`, a number (px), or a CSS dimension string
(`"1.5rem"`, `"2em"`). The scale defaults to **12 / 16 / 24 / 28 / 36 / 40 px**
(`xs`→`2xl`) and is the same scale `BbAvatar` and the icon-bearing components
read; consumers can retune it **library-wide** via the plugin's
`iconDefaultSizes` option (`config.iconDefaultSizes`), so prefer the named scale
over hard pixel numbers to stay consistent with any override. An invalid `size`
logs a warning and falls back to `md`.

**The size scale**

```vue
<div class="flex items-end gap-3">
	<BbIcon icon="lucide:rocket" size="xs" />
	<BbIcon icon="lucide:rocket" size="sm" />
	<BbIcon icon="lucide:rocket" size="md" />
	<BbIcon icon="lucide:rocket" size="lg" />
	<BbIcon icon="lucide:rocket" size="xl" />
	<BbIcon icon="lucide:rocket" size="2xl" />
</div>
```

### Color: currentColor inheritance

Icons paint in `currentColor`, so they inherit the **text color of their
container**. Never set `color`/`fill` on the icon element — color the **parent**
via a token-driven utility class (or a soft status accent mixed toward
`--bb-panel` / `--bb-text`), and the glyph follows. The status legend and
deploy-stages companions both color the row wrapper; the icon tracks it.

### Config and platform

- **`iconDefaultSizes`** (Vite plugin / Nuxt module) — remaps the `xs`–`2xl`
  scale library-wide; the defaults above apply when unset.
- **Plugin required** — `BbIcon` resolves names through the
  `virtual:bitboss-ui/icons` module the platform plugin provides; without the
  Vue/Nuxt/Inertia plugin installed it throws a "Failed to load icons" error.
  Provider sets (`@iconify-json/*`) are auto-discovered from `node_modules`;
  `local:*` comes from `iconDir` (default `./assets/icons` on Nuxt).
- **SSR / Nuxt** — icons resolve during `onServerPrefetch`, so server-rendered
  markup contains the glyph on first paint (no hydration flash). `BbIcon` carries
  no navigation surface — it is a pure visual primitive.

### Works well with

- `BbButton` / `BbBadge` / inputs / `BbAlert` — prefer their icon
  props over a hand-placed `BbIcon`; the host sizes and aligns the glyph.
- `BbTabs` / `BbBreadcrumbs` / `BbRating` / `BbSwitch` — the slot surfaces where
  `BbIcon` is the intended way to inject a glyph (no icon field on their items).
- `BbAvatar` — shares the `iconDefaultSizes` scale, so icon and avatar sizes line
  up on the same scale keys.

### Gotchas & anti-patterns

- Hand-placing `BbIcon` where a component already accepts an icon via a prop or
  item field (only slots without an icon field are fair game).
- Runtime-composed names (template strings / concatenation) — invisible to the
  build scanner, broken in production. Use a lookup of full literals.
- Setting `color`/`fill` on the icon element instead of on the parent container.
- Wrapping `BbIcon` in a raw `<button>` — use `BbButton` with `icon` plus a
  label (default slot or `text`; `aria-label` only to override that name).
- Inventing icon names or assuming a provider set is installed without checking
  `package.json`.

### Accessibility

A meaningful icon needs a `label`: it adds `role="img"` and an `aria-label` —
no native `title`, so no browser tooltip ever appears; when a hover tooltip is
wanted, attach the `v-bb-tooltip` directive. Omit `label` for **decorative** icons that
sit beside a visible text label, so assistive tech does not announce the same
thing twice. `BbIcon` is **never focusable** (`focusable="false"` is always set)
— it is not interactive; interactivity belongs to the `BbButton`/`BbBaseButton`
wrapping it.

**Meaningful vs decorative**

```vue
<div class="flex items-center gap-3">
	<BbIcon icon="lucide:triangle-alert" size="lg" label="Warning" />
	<BbIcon icon="lucide:star" size="lg" />
</div>
```

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `icon` | `string` |  | yes | Name of a registered icon to use, or a full raw `<svg>` string (e.g. an SVG file imported with `?raw`). |
| `label` | `string \| undefined` |  |  | Label of the icon for accessibility. |
| `size` | `number \| ({ size?: any; } & string) \| keyof Sizes \| undefined` | `"md"` |  | Defines the component size. Accepted values: - A key from the provided size map (`keyof T`), e.g. `'sm' \| 'md' \| 'lg'` - A custom CSS size string (e.g. `'20px'`, `'1.5rem'`, `'2em'`) - A number, typically interpreted as pixels by size par… |

## Events

- None.

## Slots

- None.

## See Also

- [BbButton](./BbButton.md) — Button with loading state, tooltip, and icon support.
- [BbAvatar](./BbAvatar.md) — Displays an avatar and has a fallback content slot.

---

<!-- dist/ai/BbIndicator.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbIndicator.md -->

# BbIndicator

## Agent Contract

- Safety level: **Consumer API**
- Group: **Feedback**
- Description: Anchors a notification bubble (count/short text) or a dot over a wrapped element.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbIndicator.md](./source/BbIndicator.md)

## Usage & Guidelines

### When to use

`BbIndicator` pins a passive marker to the corner of another element: an unread
count on a bell button, a presence dot on an avatar, a "new" flag on a nav
item. It always wraps the element it decorates — put that element in the
**default slot** and the indicator positions itself over it.

Reach for a sibling instead when:

- the marker is an inline label or pill, not pinned over something → `BbBadge`;
- the token is removable (a filter, a selection) → a `clearable` `BbBadge`;
- it should be clickable → wrap a `BbButton` in the slot; the indicator itself
  is inert.

### Counts and dots

Give the indicator a `text` (a string or, for count ergonomics, a number) to
render a bubble, or `dot` for a plain presence marker with no content.

**A count and a presence dot**

```vue
<div class="flex items-center gap-5">
	<BbIndicator :text="4" variant="destructive">
		<BbButton variant="outline" icon="lucide:bell">Notifications</BbButton>
	</BbIndicator>
	<BbIndicator dot variant="success">
		<BbAvatar size="40">AL</BbAvatar>
	</BbIndicator>
</div>
```

The bubble scales in when it first appears. A count of `0` still renders ("0" is
content) — hide the marker by simply not passing `text` (bind
`count || undefined`); see Live counts.

Cap large counts with `max`: a numeric `text` above it renders as `${max}+`, so
you don't hand-format overflow. It only applies to numbers — string `text`
passes through untouched.

**Capping a count with max**

```vue
<div class="flex items-center gap-5">
	<BbIndicator :text="128" :max="99" variant="destructive">
		<BbButton variant="outline" icon="lucide:bell">Notifications</BbButton>
	</BbIndicator>
	<BbIndicator :text="8" :max="99" variant="destructive">
		<BbButton variant="outline" icon="lucide:mail">Inbox</BbButton>
	</BbIndicator>
</div>
```

`text` isn't limited to numbers — a short string works as a flag or tag. Keep it
brief; the bubble is a corner marker, not a label. Adjust size accordingly.

**A short text flag**

```vue
<div class="flex items-center gap-6">
	<BbIndicator text="New!" variant="success" size="xs">
		<BbButton variant="outline">Templates</BbButton>
	</BbIndicator>
	<BbIndicator text="Beta" variant="info" size="xs">
		<BbButton variant="outline">Playground</BbButton>
	</BbIndicator>
</div>
```

### Positioning

The bubble sits at the top-right corner by default. Two combinable booleans
move it:

- `bottom` — pin to the bottom edge instead of the top;
- `left` — pin to the left corner instead of the right.

**Corner placement**

```vue
<div class="flex items-center gap-6">
	<BbIndicator dot variant="success">
		<BbAvatar size="40">TR</BbAvatar>
	</BbIndicator>
	<BbIndicator dot bottom variant="warning">
		<BbAvatar size="40">TR</BbAvatar>
	</BbIndicator>
	<BbIndicator :text="9" left variant="info">
		<BbButton variant="outline" icon="lucide:git-branch">Branches</BbButton>
	</BbIndicator>
</div>
```

### Variants

`variant` maps to the shared status colors: `default` (primary), `success`,
`info`, `warning`, and `destructive`. Register more through the vite plugin's
`indicatorVariants` option — that extends the TypeScript union and gives you a
`.bb-indicator--<name>` hook to style (set `--bg` / `--color`).

**The status variants**

```vue
<div class="flex items-center gap-5">
	<BbIndicator :text="1" variant="default">
		<BbButton variant="outline" icon="lucide:bell">Default</BbButton>
	</BbIndicator>
	<BbIndicator :text="2" variant="success">
		<BbButton variant="outline" icon="lucide:check">Success</BbButton>
	</BbIndicator>
	<BbIndicator :text="3" variant="info">
		<BbButton variant="outline" icon="lucide:info">Info</BbButton>
	</BbIndicator>
	<BbIndicator :text="4" variant="warning">
		<BbButton variant="outline" icon="lucide:triangle-alert">Warning</BbButton>
	</BbIndicator>
	<BbIndicator :text="5" variant="destructive">
		<BbButton variant="outline" icon="lucide:x">Error</BbButton>
	</BbIndicator>
</div>
```

### Sizes

Indicators follow the shared `xs → 2xl` scale (default `md`; an invalid size
warns in dev and falls back to `md`). Match the indicator to the element it
decorates.

**The size scale**

```vue
<div class="flex items-center gap-5">
	<BbIndicator size="xs" :text="9" variant="destructive">
		<BbButton variant="outline" icon="lucide:bell">xs</BbButton>
	</BbIndicator>
	<BbIndicator size="md" :text="9" variant="destructive">
		<BbButton variant="outline" icon="lucide:bell">md</BbButton>
	</BbIndicator>
	<BbIndicator size="xl" :text="9" variant="destructive">
		<BbButton variant="outline" icon="lucide:bell">xl</BbButton>
	</BbIndicator>
</div>
```

### One-off colors

There is no `color` prop. To paint a single indicator outside the variant
system, override the same CSS custom properties the variants drive — `--bg` for
the fill and `--color` for the text — inline:

**A one-off accent via the --bg token**

```vue
<div class="flex items-center gap-5">
	<BbIndicator dot :style="{ '--bg': '#7c3aed' }">
		<BbAvatar size="40">ZK</BbAvatar>
	</BbIndicator>
	<BbIndicator :text="7" :style="{ '--bg': '#0891b2', '--color': '#fff' }">
		<BbButton variant="outline" icon="lucide:bell">Alerts</BbButton>
	</BbIndicator>
</div>
```

For anything recurring, register a variant instead so the styling stays in the
design system.

### Live counts

The indicator is passive — it reflects state you already track. Bind `text` and
omit it (bind `undefined`) to hide the marker when the count is zero. The
notification-bell companion is the canonical pattern: wrap an icon-only
`BbButton`, bind `:text="count || undefined"`, and let the bubble scale out
when the inbox clears.

**Notification bell with a live unread count**

```vue
<template>
	<div
		class="flex max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="min-w-0">
			<p class="truncate text-sm font-medium">Northwind</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">{{ statusLine }}</p>
		</div>
		<div class="flex items-center gap-1.5">
			<BbIndicator :text="count || undefined" variant="destructive">
				<BbButton icon="lucide:bell" variant="ghost">Notifications</BbButton>
			</BbIndicator>
			<BbButton size="xs" variant="secondary" @click="onNotify"
				>Notify</BbButton
			>
			<BbButton size="xs" variant="ghost" @click="onClear">Clear</BbButton>
		</div>
	</div>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbButton, BbIndicator } from 'bitboss-ui';

// Bind `count || undefined` so a zero count omits the bubble entirely instead
// of rendering "0". The indicator wraps the bell — never the reverse.
const count = ref(3);

const statusLine = computed(() =>
	count.value
		? `${count.value} unread notification${count.value === 1 ? '' : 's'}`
		: 'Inbox clear'
);

const onNotify = () => {
	count.value += 1;
};

const onClear = () => {
	count.value = 0;
};
</script>
```

### Works well with

- `BbAvatar` — a presence `dot`, or a role/count pinned to the avatar.
- `BbButton` with `icon` — the notification-bell pattern; the indicator wraps
  the button, never the reverse.
- `BbBadge` — the inline, non-anchored sibling for status pills and labels.

### Gotchas & anti-patterns

- The indicator is inert: no events, no `href`. If the marker should be
  clickable, wrap a `BbButton` in the default slot — don't attach handlers.
- `dot` takes precedence over `text`: a dotted indicator shows no number.
- A count of `0` renders as "0" — hide it by omitting `text`
  (`:text="count || undefined"`), not by passing `0`.
- For an inline label or removable token, use `BbBadge` (`clearable` for
  removable) — not an indicator with nothing wrapped.

### Accessibility

- The bubble carries `role="status"`, `aria-live="polite"`, and `aria-atomic`,
  so count changes are announced without extra wiring.
- The wrapped element keeps its own semantics — wrap an accessible control
  (e.g. a `BbButton` with a label) so the marker decorates something meaningful.
- Prefer a registered `variant` over a one-off inline `--bg`; a bare color
  carries no semantic meaning and no guaranteed contrast.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `bottom` | `boolean \| undefined` | `false` |  | Anchors the indicator to the bottom edge of the wrapped element instead of the top. |
| `dot` | `boolean \| undefined` | `false` |  | Renders a small contentless dot instead of a labelled bubble. Takes precedence over `text`. |
| `left` | `boolean \| undefined` | `false` |  | Anchors the indicator to the left edge of the wrapped element instead of the right. |
| `max` | `number \| undefined` |  |  | Caps a numeric `text` count: values above `max` render as `${max}+` (e.g. `max: 99` shows `99+`). Ignored for string `text`. |
| `size` | `keyof Sizes \| undefined` | `"md"` |  | Preset size of the indicator. |
| `text` | `string \| number \| undefined` |  |  | Content shown inside the indicator bubble. A `number` is accepted for count ergonomics (e.g. `:text="unread"`). When omitted the indicator renders only if `dot` is set. |
| `variant` | `keyof IndicatorVariantRegistry \| undefined` | `"default"` |  | Visual variant. `default` uses the primary color; `success`, `info`, `warning` and `destructive` map to the shared status colors. Register more via the vite plugin `indicatorVariants` option and style `.bb-indicator--<variant>`. |

## Events

- None.

## Slots

- `default` — scope: `object` — The element the indicator is anchored to.

## See Also

- [BbBadge](./BbBadge.md) — Displays a compact inline status counter or label. It sits in the flow — for a bubble or dot anchored OVER another element, use BbIndicator (includes the co-located BbBadgeButton export).
- [BbAvatar](./BbAvatar.md) — Displays an avatar and has a fallback content slot.

---

<!-- dist/ai/BbNumberInput.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbNumberInput.md -->

# BbNumberInput

## Agent Contract

- Safety level: **Consumer API**
- Group: **Inputs**
- Description: Captures and validates numeric form values, emits a number value.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbNumberInput.md](./source/BbNumberInput.md)

## Usage & Guidelines

### When to use

Use `BbNumberInput` whenever the value is a number the user edits directly:
quantities, prices, ages, thresholds, counts. It sanitises input as people type
(accepts commas as decimal separators, strips stray characters, keeps
in-progress states like `12.` or `-0.`), clamps to `min`/`max`, and emits a real
`number | null` — no manual parsing on your side. It shares the whole
input-family chrome (`label`, `description`, `hint`, `errors`, affixes,
`clearable`, `loading`) with `BbTextInput`, so it lines up in the same form.

Reach for a sibling instead when:

- the value is best chosen from a bounded range by dragging → `BbSlider`;
- it's a rating/score on a fixed scale → `BbRating`;
- it's really an identifier or code (leading zeros matter, no arithmetic) →
  `BbTextInput` with a `mask`.

Under the hood the control is a `<input type="text" inputmode="decimal"
role="spinbutton">`, not a native `type="number"` — which is why leading-zero
and locale-separator quirks of native number inputs don't apply here.

`v-model` accepts `number | string | null` and the component **emits
`number | null`** (a cleared field emits `null`, never `''` or `NaN`).

### Label & label modes

`label` is required, but it names the field for display and accessibility
only — it has **no** effect on the native `name` attribute. Leave `name`
unset and the rendered `<input>` carries none at all, so a plain form post
silently drops the value; pass `name` explicitly whenever it's submitted via
a native form or read from `FormData`. The shared label controls apply:

- **`labelMode`** sets where the label sits: `outside` (default, above),
  `floating` (rests inside like a placeholder, lifts on focus/fill) or `inside`
  (pinned small at the top of the field). Avoid pairing `floating` with a
  `placeholder` — the resting label already plays that role.
- **`hideLabel`** hides it visually but keeps the accessible name;
  **`labelPosition`** aligns the text; the **`label` slot** replaces it and
  receives `{ text, hasErrors }`.

When you don't set `labelMode`, the project-wide `config.defaultInputLabelMode`
applies (library default: `outside`) — the same fallback as `BbTextInput`, so a
project can go all-floating without touching call sites.

**Inventory counts — three label modes**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Inventory counts</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Same field, three label placements — pick one per product.
			</p>
		</div>
		<BbNumberInput
			v-model="outside"
			compact
			label="Outside (default)"
			:max-precision="0"
			:min="0"
		/>
		<BbNumberInput
			v-model="floating"
			compact
			label="Floating"
			label-mode="floating"
			:max-precision="0"
			:min="0"
		/>
		<BbNumberInput
			v-model="inside"
			compact
			label="Inside"
			label-mode="inside"
			:max-precision="0"
			:min="0"
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbNumberInput } from 'bitboss-ui';

const outside = ref<number | null>(24);
// Left empty so the floating label rests inside the field like a placeholder.
const floating = ref<number | null>(null);
const inside = ref<number | null>(8);
</script>
```

### Description, hint & validation

The same messaging surface as the rest of the family:

- **`description`** — always-visible text between label and field
  (`aria-describedby`), for instructions the user needs before typing.
- **`hint`** — shows below the field on focus; `persistentHint` pins it. Great
  for stating the range or unit.
- **`errors`** (string or string array) + **`hasErrors`** — render below the
  field in an `aria-live="polite"` region, are referenced first in the field's
  `aria-describedby` while present, and set `aria-invalid`. Because `min`
  and `max` already clamp silently, drive `errors` yourself when a value is
  business-invalid (e.g. "must be a multiple of 5").
- **`warnings`** — the amber counterpart of `errors`: a string or string array
  rendered below the field in its own `aria-live="polite"` region — and
  referenced from `aria-describedby` while displayed — in amber
  (`--bb-text-warn`), for a valid-but-noteworthy number (unusual, near a limit,
  soft-flagged) where a hard error would overstate the problem. A non-empty
  `warnings` implies the warning state, so **`hasWarning`** is just the
  force-the-chrome flag (tinted border, focus ring, warning icon) for when the
  message lives elsewhere — parallel to how `errors` relates to `hasErrors`.
  Unlike `errors`, `warnings` do **not** set `aria-invalid`, and `errors` win
  when both are set — the warning messages are suppressed, so the field never
  shows amber and red at once.
- **`required`** forwards to the native input.

**Team seats with hint and plan-cap error**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Team seats · Pro plan</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Hint states the range; business caps surface as errors.
			</p>
		</div>
		<BbNumberInput
			v-model="seats"
			compact
			hint="Billed per seat · 1–100 on Pro."
			label="Seats"
			:max="100"
			:max-precision="0"
			:min="1"
			name="seats"
			persistent-hint
		/>
		<BbNumberInput
			v-model="overCap"
			compact
			errors="Max 100 seats on this plan. Upgrade to Enterprise."
			label="Seats (over plan)"
			:max="100"
			:max-precision="0"
			:min="1"
			name="seats-over"
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbNumberInput } from 'bitboss-ui';

const seats = ref<number | null>(12);
const overCap = ref<number | null>(100);
</script>
```

### Bounds & precision

`min` and `max` clamp the **emitted** value — type past the ceiling and it
settles back to `max` (defaults are the safe-integer bounds, i.e. effectively
unbounded). `maxPrecision` caps the number of decimal places (default `8`),
which is how you pin a field to whole numbers (`0`) or currency (`2`). Commas are
accepted as the decimal separator and normalised to a period, so European
keyboards work without configuration.

**Clamped office setpoint, 16–28 °C**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Office climate · Floor 3</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Clamped 16–28 °C · whole degrees only.
			</p>
		</div>
		<BbNumberInput
			v-model="temperature"
			compact
			hint="Between 16 and 28 °C."
			label="Setpoint"
			:max="28"
			:max-precision="0"
			:min="16"
			name="setpoint"
			persistent-hint
			prepend:icon="lucide:thermometer"
		>
			<template #suffix>°C</template>
		</BbNumberInput>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbNumberInput } from 'bitboss-ui';

const temperature = ref<number | null>(21);
</script>
```

### Step controls

`step` (default `1`) is the increment applied by:

- **keyboard stepping** — ArrowUp / ArrowDown while the field is focused;
- the **`increase()` / `decrease()`** scope functions.

Those functions are handed to the `prepend` / `append` / `prefix` / `suffix`
slots as scope props, so you build a plus/minus stepper without wiring any state
yourself. For a stepper rendered _outside_ the field, drive `v-model` directly
(`model += step`) rather than reaching for a template ref. Stepping respects
`min`/`max`/`maxPrecision` and is a no-op while `disabled` or `readonly`.

Crucially, `step` is **not** applied to typed input — a `step` of `5` would
otherwise stop someone typing `115` (it would round down) — so manual entry
stays free while the buttons move in fixed increments.

**Cart quantity with plus/minus steppers**

```vue
<template>
	<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-3">
		<div>
			<p class="text-sm font-medium">USB-C Cable (2 m)</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				$12.50 each · 10 in stock
			</p>
		</div>
		<BbNumberInput
			v-model="quantity"
			compact
			label="Quantity"
			:max="10"
			:max-precision="0"
			:min="1"
			name="quantity"
		>
			<template #prepend="{ decrease }">
				<BbButton
					aria-label="Decrease quantity"
					icon="lucide:minus"
					size="xs"
					variant="ghost"
					@click="decrease"
				/>
			</template>
			<template #append="{ increase }">
				<BbButton
					aria-label="Increase quantity"
					icon="lucide:plus"
					size="xs"
					variant="ghost"
					@click="increase"
				/>
			</template>
		</BbNumberInput>
		<p class="text-sm font-medium">Subtotal: {{ formattedSubtotal }}</p>
	</div>
</template>
<script setup lang="ts">
import { ref, computed } from 'vue';
import { BbNumberInput, BbButton } from 'bitboss-ui';

const unitPrice = 12.5;
const quantity = ref<number | null>(1);

const formattedSubtotal = computed(() =>
	new Intl.NumberFormat('en-US', {
		style: 'currency',
		currency: 'USD',
	}).format((quantity.value ?? 0) * unitPrice)
);
</script>
```

### Currency & unit fields

Combine `maxPrecision="2"`, `min="0"` and the `prefix` / `suffix` slots for money
and measurement inputs. The affixes are inert decoration inside the field; the
model stays a clean number.

**Invoice unit price with currency affixes**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Line item · INV-2048</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Currency stays in the chrome; the model is a clean number.
			</p>
		</div>
		<BbNumberInput
			v-model="price"
			compact
			label="Unit price"
			:max-precision="2"
			:min="0"
			name="unit-price"
			:step="0.5"
		>
			<template #prefix>$</template>
			<template #suffix>USD</template>
		</BbNumberInput>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbNumberInput } from 'bitboss-ui';

const price = ref<number | null>(49.99);
</script>
```

### Icons, affixes & slots

`prepend:icon` / `append:icon` add iconography inside the field; the append
position is shared with the status indicators by priority — **clear button →
spinner (`loading`) → error icon (`hasErrors`) → your `append:icon`** — so don't
count on `append:icon` showing on a `clearable` or validated field. The warning
icon (`hasWarning`) shares the error icon's slot — shown when `hasWarning` is set
and there is no error.

Every content slot (`prefix`, `suffix`, `prepend`, `append`, `prepend-outer`,
`append-outer`) receives `{ increase, decrease }` scope, so stepper buttons can
live anywhere in the ring. Put interactive controls in the _outer_ slots or use
the scoped callbacks; plain `prefix`/`suffix` text is decoration only.

### Clearable & loading

`clearable` shows a clear button while the field has a value and is
hovered/focused; clicking it emits `update:modelValue` with `null` and is
suppressed on `disabled`/`readonly`. `loading` shows a spinner in the append
position and is visual only — the field stays editable, so guard the value
yourself if an async check must settle first.

**Clearable budget and async coupon check**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Invoice credit</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Clear the budget anytime; coupon check is visual-only loading.
			</p>
		</div>
		<BbNumberInput
			v-model="budget"
			clearable
			compact
			label="Budget"
			:max-precision="2"
			:min="0"
			name="budget"
		>
			<template #prefix>$</template>
		</BbNumberInput>
		<BbNumberInput
			v-model="coupon"
			compact
			:errors="couponError"
			:hint="couponHint"
			label="Coupon amount"
			:loading="checking"
			:max-precision="2"
			:min="0"
			name="coupon"
			persistent-hint
		>
			<template #prefix>$</template>
		</BbNumberInput>
	</div>
</template>
<script setup lang="ts">
import { ref, computed, watch } from 'vue';
import { BbNumberInput } from 'bitboss-ui';

const budget = ref<number | null>(2500);
const coupon = ref<number | null>(50);
const checking = ref(false);
const couponError = ref('');

const couponHint = computed(() =>
	checking.value ? 'Checking availability…' : 'Applied to your next invoice.'
);

// `loading` is visual only — the field stays editable — so we settle the async
// check ourselves and only surface an error once the deterministic timeout
// resolves. A token guards against a stale check overwriting a newer one.
const maxRedeemable = 200;
let token = 0;
watch(coupon, (value) => {
	const current = ++token;
	couponError.value = '';
	checking.value = true;
	setTimeout(() => {
		if (current !== token) return;
		checking.value = false;
		couponError.value =
			value !== null && value > maxRedeemable
				? `Coupons are capped at $${maxRedeemable}.`
				: '';
	}, 700);
});
</script>
```

### Disabled & readonly

`disabled` greys the field and blocks all interaction (`aria-disabled`);
`readonly` keeps the value visible and copyable but not editable
(`aria-readonly`). Both also disable `increase()` / `decrease()`. Prefer
`readonly` for detected or derived numbers the user shouldn't change.

**Error, disabled and readonly seats**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Seat allocation</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Error, disabled, and readonly — same chrome, different affordances.
			</p>
		</div>
		<BbNumberInput
			v-model="qtyErr"
			compact
			errors="Only 10 in stock."
			label="Quantity"
			:max="10"
			:max-precision="0"
			:min="1"
			name="qty-err"
		/>
		<BbNumberInput
			compact
			disabled
			label="Allocated seats"
			:max-precision="0"
			:model-value="64"
			name="allocated"
		/>
		<BbNumberInput
			compact
			label="Detected weight (kg)"
			:max-precision="1"
			:model-value="98.2"
			name="detected-weight"
			readonly
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbNumberInput } from 'bitboss-ui';

const qtyErr = ref<number | null>(12);
</script>
```

### Density & layout

`compact` reduces the control height — set it per view. `direction` works
whenever the resolved label mode is `'outside'` (the config default), so
`direction="horizontal"` lays the label beside the field out of the box. With
`labelMode="floating"` or `"inside"` (prop or `config.defaultInputLabelMode`)
the label is embedded in the field, so the layout is forced vertical and
`direction` is ignored — same rule as `BbTextInput`/`BbSelect`/
`BbDatePickerInput`.

**Compact shipping package fields**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
		<div>
			<p class="text-sm font-medium">Package · BOX-4412</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Shipping dimensions · compact density throughout.
			</p>
		</div>
		<BbNumberInput
			v-model="weight"
			compact
			label="Weight"
			:max-precision="1"
			:min="0"
			name="weight"
		>
			<template #suffix>kg</template>
		</BbNumberInput>
		<BbNumberInput
			v-model="units"
			compact
			label="Units in box"
			:max-precision="0"
			:min="1"
			name="units"
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbNumberInput } from 'bitboss-ui';

const weight = ref<number | null>(2.5);
const units = ref<number | null>(12);
</script>
```

Settings panels are where `direction="horizontal"` earns its keep: each numeric
limit reads as one dense row — label left, value right — the way rate-limit or
quota screens do it.

**API rate limits settings card**

```vue
<template>
	<div class="grid max-w-md gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">API rate limits</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Applied per key. Changes take effect immediately.
			</p>
		</div>
		<BbNumberInput
			v-model="requestsPerMinute"
			compact
			direction="horizontal"
			label="Requests / min"
			:max="10000"
			:max-precision="0"
			:min="10"
			name="rpm"
			:step="10"
		/>
		<BbNumberInput
			v-model="burstLimit"
			compact
			direction="horizontal"
			label="Burst limit"
			:max="20000"
			:max-precision="0"
			:min="10"
			name="burst"
			:step="10"
		/>
		<BbNumberInput
			v-model="timeoutSeconds"
			compact
			direction="horizontal"
			label="Timeout"
			:max="120"
			:max-precision="0"
			:min="1"
			name="timeout"
		>
			<template #suffix>s</template>
		</BbNumberInput>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbNumberInput } from 'bitboss-ui';

const requestsPerMinute = ref<number | null>(500);
const burstLimit = ref<number | null>(1000);
const timeoutSeconds = ref<number | null>(30);
</script>
```

### Events & v-model

- `update:modelValue` — `number` on any change, `null` when emptied. In-progress
  non-numeric states (`.`, `-`, `12.`) do **not** emit a number; the field waits
  until the value parses.
- `increase` / `decrease` — fire with the **new** clamped number whenever a step
  control runs (slot button or Arrow key), alongside `update:modelValue`.
- `focus` / `blur` — forwarded, and drive the hint's show-on-focus behavior.
- `input`, `change`, `keydown`, `keyup`, `click`, `mousedown`, `mouseup`,
  `compositionstart`, `compositionend`, `paste` — all forwarded as-is (a fuller
  set than `BbTextInput`, which doesn't forward keyup/paste/composition).

### Global config & platforms

- No size scale — `compact` is the density knob. `labelMode` falls back to
  `config.defaultInputLabelMode` when unset, like `BbTextInput`.
- Plain controlled input: SSR-safe in Nuxt, nothing teleported.
- Inertia validation binds straight in:

```vue
<!-- Inertia: useForm drives value and errors -->
<BbNumberInput
	v-model="form.quantity"
	label="Quantity"
	:min="1"
	:errors="form.errors.quantity"
	:has-errors="!!form.errors.quantity"
/>
```

### Works well with

- `BbSlider` — when a bounded number is better dragged than typed, or pair the
  two on the same model for coarse + precise entry.
- `BbTextInput` / `BbTextarea` / `BbDatePickerInput` — same chrome; mix in one
  form (the `BbTextInput` invoice example composes all four).
- `BbButton` — icon-only stepper buttons in the slot ring (give them an
  `aria-label`).
- `useToast` — confirm a save once the number is committed.

### Gotchas & anti-patterns

- `step` never constrains typed input — don't expect a `step` of `5` to force
  multiples on manual entry; enforce that with `errors` on blur/submit.
- The model can be `null` (empty) — write `value ?? 0` before arithmetic.
- Don't rebuild parsing/clamping in a watcher; the component already sanitises,
  clamps and limits precision.
- Icon-only stepper buttons **require** an `aria-label`.
- `direction` is ignored under `labelMode="floating"`/`"inside"` — those modes
  embed the label in the field and force the vertical layout; it works with the
  default `'outside'` mode.

### Accessibility

- The field carries `role="spinbutton"` and mirrors `min` / `max` / current
  value into `aria-valuemin` / `aria-valuemax` / `aria-valuenow`, so keep `min`
  and `max` set when the range is known.
- ArrowUp / ArrowDown step the value natively — don't rebuild that with custom
  key handlers.
- `hasErrors` / non-empty `errors` set `aria-invalid`; `disabled` / `readonly`
  set `aria-disabled` / `aria-readonly`.
- Slot-based stepper buttons are icon-only, so they **require** an `aria-label`
  (see the stepper example).

## v-model

- `v-model` — type: `string \| number \| null`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
| `autocomplete` | `string \| undefined` |  |  | Guides the browser as to the type of information expected in the field. |
| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
| `clearable` | `boolean \| undefined` | `false` |  | Displays a clear button when the input has a value and is being interacted with. |
| `compact` | `boolean \| undefined` | `false` |  | Sets the component in a compact state. |
| `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
| `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `label` | `string` |  | yes | Text content of the label of the element. |
| `labelMode` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Label rendering mode. |
| `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
| `loading` | `boolean \| undefined` | `false` |  | Sets the component in a loading state, usually triggering some visual styles. |
| `max` | `number \| undefined` |  |  | Maximum value cap. |
| `maxPrecision` | `number \| undefined` |  |  | Maximum precision of the number. |
| `min` | `number \| undefined` |  |  | Minimum value cap. |
| `modelValue` | `string \| number \| null` | `null` | yes | Used by v-model. |
| `name` | `string \| undefined` |  |  | Defines the name of the input. |
| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
| `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
| `step` | `number \| undefined` |  |  | Incremental unit used in the exposed `increase` and `decrease` functions. It is NOT applied to manual input as a step of 5 would prevent the user from inserting a value like `115` because of rounding down. |
| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |

## Events

- `blur` — `(event: "blur", event: FocusEvent): void`
- `change` — `(event: "change", event: Event): void`
- `click` — `(event: "click", event: MouseEvent): void`
- `compositionend` — `(event: "compositionend", event: CompositionEvent): void`
- `compositionstart` — `(event: "compositionstart", event: CompositionEvent): void`
- `decrease` — `(event: "decrease", value: number): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `increase` — `(event: "increase", value: number): void`
- `input` — `(event: "input", event: Event): void`
- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
- `keyup` — `(event: "keyup", event: KeyboardEvent): void`
- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
- `paste` — `(event: "paste", event: ClipboardEvent): void`
- `update:modelValue` — `(event: "update:modelValue", value: number \| null): void`

## Slots

- `append` — scope: `BaseNumberInputStepSlotProps` — Content rendered after the number input, at the end of the inner container. Typically used to place increment/decrement buttons next to the input.
- `append-outer` — scope: `BaseNumberInputStepSlotProps` — Content rendered after the entire input control, outside the input chrome.
- `label` — scope: `BbNumberInputLabelSlotProps` — Replaces the default label text rendered above the number input.
- `prefix` — scope: `BaseNumberInputStepSlotProps` — Inline content rendered at the start of the input field area, before the typed number.
- `prepend` — scope: `BaseNumberInputStepSlotProps` — Content rendered before the number input, at the start of the inner container.
- `prepend-outer` — scope: `BaseNumberInputStepSlotProps` — Content rendered before the entire input control, outside the input chrome.
- `suffix` — scope: `BaseNumberInputStepSlotProps` — Inline content rendered at the end of the input field area, after the typed number.

## Validated variant

Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).

| Prop | Type | Description |
| --- | --- | --- |
| `rules` | `RuleExpression<string \| number \| null>` | vee-validate rules for this field. |
| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |

## See Also

- [BbTextInput](./BbTextInput.md) — Captures single-line text values.
- [BbSlider](./BbSlider.md) — Selects numeric values across a bounded range.
- [BbDatePickerInput](./BbDatePickerInput.md) — Combines date selection with text input behavior.

---

<!-- dist/ai/BbOffCanvas.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbOffCanvas.md -->

# BbOffCanvas

## Agent Contract

- Safety level: **Consumer API**
- Group: **Overlay**
- Description: Shows side-panel overlay content outside normal layout flow.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbOffCanvas.md](./source/BbOffCanvas.md)

## Usage & Guidelines

### When to use

Reach for `BbOffCanvas` for **supplementary content that lives beside the main
task**: a filter panel, a record's detail view, a settings drawer, a
notifications tray. It slides in from an edge, dims the page, and leaves as
quickly as it came — the user is topping up context, not switching tasks.

Choose a sibling when the intent differs:

- A single focused task the user must finish (a form, a confirm, an
  announcement) → `BbDialog` (centered modal).
- A plain yes/no or destructive confirm → `BbConfirm` with `useConfirm`.
- A small anchored menu or bit of interactive content → `BbPopover`.

`BbDialog` and `BbOffCanvas` share most of their API (v-model, `title`, the
`header` / `default` / `footer` slots, `persistent`, `disabled`, `hide-close`,
`focus-target`, `eager`, `stack`, `transition-duration`, and the four lifecycle
events), so moving a surface between them is mostly a tag swap. The differences
are physical: `size` means the panel's **extent along its axis** (not a max
width), and `side`, `draggable` and `stack-gap` are off-canvas-only.

### Open and close with v-model

`v-model` owns visibility — there is no imperative `open()`. Bind a boolean and
flip it. The panel dismisses itself on the header close button, the `Escape`
key, and a backdrop click; the `default` slot also receives a `close` callback
for buttons inside the body, and footer buttons simply set the model back to
`false`.

**A right-hand panel**

```vue
<template>
	<div
		class="flex max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="min-w-0">
			<p class="m-0 text-sm font-medium">Workspace</p>
			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
				3 updates since yesterday
			</p>
		</div>
		<BbButton variant="outline" @click="open = true">Open activity</BbButton>
	</div>
	<BbOffCanvas v-model="open" side="right" title="Recent activity">
		<template #default="{ close }">
			<div class="grid gap-3 text-sm">
				<div v-for="entry in activity" :key="entry.id" class="grid gap-0.5">
					<p class="m-0">{{ entry.text }}</p>
					<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
						{{ entry.when }}
					</p>
				</div>
				<BbButton class="justify-self-start" variant="ghost" @click="close">
					Close
				</BbButton>
			</div>
		</template>
	</BbOffCanvas>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbOffCanvas } from 'bitboss-ui';

type ActivityEntry = {
	id: number;
	text: string;
	when: string;
};

const open = ref(false);

const activity: ActivityEntry[] = [
	{
		id: 1,
		text: 'Invoice #INV-2043 was paid.',
		when: '12 minutes ago',
	},
	{
		id: 2,
		text: 'Maria commented on “Q3 report”.',
		when: '1 hour ago',
	},
	{
		id: 3,
		text: 'Webhook delivery to Stripe succeeded.',
		when: 'Yesterday · 16:42',
	},
];
</script>
```

### Direction

`side` sets the edge the panel enters from — `left`, `right`, `top`, or
`bottom` (default `left`). Use `right` for detail and filter panels that sit
beside a right-aligned action flow, `bottom` for mobile-style sheets, `top` for
banners and command surfaces. The side also decides the drag axis and which
dimension `size` controls.

**Enter from any edge**

```vue
<template>
	<div
		class="flex max-w-md flex-wrap gap-2 rounded-[var(--bb-radius)] border p-3"
	>
		<BbButton
			v-for="edge in edges"
			:key="edge"
			variant="outline"
			@click="activeSide = edge"
		>
			{{ edge }}
		</BbButton>
		<BbOffCanvas
			:model-value="activeSide !== null"
			:side="activeSide ?? 'right'"
			:title="`From ${activeSide ?? 'right'}`"
			@update:model-value="
				(value) => {
					if (!value) activeSide = null;
				}
			"
		>
			<p class="m-0 text-sm">
				This panel slid in from the <strong>{{ activeSide }}</strong> edge.
			</p>
		</BbOffCanvas>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbOffCanvas } from 'bitboss-ui';

type Side = 'left' | 'top' | 'right' | 'bottom';

const edges: Side[] = ['left', 'right', 'top', 'bottom'];
const activeSide = ref<Side | null>(null);
</script>
```

### Header, footer and body

A `title` prop renders the standard header (title text + close button) and wires
`aria-labelledby` for you. Put content in the `default` slot and actions in the
`footer` slot. The body area scrolls internally when content overflows; the
header and footer stay pinned.

- Use the `title` slot to restyle just the title text — it stays wired to
  `aria-labelledby` and receives the `title` prop as `text`.
- The **`header` slot** replaces the whole header section; it receives
  `titleId`, `title` and `close`, so you can build a custom header and still
  keep the accessible name wired through `titleId`. `BbDialog` supports the
  same slot with the same payload, and forwards it to its adaptive sheet — the
  two surfaces are symmetric here.
- Omitting `title` (and the `header` slot) removes the header entirely — you
  then own the accessible name.

### A filters drawer

The archetypal off-canvas: search + toggles in the `default` slot, Apply/Reset
in the `footer`. Keep one primary action (Apply) and align actions to the end.
This companion seeds typed filter state and resets it in place.

**Invoice filters**

```vue
<template>
	<div
		class="flex max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="min-w-0">
			<p class="m-0 text-sm font-medium">Invoices</p>
			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
				{{ matchingLabel }}
			</p>
		</div>
		<BbButton
			prepend:icon="lucide:sliders-horizontal"
			variant="outline"
			@click="open = true"
		>
			Filters
		</BbButton>
	</div>
	<BbOffCanvas v-model="open" side="right" title="Filter invoices">
		<div class="grid gap-3">
			<BbTextInput
				v-model="filters.query"
				compact
				label="Search"
				placeholder="Invoice #, customer…"
			/>
			<BbCheckbox v-model="filters.overdue" label="Only overdue" />
			<BbCheckbox v-model="filters.unpaid" label="Only unpaid" />
		</div>
		<template #footer>
			<div class="flex justify-end gap-2">
				<BbButton variant="ghost" @click="reset">Reset</BbButton>
				<BbButton variant="primary" @click="open = false">Apply</BbButton>
			</div>
		</template>
	</BbOffCanvas>
</template>
<script setup lang="ts">
import { computed, reactive, ref } from 'vue';
import { BbButton, BbCheckbox, BbOffCanvas, BbTextInput } from 'bitboss-ui';

type InvoiceFilterState = {
	query: string;
	overdue: boolean;
	unpaid: boolean;
};

const open = ref(false);
const filters = reactive<InvoiceFilterState>({
	query: '',
	overdue: false,
	unpaid: true,
});

const activeCount = computed(() => {
	let count = 0;
	if (filters.query.trim()) count += 1;
	if (filters.overdue) count += 1;
	if (filters.unpaid) count += 1;
	return count;
});

const matchingLabel = computed(() => {
	const n = activeCount.value;
	if (n === 0) return '48 total · no filters';
	return `12 matching · ${n} filter${n === 1 ? '' : 's'} on`;
});

/** Clear every filter back to the empty baseline. */
const reset = () => {
	filters.query = '';
	filters.overdue = false;
	filters.unpaid = false;
};
</script>
```

### A record inspector

The other archetype: a record's detail view opened beside a list, so the user
keeps their place in the table. Open from a row, show identity + status + key
fields in a `right`-hand panel, and let footer actions navigate or close. This
companion opens an inspector per selected member and offloads the "open full
record" action to `BbButton`'s `href` rather than a click handler.

**Record inspector**

```vue
<template>
	<div class="grid max-w-sm gap-1 rounded-[var(--bb-radius)] border p-1">
		<p
			class="m-0 px-2 pt-1.5 text-xs font-medium text-[color:var(--bb-text-muted)]"
		>
			Members
		</p>
		<BbButton
			v-for="member in members"
			:key="member.id"
			class="justify-start"
			size="sm"
			variant="ghost"
			@click="openDetail(member)"
		>
			<span class="flex min-w-0 items-center gap-2">
				<BbAvatar
					:alt="member.name"
					size="32"
					:src="member.src"
					:timeout="demoAvatarTimeout"
				>
					{{ member.initials }}
				</BbAvatar>
				<span class="truncate">{{ member.name }}</span>
			</span>
		</BbButton>
	</div>
	<BbOffCanvas v-model="open" side="right" size="sm" :title="selected?.name">
		<div v-if="selected" class="grid gap-4 text-sm">
			<div class="flex items-start gap-3">
				<BbAvatar
					:alt="selected.name"
					size="56"
					:src="selected.src"
					:timeout="demoAvatarTimeout"
				>
					{{ selected.initials }}
				</BbAvatar>
				<div class="grid min-w-0 gap-1.5">
					<p class="m-0 font-medium">{{ selected.role }}</p>
					<BbBadge size="sm" :variant="selected.statusVariant">
						{{ selected.status }}
					</BbBadge>
				</div>
			</div>
			<dl class="m-0 grid gap-2">
				<div
					v-for="row in detailRows"
					:key="row.label"
					class="flex items-baseline justify-between gap-3"
				>
					<dt class="shrink-0 text-xs text-[color:var(--bb-text-muted)]">
						{{ row.label }}
					</dt>
					<dd class="m-0 truncate text-right">{{ row.value }}</dd>
				</div>
			</dl>
		</div>
		<template #footer>
			<div class="flex justify-end gap-2">
				<BbButton variant="ghost" @click="open = false">Close</BbButton>
				<BbButton
					append:icon="lucide:arrow-right"
					:href="`#member-${selected?.id}`"
					variant="primary"
				>
					Open full record
				</BbButton>
			</div>
		</template>
	</BbOffCanvas>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbAvatar, BbBadge, BbButton, BbOffCanvas } from 'bitboss-ui';
import {
	demoAvatarTimeout,
	demoFaces,
} from '@/components/BbAvatar/examples/demoAvatars';

type MemberStatus = 'Active' | 'Away';

type Member = {
	id: number;
	name: string;
	initials: string;
	role: string;
	email: string;
	joined: string;
	team: string;
	status: MemberStatus;
	statusVariant: 'soft-green' | 'soft-amber';
	src?: string;
};

const members: Member[] = [
	{
		id: 1,
		name: 'Ada Lovelace',
		initials: 'AL',
		role: 'Lead engineer',
		email: 'ada@northwind.co',
		joined: 'Mar 2021',
		team: 'Platform',
		status: 'Active',
		statusVariant: 'soft-green',
		src: demoFaces.ada,
	},
	{
		id: 2,
		name: 'Grace Hopper',
		initials: 'GH',
		role: 'Principal engineer',
		email: 'grace@northwind.co',
		joined: 'Sep 2019',
		team: 'Billing',
		status: 'Away',
		statusVariant: 'soft-amber',
		src: demoFaces.grace,
	},
];

const open = ref(false);
const selected = ref<Member | null>(null);

const detailRows = computed(() => {
	const member = selected.value;
	if (!member) return [];
	return [
		{ label: 'Email', value: member.email },
		{ label: 'Team', value: member.team },
		{ label: 'Joined', value: member.joined },
	];
});

/** Open the inspector for the chosen member beside the list. */
const openDetail = (member: Member) => {
	selected.value = member;
	open.value = true;
};
</script>

<!-- Non-scoped: soft status palette for the inspector badge.
     Canonical source: ai/guides/design-language.md § Using color. -->
<style>
.bb-badge.bb-badge--soft-green {
	--accent: #16a34a;
}
.bb-badge.bb-badge--soft-amber {
	--accent: #d97706;
}
.bb-badge.bb-badge--soft-green,
.bb-badge.bb-badge--soft-amber {
	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
	--border-width: 1px;
	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
}
</style>
```

### A mobile nav sheet

The third classic: app navigation behind a menu button. A `left` drawer at
`size="xs"` reads as the familiar mobile nav; every destination is a real link
(`href` — hash-only here, in an app pass `to` for the router), never an
`@click` handler. Icon names live as typed literals on the nav data and flow
into `BbButton`'s `prepend:icon`; the active route gets the one non-ghost
treatment in the list, and account/sign-out sit in the footer.

**Mobile navigation sheet**

```vue
<template>
	<div
		class="flex max-w-sm items-center justify-between gap-2 rounded-[var(--bb-radius)] border p-2"
	>
		<div class="min-w-0">
			<p class="m-0 truncate text-sm font-medium">Acme Billing</p>
			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">Workspace</p>
		</div>
		<BbButton
			aria-label="Open navigation"
			icon="lucide:menu"
			variant="outline"
			@click="open = true"
		>
			Menu
		</BbButton>
	</div>
	<BbOffCanvas v-model="open" side="left" size="xs" title="Acme Billing">
		<nav aria-label="Primary" class="grid gap-1">
			<p
				class="m-0 px-1 pb-0.5 text-xs font-medium text-[color:var(--bb-text-muted)]"
			>
				Navigate
			</p>
			<BbButton
				v-for="item in navItems"
				:key="item.href"
				class="justify-start"
				:href="item.href"
				:prepend:icon="item.icon"
				size="sm"
				:variant="item.active ? 'secondary' : 'ghost'"
			>
				{{ item.label }}
			</BbButton>
		</nav>
		<template #footer>
			<div class="grid gap-1">
				<BbButton
					class="w-full justify-start"
					href="#account"
					prepend:icon="lucide:circle-user"
					size="sm"
					variant="ghost"
				>
					Alex Rivera
				</BbButton>
				<BbButton
					class="w-full justify-start"
					href="#sign-out"
					prepend:icon="lucide:log-out"
					size="sm"
					variant="ghost"
				>
					Sign out
				</BbButton>
			</div>
		</template>
	</BbOffCanvas>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbOffCanvas, type IconType } from 'bitboss-ui';

type NavItem = {
	label: string;
	href: string;
	icon: IconType;
	active?: boolean;
};

const open = ref(false);

const navItems: NavItem[] = [
	{
		label: 'Dashboard',
		href: '#dashboard',
		icon: 'lucide:house',
		active: true,
	},
	{ label: 'Invoices', href: '#invoices', icon: 'lucide:receipt' },
	{ label: 'Customers', href: '#customers', icon: 'lucide:users' },
	{ label: 'Reports', href: '#reports', icon: 'lucide:chart-line' },
	{ label: 'Settings', href: '#settings', icon: 'lucide:settings' },
];
</script>
```

### Size and `auto`

`size` runs the shared `xs`–`2xl` scale **plus `auto`**, and controls the
panel's extent along its travel axis — width for `left`/`right`, height for
`top`/`bottom`. The presets map to `config.offCanvasDefaultSizes` (320px for
`xs` up to 672px for `2xl`; the default `sm` is 384px, overridable in the plugin
options). A number is pixels, a string passes through as a CSS size, and `auto`
hugs the content (`fit-content`) — the basis of a content-sized sheet.

Give it a per-breakpoint map to switch responsively without media queries of
your own. Like `BbDialog`, a **bare size is resolved once**; only the map form
reacts to live resizes.

**Responsive extent**

```vue
<div>
	<BbButton variant="outline" @click="state.open = true">Settings</BbButton>
	<BbOffCanvas
		v-model="state.open"
		side="right"
		:size="{ default: 'sm', lg: 'lg' }"
		title="Settings"
	>
		<p class="m-0 text-sm">
			<strong>sm</strong> (384px) on smaller viewports, <strong>lg</strong>
			(512px) from the <code>lg</code> breakpoint up — resize to see it switch.
		</p>
	</BbOffCanvas>
</div>
```

### Draggable sheets

Set `draggable` to let the user flick the panel toward its edge to dismiss; a
grab handle appears on the inner edge as the affordance. A draggable,
`auto`-sized bottom panel is the canonical mobile sheet.

The gesture is physical, not just a tap target:

- Dragging past **a quarter of the panel's extent**, or a fast **flick toward
  the edge**, dismisses it; a shorter drag springs back to fully open.
- On a vertical (top/bottom) sheet with a scrollable body, the drag **hands off
  to native scrolling** first — you only start dragging the sheet once the body
  is scrolled to its edge, so scrolling a long sheet never accidentally closes
  it.
- `persistent` / `disabled` still win: a drag that would dismiss instead plays
  the "deny" nudge and springs back.

**A draggable bottom sheet**

```vue
<div>
	<BbButton variant="outline" @click="state.open = true">Share</BbButton>
	<BbOffCanvas
		v-model="state.open"
		side="bottom"
		draggable
		size="auto"
		title="Share invoice"
	>
		<div class="flex flex-wrap gap-2">
			<BbButton append:icon="lucide:link" variant="outline">Copy link</BbButton>
			<BbButton append:icon="lucide:mail" variant="outline">Email</BbButton>
			<BbButton append:icon="lucide:download" variant="outline">Download PDF</BbButton>
		</div>
	</BbOffCanvas>
</div>
```

### Stacking drill-downs

Give panels the same `stack` name and they step back behind one another as you
drill in: opening a child shifts the parent inward by `stack-gap` (default
`60`px), leaving a peeking band of it visible so the hierarchy reads clearly.
Closing the child brings the parent forward. Panels with **different names (or
none) are independent** and simply layer by open order.

Only the top two open panels keep their dimmed/blurred backdrop; deeper ones go
transparent, so a three-deep stack does not stack three backdrops. Use a stack
for master → detail flows where the trail should stay visible; if the parent
should be fully replaced instead, that is what `BbDialog`'s `stack` (which swaps
rather than peeks) is for.

**Master → detail, stacked**

```vue
<template>
	<div
		class="flex max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="min-w-0">
			<p class="m-0 text-sm font-medium">Team</p>
			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
				Drill into a member
			</p>
		</div>
		<BbButton variant="outline" @click="listOpen = true">
			Team members
		</BbButton>
	</div>
	<BbOffCanvas
		v-model="listOpen"
		side="right"
		stack="team"
		:stack-gap="72"
		title="Team members"
	>
		<div class="grid gap-1">
			<BbButton
				v-for="member in members"
				:key="member.name"
				class="justify-start"
				size="sm"
				variant="ghost"
				@click="openDetail(member)"
			>
				{{ member.name }}
			</BbButton>
		</div>
	</BbOffCanvas>
	<BbOffCanvas
		v-model="detailOpen"
		side="right"
		stack="team"
		:stack-gap="72"
		:title="selected?.name"
	>
		<div v-if="selected" class="grid gap-2 text-sm">
			<p class="m-0">
				<span class="text-xs text-[color:var(--bb-text-muted)]">Role</span
				><br />
				{{ selected.role }}
			</p>
			<p class="m-0">
				<span class="text-xs text-[color:var(--bb-text-muted)]">Joined</span
				><br />
				{{ selected.joined }}
			</p>
		</div>
	</BbOffCanvas>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbOffCanvas } from 'bitboss-ui';

type Member = { name: string; role: string; joined: string };

const members: Member[] = [
	{ name: 'Ada Lovelace', role: 'Lead engineer', joined: 'Mar 2021' },
	{ name: 'Grace Hopper', role: 'Principal engineer', joined: 'Sep 2019' },
];

const listOpen = ref(false);
const detailOpen = ref(false);
const selected = ref<Member | null>(null);

/** Push the detail drawer onto the shared stack. */
const openDetail = (member: Member) => {
	selected.value = member;
	detailOpen.value = true;
};
</script>
```

### Fullscreen

`fullscreen` expands the panel to fill the viewport (minus the standard page
padding — it is intentionally not edge-to-edge), which suits content-heavy
detail views. Pass `fullscreen="mobile"` to go fullscreen only below the mobile
breakpoint (`config.mobileMaxWidth`, 768px) while keeping the sized panel on
desktop — the usual choice for a `right` detail panel that should take the whole
screen on a phone.

**Fullscreen on mobile only**

```vue
<div>
	<BbButton variant="outline" @click="state.open = true">Open article</BbButton>
	<BbOffCanvas
		v-model="state.open"
		side="right"
		fullscreen="mobile"
		size="md"
		title="Release notes"
	>
		<p class="m-0 text-sm">
			Sized (md) on desktop, full-screen below the mobile breakpoint.
		</p>
	</BbOffCanvas>
</div>
```

### Lifecycle events and lazy content

Four events bracket the transitions — `show` fires as the model turns `true`,
`shown` after the native `showModal()` call and initial focus, `hide` as the
model turns `false`, and `hidden` after the close transition completes. Use
`@show` to (re)seed form state, `@hidden` to tear down expensive content.

Body content is **lazy**: nothing inside the panel renders until the first open.
Set `eager` to render it immediately (e.g. so a chart can pre-measure, or tests
can query content before opening). `transition-duration` (ms, default `250`)
times both the slide animation and when `hidden` fires — reopening during the
close transition keeps the panel open instead of snapping shut.

The classic `@show` job is reseeding a draft: reset the working copy from the
last saved value every time the panel opens, so Cancel is a real discard —
half-typed edits never survive a close.

**Reseed a draft with @show**

```vue
<template>
	<div
		class="flex max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="min-w-0">
			<p class="m-0 text-sm font-medium">INV-2043</p>
			<p class="m-0 truncate text-xs text-[color:var(--bb-text-muted)]">
				{{ saved }}
			</p>
		</div>
		<BbButton variant="outline" @click="open = true">Add note</BbButton>
	</div>
	<BbOffCanvas
		v-model="open"
		side="right"
		title="Note · INV-2043"
		@show="draft = saved"
	>
		<BbTextarea v-model="draft" auto-grow compact label="Internal note" />
		<template #footer>
			<div class="flex justify-end gap-2">
				<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
				<BbButton variant="primary" @click="save">Save note</BbButton>
			</div>
		</template>
	</BbOffCanvas>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbOffCanvas, BbTextarea } from 'bitboss-ui';

const open = ref(false);
const saved = ref('Customer asked to postpone pickup.');
const draft = ref(saved.value);

/** Persist the draft and dismiss the panel. */
const save = () => {
	saved.value = draft.value;
	open.value = false;
};
</script>
```

### Controlling dismissal

Every dismissal path is governed by two props:

- `persistent` — backdrop click, `Escape`, and a drag-to-dismiss no longer
  close; the panel plays a short "deny" nudge instead. Your own buttons (and the
  model) still work. Use it when the user must make an explicit choice.
- `disabled` — same guard, different intent: the surface is busy (a save in
  flight). Combine with disabling your footer actions.

Two more knobs shape the surface:

- `hide-close` removes the header close button. (The close button is shown by
  default.)
- `focus-target` — a CSS selector resolved inside the panel — moves initial
  focus to a specific element; otherwise the first tabbable element receives it.

Constraint: the header **close (×) button bypasses `persistent`** (it is the
documented escape hatch) but **respects `disabled`** — a busy panel cannot be
dismissed mid-work. When a panel must be resolved from the footer, pair
`persistent` with `hide-close` and keep a visible Cancel so users are never
trapped. Backdrop clicks are also drag-protected: a text selection that starts
inside the panel and releases over the backdrop does not close it — only a
genuine click that starts and ends on the backdrop (≤4px travel) does.

**Persistent — resolve from the footer**

```vue
<template>
	<div
		class="flex max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="min-w-0">
			<p class="m-0 text-sm font-medium">PR #1842</p>
			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
				Needs a reviewer before merge
			</p>
		</div>
		<BbButton variant="outline" @click="open = true">Assign reviewer</BbButton>
	</div>
	<BbOffCanvas
		v-model="open"
		focus-target="input"
		hide-close
		persistent
		side="right"
		title="Assign reviewer"
	>
		<div class="grid gap-3">
			<BbTextInput
				v-model="reviewer"
				compact
				label="Reviewer"
				placeholder="Name or email"
			/>
			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
				Backdrop and Escape stay locked — resolve from the footer.
			</p>
		</div>
		<template #footer>
			<div class="flex justify-end gap-2">
				<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
				<BbButton variant="primary" @click="open = false">Assign</BbButton>
			</div>
		</template>
	</BbOffCanvas>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbOffCanvas, BbTextInput } from 'bitboss-ui';

const open = ref(false);
const reviewer = ref('');
</script>
```

### Top layer: what's above, what's inert

The panel is a native `<dialog>` opened with `showModal()` — the same mechanics
`BbDialog` relies on, and worth designing around:

- It renders in the browser **top layer**, above every `z-index`, sticky header,
  or transformed ancestor. There is nothing to z-index-manage.
- The element stays where you declared it in the DOM (no teleport), so scoped
  styles and provide/inject work normally; in tests, query the panel via
  `document.body` (e.g. `.bb-offcanvas--open`) after `attachTo: document.body`.
- Everything outside the panel is **inert** while it is open: no hover, click,
  or tab reaches the page behind.
- Later top-layer surfaces paint above earlier ones: a `BbSelect`, `BbPopover`,
  `BbTooltip`, `BbConfirm`, or nested drawer opened from inside works with no
  special wiring. `BbToast` regions re-home into the open panel so toasts fired
  from a drawer stay clickable.

### Works well with

- `BbDialog` — the same content as a blocking modal when the task is focused
  rather than supplementary; the shared API keeps the swap cheap.
- `BbConfirm` + `useConfirm` — a destructive action inside a drawer should raise
  a confirm on top, not a hand-built panel.
- `BbToast` + `useToast` — fire the success toast right before closing; it stays
  interactive above the panel.
- `BbButton` `href` / `to` — a footer action that navigates should carry the
  link, never an `@click` + `router.push`.

### Gotchas & anti-patterns

- **Don't rely on the close (x) button respecting `persistent`** — it doesn't
  (though it does respect `disabled`); hide it (`hide-close`) when the panel
  must be resolved explicitly, and keep a visible Cancel.
- **Don't reach for `BbOffCanvas` for a focused, blocking task** — that is
  `BbDialog`; use a drawer for content that sits beside the page.
- **Don't confuse `size` with a width** — it is the panel's extent along its
  axis (height for top/bottom drawers).
- **Don't query panel content before it has opened** unless you set `eager` —
  the body renders lazily.
- **Don't toggle `v-model` from `@hide`/`@hidden`** to "cancel" a close — use
  `persistent`; the close paths already guard correctly.
- **Don't stack unrelated drawers** expecting them to peek — the peeking band
  only appears for panels sharing a `stack` name and side.

### Accessibility

- Prefer passing `title`: it names the panel via `aria-labelledby`. Without a
  header you own the accessible name — label a heading in the body and wire it
  through the `header` slot's `titleId`.
- The panel is a true modal (`showModal()`): focus is contained within it, the
  page behind is inert, and focus returns to the trigger when it closes.
  `focus-target` only chooses where focus **starts**.
- The header close button carries a localized `aria-label` out of the box
  (`config.locale`).
- Draggable dismissal is a convenience, not the only way out — the close button,
  backdrop, and `Escape` all remain, so keyboard and assistive-tech users are
  never stranded.
- Don't lean on `persistent` to trap users. Keep a visible way out (a Cancel or
  Close button) even when backdrop/`Escape`/drag dismissal is disabled.

## v-model

- `v-model` — type: `boolean \| undefined`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `disabled` | `boolean \| undefined` | `false` |  | Disable EVERY user-initiated dismissal: backdrop click, Escape, drag-to-dismiss AND the header close (×) button (denied attempts play the deny nudge). Use it while an operation is in flight (e.g. a save) so the drawer cannot be dismissed mi… |
| `draggable` | `boolean \| undefined` | `false` |  | Enable drag-to-dismiss. The panel can be dragged from anywhere toward its edge to close, and a grab handle is shown on the inner edge as the affordance. When `false`, the panel is static (dismiss via the close button, backdrop, or Escape on… |
| `eager` | `boolean \| undefined` | `false` |  | Render offcanvas content immediately instead of waiting for the first open. |
| `focusTarget` | `string \| undefined` |  |  | CSS selector of the element to focus after opening. Defaults to the first tabbable element. |
| `fullscreen` | `boolean \| "mobile" \| undefined` |  |  | Display the offcanvas fullscreen. Use `'mobile'` to restrict fullscreen to small devices. |
| `hideClose` | `boolean \| undefined` | `false` |  | Hides the default close (×) button in the header (e.g. for a `persistent` drawer you don't want dismissible — the × otherwise still closes a persistent drawer). |
| `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to open / close the panel. A panel with no `v-model` starts closed. |
| `persistent` | `boolean \| undefined` | `false` |  | Prevent closing via outside clicks, Escape key or drag-to-dismiss. The header close (×) button STILL closes a persistent drawer — that is the documented escape hatch; combine with `hideClose` to remove it, or use `disabled` to block every d… |
| `side` | `"left" \| "right" \| "top" \| "bottom" \| undefined` | `"left"` |  | Which viewport edge the offcanvas docks to (and slides in from). |
| `size` | `Responsive<OffCanvasSize> \| undefined` | `"sm"` |  | Controls the maximum size of the offcanvas panel. Accepts named presets from `'xs'` to `'2xl'`, `'auto'`, a custom CSS size string, or a numeric pixel value — or a per-breakpoint map (e.g. `{ default: 'sm', lg: 'lg' }`) to switch responsive… |
| `stack` | `string \| undefined` |  |  | Name of the stack this drawer belongs to. Drawers sharing the same `stack` value step back behind one another as later ones open; drawers in different stacks never affect each other. When omitted, the drawer stacks with nothing. |
| `stackGap` | `number \| undefined` | `60` |  | Pixels each stacked parent drawer shifts inward when a child opens on top, leaving a peeking band of the parent visible. |
| `title` | `string \| undefined` |  |  | Title text announced to assistive technologies. If omitted, no header is rendered and accessibility must be handled manually. |
| `transitionDuration` | `number \| undefined` | `250` |  | Controls the duration of the open and close animations. |

## Events

- `hidden` — `(event: "hidden"): void`
- `hide` — `(event: "hide"): void`
- `show` — `(event: "show"): void`
- `shown` — `(event: "shown"): void`
- `update:modelValue` — `(event: "update:modelValue", value: boolean): void`

## Slots

- `default` — scope: `{ close: () => void; }` — Primary body content of the off-canvas panel, rendered in the scrollable body area.
- `footer` — scope: `object` — Content rendered in the panel footer, below the body area. Typically used for action buttons.
- `header` — scope: `BbOffCanvasHeaderSlotProps` — Replaces the entire off-canvas header section (title + close button). Maintains accessibility wiring via the provided props.
- `title` — scope: `BbOffCanvasTitleSlotProps` — Replaces the default title text inside the header. Remains linked to the panel through `aria-labelledby`. Providing this slot renders the header even when `title` is unset — a slotted title is a title.

## See Also

- [BbDialog](./BbDialog.md) — Presents modal dialogs for focused user interactions.
- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements.

---

<!-- dist/ai/BbPagination.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbPagination.md -->

# BbPagination

## Agent Contract

- Safety level: **Consumer API**
- Group: **Navigation**
- Description: Navigates paginated data sets by page index.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbPagination.md](./source/BbPagination.md)

## Usage & Guidelines

### When to use

Reach for `BbPagination` when a list is too long for one screen and the user
needs deterministic, jump-anywhere access to any page — search results, an
invoice ledger, an audit log. Prefer it over infinite scroll whenever people
need to _find their place again_ or reference "page 4".

It is a pure page selector: it does not fetch, slice, or store your data — you
own that and drive it from the page it reports. For hierarchy use
`BbBreadcrumbs`; for switching peer views use `BbTabs`.

### Control the current page with `v-model`

`v-model` is the current page (1-based); `total-pages` sets the range (a number
or numeric string — handy when it comes straight from an API). A **standalone**
control clamps out-of-range pages back into `1..totalPages` (assign `99` and the
model snaps back), disables _Previous_ on page 1 and _Next_ on the last page, and
renders the whole range when it fits.

**Paired with a table (`table-id`), it does not clamp.** There the context owns
the page and this control takes what it was given: an out-of-range page is the
consumer's to own — the table renders the empty slice it implies — so correcting
it here would push a page nobody asked for. If you need the clamp in a paired
setup, do it where you own the page state. With a single page every page button is
disabled — pagination for one page is inert by design, so consider hiding the
control instead.

**A bound page selector**

```vue
<div class="space-y-2">
	<BbPagination v-model="state.page" :total-pages="24" />
	<p class="text-xs text-[color:var(--bb-text-muted)]">On page {{ state.page ?? 1 }} of 24.</p>
</div>
```

The only event is `update:modelValue` (the new 1-based page) — everything else
(which buttons disable, where the ellipses go) is handled internally. Listen to
the model, not to clicks.

### Folding, fit and alignment

Long ranges fold around the current page with ellipses — you never compute the
window yourself. Three knobs shape the strip:

- `max-size` (default 6) caps how many **page** buttons show at once — the
  count excludes the ellipses and _Previous_/_Next_, and has a ±1 tolerance so
  odd/even windows stay balanced around the current page.
- The strip also **fits itself**: a `ResizeObserver` drops page buttons (never
  below 3) when the container is too narrow and adds them back when space
  returns, so `max-size` is a maximum, not a promise.
- `align` places the control within its full-width row: `right` (default),
  `center`, or `left`.
- `ellipsis` swaps the `...` placeholder text (the ellipsis buttons themselves
  are always disabled).

**Long ranges collapse with an ellipsis**

```vue
<BbPagination
	v-model="state.page"
	align="center"
	:max-size="7"
	:total-pages="42"
/>
```

### Wire it to your data

Pagination reports the page; your code turns that into the visible slice.
Give it the count the server reports — either `total-pages` directly, or
`total-items` with `per-page` and the control computes
`ceil(totalItems / perPage)` itself (when both are present, the derived count
wins over `total-pages`). Watch the page and fetch (or slice) when it changes. If you need to freeze the control — no data yet, a
blocking error, or to stop a user outrunning an in-flight request — set
`disabled`. Pagination has no `loading` state of its own: it is a page selector,
not a data-fetching surface, so keep the in-flight/loading affordance on the
list or table it drives.

**Repaginating a list**

```vue
<template>
	<!-- Manual wire-up: the pager reports the page; you slice (or fetch) from it.
	     Prefer this over `table-id` when the list is not a BbTable. -->
	<div
		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
	>
		<ul class="divide-y divide-[color:var(--bb-border)]">
			<li
				v-for="invoice in pageItems"
				:key="invoice.id"
				class="flex items-center justify-between gap-2 px-3 py-2 text-sm"
			>
				<span class="font-medium tabular-nums">{{ invoice.number }}</span>
				<span
					class="min-w-0 flex-1 truncate text-[color:var(--bb-text-muted)]"
					>{{ invoice.customer }}</span
				>
				<span
					class="shrink-0 text-xs tabular-nums text-[color:var(--bb-text-muted)]"
					>{{ invoice.amount }}</span
				>
			</li>
		</ul>
		<div
			class="flex flex-wrap items-center justify-between gap-2 border-t border-[color:var(--bb-border)] px-3 py-2"
		>
			<p class="text-xs text-[color:var(--bb-text-muted)]" data-test="range">
				{{ rangeStart }}–{{ rangeEnd }} of {{ invoices.length }}
			</p>
			<BbPagination
				v-model="page"
				label="Invoices pagination"
				:per-page="perPage"
				:total-items="invoices.length"
			/>
		</div>
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbPagination } from 'bitboss-ui';

type Invoice = { id: number; number: string; customer: string; amount: string };

const customers = [
	'Northwind Traders',
	'Globex',
	'Initech',
	'Umbrella',
	'Soylent',
	'Hooli',
];
const invoices: Invoice[] = Array.from({ length: 47 }, (_, index) => ({
	id: index + 1,
	number: `INV-${1042 + index}`,
	customer: customers[index % customers.length],
	amount: `€${(480 + index * 35).toLocaleString('en-IE')}.00`,
}));

const perPage = 5;
const page = ref(1);

// The page reported by BbPagination is all we need to slice the data ourselves.
const rangeStart = computed(() => (page.value - 1) * perPage + 1);
const rangeEnd = computed(() =>
	Math.min(page.value * perPage, invoices.length)
);
const pageItems = computed(() =>
	invoices.slice(rangeStart.value - 1, rangeEnd.value)
);
</script>
```

### Custom button content via slots

Four slots restyle the buttons without touching their behavior: `item` receives
`{ item, active, disabled }` for each page number, `previous` / `next` replace
the chevrons (no scope — keep the content self-describing for screen readers),
and `ellipsis` replaces the fold marker. The buttons stay real buttons with all
their wiring; the slots only swap what is painted inside them.

**Wordy controls for a document reader**

```vue
<template>
	<div
		class="max-w-sm space-y-2 rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
	>
		<div
			class="rounded-[var(--bb-radius)] bg-[color:var(--bb-muted)] px-3 py-8 text-center text-sm text-[color:var(--bb-text-muted)]"
		>
			Sheet {{ sheet }} of 18 · Q3 board pack
		</div>
		<BbPagination
			v-model="sheet"
			align="left"
			label="Document sheets"
			:max-size="5"
			:total-pages="18"
		>
			<template #previous><span class="px-1 text-xs">Prev</span></template>
			<template #next><span class="px-1 text-xs">Next</span></template>
			<template #item="{ item, active }">
				<span
					class="px-0.5 text-xs"
					:class="active && 'font-semibold underline'"
				>
					{{ item }}
				</span>
			</template>
		</BbPagination>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbPagination } from 'bitboss-ui';

// The reader tracks which sheet is visible; the slots only restyle the buttons.
const sheet = ref(1);
</script>
```

### Pair with a `BbTable` through a shared id

When the list is a `BbTable`, skip the manual wiring: give the table an `id`
and the pagination the matching `table-id`. Both components publish their
pagination props into the shared table context (see `useBbTableContext`), so
the page count is derived automatically and the current page stays two-way
synced. No `v-model` needed; mount order doesn't matter, and a page already
present in the context wins at mount.

The props are symmetric: `page`, `per-page`, `total-items`, and `total-pages`
are accepted by both components, so the server's fields can be passed to
whichever one is convenient — `total-items` on the table or on the pager both
end up as the same shared `totalItems`. One rule resolves conflicts: a page count
derived from a real `total-items` always wins, and `total-pages` (on either
side) is only a seed for when no row count is known — the common case being an
externally paged array table, whose rows are one page and no total.

For server paging, read the shared page with `useBbTableContext(id)` and use it
inside the items provider. A provider table **already treats the shared page as
a refetch trigger** — so a page turn re-runs the provider on its own; you do
_not_ list `page` in `dependencies` (that's only for your own filters/sort). The
table shows its own skeletons while it awaits — no watcher, no `loading` ref of
your own. Sit the pager in the table footer:

**Server-paged audit log footer**

```vue
<template>
	<!-- Server-paged table footer: the shared `audit-log` id pairs the table and
	     pager. A provider table auto-refetches when the shared page moves, so no
	     `dependencies` wiring is needed — the provider just reads `page` from the
	     same context the pager drives. -->
	<div
		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
	>
		<BbTable
			id="audit-log"
			caption="Audit log"
			:columns="columns"
			compact
			item-value="id"
			:items="fetchEvents"
		/>
		<div
			class="flex flex-wrap items-center justify-between gap-2 border-t border-[color:var(--bb-border)] px-3 py-2"
		>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				{{ rangeStart }}–{{ rangeEnd }} of {{ totalItems }}
			</p>
			<BbPagination label="Audit log pagination" table-id="audit-log" />
		</div>
	</div>
</template>
<script setup lang="ts">
import { computed } from 'vue';
import { BbPagination, BbTable, useBbTableContext } from 'bitboss-ui';
import type { BbTableColumn } from 'bitboss-ui';

type AuditEvent = { id: number; action: string; actor: string; time: string };

const columns: Array<BbTableColumn<AuditEvent>> = [
	{ key: 'action', label: 'Action' },
	{ key: 'actor', label: 'Actor' },
	{ key: 'time', label: 'When', align: 'right', width: 120 },
];

const actions = [
	'member.invited',
	'api_key.created',
	'billing.plan_changed',
	'webhook.updated',
	'sso.login_failed',
	'invoice.exported',
	'role.updated',
];
const actors = ['ada@acme.io', 'grace@acme.io', 'linus@acme.io'];
const events: AuditEvent[] = Array.from({ length: 23 }, (_, index) => ({
	id: index + 1,
	action: actions[index % actions.length],
	actor: actors[index % actors.length],
	time: `2026-07-0${9 - Math.floor(index / 10)} ${String(
		18 - (index % 10)
	).padStart(2, '0')}:${String((index * 7) % 60).padStart(2, '0')}`,
}));

// Same id as the table: seed `perPage` on the context handle so the table
// reads its page size from the shared context — no `:per-page` prop needed.
// `page` and `perPage` here are the same refs the pager drives and the table
// announces.
const { page, perPage, totalItems } = useBbTableContext('audit-log', {
	perPage: 5,
});

const rangeStart = computed(() => (page.value - 1) * perPage.value + 1);
const rangeEnd = computed(() =>
	Math.min(page.value * perPage.value, totalItems.value)
);

/** Non-query table provider — playbook signature; page/perPage come from context. */
const fetchEvents = (_prefill: boolean): Promise<AuditEvent[]> =>
	new Promise((resolve) => {
		setTimeout(() => {
			const start = (page.value - 1) * perPage.value;
			totalItems.value = events.length;
			resolve(events.slice(start, start + perPage.value));
		}, 250);
	});
</script>
```

Any other component can join the same rendezvous with
`useBbTableContext('audit-log')` — read `ctx.page` in a toolbar, reset it after
a filter change — and the pager follows. Mind the id: a typo doesn't error, it
just pairs with nothing.

### URL-synced pagination

Set `navigation` to reflect the current page in the URL, so a page is
bookmarkable and survives a reload. `query-key` names the query parameter
(default `page`). Under Vue Router or Nuxt each enabled button becomes a `to`
link that merges the param into the current route's query (other params
survive). Without a router it falls back to real `href`s built from
`window.location`, so the same markup deep-links in a plain SPA too.

**Pair `navigation` with `replace`.** Paging is a view control, not a journey:
without `replace` every page click pushes a history entry, and a user who
walked to page 12 needs eleven Backs to escape the list. `replace` keeps the
URL current — still deep-linkable, still reload-proof — while one Back returns
to wherever they entered the list from.

One thing stays yours: **the component does not read the URL at mount** — it
writes it. Initialize the model from the route once, and `navigation` keeps
them in sync from then on:

**URL-synced exports with replace**

```vue
<template>
	<!-- `navigation` + `replace`: ?page stays deep-linkable; Back leaves the list
	     instead of walking every page click. Seed v-model from the route once —
	     the control writes the URL, it does not read it at mount. -->
	<div
		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
	>
		<ul class="divide-y divide-[color:var(--bb-border)]">
			<li
				v-for="row in pageItems"
				:key="row.id"
				class="flex items-center justify-between gap-2 px-3 py-2 text-sm"
			>
				<span class="font-medium">{{ row.label }}</span>
				<span class="text-xs tabular-nums text-[color:var(--bb-text-muted)]">{{
					row.when
				}}</span>
			</li>
		</ul>
		<div
			class="flex flex-wrap items-center justify-between gap-2 border-t border-[color:var(--bb-border)] px-3 py-2"
		>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Page {{ page }} of {{ totalPages }}
			</p>
			<BbPagination
				v-model="page"
				label="Exports pagination"
				navigation
				query-key="page"
				replace
				:total-pages="totalPages"
			/>
		</div>
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbPagination } from 'bitboss-ui';

type ExportRow = { id: number; label: string; when: string };

const rows: ExportRow[] = [
	{ id: 1, label: 'Invoices CSV · Jul 2026', when: '2 min ago' },
	{ id: 2, label: 'Payments CSV · Q2', when: '1 hr ago' },
	{ id: 3, label: 'Customers JSON', when: 'Yesterday' },
	{ id: 4, label: 'Tax summary PDF', when: 'Jul 18' },
	{ id: 5, label: 'Audit trail CSV', when: 'Jul 12' },
	{ id: 6, label: 'Usage report XLSX', when: 'Jul 03' },
	{ id: 7, label: 'Refunds CSV · Jun', when: 'Jun 28' },
	{ id: 8, label: 'Team roster CSV', when: 'Jun 14' },
	{ id: 9, label: 'Webhooks JSON', when: 'May 30' },
	{ id: 10, label: 'Ledger dump CSV', when: 'May 09' },
	{ id: 11, label: 'Plan changes CSV', when: 'Apr 22' },
	{ id: 12, label: 'API keys CSV', when: 'Apr 02' },
];

const perPage = 4;
const page = ref(1);
const totalPages = Math.ceil(rows.length / perPage);

const pageItems = computed(() => {
	const start = (page.value - 1) * perPage;
	return rows.slice(start, start + perPage);
});
</script>
```

Seed from the route in your app (the companion above starts at page 1 for the
preview; production code reads the query once):

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { useRoute } from 'vue-router'; // or '#imports' in Nuxt

const route = useRoute();
const page = ref(Number(route.query.page) || 1);
</script>
```

Disabled buttons (the current page's _Previous_/_Next_ at the edges, and every
button while `disabled`) never carry a link, so crawlers and middle-clicks can't
reach invalid pages.

### Works well with

- `BbTable` — the shared-id pairing above; `per-page`/`total-items` on either
  component drive the page count.
- `useBbTableContext` — bulk-action toolbars and filters that reset `page` to 1
  when the query changes.
- `BbSelect` — a small page-size selector next to the pager; recompute
  `total-pages` and clamp happens for free.
- `BbBreadcrumbs` / `BbTabs` — siblings, not alternatives: hierarchy and peer
  views respectively. See the component picker.

### Gotchas and anti-patterns

- **Name the list you're paging.** The `nav` landmark's default label follows
  the configured locale (`pagination.label` → `'Pagination'` / `'Paginazione'`),
  but a generic "Pagination" is a poor landmark when a page has several. Set
  `label` to say _which_ list: `label="Invoices pagination"`.
- **`navigation` writes the URL, it doesn't read it** — seed `v-model` from the
  route at setup (example above) or a shared link lands on page 1.
- **`navigation` without `replace` buries the Back button.** Every page click
  becomes a history entry, so leaving a list the user paged through takes one
  Back per page visited. Add `replace`: the URL stays deep-linkable and Back
  goes back to the previous _screen_, which is what the user meant.
- **Pages are 1-based.** Page `0` is clamped to `1`; your slicing math is
  `(page - 1) * perPage`.
- **Don't rebuild the window.** No manual ellipsis math, no hiding buttons with
  CSS — `max-size` plus the container-fit behavior already handle it.
- **Don't fetch inside the pager.** It's a selector; watch the model (or the
  table context) and fetch in your own code.
- **Don't feed conflicting counts to a paired table and pager.** With a
  `table-id`, both components publish their pagination props into the shared
  context; giving each a different `total-items` (or `total-pages`) is an
  author error the library resolves arbitrarily. Pass each fact to one place.

### Accessibility

- The control is a labelled `nav` landmark — its default label is locale-aware;
  set `label` to describe _which_ list it paginates (see the gotcha above).
- Every control is a real `button` (or a link under `navigation`): normal Tab
  order, Enter/Space activation, no custom keyboard model to learn. There is no
  roving focus — each page button is a tab stop.
- The active page carries `aria-current="page"`; _Previous_ / _Next_ ship
  visually-hidden, locale-aware text labels behind their chevrons. If you
  replace the `previous`/`next` slots, include accessible text (visible or
  `sr-only`) yourself.
- Reach for `disabled` to freeze the whole control. Pagination has no `loading`
  state — keep the in-flight affordance on the list or table it drives.

## v-model

- `v-model` — type: `number \| undefined`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `align` | `"left" \| "center" \| "right" \| undefined` | `"right"` |  | Alignment of the pagination control. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
| `ellipsis` | `string \| undefined` | `"..."` |  | String of text displayed in place of hidden pages. |
| `label` | `string \| undefined` |  |  | Label of the pagination navigation landmark. When unset, falls back to the localized `pagination.label` (`'Pagination'` / `'Paginazione'`). |
| `maxSize` | `string \| number \| undefined` | `6` |  | Maximum number of clickable pages displayed at all times. This has a tolerance of +/- 1 for odd / even numbering. It does not include ellipses. |
| `modelValue` | `number \| undefined` | `1` |  | Used by v-model. The 1-based index of the current page — pagination starts on the first page, not page `0`. |
| `navigation` | `boolean \| undefined` | `false` |  | Synchronizes the current page with the URL. Pair it with `replace` — see that prop. |
| `perPage` | `string \| number \| undefined` |  |  | Number of items per page. Together with `totalItems` it derives the page count (`ceil(totalItems / perPage)`); when unset, one page holds everything. With a `tableId` it is also published to the shared table context, exactly like the table'… |
| `queryKey` | `string \| undefined` | `"page"` |  | Defines the query key to reference for maintaining navigation. |
| `replace` | `boolean \| undefined` | `false` |  | Replaces history rather than pushing it when changing page. Recommended default whenever `navigation` is on: the URL keeps the current page (deep-linkable, survives reload) while Back returns to the page the user came from, instead of stepp… |
| `tableId` | `string \| undefined` |  |  | Id of a `BbTable` to pair with through the shared table context (see `useBbTableContext`). The current page is kept two-way synced with the table's context state, and the context's page count drives the control, overriding the local props. … |
| `totalItems` | `string \| number \| undefined` |  |  | Total number of items across all pages. When set, the page count is derived as `ceil(totalItems / perPage)` and wins over `totalPages`. With a `tableId` it is also published to the shared table context, exactly like the table's own `total-i… |
| `totalPages` | `string \| number \| undefined` |  |  | Total number of pages. A shortcut for when the server reports a page count rather than a row count — a page count derived from `totalItems` (locally or through the shared table context) always wins over it. Falls back to `1` when nothing pr… |

## Events

- `update:modelValue` — `(event: "update:modelValue", value: number): void`

## Slots

- `ellipsis` — scope: `Record<string, never>` — Replaces the default `…` ellipsis shown when pages overflow the visible range.
- `item` — scope: `BbPaginationItemSlotProps` — Replaces the default page number button content for each individual page.
- `next` — scope: `Record<string, never>` — Replaces the default "next page" button content.
- `previous` — scope: `Record<string, never>` — Replaces the default "previous page" button content.

## See Also

- [BbTable](./BbTable.md) — Displays tabular data, configurable columns and data mapper.

---

<!-- dist/ai/BbPopover.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbPopover.md -->

# BbPopover

## Agent Contract

- Safety level: **Consumer API**
- Group: **Overlay**
- Description: Anchors floating content to reference elements.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbPopover.md](./source/BbPopover.md)

## Usage & Guidelines

### When to use

Reach for `BbPopover` when you need a **small floating panel with interactive
content** anchored to a trigger: a quick-settings form, a notifications list, a
mini picker, an inline detail card. It opens on click and stays open — the user
can click, type, and toggle inside it — dismissing only on an outside click or
`Escape`.

Pick a sibling when the shape is more specific:

- A one-line non-interactive hint on hover/focus → `BbTooltip`. Richer field
  help with links or actions still belongs in a popover (see below).
- A standard list of actions (a menu) → `BbDropdown`.
- A searchable option list bound to a value → `BbSelect` / `BbSelectPopover`.
- A focused, page-blocking task → `BbDialog`; supplementary side content →
  `BbOffCanvas`.

`BbPopover` looks lightweight — it does not dim the page, and an outside click
dismisses it — but it **is** modal underneath: a `<dialog>` opened with
`showModal()`, so focus is trapped and the page behind is inert while it is
open (see Accessibility). Plan for that: the user cannot interact with the page
until they dismiss it. If the surface should also _look_ like it owns the
user's attention until resolved, that is `BbDialog`.

### Activator and content

Render your trigger in the `activator` slot and **spread its `props`** onto the
element — that is the whole contract. `props` carries the accessibility
attributes (`aria-expanded`, `aria-controls`, `aria-haspopup="dialog"`), the
element `id`, the `disabled` state, the positioning `ref`, and the open/close
handler for whichever `trigger` is active. Miss the spread and the popover has
no anchor and no way to open.

The `activator` slot scope also exposes `isOpen`, `placement` and `disabled` so
the trigger can react (rotate a chevron, swap a label). The `default` slot
receives `close` (plus `open`, `placement`, `disabled`) so controls inside can
dismiss the panel.

**Quick display settings**

```vue
<template>
	<div
		class="flex max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="min-w-0">
			<p class="truncate text-sm font-medium">Invoices</p>
			<p class="truncate text-xs text-[color:var(--bb-text-muted)]">
				24 open · last synced 2m ago
			</p>
		</div>
		<BbPopover :width="240">
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					prepend:icon="lucide:sliders-horizontal"
					variant="outline"
				>
					Display
				</BbButton>
			</template>
			<template #default>
				<div class="grid gap-3">
					<BbSwitch v-model="compact" label="Compact rows" />
					<BbSwitch v-model="avatars" label="Show avatars" />
				</div>
			</template>
		</BbPopover>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbPopover, BbSwitch } from 'bitboss-ui';

const compact = ref(true);
const avatars = ref(false);
</script>
```

### A mini-form popover

The most common interactive popover is a small form that commits on save and
uses the slot's `close` to dismiss. Keep the primary action gated on validity,
keep Cancel always live, and close only after the write. This companion renames
a record and closes itself on save via the `close` callback.

**Rename in a popover**

```vue
<template>
	<div
		class="flex max-w-sm items-center justify-between gap-2 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="min-w-0">
			<p class="truncate text-sm font-medium">{{ name }}</p>
			<p class="truncate text-xs text-[color:var(--bb-text-muted)]">
				Shared report · edited today
			</p>
		</div>
		<BbPopover :width="260">
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Rename"
					icon="lucide:pencil"
					size="sm"
					variant="ghost"
				/>
			</template>
			<template #default="{ close }">
				<form class="grid gap-3" @submit.prevent="() => save(close)">
					<BbTextInput
						v-model="draft"
						compact
						label="Name"
						placeholder="Report name"
					/>
					<div class="flex justify-end gap-2">
						<BbButton type="button" variant="ghost" @click="close">
							Cancel
						</BbButton>
						<BbButton :disabled="!draft.trim()" type="submit" variant="primary">
							Save
						</BbButton>
					</div>
				</form>
			</template>
		</BbPopover>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbPopover, BbTextInput } from 'bitboss-ui';

const name = ref('Q3 report');
const draft = ref(name.value);

/** Commit the draft name, then dismiss via the slot `close`. */
const save = (close: () => void) => {
	const next = draft.value.trim();
	if (!next) return;
	name.value = next;
	close();
};
</script>
```

### An anchored profile card

The read-only counterpart is a **detail card** anchored to an identity — click a
member's name in a comment or an activity feed and see who they are without
leaving the page (the GitHub-hovercard pattern, click-triggered here because a
popover opens on click). `placement="bottom-start"` aligns the card's edge with
the name, and the panel is pure content: any navigation ("View profile") is an
`href`, never an `@click`.

**Member profile card**

```vue
<template>
	<div
		class="max-w-md rounded-[var(--bb-radius)] border p-3 text-sm text-[color:var(--bb-text-muted)]"
	>
		Deploy of
		<span class="font-medium text-[var(--bb-text)]">invoice-export</span>
		approved by
		<BbPopover placement="bottom-start" :width="280">
			<template #activator="{ props }">
				<BbBaseButton
					v-bind="props"
					class="font-medium text-inherit underline decoration-dotted underline-offset-2"
				>
					{{ member.name }}
				</BbBaseButton>
			</template>
			<div class="grid gap-3">
				<div class="flex items-center gap-2.5">
					<BbAvatar
						:alt="member.name"
						size="56"
						:src="member.src"
						:timeout="demoAvatarTimeout"
					>
						<span>{{ member.initials }}</span>
					</BbAvatar>
					<div class="min-w-0">
						<div class="truncate text-sm font-medium text-[var(--bb-text)]">
							{{ member.name }}
						</div>
						<div class="truncate text-xs text-[color:var(--bb-text-muted)]">
							{{ member.role }}
						</div>
					</div>
				</div>
				<div class="grid gap-1 text-xs text-[color:var(--bb-text-muted)]">
					<div class="flex items-center gap-1.5">
						<BbIcon icon="lucide:mail" size="xs" />
						<span class="truncate">{{ member.email }}</span>
					</div>
					<div class="flex items-center gap-1.5">
						<BbIcon icon="lucide:map-pin" size="xs" />
						<span>{{ member.location }}</span>
					</div>
				</div>
				<BbButton
					class="w-full"
					href="#profile-maria-bianchi"
					prepend:icon="lucide:external-link"
					variant="outline"
				>
					View profile
				</BbButton>
			</div>
		</BbPopover>
		2 hours ago.
	</div>
</template>

<script setup lang="ts">
import {
	BbAvatar,
	BbBaseButton,
	BbButton,
	BbIcon,
	BbPopover,
} from 'bitboss-ui';
// Inlined rather than imported from BbAvatar's example folder: every example
// must be copy-pasteable into a consumer project on its own, and a
// cross-example import is the one thing that breaks that.
const demoAvatarTimeout = 4000;
const demoAvatarSrc = (photoId: string, size = 256) =>
	`https://images.unsplash.com/${photoId}?w=${size}&h=${size}&fit=crop&crop=faces&auto=format`;

const member = {
	name: 'Maria Bianchi',
	initials: 'MB',
	role: 'Platform engineer · Infra',
	email: 'maria.bianchi@acme.dev',
	location: 'Milan, Italy (UTC+2)',
	src: demoAvatarSrc('photo-1573496359142-b8d87734a5a2'),
};
</script>
```

### Inline field help

For a one-line non-interactive hint, prefer `BbTooltip`. Reach for a popover
when the explanation needs room — a short paragraph plus a docs link, related
actions, or anything the user might click. Pair an icon-only ghost activator
(`aria-label` required) with the field it explains; keep the panel narrow and
dismissible.

**Field help with a docs link**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Invoice retention</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				How long paid invoices stay searchable in the workspace.
			</p>
		</div>
		<div class="flex items-end gap-1.5">
			<BbTextInput
				v-model="days"
				class="min-w-0 flex-1"
				compact
				label="Retention period"
			>
				<template #suffix>days</template>
			</BbTextInput>
			<BbPopover placement="top-end" :width="260">
				<template #activator="{ props }">
					<BbButton
						v-bind="props"
						aria-label="About retention period"
						class="shrink-0"
						icon="lucide:circle-question-mark"
						variant="ghost"
					/>
				</template>
				<div class="grid gap-2 text-sm">
					<p class="m-0 font-medium">Retention period</p>
					<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
						Paid invoices older than this window are archived and drop out of
						search. Drafts and unpaid invoices are never archived by retention.
					</p>
					<BbButton
						class="justify-start"
						href="#docs-retention"
						prepend:icon="lucide:book-open"
						size="sm"
						variant="ghost"
					>
						Read the retention guide
					</BbButton>
				</div>
			</BbPopover>
		</div>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbPopover, BbTextInput } from 'bitboss-ui';

const days = ref('90');
</script>
```

### Placement, offset and boundary

`placement` positions the panel around the activator — the `top` / `right` /
`bottom` / `left` families, each with `-start` / `-end` alignment variants
(e.g. `bottom-start`). It defaults to `bottom`. The panel **auto-flips** to stay
in view near a viewport edge, so pick the placement that reads best in the
common case and let it correct itself.

Fine-tune the geometry with:

- `offset` — gap (px) between the activator and the panel (default `3`).
- `padding` — minimum gap (px) the panel keeps from the page edge (default
  `10`).
- `boundary` — an element, ref, or CSS selector that constrains the panel so it
  never escapes a scrolling region or sidebar.

`BbPopover` is a floating **panel**, not a speech bubble — it never renders an
arrow. Reach for `BbTooltip` when you want an arrow pointing back at the trigger
for a one-line, non-interactive hint.

**Placement around the trigger**

```vue
<div class="flex flex-wrap gap-2">
	<BbPopover
		v-for="side in ['top', 'right', 'bottom', 'left']"
		:key="side"
		:placement="side"
		:width="150"
	>
		<template #activator="{ props }">
			<BbButton v-bind="props" variant="outline">{{ side }}</BbButton>
		</template>
		<div class="text-sm">Placed <strong>{{ side }}</strong></div>
	</BbPopover>
</div>
```

### Header, footer and scrollable content

Tall content (a notifications feed, a long list) should set `scrollable`: it
caps the panel to the available viewport height and scrolls the body internally.
Pin a title in the `header` slot and actions in the `footer` slot — both stay
put outside the scroll region, with their own padding and dividers, so you never
need `sticky` hacks. This companion left-aligns its rows with the `justify-start`
utility (BbButton centers labels by default).

**A notifications popover**

```vue
<template>
	<div
		class="flex max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="min-w-0">
			<p class="truncate text-sm font-medium">Acme Studio</p>
			<p class="truncate text-xs text-[color:var(--bb-text-muted)]">
				Workspace · Billing
			</p>
		</div>
		<BbPopover scrollable :width="300">
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Notifications"
					icon="lucide:bell"
					size="sm"
					variant="ghost"
				/>
			</template>
			<template #header>
				<strong class="text-sm">Notifications</strong>
			</template>
			<template #default="{ close }">
				<div class="grid gap-1">
					<BbButton
						v-for="item in items"
						:key="item.id"
						class="justify-start"
						:href="`#notification-${item.id}`"
						size="sm"
						:variant="item.read ? 'ghost' : 'secondary'"
						@click="close"
					>
						{{ item.title }}
					</BbButton>
				</div>
			</template>
			<template #footer>
				<div class="flex justify-end">
					<BbButton
						prepend:icon="lucide:check"
						size="sm"
						variant="ghost"
						@click="markAllRead"
					>
						Mark all as read
					</BbButton>
				</div>
			</template>
		</BbPopover>
	</div>
</template>

<script setup lang="ts">
import { reactive } from 'vue';
import { BbButton, BbPopover } from 'bitboss-ui';

type Notification = {
	id: number;
	title: string;
	read: boolean;
};

const items = reactive<Notification[]>([
	{ id: 1, title: 'Invoice #INV-2043 was paid', read: false },
	{ id: 2, title: 'Maria commented on “Q3 report”', read: false },
	{ id: 3, title: 'Your export is ready to download', read: true },
]);

const markAllRead = () => {
	items.forEach((item) => (item.read = true));
};
</script>
```

### Triggers and cursor anchoring

`trigger` chooses the interaction: `'click'` (default), `'contextMenu'`
(right-click on desktop, long-press on mobile), or an array to combine them.
Pair `contextMenu` with `placement="cursor"` to anchor the panel at the pointer
— a context surface for richer, interactive content. (For a plain list of
actions, reach for `BbDropdown` instead.)

**Right-click for a context panel**

```vue
<div class="max-w-sm">
	<BbPopover placement="cursor" trigger="contextMenu" :width="200">
		<template #activator="{ props }">
			<button
				v-bind="props"
				type="button"
				class="grid h-24 w-full place-items-center rounded-[var(--bb-radius)] border border-dashed text-sm text-[color:var(--bb-text-muted)]"
			>
				Right-click anywhere here
			</button>
		</template>
		<template #default="{ close }">
			<div class="grid gap-1">
				<BbButton class="justify-start" size="sm" variant="ghost" @click="close">Preview</BbButton>
				<BbButton class="justify-start" href="#rename" size="sm" variant="ghost" @click="close">Rename</BbButton>
			</div>
		</template>
	</BbPopover>
</div>
```

### External activator

When the trigger already exists elsewhere (a toolbar button, a table cell), pass
it as the `activator` prop instead of using the slot — the listeners and ARIA
are attached to that element directly, so you don't spread `props`. This needs a
template ref, so it is a **static** snippet (a live fence has no `<script>` to
declare the ref):

```vue
<template>
	<BbButton ref="triggerRef" icon="lucide:settings">Options</BbButton>
	<BbPopover :activator="triggerRef">
		<div class="grid gap-1">
			<BbSwitch v-model="notify" label="Email me" />
		</div>
	</BbPopover>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbPopover, BbSwitch } from 'bitboss-ui';

const triggerRef = ref();
const notify = ref(true);
</script>
```

The `activator` prop accepts an `HTMLElement` or a component ref; BbPopover
resolves the underlying element, wires `click` / `contextMenu` listeners, and
sets `aria-haspopup` / `aria-expanded` / `aria-controls` on it.

### Width and sizing

`width` accepts pixels (`:width="240"`) or a percentage relative to the
activator's width — `width="100%"` matches the trigger exactly, handy for
select-like panels; only the `%` form tracks the activator on resize. With no
`width` the panel sizes to its content. `scrollable` (above) is what bounds the
height; without it a tall panel grows freely.

### Lifecycle, focus and lazy content

- Four lifecycle events fire, matching `BbDialog`/`BbOffCanvas`: `show` as the
  panel starts opening and `shown` after it has opened and focus has moved inside;
  `hide` as it starts closing and `hidden` after it has closed and focus has
  returned to the activator.
- Focus moves into the panel on open (first focusable element) and returns to
  the activator on close; `focus-target` (a CSS selector) overrides where it
  first lands.
- Content is **lazy** — the body renders on first open. Set `eager` to render it
  up front (pre-measure a chart, let tests query it closed).
- `transition-duration` (ms) times the open/close animation.
- For imperative open/close, use `v-model`: write `true` to open and `false` to
  close, and the popover writes it back on every dismiss (outside click, Escape,
  backdrop) — the self-correcting two-way model `BbDialog`/`BbOffCanvas` use.
  There is no template-ref `show()`/`close()` API; the boolean model is it.

### Top layer: escaping overflow and z-index

The floating panel opens in the browser **top layer** (a native `<dialog>`), so
it paints above every `z-index`, sticky header, `overflow: hidden` clip, or
transformed ancestor — there is nothing to z-index-manage, and a popover inside
a scrolling card or table cell is not clipped by it. A popover, select, or
tooltip opened from **inside** a `BbDialog` / `BbOffCanvas` also layers correctly
above that surface with no extra wiring. In tests, query the panel via
`document.body` (the open panel carries both classes on one element —
`.bb-popover.bb-common-popover--open`) after `attachTo: document.body`.

The popover closes automatically if its activator scrolls out of view — it is
tethered to the trigger, not left floating over the page.

### Adaptive: a bottom sheet on mobile

By default (`config.adaptive`, `true` out of the box) a popover opened on a small
viewport (below `config.mobileMaxWidth`, 768px) renders as a bottom-anchored,
draggable `BbOffCanvas` sheet instead of a floating panel — better ergonomics
for thumbs. The surface is **latched when the popover opens** and stays fixed for
that session, so a mid-session resize never swaps panel ↔ sheet.

- The `header`, `default`, and `footer` slots carry over to the sheet unchanged.
- `width` is **ignored** in sheet mode (a sheet sizes itself); tune the sheet
  with `off-canvas-props` (merged over the defaults `direction: 'bottom'`,
  `size: 'auto'`, `draggable: true`).
- `:adaptive="false"` keeps the floating panel everywhere; a bare `adaptive`
  forces the sheet on regardless of the global config.

Leave `adaptive` unset unless the project asks otherwise — the tri-state default
falls back to `config.adaptive`.

### Works well with

- `BbButton` — the natural activator; spread the slot `props` onto it.
- `BbSwitch`, `BbCheckbox`, `BbTextInput` — the interactive controls a popover
  exists to hold; wire the `default` slot's `close` to commit-and-dismiss.
- `BbDialog` / `BbOffCanvas` — a popover opened from inside either layers above
  it correctly; reach for those instead when the content is a full task.
- `BbDropdown` — when the panel is really just a menu of actions, use the
  dropdown; a popover is for interactive content.

### Gotchas & anti-patterns

- **Don't forget to spread `props`** onto the activator (or pass an `activator`
  ref) — without it there is no anchor, no ARIA, and no open handler.
- **Don't put a blocking task in a popover** — it doesn't lock the page and
  dismisses on outside click; use `BbDialog`.
- **Don't reach for a popover when you mean a menu** — a plain list of actions is
  `BbDropdown`.
- **Don't set `width` and expect it on mobile** — the adaptive sheet ignores it;
  size the sheet with `off-canvas-props`.
- **Don't query popover content before first open** unless `eager` — the body is
  lazy.
- **Don't hand-roll cursor positioning** — `placement="cursor"` anchors at the
  pointer for you.

### Accessibility

- Always spread the `activator` slot's `props` onto your trigger (or pass an
  `activator`); that is what publishes `aria-expanded` / `aria-controls` /
  `aria-haspopup` and makes the trigger operable by keyboard.
- Focus moves into the panel on open and returns to the activator on close;
  `focus-target` overrides where it lands first.
- **The popover is modal, despite looking like it isn't.** It renders as a
  `<dialog>` opened with `showModal()` (`CommonPopover.vue:271`), so while it is
  open Tab is trapped inside it and the rest of the document is inert —
  `dialog.matches(':modal')` is `true`. What makes it _read_ as non-modal is
  that the `::backdrop` is merely `background-color: transparent`: the page
  behind stays fully visible and un-dimmed. That transparent backdrop is also
  what makes click-outside-to-close work — the outside click lands on it, and
  `@click.self` closes the panel.
  Consequence for design: do **not** plan a flow where the user keeps working
  behind an open popover. They cannot. If the surrounding page must stay live,
  use a non-modal surface instead. For a blocking task that should _look_
  blocking, use `BbDialog`, which dims its backdrop.
- Give an icon-only activator its own `aria-label`; the popover does not name it.

## v-model

- `v-model` — type: `boolean \| undefined`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activator` | `ElementOrComponentRef \| undefined` |  |  | External activator element or component ref. When provided, the activator slot is not rendered and click events are attached programmatically to the referenced element. |
| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile viewports (below `config.mobileMaxWidth`), render the popover as a bottom-anchored, auto-sized off-canvas sheet instead of a floating panel. The `header`, `default` and `footer` slots are forwarded to the sheet. The `width` prop i… |
| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the popover within a bounding element. When provided, the popover will not overflow this container's bounds (e.g. a sidebar). Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
| `focusTarget` | `string \| undefined` |  |  | Selector for the element that receives focus after opening. Defaults to the first focusable element inside the popover. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to open / close the popover. A popover with no `v-model` starts closed and is driven by its `trigger`. |
| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Overrides forwarded to the underlying `BbOffCanvas` when `adaptive` renders the sheet on mobile. Merged over the adaptive defaults (`side: 'bottom'`, `size: 'auto'`, `draggable: true`). Ignored when `adaptive` is `false`. |
| `offset` | `number \| undefined` | `3` |  | Space the floating container will maintain from the activator. |
| `padding` | `number \| undefined` | `10` |  | Minimum empty space to keep from the edge of the page. |
| `placement` | `Placement \| "cursor" \| undefined` | `"bottom"` |  | Position of the popover relative to the activator. Use `'cursor'` to anchor at the mouse/touch coordinates. (BbPopover never draws an arrow — arrows are tooltip-only in v3.) |
| `scrollable` | `boolean \| undefined` | `false` |  | Caps the popover height to the available viewport space and enables internal scrolling. Useful for tall content like filter panels. Not recommended for atomic popovers (calendars, color pickers). |
| `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds. |
| `trigger` | `PopoverTrigger \| PopoverTrigger[] \| undefined` | `"click"` |  | Interaction(s) that open the popover. Accepts a single trigger or an array to combine them. - `'click'` — left-click / tap (default) - `'contextMenu'` — right-click on desktop, long-press on mobile |
| `width` | `string \| number \| undefined` |  |  | Width of the popover. Accepts pixels or percentage (relative to activator width). |

## Events

- `hidden` — `(event: "hidden"): void`
- `hide` — `(event: "hide"): void`
- `show` — `(event: "show"): void`
- `shown` — `(event: "shown"): void`
- `update:modelValue` — `(event: "update:modelValue", value: boolean): void`

## Slots

- `activator` — scope: `BbPopoverActivatorSlotProps` — The element that triggers the popover to open. Spread `props` onto your trigger element.
- `default` — scope: `BbPopoverDefaultSlotProps` — The popover body content rendered inside the floating panel.
- `footer` — scope: `BbPopoverDefaultSlotProps` — Content pinned to the bottom of the panel, outside the scroll region. Stays visible while the body scrolls (when `scrollable`) and carries its own padding and top divider, so footer actions need no negative-margin or `sticky` workarounds.
- `header` — scope: `BbPopoverDefaultSlotProps` — Content pinned to the top of the panel, outside the scroll region. Stays visible while the body scrolls (when `scrollable`) and carries its own padding and bottom divider, so a title or search field needs no negative-margin or `sticky` work…

## See Also

- [BbTooltip](./BbTooltip.md) — Displays contextual helper text on interaction.
- [BbDialog](./BbDialog.md) — Presents modal dialogs for focused user interactions.
- [BbDropdown](./BbDropdown.md) — Displays contextual action menus and menu content (includes the co-located BbDropdownGroup export, which is how a selectable group is bound).

---

<!-- dist/ai/BbProgress.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbProgress.md -->

# BbProgress

## Agent Contract

- Safety level: **Consumer API**
- Group: **Feedback**
- Description: Visualizes task or operation progress state.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbProgress.md](./source/BbProgress.md)

## Usage & Guidelines

### When to use

`BbProgress` is for **determinate** progress — a task whose completion you can
measure: an upload, a multi-step setup, a storage quota. Bind the current value
with `:model-value` and the bar fills from `min` to `max`. If the wait has no
measurable end, use [`BbSpinner`](./BbSpinner.md) instead — passing `null` here
renders an _empty_ bar, not an animated indeterminate state.

The component is purely presentational: it emits no events and never changes the
value on its own. `v-model` compiles but has nothing to write back — prefer the
one-way `:model-value` binding and keep the source of truth in your state.

**Profile completeness**

```vue
<div class="max-w-sm flex flex-col gap-2">
	<div class="flex justify-between text-sm">
		<span>Profile completeness</span>
		<span class="text-[color:var(--bb-text-muted)]">60%</span>
	</div>
	<BbProgress :model-value="60" />
</div>
```

### Storage quota in real units

`max` lets you feed raw domain units — gigabytes, bytes, steps — straight in,
and the bar computes the fill; never pre-compute a percentage when you already
have the real numbers. Pair the bar with a visible textual value so the number
is legible, not just the geometry. Near a soft cap, retint via the `--fill`
hook (a theme token — never a hardcoded hex).

**Team plan storage**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex items-start justify-between gap-3">
			<div class="flex flex-col gap-0.5">
				<span class="text-sm font-medium">Storage</span>
				<span class="text-xs text-[color:var(--bb-text-muted)]">
					Northwind Billing · Team plan
				</span>
			</div>
			<span class="text-xs tabular-nums text-[color:var(--bb-text-muted)]">
				{{ usedGb }} / {{ maxGb }} GB
			</span>
		</div>

		<BbProgress
			aria-label="Storage used"
			:aria-valuetext="`${usedGb} of ${maxGb} gigabytes`"
			class="[--track:6px]"
			:max="maxGb"
			:model-value="usedGb"
			:style="nearLimit ? { '--fill': 'var(--bb-danger)' } : undefined"
		/>

		<div class="flex items-center justify-between gap-3">
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				{{ remainingGb }} GB free
				<template v-if="nearLimit"> · nearly full</template>
			</span>
			<BbButton href="#billing" text="Upgrade plan" variant="outline" />
		</div>
	</div>
</template>

<script setup lang="ts">
import { BbButton, BbProgress } from 'bitboss-ui';

// Domain units go straight into `max` / `model-value` — no pre-computed %.
// Near the cap, retint via the sanctioned `--fill` hook (token, not a hex).
const usedGb = 42.6;
const maxGb = 50;
const remainingGb = Number((maxGb - usedGb).toFixed(1));
const nearLimit = usedGb / maxGb >= 0.8;
</script>
```

`min` shifts the lower bound for ranges that don't start at zero (a sales floor,
a level's XP band). Out-of-range values are clamped — below `min` renders empty,
above `max` renders full — and a degenerate range (`max <= min`) safely renders
an empty bar. Value changes animate over 250 ms on their own — via `transform`,
not `width`, so the bar composites instead of relaying out. Don't add your own
transition.

**A range that does not start at zero**

```vue
<div class="max-w-sm flex flex-col gap-2">
	<div class="flex justify-between text-sm">
		<span>Q3 sales target</span>
		<span class="text-[color:var(--bb-text-muted)]">€310k of the €250–370k band</span>
	</div>
	<BbProgress :min="250" :max="370" :model-value="310" />
</div>
```

### Upload progress

Drive the bar from live state — here each chunk advances the value, and the
percentage label is derived from the same source of truth.

**Chunked upload**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex items-center justify-between gap-3">
			<span class="flex min-w-0 items-center gap-2 text-sm font-medium">
				<BbIcon icon="lucide:file-up" size="sm" />
				<span class="truncate">quarterly-report.pdf</span>
			</span>
			<span
				class="shrink-0 text-xs tabular-nums text-[color:var(--bb-text-muted)]"
			>
				{{ uploadedMb }} / {{ totalMb }} MB
			</span>
		</div>

		<BbProgress
			aria-label="Uploading quarterly-report.pdf"
			:aria-valuetext="`${percent} percent uploaded`"
			:max="totalMb"
			:model-value="uploadedMb"
		/>

		<div class="flex items-center justify-between gap-3">
			<span class="text-xs tabular-nums text-[color:var(--bb-text-muted)]">
				{{ percent }}% uploaded
			</span>
			<BbButton
				append:icon="lucide:upload"
				:disabled="done"
				:text="done ? 'Uploaded' : 'Upload chunk'"
				variant="outline"
				@click="onUploadChunk"
			/>
		</div>
	</div>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbButton, BbIcon, BbProgress } from 'bitboss-ui';

// Real units drive the bar via `max` — no need to pre-compute a percentage for
// the component. The label is derived from the same source of truth.
const totalMb = 512;
const chunkMb = 64;

const uploadedMb = ref(0);
const percent = computed(() => Math.round((uploadedMb.value / totalMb) * 100));
const done = computed(() => uploadedMb.value >= totalMb);

/** Advance one simulated chunk; clamps at the file size. */
const onUploadChunk = () => {
	uploadedMb.value = Math.min(totalMb, uploadedMb.value + chunkMb);
};
</script>
```

For real uploads, pair with `BbDropzone` (it captures and validates files but
does **not** upload) and feed the bar from your request layer's progress
events, then confirm with `useToast`:

```vue
<BbDropzone v-model="file" :accept="['.csv']" />
<BbProgress v-if="uploading" :max="totalBytes" :model-value="sentBytes" />
```

```ts
const { toast } = useToast();
await axios.post('/imports', form, {
	onUploadProgress: (e) => (sentBytes.value = e.loaded),
});
toast({ title: 'Import complete', variant: 'success' });
```

### Handing off to an unmeasurable phase

Uploads often finish before the work does: the server still parses rows,
transcodes, indexes — with no measurable progress. Swap the bar for
[`BbSpinner`](./BbSpinner.md) at that boundary instead of faking a bar that
creeps toward 99%. The determinate phase gets `BbProgress`, the indeterminate
one gets a spinner, and completion is derived from your own state — the bar
emits nothing.

**CSV import: upload, then processing**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex items-center justify-between gap-3">
			<span class="flex min-w-0 items-center gap-2 text-sm font-medium">
				<BbIcon icon="lucide:file-spreadsheet" size="sm" />
				<span class="truncate">contacts.csv</span>
			</span>
			<span
				class="shrink-0 text-xs tabular-nums text-[color:var(--bb-text-muted)]"
			>
				{{ statusLabel }}
			</span>
		</div>

		<!-- Measurable phase: the bar, in real units via `max`. -->
		<BbProgress
			v-if="phase === 'idle' || phase === 'uploading'"
			aria-label="Uploading contacts.csv"
			:max="totalKb"
			:model-value="sentKb"
		/>
		<!-- Unmeasurable phase: swap to a spinner — never fake a creeping bar. -->
		<div
			v-else-if="phase === 'processing'"
			class="flex items-center gap-2 text-sm text-[color:var(--bb-text-muted)]"
			role="status"
		>
			<BbSpinner size="sm" />
			Processing 1,284 rows…
		</div>
		<div v-else class="flex items-center gap-2 text-sm">
			<BbIcon icon="lucide:check" size="sm" />
			1,284 contacts imported
		</div>

		<div class="flex justify-end">
			<BbButton
				:disabled="phase === 'uploading' || phase === 'processing'"
				prepend:icon="lucide:upload"
				:text="phase === 'done' ? 'Import again' : 'Import contacts'"
				variant="outline"
				@click="onStartImport"
			/>
		</div>
	</div>
</template>

<script setup lang="ts">
import { computed, onUnmounted, ref } from 'vue';
import { BbButton, BbIcon, BbProgress, BbSpinner } from 'bitboss-ui';

type Phase = 'idle' | 'uploading' | 'processing' | 'done';

// Simulated transfer: the upload is measurable (bytes sent), the server-side
// row parsing that follows is not — that boundary is where the bar hands off
// to BbSpinner.
const totalKb = 640;
const chunkKb = 80;

const phase = ref<Phase>('idle');
const sentKb = ref(0);

let timer: ReturnType<typeof setInterval> | undefined;
onUnmounted(() => {
	if (timer !== undefined) clearInterval(timer);
});

const statusLabel = computed(() => {
	if (phase.value === 'uploading') return `${sentKb.value} / ${totalKb} KB`;
	if (phase.value === 'processing') return 'Upload complete';
	if (phase.value === 'done') return 'Done';
	return `${totalKb} KB`;
});

/** Run the upload → processing → done sequence with deterministic timers. */
const onStartImport = () => {
	phase.value = 'uploading';
	sentKb.value = 0;
	timer = setInterval(() => {
		sentKb.value = Math.min(totalKb, sentKb.value + chunkKb);
		if (sentKb.value < totalKb) return;
		if (timer !== undefined) clearInterval(timer);
		phase.value = 'processing';
		setTimeout(() => {
			phase.value = 'done';
		}, 500);
	}, 70);
};
</script>
```

### Onboarding steps

Multi-step flows read better with a completion bar than with a spinner: set
`max` to the number of steps and pass the 1-based current step. The built-in
fill transition animates each advance for free.

**Workspace setup**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex items-center justify-between gap-3">
			<div class="flex flex-col gap-0.5">
				<span class="text-sm font-medium">Workspace setup</span>
				<span class="text-xs text-[color:var(--bb-text-muted)]">{{
					steps[step]
				}}</span>
			</div>
			<span class="text-xs tabular-nums text-[color:var(--bb-text-muted)]">
				Step {{ step + 1 }} of {{ steps.length }}
			</span>
		</div>

		<BbProgress
			aria-label="Workspace setup progress"
			:aria-valuetext="`Step ${step + 1} of ${steps.length}`"
			:max="steps.length"
			:model-value="step + 1"
		/>

		<ul class="flex flex-col gap-1.5">
			<li
				v-for="(label, index) in steps"
				:key="label"
				class="flex items-center gap-2 text-sm"
				:class="index <= step ? '' : 'text-[color:var(--bb-text-muted)]'"
			>
				<BbIcon
					:icon="index < step ? 'lucide:circle-check' : 'lucide:circle'"
					size="sm"
				/>
				{{ label }}
			</li>
		</ul>

		<div class="flex items-center justify-between gap-3">
			<BbButton
				:disabled="step === 0"
				text="Back"
				variant="ghost"
				@click="onBack"
			/>
			<BbButton
				append:icon="lucide:arrow-right"
				:disabled="step === steps.length - 1"
				text="Continue"
				@click="onContinue"
			/>
		</div>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbIcon, BbProgress } from 'bitboss-ui';

// `max` = number of steps, model = 1-based current step: the bar shows how far
// through onboarding the user is, and each advance animates via the built-in
// fill transition.
const steps = [
	'Create workspace',
	'Invite teammates',
	'Connect billing',
	'Create first project',
];
const step = ref(0);

const onBack = () => {
	step.value -= 1;
};

const onContinue = () => {
	step.value += 1;
};
</script>
```

### Styling the track

There are no color or size props. The component exposes two CSS hooks —
`--track` (track height, default `4px`) and `--fill` (fill color, default
`var(--bb-primary)`, painted over a subtle track tint) — so quota bars can
shift color without touching internals. The storage example above uses both
hooks; the snippet below is the minimal `--track` override. Anything beyond
these two hooks means restyling component internals — keep such overrides in a
token/theme layer, not scattered per-usage.

**A thicker track via the --track hook**

```vue
<div class="max-w-sm">
	<BbProgress class="[--track:8px]" :model-value="45" />
</div>
```

### Works well with

- `BbDropzone` — captures the files; you upload and drive the bar (see above).
- [`BbSpinner`](./BbSpinner.md) — for the phases you _can't_ measure (e.g.
  server-side processing after the upload hits 100%). Swap components, don't
  fake a creeping bar — see the CSV import example above.
- `useToast` — announce completion once the task finishes; the bar alone is a
  silent visual.
- `BbTable` — for table data loads use its built-in `loading` skeleton, not a
  progress bar.

### Gotchas & anti-patterns

- **`modelValue: null` renders an empty bar.** There is no indeterminate
  animation; for unknown waits use `BbSpinner`.
- **Don't restate the built-in ARIA.** The bar already exposes
  `role="progressbar"` with `aria-valuemin/max/now` — wrapping it in another
  `role="progressbar"` double-announces (see Accessibility). Add a label, not
  a role.
- **No events.** Don't listen for `update:modelValue` or a "complete" event —
  derive completion from your own state (`value >= max`).
- Don't pre-compute percentages when you hold real units — pass `max` instead.
- Don't animate the fill yourself (CSS transitions or manual `setInterval`
  easing) — the 250 ms transition is built in.
- Don't rebuild the bar from `<div>`s to get a different height — override
  `--track`.

### Accessibility

The bar carries its own ARIA: `role="progressbar"` with `aria-valuemin`,
`aria-valuemax`, and `aria-valuenow` kept in sync with `min`/`max`/the model
value (out-of-range values are clamped, matching the visual fill). A `null`
value reports `aria-valuenow` = `min`, matching the empty bar it renders —
the component never signals "indeterminate" to assistive tech, because it has
no indeterminate mode (that's `BbSpinner`). Do **not** wrap the component in
another `role="progressbar"`.

What's still on you:

- **An accessible name.** Prefer the **`label` prop** — it forwards to
  `aria-label` on the progressbar and is the same naming prop `BbSpinner` and
  `BbIcon` carry, so one spelling covers all three. A raw `aria-label` (or
  `aria-labelledby`) still falls through if you need it.
- **A visible textual value** beside the bar (`72%`, `220 / 500 GB`) so the
  number is legible, not just the geometry. Add `aria-valuetext` when raw
  numbers read poorly (units, steps).

**A labelled, unit-aware bar**

```vue
<div class="max-w-sm flex flex-col gap-2">
	<div class="flex justify-between text-sm">
		<span>Storage used</span>
		<span class="text-[color:var(--bb-text-muted)]">220 / 500 GB</span>
	</div>
	<BbProgress
		aria-label="Storage used"
		aria-valuetext="220 of 500 gigabytes"
		:max="500"
		:model-value="220"
	/>
</div>
```

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `string \| undefined` | `undefined` |  | Accessible name for the progress bar, forwarded to `aria-label`. A `progressbar` with no name is announced only as a bare percentage, so give it one whenever the surrounding text doesn't already name it (e.g. `"Upload"`). Matches the `label… |
| `max` | `number \| undefined` | `100` |  | Maximum value. Upper cap. |
| `min` | `number \| undefined` | `0` |  | Minimum value. Lower cap. |
| `modelValue` | `number \| null` | `0` | yes | The current progress value — a number between `min` and `max`. This is a one-way input prop (BbProgress is a display component and never emits `update:modelValue`); `null` means no value and renders an empty bar. |

## Events

- None.

## Slots

- None.

## See Also

- [BbSpinner](./BbSpinner.md) — Indicates ongoing loading or pending operations.

---

<!-- dist/ai/BbRadio.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbRadio.md -->

# BbRadio

## Agent Contract

- Safety level: **Consumer API**
- Group: **Selection**
- Description: Represents a single choice in exclusive options.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbRadio.md](./source/BbRadio.md)

## Usage & Guidelines

### When to use

Almost always, **don't** — reach for `BbRadioGroup`. It wraps the same buttons in
a real `<fieldset>` / `<legend>`, maps your `items`, wires the shared `name` +
`v-model`, and gives you native arrow-key navigation for free. A lone `BbRadio`
only earns its place as an escape hatch: when the options must be **interleaved
with other markup** — a pricing card per option, a radio inside each table row —
or when a single option needs **bespoke label content** (a badge, emphasis) that
the group's uniform `items` mapping can't express.

Match the choice to the component:

- Exclusive choice from a small set, standard layout → `BbRadioGroup`.
- Exclusive choice from a large/dynamic set → `BbSelect`.
- Independent yes/no → `BbCheckbox`.
- If you only reach for `BbRadio` to stack a few options in a box → that's
  `BbRadioGroup`; use it instead.

### Composing a group by hand

Three things make a set of `BbRadio` behave as one exclusive group: a shared
`name`, the same `v-model`, and a **distinct `value` per button**. Selecting one
deselects the rest because they share the model, and because they are real native
radios sharing a `name`, the browser gives you **roving focus** across them for
free (Tab reaches the group once; arrow keys move focus and selection between the
buttons, wrapping around). What you don't get for free is the grouping
_semantics_ — you own the container, its `role="radiogroup"`, and its accessible
name (see Accessibility).

**Plan cards, one BbRadio each**

```vue
<template>
	<div
		aria-label="Workspace plan"
		class="grid max-w-sm gap-2"
		role="radiogroup"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Workspace plan</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Billed monthly · cancel anytime
			</p>
		</div>
		<div
			v-for="plan in plans"
			:key="plan.value"
			class="flex items-start justify-between gap-3 rounded-[var(--bb-radius)] border p-2.5"
			:class="
				selected === plan.value
					? 'border-[color:var(--bb-primary)]'
					: 'border-[color:var(--bb-border)]'
			"
		>
			<BbRadio
				v-model="selected"
				:description="plan.description"
				:label="plan.label"
				name="plan"
				:value="plan.value"
			/>
			<span class="shrink-0 pt-0.5 text-xs font-medium tabular-nums">
				{{ plan.price }}
			</span>
		</div>
		<p class="plan-summary text-xs text-[color:var(--bb-text-muted)]">
			Selected plan: {{ selected }}
		</p>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbRadio } from 'bitboss-ui';

type Plan = {
	value: string;
	label: string;
	description: string;
	price: string;
};

const plans: Plan[] = [
	{
		value: 'starter',
		label: 'Starter',
		description: 'For individuals getting started.',
		price: 'Free',
	},
	{
		value: 'pro',
		label: 'Pro',
		description: 'For growing teams that need more.',
		price: '$12/mo',
	},
	{
		value: 'scale',
		label: 'Scale',
		description: 'Advanced controls and priority support.',
		price: '$49/mo',
	},
];

const selected = ref<string>('pro');
</script>
```

`label` and `value` are **required** on each button. `value` is what lands in the
model when that button is chosen — any serializable value works (matched
structurally), but prefer stable primitive ids.

`name` is **optional** — an omitted one falls back to a generated name, unique to
that button and stable for its lifetime, so a lone radio is never left unnamed.
But that is exactly why a hand-composed group must still pass one **shared,
explicit** `name` on every button: generated names differ per button, so buttons
without a `name` never form a native group.

### States, hint and validation

Each `BbRadio` carries the full form-field surface — `hint`, `description`,
`errors` / `has-errors`, `readonly`, `disabled`, `required`. `description` is
always-visible helper text; `hint` appears on focus unless you pin it with
`persistent-hint`; both wire to the input via `aria-describedby`. A non-empty
`errors` (string or array) puts the button in the error state on its own;
`has-errors` styles the invalid state without messages. **`warnings`** is the
amber counterpart of `errors` — a string or array rendered below the button in
its own `aria-live="polite"` region (also referenced from `aria-describedby`
while displayed) for a valid-but-noteworthy value where a hard
error would overstate the problem, and a non-empty `warnings` implies the warning
state just as `errors` implies the error state; **`has-warning`** forces that
amber chrome without a message. Unlike `has-errors`, neither sets `aria-invalid` —
a soft "needs a second look" rather than an invalid state — and `has-errors` wins
when both are set, suppressing the warning messages so the button never shows
amber and red at once.

**Readonly, error and disabled**

```vue
<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-3">
	<BbRadio
		:model-value="'locked'"
		value="locked"
		label="SSO enforced"
		name="r-ro"
		readonly
		description="Your organization requires single sign-on."
	/>
	<BbRadio
		value="invalid"
		label="Needs a valid choice"
		name="r-err"
		has-errors
		errors="Please choose a merge method."
	/>
	<BbRadio
		value="off"
		label="Unavailable on free plan"
		name="r-dis"
		disabled
	/>
</div>
```

How the two locked states differ:

- `disabled` sets the **native** attribute: the button leaves the tab order and
  its value never submits.
- `readonly` does **not** set the native `disabled` attribute (radios have no
  native readonly). The input stays focusable, still submits its value, and the
  component swallows every change. Use it for a value the user may see and that
  must still post, but not change. A lone radio cannot announce the state —
  `role="radio"` supports no `aria-readonly` — so say so in nearby copy, or use
  `BbRadioGroup`, whose `radiogroup` does carry it.

### Forcing the state with `checked`

`checked` (booleanish: `true`/`false` or `'true'`/`'false'`) overrides the
model-derived display: when set, the button shows that state regardless of
`modelValue`, and re-syncs when the prop changes. Interaction still emits
`update:modelValue`. Use it when the checked display is derived from elsewhere
(server state, a parent aggregate) and you handle updates through events rather
than `v-model`. `checked` + `v-model` fight each other — pick one source of
truth.

### Custom label and dot visual

The `label` slot (`{ text, hasErrors }`) replaces the label text — use it to
append a `BbBadge` or emphasis while keeping the accessible name. Per-option
label content is the other reason to hand-compose: `BbRadioGroup` maps uniform
`items`, so the moment one option needs a "Recommended" badge you're back to
individual `BbRadio` buttons.

**Merge method with a Recommended badge**

```vue
<template>
	<div
		aria-label="Merge method"
		class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-3"
		role="radiogroup"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Merge pull request #482</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				feature/invoice-export → main
			</p>
		</div>
		<BbRadio
			v-model="strategy"
			description="All commits from the branch are added via a merge commit."
			label="Create a merge commit"
			name="merge-method"
			value="merge"
		/>
		<BbRadio
			v-model="strategy"
			description="Combine all commits into a single commit on the base branch."
			label="Squash and merge"
			name="merge-method"
			value="squash"
		>
			<template #label="{ text }">
				<span class="inline-flex items-center gap-1.5">
					{{ text }}
					<BbBadge size="xs" variant="secondary">Recommended</BbBadge>
				</span>
			</template>
		</BbRadio>
		<BbRadio
			v-model="strategy"
			description="Reapply each commit on the base branch, without a merge commit."
			label="Rebase and merge"
			name="merge-method"
			value="rebase"
		/>
		<p class="merge-summary text-xs text-[color:var(--bb-text-muted)]">
			Pull request #482 will be merged via {{ labels[strategy] }}.
		</p>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbBadge, BbRadio } from 'bitboss-ui';

type MergeMethod = 'merge' | 'squash' | 'rebase';

const labels: Record<MergeMethod, string> = {
	merge: 'a merge commit',
	squash: 'squash and merge',
	rebase: 'rebase and merge',
};

const strategy = ref<MergeMethod>('squash');
</script>
```

The `icon` slot
replaces the **entire radio-dot visual**; it receives the live state
(`checked`, `focused`, `focusVisible`, `disabled`, `readonly`, `hasErrors`,
`value`, `text`), so your slot must communicate selected/unselected and the focus
ring itself.

### Layout

- `direction` defaults to `'auto'` (label and button size to content, one line);
  `'horizontal'` / `'vertical'` / a pattern like `'xx xxxxx'` split them
  proportionally.
- `input-position` / `label-position` (`'left' | 'center' | 'right'`) align the
  button and label text within their columns.
- `hide-label` keeps the label for screen readers but hides it visually.
- **`reverse`** swaps the label in front of the button. It is an ordinary
  opt-in boolean: unset and `:reverse="false"` both put the button first,
  `reverse` puts the label first. (The source negates it internally to cancel
  `BbBaseInputContainer`'s own polarity; that is invisible from outside.
  Earlier revisions of this guide called it a consumer-facing quirk — it is
  not, and the same correction applies to `BbCheckbox` and `BbSwitch`.)

### Events and focus

`update:modelValue` (the `v-model` channel) carries the selected `value` — the
only selection-of-truth channel. The native `blur`, `change`, `click`, `focus`,
`input`, `keydown`, `mousedown`, `mouseup` events re-emit with raw payloads;
listen to them for side concerns only. `autofocus` focuses the input on mount.

### Works well with

- `BbRadioGroup` — the default you should reach for first; this is only the
  interleaving escape hatch (`./BbRadioGroup.md`).
- `BbCheckbox` — the independent-boolean sibling with the same field chrome.
- `BbBadge` — via the `label` slot, to tag an option ("Popular", "Beta").

### Gotchas and anti-patterns

- Don't hand-compose a plain stacked group of `BbRadio` — that's `BbRadioGroup`,
  which adds the fieldset, roving focus and item mapping.
- A radio with no `value`, or one whose `name` differs from its siblings, won't
  form an exclusive group — the browser treats them independently. Omitting
  `name` on a hand-composed group is the same mistake: each button then falls
  back to its own generated name.
- Hand-composed groups have **no** fieldset semantics on their own — wrap them in
  a `role="radiogroup"` element with an accessible name (see Accessibility).
- `reverse` is an opt-in, not a toggle you turn off: unset already means
  button-first. Setting `:reverse="false"` is legal but says nothing.
- `checked` + `v-model` together fight; pick one.
- `readonly` still submits and stays focusable; use `disabled` when the value
  must not post.

### Accessibility

- A radio must have a `value` and share an explicit `name` with its siblings, or
  the browser won't treat them as one exclusive group — the generated fallback
  name is per-button and groups nothing.
- Hand-composed groups have **no** fieldset semantics on their own — wrap them in
  an element with `role="radiogroup"` and an `aria-label` / `aria-labelledby`, or
  just use `BbRadioGroup`, which does this for you.
- `errors`, `warnings`, `description` and `hint` are all wired to the input through
  `aria-describedby`, in that order: the reason the field is invalid is spoken
  first when it regains focus, and a channel is referenced only while it
  actually has copy. Messages _also_ render in an `aria-live="polite"` region,
  so they are announced the moment they appear — announced on change, re-read
  on focus. Keep messages meaningful, not decorative.
- `readonly` still submits its value but is not announced on a single radio (the
  `radio` role has no `aria-readonly`) — explain it in nearby copy; `disabled`
  removes the option from the tab order entirely.
- With a custom `icon` slot, all state styling is yours — keep `checked`,
  `focusVisible` and `hasErrors` visually distinguishable.

## v-model

- `v-model` — type: `any`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
| `checked` | `boolean \| undefined` | `undefined` |  | Defines the input as checked. |
| `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
| `direction` | `InputDirection \| undefined` | `"auto"` |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `inputPosition` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can. |
| `label` | `string` |  | yes | Text content of the label of the element. |
| `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
| `modelValue` | `any` |  |  | Used by v-model. Can be any serializable type. |
| `name` | `string \| undefined` |  |  | Defines the name of the input. Optional: an omitted name falls back to a generated one, unique to this button and stable for its lifetime, so a lone radio needs no name at all. Buttons that must form ONE exclusive group still have to share … |
| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout: in every direction the order of the label and the input is swapped from the standard arrangement. |
| `value` | `any` |  | yes | Defines the value of the radio input. It can be any serializable value. |
| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |

## Events

- `blur` — `(event: "blur", event: FocusEvent): void`
- `change` — `(event: "change", event: Event): void`
- `click` — `(event: "click", event: MouseEvent): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `input` — `(event: "input", event: Event): void`
- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
- `update:modelValue` — `(event: "update:modelValue", value: any): void`

## Slots

- `icon` — scope: `BbRadioIconSlotProps` — Replaces the default radio dot visual inside the radio container. Receives `BaseRadio` slot attributes plus the label text.
- `label` — scope: `BbRadioLabelSlotProps` — Replaces the default label text rendered next to the radio button.

## See Also

- [BbRadioGroup](./BbRadioGroup.md) — Coordinates exclusive selection among radio options.
- [BbCheckbox](./BbCheckbox.md) — Toggles a single boolean option.

---

<!-- dist/ai/BbRadioGroup.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbRadioGroup.md -->

# BbRadioGroup

## Agent Contract

- Safety level: **Consumer API**
- Group: **Selection**
- Description: Coordinates exclusive selection among radio options.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbRadioGroup.md](./source/BbRadioGroup.md)

## Usage & Guidelines

### When to use

Use `BbRadioGroup` when the user must pick **exactly one** option from a short,
fixed list that's worth showing in full — billing cycle, shipping speed, a plan.
It renders one `<fieldset>` / `<legend>`, binds a **single** value, and maps each
button from your `items`.

Choose by shape:

- Several **non-exclusive** choices → `BbCheckboxGroup`.
- A large or dynamic/async option set → `BbSelect` (adds search + fetch); radios
  past ~6 options become a wall to scan.
- Radios that must be interleaved with other markup, with no container that fits
  → the standalone `BbRadio` escape hatch. For a plain stacked group, stay here.
- A single independent yes/no → `BbCheckbox`.

### Items and value mapping

Pass domain objects to `items` and resolve the display text and stored value
with `item-text` / `item-value` — a dot-path or a function. The bound model
holds only the mapped value (an id), which is what you persist. Primitive
`items` (`string[]`) need no mapping and bind to the string itself. Values match
by **deep equality**, and duplicate `item-value`s collapse to one button (first
wins) — see the
[options & items playbook](../../ai/guides/options-items-playbook.md).

**Plan selection from objects**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
	>
		<BbRadioGroup
			v-model="plan"
			compact
			description="Switch or cancel anytime from settings."
			:item-text="planLabel"
			item-value="id"
			:items="plans"
			legend="Subscription plan"
			name="plan"
		/>
		<p class="plan-summary text-xs text-[var(--bb-text-muted)]">
			Selected: {{ plan }}
		</p>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbRadioGroup } from 'bitboss-ui';

type Plan = {
	id: string;
	label: string;
	price: string;
};

const plans: Plan[] = [
	{ id: 'starter', label: 'Starter', price: 'Free' },
	{ id: 'pro', label: 'Pro', price: '$12/mo' },
	{ id: 'scale', label: 'Scale', price: '$49/mo' },
];

/** Formats each plan as "Label — price" for the option text. */
const planLabel = (plan: Plan) => `${plan.label} — ${plan.price}`;

const plan = ref<string>('pro');
</script>
```

### The model is a single value

Unlike the checkbox and switch groups, `BbRadioGroup` is **single-only** — there
is no `multiple` prop. Seed the ref with `null` (or a default option's value),
**not** an array:

```ts
const plan = ref<string | null>(null); // correct
const plan = ref<string[]>([]); // wrong — radio groups don't bind arrays
```

Picking an option **replaces** the value; a radio group can't be emptied by the
user (there's no uncheck). If "none" is a legitimate answer, add an explicit
option for it rather than expecting a cleared model.

### Layout and density

Options flow in a **wrapping row by default** — `BbBaseRadioGroup` defaults its
direction to `'horizontal'`, which suits segmented-style choices (shipping
speed, billing cycle). Pass `input-direction="vertical"` to stack them one per
line, which is what you want for long option text or a scannable list.
`compact` tightens spacing. Because a radio group binds a single value, it drives cleanly
from `v-model` inline.

**Horizontal shipping speed**

```vue
<template>
	<div class="max-w-sm rounded-[var(--bb-radius)] border p-4">
		<BbRadioGroup
			v-model="speed"
			compact
			hint="Express arrives in 1–2 business days."
			input-direction="horizontal"
			:items="['Standard', 'Express', 'Overnight']"
			legend="Shipping speed"
			name="shipping-speed"
			persistent-hint
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbRadioGroup } from 'bitboss-ui';

const speed = ref<string>('Standard');
</script>
```

`direction` splits the legend against the options block (`'auto'`,
`'horizontal'`, `'vertical'`, or a pattern like `'xx xxxxxx'`);
`input-position` / `legend-position` align options and legend within their
columns; `reverse` swaps legend and options order (a plain swap here, not
inverted); `hide-legend` hides the legend visually while keeping it for
assistive tech.

### Legend, validation and required

The `legend` names the group — always set it. `description` is always-visible
helper text; `hint` shows on focus (`persistent-hint` to pin it); both wire to
the group via `aria-describedby`. `errors` (string or array) renders messages
and puts the group in the error state; `has-errors` toggles the invalid styling
alone. **`warnings`** (string or array) is the amber counterpart of `errors` —
rendered below the group in its own `aria-live="polite"` region (also
referenced from `aria-describedby` while displayed) for a
valid-but-noteworthy choice (unusual, near a limit, soft-flagged), and a
non-empty `warnings` implies the warning state just as `errors` implies the error
state; **`has-warning`** forces that amber chrome without a message. Unlike
`has-errors`, neither sets `aria-invalid` — a soft "needs a second look", not an
invalid value — and `has-errors` wins when both are set, suppressing the warning
messages so the group never shows amber and red at once. `required` marks the group as required — because these are native radios,
it participates in native form validation. `legend-mode` places the legend
`'outside'` (default) or `'inside'` the fieldset border.

**Required billing cycle with an error**

```vue
<template>
	<div class="max-w-sm rounded-[var(--bb-radius)] border p-4">
		<BbRadioGroup
			v-model="cycle"
			compact
			description="Yearly billing saves 20% over monthly."
			:errors="cycleError"
			:has-errors="!cycle"
			:items="['Monthly', 'Yearly']"
			legend="Billing cycle"
			legend-mode="inside"
			name="billing-cycle"
			required
		/>
	</div>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbRadioGroup } from 'bitboss-ui';

// Seed with null: a radio group binds a single value, never an array.
const cycle = ref<string | null>(null);

/** Error clears the moment a valid option is picked. */
const cycleError = computed(() =>
	cycle.value ? undefined : 'Pick a billing cycle to continue.'
);
</script>
```

### Keyboard model

The options are real native `<input type="radio">` sharing one `name`, so the
group uses the browser's native **roving focus**, no custom JS. `name` is
**optional**: omit it and the group generates one for itself — unique per group
instance and stable for its lifetime, so the options group correctly and two
groups on the same page never clear each other. Pass a `name` only when the
value has to post under a known key in a native (non-JS) form submit.

- The whole group is a **single Tab stop**. Tab enters it on the checked option
  (or the first option when nothing is checked yet) and one more Tab leaves the
  group entirely.
- **Arrow keys** move focus **and** selection together to the adjacent option —
  Down/Right to the next, Up/Left to the previous — wrapping around the ends.
  This is why a radio group is one exclusive choice: moving focus selects.
- Disabled options are skipped during arrow navigation.

Keep the set short enough that arrow-cycling stays quick; past ~6 options prefer
`BbSelect`.

### Async items, loading and coherence

`items` accepts a provider function for options fetched from an API;
`loading-text` / `#loading` and `no-data-text` / `#no-data` cover the loading
and empty states, `dependencies` (+ `deps-debounce-time`) trigger re-fetches,
and `enforce-coherence` resets the model to `null` when the current value no
longer matches an available option. See the
[fetch-items](../../ai/guides/fetch-items-playbook.md) and
[coherence](../../ai/guides/coherence-playbook.md) playbooks.

The classic shape is a pair of tied fields: below, the merge strategies a
repository allows depend on the target branch. The provider uses the non-query
group signature `(prefill, modelValue)` — `prefill` is `true` on every fetch
the group starts itself (mount load and dependency-driven refetches alike).
`prefill === false` means the user typed, and a group has no search field, so
it always passes `true`. Switch the branch to `main` while "Create a merge
commit" is selected and the refetched options no longer contain it, so
coherence resets the model. Because the model is a single value there is no
array to filter — enforcement resolves to `null`, so treat `null` as "nothing
valid yet" and gate the submit on it.

**Merge strategy constrained by branch rules**

```vue
<template>
	<div
		class="flex max-w-md flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
	>
		<BbRadioGroup
			v-model="branch"
			compact
			input-direction="horizontal"
			item-text="label"
			item-value="id"
			:items="branches"
			legend="Target branch"
			name="merge-branch"
		/>
		<BbRadioGroup
			v-model="strategy"
			compact
			:dependencies="[branch]"
			:deps-debounce-time="150"
			enforce-coherence
			hint="Protected branches require a linear history."
			item-text="label"
			item-value="id"
			:items="loadStrategies"
			legend="Merge strategy"
			loading-text="Checking branch rules…"
			name="merge-strategy"
			persistent-hint
		/>
		<p class="strategy-summary text-xs text-[var(--bb-text-muted)]">
			Strategy: {{ strategy ?? 'none selected' }}
		</p>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbRadioGroup } from 'bitboss-ui';

type BranchId = 'develop' | 'main';

type Strategy = {
	id: 'merge' | 'squash' | 'rebase';
	label: string;
	branches: BranchId[];
};

const branches: Array<{ id: BranchId; label: string }> = [
	{ id: 'develop', label: 'develop' },
	{ id: 'main', label: 'main (protected)' },
];

const allStrategies: Strategy[] = [
	{ id: 'merge', label: 'Create a merge commit', branches: ['develop'] },
	{ id: 'squash', label: 'Squash and merge', branches: ['develop', 'main'] },
	{ id: 'rebase', label: 'Rebase and merge', branches: ['develop', 'main'] },
];

const branch = ref<BranchId>('develop');
const strategy = ref<string | null>('merge');

// Group provider signature: (prefill, modelValue). `prefill` is true on every
// fetch the group starts itself — the mount load and dependency-driven
// refetches alike; only a user-typed query reads false, and a group has no
// search field.
const loadStrategies = (
	_prefill: boolean,
	_modelValue?: string | null
): Promise<Strategy[]> =>
	new Promise((resolve) => {
		setTimeout(
			() =>
				resolve(
					allStrategies.filter((item) => item.branches.includes(branch.value))
				),
			300
		);
	});
</script>
```

### Slots

`#label` replaces an option's text (`{ item, text, checked }` — `checked` is what tile layouts key off); `#icon` replaces the
default radio-dot visual for each option (you then own its selected/focus
styling). `#legend` replaces the fieldset legend (`{ text, hasErrors, hasWarning }`; the validated wrappers add `showAsterisk`);
`#prepend` / `#append` inject content inside the options container.

### Selection tiles

For a small set of mutually-exclusive choices that read better as cards than a
plain list — theme (light/dark/system), an import mode — compose `#icon` +
`#label` with CSS on `.bb-base-radio-group-option`. Don't reach for a bespoke
tile component or a 2-option `BbSelect`; the semantics (one `<fieldset>`,
native roving focus, one bound value) are exactly what this component already
gives you. Each option's `<label>` picks up a `bb-base-radio-group-option--selected`
modifier class when checked — style off that, not a `:has()` selector.

**Theme selection tiles**

```vue
<template>
	<div class="max-w-md rounded-[var(--bb-radius)] border p-4">
		<BbRadioGroup
			v-model="theme"
			class="theme-tiles"
			input-direction="horizontal"
			item-text="label"
			item-value="id"
			:items="themes"
			legend="Appearance"
			name="theme"
		>
			<template #icon="{ item }">
				<BbIcon :icon="item.icon" size="lg" />
			</template>
			<template #label="{ text }">
				<span class="theme-tiles__label">{{ text }}</span>
			</template>
		</BbRadioGroup>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbIcon, BbRadioGroup } from 'bitboss-ui';

type Theme = { id: string; label: string; icon: string };

const themes: Theme[] = [
	{ id: 'light', label: 'Light', icon: 'lucide:sun' },
	{ id: 'dark', label: 'Dark', icon: 'lucide:moon' },
	{ id: 'system', label: 'System', icon: 'lucide:monitor' },
];

const theme = ref<string>('system');
</script>
<style scoped>
/*
 * Tiles: each option is `display: inline-flex` by default (content-sized),
 * so `flex: 1 1 0` on the option itself is what makes three tiles share the
 * row evenly — the row (`__container`) is a plain wrapping flexbox, not a grid.
 */
.theme-tiles :deep(.bb-base-radio-group__container) {
	flex-wrap: nowrap;
}

.theme-tiles :deep(.bb-base-radio-group-option) {
	border: var(--bb-border-w) solid var(--bb-border);
	border-radius: var(--bb-radius);
	flex: 1 1 0;
	flex-direction: column;
	justify-content: center;
	padding: 12px;
	row-gap: 6px;
}

.theme-tiles :deep(.bb-base-radio-group-option--selected) {
	background: color-mix(in oklab, var(--bb-primary) 8%, var(--bb-panel));
	border-color: var(--bb-primary);
}

.theme-tiles__label {
	font-size: var(--bb-label-fs);
}
</style>
```

Two width facts worth knowing before you reach for `width: 100%` anywhere:

- The options row (`.bb-base-radio-group__container`) is a plain wrapping
  flexbox and each option is `display: inline-flex` — content-sized by
  default. `flex: 1 1 0` on the option (as in the example above) is what makes
  tiles share the row evenly; there's no grid to opt into.
- The row's own box (`.bb-base-input-container__control`) is `display: grid`
  with a Vue-computed inline `width`, which defaults to `auto` — it does
  **not** stretch to fill a wider parent on its own. If you want the tile row
  to span full width, size the `BbRadioGroup` itself (a wrapping
  `class="w-full"`, or a container with a set width); don't set
  `direction="vertical"` just to pick up `width: 100%` — that also stacks the
  legend above the options, which a tile row usually doesn't want.

### Events and focus

`update:modelValue` (the `v-model` channel) carries the single selected value —
the only source of selection truth. Native `blur`, `change`, `click`, `focus`,
`input`, `keydown`, `mousedown`, `mouseup` re-emit with raw payloads, plus
`active` when focus enters the group (it drives the hint internally) and
`inactive` when focus leaves; use them for side effects, never to
compute selection. `autofocus` focuses the first option on mount.

### Works well with

- `BbRadio` — the escape hatch when options must be interleaved with other
  markup (`./BbRadio.md`).
- `BbCheckboxGroup` — the multi-select sibling with the same items API.
- `BbSelect` — swap to it when the option set grows past a scannable list.
- `BbButton` — gate a form submit's `disabled` on the bound value.

### Gotchas and anti-patterns

- Don't seed the model with an array — radio groups bind a single value; seed
  `null`.
- Don't expect the user to clear the selection; add an explicit "none" option if
  that's a valid answer.
- Don't reach for standalone `BbRadio` just to stack a few options in a box —
  that's this component (fieldset + roving focus + item mapping for free).
- A `disabled` field on an item object does nothing — it is inert data. Gate
  options with the `selectable` prop (a boolean, or a predicate
  `(item) => boolean` that disables the options it rejects — e.g.
  `:selectable="(plan) => plan.available"`), or disable the whole group with
  `disabled`; filter unavailable choices out of `items` when a dead row adds
  nothing.
- `readonly` still submits its value and stays focusable; use `disabled` only
  when the whole choice doesn't apply.
- Don't pre-map `items` into `{ label, value }` — pass raw rows and resolve with
  `item-text` / `item-value`.

### Accessibility

- Always provide a `legend` — it's the group's accessible name. Use `hide-legend`
  (not omission) when a visible heading already labels it.
- The component is a real `<fieldset>`; don't wrap it in another label or nest it
  inside a `BbRadio`.
- The options block itself is exposed as `role="radiogroup"`, named by the
  `legend` via `aria-labelledby` — so screen readers announce the widget as a
  radio group, not just a generic fieldset. This is automatic and needs no
  props; it is simply withheld if the `legend` is empty, since an unnamed
  radiogroup is worse than none.
- Arrow keys move between options natively (see Keyboard model); keep the set
  short enough to scan.
- `errors`, `warnings`, `description` and `hint` are all wired to the group through
  `aria-describedby`, in that order: the reason the field is invalid is spoken
  first when it regains focus, and a channel is referenced only while it
  actually has copy. Messages _also_ render in an `aria-live="polite"` region,
  so they are announced the moment they appear — announced on change, re-read
  on focus. Keep messages meaningful, not decorative.
- `readonly` exposes `aria-readonly` on the `radiogroup` (the `radio` role does
  not support it) and still submits; prefer it (with a nearby explanation) over
  a silent `disabled`.

## v-model

- `v-model` — type: `any`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
| `compact` | `boolean \| undefined` | `false` |  | Sets the component in a compact state. |
| `dependencies` | `unknown[] \| undefined` |  |  | Defines an array of dependencies that will trigger actions in the component upon change. |
| `depsDebounceTime` | `number \| undefined` |  |  | Timeout used to debounce response to changes to dependencies. |
| `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
| `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
| `enforceCoherence` | `boolean \| undefined` | `false` |  | If coherence is enforced the input cannot have a modelValue that is incoherent with its current items. e.g. You cannot set v-model to a user that is not present in the items passed. modelValue will be reset upon incoherence. |
| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides each option's label text (the text rendered next to every input) while keeping it accessible to screen readers. Does not affect the fieldset legend — use `hideLegend` for that. |
| `hideLegend` | `boolean \| undefined` | `false` |  | Visually hides the legend of the fieldset while maintaining accessibility. |
| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `inputDirection` | `"horizontal" \| "vertical" \| undefined` |  |  | Defines the direction of the inputs in the fieldset. |
| `inputPosition` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can. |
| `items` | `T[] \| ((prefill: boolean, modelValue?: any) => T[] \| Promise<T[]>)` |  | yes | Used to retrieve items; can be an array or a function. |
| `itemText` | `ItemAccessor<T, string> \| undefined` |  |  | Defines a path that returns a property of the object to use as text or a function that returns a string. |
| `itemValue` | `ItemAccessor<T> \| undefined` |  |  | Defines a path that returns a property of the object to use as value or a function that returns any value. |
| `legend` | `string` |  | yes | Text content of the legend. |
| `legendMode` | `"outside" \| "inside" \| undefined` |  |  | Legend rendering mode. `'outside'` renders the legend above the fieldset in the normal flow; `'inside'` overlays the legend inside the fieldset border. Floating mode is not supported for radio groups. |
| `legendPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
| `loadingText` | `string \| undefined` |  |  | String displayed while items are being loaded. |
| `modelValue` | `any` |  | yes | Used by v-model. Can be any serializable type. |
| `modelValueDebounceTime` | `number \| undefined` |  |  | Timeout used to debounce response to changes to modelValue. |
| `name` | `string \| undefined` |  |  | Defines the name of the option inputs. Optional: the options live inside a single component instance, so an omitted name falls back to a generated one that groups them correctly on its own — unique per group, so two groups never clear each … |
| `noDataText` | `string \| undefined` |  |  | String displayed when there are no items to display. |
| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
| `selectable` | `boolean \| ((item: T) => boolean) \| undefined` | `true` |  | Defines whether options are selectable. Can be a global boolean that affects all options or a function that accepts an item and returns a boolean that only affects that item. Non-selectable options are rendered disabled. |
| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |

## Events

- `active` — `(e: "active"): void` — Emitted when the group becomes active (focus/click enters it).
- `blur` — `(e: "blur", event: FocusEvent): void` — Emitted when one of the generated radio inputs loses focus. Forwards the original DOM `FocusEvent`.
- `change` — `(e: "change", event: Event): void` — Emitted when a radio option is selected. Forwards the original DOM `Event` from the radio input.
- `click` — `(e: "click", event: MouseEvent): void` — Emitted when one of the generated radio inputs is clicked. Forwards the original DOM `MouseEvent`.
- `focus` — `(e: "focus", event: FocusEvent): void` — Emitted when one of the generated radio inputs receives focus. Forwards the original DOM `FocusEvent`.
- `inactive` — `(e: "inactive"): void` — Emitted when focus/click moves outside the group after it was active. Useful for validation-on-blur flows at group level.
- `input` — `(e: "input", event: Event): void` — Emitted on native input events from generated radio inputs. Forwards the original DOM `Event`.
- `keydown` — `(e: "keydown", event: KeyboardEvent): void` — Emitted for keyboard interaction on generated radio inputs. Forwards the original DOM `KeyboardEvent`.
- `mousedown` — `(e: "mousedown", event: MouseEvent): void` — Emitted when a pointing device button is pressed over a radio input. Forwards the original DOM `MouseEvent`.
- `mouseup` — `(e: "mouseup", event: MouseEvent): void` — Emitted when a pointing device button is released over a radio input. Forwards the original DOM `MouseEvent`.
- `update:modelValue` — `(e: "update:modelValue", value: any): void` — Emitted with the newly selected value when the selection changes.

## Slots

- `append` — scope: `object` — Content rendered after the last option, inside the options container.
- `icon` — scope: `BaseRadioGroupIconSlotProps<T>` — Replaces the default radio dot icon for each option. Receives all `BaseRadio` slot attributes plus the source item and its display text.
- `label` — scope: `BaseRadioGroupLabelSlotProps<T>` — Replaces the default label text for each option.
- `legend` — scope: `BbRadioGroupLegendSlotProps` — Replaces the default fieldset legend text for the group.
- `loading` — scope: `object` — Content shown while options are loading (replaces the default loading text).
- `no-data` — scope: `object` — Content shown when no options are available (replaces the default "no data" text).
- `prepend` — scope: `object` — Content rendered before the first option, inside the options container.

## Validated variant

Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).

| Prop | Type | Description |
| --- | --- | --- |
| `rules` | `RuleExpression<any>` | vee-validate rules for this field. |
| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |

## See Also

- [BbRadio](./BbRadio.md) — Represents a single choice in exclusive options.
- [BbCheckboxGroup](./BbCheckboxGroup.md) — Manages multiple checkbox options as a group.
- [BbSwitchGroup](./BbSwitchGroup.md) — Manages grouped switch options with shared behavior.
- [BbSelect](./BbSelect.md) — Selects one or many options from structured data.

---

<!-- dist/ai/BbRating.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbRating.md -->

# BbRating

## Agent Contract

- Safety level: **Consumer API**
- Group: **Selection**
- Description: Collects scalar ratings through interactive icons.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbRating.md](./source/BbRating.md)

## Usage & Guidelines

### When to use

Use `BbRating` for a small whole-number scale where each step is a distinct
judgement: 1–5 stars, a 1–10 recommendation, a satisfaction score. It works two
ways from the same component:

- **Interactive** — the user picks a value (`v-model`).
- **Read-only** — you show an existing score (`readonly` + `model-value`).

For a continuous value from an interval reach for `BbSlider`; for a single
yes/no use `BbSwitch` or `BbCheckbox`. Ratings are for "how many out of N", and
the value is always a **whole number** — see the constraint below.

### Collect a rating

Bind `v-model`; set `stars` for the scale (default 5). The underlying control is
a native radio group: `legend` labels the set, and `name` is optional — omit it
and the component generates a unique group name. Pass `name` only when a native
form post needs the value under a known key.

**Interactive rating**

```vue
<BbRating
	v-model="state.stars"
	legend="Rate your experience"
	name="experience"
/>
```

Besides `update:modelValue` the component re-emits the native interaction events
(`change`, `click`, `input`, `focus`, `blur`, `keydown`, `mousedown`,
`mouseup`) — listen to those for side effects, never to derive the value.

### Clearing a rating

By default a radio group cannot be un-picked. Set `clearable` to let the user
reset to unrated (`null`): clicking the **currently selected** star again clears
it, and so does pressing **Delete** or **Backspace** while it is focused. The
gesture isn't obvious, so pair it with a hint.

**Clearable rating**

```vue
<BbRating
	v-model="state.score"
	legend="Rate your order"
	name="order"
	clearable
	hint="Click the selected star again to clear."
	persistent-hint
/>
```

When cleared, `v-model` becomes `null` (not `0`) — model your ref as
`number | null` and treat `null` as "not rated yet".

### Read-only score display

With `readonly` the stars become a compact score indicator that can still be
focused but not changed. Use the `append` slot to add the numeric value and
sample size next to the stars.

**Average score**

```vue
<BbRating :model-value="4" readonly legend="Average rating" name="avg">
	<template #append>
		<span class="text-sm text-[color:var(--bb-text-muted)]">4.0 · 128 reviews</span>
	</template>
</BbRating>
```

### Whole numbers only — no half stars

`BbRating` renders one radio per whole star and fills every star **at or below**
the value, so it has no concept of a half or fractional star. A decimal average
like `4.5` fills four stars, not four-and-a-half. When you display an average,
round for the glyphs and print the precise figure as text (as above) rather than
expecting a half-filled star. For fractional _input_, use `BbSlider`.

### Scale size with `stars`

`stars` sets both how many glyphs render **and** the maximum value. Use it for
non-5 scales — a 3-point mood, a 10-point NPS-style score.

**Ten-point scale**

```vue
<BbRating
	v-model="state.nps"
	legend="How likely are you to recommend us?"
	name="nps"
	:stars="10"
	size="sm"
/>
```

### Glyph sizes

`size` takes the shared scale (`xs`–`2xl`), or any non-percentage CSS length.
Prefer the default for interactive ratings; use `sm`/`xs` for dense inline
score displays next to compact chrome.

**Size scale**

```vue
<div class="flex flex-wrap items-center gap-3">
	<BbRating :model-value="4" readonly hide-legend legend="Small" name="rs" size="sm" />
	<BbRating :model-value="4" readonly hide-legend legend="Medium" name="rm" size="md" />
	<BbRating :model-value="4" readonly hide-legend legend="Large" name="rl" size="lg" />
</div>
```

### Custom glyph

The `icon` slot replaces the star and receives `checked` (is this glyph filled?)
plus the rendered `size`. Swap in any icon and colour the filled vs empty state
with utility classes — `BbIcon` inherits `currentColor`.

Note the slot's `size` is a **CSS length string** (e.g. `"28"`), already resolved
from the `size` prop through the shared scale — pass it straight to `BbIcon`'s
`size`, don't do arithmetic on it as if it were a number.

**Hearts instead of stars**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">Pulse · App Store</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]"
				>How much do you love it?</span
			>
		</div>
		<BbRating
			v-model="love"
			hide-legend
			legend="How much do you love it?"
			name="love"
		>
			<template #icon="{ checked, size }">
				<BbIcon
					:class="
						checked ? 'text-rose-500' : 'text-[color:var(--bb-text-faint)]'
					"
					icon="lucide:heart"
					:size="size"
				/>
			</template>
		</BbRating>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbIcon, BbRating } from 'bitboss-ui';

// The icon slot replaces the star glyph; `size` arrives as a resolved CSS
// length string, so pass it straight through to BbIcon.
const love = ref<number | null>(4);
</script>
```

### Keyboard

The stars are a standard radio group, so keyboard behaviour is the native one:
**Arrow** keys move the selection between adjacent stars and **Tab** moves in and
out of the group. When `clearable` is set, **Delete** / **Backspace** on the
selected star clears it to `null`. A `readonly` rating swallows those keys so the
displayed score can't be nudged while remaining focusable.

### A rating inside a form

Because the control is a real radio group inside a `<fieldset>`, `required` and
the error props integrate with form validation like any other field. `errors`
(string or array) renders messages under the stars; `has-errors` toggles error
styling alone.

The classic shape is a post-purchase review prompt: the rating is the required
field, a follow-up question appears only for low scores, and submitting without
a rating surfaces `errors` on the fieldset. Remember to reset `errors` as soon
as the user picks a value.

**Order review with follow-up**

```vue
<template>
	<form
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
		novalidate
		@submit.prevent
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">How was your order?</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				Order #10482 · delivered Jul 8, 2026
			</span>
		</div>
		<BbRating
			v-model="score"
			clearable
			compact
			:errors="errors"
			legend="Rate your order"
			name="order-review"
			required
			@update:model-value="onScoreChange"
		/>
		<p class="text-sm text-[color:var(--bb-text-muted)]" data-testid="score">
			{{ score === null ? 'Not rated yet' : `${score}/5 — ${labels[score]}` }}
		</p>
		<BbTextarea
			v-if="score !== null && score <= 3"
			v-model="feedback"
			compact
			data-testid="followup"
			label="What went wrong?"
			name="order-feedback"
			placeholder="Late delivery, damaged packaging…"
			:rows="3"
		/>
		<div class="flex items-center gap-2">
			<BbButton variant="primary" @click="submit">Submit review</BbButton>
			<span
				v-if="sent"
				class="text-xs text-[color:var(--bb-text-muted)]"
				data-testid="sent"
			>
				Thanks — review received.
			</span>
		</div>
	</form>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbRating, BbTextarea } from 'bitboss-ui';

const score = ref<number | null>(null);
const feedback = ref('');
const errors = ref<string | undefined>();
const sent = ref(false);

const labels: Record<number, string> = {
	1: 'Poor',
	2: 'Fair',
	3: 'Good',
	4: 'Great',
	5: 'Excellent',
};

/** Clear validation as soon as a star is picked. */
const onScoreChange = () => {
	errors.value = undefined;
	sent.value = false;
};

/** Stand-in mutation; the button spins until this resolves. */
const submit = async () => {
	if (score.value === null) {
		errors.value = 'Select a rating before submitting.';
		return;
	}
	await new Promise((resolve) => setTimeout(resolve, 600));
	sent.value = true;
};
</script>
```

### Works well with

- `BbSlider` — when you actually need a fractional or continuous value.
- `BbIcon` — inside the `icon` slot for a custom glyph.
- `BbTextarea` — the follow-up question in a review form.
- `useToast` — confirm a submitted rating in review flows.

No plugin options change `BbRating` behaviour except the star/clear accessible
labels, which come from the library's i18n strings (`rating.singleStar`,
`rating.multipleStars`, `rating.clearHint`) and localize automatically. It
renders SSR-safe markup in Nuxt and Inertia apps.

### Gotchas and anti-patterns

- Don't expect half stars — the value is a whole number; round averages for the
  glyphs and show the decimal as text.
- Don't treat a cleared rating as `0`; `clearable` emits `null`. Type the model
  `number | null`.
- Don't do math on the `icon` slot's `size` — it's a CSS length string, pass it
  through to `BbIcon`.
- Don't hide the per-star accessible label to "clean up" the DOM — it is the only
  text a screen-reader user gets.
- Pass `name` when a native form post needs a known key; otherwise the generated
  group name is enough for multiple ratings on one page.

### Accessibility

- `legend` is required — it labels the set via the `<fieldset>`. `name` is
  optional (a unique group name is generated when omitted).
- Each star exposes an accessible label ("n of m stars"); keep it.
- `errors`, `warnings`, `description` and `hint` are all wired to the input through
  `aria-describedby`, in that order: the reason the field is invalid is spoken
  first when it regains focus, and a channel is referenced only while it
  actually has copy. Messages _also_ render in an `aria-live="polite"` region,
  so they are announced the moment they appear — announced on change, re-read
  on focus. The clear affordance appends its own hint when `clearable`.
- The `icon` slot content is decorative — keep the meaningful label on the
  fieldset, not the glyph.
- Prefer `readonly` (focusable) over `disabled` for scores the user may inspect.

## v-model

- `v-model` — type: `number \| null`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
| `clearable` | `boolean \| undefined` | `false` |  | Allows clearing the selected rating by clicking the current value. |
| `compact` | `boolean \| undefined` | `false` |  | Sets the component in a compact state. |
| `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
| `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
| `hideLegend` | `boolean \| undefined` | `false` |  | Visually hides the legend of the fieldset while maintaining accessibility. |
| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `inputPosition` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can. |
| `legend` | `string` |  | yes | Text content of the legend. |
| `legendMode` | `"outside" \| "inside" \| undefined` |  |  | Legend rendering mode. `'outside'` renders the legend above the fieldset in the normal flow; `'inside'` overlays the legend inside the fieldset border. Floating mode is not supported for rating groups. |
| `legendPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the legend. |
| `modelValue` | `number \| null` |  | yes | Used by v-model. |
| `name` | `string \| undefined` |  |  | Defines the name of the star radio inputs. Optional: the stars live inside a single component instance, so an omitted name falls back to a generated one that groups them correctly on its own. Pass a name only when the value has to be submit… |
| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
| `size` | `number \| ({ size?: any; } & string) \| keyof Sizes \| undefined` | `'md'` |  | Defines the component size. Accepted values: - A key from the provided size map (`keyof T`), e.g. `'sm' \| 'md' \| 'lg'` - A custom CSS size string (e.g. `'20px'`, `'1.5rem'`, `'2em'`) - A number, typically interpreted as pixels by size par… |
| `stars` | `number \| undefined` |  |  | Maximum number of stars to render and maximum value of the component. |
| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |

## Events

- `active` — `(event: "active"): void`
- `blur` — `(event: "blur", event: FocusEvent): void`
- `change` — `(event: "change", event: Event): void`
- `click` — `(event: "click", event: MouseEvent): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `inactive` — `(event: "inactive"): void`
- `input` — `(event: "input", event: Event): void`
- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
- `update:modelValue` — `(event: "update:modelValue", value: number \| null): void`

## Slots

- `append` — scope: `object` — Content rendered after the row of rating stars.
- `icon` — scope: `BaseRatingIconSlotProps` — Replaces the default star SVG for each rating option.
- `legend` — scope: `BbRatingLegendSlotProps` — Replaces the default fieldset legend text rendered above the rating stars.
- `prepend` — scope: `object` — Content rendered before the row of rating stars.

## Validated variant

Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).

| Prop | Type | Description |
| --- | --- | --- |
| `rules` | `RuleExpression<number \| null>` | vee-validate rules for this field. |
| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |

## See Also

- [BbSlider](./BbSlider.md) — Selects numeric values across a bounded range.

---

<!-- dist/ai/BbSelect.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbSelect.md -->

# BbSelect

## Agent Contract

- Safety level: **Consumer API**
- Group: **Selection**
- Description: Selects one or many options from structured data.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbSelect.md](./source/BbSelect.md)

## Usage & Guidelines

### When to use

Reach for `BbSelect` when the user picks from a list that is **large, dynamic,
or searchable**, and you want a labelled form control with hint, error and
loading states baked in. It is the default choice for country/city pickers,
assignee fields, tag inputs and any async-backed lookup.

Prefer a sibling when the shape is simpler:

- Small, static, exclusive choice (≤6 options, always visible) → `BbRadioGroup`.
- Small, static, multi-choice → `BbCheckboxGroup` / `BbSwitchGroup`.
- You need a **custom trigger** (a status pill, an avatar stack, a badge) rather
  than an inline input → `BbSelectPopover`, the popover-anchored sibling that
  shares this component's search and option engine.
- Values the user _invents_ (open vocabulary) → `BbTag`; if values come from a
  known set, `BbSelect` in multiple mode is the right tool.

`label` is required — it is the accessible name. Hide it visually with
`hide-label` when the surrounding UI already labels the field.

### Map options with `item-text` and `item-value`

Pass your domain objects to `items` **as they are** and tell the component which
field is the display text and which is the stored value with `item-text` /
`item-value` (dot-paths or extractor functions). Never pre-map `items` into
`{ label, value }` objects — matching is hash-based, so component-native
extraction stays robust. The `v-model` holds the resolved _value_, not the whole
object.

**Single select mapped from domain objects**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
		<div class="flex items-baseline justify-between gap-2">
			<h3 class="text-sm font-medium">ISSUE-1842</h3>
			<span class="text-xs text-[color:var(--bb-text-muted)]">In progress</span>
		</div>
		<p class="text-xs text-[color:var(--bb-text-muted)]">
			Wire invoice PDF export for the Milan office.
		</p>
		<BbSelect
			v-model="assignee"
			clearable
			compact
			item-text="fullName"
			item-value="id"
			:items="teammates"
			label="Assignee"
			placeholder="Choose a teammate"
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSelect } from 'bitboss-ui';

type Teammate = {
	id: string;
	fullName: string;
	role: string;
};

// Raw domain objects — passed straight to `items`, never pre-mapped.
const teammates: Teammate[] = [
	{ id: 'ada', fullName: 'Ada Lovelace', role: 'Engineering' },
	{ id: 'grace', fullName: 'Grace Hopper', role: 'Engineering' },
	{ id: 'maggie', fullName: 'Margaret Hamilton', role: 'Flight Systems' },
	{ id: 'katherine', fullName: 'Katherine Johnson', role: 'Mathematics' },
];

// The model holds the resolved value (id), not the whole object.
const assignee = ref<string | null>(null);
</script>
```

Value-identity rules (shared with every items-driven component — see the
Options and Items playbook):

- For primitive `items` (`string[]` / `number[]`) omit both mapping props — the
  value is the primitive itself. For object items always set both: the defaults
  are the whole item as value and `JSON.stringify(item)` as text.
- Matching compares **value hashes** (deep structural equality, not reference
  identity), so object values survive refetches — but prefer primitive ids:
  stable, unique, cheap to submit.
- Options resolving to a **duplicate value are silently dropped** (first wins).
- Per-option gating goes through `selectable`: a boolean (`false` disables every
  option) or a predicate `(item) => boolean` — rejected options render disabled
  and keyboard navigation skips them (e.g. `:selectable="(u) => u.active"`). A
  `disabled` field on the item object itself is inert domain data — feed it to
  the predicate. Alternatives: filter unavailable choices out of `items`, cap
  with `max`, or disable the whole control with `disabled`.

### The field around the control

`BbSelect` is a complete form field. Everything here is declarative — no custom
markup needed:

- **Label**: `label` (required), `hide-label`, `label-position`
  (`left`/`center`/`right`), and `label-mode` — `outside` (the default via
  global config `defaultInputLabelMode`), `floating`, or `inside`. `reverse`
  swaps the order of label and control.
- **Guidance**: `description` renders always-visible helper text linked via
  `aria-describedby`; `hint` shows contextual guidance while the field is
  active (add `persistent-hint` to keep it visible).
- **Validation**: `has-errors` switches error styling; `errors` (string or
  array) renders the messages, associated with the field for assistive tech.
  `warnings` (string or array) is the amber counterpart of `errors` — the same
  messages rendered below the field in their own `aria-live="polite"` region —
  and referenced from `aria-describedby` while displayed — in
  amber (`--bb-text-warn`), with a warning icon in the append stack, for a
  valid-but-noteworthy selection; a non-empty `warnings` implies the warning
  state, so `has-warning` just forces that chrome without a message. Unlike
  `errors` it sets no `aria-invalid` — a soft "needs a second look" state. When
  both are set the error state wins and the warning messages are suppressed, so
  the field never shows amber while it has an error.
- **Form participation**: `name` renders hidden inputs carrying the selection
  (one per value; non-string values are JSON-stringified), so the select posts
  in a plain HTML form. **`required` does NOT give you native constraint
  validation**: the HTML spec bars `required` on `input[type=hidden]` from
  constraint validation, so the browser will never block submission on an empty
  select (`BbBaseSelect.vue:432` says so in its own comment). `required` is kept
  for form introspection and for the asterisk. Gate submission with `errors` /
  `has-errors`, or with the validated entrypoint. `autocomplete` / `autofocus`
  forward to the control.
- **Affixes**: `prepend:icon` / `append:icon` place icons in the control —
  `append:icon` replaces the default chevron (there is no `#chevron` slot).
- **Value display**: `placeholder` shows when a _single-mode_ select is empty.
  In multiple mode the placeholder is never rendered — use `description` /
  `hint` for guidance instead.

**A complete form field**

```vue
<div class="max-w-sm">
	<BbSelect
		v-model="state.plan"
		label="Plan"
		description="You can change plan at any time."
		hint="Yearly billing saves 20%"
		placeholder="Choose a plan"
		prepend:icon="lucide:credit-card"
		required
		clearable
		:items="['Starter', 'Growth', 'Enterprise']"
	/>
</div>
```

**Error state**

```vue
<div class="max-w-sm">
	<BbSelect
		v-model="state.country"
		label="Country"
		placeholder="Required for invoicing"
		has-errors
		errors="Pick a country to continue"
		:items="['Italy', 'Germany', 'Portugal']"
	/>
</div>
```

### Multiple selection and how it displays

Add `multiple` for multi-select; the model becomes an array and **must be seeded
as one** (`ref<string[]>([])`) — a non-array model throws at setup. Cap the
count with `max`: at the cap, unselected options auto-disable while selected
options never do, so the user can always deselect.

Selected values render as removable chips inside the control. When they no
longer fit the row, it collapses into a count summary ("N items selected", from
the active locale). You can steer that display:

- `max-selected-labels` collapses by **count** instead of by overflow width.
- `selected-labels-fn` customises the summary text (`(count) => string`).
- `comma` renders a plain comma-separated string instead of chips — values can
  then only be deselected from the panel.
- Under `disabled` / `readonly`, chips become non-removable badges.

`clearable` shows a clear affix once there is a value; clearing resets the
model to `[]` (or `null` in single mode).

**Multi-select with a maximum and collapsed labels**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
		<div>
			<h3 class="text-sm font-medium">Warehouse coverage</h3>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Cap at 3 hubs for the pilot route.
			</p>
		</div>
		<BbSelect
			v-model="cities"
			clearable
			compact
			hint="Pick up to 3 cities"
			item-text="label"
			item-value="value"
			:items="options"
			label="Cities"
			:max="3"
			:max-selected-labels="2"
			multiple
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSelect } from 'bitboss-ui';

const options = [
	{ label: 'Amsterdam', value: 'ams' },
	{ label: 'Berlin', value: 'ber' },
	{ label: 'Copenhagen', value: 'cph' },
	{ label: 'Lisbon', value: 'lis' },
	{ label: 'Milan', value: 'mil' },
];

// `multiple` requires the model to be an array from the start.
const cities = ref<string[]>(['ber', 'mil']);
</script>
```

**Comma display for dense forms**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
		<div>
			<h3 class="text-sm font-medium">Email digests</h3>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Who gets the Monday summary?
			</p>
		</div>
		<BbSelect
			v-model="recipients"
			comma
			compact
			item-text="name"
			item-value="id"
			:items="team"
			label="Weekly digest recipients"
			multiple
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSelect } from 'bitboss-ui';

const team = [
	{ id: 'ada', name: 'Ada Lovelace' },
	{ id: 'grace', name: 'Grace Hopper' },
	{ id: 'alan', name: 'Alan Turing' },
	{ id: 'maggie', name: 'Margaret Hamilton' },
];

// `comma` renders the selection as plain comma-separated text: values can only
// be deselected from the panel, not removed from the control itself.
const recipients = ref<string[]>(['ada', 'grace']);
</script>
```

### Panel actions: header, footer and select-all

The `#header` and `#footer` slots pin content above the search field and below
the options list — the same markup renders in the desktop popover and the
mobile adaptive sheet. Both receive `{ close, clear, focus, query,
selectedOptions }`: `close()` closes the panel, `clear()` empties the
selection, `focus()` refocuses the search input, and `selectedOptions` are the
resolved selected options (`.text` / `.value` / raw `.item`).

Select-all is not built in — it is a one-liner in a panel slot, because the
v-model is yours:

**Select all + done in the footer**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
		<div>
			<h3 class="text-sm font-medium">Incident alerts</h3>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Where should paging go when severity is high?
			</p>
		</div>
		<BbSelect
			v-model="channels"
			compact
			item-text="label"
			item-value="value"
			:items="options"
			label="Notify via"
			:max-selected-labels="2"
			multiple
			:selected-labels-fn="(count) => `${count} channels`"
		>
			<template #footer="{ close, clear, selectedOptions }">
				<div class="flex w-full items-center gap-1.5">
					<BbButton
						size="xs"
						variant="ghost"
						@click="channels = options.map((option) => option.value)"
					>
						Select all
					</BbButton>
					<BbButton size="xs" variant="ghost" @click="clear">Clear</BbButton>
					<BbButton class="ml-auto" size="xs" variant="primary" @click="close">
						Done ({{ selectedOptions.length }})
					</BbButton>
				</div>
			</template>
		</BbSelect>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSelect, BbButton } from 'bitboss-ui';

const options = [
	{ label: 'Email', value: 'email' },
	{ label: 'SMS', value: 'sms' },
	{ label: 'Push notification', value: 'push' },
	{ label: 'Slack', value: 'slack' },
];

const channels = ref<string[]>(['email']);
</script>
```

The `#header` slot is the mirror image: pin context above the search field — a
live summary of the selection, computed from your own model since the v-model
is yours:

**A pinned header with a live summary**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
		<div>
			<h3 class="text-sm font-medium">Lisbon half-day</h3>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Build a route under about four hours.
			</p>
		</div>
		<BbSelect
			v-model="stops"
			compact
			hint="A half-day tour fits roughly 4 hours"
			item-text="name"
			item-value="id"
			:items="catalog"
			label="Tour stops"
			:max-selected-labels="2"
			multiple
		>
			<template #header="{ clear }">
				<div
					class="flex w-full items-center justify-between gap-2 px-1 text-xs text-[color:var(--bb-text-muted)]"
				>
					<span>{{ summary }}</span>
					<BbButton
						:disabled="!stops.length"
						size="xs"
						variant="ghost"
						@click="clear"
					>
						Reset
					</BbButton>
				</div>
			</template>
		</BbSelect>
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbSelect, BbButton } from 'bitboss-ui';

type Stop = { id: string; name: string; durationMin: number };

const catalog: Stop[] = [
	{ id: 'belem', name: 'Belém Tower', durationMin: 45 },
	{ id: 'jeronimos', name: 'Jerónimos Monastery', durationMin: 60 },
	{ id: 'alfama', name: 'Alfama walking tour', durationMin: 90 },
	{ id: 'tram28', name: 'Tram 28 ride', durationMin: 40 },
	{ id: 'oceanario', name: 'Oceanário aquarium', durationMin: 120 },
	{ id: 'lxfactory', name: 'LX Factory market', durationMin: 60 },
];

const stops = ref<string[]>(['belem', 'alfama']);

// The panel slots also expose `selectedOptions`, but the v-model is ours —
// deriving the summary from it keeps the header logic on plain typed data.
const summary = computed(() => {
	if (!stops.value.length) return 'No stops yet';
	const total = stops.value.reduce(
		(sum, id) =>
			sum + (catalog.find((stop) => stop.id === id)?.durationMin ?? 0),
		0
	);
	const hours = Math.floor(total / 60);
	const minutes = total % 60;
	return `${stops.value.length} stops · ~${hours}h${minutes ? ` ${minutes}m` : ''}`;
});
</script>
```

### Search and filtering semantics

The panel carries a search field (role `searchbox`). How typing filters depends
on your setup:

- **Array `items`**: typing filters locally — a case-insensitive **substring**
  match against each option's display text.
- **`filter-by: ['path', ...]`**: the listed item paths are searched **instead
  of** the display text (no fallback union with the text). Every path must
  exist on every item, or matching throws. Use it to also match a city by its
  country, a member by email.
- **Provider `items`**: the provider re-runs with the query (next section) —
  and the local text filter **still applies on top of the response**. Results
  whose display text (or `filter-by` paths) don't contain the query substring
  are hidden, so fuzzy or synonym-based server matches can vanish. Keep server
  search substring-compatible, or point `filter-by` at a field the server
  guarantees to match.
- **Single-mode exception**: when the query equals the selected option's text
  (as right after picking), the list shows unfiltered.
- **`disable-writing`** removes the search field entirely (`true`, or
  `'mobile'` / `'desktop'` to remove it on one platform only) — this is also
  the supported way to disable filtering; there is no "falsy `filter-by`"
  escape hatch.

**Match on fields other than the display text**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
		<div>
			<h3 class="text-sm font-medium">Shipping destination</h3>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Search by city or country name.
			</p>
		</div>
		<BbSelect
			v-model="city"
			compact
			:filter-by="['label', 'country']"
			item-text="label"
			item-value="id"
			:items="cities"
			label="City"
			placeholder="Search city or country"
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSelect } from 'bitboss-ui';

type City = { label: string; country: string; id: string };

// `filter-by` searches these item paths instead of the display text, so a
// city matches by its country too — every listed path must exist on every item.
const cities: City[] = [
	{ label: 'Milan', country: 'Italy', id: 'mil' },
	{ label: 'Rome', country: 'Italy', id: 'rom' },
	{ label: 'Lisbon', country: 'Portugal', id: 'lis' },
	{ label: 'Porto', country: 'Portugal', id: 'por' },
];

const city = ref<string | null>(null);
</script>
```

### Fetch options with a provider

When options come from a backend, pass a **function** to `items` instead of an
array. It receives `(query, prefill, modelValue)` and returns `T[]` or a
`Promise<T[]>` — the full call matrix lives in the Fetch Items playbook. The
short version:

- `prefill === false` means exactly one thing: **the user typed**. Search then.
- Every component-initiated call (first load, dependency change, external model
  update) passes `prefill === true` and expects the current selection to stay
  resolvable in the response — return the selected items (by id) so chosen
  values are never orphaned.
- `modelValue` is your v-model as-is (array in multiple mode, the raw model
  value — possibly `null` — otherwise); the prop declares it `any`, so annotate
  it `any` or your own model type.

**Async, debounced member search**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
		<div>
			<h3 class="text-sm font-medium">Pull request reviewers</h3>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Search the directory; picks stay pinned.
			</p>
		</div>
		<BbSelect
			v-model="reviewers"
			clearable
			compact
			hint="Type a name to search"
			item-text="name"
			item-value="id"
			:items="searchMembers"
			label="Reviewers"
			loading-text="Searching…"
			multiple
			no-data-text="No members match your search"
			persistent-hint
			:query-debounce-time="300"
			stash
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSelect } from 'bitboss-ui';

type Member = {
	id: string;
	name: string;
};

// Stand-in for a real API. In a product this is `api.members.search(...)`.
const directory: Member[] = [
	{ id: 'ada', name: 'Ada Lovelace' },
	{ id: 'alan', name: 'Alan Turing' },
	{ id: 'grace', name: 'Grace Hopper' },
	{ id: 'katherine', name: 'Katherine Johnson' },
	{ id: 'ken', name: 'Ken Thompson' },
	{ id: 'maggie', name: 'Margaret Hamilton' },
];

const fetchFromApi = (predicate: (member: Member) => boolean) =>
	new Promise<Member[]>((resolve) => {
		setTimeout(() => resolve(directory.filter(predicate)), 250);
	});

// With `stash`, picked options stay resolvable across later searches, so the
// provider only ever answers the current query — no need to merge the selected
// members back into every response.
const searchMembers = (
	query: string,
	_prefill: boolean,
	_modelValue: string[]
): Promise<Member[]> => {
	const q = query.trim().toLowerCase();
	if (!q) return Promise.resolve([]);
	return fetchFromApi((member) => member.name.toLowerCase().includes(q));
};

const reviewers = ref<string[]>([]);
</script>
```

```ts
const searchMembers = async (
	query: string,
	prefill: boolean,
	modelValue: string[]
): Promise<Member[]> => {
	// Component-initiated: keep the current selection resolvable.
	if (prefill && modelValue.length) {
		return api.members.byIds(modelValue);
	}
	if (!query.trim()) return []; // project-defined idle behavior
	return api.members.search({ query });
};
```

Runtime guarantees you should not re-implement:

- **Debouncing**: typing is debounced by `query-debounce-time` (default 500ms);
  dependency reloads by `deps-debounce-time` (default 0); external model-change
  reloads by `model-value-debounce-time` (default 0).
- **Race protection**: out-of-order responses are discarded — only the latest
  request writes items.
- **Loading**: in-flight requests set the loading state automatically — the
  `loading` prop is only for _external_ pending state (e.g. the parent form).
- **Errors**: a rejected provider is logged (`console.error`) and the previous
  items are kept; surface failures yourself (e.g. `useToast`) if the user must
  know.
- **Panel states**: `loading-text` / `no-data-text` (locale defaults
  "Loading..." / "No data to display") or the `#loading` / `#no-data` slots —
  both receive `{ query }`, `#no-data` also a `focus()` callback.

Enable `stash` to accumulate picked options across searches: selected values
stay resolvable (chips keep their text, coherence keeps passing) even when
later responses don't include them — no need to merge them into every response.

### Laziness and prefill

`prefill` controls **when the first load happens**:

- `'interaction'` (default) — on the first open.
- `true` — immediately on mount, and during SSR (`onServerPrefetch`), so the
  panel is warm on hydration.
- `false` — **search-first**: nothing loads until the user types. Opening is not
  a search, so the panel opens empty and shows a _"search to begin"_ hint until
  the first query. Use it when the result set is too big or too costly to browse
  and the query is the only sensible entry point.

When the model already has a value, `BbSelect` upgrades to immediate prefill
regardless of the setting, so the selection can render its text right away — so
`false` never strands a seeded value. **Array `items` are never lazy either** —
there is no request to defer, so they resolve on mount whatever `prefill` says.

Search-first also needs a search field to exist, so `disable-writing` (which
hides it) falls back to loading on open — otherwise the user would face an empty
panel with no way to fill it.

That upgrade reads "has a value" as "is not empty", and `null` counts as
**empty** — which is the one case where you must ask for the load yourself (see
the next section).

Laziness also gates coherence: an untouched `prefill: 'interaction'` select — or
an un-searched `prefill: false` one — with a **provider** and an **empty** model
ignores `dependencies` and external model changes until its first load. Don't
"fix" the quiet period with eager watchers: there is nothing on screen to keep
coherent yet, and the first load reads the current dependencies anyway. The user's
first search counts as that load, so a search-first select tracks `dependencies`
from then on.

### An "All" / "Any" option (`null` as a real value)

Distinct from the [select-all footer button](#panel-actions-header-footer-and-select-all)
above: that fills a `multiple` array with every option. This is a **single**
select where one option means _"everything"_ — the "no filter" row at the top of
a location or status filter.

Model it as a real option whose value is `null`, returned by your provider (or
present in your array) like any other. It resolves and renders as the selection.

**The one requirement: with a provider, set `prefill: true`.** `null` is also the
value the library reads as _nothing selected_, so the automatic
model-has-a-value upgrade does **not** fire for it. Nothing loads, there is no
text to show, and the field falls back to the **placeholder** — greyed, and
indistinguishable from an empty select, while your model holds a real choice.
The library cannot tell that `null` means "All" in your app without loading the
options to look, so you have to say so:

**An 'All locations' filter (provider + prefill)**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
		<div>
			<h3 class="text-sm font-medium">Invoice filters</h3>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Office location, or every office.
			</p>
		</div>
		<BbSelect
			v-model="location"
			compact
			item-text="label"
			item-value="value"
			:items="loadLocations"
			label="Location"
			placeholder="Select location…"
			prefill
		/>
		<p class="text-xs text-[color:var(--bb-text-muted)]">
			Filtering by:
			<strong>{{ location === null ? 'All locations' : location }}</strong>
		</p>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSelect } from 'bitboss-ui';

type Location = { label: string; value: string | null };

const pool: Location[] = [
	{ label: 'Milan', value: 'milan' },
	{ label: 'Rome', value: 'rome' },
	{ label: 'Berlin', value: 'berlin' },
];

/**
 * "Everything" is modelled as a real option whose value is `null`, sitting at
 * the top of the list next to the concrete ones. Returned by the provider like
 * any other option — the component does not synthesise it.
 */
const ALL: Location = { label: 'All locations', value: null };

// `null` is the seeded value, and here it means "All locations" — not "empty".
const location = ref<string | null>(null);

const loadLocations = (
	query: string,
	prefill: boolean
): Promise<Location[]> => {
	const q = query.trim().toLowerCase();
	const matches =
		prefill || !q
			? pool
			: pool.filter((l) => l.label.toLowerCase().includes(q));
	// "All" always leads the list; it is not filtered out by a search.
	return new Promise((resolve) =>
		setTimeout(() => resolve([ALL, ...matches]), 200)
	);
};
</script>
```

With an **array** you need nothing at all — arrays are never lazy, so "All
locations" renders from the first paint:

**The same thing with array items — no prefill needed**

```vue
<BbSelect
	v-model="state.location"
	item-text="label"
	item-value="value"
	:items="[
		{ label: 'All locations', value: null },
		{ label: 'Milan', value: 'milan' },
		{ label: 'Rome', value: 'rome' },
	]"
	label="Location"
	placeholder="Select location…"
/>
```

Know what else you inherit by overloading `null`, because the component cannot
distinguish the two meanings:

- **`clear` selects "All".** The clear button emits `null`, which is now a
  choice, not an absence.
- **`enforce-coherence` never prunes it** — an empty selection is always
  coherent, so the "All" value is never questioned.
- **A prune of some _other_ stale value widens to "All"**, because enforcement
  emits `null` in single mode. A dead filter value becomes "show everything"
  rather than "show nothing".

If "everything" and "nothing" must stay distinct — a required field, or a filter
where widening is unsafe — use a **sentinel** instead (`value: 'all'`). Then
`null` keeps meaning empty, but the sentinel must appear in **every** provider
response or `enforce-coherence` will prune it, and it counts as a value, so it
triggers the eager-prefill upgrade on its own.

### Dependent fields and enforced coherence

When one select constrains another, list the upstream value in `dependencies`:
the component re-runs its `items` provider whenever a dependency changes
(value-hash compared, so array identity churn doesn't refetch), debounced by
`deps-debounce-time`. Add `enforce-coherence` so a now-invalid selection is
cleaned up automatically. Details in the Coherence playbook.

**Region drives the city options**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
		<div>
			<h3 class="text-sm font-medium">Shipping address</h3>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				City options follow the chosen region.
			</p>
		</div>
		<BbSelect
			v-model="region"
			compact
			item-text="label"
			item-value="value"
			:items="regions"
			label="Region"
			placeholder="Pick a region"
		/>
		<BbSelect
			v-model="city"
			compact
			:dependencies="[region]"
			:deps-debounce-time="150"
			enforce-coherence
			item-text="label"
			item-value="value"
			:items="loadCities"
			label="City"
			:placeholder="region ? 'Pick a city' : 'Select a region first'"
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSelect } from 'bitboss-ui';

type Region = { label: string; value: string };
type City = { label: string; value: string; region: string };

const regions: Region[] = [
	{ label: 'Italy', value: 'it' },
	{ label: 'Germany', value: 'de' },
	{ label: 'Portugal', value: 'pt' },
];

const cityPool: City[] = [
	{ label: 'Rome', value: 'rome', region: 'it' },
	{ label: 'Milan', value: 'milan', region: 'it' },
	{ label: 'Berlin', value: 'berlin', region: 'de' },
	{ label: 'Munich', value: 'munich', region: 'de' },
	{ label: 'Lisbon', value: 'lisbon', region: 'pt' },
	{ label: 'Porto', value: 'porto', region: 'pt' },
];

// Single-mode enforcement resolves to `null` — seed the models accordingly.
const region = ref<string | null>(null);
const city = ref<string | null>(null);

// The provider reads the selected region; the component re-runs it whenever
// `region` changes because it is listed in `dependencies`. Component-initiated
// calls (`prefill === true`) return the region's whole pool so a still-valid
// city stays resolvable; `enforce-coherence` clears one that no longer fits.
const loadCities = (query: string, prefill: boolean): Promise<City[]> => {
	const pool = cityPool.filter((c) => c.region === region.value);
	const q = query.trim().toLowerCase();
	const matches =
		prefill || !q
			? pool
			: pool.filter((c) => c.label.toLowerCase().includes(q));
	return new Promise((resolve) => setTimeout(() => resolve(matches), 200));
};
</script>
```

What enforcement emits when a reload leaves the model incoherent:

- multiple → `update:modelValue` with the **filtered array** (still-valid
  entries survive);
- single → `update:modelValue` with **`null`** — seed single models as
  `ref<T | null>(null)` and treat `null` as "nothing valid" in submit logic;
- an empty selection is always coherent, so nothing fires.

In multiple mode the pruning shows up as a filtered chip row. Here switching
the project keeps reviewers who belong to the new team and drops the rest —
no watcher, no manual reset:

**Project change prunes reviewers**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
		<div>
			<h3 class="text-sm font-medium">Review request</h3>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Reviewers must belong to the selected project.
			</p>
		</div>
		<BbSelect
			v-model="project"
			compact
			item-text="name"
			item-value="id"
			:items="projects"
			label="Project"
		/>
		<BbSelect
			v-model="reviewers"
			compact
			:dependencies="[project]"
			:deps-debounce-time="150"
			enforce-coherence
			hint="Only members of the selected project can review"
			item-text="name"
			item-value="id"
			:items="loadReviewers"
			label="Reviewers"
			multiple
			name="reviewers"
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSelect } from 'bitboss-ui';

type Project = { id: string; name: string };
type Member = { id: string; name: string; projects: string[] };

const projects: Project[] = [
	{ id: 'web', name: 'Web app' },
	{ id: 'mobile', name: 'Mobile app' },
];

const members: Member[] = [
	{ id: 'ada', name: 'Ada Lovelace', projects: ['web', 'mobile'] },
	{ id: 'grace', name: 'Grace Hopper', projects: ['web'] },
	{ id: 'alan', name: 'Alan Turing', projects: ['mobile'] },
	{ id: 'maggie', name: 'Margaret Hamilton', projects: ['web', 'mobile'] },
];

const project = ref<string>('web');
// A seeded selection upgrades the select to immediate prefill, so the
// dependency watcher is armed from the first render.
const reviewers = ref<string[]>(['ada', 'grace']);

// Query-aware provider: `prefill === false` only when the user typed. On
// component-initiated calls (mount, project change) return the project's full
// member pool, so a still-valid selection stays resolvable — switching to
// "Mobile app" keeps Ada and prunes Grace.
const loadReviewers = (query: string, prefill: boolean): Promise<Member[]> => {
	const pool = members.filter((member) =>
		member.projects.includes(project.value)
	);
	const q = query.trim().toLowerCase();
	const matches =
		prefill || !q
			? pool
			: pool.filter((member) => member.name.toLowerCase().includes(q));
	return new Promise((resolve) => setTimeout(() => resolve(matches), 200));
};
</script>
```

Because enforcement checks the merged result (fetched + stashed), a provider
that returns `[]` on a `prefill: true` call **will wipe a valid selection** —
always resolve the current selection on component-initiated calls (or enable
`stash`).

### Create options on the fly (`option:add`)

Pressing Enter in the search field with **no option highlighted** emits
`option:add` with the trimmed query (it can be `''` — guard). The component
does not create anything itself: append the new item to `items` and select it.
This is the idiomatic pattern for closed-but-growable vocabularies.

**Create a label by pressing Enter**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
		<div>
			<h3 class="text-sm font-medium">Issue labels</h3>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Add from the list, or invent one with Enter.
			</p>
		</div>
		<BbSelect
			v-model="labels"
			clearable
			compact
			item-text="name"
			item-value="id"
			:items="available"
			label="Labels"
			multiple
			no-data-text="No matching label — press Enter to create it"
			@option:add="createLabel"
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSelect } from 'bitboss-ui';

type Label = { id: string; name: string };

const available = ref<Label[]>([
	{ id: 'bug', name: 'Bug' },
	{ id: 'docs', name: 'Documentation' },
	{ id: 'design', name: 'Design' },
]);

const labels = ref<string[]>(['bug']);

// `option:add` fires with the trimmed query when the user presses Enter and no
// option is highlighted. It can fire with '' (Enter on an empty query) — guard.
const createLabel = (text: string) => {
	const name = text.trim();
	if (!name) return;
	const id = name.toLowerCase().replace(/\s+/g, '-');
	if (!available.value.some((label) => label.id === id)) {
		// Mutating `items` re-runs the options pipeline, so the new label is
		// immediately matchable — no manual refresh needed.
		available.value = [...available.value, { id, name }];
	}
	if (!labels.value.includes(id)) {
		labels.value = [...labels.value, id];
	}
};
</script>
```

### Group related options

Set `group-by` to a field path (or a function) to bucket options under headers.
The `#group` slot styles the header and receives
`{ text, item, index, length, disabled }` — `length` is the number of options
in the group, `index` the list index of its first option.

A grouped list virtualizes **whole groups, not rows**: a group mounts only
when it scrolls into range, but all of its rows mount together. Many
small-to-medium groups window just as well as a flat list; one very large
group (say thousands of options under a single header) mounts in full and
defeats the virtualization. For sources that big, keep the list flat (flat
lists window per row) or pre-chunk the data into smaller groups.

**Options grouped by department**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
		<div>
			<h3 class="text-sm font-medium">Invite teammate</h3>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Roles grouped by department.
			</p>
		</div>
		<BbSelect
			v-model="role"
			clearable
			compact
			group-by="department"
			item-text="label"
			item-value="value"
			:items="roles"
			label="Role"
			placeholder="Pick a role"
		>
			<template #group="{ text, length }">
				<div
					class="flex items-center justify-between px-2 text-xs font-semibold text-[color:var(--bb-text-muted)]"
				>
					<span>{{ text }}</span>
					<span>{{ length }}</span>
				</div>
			</template>
		</BbSelect>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSelect } from 'bitboss-ui';

type Role = { label: string; value: string; department: string };

// `group-by` buckets options under headers by this field path; the `#group`
// slot styles each header and receives the group `text` and `length`.
const roles: Role[] = [
	{ label: 'Frontend', value: 'fe', department: 'Engineering' },
	{ label: 'Backend', value: 'be', department: 'Engineering' },
	{ label: 'Brand', value: 'br', department: 'Design' },
	{ label: 'Product', value: 'pr', department: 'Design' },
];

const role = ref<string | null>(null);
</script>
```

### Custom option rows

The `#option` slot replaces the row's **text** — use it for avatars, secondary
text or metadata. It exposes the raw `item`, the resolved `text` and `value`,
plus `selected` / `focused` / `disabled` / `loading` / `hasErrors` flags and the
row `index`. The selection check is not yours to redraw: it renders outside the
slot, so a custom row keeps it (`selected` is there for rows that want to show
the state some _other_ way, not for drawing a second check). Rows are fixed-height (the list is virtualized): if
your markup is taller than the default 28px (24px compact; 44px / 36px inside
the adaptive sheet), set `item-height` to match — and `header-height` for
grouped headers (defaults 32px / 24px compact; 36px / 32px in the sheet). The
taller touch ladder belongs to the sheet alone: a flyout is anchored to a
compact control, so it keeps the compact rows on every device — turning
`adaptive` off asks for that compact surface. An explicit `item-height` /
`header-height` wins everywhere.

**Rich option rows with an avatar chip**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
		<div class="flex items-baseline justify-between gap-2">
			<h3 class="text-sm font-medium">Code review</h3>
			<span class="text-xs text-[color:var(--bb-text-muted)]">PR #842</span>
		</div>
		<BbSelect
			v-model="assignee"
			compact
			item-text="label"
			item-value="value"
			:items="teammates"
			label="Assignee"
			placeholder="Choose a teammate"
		>
			<template #option="{ item, text }">
				<span class="flex w-full items-center gap-2">
					<BbAvatar :alt="text" size="32">{{ item.initials }}</BbAvatar>
					<span class="min-w-0 flex-1 truncate">{{ text }}</span>
					<span class="shrink-0 text-xs text-[color:var(--bb-text-muted)]">{{
						item.role
					}}</span>
				</span>
			</template>
		</BbSelect>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbAvatar, BbSelect } from 'bitboss-ui';

type Teammate = {
	label: string;
	value: string;
	initials: string;
	role: string;
};

// The `#option` slot replaces the default row rendering — here a BbAvatar
// initials fallback next to the resolved display `text`.
const teammates: Teammate[] = [
	{
		label: 'Ada Lovelace',
		value: 'ada',
		initials: 'AL',
		role: 'Platform',
	},
	{
		label: 'Grace Hopper',
		value: 'grace',
		initials: 'GH',
		role: 'Backend',
	},
	{
		label: 'Margaret Hamilton',
		value: 'maggie',
		initials: 'MH',
		role: 'Flight',
	},
];

const assignee = ref<string | null>(null);
</script>
```

### Custom chips

In `multiple` mode each selection renders as a badge. The `#chip` slot replaces
that badge outright — a colored label, an avatar plus a name, anything — and
receives `{ item, text, value, disabled, deselect }`. `item` is the raw entry
from `items` (where a per-selection color or avatar lives), `disabled` is `true`
while the control is `disabled` or `readonly` (render no remove affordance —
`deselect` refuses anyway), and `deselect` drops just this value from the model.

Custom chips need none of the library's class names: the chips row supplies the
spacing and keeps them from shrinking. The slot is not called in `comma` mode
(there are no chips to replace) nor for the collapsed "+N" summary that appears
once the chips outgrow the field — keep chips compact, or raise
`max-selected-labels`.

**Labels as colored chips**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
		<BbSelect
			v-model="tags"
			clearable
			item-text="label"
			item-value="value"
			:items="tagItems"
			label="Labels"
			multiple
			placeholder="Add labels"
		>
			<template #option="{ item, text }">
				<span class="flex w-full items-center gap-2">
					<span
						class="size-2 shrink-0 rounded-full"
						:style="{ background: item.color }"
					></span>
					<span class="min-w-0 flex-1 truncate">{{ text }}</span>
				</span>
			</template>
			<!-- The chip slot replaces the default badge for each selection. It
			hands over the raw `item` (here: the label's own color), the resolved
			`text` / `value`, a `disabled` flag that is true while the control is
			disabled or readonly, and `deselect` — which drops just this value. -->
			<template #chip="{ item, text, disabled, deselect }">
				<BbBadge
					:clearable="!disabled"
					size="lg"
					:style="{
						'--bg': `color-mix(in oklab, ${item.color} 15%, transparent)`,
						'--color': 'var(--bb-text)',
					}"
					@click:clear="deselect"
				>
					<span
						class="size-2 rounded-full"
						:style="{ background: item.color }"
					></span>
					{{ text }}
				</BbBadge>
			</template>
		</BbSelect>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbBadge, BbSelect } from 'bitboss-ui';

type Label = { label: string; value: string; color: string };

const tagItems: Label[] = [
	{ label: 'Bug', value: 'bug', color: '#ef4444' },
	{ label: 'Enhancement', value: 'enhancement', color: '#0ea5e9' },
	{ label: 'Documentation', value: 'documentation', color: '#8b5cf6' },
	{ label: 'Good first issue', value: 'good-first-issue', color: '#22c55e' },
];

const tags = ref<string[]>(['bug']);
</script>
```

### Slots around the input

Beyond the panel slots, the field itself is extensible:

- `#label` replaces the label text; receives `{ text, hasErrors, hasWarning }`.
- `#prefix` / `#suffix` render inline adornments inside the field (no scope) —
  currency symbols, units.
- `#prepend` / `#append` render inside the field wrapper, before/after the
  value area; both receive `{ query, focus, close }`.
- `#prepend-outer` / `#append-outer` render outside the field wrapper; both
  receive `{ query, close }` — e.g. a companion button acting on the field.

Prefer the icon props (`prepend:icon` / `append:icon`) over slots when an icon
is all you need.

### States

- `disabled` — control inert, chips become badges, hidden form inputs disabled.
- `readonly` — the value is visible and focusable but **the panel never
  opens**; chips become non-removable badges. Use it for review screens, not
  for fields whose options the user might still need to browse (they can't).
- `loading` — external loading state: shows the control spinner and suspends
  keyboard opening. Fetch-driven loading is automatic; don't mirror it here.
- `clearable` — clear affix when a value exists; emits `null` / `[]`.
- Empty panel — `no-data-text` or `#no-data`.

### Events and v-model

- `update:modelValue` — the resolved value (single) or array (multiple), on
  pick, chip removal, clear and coherence enforcement.
- `option:add` — Enter on a query with no highlighted option (see above).
- `focus` / `blur` — the control gaining/losing focus; `input` / `change` —
  native events from the panel search field.
- `inactive` — focus has fully left the component (control **and** panel).
  Because focus legitimately moves into the panel, validate on `inactive`, not
  on `blur`.

### Keyboard model

Shipped behavior — never reimplement it:

- Closed, control focused: `ArrowDown` opens and focuses the first selected
  option, `ArrowUp` opens and focuses the last selected, `Enter` opens and
  focuses the selection or the search field.
- Open: typing searches; `ArrowDown` / `ArrowUp` move the highlighted option
  while DOM focus stays in the search field (conveyed via
  `aria-activedescendant`); `Enter` confirms the highlighted option — or emits
  `option:add` when none is highlighted; `Esc` closes and returns focus to the
  control.
- Picking in single mode closes the panel and refocuses the control; in
  multiple mode the panel stays open and focus returns to the search field.
- Clicks or focus outside the control and panel close it.
- `disabled`, `readonly` and `loading` suppress the open/navigate bindings
  (`Esc` still closes an open panel).

### Sizing and layout

- `compact` — denser control and panel (24px options, 24px group headers).
- The panel width always matches the control; the control fills its container,
  so size it with layout classes on a wrapper (`class="max-w-xs"` etc.).
- `direction` works whenever the resolved label mode is `'outside'` (the
  library default) — `direction="horizontal"` gives a label-beside-field row.
  Only `floating`/`inside` label modes force the vertical layout, since they
  embed the label in the field itself.
- **A long `placeholder` or a long selected label never widens the control's
  track.** The trigger is a button, not an `<input>`, so the placeholder is
  real text rather than a paint-only `::placeholder` — but the field's minimum
  size is capped so that text cannot become the floor of a grid or flex track.
  Put a select with a paragraph-length placeholder in
  `grid-template-columns: repeat(3, 1fr)` and you still get three equal
  columns, with the text ellipsised inside its field. You do **not** need
  `min-w-0` on the item or `minmax(0, 1fr)` on the track to get this.

### Adaptive mobile sheet

With `adaptive` (default: global `config.adaptive`, which is `true`), the panel
opens as a bottom off-canvas sheet on mobile viewports (below
`config.mobileMaxWidth`) instead of a floating popover — same search, options
and header/footer slots, plus a chips row of the current selection above the
search field. The surface is latched per open cycle: a mid-open resize never
swaps popover ↔ sheet.

- `off-canvas-props` forwards extra `BbOffCanvas` props to the sheet (`size`,
  `draggable`, `fullscreen`, …).
- `disable-writing="'mobile'"` hides the search on the sheet only — common when
  the list is short.
- Set `:adaptive="false"` to keep a floating popover everywhere.

### Global config and platforms

From the vite/nuxt plugin options:

- `config.adaptive` — default for `adaptive` (see above).
- `config.mobileMaxWidth` — the viewport threshold for "mobile".
- `config.defaultInputLabelMode` — default `label-mode`.
- `config.locale` — built-in strings: the collapsed-chips summary ("N items
  selected") and the panel loading/no-data defaults. The library ships 22
  built-in dictionaries — see
  [Installation and Plugin Setup](./guides/installation-and-plugin-setup.md) §
  locale for the full list.

Platform notes:

- **SSR / Nuxt**: `prefill: true` providers also run in `onServerPrefetch`, so
  server-rendered pages hydrate with options loaded. Keep providers isomorphic
  (no `window` access).
- **Plain HTML forms / Inertia form posts**: give the select a `name` — hidden
  inputs carry the values (JSON-stringified when not strings), and `required`
  participates in native validation.
- The desktop panel is anchored to the control; the mobile sheet manages its
  own backdrop, Escape and focus.

### Works well with

- `BbSelectPopover` — the same engine on a custom trigger (status pills,
  table-cell chips, toolbars).
- `BbTable` — selects as column filters: list their models in the table
  provider's `dependencies`.
- `useToast` — surface provider failures (the component only logs them).
- `BbRadioGroup` / `BbCheckboxGroup` — swap to these when the option set turns
  out small and static; the `items` contract is identical, so migration is
  cheap.
- `BbTag` — open vocabularies typed by the user; `BbSelect` + `option:add`
  covers "known set, occasionally growable".

### Gotchas and constraints

- **Clicking the selected option does not clear a single select** — it re-picks
  it and closes the panel. Add `clearable` for an explicit clear button; a
  required status field should not empty itself because someone clicked twice.
  Multiple mode still toggles a selected option off.
- `multiple` with a non-array model **throws at setup** — seed `ref([])`.
- `placeholder` renders only in single mode; an empty multiple select shows
  nothing.
- **A `null` "All" option needs `prefill: true` when `items` is a provider.**
  Modelling "everything" as `{ label: 'All locations', value: null }` works — the
  row resolves and renders as the selection — but `null` is also the value the
  component reads as _nothing selected_, so it never upgrades to an eager
  prefill. With a provider that means nothing loads, there is no text, and the
  field renders the **placeholder** — greyed, indistinguishable from an empty
  select, while the model holds a real choice. Set `prefill: true` so the label
  can resolve. Array `items` need nothing: they are never lazy. (Note `clear`
  then also produces `null`, i.e. it selects "All" — use a sentinel like `'all'`
  if the two must stay distinct.)
- The local substring filter also applies to provider results — server matches
  whose text doesn't contain the query are hidden (see Search semantics).
- `filter-by` is `string[]` only (no function, no bare string) and matches
  exclusively those paths; each path must exist on every item or matching
  throws.
- `prefill: false` still fetches once when the panel first opens.
- `readonly` prevents the panel from opening at all.
- `enforce-coherence` + a provider that drops the selection on `prefill: true`
  calls = wiped model. Resolve the selection, or enable `stash`.
- The flip side: `stash` keeps every previously fetched option resolvable, so
  on a select with `dependencies` it also keeps _stale_ picks coherent —
  enforcement will never prune them. When an upstream change must clear
  now-invalid values, skip `stash` and resolve the selection in the provider
  instead.
- `direction` is honored with `'outside'` labels (the default); it is ignored
  only under `floating`/`inside` label modes.
- No `#chevron` slot — customise the trailing icon via `append:icon`.
- The multiple-mode search query persists after picking an option (it clears on
  close).
- `option:add` can fire with an empty string — trim and guard in the handler.

### Anti-patterns

- Pre-mapping items to `{ label, value }`, or storing whole objects in the
  model when an id is enough.
- `watch(filter, refetch)` when `dependencies` exists; blind `model = null`
  resets when `enforce-coherence` would preserve still-valid values.
- Hand-rolled debounce or loading refs around the provider.
- Rebuilding chips, counts or select-all outside the component when `max`,
  `max-selected-labels`, `selected-labels-fn` and the panel slots cover it.
- Expecting a `disabled` field on items to disable options — it is inert data;
  use the `selectable` predicate or filter unavailable options out.
- Using `BbSelect` for three static options (that's `BbRadioGroup`), or as an
  actions menu (that's `BbDropdown`).

### Accessibility

- `label` is mandatory and is the accessible name; use `hide-label` (not an
  empty label) to hide it visually. The activator is announced as a combobox
  with `aria-expanded` and `aria-controls`; the selected text is the trigger's
  own content (the select-only combobox pattern — its value is what the
  element shows).
- `errors`, `warnings`, `description` and `hint` are all wired to the trigger through
  `aria-describedby`, in that order: the reason the field is invalid is spoken
  first when it regains focus, and a channel is referenced only while it
  actually has copy. Messages _also_ render in an `aria-live="polite"` region,
  so they are announced the moment they appear — announced on change, re-read
  on focus. The error state also sets `aria-invalid`.
- The panel manages listbox roles, `aria-activedescendant` and the full
  keyboard model (see Keyboard model) for you — do not rebuild any of it.
- The in-panel search field ships an accessible name ("Search options").
- Chip removal affordances only render when removal is actually possible (not
  under `disabled` / `readonly` / `comma`).

## v-model

- `v-model` — type: `any`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | When `true`, the options panel opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover; on desktop it stays a popover. When unset, falls back to the global `config.adaptive`. |
| `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
| `autocomplete` | `string \| undefined` |  |  | Guides to the browser as to the type of information expected in the field. |
| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
| `clearable` | `boolean \| undefined` | `false` |  | Displays a clear button when the input has a value and is being interacted with. |
| `comma` | `boolean \| undefined` | `false` |  | Sets the display model for selected values to a list of comma separated string. In this mode the user cannot deselect an option by pressing the close button. |
| `compact` | `boolean \| undefined` | `false` |  | Sets the component in a compact mode. |
| `dependencies` | `unknown[] \| undefined` |  |  | Defines an array of dependencies that will trigger actions in the component upon change. |
| `depsDebounceTime` | `number \| undefined` | `0` |  | Timeout used to debounce response to changes to dependencies. |
| `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
| `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
| `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` | `false` |  | Controls whether the search input is shown inside the dropdown panel. Use `'mobile'` / `'desktop'` to hide it on that platform only. |
| `enforceCoherence` | `boolean \| undefined` | `false` |  | If coherence is enforced the input cannot have a modelValue that is incoherent with its current items. modelValue will be reset upon incoherence. |
| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
| `filterBy` | `string[] \| undefined` | `[]` |  | Property paths used to filter options when the user types in the search input. When empty (default) options are matched against their display text. When non-empty the provided paths are searched instead of the display text. To disable filte… |
| `groupBy` | `string \| ((item: T) => string \| number \| symbol) \| undefined` |  |  | Path to item property for grouping options. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
| `headerHeight` | `number \| undefined` |  |  | Height of group headers in the listbox (px). Defaults to 32px (24px compact; 36px / 32px on mobile viewports). Only applies when `groupBy` is set. An explicit value wins on every viewport. |
| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `itemHeight` | `number \| undefined` | `28` |  | Height of the options in the listbox (px). Defaults to 28px (24px compact; 44px / 36px on mobile viewports). An explicit value wins on every viewport. |
| `items` | `T[] \| ((query: string, prefill: boolean, modelValue: any) => Promise<T[]>) \| ((query: string, prefill: boolean, modelValue: any) => T[])` |  | yes | Used to retrieve items; can be an array or a function. |
| `itemText` | `ItemAccessor<T, string> \| undefined` |  |  | Defines a path that returns a property of the object to use as text or a function that returns a string. |
| `itemValue` | `ItemAccessor<T> \| undefined` |  |  | Defines a path that returns a property of the object to use as value or a function that returns any value. |
| `label` | `string` |  | yes | Text content of the label of the element. |
| `labelMode` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Label rendering mode. |
| `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
| `loading` | `boolean \| undefined` | `false` |  | Sets the component in a loading state, usually triggering some visual styles. |
| `loadingText` | `string \| undefined` |  |  | String displayed while items are being loaded. |
| `max` | `number \| undefined` |  |  | Maximum number of selectable items when the multiple flag is set. |
| `maxSelectedLabels` | `number \| undefined` |  |  | Maximum number of labels shown before collapsing to a count summary. |
| `modelValue` | `any` |  | yes | Used by v-model. Can be any serializable type. |
| `modelValueDebounceTime` | `number \| undefined` | `0` |  | Timeout used to debounce response to changes to modelValue. |
| `multiple` | `boolean \| undefined` | `false` |  | Allows the selection of multiple items. |
| `name` | `string \| undefined` |  |  | Defines the name of the input. |
| `noDataText` | `string \| undefined` |  |  | String displayed when there are no items to display. |
| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile. |
| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
| `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
| `prefill` | `boolean \| "interaction" \| undefined` | `'interaction'` |  | Controls when items are pre-loaded. `'interaction'` loads on the first user interaction, `true` loads immediately on mount, `false` is *search-first*: with a provider, nothing is fetched until the user types — opening alone does not load, a… |
| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
| `queryDebounceTime` | `number \| undefined` | `500` |  | Time to wait when the user stops writing in the input before querying data. |
| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
| `selectable` | `boolean \| ((item: T) => boolean) \| undefined` | `true` |  | Defines whether options are selectable. Can be a global boolean that affects all options or a function that accepts an item and returns a boolean that only affects that item. Non-selectable options are rendered disabled. |
| `selectedLabelsFn` | `((count: number) => string) \| undefined` |  |  | Function that returns a string to be displayed when the number of selected labels is greater than `maxSelectedLabels`. |
| `stash` | `boolean \| undefined` | `false` |  | Adds a stash to accumulate selected values across searches. |
| `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds. |
| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |

## Events

- `active` — `(e: "active"): void`
- `blur` — `(e: "blur", event: FocusEvent): void`
- `change` — `(e: "change", event: Event): void`
- `click` — `(e: "click", event: MouseEvent): void`
- `focus` — `(e: "focus", event: FocusEvent): void`
- `inactive` — `(e: "inactive"): void`
- `input` — `(e: "input", event: Event): void`
- `option:add` — `(e: "option:add", text: string): void`
- `update:modelValue` — `(e: "update:modelValue", value: any): void`

## Slots

- `append` — scope: `{ query: string; focus: () => void; close: () => Promise<void>; }` — Content appended inside the input field, after the value area.
- `append-outer` — scope: `{ query: string; close: () => Promise<void>; }` — Content appended outside the input field wrapper.
- `chip` — scope: `BbSelectChipSlotProps<T>` — Replaces the default badge rendered for each selection in `multiple` mode. Not called in `comma` mode, nor for the collapsed "+N" summary.
- `footer` — scope: `BbSelectPanelSlotProps` — Content pinned to the bottom of the options panel, below the options list. Rendered in both the desktop popover and the adaptive sheet.
- `group` — scope: `BbSelectGroupSlotProps<T>` — Replaces the default group header rendered above grouped options.
- `header` — scope: `BbSelectPanelSlotProps` — Content pinned to the top of the options panel, above the search field. Rendered in both the desktop popover and the adaptive sheet.
- `label` — scope: `BbSelectLabelSlotProps` — Replaces the default label text rendered above the input.
- `loading` — scope: `{ query: string; }` — Content shown inside the options dropdown while items are loading.
- `no-data` — scope: `{ query: string; focus: () => void; }` — Content shown when no options match the query or the list is empty.
- `option` — scope: `BbSelectOptionSlotProps<T>` — Replaces the default rendering of each option row in the dropdown.
- `prefix` — scope: `object` — Content rendered as an inline prefix inside the input field.
- `prepend` — scope: `{ query: string; focus: () => void; close: () => Promise<void>; }` — Content prepended inside the input field, before the value area.
- `prepend-outer` — scope: `{ query: string; close: () => Promise<void>; }` — Content prepended outside the input field wrapper.
- `suffix` — scope: `object` — Content rendered as an inline suffix inside the input field.

## Validated variant

Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).

| Prop | Type | Description |
| --- | --- | --- |
| `rules` | `RuleExpression<any>` | vee-validate rules for this field. |
| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |

## See Also

- [BbSelectPopover](./BbSelectPopover.md) — Provides popover-driven option selection and search.
- [BbCheckboxGroup](./BbCheckboxGroup.md) — Manages multiple checkbox options as a group.
- [BbRadioGroup](./BbRadioGroup.md) — Coordinates exclusive selection among radio options.

---

<!-- dist/ai/BbSelectPopover.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbSelectPopover.md -->

# BbSelectPopover

## Agent Contract

- Safety level: **Consumer API**
- Group: **Selection**
- Description: Provides popover-driven option selection and search.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbSelectPopover.md](./source/BbSelectPopover.md)

## Usage & Guidelines

### When to use

`BbSelectPopover` is `BbSelect` with the inline form input removed: **you own the
trigger**, it owns search, filtering, keyboard navigation, single/multiple
selection and the virtualized options list. Reach for it when the control that
opens the picker is _not_ a form field — a status pill, an avatar stack, a role
badge, a toolbar button, a table-cell chip. It is the right tool for
command-palette and inline-edit patterns.

Prefer a sibling when the shape is different:

- You want a **labelled, bordered form control** with hint/error/description
  states → `BbSelect` (`./BbSelect.md`). That is a field, not a trigger.
- A small, always-visible exclusive choice → `BbRadioGroup`; small static
  multi-choice → `BbCheckboxGroup` / `BbSwitchGroup`.
- Values the user _invents_ → `BbTag`; a known-but-growable set →
  `BbSelectPopover` (or `BbSelect`) with `option:add`.

Everything from the **Options and Items** and **Fetch Items** playbooks carries
over unchanged — this component shares `BbSelect`'s option engine. This guide
covers what is _specific_ to the popover: the activator, and the traps of
driving a trigger you render yourself.

### Map options with `item-text` / `item-value`

Pass your domain objects to `items` as they are and name the display/value
fields with `item-text` / `item-value` (dot-paths or extractor functions). The
`v-model` holds the resolved **value**, not the whole object. The value-identity
rules are the shared ones (see the Options and Items playbook), in brief:

- Primitive `items` (`string[]` / `number[]`) need no mapping props; for object
  items always set both.
- Matching compares **value hashes** (deep structural equality), so object
  values survive refetches — but prefer stable primitive ids.
- Options resolving to a **duplicate value are silently dropped** (first wins).
- Gate individual options with `selectable` — a boolean (`false` disables every
  option) or a predicate `(item) => boolean`; rejected options render disabled
  and keyboard navigation skips them. A `disabled` field on the item object is
  inert domain data — feed it to the predicate
  (`:selectable="(item) => !item.disabled"`) if it encodes availability.

### Wire up an activator

Provide the trigger through the `#activator` slot and **spread its `props` onto
your element** with `v-bind="props"` — that wires the popover reference and the
open/close handlers. The full slot scope:

- `props` — spread onto the focusable trigger element.
- `shown` — is the popover open (reflect it visually).
- `toggle` / `open` / `close` — imperative open-state control (all async).
- `clear` — empty the selection (and query).
- `focus` — focus the search field (or the listbox when writing is disabled).
- `query` — the current search string.
- `selectedOptions` — the resolved selected options (`.text` / `.value` /
  `.item`) — **popover state** (see below).
- `text` — display text of the current selection — **popover state** (see below).
- `disabled` / `readonly` / `loading` — state mirrors for styling the trigger.

**The trigger must not depend on the popover's state — label it from your own
data.** The popover is an _optional_ editing affordance: it may never be opened,
and whether it has been opened must never change how the trigger reads. `text`
and `selectedOptions` resolve the model against **loaded options**, so with a
provider they stay empty until that provider first runs — by default, the first
open. A trigger fed from them renders blank and then flickers into truth; a
trigger fed from your own data is correct on first paint and stays that way.

The robust pattern — used in the example — is a `computed` that resolves the
label from the model against your own data:

```ts
const assigneeLabel = computed(
	() => people.find((p) => p.id === assignee.value)?.name ?? 'Unassigned'
);
```

(Array `items` do resolve on mount, so `text` is populated from the first paint
there — but keep labelling from your own data anyway: it is the same amount of
code, and it does not change meaning the day the array becomes a provider.)

**Filter-pill assignee picker**

```vue
<template>
	<div
		class="flex max-w-sm items-center gap-1.5 rounded-[var(--bb-radius)] border p-2"
	>
		<span class="pr-1 text-xs font-medium text-[color:var(--bb-text-muted)]"
			>Assignee</span
		>
		<BbSelectPopover
			v-model="assignee"
			compact
			item-text="fullName"
			item-value="id"
			:items="teammates"
			width="240px"
		>
			<template #activator="{ props }">
				<!-- The badge IS the trigger — Linear filter-pill grammar. Label
				from our own state, never the slot's `text` (empty until first open
				with a provider). -->
				<BbBadge
					append:icon="lucide:chevron-down"
					prepend:icon="lucide:user"
					size="lg"
					variant="outline"
				>
					<BbBadgeButton aria-label="Filter by assignee" v-bind="props">{{
						assigneeLabel || 'Assign'
					}}</BbBadgeButton>
				</BbBadge>
			</template>
		</BbSelectPopover>
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';

type Teammate = {
	id: string;
	fullName: string;
};

const teammates: Teammate[] = [
	{ id: 'ada', fullName: 'Ada Lovelace' },
	{ id: 'grace', fullName: 'Grace Hopper' },
	{ id: 'alan', fullName: 'Alan Turing' },
	{ id: 'maggie', fullName: 'Margaret Hamilton' },
];

const assignee = ref<string | null>(null);

const assigneeLabel = computed(
	() => teammates.find((t) => t.id === assignee.value)?.fullName ?? ''
);
</script>
```

### Multiple selection

Add `multiple` and the model becomes an array — it **must be seeded as one**
(`ref<string[]>([])`); a non-array model **throws at setup**
(`"Multiple is set to \"true\" but modelValue is not an array."`). Cap the count
with `max`: at the cap, unselected options auto-disable while selected ones never
do, so the user can always deselect. Because the trigger is yours, _you_
summarise the selection — a count, a chip cluster, an avatar stack — from
`selectedOptions` or your own model.

**Reviewers filter pill with a live count**

```vue
<template>
	<div
		class="flex max-w-sm items-center gap-1.5 rounded-[var(--bb-radius)] border p-2"
	>
		<span class="pr-1 text-xs font-medium text-[color:var(--bb-text-muted)]"
			>Filters</span
		>
		<BbSelectPopover
			v-model="reviewers"
			compact
			item-text="name"
			item-value="id"
			:items="people"
			:max="4"
			multiple
			width="240px"
		>
			<template #activator="{ props }">
				<!-- Summarise the multi-select yourself — a live count on the pill. -->
				<BbBadge
					append:icon="lucide:chevron-down"
					prepend:icon="lucide:users"
					size="lg"
					variant="outline"
				>
					<BbBadgeButton v-bind="props"
						>Reviewers ({{ reviewers.length }})</BbBadgeButton
					>
				</BbBadge>
			</template>
		</BbSelectPopover>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';

type Person = { id: string; name: string };

const people: Person[] = [
	{ id: 'ada', name: 'Ada Lovelace' },
	{ id: 'grace', name: 'Grace Hopper' },
	{ id: 'alan', name: 'Alan Turing' },
	{ id: 'katherine', name: 'Katherine Johnson' },
	{ id: 'ken', name: 'Ken Thompson' },
];

// `multiple` requires an array model from the start.
const reviewers = ref<string[]>(['ada', 'grace']);
</script>
```

### Custom option rows

The `#option` slot replaces each row's **text** — exposing the raw `item`,
resolved `text` / `value`, the row `index`, and `selected` / `focused` /
`disabled` / `loading` flags — so options can carry avatars, badges or secondary
metadata. The selection check renders outside the slot and survives any custom
markup, so there is no need to redraw it from `selected`. Rows are
fixed-height and virtualized: if your markup is taller than the default 28px
(24px compact; 44px / 36px inside the adaptive sheet), set `item-height` to
match — and `header-height` for grouped headers (32px / 24px compact; 36px /
32px in the sheet). The taller touch ladder belongs to the sheet alone: a
flyout is anchored to a compact control, so it keeps the compact rows on every
device — turning `adaptive` off asks for that compact surface. An explicit
height wins everywhere.

**Option rows with avatar initials**

```vue
<template>
	<div
		class="flex max-w-sm items-center gap-1.5 rounded-[var(--bb-radius)] border p-2"
	>
		<span class="pr-1 text-xs font-medium text-[color:var(--bb-text-muted)]"
			>Owner</span
		>
		<BbSelectPopover
			v-model="owner"
			compact
			:item-height="48"
			item-text="label"
			item-value="value"
			:items="people"
			width="240px"
		>
			<template #activator="{ props }">
				<BbBadge
					append:icon="lucide:chevron-down"
					prepend:icon="lucide:user"
					size="lg"
					variant="outline"
				>
					<BbBadgeButton v-bind="props">{{
						ownerLabel || 'Set owner'
					}}</BbBadgeButton>
				</BbBadge>
			</template>
			<!-- The slot replaces the row's TEXT only: the selection check keeps
			rendering outside it, so custom rows never have to redraw it. -->
			<template #option="{ item, text }">
				<span class="flex w-full items-center gap-2">
					<BbAvatar :alt="text" size="32">{{ item.initials }}</BbAvatar>
					<span class="min-w-0 flex-1 truncate">{{ text }}</span>
				</span>
			</template>
		</BbSelectPopover>
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbAvatar, BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';

type Person = { label: string; value: string; initials: string };

const people: Person[] = [
	{ label: 'Ada Lovelace', value: 'ada', initials: 'AL' },
	{ label: 'Grace Hopper', value: 'grace', initials: 'GH' },
	{ label: 'Alan Turing', value: 'alan', initials: 'AT' },
];

const owner = ref<string | null>(null);
const ownerLabel = computed(
	() => people.find((p) => p.value === owner.value)?.label ?? ''
);
</script>
```

### Fetch options with a provider

When options come from a backend, pass a **function** to `items`. It receives
`(query, prefill, modelValue)` and returns `Item[]` or a `Promise<Item[]>` — the
full call matrix is the shared one in the Fetch Items playbook. The essentials:

- `prefill === false` means exactly one thing: **the user typed** — search then.
- Every component-initiated call (first load, dependency change, model change)
  passes `prefill === true` and expects the current selection to stay resolvable
  in the response — so return the selected items (by id) to keep the trigger
  label and chips accurate.
- `modelValue` is your v-model as-is; the prop types it `any` — an array in
  `multiple` mode, the raw model value (possibly `null`) in single mode.

Runtime guarantees you should not re-implement: **debouncing** (`query-debounce-time`
default 500ms; `deps-debounce-time` and `model-value-debounce-time` default 0),
**race protection** (out-of-order responses discarded), **loading** (in-flight
requests set the slot's `loading` flag automatically — the `loading` prop is only
for _external_ pending state), and **errors** (a rejected provider is logged and
the previous items kept — surface failures yourself via `useToast`). Enable
`stash` to accumulate picked options across searches so chosen values stay
resolvable even when later responses omit them.

**Async, debounced destination picker**

```vue
<template>
	<div
		class="flex max-w-sm items-center gap-1.5 rounded-[var(--bb-radius)] border p-2"
	>
		<span class="pr-1 text-xs font-medium text-[color:var(--bb-text-muted)]"
			>Trip</span
		>
		<BbSelectPopover
			v-model="destination"
			compact
			item-text="label"
			item-value="value"
			:items="searchCities"
			loading-text="Searching…"
			no-data-text="No city found"
			:query-debounce-time="250"
			width="240px"
		>
			<template #activator="{ props, loading }">
				<!-- Badge `loading` reflects the provider's in-flight fetch. Label
				from our own pool — never the slot's `text`. -->
				<BbBadge
					append:icon="lucide:chevron-down"
					:loading="loading"
					prepend:icon="lucide:map-pin"
					size="lg"
					variant="outline"
				>
					<BbBadgeButton v-bind="props">{{
						destinationLabel || 'Add destination'
					}}</BbBadgeButton>
				</BbBadge>
			</template>
		</BbSelectPopover>
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';

type City = { label: string; value: string };

const pool: City[] = [
	{ label: 'Amsterdam', value: 'amsterdam' },
	{ label: 'Athens', value: 'athens' },
	{ label: 'Barcelona', value: 'barcelona' },
	{ label: 'Copenhagen', value: 'copenhagen' },
	{ label: 'Dublin', value: 'dublin' },
	{ label: 'Prague', value: 'prague' },
];

const fetchFromApi = (predicate: (city: City) => boolean) =>
	new Promise<City[]>((resolve) => {
		setTimeout(() => resolve(pool.filter(predicate)), 250);
	});

const searchCities = (
	query: string,
	prefill: boolean,
	// The raw v-model — type it with your own model shape: a single value (or
	// null) here, an array in multiple mode.
	modelValue: string | null
): Promise<City[]> => {
	// Prefill: resolve the current selection so the trigger label stays accurate.
	if (prefill && modelValue) {
		return fetchFromApi((city) => city.value === modelValue);
	}
	if (!query.trim()) return Promise.resolve([]);
	const q = query.trim().toLowerCase();
	return fetchFromApi((city) => city.label.toLowerCase().includes(q));
};

const destination = ref<string | null>(null);
const destinationLabel = computed(
	() => pool.find((c) => c.value === destination.value)?.label ?? ''
);
</script>
```

### Laziness, prefill and the trigger label

`prefill` controls **when the first load happens**: `'interaction'` (default) on
first open, `true` immediately on mount (and during SSR via `onServerPrefetch`),
`false` **search-first** — nothing is fetched until the user types a query.
Opening the panel is not a search, so it loads nothing; until the first query the
list shows a _"search to begin"_ hint instead of "no data".

Reach for `false` when the result set is too large or too expensive to browse and
the query is the only sensible entry point — a user picker over thousands of
rows. Note the panel is deliberately empty on open: that is the mode telling the
user to type.

**Search-first needs both a way to search and something to defer**, so `false`
falls back to loading on open when either is missing:

- **Writing is disabled** (`disable-writing`, including the per-surface
  `'mobile'`/`'desktop'` forms) — there is no search field, so a user could never
  trigger the load and the panel would stay empty forever.
- **The model is non-empty** — its text has to resolve for the selection to
  render. (In-field `BbSelect` upgrades this to a mount prefill; see below.)

**Two further cases ignore `prefill` entirely and always load**, because deferring
would buy nothing or break a promise you made:

- **`items` is an array.** There is no request to defer, so laziness would only
  leave the selection unresolved. Options resolve on mount, whatever `prefill`
  says — free, and it makes `text`/`selectedOptions` and coherence work from the
  first paint.
- **`enforce-coherence` over a non-empty model.** Validating a value is
  impossible without options, so the popover loads and checks on that first load.
  An empty model stays lazy — empty is always coherent, so there is nothing to
  check.

Outside those two, a standalone popover with a **provider does not** auto-upgrade
a seeded model to an eager prefill the way in-field `BbSelect` does. That
laziness is deliberate: a fetch per instance must be something you ask for (see
_One popover per table row_).

**Do not reach for `prefill: true` to fix a trigger label.** Resolve the label
from your own state instead (above) — a trigger that needs a fetch to render is
a trigger that renders wrong until the fetch lands.

### Dependent fields and coherence

When one picker constrains another, list the upstream value in `dependencies`:
the provider re-runs whenever a dependency changes (value-hash compared, so array
identity churn doesn't refetch), debounced by `deps-debounce-time`. Add
`enforce-coherence` to auto-clean a now-invalid selection — multiple emits the
**filtered array**, single emits **`null`**, an already-empty selection stays
quiet. Because enforcement checks the merged result (fetched + stashed), a
provider that returns `[]` on a `prefill: true` call **wipes a valid selection** —
always resolve the current selection on component-initiated calls, or enable
`stash`. The full mechanics are in the Coherence playbook.

**You do not need `prefill: true` to make this work.** Asking for
`enforce-coherence` over a seeded model _is_ a request to validate it, and that
is impossible without options — so the popover loads on mount by itself and runs
the check on that first load. The filter bar below relies on exactly that: no
`prefill` prop anywhere, yet switching the project re-runs the milestone provider
and clears a milestone the new project lacks, while a still-valid one survives.

What that costs is honest and worth knowing: **`enforce-coherence` opts each
instance into its own load**. One filter, one request. Fifty rows with a provider
each, fifty requests. That is the trade you asked for by enabling it — and it is
the reason the table pattern below hands every row the _same array_ instead.

#### Never share one ref across instances

Independent popovers each with their own model and their own `enforce-coherence`
are fine: every instance judges **its own** value against **its own** options, so
they never interfere. What breaks is binding them all to **one** ref:

```vue
<!-- WRONG: every row writes the same value -->
<script setup>
const status = ref(null); // ← one ref, shared by every row
</script>
<BbSelectPopover v-for="row in rows" v-model="status" enforce-coherence … />
```

Now every instance judges **the same** value against **its own** options, and
coherence's answer to a value it doesn't recognise is `null`. Pick a value only
one row's options contain and the others each emit `null` in turn — measured with
5 rows: the pick lands, four instances overwrite it, the model ends `null`. The
user watches their choice vanish, with nothing logged.

The component cannot catch this for you: it receives a **value**, not a ref
identity, and two rows legitimately holding the same value is ordinary. Give
every row its own model.

**Toolbar filter pills — milestone follows project**

```vue
<template>
	<div
		class="flex max-w-md flex-wrap items-center gap-1.5 rounded-[var(--bb-radius)] border p-2"
	>
		<span class="pr-1 text-xs font-medium text-[color:var(--bb-text-muted)]"
			>Filters</span
		>
		<BbSelectPopover
			v-model="project"
			compact
			disable-writing
			item-text="name"
			item-value="id"
			:items="projects"
			width="200px"
		>
			<template #activator="{ props }">
				<BbBadge
					append:icon="lucide:chevron-down"
					prepend:icon="lucide:folder"
					size="lg"
					variant="outline"
				>
					<BbBadgeButton v-bind="props">{{ projectLabel }}</BbBadgeButton>
				</BbBadge>
			</template>
		</BbSelectPopover>
		<BbSelectPopover
			v-model="milestone"
			compact
			:dependencies="[project]"
			:deps-debounce-time="150"
			enforce-coherence
			item-text="title"
			item-value="id"
			:items="fetchMilestones"
			no-data-text="No milestone matches"
			width="220px"
		>
			<template #activator="{ props }">
				<BbBadge
					append:icon="lucide:chevron-down"
					prepend:icon="lucide:flag"
					size="lg"
					variant="outline"
				>
					<BbBadgeButton v-bind="props">{{
						milestoneLabel || 'Milestone'
					}}</BbBadgeButton>
				</BbBadge>
			</template>
		</BbSelectPopover>
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';

type Project = { id: string; name: string };
type Milestone = { id: string; title: string; project: string };

const projects: Project[] = [
	{ id: 'mobile', name: 'Mobile app' },
	{ id: 'web', name: 'Web dashboard' },
	{ id: 'design', name: 'Design system' },
];

const milestonePool: Milestone[] = [
	{ id: 'ms-beta', title: 'Private beta', project: 'mobile' },
	{ id: 'ms-launch', title: 'App Store launch', project: 'mobile' },
	{ id: 'ms-ga', title: 'GA rollout', project: 'web' },
	{ id: 'ms-audit', title: 'SOC 2 audit', project: 'web' },
	{ id: 'ms-tokens', title: 'Token overhaul', project: 'design' },
];

const project = ref<string>('mobile');
const milestone = ref<string | null>('ms-beta');

// Trigger labels come from our own state — the slot's `text` is empty until
// the popover first matches the model against loaded items.
const projectLabel = computed(
	() => projects.find((p) => p.id === project.value)?.name ?? 'Project'
);
const milestoneLabel = computed(
	() => milestonePool.find((m) => m.id === milestone.value)?.title ?? ''
);

// Query-aware provider. Component-initiated calls (the mount load, project
// changes via `dependencies`) pass `prefill === true` and get the project's
// full list back, so a still-valid selection stays resolvable —
// `enforce-coherence` then clears only a milestone the new project lacks.
// No `prefill` prop needed: `enforce-coherence` over a seeded model loads on
// mount by itself, because validating a value requires having the options.
const fetchMilestones = (
	query: string,
	prefill: boolean,
	_modelValue: string | null
): Promise<Milestone[]> => {
	const inProject = milestonePool.filter((m) => m.project === project.value);
	const q = query.trim().toLowerCase();
	const matches = prefill
		? inProject
		: inProject.filter((m) => m.title.toLowerCase().includes(q));
	return new Promise((resolve) => setTimeout(() => resolve(matches), 200));
};
</script>
```

### One popover per table row (inline edit)

The status-pill-in-a-table is the popover's signature use — and the structure of
the **page** decides whether it scales. Three rules, in priority order:

**1. Resolve the options once, for the whole page. Pass an array, not a provider.**
This is the load-bearing decision. A provider is per-instance, so 50 rows means
50 popovers each owning a fetch. Lift the fetch to the page, `await` it once, and
hand every row the same array — 50 rows, **zero** requests, because there is
nothing left to fetch. Array `items` are never lazy either: every row resolves on
mount, so selections and coherence work immediately with no `prefill` prop.

```ts
// Page level — once, not per row.
const statuses = ref<Status[]>([]);
onMounted(async () => (statuses.value = await api.statuses.list()));
```

**2. Hold the edit off the row — a page-level draft map keyed by id.** Never
`v-model="item.status"`: writing straight back onto the slot's `item` mutates the
table's data, so any refetch (a filter change, a poll) silently discards the edit,
and a partially-dirty row has no clean before/after. Instead bind the value _down_
(`:model-value="valueOf(item, 'status')"`) and commit it _up_ into a `drafts` map
(`@update:model-value="setField(item, 'status', $event)"`). The map is the dirty
set **and** the save payload; the row object stays pristine. This is the table
case of the [inline-edit playbook](../../ai/guides/inline-edit-playbook.md) —
reach for autosave there instead when the domain wants every pick to persist on
the spot.

**3. Label the pill from your own state, not from the popover.**
`{{ labelFor(valueOf(item, 'status')) }}` resolved against your page-level array —
never the slot's `text`. The badge must read correctly on first paint for every
row, including the hundreds nobody ever opens.

**Inline status cell — soft badge editor**

```vue
<template>
	<div class="flex max-w-xl flex-col gap-1.5">
		<div
			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
		>
			<BbTable
				caption="Tickets — edit statuses, then Save the batch"
				:columns="columns"
				compact
				item-value="id"
				:items="tickets"
			>
				<!-- One popover per row. Three rules keep it cheap and correct:
				     1. `:items="statuses"` is the SAME array for every row — resolved
				        once at page level, so N rows cost zero extra requests.
				     2. The edit is held in a page-level `drafts` map keyed by row id,
				        NEVER written back onto `item`. Bind the value down with
				        `valueOf` and commit up with `setField`; the row object stays
				        pristine, so a refetch (filter, poll) can't wipe an edit.
				     3. The pill renders from `valueOf(item, 'status')`, our own state —
				        never the slot's `text` — so it is correct on first paint
				        whether or not the popover is ever opened. -->
				<template #status="{ item }">
					<BbSelectPopover
						compact
						disable-writing
						item-text="label"
						item-value="value"
						:items="statuses"
						:model-value="valueOf(item, 'status')"
						width="180px"
						@update:model-value="setField(item, 'status', $event as Status)"
					>
						<template #activator="{ props, shown }">
							<!-- Soft status pill: the badge IS the trigger. A dirty pill
							(edited, not yet saved) keeps a deeper border until Save. -->
							<BbBadge
								append:icon="lucide:chevron-down"
								:class="{
									'status-trigger--editing': shown,
									'status-trigger--dirty': isDirty(item),
								}"
								size="lg"
								:variant="variantFor(valueOf(item, 'status'))"
							>
								<BbBadgeButton v-bind="props">{{
									labelFor(valueOf(item, 'status'))
								}}</BbBadgeButton>
							</BbBadge>
						</template>
					</BbSelectPopover>
				</template>
			</BbTable>
		</div>

		<div class="flex items-center gap-2">
			<BbButton :disabled="!dirtyCount" size="sm" @click="save">
				Save{{ dirtyCount ? ` (${dirtyCount})` : '' }}
			</BbButton>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				Edits live in a draft map keyed by row id — the map is the save payload.
				Rows are never mutated, so nothing is lost on a refetch.
			</span>
		</div>
	</div>
</template>
<script setup lang="ts">
import { computed, reactive, ref } from 'vue';
import {
	BbBadge,
	BbBadgeButton,
	BbButton,
	BbSelectPopover,
	BbTable,
} from 'bitboss-ui';
import type { BadgeVariantType, BbTableColumn } from 'bitboss-ui';

type Status = 'open' | 'in-progress' | 'blocked' | 'done';
type Ticket = { id: string; ref: string; title: string; status: Status };
type Patch = Partial<Pick<Ticket, 'status'>>;

/**
 * The option list is resolved ONCE for the whole page and handed to every row as
 * a plain array. With a provider per row, each popover would own its own fetch;
 * as an array there is no request at all, and every row resolves on mount.
 */
const statuses: Array<{ value: Status; label: string }> = [
	{ value: 'open', label: 'Open' },
	{ value: 'in-progress', label: 'In progress' },
	{ value: 'blocked', label: 'Blocked' },
	{ value: 'done', label: 'Done' },
];

const tickets = ref<Ticket[]>([
	{
		id: 't-1',
		ref: 'BB-104',
		title: 'Popover drops focus on Esc',
		status: 'open',
	},
	{
		id: 't-2',
		ref: 'BB-118',
		title: 'Table header misaligns at 320px',
		status: 'in-progress',
	},
	{
		id: 't-3',
		ref: 'BB-121',
		title: 'Token audit for dark mode',
		status: 'blocked',
	},
	{
		id: 't-4',
		ref: 'BB-130',
		title: 'Ship the migration guide',
		status: 'done',
	},
]);

const columns: Array<BbTableColumn<Ticket>> = [
	{ key: 'ref', label: 'Ref', width: 90 },
	{ key: 'title', label: 'Title' },
	{ key: 'status', label: 'Status', width: 140 },
];

/* ---- Draft map: the edit lives here, never on the row -------------------- */

const drafts = reactive<Record<string, Patch>>({});

/**
 * Read-through: the draft wins, the row is the fallback. Use a `key in` check,
 * NOT `??` — a field legitimately drafted to a nullish value would otherwise
 * fall through to the row.
 */
const valueOf = <K extends keyof Patch>(item: Ticket, key: K): Ticket[K] => {
	const draft = drafts[item.id];
	return draft && key in draft ? (draft[key] as Ticket[K]) : item[key];
};

/** One setter covers every field; re-picking the original un-dirties for free. */
const setField = <K extends keyof Patch>(
	item: Ticket,
	key: K,
	value: Patch[K]
) => {
	if (value === item[key]) {
		delete drafts[item.id]?.[key];
		if (drafts[item.id] && !Object.keys(drafts[item.id]).length) {
			delete drafts[item.id];
		}
		return;
	}
	(drafts[item.id] ??= {})[key] = value;
};

const isDirty = (item: Ticket) => drafts[item.id]?.status !== undefined;
const dirtyCount = computed(() => Object.keys(drafts).length);

/** The map IS the payload. Here it patches the local rows; a real app PATCHes. */
const save = () => {
	tickets.value = tickets.value.map((row) =>
		drafts[row.id] ? { ...row, ...drafts[row.id] } : row
	);
	Object.keys(drafts).forEach((id) => delete drafts[id]);
};

/* Row labels come from our own state — stable regardless of popover state. */
const labelFor = (status: Status) =>
	statuses.find((s) => s.value === status)?.label ?? '—';

const VARIANT: Record<Status, BadgeVariantType> = {
	open: 'soft-gray',
	'in-progress': 'soft-blue',
	blocked: 'soft-red',
	done: 'soft-green',
};

const variantFor = (status: Status) => VARIANT[status];
</script>

<!-- Soft status palette — canonical source: ai/guides/design-language.md § Using color.
     Non-scoped so variant classes on the child badge receive the accents. -->
<style>
.bb-badge.bb-badge--soft-gray {
	--accent: #64748b;
}
.bb-badge.bb-badge--soft-blue {
	--accent: #2563eb;
}
.bb-badge.bb-badge--soft-green {
	--accent: #16a34a;
}
.bb-badge.bb-badge--soft-red {
	--accent: #dc2626;
}
.bb-badge.bb-badge--soft-gray,
.bb-badge.bb-badge--soft-blue,
.bb-badge.bb-badge--soft-green,
.bb-badge.bb-badge--soft-red {
	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
	--border-width: 1px;
	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
}

/* Unsaved edit: hold a deeper border until the batch is saved. */
.status-trigger--dirty {
	--border-width: 1px;
	--border-color: color-mix(in oklab, var(--color) 60%, var(--bb-panel));
}

/* While open, deepen the badge's own hue — not a generic indigo ring. */
.status-trigger--editing {
	--bg: color-mix(in oklab, var(--color) 25%, var(--bb-panel));
	--border-color: color-mix(in oklab, var(--color) 45%, var(--bb-panel));
	box-shadow: 0 0 0 var(--bb-ring-size) var(--ring);
}
</style>
```

**Why this shape and not the obvious one.** The instinct is to give each row a
provider and `enforce-coherence` so rows keep themselves honest. That inverts the
cost: coherence with a seeded model makes every row load, so the table's request
count tracks its row count, and each row can rewrite its own model from a
response you never see. The page-level array collapses all of it — one source,
one fetch, every row consistent by construction, nothing to prune because every
row already draws from the same list.

If rows genuinely need **different** option sets (per-type statuses, say),
resolve _those_ lists at page level too — one fetch per distinct set, keyed by
type — and pass the right array down. Still zero per-row requests. Reach for a
per-row provider only when the options truly depend on that row's identity and
cannot be batched, and then expect the request count to follow the row count.

Pruning stale values in a table is a **page-level** job, not a per-row one: when
the source list narrows, reconcile the rows yourself in one pass, where you can
show the user what changed (or ask them) instead of nulling values invisibly.

### Create options on the fly (`option:add`)

Pressing Enter in the search field with **no option highlighted** emits
`option:add` with the trimmed query (it can be `''`, and it won't fire if the
query already matches a selected option). The component creates nothing itself:
append the new item to `items` and select it. This is the idiomatic pattern for
closed-but-growable vocabularies — the same as `BbSelect`. The behaviour is gated
by the search field existing; `disable-writing` (which removes the field) also
disables it.

```ts
const roles = ref<string[]>(['Reviewer', 'Approver']);
const role = ref<string | null>(null);

const onAdd = (text: string) => {
	const name = text.trim();
	if (!name || roles.value.includes(name)) return;
	roles.value.push(name);
	role.value = name;
};
```

### Group options

`group-by` (a field path or a function) buckets options under headers; the
`#group` slot styles each header and receives `{ text, item, index, length,
disabled }` — `length` is the group size, `index` the list index of its first
option. Identical to `BbSelect`, anchored to your trigger.

**Roles grouped by department**

```vue
<template>
	<div
		class="flex max-w-sm items-center gap-1.5 rounded-[var(--bb-radius)] border p-2"
	>
		<span class="pr-1 text-xs font-medium text-[color:var(--bb-text-muted)]"
			>Role</span
		>
		<BbSelectPopover
			v-model="role"
			compact
			group-by="department"
			item-text="label"
			item-value="value"
			:items="roles"
			width="240px"
		>
			<template #activator="{ props }">
				<BbBadge
					append:icon="lucide:chevron-down"
					prepend:icon="lucide:briefcase"
					size="lg"
					variant="outline"
				>
					<BbBadgeButton v-bind="props">{{
						roleLabel || 'Assign role'
					}}</BbBadgeButton>
				</BbBadge>
			</template>
			<template #group="{ text, length }">
				<div
					class="flex items-center justify-between px-2 text-xs font-medium text-[color:var(--bb-text-muted)]"
				>
					<span>{{ text }}</span>
					<span>{{ length }}</span>
				</div>
			</template>
		</BbSelectPopover>
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';

type Role = { label: string; value: string; department: string };

const roles: Role[] = [
	{ label: 'Analyst', value: 'mkt-analyst', department: 'Marketing' },
	{ label: 'Manager', value: 'mkt-manager', department: 'Marketing' },
	{ label: 'Frontend', value: 'eng-fe', department: 'Engineering' },
	{ label: 'Backend', value: 'eng-be', department: 'Engineering' },
];

const role = ref<string | null>(null);
const roleLabel = computed(
	() => roles.find((r) => r.value === role.value)?.label ?? ''
);
</script>
```

### Panel header, footer and empty/loading states

`#header` and `#footer` pin content above the search field and below the options
list, in **both** the desktop popover and the mobile adaptive sheet. Both receive
`{ close, clear, focus, query, selectedOptions }` — ideal for a title and a
"Done" action. Two more panel slots cover async states: `#loading` and
`#no-data` (both receive `{ query }`; `#no-data` also a `focus()` callback), or
their string equivalents `loading-text` / `no-data-text`.

**A titled panel with a done action**

```vue
<template>
	<div
		class="flex max-w-sm items-center gap-1.5 rounded-[var(--bb-radius)] border p-2"
	>
		<span class="pr-1 text-xs font-medium text-[color:var(--bb-text-muted)]"
			>Destination</span
		>
		<BbSelectPopover
			v-model="city"
			compact
			item-text="label"
			item-value="value"
			:items="cities"
			width="240px"
		>
			<template #activator="{ props }">
				<BbBadge
					append:icon="lucide:chevron-down"
					prepend:icon="lucide:map-pin"
					size="lg"
					variant="outline"
				>
					<BbBadgeButton v-bind="props">{{
						cityLabel || 'Add destination'
					}}</BbBadgeButton>
				</BbBadge>
			</template>
			<template #header>
				<span class="text-sm font-medium">Popular destinations</span>
			</template>
			<template #footer="{ close, clear }">
				<div class="flex w-full items-center gap-2">
					<BbButton class="mr-auto" variant="ghost" @click="clear"
						>Clear</BbButton
					>
					<BbButton variant="primary" @click="close">Done</BbButton>
				</div>
			</template>
		</BbSelectPopover>
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbBadge, BbBadgeButton, BbButton, BbSelectPopover } from 'bitboss-ui';

type City = { label: string; value: string };

const cities: City[] = [
	{ label: 'Amsterdam', value: 'ams' },
	{ label: 'Berlin', value: 'ber' },
	{ label: 'Lisbon', value: 'lis' },
	{ label: 'Milan', value: 'mil' },
];

const city = ref<string | null>(null);
const cityLabel = computed(
	() => cities.find((c) => c.value === city.value)?.label ?? ''
);
</script>
```

### Search field and filtering

The panel carries a search field (role `searchbox`). Filtering follows the shared
semantics (Options/Fetch playbooks): array items filter locally by
case-insensitive **substring** against the display text; `filter-by: ['path', …]`
searches the listed paths **instead of** the text (every path must exist on every
item or matching throws); with a provider, the local substring filter **still
applies on top of** the response, so keep server matches substring-compatible.

`disable-writing` removes the search field entirely — `true` everywhere, or
`'mobile'` / `'desktop'` to drop it on one platform only. It is also the
supported way to disable typing/filtering (and, with it, `option:add`); use it
when the option list is short enough to just scroll.

**Scroll-only status pill**

```vue
<template>
	<div
		class="flex max-w-sm items-center gap-1.5 rounded-[var(--bb-radius)] border p-2"
	>
		<span class="pr-1 text-xs font-medium text-[color:var(--bb-text-muted)]"
			>Status</span
		>
		<BbSelectPopover
			v-model="status"
			compact
			disable-writing
			:items="statuses"
			width="200px"
		>
			<template #activator="{ props, shown }">
				<BbBadge
					append:icon="lucide:chevron-down"
					:class="{ 'status-trigger--editing': shown }"
					size="lg"
					:variant="variantFor(status)"
				>
					<BbBadgeButton v-bind="props">{{
						status ?? 'Set status'
					}}</BbBadgeButton>
				</BbBadge>
			</template>
		</BbSelectPopover>
	</div>
</template>
<script setup lang="ts">
import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
import type { BadgeVariantType } from 'bitboss-ui';
import { ref } from 'vue';

const statuses = ['Draft', 'In review', 'Approved', 'Published'];
type Status = (typeof statuses)[number];

const status = ref<Status | null>(null);

const VARIANT: Record<Status, BadgeVariantType> = {
	Draft: 'soft-gray',
	'In review': 'soft-amber',
	Approved: 'soft-blue',
	Published: 'soft-green',
};

const variantFor = (value: Status | null): BadgeVariantType =>
	value ? VARIANT[value] : 'outline';
</script>

<!-- Soft status palette — canonical source: ai/guides/design-language.md § Using color. -->
<style>
.bb-badge.bb-badge--soft-gray {
	--accent: #64748b;
}
.bb-badge.bb-badge--soft-blue {
	--accent: #2563eb;
}
.bb-badge.bb-badge--soft-green {
	--accent: #16a34a;
}
.bb-badge.bb-badge--soft-amber {
	--accent: #d97706;
}
.bb-badge.bb-badge--soft-gray,
.bb-badge.bb-badge--soft-blue,
.bb-badge.bb-badge--soft-green,
.bb-badge.bb-badge--soft-amber {
	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
	--border-width: 1px;
	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
}

.status-trigger--editing {
	--bg: color-mix(in oklab, var(--color) 25%, var(--bb-panel));
	--border-color: color-mix(in oklab, var(--color) 45%, var(--bb-panel));
	box-shadow: 0 0 0 var(--bb-ring-size) var(--ring);
}
</style>
```

### Sizing and layout

- `width` sets the popover width — a number (px) or a CSS string (`'240px'`,
  `'100%'`). Unlike `BbSelect` (whose panel always matches the control), here the
  trigger and panel are independent, so **give the panel a coherent number**. The
  default is `200` (px) — right for a form-field-shaped picker. For a
  **status/enum chip trigger** (a small badge in a table cell or filter rail),
  `200` is a touch wide for a handful of short labels: pass a small explicit width
  (`160`–`180`) to match the chip. Reserve `200`+ for pickers with long labels or
  a search box.
- **Avoid `width="auto"`.** It does not shrink-to-content the way it reads:
  because the panel is a fixed-positioned floating element, CSS `width: auto`
  resolves against the viewport as the containing block and blows the panel out
  to ~100% of the page. Always give a number (or `'100%'` to match the trigger
  deliberately) — never `'auto'`.
- **Set `width` explicitly on every compact trigger.** The 200px default is
  sized for a form field, so a `compact` picker hanging off a chip or a table
  cell looks like a panel that lost its field. This is a defaults mismatch, not
  a bug — the default cannot know what the trigger is — so the rule is: if the
  trigger is not field-shaped, pass a number. (Ruled PG-017, 2026-08-07:
  document, do not change the default.)
- `compact` applies the dense density variant (24px options, 24px group headers).
- `item-height` / `header-height` tune the virtualized row heights when you use
  taller custom `#option` / `#group` markup.
- Placement props mirror the palette/dropdown float: `placement`, `offset`
  (default 4), `padding`, `boundary`, `disable-flip`, `transition-duration`. The
  panel is a frame, not a bubble — it never shows an arrow.

### Adaptive mobile sheet

With `adaptive` (default: global `config.adaptive`, which is `true`), the panel
opens as a bottom off-canvas sheet on mobile viewports (below
`config.mobileMaxWidth`) instead of a floating popover — same search, options and
`#header`/`#footer` slots, plus a representation of the current selection between
them. The surface is **latched per open cycle**: a mid-open resize never swaps
popover ↔ sheet. `off-canvas-props` forwards extra `BbOffCanvas` props to the
sheet (`size`, `draggable`, `fullscreen`, `stack`); `:adaptive="false"` keeps a
floating popover everywhere.

### Events and v-model

- `update:modelValue` — the resolved value (single) or array (multiple), on pick,
  `clear`, coherence enforcement, and — in `multiple` mode only — deselect.
  A second click on the current option in single mode emits nothing.
- `option:add` — Enter on a non-matching query with nothing highlighted (above).
- `focus` / `blur` — the activator gaining/losing focus.
- `input` / `change` — native events from the panel search field.
- `click` — the activator was clicked.
- `inactive` — focus has fully left the component (**trigger and panel**). Because
  focus legitimately moves into the panel while open, validate/react on
  `inactive`, not on `blur`.

### Config and platform

- **No teleport** — the popover renders **in the component's own subtree** (it is
  not portalled to `<body>`), so it inherits your CSS context and is directly
  queryable (handy for tests: the open panel is `.bb-listbox--open` on the same
  root, no portal hop).
- **Global config** — `config.adaptive` (default for `adaptive`),
  `config.mobileMaxWidth` (the mobile threshold), `config.locale` (the search
  field's default accessible name and panel string defaults).
- **SSR / Nuxt** — `prefill: true` providers also run in `onServerPrefetch`, so
  server-rendered pages hydrate with options loaded; keep providers isomorphic
  (no `window` access).

### Works well with

- `BbSelect` — the same engine as a labelled form field; swap when the trigger
  should be an inline input with hint/error states.
- `BbTable` — popover triggers as inline-edit cells or toolbar filters; list
  their models in the table provider's `dependencies`.
- `BbButton` — the natural activator (it forwards `props` and exposes a
  `loading` state to reflect fetches).
- `useToast` — surface provider failures the component only logs.

### Gotchas and constraints

- `multiple` with a non-array model **throws at setup** — seed `ref([])`.
- A seeded model shows **no trigger `text`** until the first load (no eager
  prefill upgrade, by design) — resolve the label from your own state. Array
  `items` resolve on mount, so this only bites providers.
- The local substring filter also applies to provider results — server matches
  whose text doesn't contain the query are hidden.
- `filter-by` is `string[]` only and matches exactly those paths; each must exist
  on every item or matching throws.
- `prefill: false` is search-first: opening fetches nothing and the panel shows
  the "search to begin" hint until the user types. It quietly falls back to
  loading on open when writing is disabled, the model is non-empty, or `items` is
  an array.
- `enforce-coherence` + a provider that drops the selection on component-initiated
  (`prefill === true`) calls = wiped model — and since the check now runs on the
  **first** load, that wipe happens at mount rather than later. Resolve the
  current selection in those responses, or enable `stash`.
- `enforce-coherence` opts **each instance** into its own load. One field, one
  request; N provider-backed rows, N requests.
- `option:add` can fire with an empty string — trim and guard.
- **Clicking the selected option does not clear a single select** — it re-picks
  it and closes the panel. Emptying is the `clear` callback (activator/panel
  slot scope), never an accidental second click. Multiple mode still toggles.
- **`null` as a real "All" option** works — it resolves and renders as the
  selection — but it overloads the value the component uses for _nothing
  selected_. So a `null` model stays lazy (nothing to resolve, no load, not even
  with `enforce-coherence`), `clear` is indistinguishable from picking "All", and
  an `enforce-coherence` prune emits `null` — i.e. a stale value **widens to
  "All"** rather than clearing. Fine if you want it; use a sentinel
  (`'all'`) if "everything" and "nothing" must stay distinct.

### Anti-patterns

- Reading `text` (or `selectedOptions`) for the trigger label instead of
  computing it from your own state — with a provider they are empty until the
  first load, so the trigger's appearance ends up depending on whether the panel
  was ever opened.
- Binding many instances to **one shared ref**: each judges the same value against
  its own options and every instance that disagrees emits `null`, so the user's
  pick is overwritten by its neighbours. One model per row.
- Giving every table row its own **provider**: N rows becomes N requests. Resolve
  the options once at page level and pass the same array down.
- Reaching for `prefill: true` to populate a trigger label.
- Rebuilding chips, counts or select-all in wrapper markup when `max`,
  `selectedOptions` and the panel slots cover it.
- Hand-rolled debounce/loading refs around the provider.
- `watch(filter, refetch)` when `dependencies` exists; blind `model = null`
  resets when `enforce-coherence` would preserve still-valid values.
- Using it where an inline labelled field is wanted (that's `BbSelect`), or for a
  static three-option choice (that's `BbRadioGroup`).
- Shipping a text-labelled activator with no `aria-label` and relying on the
  component's generic fallback name — `role="combobox"` means the visible
  text is read as the value, not the name, so a "labelled" trigger falls back
  to a generic "Select an option" name rather than saying what it actually
  picks (see Accessibility below).

### Accessibility

- The component puts `role="combobox"` on the slot activator, and `combobox`
  is **not** in ARIA's name-from-content set — visible button text is read as
  the current _value_, never the accessible _name_. That makes an explicit
  name mandatory on **every** activator, not just icon-only ones: a
  `<BbButton>Status</BbButton>` trigger with no `aria-label` announces as an
  unlabelled combobox, and the word "Status" is heard as if it were the
  selection. Give every activator an `aria-label` (or `aria-labelledby`) that
  names what it picks, independent of its visible text:
- **The component also supplies a fallback name automatically (BTG-013).** If
  the activator has no `aria-label`/`aria-labelledby` of its own, the
  component sets a localized generic one (`select.triggerLabel`, "Select an
  option") so the role is never left completely nameless — a forgotten label
  still ships an _accessible_, if generic, combobox. An `aria-label` or
  `aria-labelledby` you set yourself is always left untouched. The fallback is
  a safety net, not a substitute for a real one: it cannot say what the field
  picks, so still label every activator explicitly for a meaningful name.

  ```vue
  <template #activator="{ props }">
  	<BbBadge append:icon="lucide:chevron-down" variant="outline">
  		<BbBadgeButton aria-label="Filter by status" v-bind="props">
  			{{ statusLabel }}
  		</BbBadgeButton>
  	</BbBadge>
  </template>
  ```

  Keep the accessible name's wording distinct enough from the visible text
  that voice-control users can still target the visible words (WCAG 2.5.3
  Label in Name) — `aria-label="Filter by status"` over visible `Status · 2`
  is fine; `aria-label="Status"` over visible `Select a status…` is not,
  because "Select a status" no longer appears in the name.

- Make the activator a real focusable element (a `<button>` or `BbButton`).
- The in-panel search field is labelled by `search-input-aria-label` (defaults to
  "Search options"); override it to match your domain.
- The component manages listbox roles, `aria-activedescendant`, the full keyboard
  model and focus return to the trigger on close — do not reimplement them.
- Because the trigger is yours, reflect the open state visually (the `shown` slot
  prop) so keyboard and low-vision users can see the popover is expanded.

## v-model

- `v-model` — type: `any`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activator` | `Record<string, any> \| HTMLElement \| null \| undefined` |  |  | External activator element or component ref. When provided, the activator slot is not rendered and event listeners are attached programmatically to the referenced element. |
| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | When `true`, the panel opens as a bottom off-canvas sheet on mobile viewports instead of a floating popover; on desktop it stays a popover. The sheet reuses the same search field and options list, adding a representation of the current sele… |
| `anchor` | `Record<string, any> \| HTMLElement \| null \| undefined` | `null` |  | Override the element used for popover positioning and width measurement. Useful when the focusable activator is narrower than its visual container (e.g. a button inside a wrapper). Falls back to `activatorEl` when omitted. |
| `ariaDescribedby` | `string \| string[] \| undefined` |  |  | Space-separated IDREF(s) that describe this field for assistive technologies. Accepts either a string or array of ids. |
| `ariaInvalid` | `boolean \| undefined` | `undefined` |  | Explicit invalid state for accessibility semantics. Falls back to `hasErrors` when not provided. |
| `autocomplete` | `string \| undefined` | `"off"` |  | Browser autocomplete hint for the popover search input. |
| `boundary` | `string \| Record<string, any> \| HTMLElement \| null \| undefined` |  |  | Constrains the popover to a specific boundary element. |
| `clearable` | `boolean \| undefined` | `false` |  | Shows a clear button inside the search field's icon stack: it takes the lens' place on hover/focus while there is a query or selection to clear, and resets both. Off by default. Leave it off when the component is wrapped by a control that a… |
| `compact` | `boolean \| undefined` | `false` |  | Apply the compact density variant. |
| `dependencies` | `unknown[] \| undefined` | `[]` |  | Additional dependencies that trigger item reloading when changed. |
| `depsDebounceTime` | `number \| undefined` | `0` |  | Debounce delay (ms) for dependency-triggered reloads. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
| `disableFlip` | `boolean \| undefined` | `false` |  | Disables the automatic flip to the opposite side when the popover would overflow (flipping is on by default). |
| `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` | `false` |  | Controls whether the search input is shown inside the popover panel. Use `'mobile'` to hide the search input on mobile, `'desktop'` to hide it on desktop. |
| `enforceCoherence` | `boolean \| undefined` | `false` |  | Reset modelValue to `null` or empty array if it no longer matches available items. |
| `filterBy` | `string[] \| undefined` | `[]` |  | Property paths used to filter options when the user types in the search input. When empty (default) options are matched against their display text. When non-empty the provided paths are searched instead of the display text. To disable filte… |
| `groupBy` | `string \| ((item: Item) => string \| number \| symbol) \| undefined` |  |  | Path to item property for grouping options. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Marks the component as being in error state. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Marks the component as being in a warning state. Visually mirrors `hasErrors` but uses `--bb-warn` chrome; errors take priority when both are set. |
| `headerHeight` | `number \| undefined` |  |  | Height of group headers in the listbox (px). Defaults to 32px (24px compact; 36px / 32px on mobile viewports). Only applies when `groupBy` is set. An explicit value wins on every viewport. |
| `id` | `string \| undefined` |  |  | Explicit id for the component. Used to generate ids for listbox and options. |
| `itemHeight` | `number \| undefined` | `28` |  | Height of the options in the listbox (px). Defaults to 28px (24px compact; 44px / 36px on mobile viewports). An explicit value wins on every viewport. |
| `items` | `Item[] \| ((query: string, prefill: boolean, modelValue: any) => Promise<Item[]>) \| ((query: string, prefill: boolean, modelValue: any) => Item[])` | `[]` | yes | Array of items or function to load them asynchronously. Functions receive `(query, prefill, modelValue)` and can return a promise. `modelValue` is the raw v-model: an array in `multiple` mode, the raw model value (possibly `null`) in single… |
| `itemText` | `ItemAccessor<Item, string> \| undefined` |  |  | Path to item property for display text or function to extract it. |
| `itemValue` | `ItemAccessor<Item> \| undefined` |  |  | Path to item property for value or function to extract it. |
| `loading` | `boolean \| undefined` | `false` |  | Display the loading state styles. |
| `loadingText` | `string \| undefined` |  |  | Message shown while items are being loaded. |
| `max` | `number \| undefined` | `Infinity` |  | Maximum number of selectable items (limits selection when `multiple` is true). |
| `modelValue` | `any` |  | yes | v-model value. Single value for single select, array for multiple select. |
| `modelValueDebounceTime` | `number \| undefined` | `0` |  | Debounce delay (ms) for modelValue change handling. |
| `multiple` | `boolean \| undefined` | `false` |  | Enable multiple item selection. When true, modelValue must be an array. |
| `noDataText` | `string \| undefined` |  |  | Message displayed when no items are available. |
| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile (e.g. `size`, `draggable`, `fullscreen`, `stack`). |
| `offset` | `number \| undefined` | `4` |  | Distance (px) between the activator and the popover. |
| `padding` | `number \| undefined` | `10` |  | Minimum page padding used by floating shift middleware. |
| `placement` | `Placement \| undefined` | `"bottom"` |  | Floating placement of the popover. |
| `prefill` | `boolean \| "interaction" \| undefined` | `"interaction"` |  | Controls when items are pre-loaded. `'interaction'` loads on the first user interaction (opening the popover), `true` loads immediately on mount (and during SSR via `onServerPrefetch`), `false` is *search-first*: nothing is fetched until th… |
| `queryDebounceTime` | `number \| undefined` | `500` |  | Debounce delay (ms) before triggering search queries after user input stops. |
| `readonly` | `boolean \| undefined` | `false` |  | Prevents opening the popover while keeping the activator accessible. |
| `searchInputAriaLabel` | `string \| undefined` | ``t('select.searchLabel')` (`'Search options'`)` |  | Accessible label used by the search input rendered inside the popover. Falls back to the localized `select.searchLabel` key when omitted. |
| `selectable` | `boolean \| ((item: Item) => boolean) \| undefined` | `true` |  | Defines whether options are selectable. Can be a global boolean that affects all options or a function that accepts an item and returns a boolean that only affects that item. Non-selectable options are rendered disabled. |
| `stash` | `boolean \| undefined` | `false` |  | Accumulate selected items across searches instead of replacing them. |
| `transitionDuration` | `number \| undefined` | `250` |  | Transition duration (ms) for popover show/hide animations. |
| `width` | `string \| number \| undefined` | `"200"` |  | Width of the popover in pixels, percentage, or `'auto'`. A bare number is read as pixels — the default is the string `'200'`, not the number `200`. |

## Events

- `active` — `(e: "active"): void` — Emitted when the component becomes active (focus enters it).
- `blur` — `(e: "blur", event: FocusEvent): void` — Emitted when the activator loses focus.
- `change` — `(e: "change", event: Event): void` — Emitted when the value changes via native change event.
- `click` — `(e: "click", event: MouseEvent): void` — Emitted when the activator is clicked.
- `focus` — `(e: "focus", event: FocusEvent): void` — Emitted when the activator receives focus.
- `inactive` — `(e: "inactive"): void` — Emitted when focus moves outside the entire component after it was active.
- `input` — `(e: "input", event: Event): void` — Emitted on native input events from the search input.
- `option:add` — `(e: "option:add", text: string): void` — Emitted when the user types a new value and confirms it (Enter key) while writing is enabled (i.e. `disableWriting` does not suppress the search input for the current surface).
- `update:modelValue` — `(e: "update:modelValue", value: any): void` — Emitted with the next selection value whenever selection changes.

## Slots

- `activator` — scope: `BbSelectPopoverActivatorSlotProps` — Replaces the default trigger element that opens the select popover.
- `footer` — scope: `BbSelectPopoverPanelSlotProps` — Content pinned to the bottom of the panel, below the options list. Rendered in both the desktop popover and the adaptive sheet.
- `group` — scope: `BbSelectPopoverGroupSlotProps<Item>` — Replaces the default group header rendered above grouped options.
- `header` — scope: `BbSelectPopoverPanelSlotProps` — Content pinned to the top of the panel, above the search field. Rendered in both the desktop popover and the adaptive sheet.
- `loading` — scope: `{ query: string; }` — Content shown inside the options dropdown while items are loading.
- `no-data` — scope: `{ query: string; focus: () => void; }` — Content shown when no options match the query or the list is empty.
- `option` — scope: `BbSelectPopoverOptionSlotProps<Item>` — Replaces the default rendering of each option row in the dropdown.

## See Also

- [BbSelect](./BbSelect.md) — Selects one or many options from structured data.
- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements.

---

<!-- dist/ai/BbSlider.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbSlider.md -->

# BbSlider

## Agent Contract

- Safety level: **Consumer API**
- Group: **Selection**
- Description: Selects numeric values across a bounded range.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbSlider.md](./source/BbSlider.md)

## Usage & Guidelines

### When to use

Use `BbSlider` when the value lives in a known interval and the _position_
carries meaning: volume, brightness, opacity, a price filter. The trade-off is
precision — a slider is for "about here", not exact entry.

- Need an exact number typed in? Use `BbNumberInput`.
- Rating a few discrete points (1–5 stars, a score)? Use `BbRating`.
- Bounded interval, approximate, visual? `BbSlider`.

Always give it a real interval: set `min`, `max`, and a `step` that matches the
resolution you want. The slider has **no built-in numeric read-out** — the thumb
shows position, not a number — so pair it with a live value display (or the
`thumb` slot below) whenever the exact figure matters.

### A single value

Bind a number with `v-model`. The label sits above the track; add a live readout
so the current number is legible.

**Volume**

```vue
<div class="w-full max-w-sm">
	<BbSlider v-model="state.volume" label="Volume" :min="0" :max="100" :step="5" />
	<p class="text-sm text-[color:var(--bb-text-muted)]">{{ state.volume ?? 0 }}%</p>
</div>
```

Besides `update:modelValue` the slider re-emits interaction events (`active`,
`inactive`, `focus`, `keydown`, `pointerdown`, `pointermove`, `pointerup`) —
use them for analytics or "commit on release" patterns, never to derive the
value: the value is what `v-model` gives you.

### Range mode

Set `range` and bind a **two-element array** to select an interval between two
thumbs — the canonical "price from–to" filter. In range mode `modelValue` must
be an array; passing a scalar throws at mount. The component keeps the pair
sorted for you and assigns each incoming value to the nearer thumb, so you never
have to reason about which handle is which.

**Price range filter**

```vue
<template>
	<div
		class="flex w-full max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-4"
	>
		<div class="flex items-baseline justify-between gap-2">
			<p class="text-sm font-medium">Price</p>
			<p
				class="text-xs tabular-nums text-[color:var(--bb-text-muted)]"
				data-testid="range"
			>
				€{{ price[0] }} – €{{ price[1] }}
			</p>
		</div>
		<BbSlider
			v-model="price"
			hide-label
			label="Price range"
			:max="1000"
			:min="0"
			range
			:step="50"
		/>
		<p class="text-xs text-[color:var(--bb-text-muted)]">
			324 stays in this range
		</p>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSlider } from 'bitboss-ui';

const price = ref<[number, number]>([200, 800]);
</script>
```

### Min, max and step

`min`/`max` bound the interval (defaults `0`–`100`) and `step` sets the
granularity every value snaps to (default `1`). These are validated at mount and
throw on nonsense input, so treat them as hard invariants:

- `max` must be strictly greater than `min` (else `RangeError`).
- `step` must be a finite number greater than `0` (else `RangeError`).
- `min`/`max` must be finite and within safe-integer range.

Fractional steps work — emitted values are rounded to **`max-precision`
decimal places** (default `2`) to avoid floating-point dust like
`10.000000000000002`. For steps finer than `0.01`, raise `max-precision` to
match the step's resolution (e.g. `:step="0.001"` needs
`:max-precision="3"`), otherwise the extra digits are rounded away.

**Fractional step**

```vue
<div class="w-full max-w-sm">
	<BbSlider v-model="state.opacity" label="Layer opacity" :min="0" :max="1" :step="0.05" />
	<p class="text-sm text-[color:var(--bb-text-muted)]">{{ (state.opacity ?? 0).toFixed(2) }}</p>
</div>
```

### Stepper controls

The `prepend` and `append` slots receive `increase` / `decrease` callbacks that
nudge the value by one `step`. Wrap them in `BbButton`s for an accessible
±stepper around the track — no manual math, the slider clamps to `min`/`max`
for you. These callbacks are **single-value only**; they are inert in `range`
mode (they early-return), so don't build a stepper around a range slider.

**Volume with ± buttons**

```vue
<template>
	<div
		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
	>
		<div class="flex items-baseline justify-between gap-2">
			<div>
				<p class="text-sm font-medium">Playback volume</p>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					Speaker · MacBook Pro
				</p>
			</div>
			<p
				class="text-xs tabular-nums text-[color:var(--bb-text-muted)]"
				data-testid="value"
			>
				{{ volume }}%
			</p>
		</div>
		<BbSlider
			v-model="volume"
			hide-label
			label="Playback volume"
			:max="100"
			:min="0"
			:step="10"
		>
			<template #prepend="{ decrease }">
				<BbButton
					aria-label="Quieter"
					icon="lucide:minus"
					size="xs"
					variant="ghost"
					@click="decrease"
				/>
			</template>
			<template #append="{ increase }">
				<BbButton
					aria-label="Louder"
					icon="lucide:plus"
					size="xs"
					variant="ghost"
					@click="increase"
				/>
			</template>
		</BbSlider>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbSlider } from 'bitboss-ui';

const volume = ref(40);
</script>
```

### Discrete steps with ticks

`ticks` lays out one evenly-spaced slot per step. **You draw the mark**: the
library positions the tick elements but ships no default notch —
`.bb-base-slider__tick` carries only `position: relative`, and the `tick` slot
has no fallback content, so `ticks` on its own renders empty spans and looks
like nothing happened. Fill the `tick` slot (`{ value, percent, active }`) with
your notch or per-step label, or style `.bb-base-slider__tick` yourself.

Add `disable-thumb-translate` so the thumb sits exactly over each tick instead
of being nudged to stay centred — the two pair naturally when you want a
stepped, notched slider.

**Stepped slider with ticks**

```vue
<div class="w-full max-w-sm">
	<BbSlider
		v-model="state.priority"
		label="Priority"
		:min="1"
		:max="5"
		:step="1"
		ticks
		disable-thumb-translate
	/>
</div>
```

### Keyboard model

Each thumb is a real `role="slider"` handle in the tab order, and moves the
value from the keyboard when focused:

- **Arrow Right / Arrow Up** — increase by one `step`.
- **Arrow Left / Arrow Down** — decrease by one `step`.
- **Page Up / Page Down** — jump by ten steps.
- **Home / End** — snap to `min` / `max`.

In range mode the keys drive whichever thumb has focus. Every keystroke emits
`update:modelValue`, so keyboard and pointer produce identical, clamped values —
never wire your own key handlers on top.

### Displaying the value on the thumb

Because there is no built-in tooltip, use the `thumb` slot to render the current
value on the handle itself. The slot gives you `{ value, percent, focused }`; its
content renders inside the thumb, so you augment the handle rather than replacing
it. (Use `thumb:lower` / `thumb:higher` to target one handle of a range.)

**Value bubble on the thumb**

```vue
<template>
	<div class="w-full max-w-sm pt-8">
		<BbSlider v-model="zoom" label="Zoom" :max="200" :min="0" :step="10">
			<template #thumb="{ value, focused }">
				<span
					class="absolute -top-7 left-1/2 -translate-x-1/2 rounded-[var(--bb-radius-sm)] bg-[var(--bb-primary)] px-1.5 py-0.5 text-xs text-[var(--bb-primary-fg)] transition-opacity"
					:class="focused ? 'opacity-100' : 'opacity-0'"
					>{{ value ?? 0 }}%</span
				>
			</template>
		</BbSlider>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSlider } from 'bitboss-ui';

const zoom = ref(80);
</script>
```

### Pair with exact entry

When the figure is consequential — a billing cap, a quota — the slider gives the
feel of the interval and a `BbNumberInput` bound to the **same ref** gives exact
entry. No sync code is needed: both components drive the one value, and the
slider clamps and snaps whatever the field emits.

**Monthly spend limit**

```vue
<template>
	<div
		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
	>
		<div class="flex items-baseline justify-between gap-2">
			<div>
				<p class="text-sm font-medium">Monthly spend limit</p>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					API usage pauses once the cap is reached.
				</p>
			</div>
			<p class="text-sm font-medium tabular-nums">€{{ limit ?? 0 }}</p>
		</div>
		<BbSlider
			v-model="limit"
			compact
			hide-label
			label="Monthly spend limit"
			:max="500"
			:min="0"
			:step="25"
		/>
		<BbNumberInput
			v-model="limit"
			compact
			hide-label
			label="Monthly spend limit, exact amount"
			:max="500"
			:max-precision="0"
			:min="0"
			:step="25"
		>
			<template #prefix>€</template>
			<template #suffix>/ mo</template>
		</BbNumberInput>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbNumberInput, BbSlider } from 'bitboss-ui';

const limit = ref<number | null>(200);
</script>
```

### Label modes, layout and density

- `label` is required and names the slider; `hide-label` keeps it for assistive
  tech only.
- `label-mode` is `'outside'` (default) or `'inside'`. `'floating'` is **not
  supported** — a slider has no empty/filled state for the label to float
  against — and it is no longer in the type, so a typed template cannot write
  it. It does not throw: an explicit `'floating'` from untyped code warns in
  dev and falls back to `'outside'` (`resolveEnumProp`, the library-wide policy
  that a bad enum token is cosmetic, never fatal). A plugin-level
  `defaultInputLabelMode: 'floating'` degrades to `'outside'` **silently** —
  the consumer made no per-slider choice, so there is nothing to warn about.
- `direction` (`'horizontal'`, `'vertical'`, `'auto'`, or a pattern like
  `'xx xxxxxx'`), `reverse`, and `label-position` arrange the label against the
  track, exactly as on the other inputs.
- `compact` applies the denser variant for toolbars and settings rows.

**Inside label mode**

```vue
<div class="w-full max-w-sm">
	<BbSlider
		v-model="state.contrast"
		label="Contrast"
		label-mode="inside"
		:min="0"
		:max="100"
		:step="1"
	/>
</div>
```

In a dense settings panel set `compact` on every slider in the group — density
is a screen-level decision, not a per-control one.

**Compact display settings**

```vue
<template>
	<div
		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
	>
		<div>
			<p class="text-sm font-medium">Display</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Applies to this display only.
			</p>
		</div>
		<div class="flex flex-col gap-1">
			<BbSlider
				v-model="brightness"
				compact
				label="Brightness"
				:max="100"
				:min="0"
				:step="5"
			/>
			<p
				class="text-xs tabular-nums text-[color:var(--bb-text-muted)]"
				data-testid="brightness"
			>
				{{ brightness }}%
			</p>
		</div>
		<div class="flex flex-col gap-1">
			<BbSlider
				v-model="warmth"
				compact
				label="Night light"
				:max="100"
				:min="0"
				:step="5"
			/>
			<p
				class="text-xs tabular-nums text-[color:var(--bb-text-muted)]"
				data-testid="warmth"
			>
				{{ warmth }}%
			</p>
		</div>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSlider } from 'bitboss-ui';

const brightness = ref(80);
const warmth = ref(20);
</script>
```

### Disabled, readonly and errors

- `disabled` removes the thumb from the tab order and greys the track; pointer
  and keyboard are inert.
- `readonly` shows a fixed value that can still be focused and exposes
  `aria-readonly` — prefer it, with a nearby explanation, for values the user may
  inspect but not change.
- `errors` (string or array) renders messages below the track and `has-errors`
  toggles error styling alone — rare for a bounded slider, but available when a
  value is rejected by validation.

### Config, platform and pairings

No plugin options change `BbSlider` behaviour (no i18n strings, no teleport, no
variant registry) and it renders SSR-safe static markup in Nuxt and Inertia
apps. A hidden text input carries the JSON-serialized value under `name` for
classic form posts.

Works well with:

- `BbButton` — as the ± stepper via the `prepend`/`append` callbacks.
- `BbNumberInput` — a paired exact-entry field for the same value.
- `useToast` — confirm a committed change on `inactive` (drag release).

### Gotchas and anti-patterns

- Don't bind a scalar with `range` — that one throws at mount
  (`BbBaseSlider.vue:249`). The mirror case is worse because it is **quiet**:
  an array **without** `range` renders a single thumb and silently reads
  `head()`, so the second value is dropped with no warning. Keep the mode and
  the `modelValue` shape in step in both directions.
- Don't expect `increase`/`decrease` to work in range mode; they are single-value
  only. Drive range thumbs with the keyboard or pointer.
- Don't set `label-mode="floating"` — it is not in the type, and at runtime it
  warns and falls back to `'outside'`. Use `'outside'` or `'inside'`.
- Don't rely on a slider for exact numbers — steps finer than `0.01` round away
  unless you raise `max-precision` to match. Use `BbNumberInput` when the
  precise figure is the point.
- Don't add your own value read-out via `@pointermove`/`@keydown` math — read
  `v-model` (or use the `thumb` slot), which already delivers the clamped value.

### Accessibility

- Always provide a `label` — it is the slider's accessible name: each thumb
  references it via `aria-labelledby`, and in `range` mode a localized
  "minimum"/"maximum" qualifier is appended so the two thumbs are
  distinguishable to assistive tech.
- Each thumb exposes `role="slider"` with `aria-valuemin`/`aria-valuemax`/
  `aria-valuenow` automatically; do not add your own ARIA.
- `errors`, `warnings`, `description` and `hint` are all wired to each thumb through
  `aria-describedby`, in that order: the reason the field is invalid is spoken
  first when it regains focus, and a channel is referenced only while it
  actually has copy. Messages _also_ render in an `aria-live="polite"` region,
  so they are announced the moment they appear — announced on change, re-read
  on focus. Keep messages meaningful, not decorative.
- Prefer `readonly` (focusable, discoverable) with an explanation over a silent
  `disabled` for locked settings.
- Provide a visible value read-out for sighted users — the thumb position alone
  is not a precise number.

## v-model

- `v-model` — type: `number \| number[] \| null`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
| `compact` | `boolean \| undefined` | `false` |  | Set the component in compact mode. |
| `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
| `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
| `disableThumbTranslate` | `boolean \| undefined` | `false` |  | Disables the proportional thumb translation that keeps the thumb on track (enabled by default). Set it when displaying ticks so they align with less effort. |
| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `label` | `string` |  | yes | Text content of the label of the element. |
| `labelMode` | `"outside" \| "inside" \| undefined` |  |  | Label rendering mode. Sliders do not support `floating` labels. |
| `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
| `max` | `number \| undefined` |  |  | Maximum value cap. |
| `maxPrecision` | `number \| undefined` | `2` |  | Maximum decimal places to retain in emitted values. |
| `min` | `number \| undefined` |  |  | Minimum value cap. |
| `modelValue` | `number \| number[] \| null` |  | yes | Used by v-model. |
| `name` | `string \| undefined` |  |  | Defines the name of the input. |
| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
| `range` | `boolean \| undefined` | `false` |  | Set the input as range. modelValue must be an array. |
| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
| `step` | `number \| undefined` |  |  | The step attribute specifies the granularity that the value must adhere to. |
| `ticks` | `boolean \| undefined` | `false` |  | Displays ticks on step. |
| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |

## Events

- `active` — `(event: "active"): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `inactive` — `(event: "inactive"): void`
- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
- `pointerdown` — `(event: "pointerdown", event: PointerEvent): void`
- `pointermove` — `(event: "pointermove", event: PointerEvent): void`
- `pointerup` — `(event: "pointerup", event: PointerEvent): void`
- `update:modelValue` — `(event: "update:modelValue", value: number \| number[]): void`

## Slots

- `append` — scope: `BaseSliderStepSlotProps` — Content rendered after the slider track, typically used to add a max-value label or button.
- `label` — scope: `BbSliderLabelSlotProps` — Replaces the default label text rendered above the slider.
- `prepend` — scope: `BaseSliderStepSlotProps` — Content rendered before the slider track, typically used to add a min-value label or button.
- `thumb` — scope: `BaseSliderThumbSlotProps` — Fallback thumb used for non-range sliders (or inside `thumb:higher`/`thumb:lower` when not overridden separately).
- `thumb:higher` — scope: `BaseSliderThumbSlotProps` — Replaces the default higher-value thumb in range mode (`range: true`).
- `thumb:lower` — scope: `BaseSliderThumbSlotProps` — Replaces the default lower-value thumb in range mode (`range: true`).
- `tick` — scope: `BaseSliderTickSlotProps` — Replaces the default tick mark rendered at each step when ticks are enabled.

## Validated variant

Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).

| Prop | Type | Description |
| --- | --- | --- |
| `rules` | `RuleExpression<number \| number[] \| null>` | vee-validate rules for this field. |
| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |

## See Also

- [BbNumberInput](./BbNumberInput.md) — Captures and validates numeric form values, emits a number value.
- [BbRating](./BbRating.md) — Collects scalar ratings through interactive icons.

---

<!-- dist/ai/BbSmoothHeight.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbSmoothHeight.md -->

# BbSmoothHeight

## Agent Contract

- Safety level: **Consumer API**
- Group: **Layout & Utility**
- Description: Animates height transitions for dynamic content.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbSmoothHeight.md](./source/BbSmoothHeight.md)

## Usage & Guidelines

### When to use

`BbSmoothHeight` is the lowest rung of the disclosure ladder: it does one thing —
smoothly transition its own height whenever the content inside it changes size.
It has **no `v-model`, no trigger, no events, and no hide/show semantics**. You
keep owning the content; it just removes the layout jump.

Reach for it when height changes for reasons other than a simple toggle: content
swapping in a wizard step, a list gaining or losing rows, an async panel that
grows once data loads, a validation message appearing under a field.

Escalate when you actually need to _hide_ something:

- A toggle that reveals a body under a header → **`BbAccordion`**
  (`./BbAccordion.md`) — header + collapsible body, ARIA wired for you.
- A toggle you drive from your own trigger → **`BbCollapsible`**
  (`./BbCollapsible.md`) — a show/hide primitive with a boolean model.

Because the content is always mounted and measured, `BbSmoothHeight` does **not**
add `hidden`/`inert` — everything inside stays in the DOM and focusable. Use a
collapsible when hidden content must be inert.

### How it works (and why it matters)

The component wraps your content in an inner measuring element, watches that
element with an observer, and sets an explicit pixel `height` on the outer
wrapper, which CSS then transitions. Height updates are batched to one per
animation frame, and a trailing re-measure runs after `transition-duration` so
the final height always settles exactly on the content's real size. The wrapper
has `overflow: clip`, so content never spills while animating.

Practical consequences:

- The wrapper always carries a fixed inline height — don't try to stretch it
  with `height: 100%` from outside or read its height mid-animation.
- Every animated frame re-runs layout for the wrapped subtree. Cheap for cards
  and lists; see "When not to use it" for the expensive cases.

### Animating a content reveal

Wrap the region whose height changes. The default `resize` strategy puts a
`ResizeObserver` on the content box and animates the container to match — you
toggle content however you like (here a `v-if`), and the height follows. This
also catches text reflow, images loading, and window-resize-driven wrapping.

**Height follows a v-if reveal**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex items-start justify-between gap-3">
			<div class="flex flex-col gap-0.5">
				<p class="text-sm font-medium">Acme Pro</p>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					$29 / month · billed annually
				</p>
			</div>
			<BbButton
				:aria-expanded="showDetails"
				variant="outline"
				@click="showDetails = !showDetails"
			>
				{{ showDetails ? 'Hide details' : "What's included" }}
			</BbButton>
		</div>

		<BbSmoothHeight>
			<ul
				v-if="showDetails"
				class="flex flex-col gap-1.5 text-sm text-[color:var(--bb-text-muted)]"
			>
				<li v-for="perk in perks" :key="perk">{{ perk }}</li>
			</ul>
		</BbSmoothHeight>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbSmoothHeight } from 'bitboss-ui';

const showDetails = ref(false);

const perks = [
	'Unlimited projects',
	'Priority support',
	'Advanced analytics',
	'Single sign-on (SSO)',
];
</script>
```

### Swapping sections of different heights

The same wrapper handles content **replacement**, not just reveal: when a
`v-if`/`v-else` swaps one block for another (a wizard step, a form section
that depends on an earlier choice), the container glides from the old height
to the new one instead of snapping. Wrap only the region that swaps — the
controls above and the actions below stay put while the middle animates.

**Form section swap on payment method**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Billing details</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Acme Studio · next invoice Jul 31, 2026
			</p>
		</div>

		<BbRadioGroup
			v-model="method"
			compact
			input-direction="horizontal"
			item-text="label"
			item-value="id"
			:items="methods"
			legend="Payment method"
			name="payment-method"
		/>

		<BbSmoothHeight>
			<div v-if="method === 'card'" class="flex flex-col gap-3">
				<BbTextInput
					v-model="cardNumber"
					compact
					label="Card number"
					placeholder="4242 4242 4242 4242"
					prepend:icon="lucide:credit-card"
				/>
				<div class="grid grid-cols-2 gap-3">
					<BbTextInput
						v-model="expiry"
						compact
						label="Expiry"
						placeholder="08/28"
					/>
					<BbTextInput v-model="cvc" compact label="CVC" placeholder="123" />
				</div>
			</div>
			<div v-else class="flex flex-col gap-2">
				<BbTextInput
					v-model="iban"
					compact
					label="IBAN"
					placeholder="DE89 3704 0044 0532 0130 00"
				/>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					We will email a SEPA mandate to finance@acme.dev for approval.
				</p>
			</div>
		</BbSmoothHeight>

		<BbButton class="self-start" variant="primary">
			Save payment method
		</BbButton>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import {
	BbButton,
	BbRadioGroup,
	BbSmoothHeight,
	BbTextInput,
} from 'bitboss-ui';

type MethodId = 'card' | 'bank';

const methods: Array<{ id: MethodId; label: string }> = [
	{ id: 'card', label: 'Card' },
	{ id: 'bank', label: 'Bank transfer' },
];

const method = ref<MethodId>('card');

const cardNumber = ref<string | null>(null);
const expiry = ref<string | null>(null);
const cvc = ref<string | null>(null);
const iban = ref<string | null>(null);
</script>
```

### Expanding search results

Async panels are the same story with three branches instead of two: a spinner
while the query runs, the result list once it lands, an empty message when
nothing matches. Keep every branch inside one `BbSmoothHeight` and the panel
glides between their heights — short spinner row, tall result list, one-line
empty state — instead of snapping as each state swaps in. The default `resize`
strategy covers all of it, including results wrapping onto more lines.

**Expanding search results**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
	>
		<BbTextInput
			v-model="query"
			compact
			hide-label
			label="Search documentation"
			placeholder="Search documentation…"
			prepend:icon="lucide:search"
		/>

		<BbSmoothHeight>
			<div
				v-if="loading"
				class="flex items-center gap-2 px-1 py-2 text-sm text-[color:var(--bb-text-muted)]"
				role="status"
			>
				<BbSpinner size="sm" /> Searching…
			</div>
			<ul v-else-if="results.length" class="flex flex-col">
				<li
					v-for="page in results"
					:key="page.href"
					class="flex items-baseline justify-between gap-3 px-1 py-1.5 text-sm"
				>
					<a class="truncate font-medium" :href="page.href">{{ page.title }}</a>
					<span class="shrink-0 text-xs text-[color:var(--bb-text-muted)]">{{
						page.section
					}}</span>
				</li>
			</ul>
			<p
				v-else-if="query"
				class="px-1 py-2 text-sm text-[color:var(--bb-text-muted)]"
			>
				No pages match “{{ query }}”.
			</p>
		</BbSmoothHeight>
	</div>
</template>

<script setup lang="ts">
import { ref, watch, onBeforeUnmount } from 'vue';
import { BbSmoothHeight, BbSpinner, BbTextInput } from 'bitboss-ui';

type DocPage = { title: string; section: string; href: string };

const pages: DocPage[] = [
	{ title: 'Quickstart', section: 'Getting started', href: '#quickstart' },
	{ title: 'Authentication', section: 'Guides', href: '#authentication' },
	{ title: 'Webhooks', section: 'Guides', href: '#webhooks' },
	{ title: 'Rate limits', section: 'Reference', href: '#rate-limits' },
	{ title: 'Error codes', section: 'Reference', href: '#error-codes' },
	{ title: 'API keys', section: 'Reference', href: '#api-keys' },
];

const query = ref<string | null>(null);
const loading = ref(false);
const results = ref<DocPage[]>([]);

let timeoutId: ReturnType<typeof setTimeout> | null = null;

watch(query, (value) => {
	if (timeoutId !== null) {
		clearTimeout(timeoutId);
		timeoutId = null;
	}

	const term = value?.trim().toLowerCase() ?? '';
	if (!term) {
		loading.value = false;
		results.value = [];
		return;
	}

	loading.value = true;
	timeoutId = setTimeout(() => {
		results.value = pages.filter((page) =>
			`${page.title} ${page.section}`.toLowerCase().includes(term)
		);
		loading.value = false;
		timeoutId = null;
	}, 300);
});

onBeforeUnmount(() => {
	if (timeoutId !== null) {
		clearTimeout(timeoutId);
	}
});
</script>
```

### Growing and shrinking lists (mutation strategy)

When height changes because DOM nodes are **added or removed**, switch to
`strategy="mutation"`: a `MutationObserver` re-measures `scrollHeight` whenever
the DOM mutates. The default watch scope is `{ childList: true }` — **direct
children of the content element only**. Pass `mutation-options` (a standard
`MutationObserverInit`) to widen it: `{ childList: true, subtree: true }`
catches nested inserts, and you can add `attributes` or `characterData` when
class swaps or text edits drive the height.

**Mutation strategy for a dynamic list**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex items-center justify-between gap-3">
			<div class="flex flex-col gap-0.5">
				<p class="text-sm font-medium">Recent activity</p>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					Q3 launch · Acme Studio
				</p>
			</div>
			<div class="flex gap-1.5">
				<BbButton size="sm" variant="ghost" @click="removeEntry">
					Remove
				</BbButton>
				<BbButton size="sm" variant="outline" @click="addEntry">Add</BbButton>
			</div>
		</div>

		<BbSmoothHeight
			:mutation-options="{ childList: true, subtree: true }"
			strategy="mutation"
		>
			<ul class="flex flex-col divide-y">
				<li
					v-for="entry in entries"
					:key="entry.id"
					class="flex items-baseline justify-between gap-3 py-2 text-sm first:pt-0 last:pb-0"
				>
					<span>{{ entry.text }}</span>
					<span class="shrink-0 text-xs text-[color:var(--bb-text-muted)]">{{
						entry.when
					}}</span>
				</li>
			</ul>
		</BbSmoothHeight>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbSmoothHeight } from 'bitboss-ui';

type Entry = { id: number; text: string; when: string };

const feed: Array<{ text: string; when: string }> = [
	{ text: 'Jordan closed “Q3 launch”', when: '2m' },
	{ text: 'Priya commented on “Pricing page”', when: '18m' },
	{ text: 'Sam invited a new teammate', when: '1h' },
	{ text: 'Alex archived “Legacy import”', when: '3h' },
];

let nextId = 2;
const entries = ref<Entry[]>([
	{ id: 0, ...feed[0] },
	{ id: 1, ...feed[1] },
]);

const addEntry = () => {
	const item = feed[nextId % feed.length];
	entries.value = [...entries.value, { id: nextId++, ...item }];
};

const removeEntry = () => {
	entries.value = entries.value.slice(0, -1);
};
</script>
```

Rule of thumb: stay on `resize` — it covers anything that changes the measured
box, structural or not. Choose `mutation` when you need mutation-scoped control
(or want `resizeOptions`' counterpart tuning); `resize-options` likewise forwards
`ResizeObserverOptions` (e.g. `box`) to the resize path. Changing `strategy`,
options, `disabled` or `transition-duration` at runtime re-wires the observer
on the fly.

### Tag, timing and opting out

- `tag` picks the wrapper: `div` (default) or `span` when the surrounding markup
  only accepts phrasing content. The inner measuring element mirrors it, so you
  get div-in-div or span-in-span — never a block element inside an inline one.
  Both are forced to `display: block`, so a `span` animates exactly like a
  `div`. That mirroring is why the list is only those two: anything with a
  restricted content model (`<ul>`, `<p>`…) would nest invalidly inside itself.
  Wrap such an element around `BbSmoothHeight` instead of asking for it via
  `tag`.
- `transition-duration` (ms, default 250) sets the animation length; the easing
  comes from the design-token `--bb-ease`.
- `disabled` opts out entirely: the inline height is removed, overflow returns
  to visible, and layout is instant. It is reactive — flip it per instance when
  a parent already animates height. (You don't need it for reduced motion —
  that's automatic, see below.)

**Slower glide on a release checklist**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Release checklist</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				v2.4.0 · ship window Fri Jul 24
			</p>
		</div>

		<BbSmoothHeight :transition-duration="400">
			<ul class="flex flex-col gap-1.5 text-sm">
				<li>Design review signed off</li>
				<li>Ship the release notes</li>
				<li v-if="expanded" class="text-[color:var(--bb-text-muted)]">
					Notify the changelog subscribers
				</li>
			</ul>
		</BbSmoothHeight>

		<BbButton class="self-start" variant="ghost" @click="expanded = !expanded">
			{{ expanded ? 'Hide optional step' : 'Show optional step' }}
		</BbButton>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbSmoothHeight, BbButton } from 'bitboss-ui';

// A longer 400ms transition makes the height glide read clearly as the
// final release-checklist step appears and disappears.
const expanded = ref(false);
</script>
```

### When NOT to use it

- **Continuously resizing content** — a textarea being typed into, streaming
  chat output, anything animating inside: the height transition re-runs layout
  every frame, permanently.
- **Large or expensive subtrees** — virtualized tables (`BbTable` with
  `virtual`), long feeds: per-frame layout of a huge subtree janks. Animate a
  small wrapper near the change instead of the whole page section.
- **Inside `BbCollapsible`/`BbAccordion` content** — they already animate
  height; nesting a second height animation causes double-easing and fighting
  measurements.
- **When the content must be hidden** — this component never hides anything;
  use the collapsible rungs.
- `strategy="mutation"` with `subtree: true` on a large tree observes every
  descendant — keep the wrapped region small.

### Works well with

- `BbTextInput`/form fields — wrap the field + its error region so validation
  messages push content smoothly instead of jumping.
- Multi-step forms — wrap the step outlet so each step change glides to the new
  height instead of snapping.
- `BbSpinner` → content swaps — wrap the region that shows a spinner while
  loading, so the swap to real data stops jumping.

### Accessibility & motion

- Purely visual — it adds no roles or ARIA, and hidden-looking content does not
  exist: everything stays mounted and focusable. If the region is a disclosure
  that should be announced, use `BbAccordion`/`BbCollapsible` so state and
  `inert` are handled.
- **It respects `prefers-reduced-motion: reduce` automatically** — a CSS media
  query collapses the transition duration, so the height still updates (layout
  stays correct) but the change applies instantly. No prop wiring needed.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `disabled` | `boolean \| undefined` | `false` |  | Disable smooth-height behavior and allow natural content height. |
| `mutationOptions` | `MutationObserverInit \| undefined` | `{ childList: true }` |  | Options to pass to the MutationObserver. |
| `resizeOptions` | `ResizeObserverOptions \| undefined` |  |  | Options to pass to the ResizeObserver. |
| `strategy` | `"resize" \| "mutation" \| undefined` | `"resize"` |  | Define which strategy to use. By default `'resize'` is used, which means the component will update on resizing. You can also define `'mutation'` to use a MutationObserver. |
| `tag` | `LayoutTag \| undefined` | `"div"` |  | Element rendered as the component's wrapper. |
| `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds |

## Events

- None.

## Slots

- `default` — scope: `object` — Content whose height changes are animated with a smooth transition.

## See Also

- [BbCollapsible](./BbCollapsible.md) — Toggles visibility of collapsible content blocks.

---

<!-- dist/ai/BbSpinner.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbSpinner.md -->

# BbSpinner

## Agent Contract

- Safety level: **Consumer API**
- Group: **Feedback**
- Description: Indicates ongoing loading or pending operations.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbSpinner.md](./source/BbSpinner.md)

## Usage & Guidelines

### Spinner or progress bar?

Use `BbSpinner` when a wait has **no measurable progress** — a request in
flight, a panel hydrating, results being fetched. When you _can_ express how far
along you are (upload bytes, steps completed, quota used), reach for
[`BbProgress`](./BbProgress.md) instead: a filling bar reads as "almost done",
a spinner reads as "still working". Never fake determinate progress with a
spinner, or vice-versa — `BbProgress` has no indeterminate mode (`null` renders
an empty bar), so this component **is** the library's indeterminate state.

Two props, no slots, no events: `size` (icon scale) and optional `label` (an
sr-only status announcement). Show the spinner with `v-if` while loading, remove
it when done.

**An indeterminate wait**

```vue
<span class="inline-flex items-center gap-2">
	<BbSpinner size="sm" /> Loading results…
</span>
```

Some waits change nature mid-flight. A CSV import first parses and validates
the file — no numbers to show, so it spins — then uploads rows it can count.
Hand off from spinner to bar the moment progress becomes measurable, and never
earlier:

**Hand off to BbProgress when progress becomes measurable**

```vue
<template>
	<div class="import-card">
		<div class="import-card__head">
			<div class="import-card__titles">
				<span class="import-card__title">Import contacts</span>
				<span class="import-card__meta">contacts.csv · 1,284 rows</span>
			</div>
			<BbButton
				:disabled="phase === 'validating' || phase === 'uploading'"
				prepend:icon="lucide:upload"
				variant="outline"
				@click="onImport"
			>
				Import
			</BbButton>
		</div>

		<div
			v-if="phase === 'validating'"
			class="import-card__status"
			role="status"
		>
			<BbSpinner size="sm" />
			<span>Validating contacts.csv…</span>
		</div>
		<div v-else-if="phase === 'uploading'" class="import-card__upload">
			<BbProgress :model-value="progress" />
			<span class="import-card__meta">Uploading rows… {{ progress }}%</span>
		</div>
		<span v-else-if="phase === 'done'" class="import-card__meta">
			1,284 contacts imported.
		</span>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbProgress, BbSpinner } from 'bitboss-ui';

// The wait changes nature mid-flight: validation has no measurable progress
// (spinner), the row upload does (progress bar). Hand off the moment numbers
// exist — never fake a bar during validation, never keep spinning once bytes
// are countable.
type Phase = 'idle' | 'validating' | 'uploading' | 'done';

const phase = ref<Phase>('idle');
const progress = ref(0);

const onImport = () => {
	phase.value = 'validating';
	progress.value = 0;
	// Stand-in for parsing + validating the file (duration unknown → spinner).
	setTimeout(() => {
		phase.value = 'uploading';
		// Stand-in for a chunked upload (rows counted → progress bar).
		const timer = setInterval(() => {
			progress.value = Math.min(progress.value + 20, 100);
			if (progress.value === 100) {
				clearInterval(timer);
				phase.value = 'done';
			}
		}, 90);
	}, 350);
};
</script>

<style scoped>
.import-card {
	background: var(--bb-panel);
	border: var(--bb-border-w) solid var(--bb-border);
	border-radius: var(--bb-radius);
	display: flex;
	flex-direction: column;
	gap: 12px;
	max-width: 24rem;
	padding: 12px;
}

.import-card__head {
	align-items: flex-start;
	display: flex;
	gap: 12px;
	justify-content: space-between;
}

.import-card__titles {
	display: flex;
	flex-direction: column;
	gap: 1px;
	min-width: 0;
}

.import-card__title {
	font-size: 14px;
	font-weight: 500;
}

.import-card__meta {
	color: var(--bb-text-muted);
	font-size: 13px;
}

.import-card__status {
	align-items: center;
	color: var(--bb-text-muted);
	display: flex;
	font-size: 14px;
	gap: 8px;
}

.import-card__upload {
	display: flex;
	flex-direction: column;
	gap: 6px;
}
</style>
```

### Sizing and color

`size` follows the icon scale `xs–2xl` (12/16/24/28/36/40 px by default — the
same `iconDefaultSizes` plugin option that sizes `BbIcon` remaps these keys), a
number (px), or a CSS dimension string (`"3rem"`). The spinner paints in
`currentColor`, so it inherits the text color of whatever it sits in — put it
inside muted helper text and it turns muted for free. To recolor it, set a
text-color class on the wrapper (or the spinner itself); never touch the SVG
internals.

**The size scale**

```vue
<div class="flex items-center gap-4">
	<BbSpinner size="xs" />
	<BbSpinner size="sm" />
	<BbSpinner size="md" />
	<BbSpinner size="lg" />
	<BbSpinner size="xl" />
	<BbSpinner size="2xl" />
</div>
```

**Color rides on the text color**

```vue
<div class="flex items-center gap-4">
	<span class="inline-flex items-center gap-2 text-[color:var(--bb-text-muted)]">
		<BbSpinner size="sm" /> Muted
	</span>
	<span class="inline-flex items-center gap-2 text-[color:var(--bb-primary)]">
		<BbSpinner size="sm" /> Brand
	</span>
	<span class="inline-flex items-center gap-2 text-[color:var(--bb-danger)]">
		<BbSpinner size="sm" /> Retrying…
	</span>
</div>
```

### Loading buttons vs loading regions

`BbButton` has a built-in `loading` state: it swaps in a spinner, blocks
interaction, and sets the right ARIA — and it even tracks async `@click`
handlers automatically. **Do not compose a spinner inside a button yourself** —
pass `loading` (or just return a promise from `@click`). Keep `BbSpinner` for
_region_ or _inline_ loading: a fetching panel, a lazy list, an inline
"saving…" hint.

**Loading buttons use BbButton, not a hand-placed spinner**

```vue
<div class="flex items-center gap-3">
	<BbButton loading>Saving…</BbButton>
	<BbButton loading variant="outline">Refreshing…</BbButton>
</div>
```

When content already exists and a region is refreshing, put the spinner in the
panel body (and let the trigger button use its own `loading` prop):

**A region that is fetching**

```vue
<template>
	<div class="results-panel">
		<div class="results-panel__head">
			<span class="results-panel__title">Invoices</span>
			<BbButton
				:loading="loading"
				prepend:icon="lucide:refresh-cw"
				size="sm"
				variant="outline"
				@click="onRefresh"
			>
				Refresh
			</BbButton>
		</div>

		<div v-if="loading" class="results-panel__status" role="status">
			<BbSpinner size="sm" />
			<span>Fetching latest invoices…</span>
		</div>
		<ul v-else class="results-panel__list">
			<li
				v-for="invoice in invoices"
				:key="invoice.id"
				class="results-panel__row"
			>
				<span class="results-panel__id">{{ invoice.id }}</span>
				<span class="results-panel__customer">{{ invoice.customer }}</span>
				<span class="results-panel__amount">{{ invoice.amount }}</span>
			</li>
		</ul>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbSpinner } from 'bitboss-ui';

type Invoice = {
	id: string;
	customer: string;
	amount: string;
};

// A region-level load: the spinner marks the panel that is fetching, while the
// button's own `loading` prop handles the action affordance. Never hand-place
// a spinner inside a button — `BbButton loading` already does that.
const invoices = ref<Invoice[]>([
	{ id: 'INV-1042', customer: 'Acme Corp', amount: '€4,200.00' },
	{ id: 'INV-1041', customer: 'Globex', amount: '€1,980.00' },
	{ id: 'INV-1039', customer: 'Initech', amount: '€760.00' },
]);
const loading = ref(false);

const onRefresh = () => {
	loading.value = true;
	setTimeout(() => {
		invoices.value = [
			{ id: 'INV-1045', customer: 'Umbrella', amount: '€5,120.00' },
			{ id: 'INV-1044', customer: 'Hooli', amount: '€2,340.00' },
			{ id: 'INV-1043', customer: 'Stark Industries', amount: '€8,900.00' },
		];
		loading.value = false;
	}, 800);
};
</script>

<style scoped>
.results-panel {
	background: var(--bb-panel);
	border: var(--bb-border-w) solid var(--bb-border);
	border-radius: var(--bb-radius);
	display: flex;
	flex-direction: column;
	gap: 12px;
	max-width: 24rem;
	padding: 12px;
}

.results-panel__head {
	align-items: center;
	display: flex;
	gap: 12px;
	justify-content: space-between;
}

.results-panel__title {
	font-size: 14px;
	font-weight: 500;
}

.results-panel__status {
	align-items: center;
	color: var(--bb-text-muted);
	display: flex;
	font-size: 14px;
	gap: 8px;
	padding: 6px 0;
}

.results-panel__list {
	display: flex;
	flex-direction: column;
	gap: 6px;
}

.results-panel__row {
	align-items: baseline;
	display: grid;
	font-size: 14px;
	gap: 8px;
	grid-template-columns: auto 1fr auto;
}

.results-panel__id {
	font-variant-numeric: tabular-nums;
	font-weight: 500;
}

.results-panel__customer {
	color: var(--bb-text-muted);
	min-width: 0;
	overflow: hidden;
	text-overflow: ellipsis;
	white-space: nowrap;
}

.results-panel__amount {
	font-variant-numeric: tabular-nums;
}
</style>
```

### Inline pending and section placeholders

When a single row is saving, keep the spinner on that row — the rest of the
list stays usable. For a first paint before any content exists, center a larger
spinner in the empty section and pair it with a line saying _what_ is coming
(a bare spinner in a blank region tells users nothing). Putting `role="status"`
on the container makes the state audible to assistive tech, per the
[Accessibility](#accessibility) notes below.

**Inline pending row**

```vue
<template>
	<div class="pending-list">
		<div class="pending-list__head">
			<span class="pending-list__title">Team members</span>
			<span class="pending-list__meta">3 seats</span>
		</div>

		<ul class="pending-list__rows">
			<li
				v-for="member in members"
				:key="member.email"
				class="pending-list__row"
			>
				<div class="pending-list__identity">
					<span class="pending-list__name">{{ member.name }}</span>
					<span class="pending-list__meta">{{ member.email }}</span>
				</div>

				<div class="pending-list__trail">
					<span class="pending-list__role">{{ member.role }}</span>
					<span
						v-if="pendingId === member.email"
						class="pending-list__status"
						role="status"
					>
						<BbSpinner size="xs" />
						Saving…
					</span>
					<BbButton
						v-else
						size="sm"
						variant="ghost"
						@click="onSave(member.email)"
					>
						Save
					</BbButton>
				</div>
			</li>
		</ul>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbSpinner } from 'bitboss-ui';

type Member = {
	name: string;
	email: string;
	role: string;
};

// Inline pending: the spinner lives on the row that is mutating — the rest of
// the list stays interactive. Prefer this over blanking the whole table for a
// single save.
const members: Member[] = [
	{
		name: 'Alex Rivera',
		email: 'alex@northwind.co',
		role: 'Admin',
	},
	{
		name: 'Sam Chen',
		email: 'sam@northwind.co',
		role: 'Member',
	},
	{
		name: 'Jordan Lee',
		email: 'jordan@northwind.co',
		role: 'Billing',
	},
];

const pendingId = ref<string | null>(null);

const onSave = (email: string) => {
	pendingId.value = email;
	setTimeout(() => {
		pendingId.value = null;
	}, 700);
};
</script>

<style scoped>
.pending-list {
	background: var(--bb-panel);
	border: var(--bb-border-w) solid var(--bb-border);
	border-radius: var(--bb-radius);
	display: flex;
	flex-direction: column;
	gap: 8px;
	max-width: 28rem;
	padding: 12px;
}

.pending-list__head {
	align-items: baseline;
	display: flex;
	gap: 12px;
	justify-content: space-between;
}

.pending-list__title {
	font-size: 14px;
	font-weight: 500;
}

.pending-list__meta {
	color: var(--bb-text-muted);
	font-size: 13px;
}

.pending-list__rows {
	display: flex;
	flex-direction: column;
}

.pending-list__row {
	align-items: center;
	border-top: var(--bb-border-w) solid var(--bb-border);
	display: flex;
	gap: 12px;
	justify-content: space-between;
	padding: 8px 0;
}

.pending-list__identity {
	display: flex;
	flex-direction: column;
	gap: 1px;
	min-width: 0;
}

.pending-list__name {
	font-size: 14px;
	font-weight: 500;
}

.pending-list__trail {
	align-items: center;
	display: flex;
	flex-shrink: 0;
	gap: 8px;
}

.pending-list__role {
	color: var(--bb-text-muted);
	font-size: 13px;
}

.pending-list__status {
	align-items: center;
	color: var(--bb-text-muted);
	display: inline-flex;
	font-size: 13px;
	gap: 6px;
}
</style>
```

**First-load section placeholder**

```vue
<template>
	<div class="section-shell">
		<div class="section-shell__head">
			<div class="section-shell__titles">
				<span class="section-shell__title">Revenue overview</span>
				<span class="section-shell__meta">Last 30 days · Northwind</span>
			</div>
			<BbButton
				:disabled="loading"
				prepend:icon="lucide:refresh-cw"
				size="sm"
				variant="outline"
				@click="onReload"
			>
				Reload
			</BbButton>
		</div>

		<div v-if="loading" class="section-shell__placeholder" role="status">
			<BbSpinner size="lg" />
			<span class="section-shell__hint">Loading your dashboard…</span>
		</div>
		<div v-else class="section-shell__stats">
			<div v-for="stat in stats" :key="stat.label" class="section-shell__stat">
				<span class="section-shell__meta">{{ stat.label }}</span>
				<span class="section-shell__value">{{ stat.value }}</span>
			</div>
		</div>
	</div>
</template>

<script setup lang="ts">
import { onMounted, ref } from 'vue';
import { BbButton, BbSpinner } from 'bitboss-ui';

type Stat = { label: string; value: string };

// First paint of an empty section: center a spinner with a line naming what is
// coming. A bare spinner in a blank region tells users nothing.
const stats = ref<Stat[]>([]);
const loading = ref(true);

const load = () => {
	loading.value = true;
	stats.value = [];
	setTimeout(() => {
		stats.value = [
			{ label: 'Collected', value: '€48,210' },
			{ label: 'Outstanding', value: '€12,940' },
			{ label: 'Overdue', value: '€3,180' },
		];
		loading.value = false;
	}, 800);
};

const onReload = () => {
	load();
};

onMounted(load);
</script>

<style scoped>
.section-shell {
	background: var(--bb-panel);
	border: var(--bb-border-w) solid var(--bb-border);
	border-radius: var(--bb-radius);
	display: flex;
	flex-direction: column;
	gap: 12px;
	max-width: 28rem;
	padding: 12px;
}

.section-shell__head {
	align-items: flex-start;
	display: flex;
	gap: 12px;
	justify-content: space-between;
}

.section-shell__titles {
	display: flex;
	flex-direction: column;
	gap: 1px;
	min-width: 0;
}

.section-shell__title {
	font-size: 14px;
	font-weight: 500;
}

.section-shell__meta {
	color: var(--bb-text-muted);
	font-size: 13px;
}

.section-shell__placeholder {
	align-items: center;
	color: var(--bb-text-muted);
	display: flex;
	flex-direction: column;
	gap: 8px;
	justify-content: center;
	padding: 40px 12px;
}

.section-shell__hint {
	font-size: 14px;
}

.section-shell__stats {
	display: grid;
	gap: 8px;
	grid-template-columns: repeat(3, minmax(0, 1fr));
}

.section-shell__stat {
	border: var(--bb-border-w) solid var(--bb-border);
	border-radius: var(--bb-radius-sm);
	display: flex;
	flex-direction: column;
	gap: 2px;
	padding: 8px 10px;
}

.section-shell__value {
	font-size: 14px;
	font-variant-numeric: tabular-nums;
	font-weight: 500;
}
</style>
```

### Spinner or skeleton?

A spinner says "something is happening"; a skeleton says "this exact layout is
coming". Prefer a skeleton when the incoming content's shape is known and
stable — `BbTable` ships this built in: pass `loading` (plus a `skeleton` style
like `'avatar-text'`) and it renders placeholder rows, no spinner overlay
needed. Use `BbSpinner` when the shape is unknown (first-time search results,
mixed content) or the indicator is inline with text.

```vue
<!-- Table loads: built-in skeleton rows, not a spinner overlay -->
<BbTable :items="invoices" :loading="fetching" skeleton="text" … />
```

### Config, platform & performance

- **Global config**: only `iconDefaultSizes` affects this component (it remaps
  the `xs–2xl` keys library-wide). Nothing else in the plugin config applies.
- **SSR (Nuxt / Inertia)**: safe. The spinner embeds its own SVG payload — no
  icon-registry lookup, no client-only work — and animates in pure CSS, so it
  renders identically server- and client-side.
- **Performance**: the dots animate with `transform: scale()` only — no layout
  or paint storms, safe to keep on screen indefinitely. Don't "re-theme" it by
  animating SVG geometry attributes; that reintroduces per-frame layout work.

### Works well with

- `BbButton` — `loading` / async `@click` for action feedback (never a
  hand-placed spinner).
- `BbTable` — `loading` + `skeleton` for data grids.
- [`BbProgress`](./BbProgress.md) — switch to it the moment progress becomes
  measurable (e.g. spinner while preparing, bar while uploading).

### Gotchas & anti-patterns

- Never place a `BbSpinner` inside a `BbButton`'s content — the `loading` prop
  exists precisely for that and also handles disabling + ARIA.
- Don't leave a spinner as the only content of an empty region — pair it with
  a line of text so users know _what_ is loading.
- Don't use it for measurable waits (uploads, steps) — that's `BbProgress`.
- Don't build "skeleton screens" out of spinners — components with a known
  layout (tables) have real skeletons.
- There is no `color` prop — color comes from `currentColor`; style the text
  color of the container.
- Prefer `label` only when the spinner has **no** adjacent visible text. When
  you already show "Loading…" next to it, put `role="status"` on your container
  and omit `label` so assistive tech is not announced twice.

### Accessibility

By default the spinner is decorative — no live region and no ARIA role. Pair it
with adjacent visible text (`Loading results…`) and put `role="status"` /
`aria-live="polite"` on the text container you control. When the spinner stands
alone (icon-only pending affordance), set `label` so the component wraps itself
in `role="status"` with that text rendered `sr-only`. Prefer `BbButton`'s
`loading` for action feedback since it wires up ARIA for you.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `string \| undefined` |  |  | Accessible loading announcement. When set, the spinner is wrapped in a `role="status"` element containing this text rendered `sr-only`, so screen readers announce the loading state. When omitted the markup is unchanged and the spinner is pu… |
| `size` | `number \| ({ size?: any; } & string) \| keyof Sizes \| undefined` | `"md"` |  | Defines the component size. Accepted values: - A key from the provided size map (`keyof T`), e.g. `'sm' \| 'md' \| 'lg'` - A custom CSS size string (e.g. `'20px'`, `'1.5rem'`, `'2em'`) - A number, typically interpreted as pixels by size par… |

## Events

- None.

## Slots

- None.

## See Also

- [BbProgress](./BbProgress.md) — Visualizes task or operation progress state.

---

<!-- dist/ai/BbSwitch.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbSwitch.md -->

# BbSwitch

## Agent Contract

- Safety level: **Consumer API**
- Group: **Selection**
- Description: Toggles two-state values with switch semantics.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbSwitch.md](./source/BbSwitch.md)

## Usage & Guidelines

### When to use

Reach for `BbSwitch` when the control is the **on/off state of a thing**: dark
mode, notifications, a beta flag, "anyone with the link can view", auto-renew.
The switch says _this thing is on or off right now_.

Prefer `BbCheckbox` when the control is an **answer or a selection** rather than
a state — accepting terms, ticking "also send me a copy", selecting a row. For a
set of related on/off settings bound to one array, use `BbSwitchGroup`.

**The commit model does not decide this.** A switch is equally correct as a live
toggle and as a field inside a form that commits on Save or Next: the library
ships `BbSwitch` from `bitboss-ui/validated` for exactly that, its own fixtures
put one inside `<BbForm>`, and its wizard recipes put one behind a Next button.
Do not downgrade a state toggle to a checkbox just because a Save button exists.
What matters is that a surface picks **one** commit model — see
[Gotchas and anti-patterns](#gotchas-and-anti-patterns).

### Binding on/off

`v-model` holds the value and updates on every toggle (click, or Space/Enter on
the focused control). `description` is always-visible helper text tied to the
control via `aria-describedby`; `hint` is transient guidance that appears while
the switch has focus — pin it open with `persistent-hint`.

**Instant-effect settings**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Account security</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Preferences take effect as soon as you flip them.
			</p>
		</div>
		<div class="grid gap-3">
			<BbSwitch
				v-model="twoFactor"
				description="Require a one-time code at every sign-in."
				label="Two-factor authentication"
				name="2fa"
			/>
			<BbSwitch
				v-model="digest"
				hint="Sent every Monday morning."
				label="Weekly digest email"
				name="digest"
				persistent-hint
			/>
		</div>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSwitch } from 'bitboss-ui';

const twoFactor = ref(true);
const digest = ref(false);
</script>
```

Besides `update:modelValue` the switch re-emits the native interaction events
(`change`, `click`, `input`, `focus`, `blur`, `keydown`, `mousedown`,
`mouseup`) — listen to those for analytics or side effects, never to derive the
value: the value is what `v-model` gives you.

### Custom on/off values

The bound value does not have to be a boolean. Set `true-value` /
`false-value` — any serializable value works (strings, numbers, arrays,
objects; equality is structural) — and `v-model` stores whichever the current
state maps to. Handy when the switch drives an enum-like setting.

**Custom on/off values**

```vue
<template>
	<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-4">
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Profile visibility</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Stores an enum string instead of a boolean.
			</p>
		</div>
		<BbSwitch
			v-model="visibility"
			false-value="private"
			label="Public profile"
			name="visibility"
			true-value="public"
		/>
		<p class="text-xs text-[color:var(--bb-text-muted)]">
			Stored value: <code>{{ visibility }}</code>
		</p>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSwitch } from 'bitboss-ui';

const visibility = ref<'public' | 'private'>('private');
</script>
```

For classic (non-AJAX) form posts the checked switch submits `true-value`
under `name` (non-string values are JSON-encoded). An unchecked checkbox
normally submits nothing — set `submit-when-false` to also send `false-value`
via a hidden input, so the server always receives the field.

### Saving instantly — and reverting on failure

This is the pattern for a **live** switch — one with no Save button behind it
(inside a submit-gated form, do none of this and let the form commit). Wire the
save to the toggle itself: bind
`:model-value` + `@update:model-value`, apply the change optimistically, and
revert if the request fails. Set `readonly` while the request is in flight so
the user cannot queue conflicting toggles.

**Async toggle with revert**

```vue
<template>
	<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-4">
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Workspace</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Northwind Billing — flips save immediately and revert on failure.
			</p>
		</div>
		<BbSwitch
			description="Visitors see a status page while enabled."
			label="Maintenance mode"
			:model-value="maintenance"
			name="maintenance"
			:readonly="saving"
			@update:model-value="onSave"
		/>
		<p v-if="error" class="text-xs text-red-600" data-testid="error">
			{{ error }}
		</p>
		<p class="text-xs text-[color:var(--bb-text-muted)]" data-testid="status">
			{{ saving ? 'Saving…' : maintenance ? 'Enabled' : 'Disabled' }}
		</p>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSwitch } from 'bitboss-ui';

const maintenance = ref(false);
const saving = ref(false);
const error = ref('');

/** Simulated API: enabling succeeds; disabling is rejected mid-deploy. */
const persist = (value: boolean) =>
	new Promise<void>((resolve, reject) => {
		setTimeout(
			() => (value ? resolve() : reject(new Error('Deployment in progress'))),
			120
		);
	});

const onSave = async (value: boolean) => {
	error.value = '';
	saving.value = true;
	maintenance.value = value; // optimistic
	try {
		await persist(value);
	} catch {
		maintenance.value = !value; // revert
		error.value = 'Could not save — the setting was restored.';
	} finally {
		saving.value = false;
	}
};
</script>
```

In this demo enabling succeeds and disabling is rejected by the "server" — flip
it off to see the revert. Pair the failure path with `useToast` in a real app
so the feedback doesn't depend on nearby text.

### Passive state: checked and indeterminate

Two props override the visual state without touching `v-model`:

- `checked` (booleanish: `true`/`false`/`'true'`/`'false'`) forces the checked
  visual regardless of the model — useful when the state is owned elsewhere and
  the switch is display-driven. Leave it unset to let `modelValue` drive.
- `indeterminate` shows the "partially on" thumb position — e.g. a master
  switch whose children disagree. It is a visual flag only; the model keeps its
  value, and the component re-asserts it after clicks (the DOM resets
  indeterminate natively).

**Master switch with mixed children**

```vue
<BbSwitch
	label="All notifications"
	:checked="true"
	indeterminate
	readonly
	name="master"
	hint="Some channels are on, some off."
	persistent-hint
/>
```

### Custom toggle visual

The `icon` slot replaces the **entire track-and-thumb visual** (not just a
glyph inside it) — the native input keeps carrying `role="switch"` and the
state, so accessibility is unaffected. The slot receives the live state to
render from: `checked`, `focused`, `focusVisible`, `disabled`, `readonly`,
`indeterminate`, `hasErrors`, `value`/`trueValue`/`falseValue`, and `text` (the
label). When you replace the visual, you own its checked/unchecked styling and
its focus ring (style against `focusVisible`).

**A glyph that tracks state**

```vue
<template>
	<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-4">
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Appearance</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				The icon slot replaces the whole track — style checked state yourself.
			</p>
		</div>
		<BbSwitch v-model="dark" label="Dark mode" name="theme">
			<template #icon="{ checked, focusVisible }">
				<span
					class="glyph inline-flex h-6 w-6 items-center justify-center rounded-full"
					:class="{
						'glyph--on': checked,
						'glyph--focus': focusVisible,
					}"
				>
					<BbIcon :icon="checked ? 'lucide:moon' : 'lucide:sun'" size="xs" />
				</span>
			</template>
		</BbSwitch>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSwitch, BbIcon } from 'bitboss-ui';

const dark = ref(true);
</script>

<style scoped>
.glyph {
	background: var(--bb-muted);
	color: var(--bb-text-muted);
	transition:
		background var(--bb-transition-fast) var(--bb-ease),
		color var(--bb-transition-fast) var(--bb-ease);
}
.glyph--on {
	background: var(--bb-primary);
	color: var(--bb-primary-fg);
}
.glyph--focus {
	box-shadow:
		0 0 0 2px var(--bb-panel),
		0 0 0 4px var(--bb-ring);
}
</style>
```

The `label` slot (`{ text, hasErrors }`) replaces the label text instead — use
it to append a `BbBadge` ("Beta") or emphasis without giving up the accessible
name. The classic case is a feature-flags panel where experimental flags carry
a stage pill next to the flag name:

**Feature flags with a Beta badge**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Feature flags</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Workspace experiments for Northwind Billing.
			</p>
		</div>
		<div class="grid gap-3">
			<BbSwitch
				v-model="newEditor"
				description="Block-based editing with slash commands."
				label="New editor"
				name="new-editor"
			>
				<template #label="{ text }">
					<span class="inline-flex items-center gap-1.5">
						{{ text }}
						<BbBadge size="sm" variant="soft-amber">Beta</BbBadge>
					</span>
				</template>
			</BbSwitch>
			<BbSwitch
				v-model="aiSummaries"
				description="Summarize long invoice threads automatically."
				label="AI thread summaries"
				name="ai-summaries"
			/>
			<BbSwitch
				v-model="usageAnalytics"
				description="Anonymized product usage for the retention policy."
				label="Usage analytics"
				name="usage-analytics"
			/>
		</div>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSwitch, BbBadge } from 'bitboss-ui';

const newEditor = ref(true);
const aiSummaries = ref(false);
const usageAnalytics = ref(true);
</script>

<!-- Non-scoped on purpose: styles the child badge's soft variant (scoped CSS
     can't reach it without :deep). Canonical palette:
     ai/guides/design-language.md § Using color. -->
<style>
.bb-badge.bb-badge--soft-amber {
	--accent: #d97706;
	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
	--border-width: 1px;
	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
}
</style>
```

### Label, layout and density

- `label` is required; `hide-label` keeps it for assistive tech only.
- `direction` arranges label vs control: `'horizontal'`, `'vertical'`, the
  default `'auto'`, or a proportional pattern like `'xx xxxxxx'` (label 25% /
  control 75%).
- `reverse` swaps the label/control order in whichever direction is active.
- `label-position` / `input-position` (`left | center | right`) align the two
  parts within their tracks.

**Row layout for settings lists**

```vue
<template>
	<div class="grid max-w-md gap-2 rounded-[var(--bb-radius)] border p-3">
		<div class="flex flex-col gap-0.5 pb-1">
			<p class="text-sm font-medium">Playback</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Label-heavy rows with the control pinned to the trailing edge.
			</p>
		</div>
		<BbSwitch
			v-model="autoplay"
			direction="xxxxxx xx"
			label="Autoplay videos"
			name="autoplay"
			reverse
		/>
		<BbSwitch
			v-model="captions"
			direction="xxxxxx xx"
			label="Always show captions"
			name="captions"
			reverse
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSwitch } from 'bitboss-ui';

const autoplay = ref(true);
const captions = ref(false);
</script>
```

### A panel of switches

Bind each switch to its own field of a typed settings object. The example below
is a **live** panel: every toggle applies on change, so there is no Save button
and none is wanted. The same markup inside a `<BbForm>` with a Save button is
equally valid — it is then a submit-gated form and no toggle writes on its own.
What a panel must not do is both.

**Notification preferences**

```vue
<template>
	<div class="grid max-w-md gap-3 rounded-[var(--bb-radius)] border p-4">
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Email notifications</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Sent to alex@northwind.io — changes apply immediately.
			</p>
		</div>
		<div class="grid gap-3">
			<BbSwitch
				v-for="pref in preferences"
				:key="pref.key"
				v-model="pref.enabled"
				:description="pref.description"
				:label="pref.label"
				:name="pref.key"
			/>
		</div>
		<p class="text-xs text-[color:var(--bb-text-muted)]" data-testid="summary">
			{{ enabledCount }} of {{ preferences.length }} notifications on
		</p>
	</div>
</template>
<script setup lang="ts">
import { computed, reactive } from 'vue';
import { BbSwitch } from 'bitboss-ui';

type Preference = {
	key: string;
	label: string;
	description: string;
	enabled: boolean;
};

const preferences = reactive<Preference[]>([
	{
		key: 'product',
		label: 'Product updates',
		description: 'New features, changelog notes, and roadmap posts.',
		enabled: true,
	},
	{
		key: 'security',
		label: 'Security alerts',
		description: 'Sign-ins from unrecognised devices and API key changes.',
		enabled: true,
	},
	{
		key: 'marketing',
		label: 'Marketing emails',
		description: 'Occasional offers, webinars, and partner news.',
		enabled: false,
	},
]);

const enabledCount = computed(
	() => preferences.filter((pref) => pref.enabled).length
);
</script>
```

### Disabled, readonly and errors

- `disabled` sets the native attribute: the switch leaves the tab order and
  greys out.
- `readonly` blocks changes (pointer and Space/Enter) but stays focusable and
  exposes `aria-disabled`/`aria-readonly` — prefer it over `disabled` for
  admin-locked settings, with a nearby explanation. Note it does **not** set
  the native `disabled` attribute, so don't target `:disabled` in CSS or tests
  for readonly switches (`.bb-base-switch--readonly` is the styling hook).
- `errors` (string or array) renders messages below the control and
  `has-errors` toggles error styling alone — rare for switches, but available
  when a toggle is rejected by validation.
- `warnings` (string or array) is the amber counterpart of `errors`, rendered
  below the control in its own `aria-live="polite"` region (also referenced
  from `aria-describedby` while displayed) for a
  valid-but-noteworthy toggle; a non-empty `warnings` implies the warning state
  just as `errors` implies the error state, while `has-warning` forces that amber
  chrome without a message. Unlike `has-errors`, neither sets `aria-invalid` — a
  soft flag, not an invalid state — and `has-errors` takes priority when both are
  set, suppressing the warning messages so the switch never shows amber and red
  at once.

### Config, platform and pairings

No plugin options change `BbSwitch` behavior (it has no i18n strings, no
teleport, no variant registry) and it renders SSR-safe static markup in Nuxt
and Inertia apps.

Works well with:

- `BbSwitchGroup` — the same toggle bound to one array of enabled values.
- `BbCheckbox` — identical API, for answers and selections rather than states.
- `bitboss-ui/validated` — the vee-validate-bound `BbSwitch` for a switch that
  commits with the form (see
  [validated forms](../../ai/guides/validated-forms.md)).
- `useToast` — confirm or report the outcome of an instant setting change.
- `useConfirm` — gate a destructive toggle (e.g. disabling backups) before
  applying it.

### Gotchas and anti-patterns

- Don't mix commit models on one surface. Switches that already applied the
  moment they were flipped must not sit under a "Save" button implying they had
  not — the user cannot tell what is already live. Pick one: either the panel is
  live (no Save), or every field commits on submit (Save, and no optimistic
  write on toggle). A switch inside a submit-gated form is fine; a switch that
  saves itself _and_ has a Save button is not.
- Don't listen to `@click`/`@change` to compute the next value yourself —
  `v-model` (or `@update:model-value`) already delivers the mapped
  `true-value`/`false-value`.
- Don't pass `:checked` together with `v-model` expecting them to sync;
  `checked` overrides the derived state and wins until unset.
- The `icon` slot replaces the whole toggle visual — supplying just a bare icon
  removes the track. Wrap it in your own styled container as shown above.

### Accessibility

- Always provide a `label` — it is the switch's accessible name. Use
  `hide-label` only when an adjacent element already labels it.
- The control exposes `role="switch"` with its checked state automatically; do
  not add your own ARIA.
- `errors`, `warnings` and `description` are all wired to the control through
  `aria-describedby`, in that order: the reason the field is invalid is spoken
  first when it regains focus, and a channel is referenced only while it
  actually has copy. Messages _also_ render in an `aria-live="polite"` region,
  so they are announced the moment they appear — announced on change, re-read
  on focus. Keep messages meaningful, not decorative.
- Prefer `readonly` (focusable, discoverable) with a nearby explanation over a
  silent `disabled`.

## v-model

- `v-model` — type: `any`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
| `checked` | `boolean \| undefined` | `undefined` |  | Defines the input as checked. |
| `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
| `direction` | `InputDirection \| undefined` | `"auto"` |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
| `falseValue` | `any` |  |  | Value of the input when unchecked. It handles any kind of serializable object. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `indeterminate` | `boolean \| undefined` | `false` |  | Sets the input in an indeterminate state. |
| `inputPosition` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can. |
| `label` | `string` |  | yes | Text content of the label of the element. |
| `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
| `modelValue` | `any` |  |  | Used by v-model. Can be any serializable type. |
| `name` | `string \| undefined` |  |  | Defines the name of the input. |
| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout: in every direction the order of the label and the input is swapped from the standard arrangement. |
| `submitWhenFalse` | `boolean \| undefined` | `false` |  | Will submit "falseValue" if the input is not checked. Otherwise "trueValue" will be submitted. |
| `trueValue` | `any` |  |  | Value of the input when checked. It handles any kind of serializable object. |
| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |

## Events

- `blur` — `(event: "blur", event: FocusEvent): void`
- `change` — `(event: "change", event: Event): void`
- `click` — `(event: "click", event: MouseEvent): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `input` — `(event: "input", event: Event): void`
- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
- `update:modelValue` — `(event: "update:modelValue", value: any): void`

## Slots

- `icon` — scope: `BbSwitchIconSlotProps` — Replaces the default toggle track visual inside the switch. Receives `BaseSwitch` slot attributes plus the label text.
- `label` — scope: `BbSwitchLabelSlotProps` — Replaces the default label text rendered next to the switch.

## Validated variant

Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).

| Prop | Type | Description |
| --- | --- | --- |
| `rules` | `RuleExpression<any>` | vee-validate rules for this field. |
| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |

## See Also

- [BbSwitchGroup](./BbSwitchGroup.md) — Manages grouped switch options with shared behavior.
- [BbCheckbox](./BbCheckbox.md) — Toggles a single boolean option.

---

<!-- dist/ai/BbSwitchGroup.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbSwitchGroup.md -->

# BbSwitchGroup

## Agent Contract

- Safety level: **Consumer API**
- Group: **Selection**
- Description: Manages grouped switch options with shared behavior.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbSwitchGroup.md](./source/BbSwitchGroup.md)

## Usage & Guidelines

### When to use

Use `BbSwitchGroup` for a set of related settings that each take effect on their
own, the moment they flip — notification channels, editor features, privacy
options. It renders a `<fieldset>` / `<legend>` and binds an **array** of the
enabled values, mapping each switch from your `items`.

Same visual family as its siblings, different promise — choose by what the flip
means:

- `BbSwitchGroup` — each row is the on/off **state of a thing**. "Turn things on
  and off." Usually a live panel, but equally valid inside a submit-gated form
  (`bitboss-ui/validated` ships `BbSwitchGroup` for exactly that).
- `BbCheckboxGroup` — the selections are **answers or picks** in a form.
  "Pick some options." Identical items API.

Choose on what the flip _means_, not on whether a Save button exists.

- `BbSwitch` — a single standalone toggle, not part of a set.
- `BbRadioGroup` — exactly one exclusive choice.

### Items are your domain objects

`BbSwitchGroup` is items-driven and shares the checkbox group's mapping API.
Pass your domain objects straight to `items` and resolve the display text and
stored value with `item-text` / `item-value` — never pre-map into
`{ label, value }` arrays. `v-model` then holds an array of the resolved values
(here, ids), which is what you persist. See the
[options & items playbook](../../ai/guides/options-items-playbook.md).

**Notification channels (object items)**

```vue
<template>
	<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-3">
		<BbSwitchGroup
			v-model="channels"
			compact
			description="Each channel applies the moment you flip it."
			item-text="label"
			item-value="id"
			:items="options"
			legend="Where should we reach you?"
			name="workspace-notifications"
		/>
		<p class="text-xs text-[color:var(--bb-text-muted)]" data-testid="summary">
			{{ channels.length }} channel{{ channels.length === 1 ? '' : 's' }} active
		</p>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSwitchGroup } from 'bitboss-ui';

type Channel = { id: string; label: string };

const options: Channel[] = [
	{ id: 'email', label: 'Email' },
	{ id: 'sms', label: 'SMS' },
	{ id: 'push', label: 'Push notifications' },
	{ id: 'slack', label: 'Slack' },
];

const channels = ref<string[]>(['email', 'push']);
</script>
```

The mapping grammar:

- **Primitive `items`** (`string[]` / `number[]`): omit both props; the value is
  the primitive.
- **Dot path**: `item-value="id"`, `item-text="profile.fullName"`.
- **Extractor function** for anything a path can't express.

Values are matched by **deep equality** (structural, not by reference), and two
items resolving to the same `item-value` collapse to one switch (first wins), so
keep values unique — prefer stable primitive ids.

### The array model is mandatory

Like `BbCheckboxGroup`, `multiple` defaults to **`true`**, so `modelValue`
**must be an array** — seed `ref([])`. A non-array model **throws at setup**;
that's deliberate, to surface the mis-binding immediately.

```ts
const enabled = ref<string[]>(['email']); // correct
const enabled = ref(); // throws at setup
```

Flipping a switch on appends its value; flipping off removes it. The whole array
is re-emitted every change — treat `v-model` as immutable. Each switch is
independent, so the panel reads as "things that are on or off", not "options to
pick".

### Cap how many can be on with `max`

`max` caps how many switches may be **on** at once. At the cap the remaining
**off** switches disable automatically, while switches already **on** stay
toggleable so the user can trade one for another. Pair it with a `hint` that
explains the limit.

**At most two channels on**

```vue
<template>
	<div class="max-w-sm rounded-[var(--bb-radius)] border p-3">
		<BbSwitchGroup
			v-model="channels"
			compact
			hint="Choose up to two channels."
			:items="['Email', 'SMS', 'Push', 'Slack']"
			legend="Alert channels"
			:max="2"
			name="alert-channels"
			persistent-hint
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSwitchGroup } from 'bitboss-ui';

// Two channels already on: the remaining off switches disable at the cap,
// while these stay toggleable so the user can trade one for another.
const channels = ref<string[]>(['Email', 'Push']);
</script>
```

`max` gates _how many_; to gate _which_ switches can be flipped,
use `selectable`: a boolean (`false` disables every switch) or a predicate
`(item) => boolean` — options it rejects render disabled (e.g.
`:selectable="(feature) => feature.enabledForPlan"`). A `disabled` field on the
item object itself has no effect — it is plain domain data; feed it to the
predicate instead. To make the whole group non-interactive use the `disabled`
prop; when a dead row adds nothing, filter the item out of `items`.

### Layout and density

- `input-direction` (`'horizontal' | 'vertical'`) lays the switches in a row or
  a stack.
- `compact` tightens spacing so a group of quick toggles fits inline.
- `direction` splits the legend against the options block (`'auto'`,
  `'horizontal'`, `'vertical'`, or a pattern like `'xx xxxxxx'`).
- `input-position` / `legend-position` align the switches and legend within
  their columns; `reverse` swaps legend and options order (a plain swap here, not
  inverted).
- `hide-legend` hides the legend visually but keeps it for assistive tech. Keep
  density consistent with the surrounding form.

**Horizontal, compact toggles**

```vue
<template>
	<div class="max-w-sm rounded-[var(--bb-radius)] border p-3">
		<BbSwitchGroup
			v-model="enabled"
			compact
			hint="Applies to the current file only."
			input-direction="horizontal"
			:items="['Word wrap', 'Minimap', 'Line numbers']"
			legend="Editor"
			name="editor-toggles"
			persistent-hint
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSwitchGroup } from 'bitboss-ui';

const enabled = ref<string[]>(['Word wrap', 'Line numbers']);
</script>
```

### Legend, description and validation

The `legend` names the group — always set it. `description` is always-visible
helper text; `hint` shows on focus (`persistent-hint` to pin it); both are wired
via `aria-describedby`. `errors` (string or array) renders messages and puts the
group in the error state; `has-errors` toggles error styling alone — rare for a
settings panel, but available when a toggle is rejected. `legend-mode` places
the legend `'outside'` (default) or `'inside'` the border. There is **no
`required` prop** (a switch panel isn't a required field).

### Saving instantly

This is the pattern for a **live** panel — one with no Save button behind it
(inside a submit-gated form, do none of this and let the form commit). Wire
persistence to the change, not to a submit button:
bind `:model-value` + `@update:model-value`, apply optimistically,
and revert on failure; set `readonly` while a request is in flight so the user
can't queue conflicting toggles. In production, confirm the outcome with
`useToast` so feedback doesn't depend on nearby text, and gate destructive
toggles (e.g. disabling backups) with `useConfirm`.

In this feature-flags panel every flip saves immediately; the simulated API
rejects turning "Usage analytics" off, so that flip reverts and the message
explains why:

**Feature flags with optimistic save**

```vue
<template>
	<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-3">
		<BbSwitchGroup
			compact
			item-text="label"
			item-value="id"
			:items="flags"
			legend="Feature flags"
			:model-value="enabled"
			name="feature-flags"
			:readonly="saving"
			@update:model-value="onSave"
		/>
		<p
			v-if="error"
			class="text-xs text-[color:var(--bb-danger)]"
			data-testid="flags-error"
		>
			{{ error }}
		</p>
		<p
			class="text-xs text-[color:var(--bb-text-muted)]"
			data-testid="flags-status"
		>
			{{ saving ? 'Saving…' : `${enabled.length} of ${flags.length} flags on` }}
		</p>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbSwitchGroup } from 'bitboss-ui';

type FeatureFlag = { id: string; label: string };

const flags: FeatureFlag[] = [
	{ id: 'command-palette', label: 'Command palette' },
	{ id: 'ai-review', label: 'AI code review' },
	{ id: 'usage-analytics', label: 'Usage analytics' },
];

const enabled = ref<string[]>(['command-palette', 'usage-analytics']);
const saving = ref(false);
const error = ref('');

/** Simulated API — retention policy forbids turning usage analytics off. */
const persist = (next: string[]) =>
	new Promise<void>((resolve, reject) => {
		setTimeout(
			() =>
				next.includes('usage-analytics')
					? resolve()
					: reject(new Error('Retention policy requires usage analytics')),
			200
		);
	});

/** Optimistic flip; reverts and surfaces an error when the API rejects. */
const onSave = async (next: string[]) => {
	const previous = enabled.value;
	enabled.value = next;
	error.value = '';
	saving.value = true;
	try {
		await persist(next);
	} catch {
		enabled.value = previous;
		error.value = 'Could not save — usage analytics was restored.';
	} finally {
		saving.value = false;
	}
};
</script>
```

### Async items, loading and coherence

`items` also accepts a provider function (`(prefill, modelValue) => T[] |
Promise<T[]>`) for options fetched from an API. The group calls it on mount and
on every dependency-driven refetch with `prefill = true` — groups have no search
field, so `prefill` is never `false` here. While it resolves, `loading-text` (or
the `#loading` slot) shows; `no-data-text` (or `#no-data`) covers the empty
result. Loading and race protection are built in — don't wrap the provider in
your own `loading` ref or debounce.

Tie the option set to external state with `dependencies` (debounced by
`deps-debounce-time`) instead of a manual watcher, and set `enforce-coherence`
so any model entry that no longer matches an available option is dropped
automatically after a reload. Here the channel list depends on the workspace
plan: changing plan re-runs the provider (`prefill = true`) and
`enforce-coherence` flips off any channel the new plan doesn't include —
downgrade from Pro to Free and watch Slack turn off on its own, no watchers
involved. See the [fetch-items](../../ai/guides/fetch-items-playbook.md) and
[coherence](../../ai/guides/coherence-playbook.md) playbooks.

**Alert channels constrained by plan (fetch + coherence)**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<BbRadioGroup
			v-model="plan"
			compact
			input-direction="horizontal"
			item-text="label"
			item-value="id"
			:items="plans"
			legend="Workspace plan"
			name="workspace-plan"
		/>
		<BbSwitchGroup
			v-model="enabled"
			compact
			:dependencies="[plan]"
			:deps-debounce-time="150"
			enforce-coherence
			hint="Channels outside the current plan turn off automatically."
			item-text="label"
			item-value="id"
			:items="loadChannels"
			legend="Alert channels"
			loading-text="Loading channels…"
			name="alert-channels-by-plan"
			persistent-hint
		/>
		<p class="channel-summary text-xs text-[color:var(--bb-text-muted)]">
			{{ enabled.length }} channel{{ enabled.length === 1 ? '' : 's' }} on
		</p>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbRadioGroup, BbSwitchGroup } from 'bitboss-ui';

type Plan = 'free' | 'pro' | 'business';

type Channel = {
	id: string;
	label: string;
	plans: Plan[];
};

const plans: Array<{ id: Plan; label: string }> = [
	{ id: 'free', label: 'Free' },
	{ id: 'pro', label: 'Pro' },
	{ id: 'business', label: 'Business' },
];

const allChannels: Channel[] = [
	{ id: 'email', label: 'Email', plans: ['free', 'pro', 'business'] },
	{ id: 'slack', label: 'Slack', plans: ['pro', 'business'] },
	{ id: 'webhook', label: 'Webhooks', plans: ['pro', 'business'] },
	{ id: 'sms', label: 'SMS', plans: ['business'] },
];

const plan = ref<Plan>('pro');
const enabled = ref<string[]>(['email', 'slack']);

// Group provider signature: (prefill, modelValue). `prefill` is true on every
// fetch the group starts itself — the mount load and dependency-driven
// refetches alike; only a user-typed query reads false, and a group has no
// search field.
const loadChannels = (
	_prefill: boolean,
	_modelValue?: string[]
): Promise<Channel[]> =>
	new Promise((resolve) => {
		setTimeout(
			() =>
				resolve(
					allChannels.filter((channel) => channel.plans.includes(plan.value))
				),
			300
		);
	});
</script>
```

### Slots

`#label` replaces an option's text (`{ item, text, checked }`); `#icon` replaces
the **entire track-and-thumb visual** for that switch — the native input keeps
`role="switch"` and its state, so accessibility is unaffected, but you own the
checked/focus styling. `#legend` replaces the fieldset legend
(`{ text, hasErrors, hasWarning }`; the validated wrapper adds
`showAsterisk`); `#prepend` /
`#append` inject content inside the options container.

### Events and focus

`update:modelValue` carries the full array — the only selection-of-truth
channel. Native `blur`, `change`, `click`, `focus`, `input`, `keydown`,
`mousedown`, `mouseup` re-emit with raw payloads, plus `active` when focus
enters the group (it drives the hint internally) and `inactive` when focus
leaves the group. `autofocus` focuses the first switch on mount.

### Config, platform and pairings

No plugin options change `BbSwitchGroup` behavior, and it renders SSR-safe static
markup in Nuxt and Inertia apps.

Works well with:

- `BbSwitch` — a single standalone toggle with the same on/off API.
- `BbCheckboxGroup` — swap to it when the rows are answers or picks rather than
  states (identical items API).
- `useToast` — confirm or report the outcome of an instant setting change.
- `useConfirm` — gate a destructive toggle before applying it.

### Gotchas and anti-patterns

- Don't mix commit models on one surface. A group whose toggles already saved
  themselves must not sit under a "Save" button implying they had not. Pick one:
  either the panel is live (no Save), or the whole form commits on submit (Save,
  and no optimistic write on toggle). A switch group inside a submit-gated form
  is fine; one that saves itself _and_ has a Save button is not.
- Don't seed the `v-model` ref with a non-array in multiple mode — it **throws**.
  Use `ref([])`.
- Don't listen to `@change`/`@click` to compute the next array yourself —
  `update:modelValue` already delivers it.
- At `max`, on-switches stay enabled so the user can trade — don't disable them.
- A `disabled` field on an item object does nothing — it is inert data. Gate
  options with the `selectable` predicate, or disable the whole group with
  `disabled`.
- Don't pre-map `items` into `{ label, value }` — pass raw rows and resolve with
  `item-text` / `item-value`.

### Accessibility

- `legend` is required and names the group; use `hide-legend` (not omission) if a
  visible heading already labels it.
- Each switch exposes `role="switch"` and derives its accessible name from its
  item text — keep item labels human-readable.
- The group is a real `<fieldset>`; don't nest it inside another label.
- `errors`, `warnings` and `description` are all wired to the group through
  `aria-describedby`, in that order: the reason the field is invalid is spoken
  first when it regains focus, and a channel is referenced only while it
  actually has copy. Messages _also_ render in an `aria-live="polite"` region,
  so they are announced the moment they appear — announced on change, re-read
  on focus. Keep messages meaningful, not decorative.
- Prefer `readonly` (focusable, discoverable, still submits) with a nearby
  explanation over a silent `disabled`.
- With a custom `#icon` slot you own the visual state — keep `checked` and
  `focusVisible` distinct.

## v-model

- `v-model` — type: `any`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
| `compact` | `boolean \| undefined` | `false` |  | Displays the component in a compact version. |
| `dependencies` | `unknown[] \| undefined` |  |  | Defines an array of dependencies that will trigger actions in the component upon change. |
| `depsDebounceTime` | `number \| undefined` |  |  | Timeout used to debounce response to changes to dependencies. |
| `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
| `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
| `enforceCoherence` | `boolean \| undefined` | `false` |  | If coherence is enforced the input cannot have a modelValue that is incoherent with its current items. e.g. You cannot set v-model to a user that is not present in the items passed. modelValue will be reset upon incoherence. |
| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides each option's label text (the text rendered next to every input) while keeping it accessible to screen readers. Does not affect the fieldset legend — use `hideLegend` for that. |
| `hideLegend` | `boolean \| undefined` | `false` |  | Visually hides the legend of the fieldset while maintaining accessibility. |
| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `inputDirection` | `"horizontal" \| "vertical" \| undefined` |  |  | Defines the direction of the inputs in the fieldset. |
| `inputPosition` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can. |
| `items` | `T[] \| ((prefill: boolean, modelValue?: any) => T[] \| Promise<T[]>)` |  | yes | Used to retrieve items; can be an array or a function. |
| `itemText` | `ItemAccessor<T, string> \| undefined` |  |  | Defines a path that returns a property of the object to use as text or a function that returns a string. |
| `itemValue` | `ItemAccessor<T> \| undefined` |  |  | Defines a path that returns a property of the object to use as value or a function that returns any value. |
| `legend` | `string` |  | yes | Text content of the legend. |
| `legendMode` | `"outside" \| "inside" \| undefined` |  |  | Legend rendering mode. `'outside'` renders the legend above the fieldset in the normal flow; `'inside'` overlays the legend inside the fieldset border. Floating mode is not supported for option groups (checkbox, radio or switch) — there is … |
| `legendPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
| `loadingText` | `string \| undefined` |  |  | String displayed while items are being loaded. |
| `max` | `number \| undefined` |  |  | Maximum number of selected items. |
| `modelValue` | `any` |  | yes | Used by v-model. Can be an array of any serializable type. |
| `modelValueDebounceTime` | `number \| undefined` |  |  | Timeout used to debounce response to changes to modelValue. |
| `multiple` | `boolean \| undefined` | `true` |  | Enables multi-selection behavior. When true, `modelValue` must be an array. When false, `modelValue` should be a single value. |
| `name` | `string \| undefined` |  |  | Defines the name of the input. |
| `noDataText` | `string \| undefined` |  |  | String displayed when there are no items to display. |
| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
| `selectable` | `boolean \| ((item: T) => boolean) \| undefined` | `true` |  | Defines whether options are selectable. Can be a global boolean that affects all options or a function that accepts an item and returns a boolean that only affects that item. Non-selectable options are rendered disabled. |
| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |

## Events

- `active` — `(e: "active"): void` — Emitted when the group becomes active (focus/click enters it).
- `blur` — `(e: "blur", event: FocusEvent): void` — Emitted when one of the generated checkbox inputs loses focus. Forwards the original DOM `FocusEvent`.
- `change` — `(e: "change", event: Event): void` — Emitted when an option is toggled. Forwards the original DOM `Event` from the checkbox input.
- `click` — `(e: "click", event: MouseEvent): void` — Emitted when one of the generated checkbox inputs is clicked. Forwards the original DOM `MouseEvent`.
- `focus` — `(e: "focus", event: FocusEvent): void` — Emitted when one of the generated checkbox inputs receives focus. Forwards the original DOM `FocusEvent`.
- `inactive` — `(e: "inactive"): void` — Emitted when focus/click moves outside the group after it was active. Useful for validation-on-blur flows at group level.
- `input` — `(e: "input", event: Event): void` — Emitted on native input events from generated checkbox inputs. Forwards the original DOM `Event`.
- `keydown` — `(e: "keydown", event: KeyboardEvent): void` — Emitted for keyboard interaction on generated checkbox inputs. Forwards the original DOM `KeyboardEvent`.
- `mousedown` — `(e: "mousedown", event: MouseEvent): void` — Emitted when a pointing device button is pressed over a checkbox input. Forwards the original DOM `MouseEvent`.
- `mouseup` — `(e: "mouseup", event: MouseEvent): void` — Emitted when a pointing device button is released over a checkbox input. Forwards the original DOM `MouseEvent`.
- `update:modelValue` — `(e: "update:modelValue", value: any): void` — Emitted with the coherent next selection array whenever selection changes.

## Slots

- `append` — scope: `object` — Content rendered after the last option, inside the options container.
- `icon` — scope: `BbSwitchGroupIconSlotProps<T>` — Replaces the default switch track visual for each option. Receives all `BaseSwitch` slot attributes plus the source item and its display text.
- `label` — scope: `BbSwitchGroupLabelSlotProps<T>` — Replaces the default label text for each option.
- `legend` — scope: `BbSwitchGroupLegendSlotProps` — Replaces the default fieldset legend text for the group.
- `loading` — scope: `object` — Content shown while options are loading (replaces the default loading text).
- `no-data` — scope: `object` — Content shown when no options are available (replaces the default "no data" text).
- `prepend` — scope: `object` — Content rendered before the first option, inside the options container.

## Validated variant

Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).

| Prop | Type | Description |
| --- | --- | --- |
| `rules` | `RuleExpression<any>` | vee-validate rules for this field. |
| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |

## See Also

- [BbSwitch](./BbSwitch.md) — Toggles two-state values with switch semantics.
- [BbCheckboxGroup](./BbCheckboxGroup.md) — Manages multiple checkbox options as a group.
- [BbRadioGroup](./BbRadioGroup.md) — Coordinates exclusive selection among radio options.

---

<!-- dist/ai/BbTable.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTable.md -->

# BbTable

## Agent Contract

- Safety level: **Consumer API**
- Group: **Data Display**
- Description: Displays tabular data, configurable columns and data mapper.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbTable.md](./source/BbTable.md)

## Usage & Guidelines

### When to use

Reach for `BbTable` to present **rows of records with columns** — an invoices
listing, a members admin, an audit log. It owns extraction, formatting, loading
skeletons, empty states, selection, sorting indicators, row expansion and
keyboard navigation, so your markup stays a column definition plus a few slots.

- For a **single-select or multi-select list of options** in a form, use
  `BbSelect` / `BbCheckboxGroup` / `BbRadioGroup` — not a selectable table.
- For **hierarchical, expandable nodes** (a file tree, nested categories), use
  `BbTree`. Flat rows with one level of detail stay in `BbTable` (`#expand`).
- `BbTable` is items-driven: read the Options/Items and Fetch playbooks. Pass
  domain objects straight to `items` and set `item-value` for stable row
  identity — never pre-map rows into `{ label, value }` shapes.

The table **reports** state (sort, column order, selection, page, expansion,
highlight) through v-models; it never sorts, slices, or fetches on its own. You apply
that state to your data source (client-side or via `dependencies`-driven
refetch). This keeps it equally at home in a client-only screen and a
server-paginated one.

**Every row in `items` mounts to the DOM unless you say `virtual`.** A few
hundred rows is fine for a client-only screen. Past roughly 1,000 rows,
either page it — feed `BbTable` the current slice as `items` and pass `page`
/ `per-page` / `total-items` (see § Pagination) so the server, not the DOM,
holds the rest — or, when the whole dataset legitimately lives in the
browser (local filtering, a spreadsheet-shaped tool), add `virtual` and let
the table window its rows (see § Virtual rows). The two compose: a large
page can be windowed.

### Columns: the full grammar

A column is `{ key, label }` plus optional presentation — everything a cell
needs is declared here, not in markup:

- **`key`** extracts the cell from the item; dot paths reach nested fields
  (`'customer.address.city'`). Keys autocomplete from the item type (up to 3
  levels deep), but any string is accepted — that is how virtual columns work.
- **`formatter(content, key, item)`** transforms the extracted value. It runs
  even when the value is nullish, so a virtual column whose `key` matches no
  field can still compute from `item`; set `formatOnNull: false` when a
  formatter must only see real values.
- **`placeholder`** fills the cell when the pipeline still ends nullish.
- **`align`** (`'left' | 'center' | 'right'`) per column; the table-level
  `align` prop sets the default for the whole table (`left`).
- **`width`** freezes the column: numbers and bare numeric strings are px
  (`130`, `'130'`); anything carrying a unit passes through (`'12rem'`,
  `'20%'`). A declared width is the column's grid track and holds exactly;
  unfrozen columns size to their content and share any leftover space equally
  (the table is a CSS grid — the tracks are the width API, there is no
  `table-layout`). When _every_ column declares a width, the surplus is shared
  in proportion to the declared widths so the table still fills its container.
- **`skeleton`** picks the loading placeholder shape (see Loading below).
- **`sortable` / `sorted`** — see Sorting.
- **`thClass` / `tdClass` / `rowClass`** style the header cell, the data cells,
  and the whole row. `tdClass` and `rowClass` may be functions
  `(content, key, item) => Classes` for state-dependent styling. Table-level
  `thClass` / `tdClass` / `rowClass` / `headerRowClass` apply everywhere; a
  row's classes accumulate the table `rowClass` plus every column's.
- **`snap`** maps a nested table's column onto its parent's tracks — see
  Nested tables.

**Columns, formatters and a per-row class**

```vue
<template>
	<div
		class="max-w-2xl overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
	>
		<BbTable
			caption="Recent invoices"
			:columns="columns"
			compact
			item-value="id"
			:items="invoices"
			:row-class="rowClass"
		/>
	</div>
</template>
<script setup lang="ts">
import { BbTable } from 'bitboss-ui';
import type { BbTableColumn } from 'bitboss-ui';

type Invoice = {
	id: string;
	number: string;
	client: string;
	issuedAt: string;
	note: string | null;
	amount: number;
	status: 'paid' | 'pending' | 'overdue';
};

const euro = new Intl.NumberFormat('en-IE', {
	style: 'currency',
	currency: 'EUR',
});

// Columns declare extraction (`key`), formatting (`formatter`), alignment and a
// fixed `width`. `placeholder` fills in when a cell resolves to nullish.
const columns: Array<BbTableColumn<Invoice>> = [
	{ key: 'number', label: 'Invoice', width: 110 },
	{ key: 'client', label: 'Client' },
	{
		key: 'issuedAt',
		label: 'Issued',
		width: 100,
		formatter: (value: string) => new Date(value).toLocaleDateString('en-GB'),
	},
	{ key: 'note', label: 'Note', placeholder: '—' },
	{
		key: 'amount',
		label: 'Amount',
		align: 'right',
		width: 110,
		formatter: euro.format,
	},
];

const invoices: Invoice[] = [
	{
		id: 'inv-1041',
		number: 'INV-1041',
		client: 'Northwind Traders',
		issuedAt: '2026-06-02',
		note: 'Retainer',
		amount: 4200,
		status: 'paid',
	},
	{
		id: 'inv-1042',
		number: 'INV-1042',
		client: 'Globex',
		issuedAt: '2026-06-11',
		note: null,
		amount: 980.5,
		status: 'pending',
	},
	{
		id: 'inv-1043',
		number: 'INV-1043',
		client: 'Initech',
		issuedAt: '2026-05-19',
		note: 'Overage',
		amount: 15600,
		status: 'overdue',
	},
];

// `row-class` is applied to each row (`.bb-table-data__row`); use it to flag rows by state. Soft amber
// wash matches the design-language attention accent — public API, no internals.
const rowClass = (invoice: Invoice) =>
	invoice.status === 'overdue'
		? 'bg-[color:color-mix(in_oklab,#d97706_8%,var(--bb-panel))]'
		: '';
</script>
```

A virtual column has a `key` that matches nothing and derives its content in
the formatter — use it for computed cells (totals, ratios) instead of
pre-mapping your items:

**A virtual total column computed from the row**

```vue
<BbTable
	caption="Order lines"
	:columns="[
		{ key: 'sku', label: 'SKU' },
		{ key: 'qty', label: 'Qty', align: 'right' },
		{ key: 'unitPrice', label: 'Unit €', align: 'right' },
		{
			key: 'total',
			label: 'Total €',
			align: 'right',
			formatter: (_, __, item) =>
				(item.qty * item.unitPrice).toLocaleString('en-IE'),
		},
	]"
	:items="[
		{ sku: 'CHAIR-OAK', qty: 4, unitPrice: 189 },
		{ sku: 'DESK-140', qty: 2, unitPrice: 420 },
		{ sku: 'LAMP-LED', qty: 6, unitPrice: 39 },
	]"
/>
```

**`actions` and `select` are not columns.** Both are rendered by the table
itself, from the `actions` and `selectable` props. Putting
`{ key: 'actions' }` in `columns` adds an ordinary data column that reads
`item.actions`, so you get a stray empty cell _and_ the `#actions` slot never
renders — which looks like a broken slot and is really a bad column list. Dev
builds warn.

### Custom cells and headers

Override any column's body with a `#<key>` slot and its header with a
`#header:<key>` slot. The slot name is the key with every run of non-word
characters turned into `_` (dashes are kept as-is), **lowercased**:
`address.city` → `#address_city`, `first_name` → `#first_name`, `issued-at` →
`#issued-at`, but also `issuedAt` → `#issuedat` — prefer snake_case keys so
slot names read naturally. Building slot names in code (columns from config, a
dynamic `<template>` loop)? Import the normalizer itself — `import { slotKey }
from 'bitboss-ui'` — instead of restating the rule: a hand copy that differs by
one character (`\W+` collapses dashes; the real rule keeps them) makes the slot
silently never match. Keep the column in `columns`
even when you fully slot it: label, alignment and width still come from there.

Body cell scope: `content` (the formatted value), `item` (raw row), `value`
(resolved via `item-value`), `classes`, plus the row's interaction surface —
`selected` / `toggleSelected`, `highlighted` / `toggleHighlighted`,
`expanded` / `toggleExpanded` / `expandProps`, and `sortOrder`. The flags are
one-way state; the `toggle*` callbacks are the write path.

Header scope: `label`, `items` (the full list — handy for counts), `sortable`,
`sortOrder`, `toggleSort`, `classes`.

**Add beside a header instead of replacing it** with
`#header:<key>:prepend` / `#header:<key>:append` — rendered before / after the
column's existing header content (the label + sort control, or your own
`#header:<key>` replacement), so a resize grip or reorder handle no longer
costs you the built-in sort button. The table-wide pair `#header:prepend` /
`#header:append` applies one template to every data column's header (never the
structural select/actions cells); both forms receive the header scope above
plus `columnKey` (the raw column key) so a table-wide template can branch per
column. When both a per-column and the table-wide slot are provided for the
same side, the per-column one wins for that column — they never stack. Affixes
render even beside a full `#header:<key>` replacement (the same rule as
BbDropdown's `#<key>:prepend/append`). One caveat: a column key that
normalizes to `prepend` or `append` collides with the table-wide slot names;
the table-wide interpretation wins, per-column header slots are unavailable
for that column, and dev builds warn.

Below, the status badges carry brand glyphs shipped in the app's `iconDir`,
referenced as `local:*` names on the badge's `prepend:icon`. Per the icons
policy the dynamic status maps to **full-name literals** (a lookup object) —
never a template-composed `` `local:${status}` ``. Colours use the registered
`soft-*` badge variants (design-language palette); the companion carries their
CSS in a non-scoped style block.

**Status badges and an annotated header**

```vue
<template>
	<div
		class="max-w-2xl overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
	>
		<BbTable
			caption="Invoice status"
			:columns="columns"
			compact
			item-value="id"
			:items="invoices"
		>
			<!-- Cell slot: name = the column key (dots/non-word chars become `_`,
			     dashes are kept).
			     The glyphs are brand assets from the app's `iconDir`, referenced as
			     `local:*` names — mapped to full literals, never template-composed. -->
			<template #status="{ content }">
				<BbBadge
					:prepend:icon="glyphs[content as Status]"
					size="sm"
					:variant="variants[content as Status]"
					>{{ labels[content as Status] }}</BbBadge
				>
			</template>

			<!-- Header slot: `header:` + the column key. `label` comes from the scope. -->
			<template #header:amount="{ label }">
				<span class="inline-flex items-center gap-1">
					{{ label }}
					<span class="text-xs font-normal text-[color:var(--bb-text-muted)]"
						>EUR</span
					>
				</span>
			</template>
		</BbTable>
	</div>
</template>
<script setup lang="ts">
import { BbBadge, BbTable } from 'bitboss-ui';
import type { BadgeVariantType, BbTableColumn, IconType } from 'bitboss-ui';

type Status = 'paid' | 'pending' | 'overdue';
type Invoice = {
	id: string;
	number: string;
	client: string;
	status: Status;
	amount: string;
};

const columns: Array<BbTableColumn<Invoice>> = [
	{ key: 'number', label: 'Invoice', width: 110 },
	{ key: 'client', label: 'Client' },
	{ key: 'status', label: 'Status', width: 120 },
	{ key: 'amount', label: 'Amount', align: 'right', width: 110 },
];

const labels: Record<Status, string> = {
	paid: 'Paid',
	pending: 'Pending',
	overdue: 'Overdue',
};

// Status → full-name literals (icons policy: no `local:${status}` templates).
const glyphs: Record<Status, IconType> = {
	paid: 'local:check_circle',
	pending: 'local:clock',
	overdue: 'local:alert_circle',
};

const variants: Record<Status, BadgeVariantType> = {
	paid: 'soft-green',
	pending: 'soft-amber',
	overdue: 'soft-red',
};

const invoices: Invoice[] = [
	{
		id: 'inv-1041',
		number: 'INV-1041',
		client: 'Northwind Traders',
		status: 'paid',
		amount: '€4,200.00',
	},
	{
		id: 'inv-1042',
		number: 'INV-1042',
		client: 'Globex',
		status: 'pending',
		amount: '€980.50',
	},
	{
		id: 'inv-1043',
		number: 'INV-1043',
		client: 'Initech',
		status: 'overdue',
		amount: '€15,600.00',
	},
	{
		id: 'inv-1044',
		number: 'INV-1044',
		client: 'Umbrella',
		status: 'pending',
		amount: '€2,750.00',
	},
];
</script>

<!-- Soft status palette — canonical source: ai/guides/design-language.md § Using color.
     Non-scoped so variant classes on the child badge receive the accents. -->
<style>
.bb-badge.bb-badge--soft-green {
	--accent: #16a34a;
}
.bb-badge.bb-badge--soft-amber {
	--accent: #d97706;
}
.bb-badge.bb-badge--soft-red {
	--accent: #dc2626;
}
.bb-badge.bb-badge--soft-green,
.bb-badge.bb-badge--soft-amber,
.bb-badge.bb-badge--soft-red {
	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
	--border-width: 1px;
	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
}
</style>
```

Beyond per-column slots, the structural slots cover every other region:
`#header:select` (the select-all cell content), `#header:actions`, `#select`
(replace the per-row checkbox/radio; scope: `item`, `value`, `checked`,
`disabled`, `readonly`, `inputName`, `toggleSelected`), `#loading`, `#no-data`
(both below), and `#thead` / `#tbody` / `#tfoot` to replace an entire region
when you need full control (you then own its markup and semantics: the table
is a CSS grid, so pass `<div role="row">` rows holding `<div role="cell">` /
`<div role="columnheader">` cells — never `<tr>`/`<td>`; a spanning cell uses
`grid-column: span N` with `#tfoot`'s `columnCount`, see **Styling hooks**).

### Loading and empty states

`loading` means two different things and the table tells them apart for you:

- **Nothing to show yet** (first load, or a filter that emptied the table) →
  **skeleton rows**, whose shape you tune per column with `skeleton` (`text`,
  `avatar`, `avatar-text`, `image`, `badge`). Between 4 and 10 rows, matching the
  current row count when it has one.
- **Already showing rows** (a refetch: a `dependencies` change, a poll, a
  save-then-reload) → **the rows stay put**, dimmed, with an indeterminate bar
  along the header. Blanking a populated table to skeleton on every refetch loses
  the user's place and flashes — so it doesn't.

A function `items` source triggers this automatically while it resolves; so does
the `loading` prop. `aria-busy` is set on the table in both cases, and the
`loading-text` announcement fires in both.

**While loading, the header and the rows are `inert`** — a refetch is about to
replace the rows, so editing, selecting or sorting them races the incoming data.
Same shape as `BbButton`: blocked by default, with `interactive-while-loading` as the
escape hatch for tables that must stay usable during a background refresh (a poll
that must not interrupt an open editor, say). The loading announcement is never
inert, so the busy state is always conveyed.

The `#loading` slot replaces the **skeleton**, so it follows the skeleton's rule:
it renders only when there is nothing to keep. (Scope: the current, possibly
stale `items` — handy for matching the previous row count.) When `items` resolves
empty the table shows its no-data row — localized default text, overridable via
`no-data-text` or fully via the `#no-data` slot. That slot fills the table's own
full-width empty-state cell (already centred, already spanning every column),
so pass the content — a message, a "clear filters" button — not a row of your
own.

`loading-text` is the loading row's `aria-live` announcement. Like
`no-data-text` it has a **localized default** (`common.loadingText` —
"Loading…", translated in every shipped locale), so omitting it still
announces. Unlike `no-data-text` it is `sr-only`: it is never painted, the
skeleton carries the visual signal. Set it when a table-specific message beats
the generic one ("Loading invoices…"), not to avoid an empty announcement.

There is no `error-text` prop and no `empty-text` alias — don't guess either
by analogy with `loading-text`. There is also no table-level error state: a
failed _server_ visit (Inertia, a full-page load) is a full error page, not
something the table renders inline. For a failed _client-side_ fetch (an
`items` provider function that rejects), catch it yourself and render the
failure through the `#no-data` slot — it's the one slot the table gives you
for "there is nothing to show, here's why."

**Skeletons and a custom empty state**

```vue
<template>
	<div class="flex max-w-2xl flex-col gap-2">
		<div class="flex gap-1.5">
			<BbButton size="sm" variant="outline" @click="loading = !loading">
				Toggle loading
			</BbButton>
			<BbButton size="sm" variant="ghost" @click="empty = !empty">
				Toggle empty
			</BbButton>
		</div>

		<div
			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
		>
			<BbTable
				caption="Team members"
				:columns="columns"
				compact
				item-value="id"
				:items="empty ? [] : members"
				:loading="loading"
				loading-text="Loading members…"
			>
				<template #no-data>
					<p class="p-3 text-center text-sm text-[color:var(--bb-text-muted)]">
						No members match your filters yet.
					</p>
				</template>
			</BbTable>
		</div>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbTable } from 'bitboss-ui';
import type { BbTableColumn } from 'bitboss-ui';

type Member = { id: string; name: string; email: string; role: string };

// `skeleton` shapes each column's placeholder while `loading` is true so the
// skeleton mirrors the real content (avatar + text, a badge, plain text).
const columns: Array<BbTableColumn<Member>> = [
	{ key: 'name', label: 'Name', skeleton: 'avatar-text' },
	{ key: 'email', label: 'Email' },
	{ key: 'role', label: 'Role', skeleton: 'badge', width: 90 },
];

const members: Member[] = [
	{ id: 'u1', name: 'Ada Lovelace', email: 'ada@acme.io', role: 'Admin' },
	{ id: 'u2', name: 'Grace Hopper', email: 'grace@acme.io', role: 'Editor' },
	{ id: 'u3', name: 'Ken Thompson', email: 'ken@acme.io', role: 'Viewer' },
];

const loading = ref(false);
const empty = ref(false);
</script>
```

### Async items and filters

Set `items` to a provider function and the table runs it, tracking loading
itself:

```ts
type ItemsProvider<T> = (
	prefill: boolean,
	selected?: any // the current selection (v-model)
) => T[] | Promise<T[]>;
```

- On mount it is called `(true, selection)`; when `dependencies` (or the
  `items` prop itself) change it is called `(false, selection)`, debounced by
  `deps-debounce-time`.
- `dependencies` are compared **by value** (hashed), so `[filters]` refetches
  only when content actually changes. Never wire a manual
  `watch(filter, refetch)` — that is exactly what `dependencies` replaces.
- Out-of-order responses are discarded (only the latest request writes rows);
  a rejected provider is logged via `console.error` and the previous rows are
  kept — surface failures yourself (e.g. `useToast`) if the user must know.
- A plain array bypasses the provider machinery entirely.

**Debounced search through the items function**

```vue
<template>
	<div class="flex max-w-2xl flex-col gap-2">
		<BbTextInput
			v-model="search"
			clearable
			compact
			label="Search invoices"
			label-mode="outside"
			placeholder="Client or number…"
		/>

		<!-- `items` is an async function; the table re-runs it (debounced) whenever
		     an entry in `dependencies` changes, showing skeletons while it awaits. -->
		<div
			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
		>
			<BbTable
				caption="Invoices"
				:columns="columns"
				compact
				:dependencies="[search]"
				:deps-debounce-time="300"
				item-value="id"
				:items="fetchInvoices"
				loading-text="Searching…"
			/>
		</div>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbTable, BbTextInput } from 'bitboss-ui';
import type { BbTableColumn } from 'bitboss-ui';

type Invoice = { id: string; number: string; client: string; amount: string };

const columns: Array<BbTableColumn<Invoice>> = [
	{ key: 'number', label: 'Invoice', width: 110 },
	{ key: 'client', label: 'Client' },
	{ key: 'amount', label: 'Amount', align: 'right', width: 100 },
];

const catalogue: Invoice[] = [
	{
		id: '1',
		number: 'INV-1041',
		client: 'Northwind Traders',
		amount: '€4,200',
	},
	{ id: '2', number: 'INV-1042', client: 'Globex', amount: '€980' },
	{ id: '3', number: 'INV-1043', client: 'Initech', amount: '€15,600' },
	{ id: '4', number: 'INV-1044', client: 'Umbrella', amount: '€2,750' },
];

const search = ref('');

// Real apps forward the query to the backend; here we filter a local catalogue
// after a short simulated round-trip.
const fetchInvoices = async (): Promise<Invoice[]> => {
	await new Promise((resolve) => setTimeout(resolve, 250));
	const term = search.value.trim().toLowerCase();
	if (!term) return catalogue;
	return catalogue.filter(
		(invoice) =>
			invoice.client.toLowerCase().includes(term) ||
			invoice.number.toLowerCase().includes(term)
	);
};
</script>
```

On a server-paginated screen the provider forwards filters, sort and page to
the backend and returns the current slice:

```ts
const fetchInvoices = async (): Promise<Invoice[]> => {
	const res = await api.invoices.list({
		search: search.value,
		status: status.value,
		orderBy: sort.value, // the v-model:sort array, forwarded as-is
		page: page.value,
		perPage,
	});
	totalItems.value = res.total;
	return res.data;
};
// dependencies: [search, status, sort]
// page is NOT listed: a provider table already refetches when the shared
// (table-id) page moves — list only your own filters and sort here.
```

This is the shape of every server-driven listing — the full assembly (filters,
pagination, confirm-delete, toasts) is the records workspace recipe
(`./recipes/vue/records-workspace.md`), which works unchanged under Inertia or
Nuxt since the table itself never touches the router.

### Pagination

`BbTable` never slices its own data — you do, or the server does. Feed it the
current slice as `items` and pass `page` / `per-page` / `total-items` so it
can announce `aria-rowcount` and per-row absolute indices (when `items` is an
array, `per-page` and `total-items` default to its length — so a one-page
table is accessible with just `page`). Pair it with `BbPagination` bound to
the same page ref.

**BbPagination alongside the table**

```vue
<template>
	<div class="flex max-w-2xl flex-col gap-2">
		<!-- `page` / `per-page` / `total-items` power the table's accessibility
		     announcements (aria-rowcount / aria-rowindex); the actual slicing is
		     yours (or the server's). -->
		<div
			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
		>
			<BbTable
				caption="Invoices"
				:columns="columns"
				compact
				item-value="id"
				:items="pageRows"
				:page="page"
				:per-page="perPage"
				:total-items="invoices.length"
			/>
		</div>
		<div class="flex items-center justify-between gap-2">
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				{{ rangeStart }}–{{ rangeEnd }} of {{ invoices.length }}
			</p>
			<BbPagination v-model="page" :total-pages="totalPages" />
		</div>
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbPagination, BbTable } from 'bitboss-ui';
import type { BbTableColumn } from 'bitboss-ui';

type Invoice = { id: string; number: string; client: string; amount: string };

const columns: Array<BbTableColumn<Invoice>> = [
	{ key: 'number', label: 'Invoice', width: 110 },
	{ key: 'client', label: 'Client' },
	{ key: 'amount', label: 'Amount', align: 'right', width: 100 },
];

const invoices: Invoice[] = Array.from({ length: 13 }, (_, index) => ({
	id: String(index + 1),
	number: `INV-${1041 + index}`,
	client: ['Northwind Traders', 'Globex', 'Initech', 'Umbrella'][index % 4],
	amount: `€${((index + 1) * 640).toLocaleString('en-IE')}`,
}));

const perPage = 5;
const page = ref(1);
const totalPages = computed(() => Math.ceil(invoices.length / perPage));
const rangeStart = computed(() => (page.value - 1) * perPage + 1);
const rangeEnd = computed(() =>
	Math.min(page.value * perPage, invoices.length)
);

const pageRows = computed(() =>
	invoices.slice((page.value - 1) * perPage, page.value * perPage)
);
</script>
```

For no-prop-drilling wiring, give the table an `id` and the pagination a
matching `table-id`: both join the same table context and stay in sync without
a shared ref. The pagination props are symmetric across the pair — `page` /
`per-page` / `total-items` / `total-pages` are accepted by both components and
publish into the same context, so the server's fields go to whichever one is
convenient. `total-pages` is a seed for when no row count is known (an
externally paged array table, or a server that only reports a page count): a
count derived from a real `total-items` always wins over it. Add `navigation`
to `BbPagination` to mirror the page in the URL query. The same context is
scriptable from anywhere via `useBbTableContext`
(`./composables/useBbTableContext.md`).

### Sorting

Mark columns `sortable` and bind `v-model:sort` — an ordered
`BbTableSortEntry[]` (`[columnKey, 'asc' | 'desc']`). A click anywhere on a
sortable header (its whitespace included — AG Grid parity; the built-in
button is the keyboard/AT control) cycles the column unsorted → asc → desc →
removed; a direction flip updates the entry in
place, so the column keeps its priority in a multi-column sort and other
entries are never touched. The array order **is** the priority: first entry
sorts first. The table only reports the model; **apply it to your data**
(client-side, as below) or forward it to the server as `orderBy` and refetch
via `dependencies`.

The affordance is one arrow: nothing at rest, a faint arrow previewed while
the header is hovered or focused, solid once the column is sorted (up for
ascending, down for descending — the AG Grid convention), gone again on the
third click.

**Sortable headers driving a client-side sort**

```vue
<template>
	<div class="flex max-w-2xl flex-col gap-1.5">
		<!-- Mark columns `sortable` and bind `v-model:sort`. The header buttons
		     cycle asc → desc → off; the table only REPORTS the model — you sort
		     the data. -->
		<div
			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
		>
			<BbTable
				v-model:sort="sort"
				caption="Invoices"
				:columns="columns"
				compact
				item-value="id"
				:items="sortedInvoices"
			/>
		</div>
		<p class="text-xs text-[color:var(--bb-text-muted)]">
			Sort model: <code>{{ JSON.stringify(sort) }}</code>
		</p>
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbTable } from 'bitboss-ui';
import type { BbTableColumn, BbTableSortEntry } from 'bitboss-ui';

type Invoice = { id: string; number: string; client: string; amount: number };

const euro = new Intl.NumberFormat('en-IE', {
	style: 'currency',
	currency: 'EUR',
});

const columns: Array<BbTableColumn<Invoice>> = [
	{ key: 'number', label: 'Invoice', sortable: true, width: 110 },
	{ key: 'client', label: 'Client', sortable: true },
	{
		key: 'amount',
		label: 'Amount',
		align: 'right',
		sortable: true,
		width: 110,
		formatter: euro.format,
	},
];

const invoices: Invoice[] = [
	{ id: '1', number: 'INV-1041', client: 'Northwind Traders', amount: 4200 },
	{ id: '2', number: 'INV-1042', client: 'Globex', amount: 980 },
	{ id: '3', number: 'INV-1043', client: 'Initech', amount: 15600 },
	{ id: '4', number: 'INV-1044', client: 'Umbrella', amount: 2750 },
];

const sort = ref<BbTableSortEntry[]>([['amount', 'desc']]);

// Apply the ordered sort model to the data — first entry wins ties first.
const sortedInvoices = computed(() => {
	if (!sort.value.length) return invoices;
	return [...invoices].sort((a, b) => {
		for (const [key, direction] of sort.value) {
			const left = a[key as keyof Invoice];
			const right = b[key as keyof Invoice];
			const compared =
				typeof left === 'number' && typeof right === 'number'
					? left - right
					: String(left).localeCompare(String(right));
			if (compared !== 0) return direction === 'asc' ? compared : -compared;
		}
		return 0;
	});
});
</script>
```

A custom `#header:<key>` slot replaces the built-in sort button, but its scope
hands you `sortOrder` and `toggleSort` so your header can keep sorting alive
(render your own button and call `toggleSort`). To merely add something next
to the control — a resize grip, a filter icon — use
`#header:<key>:prepend/append` instead and keep the built-in button (see
"Custom cells and headers"). The column-level `sorted`
field only seeds the header's `aria-sort` when no live model entry exists — it
does not move the visual indicator; to start pre-sorted, seed `v-model:sort`
instead (as the example does).

### Column order

`columns` declares what a column **is**; `v-model:order` is the order
it **renders** in — an array of column keys, the same split as `sortable` +
`v-model:sort`. Two things write it:

- **Your own control** — a column panel, a settings drawer, a persisted
  preference. Bind the model and write the array; the table follows. No flag
  needed for this.
- **The user, on the table** — with `reorderable`, every data header
  is a grab surface: drag it and the column moves live under the pointer (AG
  Grid style, a chip with the label follows), release to commit. The same
  header row is also one keyboard tab stop (the AG Grid grammar): ←/→ move
  focus between headers, **Shift+←/→** move the column one slot
  (Shift+Home/End to the ends), Enter sorts a sortable header.
  Each committed move writes the model once and is announced.

The model's contract is what makes a column panel trivial:

- Keys listed first render first; declared columns the array omits follow, in
  declaration order (a column added to `columns` later renders last).
- Keys that match no declared column render nothing but are **preserved in
  place**. So hide a column by filtering it out of `columns` — never out of
  the order — and it comes back exactly where it was.
- A user move relocates **exactly one key**; everything else, hidden keys
  included, keeps its relative order. The first move on a partial (or empty)
  model emits the completed array — persist that.
- A drop that changes nothing emits nothing; unbound, the table keeps the
  order as per-mount state like `sort`.

**A column panel and the header drag sharing one order**

```vue
<template>
	<div class="flex max-w-2xl flex-col gap-3">
		<!-- ONE order, two writers: the panel's buttons and the table's own
		     header drag / keyboard handles both write `v-model:order`.
		     Hiding a column only filters `columns` — its key stays in the order,
		     so it comes back where it was. -->
		<ul
			aria-label="Columns"
			class="flex flex-wrap gap-2 text-xs text-[color:var(--bb-text-muted)]"
		>
			<li
				v-for="(column, index) in panelColumns"
				:key="column.key"
				class="flex items-center gap-1 rounded-[var(--bb-radius-sm)] border border-[color:var(--bb-border)] py-0.5 pl-2 pr-1"
			>
				<BbCheckbox
					:label="column.label"
					:model-value="!hidden.has(column.key)"
					@update:model-value="toggleVisible(column.key)"
				/>
				<BbButton
					:aria-label="`Move ${column.label} left`"
					:disabled="index === 0"
					icon="lucide:chevron-left"
					size="xs"
					variant="ghost"
					@click="move(column.key, -1)"
				/>
				<BbButton
					:aria-label="`Move ${column.label} right`"
					:disabled="index === panelColumns.length - 1"
					icon="lucide:chevron-right"
					size="xs"
					variant="ghost"
					@click="move(column.key, 1)"
				/>
			</li>
		</ul>
		<div
			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
		>
			<BbTable
				v-model:order="order"
				caption="Invoices"
				:columns="visibleColumns"
				compact
				item-value="id"
				:items="invoices"
				reorderable
			/>
		</div>
		<p class="text-xs text-[color:var(--bb-text-muted)]">
			Order model: <code>{{ JSON.stringify(order) }}</code>
		</p>
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbButton, BbCheckbox, BbTable } from 'bitboss-ui';
import type { BbTableColumn } from 'bitboss-ui';

type Invoice = {
	id: string;
	number: string;
	client: string;
	issued: string;
	amount: number;
};

const euro = new Intl.NumberFormat('en-IE', {
	style: 'currency',
	currency: 'EUR',
});

// The declaration: what a column IS. Never reordered.
const columns: Array<BbTableColumn<Invoice>> = [
	{ key: 'number', label: 'Invoice', width: 110 },
	{ key: 'client', label: 'Client' },
	{ key: 'issued', label: 'Issued', width: 110 },
	{
		key: 'amount',
		label: 'Amount',
		align: 'right',
		width: 110,
		formatter: euro.format,
	},
];

const invoices: Invoice[] = [
	{
		id: '1',
		number: 'INV-1041',
		client: 'Northwind Traders',
		issued: '2026-08-02',
		amount: 4200,
	},
	{
		id: '2',
		number: 'INV-1042',
		client: 'Globex',
		issued: '2026-08-05',
		amount: 980,
	},
	{
		id: '3',
		number: 'INV-1043',
		client: 'Initech',
		issued: '2026-08-11',
		amount: 15600,
	},
	{
		id: '4',
		number: 'INV-1044',
		client: 'Umbrella',
		issued: '2026-08-19',
		amount: 2750,
	},
];

// The state: render order (keys). Persist THIS. Seed it with the full key
// list — it also completes itself on the first move.
const order = ref<string[]>(columns.map((column) => column.key));
const hidden = ref(new Set<string>());

// Visibility is just filtering the declaration; the hidden key keeps its
// slot in `order`.
const visibleColumns = computed(() =>
	columns.filter((column) => !hidden.value.has(column.key))
);

// The panel lists every declared column in the order the model has them.
const panelColumns = computed(() =>
	[...columns].sort(
		(a, b) => order.value.indexOf(a.key) - order.value.indexOf(b.key)
	)
);

const toggleVisible = (key: string) => {
	const next = new Set(hidden.value);
	if (next.has(key)) next.delete(key);
	else next.add(key);
	hidden.value = next;
};

const move = (key: string, delta: 1 | -1) => {
	const next = [...order.value];
	const from = next.indexOf(key);
	const to = from + delta;
	if (from < 0 || to < 0 || to >= next.length) return;
	next.splice(from, 1);
	next.splice(to, 0, key);
	order.value = next;
};
</script>
```

**Pinned slots are positions, not columns.** `fixed-columns` indexes rendered
slots like a spreadsheet's freeze panes (a selection column is slot 0). With
column order the slot holds: whichever column lands in it is pinned, and
dragging the identity column out of its pinned slot (slot 1 when
`selectable`, slot 0 otherwise) unpins it (AG Grid pins columns; BbTable
pins positions). Keep the reorder + pin combination for slots that
never move — `select`, `actions`, or a first column you also lock by
normalizing the model in your `@update:order` handler.

**Nested tables.** An inheriting child aligns to the parent's rails by
**position**, so a reordered parent re-pairs the child's columns unless the
child follows. Give both tables the same `v-model:order` when they
share keys (and the child declares no `snap`) and they stay paired by key.
`snap` points are positional in the parent's rendered order: reorder the
parent and a snap-mapped child follows its slots, but never reorder (or share
the order with) the snap-mapped child itself — dev builds warn.

Apply the model synchronously in your handler and persist afterwards: an
`await` before the write moves the cell in a later flush, after the table
has re-focused the handle, and keyboard focus is usually lost (whether it
survives depends on which cell Vue's keyed patch detaches).

### Selection and bulk actions

Add `selectable` for multi-select (`multiple` is the default) bound with
`v-model` — the model **must** be an array in multiple mode (the table throws
otherwise). With `item-value` set, the model holds ids rather than whole rows.
Pass `selectable` a predicate (`(item) => boolean`) to gate specific rows: the
excluded rows' controls disable and `toggleSelected` refuses them too.

To drive a toolbar that lives **outside** the table subtree, give the table an
`id` and read `useBbTableContext(id).selected` — the handle mirrors the
table's selection both ways, so a bulk-action bar needs no prop drilling. As
everywhere in the library, the destructive bulk action is gated by
`useConfirm` before it touches the data.

**Multi-select with a context-driven bulk bar**

```vue
<template>
	<div class="flex max-w-2xl flex-col gap-2">
		<!-- Bulk-action bar lives OUTSIDE the table and reads the selection through
		     the shared context by id — no prop drilling. The destructive action is
		     gated by `useConfirm`. -->
		<div
			v-if="selectedCount"
			class="flex items-center gap-2 rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] bg-[color:var(--bb-muted)] px-2.5 py-1.5"
		>
			<span class="text-sm">{{ selectedCount }} selected</span>
			<BbButton
				prepend:icon="lucide:trash-2"
				size="sm"
				variant="destructive"
				@click="removeSelected"
			>
				Delete
			</BbButton>
			<BbButton size="sm" variant="ghost" @click="clear">Clear</BbButton>
		</div>

		<div
			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
		>
			<BbTable
				id="member-selection"
				v-model="selected"
				caption="Team members"
				:columns="columns"
				compact
				item-value="id"
				:items="members"
				legend="Select team members"
				name="members"
				selectable
			/>
		</div>

		<!--
			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
			mount none. See ai/guides/agent-contract.md § Global Host Rule.
		-->
		<BbConfirm />
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import {
	BbButton,
	BbConfirm,
	BbTable,
	useBbTableContext,
	useConfirm,
} from 'bitboss-ui';
import type { BbTableColumn } from 'bitboss-ui';

type Member = { id: string; name: string; email: string; role: string };

const columns: Array<BbTableColumn<Member>> = [
	{ key: 'name', label: 'Name' },
	{ key: 'email', label: 'Email' },
	{ key: 'role', label: 'Role', width: 90 },
];

const members = ref<Member[]>([
	{ id: 'u1', name: 'Ada Lovelace', email: 'ada@acme.io', role: 'Admin' },
	{ id: 'u2', name: 'Grace Hopper', email: 'grace@acme.io', role: 'Editor' },
	{
		id: 'u3',
		name: 'Margaret Hamilton',
		email: 'maggie@acme.io',
		role: 'Viewer',
	},
	{ id: 'u4', name: 'Ken Thompson', email: 'ken@acme.io', role: 'Editor' },
]);

// `item-value="id"` gives rows a stable identity, so `selected` holds ids.
const selected = ref<string[]>([]);

// Same id as the table — the handle mirrors the table's selection both ways.
const ctx = useBbTableContext('member-selection', { selected: [] });
const selectedCount = computed(() => ctx.selected.value?.length ?? 0);
const clear = () => (ctx.selected.value = []);

const { confirm } = useConfirm();

// Destructive bulk action: `await` the decision, act only on a yes.
const removeSelected = async () => {
	const ids: string[] = ctx.selected.value ?? [];
	const ok = await confirm({
		title: `Delete ${ids.length} ${ids.length === 1 ? 'member' : 'members'}?`,
		text: 'They will lose access to this workspace immediately.',
		variant: 'destructive',
		yes: { text: 'Delete', 'prepend:icon': 'lucide:trash-2' },
		no: 'Cancel',
	});
	if (!ok) return;
	members.value = members.value.filter((member) => !ids.includes(member.id));
	clear();
};
</script>
```

More selection surface, all verified behavior:

- Every body slot exposes `toggleSelected`, so a bespoke control (a whole-row
  button, a status chip) drives selection through the same path as the
  checkbox — it even works without `selectable` (that prop only governs the
  built-in selection column); explicit blocks (`disabled`, `readonly`, a
  predicate exclusion) still apply.
- `item:selected` / `item:unselected` fire with the toggled row's value on
  every user toggle — use them for per-row side effects; keep `v-model` as
  the state.
- A selectable table renders as a `<fieldset>`; give it a `legend` — the
  fieldset's accessible name. Omit it and the table falls back to `caption`,
  then a generic localized string, so the grouping is never nameless, but a
  specific `legend` beats both fallbacks. With `name` set, each selected
  value renders a hidden input (objects are JSON-stringified), so the table
  submits inside a plain HTML form.
- `disabled` makes the whole table inert; `readonly` leaves controls focusable
  but ignores changes.

#### Selection across refetches

By default a `dependencies`-driven refetch replaces the rows but leaves
`v-model` untouched, so ids that just left the result set silently stay
selected. Set **`enforce-coherence`** — the same prop, same meaning as on the
selects and option groups — and after every load the table prunes its
row-keyed models of values whose row is gone: `v-model`,
`v-model:unselected-items`, `v-model:highlighted` and
`v-model:expanded-items`. Values whose rows survive the refetch stay put;
single-value models (`:multiple="false"`, single highlight) reset to `null`.
Set `item-value` so the match runs on stable identity.

One hard exclusion: **never combine it with pagination fed through
`dependencies`**. Every page turn is a refetch, so state held on rows of other
pages — cross-page selections, the whole `select-all` + `unselected-items`
pattern — would be pruned away. For paginated tables (or any custom rule),
reconcile in the provider instead: the table calls it `(prefill, selected)`
with the current selection, which is exactly where the new rows are known.

**Provider-side reconciliation, for when enforce-coherence doesn't fit**

```vue
<template>
	<div class="flex max-w-2xl flex-col gap-2">
		<div class="flex items-center gap-1.5">
			<!-- Mirrored `false-value`: one role filter is always active. -->
			<BbButton
				v-for="filter in roleFilters"
				:key="filter.value"
				v-model="role"
				:false-value="filter.value"
				group
				size="xs"
				:true-value="filter.value"
				variant="outline"
			>
				{{ filter.label }}
			</BbButton>
			<span class="ml-auto text-xs text-[color:var(--bb-text-muted)]">
				{{ selected.length }} selected
			</span>
		</div>

		<!-- The role change refetches via `dependencies`. `enforce-coherence`
		     would prune `v-model` for free here — this example keeps it off to
		     show the provider-side reconcile, the pattern paginated tables
		     (where the prop must stay off) still need. -->
		<div
			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
		>
			<BbTable
				v-model="selected"
				caption="Workspace members"
				:columns="columns"
				compact
				:dependencies="[role]"
				:deps-debounce-time="100"
				item-value="id"
				:items="fetchMembers"
				legend="Select members"
				loading-text="Loading members…"
				selectable
			/>
		</div>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbTable } from 'bitboss-ui';
import type { BbTableColumn } from 'bitboss-ui';

type Role = 'Admin' | 'Editor' | 'Viewer';
type RoleFilter = 'all' | Role;
type Member = { id: string; name: string; email: string; role: Role };

const roleFilters: Array<{ label: string; value: RoleFilter }> = [
	{ label: 'All', value: 'all' },
	{ label: 'Admins', value: 'Admin' },
	{ label: 'Editors', value: 'Editor' },
];

const columns: Array<BbTableColumn<Member>> = [
	{ key: 'name', label: 'Name' },
	{ key: 'email', label: 'Email' },
	{ key: 'role', label: 'Role', width: 90 },
];

const directory: Member[] = [
	{ id: 'u1', name: 'Ada Lovelace', email: 'ada@acme.io', role: 'Admin' },
	{ id: 'u2', name: 'Grace Hopper', email: 'grace@acme.io', role: 'Editor' },
	{
		id: 'u3',
		name: 'Margaret Hamilton',
		email: 'maggie@acme.io',
		role: 'Editor',
	},
	{ id: 'u4', name: 'Ken Thompson', email: 'ken@acme.io', role: 'Viewer' },
	{ id: 'u5', name: 'Barbara Liskov', email: 'barbara@acme.io', role: 'Admin' },
];

const role = ref<RoleFilter>('all');
const selected = ref<string[]>([]);

// Without `enforce-coherence` a refetch replaces the rows but leaves the
// selection untouched. The table calls the provider `(prefill, selected)`,
// so the provider is the one spot where both the current selection and the new
// rows are known — drop the ids that left the result set. Reconcile on every
// call, not just refetches: `prefill` is `true` for every fetch a component
// starts itself, so it can't tell an initial load from a `dependencies` refetch
// (only a user-typed query reads `false`, and a table has no search field).
const fetchMembers = async (
	_prefill: boolean,
	selectedIds?: string[]
): Promise<Member[]> => {
	await new Promise((resolve) => setTimeout(resolve, 200));
	const rows =
		role.value === 'all'
			? directory
			: directory.filter((member) => member.role === role.value);
	if (selectedIds?.length) {
		selected.value = selectedIds.filter((id) =>
			rows.some((member) => member.id === id)
		);
	}
	return rows;
};
</script>
```

### Single select, select-all and limits

`:multiple="false"` renders radios and the model becomes one value (or
`null`). Label the radio column with `select-text` (visually hidden).

**Pick one plan via radio rows**

```vue
<template>
	<div class="flex max-w-xl flex-col gap-1.5">
		<!-- `:multiple="false"` renders radios and the model is ONE value (or
		     null) — not an array. `select-text` labels the radio column for
		     screen readers. -->
		<div
			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
		>
			<BbTable
				v-model="planId"
				caption="Available plans"
				:columns="columns"
				compact
				item-value="id"
				:items="plans"
				legend="Choose a plan"
				:multiple="false"
				name="plan"
				select-text="Choose a plan"
				selectable
			/>
		</div>
		<p class="text-sm text-[color:var(--bb-text-muted)]">
			Chosen plan:
			<span class="font-medium text-[color:var(--bb-text)]">{{
				chosen ? chosen.name : 'none yet'
			}}</span>
		</p>
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbTable } from 'bitboss-ui';
import type { BbTableColumn } from 'bitboss-ui';

type Plan = { id: string; name: string; seats: string; price: string };

const columns: Array<BbTableColumn<Plan>> = [
	{ key: 'name', label: 'Plan' },
	{ key: 'seats', label: 'Seats', width: 110 },
	{ key: 'price', label: 'Price / month', align: 'right', width: 120 },
];

const plans: Plan[] = [
	{ id: 'starter', name: 'Starter', seats: 'Up to 3', price: '€0' },
	{ id: 'growth', name: 'Growth', seats: 'Up to 25', price: '€49' },
	{ id: 'scale', name: 'Scale', seats: 'Unlimited', price: '€199' },
];

// Single-select model: one id (via `item-value`) or null.
const planId = ref<string | null>(null);

const chosen = computed(() => plans.find((plan) => plan.id === planId.value));
</script>
```

`max` caps a multi-select: once reached, every unselected row's checkbox
disables until something is deselected.

Multi-select tables show a **select-all** checkbox in the header
(`v-model:select-all`; hide it with `disable-select-all`, relabel with
`select-all-label`). Select-all is designed for the server-side "all across
pages" pattern: when it is on, every row reads as selected and unchecking a
row adds its value to `v-model:unselected-items` — so your bulk endpoint
receives `{ all: true, except: unselectedItems }` instead of thousands of ids.
Toggling select-all clears both `modelValue` and `unselected-items`; the
header checkbox shows an indeterminate state for partial selections.

One real constraint to design around:

- Turning select-all on does **not** re-emit `update:modelValue` when the
  model is already empty. Treat `select-all` + `unselected-items` as the
  source of truth in all-mode; don't infer "everything selected" from
  `modelValue`.

**Native `<form>` submission + select-all:** the table renders one hidden
input per value in `modelValue`, so a plain form POST works for explicit
selections. It does **not** serialize the select-all/exclusion pattern — in
all-mode `modelValue` is empty, so the form posts nothing even though every
row appears selected. For "all across pages", submit via a handler that reads
`{ all, except: unselectedItems }` from the v-models, not via native form
fields.

### Row expansion

Track open rows with `v-model:expanded-items` (an array of row values — set
`item-value` so expansion is stable across refetches) and render their detail
through the `#expand` slot, a full-width row below the main one. Trigger it
from the `#actions` slot (enable the column with `actions`, label it with
`actions-text`): the scope hands you `toggleExpanded` — a **callback** — plus
the read-only `expanded` flag. Drive open/close through the callback; the
`expanded` prop is one-way state, not something to mutate.

**Expandable detail rows**

```vue
<template>
	<!-- Track open rows with `v-model:expanded-items`. The `#actions` scope hands
	     you `toggleExpanded` (a callback) and `expanded` (read-only) — drive the
	     toggle through the callback, never by mutating the slot prop. -->
	<div
		class="max-w-2xl overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
	>
		<BbTable
			v-model:expanded-items="expanded"
			actions
			actions-text="Details"
			caption="Invoices"
			:columns="columns"
			compact
			item-value="id"
			:items="invoices"
		>
			<template #actions="{ expanded: isOpen, toggleExpanded }">
				<BbButton size="xs" variant="ghost" @click="toggleExpanded">
					{{ isOpen ? 'Hide' : 'Details' }}
				</BbButton>
			</template>

			<template #expand="{ item }">
				<div class="bg-[color:var(--bb-muted)] px-3 py-2.5 text-sm">
					<p class="font-medium">{{ item.client }} · {{ item.number }}</p>
					<p class="text-xs text-[color:var(--bb-text-muted)]">
						Issued {{ item.issuedAt }} · net 30 · {{ item.lines }} line items
					</p>
				</div>
			</template>
		</BbTable>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbTable } from 'bitboss-ui';
import type { BbTableColumn } from 'bitboss-ui';

type Invoice = {
	id: string;
	number: string;
	client: string;
	issuedAt: string;
	amount: string;
	lines: number;
};

const columns: Array<BbTableColumn<Invoice>> = [
	{ key: 'number', label: 'Invoice', width: 110 },
	{ key: 'client', label: 'Client' },
	{ key: 'amount', label: 'Amount', align: 'right', width: 100 },
];

const invoices: Invoice[] = [
	{
		id: '1',
		number: 'INV-1041',
		client: 'Northwind Traders',
		issuedAt: '02/06/2026',
		amount: '€4,200',
		lines: 6,
	},
	{
		id: '2',
		number: 'INV-1042',
		client: 'Globex',
		issuedAt: '11/06/2026',
		amount: '€980',
		lines: 2,
	},
	{
		id: '3',
		number: 'INV-1043',
		client: 'Initech',
		issuedAt: '19/05/2026',
		amount: '€15,600',
		lines: 11,
	},
];

// Holds the expanded rows' values (ids, via `item-value`).
const expanded = ref<string[]>([]);
</script>
```

For a custom toggle control, `v-bind` the scope's `expandProps` onto it: you
get `aria-expanded`/`aria-controls` kept in sync, a click handler that stops
propagation (so the row click underneath doesn't also toggle highlight), and
Enter/Space handling for non-button elements. The nested-table example below
uses it.

#### Putting the toggle in the identity cell

`expandProps` / `expanded` / `toggleExpanded` reach **every per-column cell
slot**, not just `#actions` — so a hierarchy can be driven from the name column
instead of a far-right icon. For a drill-down (owner → holdings, account →
sites) that is usually the better shape: the chevron sits where the eye already
is, and the actions column stays for actions.

```vue
<template #name="{ item, content, expanded, expandProps, toggleExpanded }">
	<span class="table-identity">
		<BbButton
			v-bind="expandProps"
			:icon="expanded ? 'lucide:chevron-down' : 'lucide:chevron-right'"
			size="xs"
			variant="ghost"
			@click="toggleExpanded"
		/>
		<BbBaseButton class="plain-link" @click="peek(item)">{{
			content
		}}</BbBaseButton>
	</span>
</template>
```

`expandProps` carries the `aria-expanded`/`aria-controls` wiring and the
keyboard handling — bind it to the control you render, wherever it lives. Rows
with nothing to expand simply render the link without the toggle; keep the
lead-in width consistent so the names still line up (`.table-identity` with a
fixed first track).

The actions-column toggle remains valid — prefer it when expansion reveals
_detail about the row_ rather than _children of it_.

### Column resize

`resizable` puts a handle on the trailing edge of every data header:
drag it and the column follows live, release to commit; double-click it to go
back to the declared width. From the keyboard, **Alt+←/→** resizes the
focused header in 10px steps (the header row is a tab stop whenever columns
are resizable or reorderable).

There is no width model on purpose. `width` on the column definition stays
the single declared truth, and a user resize is an **override** the table
keeps until that column's `width` changes:

- Each commit fires `@resize:column="(key, width) => …"` **once** with the new width
  in px — or `null` after a double-click reset.
- To persist, write the reported width back into your column definition (a
  `computed` over your persisted widths). The definition wins whenever it
  changes, so a programmatic `width` change always takes effect.
- Unbound, the override lives for the mount, like an unbound `sort`.
- A resized width is always px; `width` still accepts `'20%'` / `'12rem'`
  for what you declare yourself.

Headers never wrap. A column you have not sized is never narrower than its
own heading — the label is the table's size hint, so an empty or slim column
with a long heading still reads on a narrow screen (the table overflows
instead). Once a track is a length (a declared `width`, a user resize) the
label cannot widen it: squeezed, it ellipsizes and the sort arrow stays; at
the narrowest only the arrow (and the handle) survive, and the column is
still resizable. The data cells of a resized column clip with an ellipsis
instead of spilling into the neighbour (a squeezed track cannot wrap a single
word); every other cell keeps wrapping. While a resize runs the whole page
shows the resize cursor.

A resized column becomes an **exact** track; the other columns keep doing
what they did — unfrozen ones share the surplus, and a table whose columns
are all declared with a `width` keeps sharing it among the un-resized ones —
so a filling table stays filled and nothing collapses. **Shift+drag** moves
the border instead: the right neighbour absorbs the delta, the total stays
put, and both columns are reported. A table that inherits its widths from a
parent (`inherit-column-widths`) renders no handles — its tracks are the
parent's.

**Resizable columns reporting widths back into the definition**

```vue
<template>
	<div class="flex max-w-2xl flex-col gap-1.5">
		<div
			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
		>
			<BbTable
				caption="Invoices"
				:columns="columns"
				compact
				item-value="id"
				:items="invoices"
				resizable
				@resize:column="onResize"
			/>
		</div>
		<p class="text-xs text-[color:var(--bb-text-muted)]">
			Widths: <code>{{ JSON.stringify(widths) }}</code>
		</p>
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbTable } from 'bitboss-ui';
import type { BbTableColumn } from 'bitboss-ui';

type Invoice = { id: string; number: string; client: string; amount: number };

const base: Array<BbTableColumn<Invoice>> = [
	{ key: 'number', label: 'Invoice' },
	{ key: 'client', label: 'Client' },
	{ key: 'amount', label: 'Amount', align: 'right' },
];
// Persist THIS (localStorage, a user preference…): key → px.
const widths = ref<Record<string, number>>({});
// The definition carries the persisted widths; the table treats them as the
// declared truth, so nothing jumps after a reload.
const columns = computed(() =>
	base.map((column) => ({ ...column, width: widths.value[column.key] }))
);
const onResize = (key: string, width: number | null) => {
	const next = { ...widths.value };
	if (width === null) delete next[key];
	else next[key] = width;
	widths.value = next;
};
const invoices: Invoice[] = [
	{ id: '1', number: 'INV-1041', client: 'Northwind Traders', amount: 4200 },
	{ id: '2', number: 'INV-1042', client: 'Globex', amount: 980 },
	{ id: '3', number: 'INV-1043', client: 'Initech', amount: 15600 },
];
</script>
```

### Nested tables that align with the parent

A `BbTable` rendered inside another's `#expand` slot is independent by
default. Add `inherit-column-widths` and it snaps its columns to the parent's
tracks, so a line-items breakdown reads as a continuation of the invoice row
above it. The mechanics:

- `inherit-column-widths` — `true` inherits from the nearest ancestor table;
  a string targets a specific ancestor's `id` (useful when an intermediate
  table has a different column count).
- By default child columns map one-to-one onto the parent's data columns. A
  column's `snap` remaps it: a number is a start track (`2` occupies the
  parent's third data region), `[start, end]` spans a range (fractions
  allowed; `end: -1` runs to the end of the data region). Structural columns
  (`select`, actions) are accounted for automatically.
- A child with **more** columns than the parent content-sizes the extras and
  overflows into the parent's scroll (see below); with **fewer**, the leading
  columns stay 1:1, the actions column inherits the parent's actions width,
  and the last content column runs across every remaining parent track so
  both tables end flush (a right-aligned total lands under the parent's last
  column). Give that last column a `width` or an explicit `[start, end]`
  snap only if you want it to stop short — the leftover then joins the
  actions region instead.
- **An inheriting child does not scroll on its own — the parent's scrollport
  is the only one.** That is what keeps the two grids locked together: a child
  with its own scroll position would fall out of alignment the moment either
  one moved, which is the whole thing `inherit-column-widths` exists to
  prevent. One scrollbar moves both.
- **The parent's `selectable`/`actions` columns are handled for you** — the
  child's content columns map to the parent's content columns 1:1 (no `snap`
  needed for that), and the parent's select/actions _regions_ are reserved on
  each side: a child with its own select or actions column widens that cell
  to the parent's (two equal cells, controls at the row's end, so the ⌃ sits
  under the parent's); a child without one folds the region into its first/
  last cell as _padding_, so its content stays flush with the parent's data
  grid on both edges (the inset reads as hierarchy). Only a child cell
  _wider_ than the parent's — a select the parent lacks, more buttons — moves
  anything, and only the adjacent content column: it shrinks by the surplus
  so every other rail holds. What a child publishes to its own children is
  the same contract (content rails + regions), so a three-level nest aligns
  at every depth.
- **Scope any page-level cell-padding overrides to the parent's own cells.** A
  bare `:deep([role='cell']:first-child)` also matches the nested table's
  cells and clobbers the offset padding it computes to stay aligned — use the
  direct-child chain through the grid's containers
  (`:deep(> .bb-table__table > .bb-table__body > [role='row'] > :first-child)`)
  so the child, which lives inside `.bb-table-expand__cell`, keeps its
  structural padding. The canonical `.table-flush` idiom is under **Styling
  hooks**.

**Invoice lines aligned under the invoice columns**

```vue
<template>
	<!-- The nested table opts into `inherit-column-widths`: its columns snap to
	     the parent's tracks, so line items line up under the invoice columns.
	     The toggle binds the scope's `expandProps` for wired-up aria state. -->
	<div
		class="max-w-2xl overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
	>
		<BbTable
			v-model:expanded-items="expanded"
			actions
			actions-text="Line items"
			caption="Invoices"
			:columns="columns"
			compact
			item-value="id"
			:items="invoices"
		>
			<template #actions="{ expanded: isOpen, expandProps }">
				<BbButton
					v-bind="expandProps"
					:append:icon="isOpen ? 'lucide:chevron-up' : 'lucide:chevron-down'"
					size="xs"
					variant="ghost"
				>
					Lines
				</BbButton>
			</template>

			<template #expand="{ item }">
				<div class="bg-[color:var(--bb-muted)] px-1 py-1">
					<BbTable
						:caption="`Line items of ${item.number}`"
						:columns="lineColumns"
						compact
						inherit-column-widths
						item-value="id"
						:items="item.lines"
					/>
				</div>
			</template>
		</BbTable>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbTable } from 'bitboss-ui';
import type { BbTableColumn } from 'bitboss-ui';

type Line = { id: string; description: string; qty: number; amount: string };
type Invoice = {
	id: string;
	number: string;
	client: string;
	amount: string;
	lines: Line[];
};

const columns: Array<BbTableColumn<Invoice>> = [
	{ key: 'number', label: 'Invoice', width: 110 },
	{ key: 'client', label: 'Client' },
	{ key: 'amount', label: 'Amount', align: 'right', width: 100 },
];

const lineColumns: Array<BbTableColumn<Line>> = [
	{ key: 'description', label: 'Description' },
	{ key: 'qty', label: 'Qty', width: 60 },
	{ key: 'amount', label: 'Amount', align: 'right', width: 100 },
];

const invoices: Invoice[] = [
	{
		id: '1',
		number: 'INV-1041',
		client: 'Northwind Traders',
		amount: '€4,200',
		lines: [
			{
				id: '1a',
				description: 'Design retainer — June',
				qty: 1,
				amount: '€3,000',
			},
			{
				id: '1b',
				description: 'Icon set extension',
				qty: 24,
				amount: '€1,200',
			},
		],
	},
	{
		id: '2',
		number: 'INV-1042',
		client: 'Globex',
		amount: '€980',
		lines: [
			{ id: '2a', description: 'Accessibility audit', qty: 1, amount: '€980' },
		],
	},
];

const expanded = ref<string[]>([]);
</script>
```

#### Affixed actions on both tables

A nested table can carry its own `fixed-columns` — child rows usually need
their own row actions — and both action columns pin to the same visible edge:

```vue
<BbTable
	id="programmes"
	actions
	:columns="columns"
	:fixed-columns="[{ index: columns.length, position: 'right' }]"
	:items="rows"
	item-value="id"
>
	<template #expand="{ item }">
		<BbTable
			actions
			:columns="childColumns"
			:fixed-columns="[{ index: childColumns.length, position: 'right' }]"
			inherit-column-widths="programmes"
			:items="item.children"
			item-value="id"
		/>
	</template>
</BbTable>
```

This works because the child shares the parent's scrollport. `position: sticky`
resolves against the nearest scrolling ancestor, and the child's own box is as
wide as the parent's **content** — so if it opened a scrollport of its own, the
child's actions would affix to an edge sitting out in the overflow, hundreds of
pixels past what anyone can see, while the parent's pinned correctly. Snap the
child's actions column onto the parent's actions track (see the snapping rule
above) so the two columns line up rather than merely both being pinned.

A pinned cell is opaque — it paints the table's `--bg` surface because it
slides over its siblings — so a nested table sitting on a tinted expand row
(`--bb-muted` is the usual choice) shows white pinned actions unless you tell
it which surface it is on: `.nest .bb-table { --bg: var(--bb-muted); }`. Same
rule as any table on a non-panel surface (see **Styling hooks**).

#### Flush tables + inherited widths: mind the edge padding

`table-flush` removes the outer cell padding so the table reads edge-to-edge in
a card. `inherit-column-widths` snaps a nested table onto the parent's tracks.
Combine them and the two disagree at the edges: the child's first cell starts at
the parent's _padded_ offset while its track was measured from the _flush_ one,
so every nested row sits a few pixels off.

Two rules keep them honest:

1. **Snap against the same base you paint.** Measure the parent's columns with
   the same flush/padded state the child renders in — never measure padded and
   render flush.
2. **Never add nest padding on the body only.** Padding the child's body
   (`.bb-table__body`) but not its header (or vice versa) reintroduces exactly
   the offset the snap just removed. Put the inset on the nest container, where
   both row groups inherit it.

### Row highlight (master–detail)

`v-model:highlighted` is a parallel, UI-intent state — "the record whose
details are open" — independent of selection. Clicking anywhere on a row
toggles it: a new click replaces the previous highlight, and clicking the
highlighted row clears it back to `null`. **Highlight is single by design** —
one row is "the open one" — so bind a single item value, never an array. Two kinds of
clicks are ignored on purpose: those inside interactive elements (links,
buttons, inputs, labels keep their own semantics) and those ending a text
selection (dragging to copy a cell must not mutate state).

**Highlight is opt-in, and the model's value is the switch.** Bind nothing and
the mechanic is entirely off — a row click emits `click:row` and does nothing
else: no class, no `aria-current`, no state. That matters because the table has
nowhere to put a highlight it invents; a table that highlighted itself would
drive a cursor the app can neither read nor clear.

The switch reads the value, not the binding: **`undefined` means "never
initialised" and keeps highlight off; `null` means "initialised and currently
empty" and turns it on.** So initialise the model:

```ts
const highlighted = ref(null); // ✅ connected
const highlighted = ref(); // ❌ undefined — highlight stays off (warns in dev)
```

A value seeded through the shared context counts exactly the same, and binds
two ways just like the prop:

```ts
const highlighted = ref(null);
useBbTableContext('invoices-table', { highlighted });
```

`click:row` is never gated — it fires on every row click whether or not
highlight is connected, so listening for clicks costs you nothing. Calling
`toggleHighlighted` from a cell slot on an unconnected table does nothing and
warns once in dev.

Highlight ships with a **default cursor**: the row gets `aria-current="true"`
and the `bb-table-data__row--highlighted` class, and the shipped stylesheet
paints that class with a quiet neutral fill plus a left accent bar in your
brand primary — distinct from hover and from a plain focus ring, and readable
in both light and dark. The fill is `--bb-muted` (the shared "selected/active"
stop on the neutral surface ladder, one step above the `--bb-surface-hover`
used for row hover) and steps to `--bb-pressed` while hovered, so it never
depends on what your `--bb-primary` happens to be — only the accent bar does. Screen-reader users get the `aria-current` announcement either way;
sighted users now get a visible cursor out of the box too, including once
`keyboard-navigation` is on and the roving tabindex needs to be seen. Override
it with `row-class` (or equivalent visible styling) whenever the default
tint doesn't fit — pass a class keyed off the highlighted value to fully
customize the look:

```ts
const rowClass = (item: Invoice) =>
	item.id === highlighted.value
		? 'bg-[color:color-mix(in_oklab,var(--bb-danger)_10%,var(--bb-panel))]'
		: '';
```

**Click a row to preview it**

```vue
<template>
	<div class="flex max-w-3xl flex-col gap-3 sm:flex-row sm:gap-3">
		<!-- Clicking a row toggles `v-model:highlighted` (the "open record" state,
		     separate from selection). A default highlight tint ships out of the
		     box; this example repaints it explicitly via the public `row-class`
		     API to show how to customize it (here, matching the same tint). -->
		<div
			class="min-w-0 flex-1 overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
		>
			<BbTable
				v-model:highlighted="highlighted"
				caption="Invoices"
				:columns="columns"
				compact
				item-value="id"
				:items="invoices"
				:row-class="rowClass"
			/>
		</div>

		<aside
			class="w-full shrink-0 rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3 text-sm sm:w-52"
		>
			<template v-if="active">
				<p class="font-medium">{{ active.client }}</p>
				<p class="mt-0.5 text-xs text-[color:var(--bb-text-muted)]">
					{{ active.number }} · {{ active.amount }}
				</p>
			</template>
			<p v-else class="text-xs text-[color:var(--bb-text-muted)]">
				Select an invoice to preview it.
			</p>
		</aside>
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbTable } from 'bitboss-ui';
import type { BbTableColumn } from 'bitboss-ui';

type Invoice = { id: string; number: string; client: string; amount: string };

const columns: Array<BbTableColumn<Invoice>> = [
	{ key: 'number', label: 'Invoice', width: 110 },
	{ key: 'client', label: 'Client' },
	{ key: 'amount', label: 'Amount', align: 'right', width: 100 },
];

const invoices: Invoice[] = [
	{
		id: '1',
		number: 'INV-1041',
		client: 'Northwind Traders',
		amount: '€4,200',
	},
	{ id: '2', number: 'INV-1042', client: 'Globex', amount: '€980' },
	{ id: '3', number: 'INV-1043', client: 'Initech', amount: '€15,600' },
];

// `item-value="id"` means `highlighted` is the row's id.
const highlighted = ref<string | null>(null);

const active = computed(() =>
	invoices.find((invoice) => invoice.id === highlighted.value)
);

// Primary tint for the open row — selection chrome stays on content, not hover.
const rowClass = (invoice: Invoice) =>
	invoice.id === highlighted.value
		? 'cursor-pointer bg-[color:color-mix(in_oklab,var(--bb-primary)_8%,var(--bb-panel))]'
		: 'cursor-pointer';
</script>
```

### Keyboard navigation and row events

Add `keyboard-navigation` to make the body a single tab stop with a roving
tabindex: ArrowUp/ArrowDown move the focused row (PageUp/PageDown stride ten
rows, Home/End jump), and
Enter/Space activate it through the same path as a mouse click — highlight
toggle plus `click:row`. Focus and highlight stay independent: arrowing over
rows opens nothing until the user commits. A mouse click re-anchors arrow
navigation, focused rows show the standard focus ring, and keys pressed inside
interactive descendants (or a nested table) keep their own semantics.

`keyboard-navigation` rides on the same default cursor as `v-model:highlighted`
— the roving tabindex, `aria-current` and the built-in highlight tint are all
correct the moment you add the prop, so `j`/`k`/arrow keys move a visible
cursor out of the box. See **Row highlight** above for how to override that
look with `row-class` if the default tint doesn't fit.

**Arrow through the audit log, Enter opens**

```vue
<template>
	<div class="flex max-w-2xl flex-col gap-1.5">
		<!-- `keyboard-navigation` makes the body one tab stop: ↑/↓ move the
		     focused row, Home/End jump, Enter/Space open it (same path as a
		     click, so it toggles `highlighted` and emits `click:row`). -->
		<div
			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
		>
			<BbTable
				v-model:highlighted="openEventId"
				caption="Audit log"
				:columns="columns"
				compact
				item-value="id"
				:items="events"
				keyboard-navigation
				:row-class="rowClass"
			/>
		</div>
		<p class="text-xs text-[color:var(--bb-text-muted)]">
			Tab into the table, move with the arrow keys, press Enter to open a row.
			Open event:
			<span class="font-medium text-[color:var(--bb-text)]">{{
				openEvent ? `${openEvent.actor} — ${openEvent.action}` : 'none'
			}}</span>
		</p>
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbTable } from 'bitboss-ui';
import type { BbTableColumn } from 'bitboss-ui';

type AuditEvent = { id: string; time: string; actor: string; action: string };

const columns: Array<BbTableColumn<AuditEvent>> = [
	{ key: 'time', label: 'Time', width: 70 },
	{ key: 'actor', label: 'Actor' },
	{ key: 'action', label: 'Action' },
];

const events: AuditEvent[] = [
	{ id: 'e1', time: '09:12', actor: 'ada@acme.io', action: 'Created API key' },
	{
		id: 'e2',
		time: '09:47',
		actor: 'grace@acme.io',
		action: 'Changed billing plan',
	},
	{
		id: 'e3',
		time: '10:03',
		actor: 'ken@acme.io',
		action: 'Invited 2 members',
	},
	{ id: 'e4', time: '10:31', actor: 'ada@acme.io', action: 'Rotated secrets' },
];

const openEventId = ref<string | null>(null);

const openEvent = computed(() =>
	events.find((event) => event.id === openEventId.value)
);

// A default highlight tint ships out of the box; row-class is only needed to
// customize it (the public API for doing so).
const rowClass = (event: AuditEvent) =>
	event.id === openEventId.value
		? 'bg-[color:color-mix(in_oklab,var(--bb-primary)_8%,var(--bb-panel))]'
		: '';
</script>
```

Row events: `click:row`, `dblclick:row` and `contextmenu:row` fire with
`(event, item)` — the native event and **your record exactly as you passed it
in `items`**, nothing else. No wrapper to unpack, no third argument; selection
state is already yours through the `v-model`, and the row's value resolves
from the record through `item-value` exactly as the models do. Reserve these
events for side effects that are not navigation —
logging, opening a drawer (though `v-model:highlighted` usually covers that
without any handler).

Overlays opened from inside a row never fire them. A popover, dropdown, select
panel, date/time/colour picker, dialog or off-canvas sheet swallows its own
clicks at the surface, so picking a date in a cell calendar edits the cell and
leaves the row's highlight and `click:row` alone — no `@click.stop` wrapper
needed.

### Opening a record

Row navigation goes through a real link component, never a row `@click`
handler. Render a `BbButton` in a cell or the actions column with `href` (or
`to` in a router app): the user gets a proper anchor, middle-click and
open-in-new-tab for free.

**A per-row link via BbButton**

```vue
<template>
	<!-- Row-level navigation is offloaded to BbButton: `href` (or `to` in a
	     router app) makes it a real link, not a JS click handler. -->
	<div
		class="max-w-2xl overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
	>
		<BbTable
			actions
			actions-text="Actions"
			caption="Invoices"
			:columns="columns"
			compact
			item-value="id"
			:items="invoices"
		>
			<template #actions="{ item }">
				<BbButton
					append:icon="lucide:arrow-right"
					:href="`#invoice-${item.id}`"
					size="xs"
					variant="outline"
				>
					Open
				</BbButton>
			</template>
		</BbTable>
	</div>
</template>
<script setup lang="ts">
import { BbButton, BbTable } from 'bitboss-ui';
import type { BbTableColumn } from 'bitboss-ui';

type Invoice = { id: string; number: string; client: string; amount: string };

const columns: Array<BbTableColumn<Invoice>> = [
	{ key: 'number', label: 'Invoice', width: 110 },
	{ key: 'client', label: 'Client' },
	{ key: 'amount', label: 'Amount', align: 'right', width: 100 },
];

const invoices: Invoice[] = [
	{
		id: '1041',
		number: 'INV-1041',
		client: 'Northwind Traders',
		amount: '€4,200',
	},
	{ id: '1042', number: 'INV-1042', client: 'Globex', amount: '€980' },
	{ id: '1043', number: 'INV-1043', client: 'Initech', amount: '€15,600' },
];
</script>
```

In a router or Inertia app the same button carries the platform's navigation
instead of an inert `href`:

```vue
<!-- vue-router / Nuxt -->
<template #actions="{ item }">
	<BbButton :to="{ name: 'invoices.show', params: { id: item.id } }" size="xs">
		Open
	</BbButton>
</template>
```

```vue
<!-- Inertia -->
<template #actions="{ item }">
	<BbButton :href="`/invoices/${item.id}`" size="xs">Open</BbButton>
</template>
```

### Inline editing

Cells can edit in place — no edit page, no modal. Two commit grammars, one
per control kind:

- **Typed cells** (text, number) bind `:model-value` down and commit on
  `@change` (blur/Enter) — never `v-model`, which fires per keystroke and
  turns an autosave into one request per character.
- **Option-backed cells** are a badge acting as the trigger of a
  `BbSelectPopover`: the pick IS the commit. The options resolve once at page
  level as an array (never a per-row provider — see the BbSelectPopover
  guide's table section), the badge carries an internal trailing chevron, and
  while the save runs the badge's `loading` prop swaps the spinner into the
  chevron's place — same size, nothing shifts.

The deeper question — who owns the uncommitted value (a draft map with an
explicit Save, or an optimistic autosave overlay, or the rows themselves —
never) — is the [Inline Edit Playbook](./guides/inline-edit-playbook.md).
This example uses the autosave grammar: per-field optimistic overlay,
rollback on failure, and overlay retirement inside the items function.

**Autosave cells: commit on blur, spinner in the chevron**

```vue
<template>
	<div class="flex max-w-2xl flex-col gap-1.5">
		<div
			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
		>
			<BbTable
				caption="Sprint tasks — every cell saves itself"
				:columns="columns"
				compact
				:dependencies="[rev]"
				item-value="id"
				:items="loadTasks"
			>
				<!-- Typed cell: bind down, commit on @change (blur/Enter) — never
				     v-model, which fires per keystroke (one request per character). -->
				<template #title="{ item }">
					<BbTextInput
						compact
						hide-label
						label="Title"
						:model-value="valueOf(item, 'title')"
						@change="onTitleChange(item, $event)"
					/>
				</template>

				<!-- Option cell: the badge IS the trigger; the pick IS the commit.
				     One page-level `statuses` array shared by every row (never a
				     per-row provider). While the save runs, `loading` swaps the
				     spinner into the chevron's place. -->
				<template #status="{ item }">
					<BbSelectPopover
						compact
						disable-writing
						item-text="label"
						item-value="value"
						:items="statuses"
						:model-value="valueOf(item, 'status')"
						width="170px"
						@update:model-value="persist(item, 'status', $event as Status)"
					>
						<template #activator="{ props }">
							<BbBadge
								append:icon="lucide:chevron-down"
								:loading="pending[item.id]?.status !== undefined"
								size="lg"
								:variant="VARIANT[valueOf(item, 'status')]"
							>
								<BbBadgeButton v-bind="props">{{
									labelFor(valueOf(item, 'status'))
								}}</BbBadgeButton>
							</BbBadge>
						</template>
					</BbSelectPopover>
				</template>
			</BbTable>
		</div>

		<p v-if="lastFailure" class="text-xs text-[color:var(--bb-danger)]">
			{{ lastFailure }}
		</p>
		<p class="text-xs text-[color:var(--bb-text-muted)]">
			No Save button anywhere — edits persist per field, optimistically.
			BB-121's save always fails and rolls back.
		</p>
	</div>
</template>
<script setup lang="ts">
import { reactive, ref } from 'vue';
import {
	BbBadge,
	BbBadgeButton,
	BbSelectPopover,
	BbTable,
	BbTextInput,
} from 'bitboss-ui';
import type { BadgeVariantType, BbTableColumn } from 'bitboss-ui';

type Status = 'open' | 'in-progress' | 'blocked' | 'done';
type Task = { id: string; ref: string; title: string; status: Status };
type EditableKey = 'title' | 'status';
type Patch = Partial<Pick<Task, EditableKey>>;

const statuses: Array<{ value: Status; label: string }> = [
	{ value: 'open', label: 'Open' },
	{ value: 'in-progress', label: 'In progress' },
	{ value: 'blocked', label: 'Blocked' },
	{ value: 'done', label: 'Done' },
];

const VARIANT: Record<Status, BadgeVariantType> = {
	open: 'soft-gray',
	'in-progress': 'soft-blue',
	blocked: 'soft-red',
	done: 'soft-green',
};

const columns: Array<BbTableColumn<Task>> = [
	{ key: 'ref', label: 'Ref', width: 90 },
	{ key: 'title', label: 'Title' },
	{ key: 'status', label: 'Status', width: 140 },
];

/* ---- Fake server (deterministic: BB-121 always rejects) ---------------- */

let server: Task[] = [
	{
		id: 't-1',
		ref: 'BB-104',
		title: 'Popover drops focus on Esc',
		status: 'open',
	},
	{
		id: 't-2',
		ref: 'BB-118',
		title: 'Header misaligns at 320px',
		status: 'in-progress',
	},
	{
		id: 't-3',
		ref: 'BB-121',
		title: 'Token audit for dark mode',
		status: 'blocked',
	},
	{
		id: 't-4',
		ref: 'BB-130',
		title: 'Ship the migration guide',
		status: 'done',
	},
];

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

const api = {
	list: async (): Promise<Task[]> => {
		await wait(150);
		return server.map((task) => ({ ...task }));
	},
	patch: async (id: string, patch: Patch): Promise<void> => {
		await wait(400);
		const row = server.find((task) => task.id === id);
		if (!row) return;
		if (row.ref === 'BB-121') throw new Error('save rejected');
		server = server.map((task) =>
			task.id === id ? { ...task, ...patch } : task
		);
	},
};

/* ---- Autosave state (the Inline Edit Playbook's flagship pattern) ------ */

const rev = ref(0);
/** Optimistic values, per row per field — two fields can be in flight independently. */
const pending = reactive<Record<string, Patch>>({});
const lastFailure = ref('');

// `key in` rather than `??` so an overlay holding a committed empty/null
// value still wins over the row (matters once a field is clearable).
const valueOf = <K extends EditableKey>(item: Task, key: K): Task[K] => {
	const patch = pending[item.id];
	return patch && key in patch ? (patch[key] as Task[K]) : item[key];
};

/**
 * The overlay is retired HERE, in the fetch, and only for fields the response
 * confirms — never when the save resolves. Between the save landing and the
 * reload arriving the table still holds the OLD row; clearing early would
 * flash the cell new → old → new for the whole reload.
 */
const loadTasks = async (): Promise<Task[]> => {
	const rows = await api.list();
	for (const row of rows) {
		const patch = pending[row.id];
		if (!patch) continue;
		for (const key of Object.keys(patch) as EditableKey[]) {
			if (patch[key] === row[key]) delete patch[key];
		}
		if (!Object.keys(patch).length) delete pending[row.id];
	}
	return rows;
};

const persist = async <K extends EditableKey>(
	item: Task,
	key: K,
	next: Task[K]
) => {
	if (next === item[key]) return; // no-op commit
	(pending[item.id] ??= {})[key] = next; // optimistic: the UI moves now
	try {
		await api.patch(item.id, { [key]: next });
		rev.value += 1; // reload; loadTasks retires the overlay once it can
	} catch {
		// Rollback: drop just this field — the cell reverts to the row's value.
		delete pending[item.id]?.[key];
		if (pending[item.id] && !Object.keys(pending[item.id]).length) {
			delete pending[item.id];
		}
		lastFailure.value = `${item.ref}: ${key} save failed — rolled back.`;
	}
};

const onTitleChange = (item: Task, event: Event) =>
	persist(item, 'title', (event.target as HTMLInputElement).value);

const labelFor = (status: Status) =>
	statuses.find((option) => option.value === status)?.label ?? '—';
</script>

<!-- Soft status palette — canonical source: ai/guides/design-language.md § Using color.
     Non-scoped so variant classes on the child badge receive the accents. -->
<style>
.bb-badge.bb-badge--soft-gray {
	--accent: #64748b;
}
.bb-badge.bb-badge--soft-blue {
	--accent: #2563eb;
}
.bb-badge.bb-badge--soft-green {
	--accent: #16a34a;
}
.bb-badge.bb-badge--soft-red {
	--accent: #dc2626;
}
.bb-badge.bb-badge--soft-gray,
.bb-badge.bb-badge--soft-blue,
.bb-badge.bb-badge--soft-green,
.bb-badge.bb-badge--soft-red {
	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
	--border-width: 1px;
	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
}
</style>
```

The status colors are the registered `soft-*` badge variants: the plugin's
`badgeVariants` option makes the names type-check, and the example carries
their CSS in its own style block — the sanctioned consumer path. The
canonical palette lives in the
[design language guide](./guides/design-language.md).

### Dense and wide tables

`compact` tightens row padding. `fixed-headers` makes the header stick to the
top of the nearest scroll container. `fixed` switches to an equal-width fixed
layout. `fixed-columns` pins columns while the rest scroll horizontally: an
array of column indices (left-pinned) or `{ index, position: 'left'|'right' }`
objects; indices count rendered columns (a selection column is index 0), and
an out-of-range index logs a console error and is skipped. When content can't
fit, the table keeps every column at its measured minimum — its header label
included — and overflows its container instead of clipping; this is by
design, not a bug to work around. Note that truncating cells yourself
(`overflow: hidden` + `text-overflow: ellipsis` via `tdClass`) removes that
column's content floor — only the label floors it then, and the grid pads
every column equally with whatever is left — so declare a `width` on the
columns you truncate, or truncate with `white-space: nowrap` alone and let
the table scroll.

**The consumer overflow contract has two parts.** Wrap the table in an
`overflow-x: auto` element (below), **and** make sure that wrapper is actually
free to shrink below the table's content width. Inside a flex or grid layout,
an item's automatic minimum size defaults to its own content's size along the
container's main axis — so a `BbTable` inside an unconstrained flex row (a
page shell's content column, a flex-direction: row split view) pushes that
whole row wider instead of scrolling, even with `overflow-x: auto` already on
the wrapper. Give that ancestor `min-width: 0` explicitly to let it shrink and
hand scrolling to the table's own wrapper. (This only bites the flex **row**
axis: a wrapper that is a cross-axis child of a `flex-direction: column`
parent already has a definite width and doesn't need it — check which axis
your wrapper actually sits on before sprinkling `min-width: 0` everywhere.)

**Compact rows with a sticky header**

```vue
<div
	class="max-h-52 max-w-2xl overflow-auto rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
>
	<BbTable
		caption="Server fleet"
		compact
		fixed-headers
		:columns="[
			{ key: 'host', label: 'Host' },
			{ key: 'region', label: 'Region' },
			{ key: 'cpu', label: 'CPU', align: 'right' },
			{ key: 'memory', label: 'Memory', align: 'right' },
			{ key: 'status', label: 'Status' },
		]"
		:items="[
			{ host: 'web-01', region: 'eu-west-1', cpu: '38%', memory: '61%', status: 'Healthy' },
			{ host: 'web-02', region: 'eu-west-1', cpu: '52%', memory: '70%', status: 'Healthy' },
			{ host: 'api-01', region: 'us-east-2', cpu: '74%', memory: '80%', status: 'Healthy' },
			{ host: 'db-01', region: 'us-east-2', cpu: '81%', memory: '88%', status: 'Degraded' },
			{ host: 'cache-01', region: 'ap-south-1', cpu: '22%', memory: '35%', status: 'Healthy' },
		]"
	/>
</div>
```

### Virtual rows

`virtual` windows the body: only the rows in the vertical scrollport (plus a
few on each side) are mounted, and two spacer rows hold the scrollport at the
full list height, so 5,000 or 50,000 rows scroll at the cost of a few dozen.
Everything else is the same table — the rows stay in flow in the grid, so the
stuck header, `fixed-columns`, nested tables, selection, highlight and the
keyboard grammar work untouched. One prop, no knobs.

- **Give it a scroller.** Bound the table's height (`max-height` / `height`
  on the table, or a flex item with `min-height: 0`) and the table itself
  scrolls its rows; left unbounded it grows with the page and the page (or
  the nearest scrolling ancestor) is the scroller. `virtual` implies a stuck
  header — a windowed body without column names is a scroller, not a table.
- **Columns are sized once.** A windowed body only ever holds a few rows, so
  `auto` tracks would move as rows come and go. The first rendered batch is
  measured and its widths become floors (`minmax(px, 1fr)`): they still share
  surplus, later rows never widen them — and the cells of those columns are
  single-line and **clip with an ellipsis** (like a resized column) so a
  longer value that shows up later never spills into its neighbour. Want a
  column to wrap (prose, notes)? Declare a `width` on it: a declared width
  wins as always and keeps wrapping. A resize overrides as always, and an
  empty→non-empty transition (a refetch) re-measures from the new first
  batch.
- **A fast wheel never shows blank space.** A band of skeleton rows is kept
  rendered beyond the window on both sides (cheap: empty cells at the
  measured row height), so a wheel that the compositor scrolls ahead of the
  main thread reveals skeletons, not blank spacer, and they turn into real
  rows as the window reaches them. While the scroll is fast, rows never
  mounted before stay skeletons and are swapped for real rows as soon as
  it slows; rows you have already seen stay real. A moderate scroll never
  sees a skeleton.
- **Dynamic heights are fine.** Every mounted row is measured (wrapping
  cells, a "show more", an expand row that opens a nested table three levels
  deep), measurements are cached by row so a row seen once stays right, and a
  height change _above_ the viewport moves the scroll offset with it so what
  you are reading does not jump.
- **Focus is never lost to an unmount.** The row (or expand row) that owns
  focus stays mounted however far it scrolls — a control inside a nested
  table included — and is released on blur. Arrow keys, Home/End and
  PageUp/PageDown work across the whole list (the target row is scrolled in,
  mounted, then focused).
- **Nested tables are not windowed.** A nested table inside an expand row is
  one tall row to the virtualizer; give a huge nested dataset its own page.
  `virtual` is ignored on a table that inherits its widths, and under a
  `#tbody` slot.
- **Rows keep their absolute position for AT** (`aria-rowcount` /
  `aria-rowindex`), page or no page — a virtual table is one page unless you
  say otherwise.

**5,000 rows in a 320px scroller**

```vue
<template>
	<!-- Bounding the table's height is what makes it the scroller of its own
	     rows; `virtual` windows them and implies the stuck header. -->
	<div
		class="max-w-2xl overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
	>
		<BbTable
			caption="Ledger"
			class="max-h-80"
			:columns="columns"
			compact
			:fixed-columns="[0]"
			item-value="id"
			:items="rows"
			virtual
		/>
	</div>
</template>
<script setup lang="ts">
import { BbTable } from 'bitboss-ui';
import type { BbTableColumn } from 'bitboss-ui';

type Entry = {
	id: number;
	number: string;
	client: string;
	issued: string;
	amount: string;
};

const columns: Array<BbTableColumn<Entry>> = [
	{ key: 'number', label: 'Invoice' },
	{ key: 'client', label: 'Client' },
	{ key: 'issued', label: 'Issued' },
	{ key: 'amount', label: 'Amount', align: 'right' },
];

const clients = ['Northwind Traders', 'Globex', 'Initech', 'Umbrella', 'Hooli'];
const rows: Entry[] = Array.from({ length: 5000 }, (_, i) => ({
	id: i,
	number: `INV-${10000 + i}`,
	client: clients[i % clients.length],
	issued: `2026-${String(1 + (i % 12)).padStart(2, '0')}-${String(1 + (i % 28)).padStart(2, '0')}`,
	amount: `€${((i * 37) % 9000) + 100}`,
}));
</script>
```

### Narrow screens: hide columns, don't scroll everything

An ops table with ten columns is unusable on a phone as a horizontal scroller —
the identity column, the one thing the user is looking for, is the first to
leave the screen. Collapse instead of scroll:

- **Rank the columns.** Identity + status + the one number that matters stay;
  everything else is secondary.
- **Drop the secondary ones from `columns` at the breakpoint** — a `computed`
  over `useMobile()` (or your own `matchMedia`) that filters the secondary keys
  out. Removing the column removes its grid track. Do **not** hide cells with
  `thClass`/`tdClass` + `display: none`: the table is a grid, a hidden cell
  leaves its track in place and every following cell shifts one track over.
  A dropped key keeps its slot in `order` (the write-back never drops
  unknown keys), so the column returns where it was — never filter the
  order array.
- **Stack what survives into the primary cell.** The identity slot renders the
  name plus the hidden facts under it, at `--bb-text-muted`, so nothing is
  actually lost.

Keep the sticky/pinned identity column for the case where the full grid really
must stay reachable (a spreadsheet-shaped tool), not as the default for a
records list.

### Styling hooks

**The table's surface is `--bg`** (default `var(--bb-panel)`), a local on
`.bb-table`. Cells are transparent at rest so the row can tint them, but
anything that slides over scrolled content — the stuck header band with
`fixed-headers`, and `fixed-columns` cells — is opaque and paints `--bg` (a
pinned cell also picks up its row's hover/highlight tint, so it never reads
as a hole). When a table sits on a surface that is not the panel colour, set
the one knob and everything pinned follows:

```css
.my-card .bb-table {
	--bg: var(--card-bg);
}
```

The table is a **CSS grid of `<div>`s with ARIA roles, not a `<table>`**: the
root `.bb-table__table[role=table]` owns the column tracks and every row group
and row is a subgrid of it. Style it through the classes and the roles — never
through element names, which match nothing:

| Region         | Class                                                                                                                      | Role                                      |
| -------------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| grid root      | `.bb-table__table`                                                                                                         | `table`                                   |
| header group   | `.bb-table__head`                                                                                                          | `rowgroup`                                |
| header row     | `.bb-table-header-row`                                                                                                     | `row`                                     |
| header cell    | `.bb-table-header` (+ `--select`, `--actions`)                                                                             | `columnheader`                            |
| body group     | `.bb-table__body`                                                                                                          | `rowgroup`                                |
| data row       | `.bb-table-data__row` (+ `--highlighted`)                                                                                  | `row`                                     |
| data cell      | `.bb-table-data__cell` (+ `--select`)                                                                                      | `cell`                                    |
| actions cell   | `.bb-table__cell--actions`                                                                                                 | `cell`                                    |
| expand row     | `.bb-table-expand__row` > `.bb-table-expand__cell`                                                                         | `row` > `cell`                            |
| empty state    | `.bb-table-no-data__row` > `.bb-table-no-data__cell`                                                                       | `row` > `cell`                            |
| footer group   | `.bb-table__foot` (`#tfoot` content)                                                                                       | `rowgroup` only when `#tfoot` is provided |
| focused header | `.bb-table-header[data-column-key]:focus-visible` (`reorderable` only; inset ring, the header row is one roving tab stop)  | `columnheader`                            |
| dragged column | `.bb-table-header--dragging` on the header; `.bb-table__head--dragging` on the head group during a drag                    | —                                         |
| clipped header | `.bb-table-header--clip` (the track is a length or an equal split, so the label ellipsizes instead of flooring the column) | `columnheader`                            |
| virtual table  | `.bb-table--virtual` on the container (`overflow: auto`, the scroller once its height is bounded)                          | —                                         |
| spacer row     | `.bb-table-spacer__row` (a `virtual` body's stand-in for unmounted rows, `aria-hidden`; never style its height)            | — (`aria-hidden`)                         |
| skeleton row   | `.bb-table-placeholder__row` > `.bb-table-placeholder__cell` (a `virtual` body's skeleton band and fast-scroll stand-in)   | `row` > `cell` (`aria-hidden`)            |
| drag chip      | `.bb-table-column-ghost` (a `popover="manual"` in the top layer; paints `--bb-panel`, not the table's `--bg`)              | — (`aria-hidden`)                         |
| caption        | `.bb-table-caption` (before the root, `aria-labelledby`)                                                                   | —                                         |

`[role='row']`, `[role='cell']` and `[role='columnheader']` are supported
hooks, not incidental markup — use them when you mean "every row kind" or
"every cell"; use the classes when you mean one kind. Cells are direct
children of their row, so `:first-child` / `:last-child` / `:nth-child(n)`
address columns.

The full-bleed idiom every workspace page reaches for — the table bleeds past
the content padding and hands the inset back to its outermost cells — is
written with a **direct-child chain** so a nested table inheriting the
parent's tracks (it lives inside `.bb-table-expand__cell`) is never touched:

```css
.table-flush {
	--page-inset: 1rem;
	margin-inline: calc(var(--page-inset) * -1);
	width: calc(100% + var(--page-inset) * 2);
}

.table-flush
	:deep(> .bb-table__table > .bb-table__head > [role='row'] > :first-child),
.table-flush
	:deep(
		> .bb-table__table
			> .bb-table__body
			> [role='row']
			> :first-child:not(.bb-table-expand__cell)
	) {
	padding-inline-start: var(--page-inset);
}

.table-flush
	:deep(> .bb-table__table > .bb-table__head > [role='row'] > :last-child),
.table-flush
	:deep(
		> .bb-table__table
			> .bb-table__body
			> [role='row']
			> :last-child:not(.bb-table-expand__cell)
	) {
	padding-inline-end: var(--page-inset);
}

/* Expand rows stay edge-to-edge so the nested table can snap onto the parent
   tracks without an extra inset shifting it sideways. */
.table-flush
	:deep(
		> .bb-table__table > .bb-table__body > [role='row'] > .bb-table-expand__cell
	) {
	padding-inline: 0;
}
```

Leave the geometry alone: `display: grid` / `gap: 0` on the root, row groups
and rows, `grid-column: 1 / -1` **and `contain: inline-size`** on the
full-width cells (without the containment, expand-row content resizes the
parent's columns), `white-space: nowrap` on the actions cell (it sizes the
actions track), and `position: sticky` on `.bb-table__head` under
`fixed-headers`.

When you replace a region with `#thead` / `#tbody` / `#tfoot`, ship the same
shape the table does — role-complete rows, spanning with `grid-column` rather
than `colspan`:

```vue
<template #tfoot="{ columnCount }">
	<div role="row">
		<div
			role="cell"
			:aria-colspan="columnCount - 1"
			:style="{ gridColumn: `span ${columnCount - 1}` }"
		>
			Total
		</div>
		<div role="cell" class="text-right">{{ total }}</div>
	</div>
</template>
```

A `<tr>` inside the grid is not merely unsemantic — the browser wraps it in an
implicit `<table>` and the cells never land on the tracks. Nothing lints the
roles: a `<div>` row without them renders fine and is invisible to a screen
reader.

### Config and platform

- **Locale.** The plugin's `locale` (`it`/`en`) drives the built-in strings:
  the no-data text, the select-all label, the single-select header text, and
  the "Select" prefix of each row's accessible selection label. Override any
  of them per table via `no-data-text` / `select-all-label` / `select-text`.
- **`actions-text` is localized** like the other built-in strings (`it` →
  `Azioni`, `en` → `Actions`). Seeing `Azioni` in an English app means the
  plugin is still on the default locale, which is `it` — set the plugin's
  `locale` option, or override per table with `actions-text` (it is visually
  hidden in the header but read by screen readers).
- **SSR / Nuxt.** A provider `items` function participates in
  `onServerPrefetch`, so the first page can render server-side. The table
  context (and thus `table-id` pagination wiring) is client-side only —
  hydration-time onward.
- **Forms.** With `name`, the selection submits as hidden inputs — no JS
  needed between the table and a plain `<form>` POST (Inertia included).

### Works well with

- `BbPagination` — shared page ref, or zero-wiring via `id` + `table-id`.
- `useBbTableContext` (`./composables/useBbTableContext.md`) — bulk-action
  toolbars, detail panels, "reset sort" buttons living outside the table.
  (Column order is not mirrored there: a column panel needs `columns` too,
  so it lives where `v-model:order` is bound.)
- `BbButton` — per-row links (`href`/`to`) in cells or `#actions`;
  `BbDropdown` for an overflow menu of row actions.
- `BbBadge` / `BbAvatar` — status and identity cells via slots.
- `BbTextInput` / `BbSelect` filters feeding `dependencies`.
- `useConfirm` + `useToast` — destructive row actions with feedback; the full
  assembly is the records workspace recipe
  (`./recipes/vue/records-workspace.md`).
- Inline editing — the ownership patterns are the
  [Inline Edit Playbook](./guides/inline-edit-playbook.md); the full autosave
  page is the inline-edit workspace recipe
  (`./recipes/vue/inline-edit-workspace.md`).
- `BbTree` — when the data is genuinely recursive rather than rows + detail.

### Gotchas and constraints

- Slot names are **lowercased**: a camelCase key like `issuedAt` yields
  `#issuedat`. Prefer snake_case keys.
- `loading-text` is `sr-only` — it is announced, never painted. The visible
  loading signal is the skeleton (or your `#loading` slot). It defaults to the
  localized `common.loadingText`, so an unset value still announces.
- Row selection labels default to the localized "select" word plus every
  cell's content. `accessible-label` overrides that per row — it is called
  `(columns, item)` with the mapped cells (in **render** order — look them up
  by `key`, never by position) and the raw record, and whatever it returns
  becomes the checkbox's label.
- `fixed-columns` pins **slots**, not columns: under `order` the
  column that lands in a pinned slot is the pinned one (see Column order).
- A column panel that holds a partial `order` receives the completed
  array on the user's first move — its persisted list grows to every key.
- Enabling select-all does not re-emit an empty `modelValue` (see the
  select-all section) — in all-mode, read `select-all` +
  `unselected-items`, not `modelValue`.
- Row event payloads are `(event, item)` with `item` your raw record — there is
  no wrapper to unpack and no `selected` argument.
- A mistyped context/pagination `id` does not error; it silently syncs with
  nothing. If a toolbar "works" but the table never reacts, check the id.
- In multiple mode `modelValue` must be an array, or it throws.

### Anti-patterns

- Watching filters and refetching manually — list them in `dependencies`.
- Expecting the table to sort, slice or fetch: it reports state; you apply it.
- Hand-rolling selection pruning after a refetch — that's `enforce-coherence`
  (see Selection across refetches); reserve provider-side reconciliation for
  paginated tables, where the prop must stay off.
- Pre-mapping items into `{ label, value }` — pass domain objects +
  `item-value`.
- `@click:row` + `router.push` for navigation — render a real `BbButton` link.
- Rebuilding selection controls in a cell slot — use `selectable`, the
  `#select` slot, or the scope's `toggleSelected`.
- Mutating slot-scope flags (`expanded`, `selected`, `highlighted`) — they are
  one-way; call the paired `toggle*` callback.
- Omitting `item-value` on tables with selection/expansion/highlight —
  object-identity matching breaks across refetches.

### Accessibility

- Always give the table a `caption` describing its content. It is visually
  hidden by default (available to screen readers); set `display-caption` to
  show it as a visible title.
- A selectable table is a `<fieldset>` — pass `legend` to name it precisely;
  it falls back to `caption`, then a generic localized string, so it is never
  left without an accessible name. Each selection control carries a
  visually-hidden label built from the row's cell contents.
- Set `item-value` so selection, expansion and highlight track rows by stable
  identity rather than object reference.
- Sortable headers set `aria-sort` and render real buttons; custom header
  slots should keep a button calling `toggleSort`.
- With `reorderable` the header row becomes one roving tab stop
  (the AG Grid grammar): ←/→ move focus between headers, Home/End to the
  ends, **Shift+←/→** move the focused column one slot (Shift+Home/End to
  the ends), Enter/Space sorts a sortable header — every move committed
  immediately and announced through a polite status region ("X moved to
  position 2 of 5"); a one-line sr-only instruction describes each header.
  The sort button leaves the tab order (the header is the target; it still
  works for the mouse). NVDA/JAWS browse mode intercepts arrows on a focused
  element — the same focus-mode step as row keyboard navigation.
- When you paginate, pass `page` / `per-page` / `total-items` so the table
  announces the full result count (`aria-rowcount`) and each row's absolute
  index (`aria-rowindex`, expansion-aware), not just the current page.
- The loading row is an `aria-live` status; it announces the localized default
  unless you give it a more specific `loading-text`.
- The highlighted row carries `aria-current="true"`; add `keyboard-navigation`
  so row-level interaction is reachable without a mouse (roving tabindex,
  Arrow/PageUp/PageDown/Home/End, Enter/Space).
- `aria-current` is announced to screen readers regardless, and a default
  highlight tint ships for sighted users too — pass `row-class` to customize
  it. See Row highlight above.
- Keep row-level navigation in real `BbButton` links (`href` / `to`), never a
  bare `@click:row` — links are focusable and announced as links.

## v-model

- `v-model:expandedItems` — type: `any[] \| undefined`
- `v-model:highlighted` — type: `any`
- `v-model` — type: `any`
- `v-model:order` — type: `string[] \| undefined`
- `v-model:selectAll` — type: `boolean \| undefined`
- `v-model:sort` — type: `BbTableSortEntry[] \| undefined`
- `v-model:unselectedItems` — type: `any[] \| undefined`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `accessibleLabel` | `((columns: MappedCell[], item: any) => string) \| undefined` |  |  | Function that accepts the columns and the current item as arguments and returns a label to be used for accessibility purposes. The cells arrive in RENDER order (they follow `order`, so the label reads like the row) — look a cell up by `key`… |
| `actions` | `boolean \| undefined` | `false` |  | Displays the actions column. |
| `actionsText` | `string \| undefined` |  |  | Label used in the header of the actions column. |
| `align` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Text alignment of the columns. |
| `caption` | `string \| undefined` |  |  | Caption that describes the content of the table. Used for accessibility purposes. |
| `columns` | `InternalColumn<T>[] \| undefined` | `[]` |  | Array of definitions of how the columns should be rendered. |
| `compact` | `boolean \| undefined` | `false` |  | Adds a CSS class that applies a compact style to the component. |
| `dependencies` | `unknown[] \| undefined` | `[]` |  | Defines an array of dependencies that will trigger actions in the component upon change. |
| `depsDebounceTime` | `number \| undefined` | `0` |  | Timeout used to debounce response to changes to dependencies. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
| `disableSelectAll` | `boolean \| undefined` | `false` |  | Hides the "Select all" checkbox that selectable multi-row tables display by default. |
| `displayCaption` | `boolean \| undefined` | `false` |  | Boolean that defines whether to display or hide the caption. By default is true and the caption is hidden. |
| `enforceCoherence` | `boolean \| undefined` | `false` |  | After every load (initial, `dependencies` refetch or a change of the `items` array) prunes the row-keyed models of values whose row is no longer in the result set: `modelValue`, `unselected-items`, `highlighted` and `expanded-items`. Values… |
| `expandedItems` | `any[] \| undefined` | `[]` |  | Used by `v-model:expandedItems`. Array of the currently expanded items — toggled by the row expand control and by external writes (mirrors the `highlighted`/`sort` v-model surfaces). Drives the `#expand` slot rows and their `aria-expanded`/… |
| `fixed` | `boolean \| undefined` | `false` |  | Splits the width equally among the columns that declare no `width` (each undeclared column becomes a `minmax(0, 1fr)` track) making each column take up the same amount of space. |
| `fixedColumns` | `(number \| { index: number; position: "left" \| "right"; })[] \| undefined` | `[]` |  | Definition for which column should be fixed. It can be an array of index of the column to fix on the left side of the table or an array of objects indicating the index and the position `left` or `right` where to affix the columns. Indices a… |
| `fixedHeaders` | `boolean \| undefined` | `false` |  | Boolean that sets the headers as sticky to the top of the table. |
| `headerRowClass` | `Classes \| undefined` |  |  | Defines the classes to be passed to the header row. |
| `highlighted` | `any` | `undefined` |  | Used by `v-model:highlighted`. A parallel, UI-intent state to selection — typically "the row whose details are open". A single item value (or `null`) — highlight is single by design. **Opt-in, and `undefined` is the opt-out.** Leave it unbo… |
| `id` | `string \| undefined` |  |  | Stable id for this table's width context. When omitted a unique id is generated. Nested tables use the nearest ancestor id to inherit widths. |
| `inheritColumnWidths` | `string \| boolean \| undefined` |  |  | Opt a nested table into inheriting its column widths from an ancestor table's matching tracks (accounting for `select`/`actions` columns). This also makes the parent's tracks authoritative, so it is **off by default** — a nested table rende… |
| `interactiveWhileLoading` | `boolean \| undefined` | `false` |  | Keeps the table interactive while it is loading. The header and the rows are `inert` while loading by default — a refetch is about to replace the rows, so editing, selecting or sorting them races the incoming data. This escape hatch exists … |
| `items` | `Item[] \| ((prefill: boolean, modelValue?: any) => Item[] \| Promise<Item[]>)` | `[]` | yes | Rows to render, or a fetcher that returns them. |
| `itemValue` | `ItemAccessor<Item> \| undefined` |  |  |  |
| `keyboardNavigation` | `boolean \| undefined` | `false` |  | Opt-in keyboard navigation with a roving tabindex: the body is one tab stop, ArrowUp/ArrowDown move the focused row (Home/End jump), and Enter/Space activate it through the same path as a mouse click (highlight toggle + `click:row`). Focus … |
| `legend` | `string \| undefined` |  |  | Text content of the `<legend>` a `selectable` table renders (it becomes a `<fieldset>`, and the legend is that fieldset's accessible name). Omit it and the table falls back to `caption`, then to a localized default — the fieldset always end… |
| `loading` | `boolean \| undefined` | `false` |  | Sets the component in a loading state, usually triggering some visual styles. With no rows yet this renders skeletons; over existing rows the rows stay on screen (dimmed, with an indeterminate bar) rather than being replaced — a refetch sho… |
| `loadingText` | `string \| undefined` | `the localized `common.loadingText` ("Loading...")` |  | Screen-reader announcement for the loading row's `aria-live` status. Visually hidden — the skeleton (or the `#loading` slot) is the visible signal. |
| `max` | `number \| undefined` | `Infinity` |  | Maximum number of items that can be selected. |
| `modelValue` | `any` | `[]` |  | Used by v-model. Can be any serializable type. |
| `multiple` | `boolean \| undefined` | `true` |  | Allows the selection of multiple items. |
| `name` | `string \| undefined` |  |  | Defines the name of the input. |
| `noDataText` | `string \| undefined` | `the localized `common.noDataText` ("No data to display")` |  | String displayed when there are no items to display. |
| `order` | `string[] \| undefined` | `[]` |  | Used by `v-model:order`. Ordered array of column keys — the render order of the data columns. Keys listed here render first, in this order; declared columns it omits follow, in declaration order (so a column added to `columns` later renders… |
| `page` | `string \| number \| undefined` |  |  | Current page number starting from 1, used for accessibility purposes. Also flows into the shared table context, so a `BbPagination` paired through `id` reads it as the current page. Numeric strings are coerced (server pagination fields ofte… |
| `perPage` | `string \| number \| undefined` |  |  | Number of items per page, used for accessibility purposes. Also flows into the shared table context read by a `BbPagination` paired through `id`. When omitted, an array `items` table infers it from `items.length`; an explicit value (or a co… |
| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
| `reorderable` | `boolean \| undefined` | `false` |  | Lets the user reorder the data columns: drag a header cell (AG Grid style — the column moves live under the pointer and a chip with its label follows) or, from the keyboard, use each header's reorder handle (ArrowLeft / ArrowRight move the … |
| `resizable` | `boolean \| undefined` | `false` |  | Lets the user resize the data columns of a root table: drag the handle on a header's trailing edge (the column follows live, the width commits on release), or press Alt + ArrowLeft / ArrowRight on the focused header; double-click the handle… |
| `rowClass` | `RowClasses<Item> \| undefined` |  |  | Defines the classes to be passed to each data row. Can also be a function of the row's item for dynamic values. |
| `selectable` | `boolean \| ((item: Item) => boolean) \| undefined` |  |  | Defines whether the table is selectable. Can be a global boolean that affects all rows or a function that accepts an item and returns a boolean that only affects that item. |
| `selectAll` | `boolean \| undefined` | `false` |  | Defines whether the "Select all" checkbox is checked. |
| `selectAllLabel` | `string \| undefined` |  |  | Text of the label used by the "Select all" boolean. |
| `selectText` | `string \| undefined` |  |  | Text of the header used for the radio inputs when the table is not `multiple`. |
| `sort` | `BbTableSortEntry[] \| undefined` | `[]` |  | Used by `v-model:sort`. Ordered array of `[columnKey, direction]` entries, one per actively sorted column. Bidirectional: the header buttons of `sortable` columns update it, and external writes update the header indicators. The table does n… |
| `tdClass` | `ColumnClasses<Item> \| undefined` |  |  | Defines the classes to be passed to every data cell. Can also be a function for dynamic values. |
| `thClass` | `Classes \| undefined` |  |  | Defines the classes to be passed to every header cell. |
| `totalItems` | `string \| number \| undefined` |  |  | Total number of items there is. Also flows into the shared table context, where a `BbPagination` paired through `id` derives its page count from it. When omitted, an array `items` table infers it from `items.length`; an explicit value (or a… |
| `totalPages` | `string \| number \| undefined` |  |  | Seeds the page count shown by a `BbPagination` paired through `id`. A shortcut for when the server reports a page count rather than a row count: the table renders nothing from it, it only flows into the shared table context. A known total a… |
| `unselectedItems` | `any[] \| undefined` | `[]` |  | Items that are not selected. |
| `virtual` | `boolean \| undefined` | `false` |  | Windows the body: only the rows in (and just around) the vertical scrollport are mounted, so a client-side dataset of any size scrolls at a constant cost. The table itself is the scroller as soon as you bound its height (`max-height` / `hei… |

## Events

- `click:row` — `(e: "click:row", event: MouseEvent, item: any): void`
- `contextmenu:row` — `(e: "contextmenu:row", event: MouseEvent, item: any): void`
- `dblclick:row` — `(e: "dblclick:row", event: MouseEvent, item: any): void`
- `item:selected` — `(e: "item:selected", value: any): void`
- `item:unselected` — `(e: "item:unselected", value: any): void`
- `resize:column` — `(e: "resize:column", key: string, width: number \| null): void` — A column was resized by the user (`resizable`): the new width in px, or `null` when the handle was double-clicked to reset the column to its declared width.
- `update:expandedItems` — `(e: "update:expandedItems", value: any[]): void`
- `update:highlighted` — `(e: "update:highlighted", value: any): void`
- `update:modelValue` — `(e: "update:modelValue", value: any): void`
- `update:order` — `(e: "update:order", value: string[]): void`
- `update:selectAll` — `(e: "update:selectAll", value: boolean): void`
- `update:sort` — `(e: "update:sort", value: BbTableSortEntry[]): void`
- `update:unselectedItems` — `(e: "update:unselectedItems", value: any[]): void`

## Slots

- `actions` — scope: `{ expanded?: boolean \| undefined; expandProps?: ExpandControllerProps \| undefined; toggleExpanded?: (() => void) \| undefined; highlighted?: boolean \| undefi…` — Content rendered in the actions cell for each row.
- `expand` — scope: `{ expanded: boolean; expandProps?: ExpandControllerProps \| undefined; toggleExpanded: () => void; highlighted?: boolean \| undefined; toggleHighlighted?: (() =…` — Full-width expandable content row rendered below each main row when expanded.
- `header:actions` — scope: `{ text: string; }` — Replaces the default actions header cell content.
- `header:append` — scope: `BbTableHeaderAffixSlotProps<Item>` — Content rendered after every data column's header cell content — the label + sort control, or the column's own `header:<key>` replacement. A column's `header:<key>:append` slot wins over this one for that column; they never stack. Branch on…
- `header:prepend` — scope: `BbTableHeaderAffixSlotProps<Item>` — Content rendered before every data column's header cell content — the label + sort control, or the column's own `header:<key>` replacement. A column's `header:<key>:prepend` slot wins over this one for that column; they never stack. Branch …
- `header:select` — scope: `{ multiple: boolean; selectAll: boolean; text: string; }` — Replaces the default selection header cell content (checkbox or radio label).
- `loading` — scope: `{ items: Item[]; }` — Content shown while table rows are loading (replaces the skeleton rows).
- `no-data` — scope: `object` — Content shown when the items list is empty and not loading. It fills the table's own full-width empty-state cell (it already spans the selection/actions columns), so provide the *content* — a message, an illustration, a "clear filters" butt…
- `select` — scope: `{ item: Item; value: any; checked: boolean; disabled: boolean; inputName: string; readonly: boolean; toggleSelected?: (() => void) \| undefined; }` — Replaces the default checkbox/radio in the selection cell for each row.
- `tbody` — scope: `object` — Replaces the content of the body row group (`.bb-table__body`). Use when you need full control over the body markup. Provide role-complete rows — `<div role="row">` holding one `<div role="cell">` per column — never a `<tr>`/`<td>`. A full-…
- `tfoot` — scope: `{ columnCount: number; }` — Fills the footer row group (`.bb-table__foot`). Use when you need a footer. Provide role-complete rows — `<div role="row">` holding `<div role="cell">` elements — never a `<tr>`/`<td>`.
- `thead` — scope: `object` — Replaces the content of the header row group (`.bb-table__head`). Use when you need full control over the header markup. The table is a CSS grid, not a `<table>`: provide role-complete rows — `<div role="row">` holding one `<div role="colum…

## See Also

- [BbTree](./BbTree.md) — Renders hierarchical expandable tree structures.
- [BbPagination](./BbPagination.md) — Navigates paginated data sets by page index.

---

<!-- dist/ai/BbTabs.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTabs.md -->

# BbTabs

## Agent Contract

- Safety level: **Consumer API**
- Group: **Navigation**
- Description: Switches between tabbed content views (shadcn-like strip; the co-located BbTabsRoot / BbTabsList / BbTabsPanes exports enable split layouts).
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbTabs.md](./source/BbTabs.md)

## Usage & Guidelines

### When to use

Reach for `BbTabs` to divide _one_ screen into peer sections the user flips
between without leaving the page — a profile's Overview / Activity / Settings, a
record's detail / history / comments. Every tab is a sibling view of the same
subject.

Do not use tabs for steps in a flow (that is a wizard), for hierarchy (that is
`BbBreadcrumbs`), or for genuinely separate destinations that deserve their own
URL and page. `BbTabs` switches peer sections of one subject; `BbBreadcrumbs`
answers "where am I and how do I get back up"; `BbPagination` steps through a
paged result set. Keep the strip short and the labels to a word or two; a strip
that overflows scrolls, but a dozen tabs usually means the page should be split.

The library ships the tabs family in two shapes with one shared API and one
shared context:

- **`BbTabs`** — batteries-included: the trigger strip immediately followed by
  its panes. Reach for it by default.
- **`BbTabsRoot` + `BbTabsList` + `BbTabsPanes`** — the same state, split so you
  can place arbitrary markup between the strip and the panes. Reach for it only
  when the layout demands it.

### Tabs with a pane per key

Pass `items` (`{ key, label }`), bind the active key with `v-model`, and provide
one slot named for each item `key` — that is the pane. With no `v-model` the
first enabled tab is selected for you (a `modelValue` of `null` behaves the same
way). `BbTabs` is the batteries-included form: the trigger strip and its panes
in one component.

**A tab strip and its panes**

```vue
<template>
	<div
		class="max-w-md rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
	>
		<div class="mb-3 flex flex-col gap-0.5">
			<p class="text-sm font-medium">Acme Checkout</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Project · last deploy 14m ago
			</p>
		</div>
		<BbTabs v-model="active" compact :items="tabs">
			<template #overview>
				<div class="grid gap-1.5 pt-3 text-sm">
					<p class="font-medium">Health: stable</p>
					<p class="text-xs text-[color:var(--bb-text-muted)]">
						Error rate 0.12% · p95 180ms · 3 open incidents
					</p>
				</div>
			</template>
			<template #activity>
				<ul class="divide-y divide-[color:var(--bb-border)] pt-3">
					<li
						v-for="event in activity"
						:key="event.id"
						class="flex flex-col gap-0.5 py-2"
					>
						<p class="text-sm">{{ event.text }}</p>
						<p class="text-xs text-[color:var(--bb-text-muted)]">
							{{ event.when }}
						</p>
					</li>
				</ul>
			</template>
			<template #members>
				<ul class="divide-y divide-[color:var(--bb-border)] pt-3">
					<li
						v-for="member in members"
						:key="member.email"
						class="flex items-center justify-between gap-2 py-2 text-sm"
					>
						<span class="truncate">{{ member.name }}</span>
						<span class="shrink-0 text-xs text-[color:var(--bb-text-muted)]">{{
							member.role
						}}</span>
					</li>
				</ul>
			</template>
		</BbTabs>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbTabs } from 'bitboss-ui';
import type { BbTabsItem } from 'bitboss-ui';

// `v-model` binds the active tab to a plain key ref. Seed it with a starting
// key; drop the binding entirely and BbTabs selects the first enabled tab.
type Section = 'overview' | 'activity' | 'members';

const tabs: Array<BbTabsItem<Section>> = [
	{ key: 'overview', label: 'Overview' },
	{ key: 'activity', label: 'Activity' },
	{ key: 'members', label: 'Members' },
];

const active = ref<Section>('overview');

const activity = [
	{ id: '1', text: 'Sam Chen merged billing retries', when: '12m ago' },
	{ id: '2', text: 'Alex Rivera rotated the Stripe key', when: '1h ago' },
	{ id: '3', text: 'Deploy v2.14.0 succeeded', when: 'Yesterday' },
];

const members = [
	{ name: 'Alex Rivera', email: 'alex@acme.co', role: 'Owner' },
	{ name: 'Sam Chen', email: 'sam@acme.co', role: 'Editor' },
	{ name: 'Jordan Lee', email: 'jordan@acme.co', role: 'Viewer' },
];
</script>
```

`v-model` is the whole event surface: the component emits `update:modelValue`
with the new key whenever the selection changes — from a click, a keyboard move,
URL navigation, or the companion composable — and it emits once on mount when a
URL query or the first-enabled fallback resolves a key the parent didn't set, so
your binding starts aligned. You rarely listen to the event directly; bind
`v-model` and read it. When `items` is generated, drive the panes with a
dynamic-name slot instead of writing one block per key:

**Dynamic pane slots from generated items**

```vue
<div
	class="max-w-md rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
>
	<BbTabs
		compact
		:items="[
			{ key: 'draft', label: 'Draft' },
			{ key: 'in-review', label: 'In review' },
			{ key: 'published', label: 'Published' },
		]"
	>
		<template
			v-for="stage in ['draft', 'in-review', 'published']"
			:key="stage"
			#[stage]
		>
			<p class="pt-3 text-sm capitalize text-[color:var(--bb-text-muted)]">{{ stage }} documents.</p>
		</template>
	</BbTabs>
</div>
```

### Rich labels and badges

Replace a tab's plain text with the `label:{key}` slot (one specific tab) or the
`label` slot (the fallback for every tab). Both receive the tab's state — `text`
(the item's `label`), `value` (its `key`), `selected`, `disabled`, plus the
group's `current` / `currentIndex` / `isFirst` / `isLast` and a `goTo` callback —
so a label can carry a count pill, an icon, or a status dot. Keep the whole
trigger the interactive target; put only presentation in the slot (do not nest a
button or link inside a label — the trigger is already the control).

**Unread count on the Inbox tab**

```vue
<template>
	<div
		class="max-w-md rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
	>
		<BbTabs v-model="active" compact :items="tabs">
			<template #label:inbox="{ text }">
				<span class="inline-flex items-center gap-1.5">
					{{ text }}
					<BbBadge size="sm" variant="soft-blue">{{ unread }}</BbBadge>
				</span>
			</template>
			<template #inbox>
				<ul class="divide-y divide-[color:var(--bb-border)] pt-3">
					<li
						v-for="thread in inbox"
						:key="thread.id"
						class="flex flex-col gap-0.5 py-2"
					>
						<p class="text-sm font-medium">{{ thread.subject }}</p>
						<p class="text-xs text-[color:var(--bb-text-muted)]">
							{{ thread.from }} · {{ thread.when }}
						</p>
					</li>
				</ul>
			</template>
			<template #sent>
				<p class="pt-3 text-sm text-[color:var(--bb-text-muted)]">
					12 messages sent this week.
				</p>
			</template>
			<template #spam>
				<p class="pt-3 text-sm text-[color:var(--bb-text-muted)]">
					3 filtered messages · last scan 2h ago.
				</p>
			</template>
		</BbTabs>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbBadge, BbTabs } from 'bitboss-ui';
import type { BbTabsItem } from 'bitboss-ui';

// Count pills ride in `label:{key}` — presentation only; the trigger stays the
// control. Soft badge palette from design-language.md § Using color.
type Folder = 'inbox' | 'sent' | 'spam';

const tabs: Array<BbTabsItem<Folder>> = [
	{ key: 'inbox', label: 'Inbox' },
	{ key: 'sent', label: 'Sent' },
	{ key: 'spam', label: 'Spam' },
];

const active = ref<Folder>('inbox');
const unread = 12;
const inbox = [
	{
		id: '1',
		subject: 'Invoice INV-1042 overdue',
		from: 'billing@acme.co',
		when: '10:14',
	},
	{
		id: '2',
		subject: 'Seat upgrade confirmed',
		from: 'hello@bitboss.io',
		when: 'Yesterday',
	},
	{
		id: '3',
		subject: 'Weekly product digest',
		from: 'product@northwind.io',
		when: 'Mon',
	},
];
</script>

<!-- Non-scoped on purpose: styles the child badge's soft variant (scoped CSS
     can't reach it without :deep). Canonical palette:
     ai/guides/design-language.md § Using color. -->
<style>
.bb-badge.bb-badge--soft-blue {
	--accent: #2563eb;
	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
	--border-width: 1px;
	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
}
</style>
```

Use `label:{key}` when only some tabs need decoration and `label` when every tab
follows one template (an icon + count for all). A badge that changes size after
mount — a count ticking up — is fine: the strip re-measures the sliding pill and
equal-width fit when label content resizes, so the layout keeps up on its own.

### Lazy by default, eager when state must persist

By default a pane's slot content mounts only when its tab first becomes active
and stays mounted thereafter — cheap panes, no wasted renders. Set `eager` to
render an inactive pane's content into the DOM anyway. Two reasons to reach for
it:

- **In-pane state that must survive switches** — a half-filled form, a scroll
  position, a loaded chart. Lazy panes unmount on the first switch away only if
  never activated; eager guarantees the node exists from the start, so nothing
  is lost.
- **SEO / SSR** — content in inactive panes is in the server-rendered HTML.

`eager` works at two granularities: on the component (every pane eager) or on a
single `items` entry (`{ key, label, eager: true }`) when only one pane is
expensive to lose. The example keeps a draft message alive while the user checks
the Audience and Schedule tabs:

**Eager panes keep an in-pane draft alive**

```vue
<template>
	<div
		class="max-w-md rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
	>
		<div class="mb-3 flex flex-col gap-0.5">
			<p class="text-sm font-medium">Product announcement</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Draft · scheduled for Tue 09:00 local
			</p>
		</div>
		<BbTabs v-model="active" compact eager :items="tabs">
			<template #message>
				<div class="grid gap-3 pt-3">
					<BbTextInput
						v-model="draft.subject"
						compact
						label="Subject"
						name="subject"
						placeholder="Your weekly product update"
						prepend:icon="lucide:megaphone"
					/>
					<BbTextInput
						v-model="draft.preview"
						compact
						label="Preview text"
						name="preview"
						placeholder="One line shown in the inbox"
					/>
				</div>
			</template>
			<template #audience>
				<p class="pt-3 text-sm text-[color:var(--bb-text-muted)]">
					Sending to
					<span class="font-medium tabular-nums">{{
						recipients.toLocaleString()
					}}</span>
					subscribers in the Product Announcements segment.
				</p>
			</template>
			<template #schedule>
				<p class="pt-3 text-sm text-[color:var(--bb-text-muted)]">
					Queued for Tuesday 09:00 in each recipient's local timezone.
				</p>
			</template>
		</BbTabs>
	</div>
</template>
<script setup lang="ts">
import { reactive, ref } from 'vue';
import { BbTabs, BbTextInput } from 'bitboss-ui';
import type { BbTabsItem } from 'bitboss-ui';

// `eager` renders every pane into the DOM up front. The Message form below is
// never unmounted when you switch to Audience or Schedule, so a half-typed
// draft survives the round trip — no manual state hoisting needed.
type Section = 'message' | 'audience' | 'schedule';

const tabs: Array<BbTabsItem<Section>> = [
	{ key: 'message', label: 'Message' },
	{ key: 'audience', label: 'Audience' },
	{ key: 'schedule', label: 'Schedule' },
];

const active = ref<Section>('message');
const recipients = 8420;
const draft = reactive({
	subject: 'Weekly product update',
	preview: 'Billing retries shipped · seat limits raised',
});
</script>
```

### Pane transitions

Switching tabs animates by default: panes slide horizontally in the direction of
travel (left when moving to an earlier tab, right for a later one — derived from
the index delta) and the container smooth-heights between differing pane sizes.
Opt out per axis with `disable-animate-x` (no horizontal slide) and
`disable-animate-y` (no height animation). Disable the height animation when a
pane hosts its own transitions or virtualized content that fights the
measurement, and disable both for instant, motion-free switching. The classic
case for "disable both" is a Code / Preview toggle on a docs or comment
composer — flipping modes should feel like a switch, not a slide. Note the draft lives in
the component's script, not inside the pane, so the default lazy panes lose
nothing when you flip back:

**Instant Code / Preview toggle**

```vue
<template>
	<div
		class="max-w-md rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
	>
		<div class="mb-3 flex flex-col gap-0.5">
			<p class="text-sm font-medium">Release notes</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Markdown draft · preview before publishing.
			</p>
		</div>
		<!-- Mode switch, not a carousel: disable both animation axes. Draft lives
		     in script so lazy panes lose nothing when flipping back. -->
		<BbTabs compact disable-animate-x disable-animate-y :items="tabs">
			<template #code>
				<div class="pt-3">
					<BbTextarea
						v-model="draft"
						auto-grow
						compact
						hide-label
						label="Markdown"
						placeholder="## Heading"
						:rows="5"
					/>
				</div>
			</template>
			<template #preview>
				<div class="grid gap-1.5 whitespace-pre-line pt-3 text-sm">
					<template v-if="draft.trim()">
						<p class="font-medium">{{ previewTitle }}</p>
						<p class="text-[color:var(--bb-text-muted)]">{{ previewBody }}</p>
					</template>
					<p v-else class="text-[color:var(--bb-text-muted)]">
						Nothing to preview.
					</p>
				</div>
			</template>
		</BbTabs>
	</div>
</template>
<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbTabs, BbTextarea } from 'bitboss-ui';
import type { BbTabsItem } from 'bitboss-ui';

// Code / Preview is a mode toggle: disable both animation axes so flipping
// feels instant. The draft lives in the script, not in the pane.
type Mode = 'code' | 'preview';

const tabs: Array<BbTabsItem<Mode>> = [
	{ key: 'code', label: 'Code' },
	{ key: 'preview', label: 'Preview' },
];

const draft = ref(
	'## Billing retries\n\nVerified on staging — invoice totals now match the ledger.'
);

const previewTitle = computed(() => {
	const heading = draft.value.match(/^##\s+(.+)$/m);
	return heading?.[1] ?? 'Untitled';
});

const previewBody = computed(() =>
	draft.value.replace(/^##\s+.+$/m, '').trim()
);
</script>
```

### Sizing, orientation, and density

`block` stretches the strip to full width with grid-equal triggers — every
trigger as wide as the widest, so the row reads as an even segmented control;
when the triggers exceed the width they keep those equal widths and the strip
scrolls. `compact` drops the whole scale a notch (a 28px strip instead of 32px,
smaller text and padding). `direction="vertical"` stacks the triggers in a
column beside the panes, with the pill sliding on the Y axis.

Mark any unreachable tab `disabled` on its item — it stays visible, is skipped
by keyboard navigation and by `goTo`, and can never be the default selection.
Disabling the whole group is a component-level `disabled` prop: every trigger
goes disabled and keyboard navigation is inert (use it while a parent is
loading, not as a permanent state).

Settings peer sections are the classic `block` strip — full-width equal
triggers over compact form panes. Pair with `navigation` + `replace` so the
active section stays in the URL without flooding Back history:

**Workspace settings sections**

```vue
<template>
	<div
		class="max-w-md rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
	>
		<div class="mb-3 flex flex-col gap-0.5">
			<p class="text-sm font-medium">Workspace settings</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Northwind Billing · changes save per section.
			</p>
		</div>
		<!-- `navigation` + `replace`: deep-linkable section, Back still leaves the page. -->
		<BbTabs
			v-model="section"
			block
			:items="tabs"
			navigation
			query-key="section"
			replace
		>
			<template #general>
				<div class="grid gap-3 pt-3">
					<BbTextInput
						v-model="org.name"
						compact
						label="Workspace name"
						name="workspace-name"
					/>
					<BbTextInput
						v-model="org.slug"
						compact
						label="URL slug"
						name="workspace-slug"
						prepend:icon="lucide:link"
					/>
					<div class="flex justify-end">
						<BbButton variant="primary" @click="onSaveGeneral">
							Save general
						</BbButton>
					</div>
				</div>
			</template>
			<template #members>
				<ul class="divide-y divide-[color:var(--bb-border)] pt-3">
					<li
						v-for="member in members"
						:key="member.email"
						class="flex items-center justify-between gap-2 py-2 text-sm"
					>
						<span class="min-w-0 truncate">
							<span class="font-medium">{{ member.name }}</span>
							<span class="text-xs text-[color:var(--bb-text-muted)]">
								· {{ member.email }}</span
							>
						</span>
						<span class="shrink-0 text-xs text-[color:var(--bb-text-muted)]">{{
							member.role
						}}</span>
					</li>
				</ul>
			</template>
			<template #billing>
				<div class="grid gap-1.5 pt-3">
					<p class="text-sm font-medium">Pro · €49 / month</p>
					<p class="text-xs text-[color:var(--bb-text-muted)]">
						Next invoice Jul 28, 2026 · Visa ···· 4242
					</p>
					<div class="pt-1">
						<BbButton prepend:icon="lucide:credit-card" variant="outline">
							Manage billing
						</BbButton>
					</div>
				</div>
			</template>
		</BbTabs>
	</div>
</template>
<script setup lang="ts">
import { reactive, ref } from 'vue';
import { BbButton, BbTabs, BbTextInput } from 'bitboss-ui';
import type { BbTabsItem } from 'bitboss-ui';

// Settings peer sections: block strip, compact fields, URL-synced with replace
// so Back leaves settings instead of walking tab history.
type Section = 'general' | 'members' | 'billing';

const tabs: Array<BbTabsItem<Section>> = [
	{ key: 'general', label: 'General' },
	{ key: 'members', label: 'Members' },
	{ key: 'billing', label: 'Billing' },
];

const section = ref<Section>('general');
const org = reactive({ name: 'Northwind Billing', slug: 'northwind' });
const members = [
	{ name: 'Alex Rivera', email: 'alex@northwind.io', role: 'Owner' },
	{ name: 'Sam Chen', email: 'sam@northwind.io', role: 'Admin' },
	{ name: 'Jordan Lee', email: 'jordan@northwind.io', role: 'Editor' },
];

const onSaveGeneral = async () => {
	await new Promise((resolve) => setTimeout(resolve, 400));
};
</script>
```

**Full-width strip with a disabled tab**

```vue
<div
	class="max-w-md rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
>
	<BbTabs
		block
		compact
		:items="[
			{ key: 'summary', label: 'Summary' },
			{ key: 'integrations', label: 'Integrations' },
			{ key: 'billing', label: 'Billing', disabled: true },
		]"
	>
		<template #summary><p class="pt-3 text-sm text-[color:var(--bb-text-muted)]">Environment status at a glance.</p></template>
		<template #integrations><p class="pt-3 text-sm text-[color:var(--bb-text-muted)]">Connected services.</p></template>
		<template #billing><p class="pt-3 text-sm text-[color:var(--bb-text-muted)]">Locked on this plan.</p></template>
	</BbTabs>
</div>
```

**Vertical, compact strip**

```vue
<div
	class="max-w-md rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
>
	<BbTabs
		compact
		direction="vertical"
		:items="[
			{ key: 'general', label: 'General' },
			{ key: 'security', label: 'Security' },
			{ key: 'api', label: 'API keys' },
		]"
	>
		<template #general><p class="px-3 text-sm text-[color:var(--bb-text-muted)]">Workspace basics.</p></template>
		<template #security><p class="px-3 text-sm text-[color:var(--bb-text-muted)]">Sessions and 2FA.</p></template>
		<template #api><p class="px-3 text-sm text-[color:var(--bb-text-muted)]">Personal access tokens.</p></template>
	</BbTabs>
</div>
```

A vertical strip reads a `--max-w` custom property (vertical only) to cap its
width — set `style="--max-w: 160px"` on the list and long labels ellipse instead
of widening the column. The strip never exceeds its container. Sizing otherwise
follows the design tokens (`--bb-control-h`, `--bb-radius`, `--bb-fs`); there is
no numeric size prop and no global tabs config to set — tokens and the `block` /
`compact` / `direction` props are the whole surface.

### Overflowing strips and scroll affordances

Both horizontal modes scroll when the triggers exceed the available width, and
the active trigger is always scrolled into view on selection — keyboard moves
never leave the focused tab off-screen. For a visible scroll control, wire the
`header:prepend` and `header:append` slots (rendered before / after the
scrollable list): each receives `canScrollLeft`, `canScrollRight`, `isScrolling`,
and a `scroll('left' | 'right')` callback that pages the strip by ~80% of its
width. Bind the arrows' `disabled` to the can-scroll flags so they dim at the
ends.

**Scroll arrows on an overflowing strip**

```vue
<template>
	<div
		class="max-w-md rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
	>
		<div class="mb-3 flex flex-col gap-0.5">
			<p class="text-sm font-medium">Release timeline</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Monthly notes · scroll arrows when the strip overflows.
			</p>
		</div>
		<BbTabs v-model="active" block compact :items="releases">
			<template #header:prepend="{ canScrollLeft, scroll }">
				<BbButton
					aria-label="Scroll tabs left"
					class="mr-1 shrink-0"
					:disabled="!canScrollLeft"
					icon="lucide:chevron-left"
					size="sm"
					variant="ghost"
					@click="scroll('left')"
				/>
			</template>
			<template #header:append="{ canScrollRight, scroll }">
				<BbButton
					aria-label="Scroll tabs right"
					class="ml-1 shrink-0"
					:disabled="!canScrollRight"
					icon="lucide:chevron-right"
					size="sm"
					variant="ghost"
					@click="scroll('right')"
				/>
			</template>
			<!--
				`slotKey(...)`, never the raw key. A pane's slot name is the
				NORMALIZED key, so `#[release.key]` only happens to work while the
				keys are already slug-safe (`v1`…`v9`). Give a release a realistic
				tag — `v3-1`, `2026-03` — and the raw key stops matching the slot
				name, and every pane silently renders empty.
			-->
			<template
				v-for="release in releases"
				:key="release.key"
				#[slotKey(release.key)]
			>
				<p class="pt-3 text-sm text-[color:var(--bb-text-muted)]">
					{{ release.label }} shipped the design-token overhaul and the tabs
					keyboard-navigation pass.
				</p>
			</template>
		</BbTabs>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbTabs, slotKey } from 'bitboss-ui';
import type { BbTabsItem } from 'bitboss-ui';

// A block strip with more triggers than fit: the pill and scroll-into-view keep
// the active trigger visible, and the header:prepend / header:append slots host
// scroll arrows fed by canScrollLeft / canScrollRight / scroll from the list.
const months = [
	'January',
	'February',
	'March',
	'April',
	'May',
	'June',
	'July',
	'August',
	'September',
];
const releases: BbTabsItem[] = months.map((label, index) => ({
	key: `v${index + 1}`,
	label: `${label} 2026`,
}));

const active = ref('v1');
</script>
```

These slots live on `BbTabsList`, so they work identically in the batteries-
included `BbTabs` and in the split `BbTabsRoot` layout below.

### Split the strip from the panes with `BbTabsRoot`

When you need arbitrary markup _between_ the triggers and the panes — a toolbar
next to the strip, a divider, a sidebar layout — reach for the renderless
`BbTabsRoot`. It owns all the state (selection, `v-model`, URL/Inertia
navigation, keyboard navigation) and publishes it through provide/inject, so
`BbTabsList` and `BbTabsPanes` can sit anywhere in its subtree — no props, they
discover the nearest root automatically — and still align. A `BbTabsList` or
`BbTabsPanes` rendered outside any root throws with a descriptive error.

Its default slot hands you `select`, `goTo`, `current`, `currentIndex`,
`isFirst`, and `isLast` — enough to build Prev/Next controls or a live section
label without a template ref. A nested `BbTabs`/`BbTabsRoot` always shadows the
outer one, so an inner tab group never leaks into (or reads from) the parent's
context; use nesting freely.

**List and panes separated by a toolbar**

```vue
<template>
	<div
		class="max-w-md rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
	>
		<div class="mb-3 flex flex-col gap-0.5">
			<p class="text-sm font-medium">Acme Checkout</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Workspace · Prev/Next via root slot
			</p>
		</div>
		<BbTabsRoot v-model="active" compact :items="tabs">
			<template #default="{ goTo, isFirst, isLast }">
				<div class="flex items-center justify-between gap-2">
					<BbTabsList class="min-w-0 flex-1" />
					<div class="flex shrink-0 gap-1">
						<BbButton
							:disabled="isFirst"
							size="sm"
							variant="outline"
							@click="goTo('previous')"
						>
							Prev
						</BbButton>
						<BbButton
							:disabled="isLast"
							size="sm"
							variant="outline"
							@click="goTo('next')"
						>
							Next
						</BbButton>
					</div>
				</div>
				<hr class="my-3 border-[color:var(--bb-border)]" />
				<BbTabsPanes>
					<template #overview>
						<p class="text-sm text-[color:var(--bb-text-muted)]">
							Health stable · owners Alex + Sam · objective: cut checkout
							latency 20%.
						</p>
					</template>
					<template #activity>
						<p class="text-sm text-[color:var(--bb-text-muted)]">
							Shipped billing retries; fixed avatar upload timeout.
						</p>
					</template>
					<template #members>
						<p class="text-sm text-[color:var(--bb-text-muted)]">
							14 editors, 23 viewers, 3 billing admins.
						</p>
					</template>
				</BbTabsPanes>
			</template>
		</BbTabsRoot>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbTabsRoot, BbTabsList, BbTabsPanes } from 'bitboss-ui';
import type { BbTabsItem } from 'bitboss-ui';

// BbTabsRoot owns the state; the list and the panes are separated by a toolbar
// row and a divider, and the Prev/Next buttons drive it through the root slot.
type Section = 'overview' | 'activity' | 'members';

const tabs: Array<BbTabsItem<Section>> = [
	{ key: 'overview', label: 'Overview' },
	{ key: 'activity', label: 'Activity' },
	{ key: 'members', label: 'Members' },
];

const active = ref<Section>('overview');
</script>
```

`BbTabsRoot` takes the exact same props as `BbTabs` (`BbTabsRootProps` is
`BbTabsProps`), so everything in this guide — `items`, `block`, `compact`,
`direction`, `eager`, `navigation`, the Inertia options — applies unchanged; you
are only relocating the list and the panes.

### Drive a tab group from anywhere with `useBbTabsContext`

Give a tab group an explicit `id` and read or steer it from any component on the
client with `useBbTabsContext(id)` — no template ref, no shared subtree, no
being inside the tabs' tree. Pass the same `id` you gave the component (auto-
generated ids are not addressable) and optionally the key union to type
`current` / `select`. The returned handle is safe to destructure:

- `current` — a **writable** ref: reading it gives the active key (`null` until
  the tabs mount), and assigning a key selects it, exactly like `select(key)`.
  Assigning `null` warns and is ignored — a tab is always selected.
- `select(key)` — select by key; unknown keys warn and leave the selection
  untouched.
- `goTo('first' | 'previous' | 'next' | 'last')` — relative navigation, skipping
  disabled tabs.
- `currentIndex` (`-1` until mount), `isFirst`, `isLast`, and `isReady` (whether
  a tabs instance with this id is mounted yet).

The handle is callable before the tabs mount — it starts empty and auto-
populates when they render, emptying again on unmount; actions on an unmounted
id warn and no-op. Selection through the handle runs the tabs' full pipeline:
`v-model` is emitted and URL/Inertia navigation fires when the group has
`navigation`, identical to clicking the trigger. Here an alert banner outside
the tabs jumps straight to the Security section:

**Steer tabs from a banner outside their tree**

```vue
<template>
	<div
		class="max-w-md space-y-3 rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
	>
		<div class="grid gap-2">
			<BbAlert
				hide-close
				icon="lucide:shield-alert"
				text="Two-factor authentication is off for this account."
				title="Security review needed"
				variant="warning"
			/>
			<div class="flex justify-end">
				<BbButton variant="outline" @click="select('security')">
					Review security
				</BbButton>
			</div>
		</div>
		<!-- Same id as useBbTabsContext below; navigation+replace keeps the
		     section deep-linkable without flooding Back history. -->
		<BbTabs
			id="account-settings-tabs"
			v-model="section"
			compact
			:items="tabs"
			navigation
			query-key="account"
			replace
		>
			<template #profile>
				<div class="grid gap-3 pt-3">
					<BbTextInput
						v-model="profile.name"
						compact
						label="Display name"
						name="display-name"
					/>
					<BbTextInput
						v-model="profile.email"
						compact
						label="Contact email"
						name="contact-email"
						type="email"
					/>
				</div>
			</template>
			<template #security>
				<div class="grid gap-1.5 pt-3 text-sm">
					<p class="font-medium">Two-factor authentication</p>
					<p class="text-xs text-[color:var(--bb-text-muted)]">
						Off · last password change Mar 12, 2026 · 2 active sessions
					</p>
					<div class="pt-1">
						<BbButton prepend:icon="lucide:shield" variant="primary">
							Enable 2FA
						</BbButton>
					</div>
				</div>
			</template>
			<template #notifications>
				<p class="pt-3 text-sm text-[color:var(--bb-text-muted)]">
					Email digests and mention alerts for alex@northwind.io.
				</p>
			</template>
		</BbTabs>
		<p
			class="text-xs text-[color:var(--bb-text-muted)]"
			data-test="active-section"
		>
			Active section: {{ current }}
		</p>
	</div>
</template>
<script setup lang="ts">
import { reactive, ref } from 'vue';
import {
	BbAlert,
	BbButton,
	BbTabs,
	BbTextInput,
	useBbTabsContext,
} from 'bitboss-ui';
import type { BbTabsItem } from 'bitboss-ui';

type SectionKey = 'profile' | 'security' | 'notifications';

const tabs: Array<BbTabsItem<SectionKey>> = [
	{ key: 'profile', label: 'Profile' },
	{ key: 'security', label: 'Security' },
	{ key: 'notifications', label: 'Notifications' },
];

const section = ref<SectionKey>('profile');
const profile = reactive({
	name: 'Alex Rivera',
	email: 'alex@northwind.io',
});

// The alert banner lives OUTSIDE the tabs subtree: it reaches the group purely
// by id. `current` is a readable/writable ref, `select` jumps straight to a key.
const { current, select } = useBbTabsContext<SectionKey>(
	'account-settings-tabs'
);
</script>
```

Client-side only — during SSR the registry stays empty, so wire cross-component
behavior from hydration onward. Two mounted groups sharing an id is an error
(the handle resolves to the most recently mounted one). See the
[`useBbTabsContext`](./composables/useBbTabsContext.md) composable doc for the
full handle reference.

### URL and Inertia navigation

Set `navigation` to keep the active tab in the URL query (`query-key`, default
`tab`) so a tab is deep-linkable and survives reload. On load the query wins over
`modelValue`; thereafter switching writes the query.

**The URL carries a normalized slug, never the raw tab key.** The query value
goes through the same normalization as dynamic slot names — lowercased,
non-word characters folded to `_` — so a tab keyed `'In Review'` (or
`reviewStatus`) appears in the URL as `in_review` (`reviewstatus`). The
component round-trips this itself; the surprise lands on anything ELSE reading
the query — a server matching `?tab=` against camelCase keys silently never
matches. Either compare against the normalized form server-side, or use
lowercase keys for server-matched tabs.

**Back/forward re-selects the tab, on every platform.** On Vue Router/Nuxt the
re-selection watcher tracks the route's own query (`$route.query[queryKey]`),
so a matching query on Back/Forward re-selects the tab. Everywhere else —
Inertia, or a plain app with no router — a `popstate` listener re-derives the
tab straight from the address bar, so Back/Forward re-selects there too. The
two mechanisms never double-fire: the `popstate` listener steps aside whenever
a router is present, deferring to the route-query watch.

**Pair `navigation` with `replace`.** Without it every tab click pushes a
history entry, so a user who browsed four tabs needs four Backs to leave the
page — the tab strip hijacks the browser's Back button. With `replace` the URL
still carries the active tab (bookmarkable, survives reload, shareable) but the
entry is overwritten in place, so one Back returns to wherever they came from.
Reach for the push default only when a tab is a destination of its own — a
`server` visit whose content the user should be able to go Back to.

```vue
<!-- /project?tab=activity — bookmarkable, and Back still leaves the page -->
<BbTabs v-model="tab" :items="items" navigation query-key="tab" replace />
```

Navigation is always offloaded to the component — never pair tabs with a manual
`router.push`/`window.location` on click. In an Inertia app, give tabs an `href`
and the component navigates there — but the trigger stays a
`<button role="tab">`, never a link, so there is no middle-click, no hover
preview and no "copy link address" on a tab. (`href` is Inertia-only: under Vue
Router/Nuxt the destination is always the current route with the query patched,
and the prop is not read at all.) By default switching updates the URL
client-side (a `history.pushState`, no round-trip); set `server` (per item or on
the component) to make it a real Inertia visit via `router.visit`, and pass the
usual Inertia options — `only` for partial reloads, `preserveScroll`,
`preserveState`, `headers`, and the lifecycle hooks (`onBefore`, `onSuccess`,
`onError`, …) — on the component as defaults or per item as overrides. Item
values always win over component values. `server` without `navigation` is a
misconfiguration and logs an error. `replace` applies to both paths — it drops
the `pushState` to a `replaceState` on client-only switches, and makes the
Inertia visit a replace visit — so keep it on here too.

The client-only path writes `history.pushState`/`replaceState` against the
live browser URL, so it stays correct even once a `navigation` tab shares the
URL with other query state — filters, pagination, anything else driving an
Inertia visit. That said, when several writers patch the same query
independently, order-of-operations bugs are still easy to introduce by hand:
prefer having the page own the **whole** query and build every visit's URL,
tab strip included, from the current query object rather than a literal
query-key string. This is the pattern the current records-workspace-style
recipes use for tab `href`s.

**Who owns the URL.** With `navigation` on, the strip is a _writer_ of the
query, and it reads back only from its own clicks and from Back/Forward. Three
consequences worth stating outright, because each one bites in an Inertia page
that also drives the URL itself:

- **A `v-model` write is a navigation.** Assigning to the bound ref runs the
  same path a click does, so `view.value = 'closed'` inside your own handler
  fires the component's visit; if that handler then issues its own
  `router.visit`, the two race and the later response wins — right tab, wrong
  filters. Let the tab own the visit, or drop `navigation` and own the URL
  yourself.
- **The strip does not follow visits you make.** Under Inertia nothing watches
  `$page.url`, so a visit from a filter chip or a saved-view link that changes
  the tab parameter leaves the strip and pane on the old tab. Keep the tab in
  `v-model` and set it alongside that visit.
- **`query-key` is written onto `href`, not read from it.** The URL that lands
  is your `href` with `?{query-key}={slug}` set on it, so an `href` of
  `/incidents?view=open` under the default `query-key="tab"` navigates to
  `/incidents?view=open&tab=open`. Point `query-key` at the parameter your
  hrefs already encode.

A `server` tab commits its selection only when the visit **succeeds**: the
pane, pill and `v-model` stay on the current tab until the server confirms. A
navigation guard that prevents the visit (a dirty-form route-leave confirm) or
a failed visit leaves the tabs exactly where they were — no optimistic switch
to roll back:

```vue
<BbTabs
	:items="[
		{ key: 'overview', label: 'Overview', href: '/project/overview' },
		{
			key: 'activity',
			label: 'Activity',
			href: '/project/activity',
			server: true,
			only: ['events'],
		},
	]"
	navigation
	replace
	preserve-scroll
/>
```

Under Nuxt, `navigation` uses the same Vue Router path — the query is part of the
route, so it is SSR-safe and shareable:

```vue
<!-- Nuxt: query-synced tabs, resolved on the server for the first paint -->
<BbTabs :items="items" navigation replace query-key="section" />
```

### Works well with

- **`BbBadge` / count pills in `label` slots** — status dots and unread counts
  ride in the `label:{key}` or `label` slot; the strip re-measures when they
  resize.
- **`BbButton` for Prev/Next** — feed `goTo` from the `BbTabsRoot` default slot
  or from `useBbTabsContext`, binding `:disabled` to `isFirst`/`isLast`.
- **`BbTable` per tab** — one tab per saved view or status filter, each pane a
  `BbTable`; combine with `eager` if a table's fetched rows should survive tab
  switches.
- **`useBbTabsContext`** — the by-id handle for driving tabs from a page header,
  a keyboard-shortcut handler, or a banner far from the strip.

### Gotchas and anti-patterns

- **The sliding pill is measured from layout.** It reads the active trigger's
  `offsetLeft`/`offsetTop`, so render tabs in a visible, normally-positioned
  container. It settles itself on mount, resize, and font load, and paints a
  static pill until the first measurement lands — nothing to configure, and
  nothing to fight in demos.
- **Vertical strips answer Up/Down _and_ Left/Right arrows.** Up/Down is the
  primary pair (matching the vertical `aria-orientation`, per the ARIA APG);
  Left/Right keeps working as a forgiving extra. Horizontal strips answer
  Left/Right only — Up/Down keeps scrolling the page.
- **Do not rebuild navigation.** No `@click="router.push(...)"` to change a tab —
  use `navigation`/`query-key`/`href`. No manual `watch` to mirror the URL — the
  component owns it.
- **`navigation` without `replace` floods the history stack.** Each tab click
  becomes its own entry, so Back walks the user through their tab clicks
  instead of leaving the page — the same trap as a router-driven filter bar.
  Add `replace` unless a tab is a real destination the user should be able to
  go Back to.
- **Do not put interactive controls inside a `label` slot.** The trigger is
  already a button; a nested button/link is invalid and steals the click. Put
  actions in a pane or a toolbar (the `BbTabsRoot` layout), not in a label.
- **Don't reach for `BbTabsRoot` by default.** If you only need a strip over its
  panes, `BbTabs` is less markup and identical behavior; split only for markup
  between them.
- **Every tab disabled renders an inert tablist** — it does not throw. With no
  `modelValue` and no enabled tab there is nothing to select, so the strip
  renders with no active tab and no pane (`useBbTabsContext.ts:200-206` handles
  this deliberately). Nothing warns, so an all-disabled group looks like a
  rendering bug; leave at least one tab enabled, or hide the strip.

### Accessibility

- **Roles and relationships are wired for you.** The strip is a `tablist`, each
  trigger a `tab` with `aria-selected` and `aria-controls` pointing at its
  `tabpanel`, and each pane a `tabpanel` labelled by its trigger
  (`aria-labelledby`). Do not add these yourself.
- **Roving tabindex + keyboard.** Exactly one trigger is in the tab order
  (`tabindex="0"`); the rest are `-1`. **Left/Right** arrows move (and select)
  the previous/next enabled tab, wrapping around the ends; **Home** and **End**
  jump to the first/last enabled tab. Disabled tabs are skipped. Focus follows
  selection — arrowing to a tab activates it (automatic activation) — so panes
  should be cheap to switch (reach for lazy panes, the default). Vertical
  strips (`direction="vertical"`) follow the APG's vertical-tablist pattern:
  **Up/Down** move to the previous/next tab with the same wrapping, and
  Left/Right stay active as a forgiving alias. Up/Down do nothing on
  horizontal strips (they keep their page-scroll meaning).
- **Provide your own accessible names for icon-only affordances.** Scroll-arrow
  buttons in the `header:prepend`/`header:append` slots need an `aria-label`
  (they are your markup, not the component's).
- **Label slots carry presentation only.** Keep the accessible name in the
  trigger text; a decorative badge or icon in a `label` slot should not be the
  only thing announced.

## v-model

- `v-model` — type: `K \| null \| undefined`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `block` | `boolean \| undefined` | `false` |  | Displays the component as full width. |
| `compact` | `boolean \| undefined` | `false` |  | Adds a CSS class that applies a compact style to the component. |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `"horizontal"` |  | Direction of the tabs component. |
| `disableAnimateX` | `boolean \| undefined` | `false` |  | Disables the horizontal slide transition between tab panels (enabled by default). |
| `disableAnimateY` | `boolean \| undefined` | `false` |  | Disables the smooth height animation when switching between tab panels (enabled by default). |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
| `headers` | `Record<string, string> \| undefined` |  |  | Additional HTTP headers forwarded to Inertia when navigation is triggered. Only meaningful in an Inertia context. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `items` | `BbTabsItem<K>[]` |  | yes | Array of items that define the tabs in the component. |
| `modelValue` | `K \| null \| undefined` |  |  | The current tab key. Used by v-model. |
| `navigation` | `boolean \| undefined` | `false` |  | Synchronizes the current tab with the URL query parameter. Pair it with `replace` unless a tab is genuinely a separate destination — see the `replace` prop. |
| `onBefore` | `(() => boolean \| void) \| undefined` |  |  | Inertia lifecycle hook — fired just before the request is sent. Return `false` to cancel the visit. |
| `onCancel` | `(() => void) \| undefined` |  |  | Inertia lifecycle hook — fired when the request is cancelled. |
| `onError` | `((errors: Record<string, string>) => void) \| undefined` |  |  | Inertia lifecycle hook — fired when the server returns validation errors. |
| `onFinish` | `(() => void) \| undefined` |  |  | Inertia lifecycle hook — fired after the visit finishes (success or error). |
| `only` | `string[] \| undefined` |  |  | Limits which server-side props are refreshed during a partial Inertia reload. Only meaningful in an Inertia context. |
| `onProgress` | `((progress: { percentage: number \| undefined; }) => void) \| undefined` |  |  | Inertia lifecycle hook — fired when upload/download progress is available. |
| `onStart` | `(() => void) \| undefined` |  |  | Inertia lifecycle hook — fired when the request starts. |
| `onSuccess` | `(() => void) \| undefined` |  |  | Inertia lifecycle hook — fired when the visit completes successfully. |
| `preserveScroll` | `boolean \| ((props: Record<string, unknown>) => boolean) \| undefined` |  |  | Controls whether Inertia preserves the scroll position after navigation. Only meaningful in an Inertia context. |
| `preserveState` | `boolean \| ((props: Record<string, unknown>) => boolean) \| null \| undefined` |  |  | Controls whether Inertia preserves the current component state after navigation. Only meaningful in an Inertia context. |
| `queryKey` | `string \| undefined` | `"tab"` |  | Defines the query key used for URL-based navigation. |
| `replace` | `boolean \| undefined` | `false` |  | Replaces history rather than pushing it when changing tab. Recommended default whenever `navigation` is on: the query keeps the active tab (deep-linkable, survives reload) while Back still returns to the page the user came from, instead of … |
| `server` | `boolean \| undefined` | `false` |  | When true and in an Inertia context, triggers a real server-side Inertia visit instead of a client-only `history.pushState`. |

## Events

- `update:modelValue` — `(e: "update:modelValue", value: K): void` — Emitted when the selected tab changes. Used by `v-model`.

## Slots

- `header:append` — scope: `BbTabsScrollSlotProps` — Content rendered after the scrollable tab label list (e.g. a right scroll arrow).
- `header:prepend` — scope: `BbTabsScrollSlotProps` — Content rendered before the scrollable tab label list (e.g. a left scroll arrow).
- `label` — scope: `BbTabsSlotProps<K>` — Fallback slot used for all tab labels when no per-tab `label:{key}` slot is provided.

## See Also

- [BbAccordion](./BbAccordion.md) — Expands and collapses a content panel.
- [BbBreadcrumbs](./BbBreadcrumbs.md) — Renders hierarchical navigation paths.

---

<!-- dist/ai/BbTabsList.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTabsList.md -->

# BbTabsList

## Agent Contract

- Safety level: **Consumer API**
- Group: **Navigation**
- Description: The trigger strip of a split BbTabsRoot layout (renders the tab buttons only).
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbTabsList.md](./source/BbTabsList.md)

## Props

- None.

## Events

- None.

## Slots

- `header:append` — scope: `BbTabsScrollSlotProps` — Content rendered after the scrollable tab label list (e.g. a right scroll arrow).
- `header:prepend` — scope: `BbTabsScrollSlotProps` — Content rendered before the scrollable tab label list (e.g. a left scroll arrow).
- `label` — scope: `BbTabsSlotProps<string>` — Fallback slot used for all tab labels when no per-tab `label:{key}` slot is provided.

## See Also

- [BbTabs](./BbTabs.md) — Switches between tabbed content views (shadcn-like strip; the co-located BbTabsRoot / BbTabsList / BbTabsPanes exports enable split layouts).
- [BbTabsRoot](./BbTabsRoot.md) — Provide/inject root that lets BbTabsList and BbTabsPanes live in separate layout slots.
- [BbTabsPanes](./BbTabsPanes.md) — The pane host of a split BbTabsRoot layout (renders the tab content only).

---

<!-- dist/ai/BbTabsPanes.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTabsPanes.md -->

# BbTabsPanes

## Agent Contract

- Safety level: **Consumer API**
- Group: **Navigation**
- Description: The pane host of a split BbTabsRoot layout (renders the tab content only).
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbTabsPanes.md](./source/BbTabsPanes.md)

## Props

- None.

## Events

- None.

## Slots

- None.

## See Also

- [BbTabs](./BbTabs.md) — Switches between tabbed content views (shadcn-like strip; the co-located BbTabsRoot / BbTabsList / BbTabsPanes exports enable split layouts).
- [BbTabsRoot](./BbTabsRoot.md) — Provide/inject root that lets BbTabsList and BbTabsPanes live in separate layout slots.
- [BbTabsList](./BbTabsList.md) — The trigger strip of a split BbTabsRoot layout (renders the tab buttons only).

---

<!-- dist/ai/BbTabsRoot.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTabsRoot.md -->

# BbTabsRoot

## Agent Contract

- Safety level: **Consumer API**
- Group: **Navigation**
- Description: Provide/inject root that lets BbTabsList and BbTabsPanes live in separate layout slots.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbTabsRoot.md](./source/BbTabsRoot.md)

## v-model

- `v-model` — type: `K \| null \| undefined`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `block` | `boolean \| undefined` | `false` |  | Displays the component as full width. |
| `compact` | `boolean \| undefined` | `false` |  | Adds a CSS class that applies a compact style to the component. |
| `direction` | `"horizontal" \| "vertical" \| undefined` | `"horizontal"` |  | Direction of the tabs component. |
| `disableAnimateX` | `boolean \| undefined` | `false` |  | Disables the horizontal slide transition between tab panels (enabled by default). |
| `disableAnimateY` | `boolean \| undefined` | `false` |  | Disables the smooth height animation when switching between tab panels (enabled by default). |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
| `headers` | `Record<string, string> \| undefined` |  |  | Additional HTTP headers forwarded to Inertia when navigation is triggered. Only meaningful in an Inertia context. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `items` | `BbTabsItem<K>[]` |  | yes | Array of items that define the tabs in the component. |
| `modelValue` | `K \| null \| undefined` |  |  | The current tab key. Used by v-model. |
| `navigation` | `boolean \| undefined` | `false` |  | Synchronizes the current tab with the URL query parameter. Pair it with `replace` unless a tab is genuinely a separate destination — see the `replace` prop. |
| `onBefore` | `(() => boolean \| void) \| undefined` |  |  | Inertia lifecycle hook — fired just before the request is sent. Return `false` to cancel the visit. |
| `onCancel` | `(() => void) \| undefined` |  |  | Inertia lifecycle hook — fired when the request is cancelled. |
| `onError` | `((errors: Record<string, string>) => void) \| undefined` |  |  | Inertia lifecycle hook — fired when the server returns validation errors. |
| `onFinish` | `(() => void) \| undefined` |  |  | Inertia lifecycle hook — fired after the visit finishes (success or error). |
| `only` | `string[] \| undefined` |  |  | Limits which server-side props are refreshed during a partial Inertia reload. Only meaningful in an Inertia context. |
| `onProgress` | `((progress: { percentage: number \| undefined; }) => void) \| undefined` |  |  | Inertia lifecycle hook — fired when upload/download progress is available. |
| `onStart` | `(() => void) \| undefined` |  |  | Inertia lifecycle hook — fired when the request starts. |
| `onSuccess` | `(() => void) \| undefined` |  |  | Inertia lifecycle hook — fired when the visit completes successfully. |
| `preserveScroll` | `boolean \| ((props: Record<string, unknown>) => boolean) \| undefined` |  |  | Controls whether Inertia preserves the scroll position after navigation. Only meaningful in an Inertia context. |
| `preserveState` | `boolean \| ((props: Record<string, unknown>) => boolean) \| null \| undefined` |  |  | Controls whether Inertia preserves the current component state after navigation. Only meaningful in an Inertia context. |
| `queryKey` | `string \| undefined` | `"tab"` |  | Defines the query key used for URL-based navigation. |
| `replace` | `boolean \| undefined` | `false` |  | Replaces history rather than pushing it when changing tab. Recommended default whenever `navigation` is on: the query keeps the active tab (deep-linkable, survives reload) while Back still returns to the page the user came from, instead of … |
| `server` | `boolean \| undefined` | `false` |  | When true and in an Inertia context, triggers a real server-side Inertia visit instead of a client-only `history.pushState`. |

## Events

- `update:modelValue` — `(e: "update:modelValue", value: K): void` — Emitted when the selected tab changes. Used by `v-model`.

## Slots

- `default` — scope: `BbTabsRootSlotProps<K>` — Arbitrary layout hosting `BbTabsList` / `BbTabsPanes` anywhere in its subtree.

## See Also

- [BbTabs](./BbTabs.md) — Switches between tabbed content views (shadcn-like strip; the co-located BbTabsRoot / BbTabsList / BbTabsPanes exports enable split layouts).
- [BbTabsList](./BbTabsList.md) — The trigger strip of a split BbTabsRoot layout (renders the tab buttons only).
- [BbTabsPanes](./BbTabsPanes.md) — The pane host of a split BbTabsRoot layout (renders the tab content only).

---

<!-- dist/ai/BbTag.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTag.md -->

# BbTag

## Agent Contract

- Safety level: **Consumer API**
- Group: **Inputs**
- Description: Captures and displays tag-like token values.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbTag.md](./source/BbTag.md)

## Usage & Guidelines

### When to use

Use `BbTag` when the values are authored by the user, not chosen from a
predefined list: skills, keywords, email recipients, labels. `v-model` binds the
**array** of tokens; typing and pressing the divider key (Enter by default) turns
the current text into a chip, and Backspace from an empty field walks back
through the existing chips to remove them.

If the user should pick from a known set of options instead of inventing values,
use `BbSelect` (single or multi, with search). Tags are for open vocabularies.

**`BbTag` is a tags-_input_ — nothing more.** It exists to let a user type and
edit tokens; it is not a display component, and `readonly` mode is for
locking an existing input field, not for rendering tags elsewhere in the UI
(a table cell, a detail view, a card). For **read-only chips**, reach for
`BbBadge` instead: `clearable` gives a removable pill with the same close
affordance, and a `soft-*` registered variant (or a one-off `--bg`/`--color`
override for data-driven, per-record colors — see `BbBadge.md` § One-off
colors) covers colored tag chips without inventing a new component. See
Works well with, below, for the concrete pairing.

### The model is always an array

`BbTag`'s `modelValue` **must be an array** — the underlying control throws at
mount if it isn't. Seed it with `ref([])` (or the starting tags); never leave it
`undefined` or bind a scalar. This is why every interactive example here is a
small SFC with a typed `ref`, rather than an inline snippet.

```ts
const skills = ref<string[]>(['Vue', 'TypeScript', 'Design systems']); // ✅
// const skills = ref();                              // ✗ throws: modelValue must be an array
```

### Adding and removing

Seed `v-model` with the starting tags. `placeholder` prompts the first entry;
`clearable` shows a button to empty the whole field at once. Removing a single
tag is built in — click a chip's close button, or use Backspace (see the keyboard
section). Editing the text and pressing Enter commits it; the input clears ready
for the next.

**Skills input**

```vue
<template>
	<div
		class="flex max-w-md flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">Profile · Skills</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				Shown on your public profile and in search
			</span>
		</div>
		<BbTag
			v-model="skills"
			clearable
			compact
			hint="Press Enter to add, Backspace to remove the last."
			label="Skills"
			name="skills"
			persistent-hint
			placeholder="Add a skill…"
		/>
		<p class="text-xs text-[color:var(--bb-text-muted)]" data-testid="count">
			{{ skills.length }} skill{{ skills.length === 1 ? '' : 's' }} shown on
			your profile
		</p>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbTag } from 'bitboss-ui';

const skills = ref<string[]>(['Vue', 'TypeScript', 'Design systems']);
</script>
```

Besides `update:modelValue`, `duplicate` and `max` (below) the component
re-emits the native input events (`focus`, `blur`, `change`, `input`,
`keydown`, `keyup`, `click`) for analytics or side effects.

### Choosing the delimiter key

`divider` sets the key (or keys) that commit the current text to a chip; it
defaults to `'Enter'`. Set it to any `KeyboardEvent.key` — most usefully `','`
for a comma-to-add field — or to an array of keys such as `['Enter', ',']` when
either should work. With a single-character divider the component also splits a
value that already contains that character (e.g. pasted text), taking the text
up to the first delimiter.

**Comma- or Enter-delimited labels**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">Issue #4821</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]"
				>bitboss-ui · triage labels</span
			>
		</div>
		<BbTag
			v-model="labels"
			compact
			:divider="[',', 'Enter']"
			hint="Type a label and press comma or Enter to add it."
			label="Labels"
			name="labels"
			persistent-hint
			placeholder="bug, regression, breaking-change…"
		/>
		<p class="text-xs text-[color:var(--bb-text-muted)]" data-testid="labels">
			{{ labels.join(' · ') || 'No labels yet' }}
		</p>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbTag } from 'bitboss-ui';

const labels = ref<string[]>(['bug', 'high-priority']);
</script>
```

### Duplicates, max and feedback

Adding a value already present does **not** create a second chip — the component
emits a `duplicate` event with the offending string instead, which you can
surface as a warning.

Entries are **always trimmed** before they are committed or compared, so
`  vue  ` is stored as `vue`, a padded restatement of an existing tag counts as
a duplicate, and a whitespace-only entry is ignored rather than becoming an
invisible chip. Matching also **folds case by default** — `Vue` is a duplicate
of `vue` — because two chips differing only in case read as duplicates to the
user. The tag is still stored with the casing the user typed; only the
comparison folds. Set `case-sensitive` when case genuinely distinguishes two
tags:

```vue
<!-- 'Vue' and 'vue' can both exist -->
<BbTag v-model="tags" case-sensitive label="Tags" />
```

`max` caps the number of tags; once the cap is reached
further entries are rejected and the component emits a `max` event with the
rejected string — surface it the same way you would a `duplicate`, and show the
remaining count from `modelValue.length` if it helps. `max` is checked with
`!== undefined`, so **`max={0}` is a real quota** (zero tags allowed — useful
when a remaining allowance hits the floor), not “unlimited”.

**Recipients with a cap**

```vue
<template>
	<div
		class="flex max-w-md flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">Invite to Acme Studio</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				Up to 5 people · they get editor access
			</span>
		</div>
		<BbTag
			v-model="recipients"
			autocomplete="email"
			compact
			label="Invite people"
			:max="5"
			name="recipients"
			placeholder="Add an email…"
			prepend:icon="lucide:mail"
			@duplicate="onDuplicate"
			@max="onMax"
			@update:model-value="warning = ''"
		/>
		<p
			class="text-xs text-[color:var(--bb-text-muted)]"
			data-testid="invite-status"
		>
			{{ recipients.length }} / 5 invited<span v-if="warning">
				— {{ warning }}</span
			>
		</p>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbTag } from 'bitboss-ui';

const recipients = ref<string[]>(['ada@lovelace.dev', 'grace@hopper.io']);
const warning = ref('');

const onDuplicate = (value: string) => {
	warning.value = `${value} is already invited`;
};

const onMax = (value: string) => {
	warning.value = `cannot invite ${value}: the list is full`;
};
</script>
```

### Keyboard

With text in the field:

- A **divider** key (Enter by default) commits the text as a new chip.

With the field **empty**, the keys navigate and edit the existing chips:

- **Backspace** highlights the last chip, then removes the highlighted one on the
  next press — a two-step "select, then delete" rather than an instant wipe.
- **Arrow Left / Arrow Right** move the highlight between chips.
- **Home / End** jump to the first / last chip.
- **Escape** drops the chip highlight back to the input.

`readonly` and `disabled` suppress all of this while keeping existing chips
visible.

### Comma display mode

`comma` renders the selected tags as a single comma-separated string rather than
individual chips. It is a compact **display** mode — in it, chips cannot be
removed one by one (there are no close buttons), so use it where the set changes
rarely. `clearable` still empties the whole field.

**Digest topics as a comma list**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<span class="text-sm font-medium">Weekly digest</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">
				Topics land as a compact comma list
			</span>
		</div>
		<BbTag
			v-model="topics"
			clearable
			comma
			compact
			label="Digest topics"
			name="topics"
			placeholder="Add a topic…"
		/>
		<p class="text-xs text-[color:var(--bb-text-muted)]">
			Your weekly digest covers {{ topics.length }} topics.
		</p>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbTag } from 'bitboss-ui';

const topics = ref<string[]>(['Product updates', 'Engineering', 'Design']);
</script>
```

### Affordances and state

- `prepend:icon` / `append:icon` add a leading/trailing glyph (e.g. a mail icon
  for a recipients field) — decorative, so they never replace the label.
- `prefix` / `suffix` slots add inline content inside the field; `prepend` /
  `append` and their `-outer` variants add content in and around the input
  chrome.
- `loading` shows the loading affordance — useful while validating or
  de-duplicating tags against a server.
- `compact` applies the denser variant for toolbars.

### Disabled, readonly and errors

- `disabled` sets the native attribute: the field leaves the tab order and greys
  out; chips stay visible but inert.
- `readonly` keeps the field focusable and the chips visible but blocks typing
  and removal — prefer it, with an explanation, for a locked set of tags.
- `required` marks the field invalid until at least one tag is present (the
  underlying input drops its `required` once the array is non-empty). Combine
  with `errors` / `has-errors` for validation messaging; the input exposes
  `aria-invalid` in the error state.

### Works well with

- `BbSelect` — when the values come from a known list instead of free text.
- `useToast` — report a rejected `duplicate` / `max` entry or a server-side
  validation failure.
- `BbBadge` — the intended read-only counterpart: same token visual, `clearable`
  for a removable pill, a registered `soft-*` variant for a fixed recurring
  palette or a one-off `--bg`/`--color` override for arbitrary/data-driven
  colors. Reach for it any time tags need to be _shown_, not edited.

No plugin options change `BbTag` behaviour (no i18n strings of its own, no
teleport). It renders SSR-safe markup in Nuxt and Inertia apps.

### Gotchas and anti-patterns

- Don't bind a non-array (or `undefined`) `modelValue` — it throws at mount.
  Always seed `ref([])`.
- Don't stack up divider keys "just in case" — `divider` accepts an array
  (e.g. `['Enter', ',']`), but only add keys users actually expect; a comma
  divider makes values containing commas impossible to enter.
- Don't mutate the array from a `max` handler to "make room" — the rejected
  value is only reported; decide explicitly whether to raise the cap or warn.
- Don't hand-roll trimming or case-folding in an `update:modelValue` handler —
  entries are trimmed and matched case-insensitively already. Reach for
  `case-sensitive` only when `Vue` and `vue` really are different tags.
- Don't use `comma` mode when users need to remove individual tags — it has no
  per-chip close button.

### Label placement

`labelMode` places the label like on every other input — `outside` (above the
field), `inside`, or `floating` — and falls back to the plugin's
`defaultInputLabelMode` when unset, so a tag field matches the rest of the form
without being configured separately. It is orthogonal to `labelPosition`, which
only sets the label's text alignment.

```vue
<BbTag v-model="tags" label="Skills" label-mode="floating" />
```

### Accessibility

- `label` names the field; keep it visible unless an adjacent heading labels it
  (`hide-label`).
- `errors`, `warnings`, `description` and `hint` are all wired to the input through
  `aria-describedby`, in that order: the reason the field is invalid is spoken
  first when it regains focus, and a channel is referenced only while it
  actually has copy. Messages _also_ render in an `aria-live="polite"` region,
  so they are announced the moment they appear — announced on change, re-read
  on focus. The input exposes `aria-invalid` in the error state.
- Chip removal is keyboard-reachable (Backspace / arrows), not pointer-only.
- Prefer `readonly` (focusable, discoverable) over `disabled` for a locked set of
  tags, with a nearby explanation.

## v-model

- `v-model` — type: `string[]`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
| `autocomplete` | `string \| undefined` |  |  | Guides to the browser as to the type of information expected in the field. |
| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
| `caseSensitive` | `boolean \| undefined` | `false` |  | Compare tags case-sensitively when rejecting duplicates, so `Vue` and `vue` can both exist. By default matching folds case, because two chips differing only in case read as duplicates to a user. Either way the tag is stored with the casing … |
| `clearable` | `boolean \| undefined` | `false` |  | Displays a clear button when the input has a value and is being interacted with. |
| `comma` | `boolean \| undefined` | `false` |  | Sets the display model for selected values to a list of comma separated string. In this mode the user cannot deselect an option by pressing the close button. |
| `compact` | `boolean \| undefined` | `false` |  | Sets the component in a compact mode. |
| `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
| `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
| `divider` | `string \| string[] \| undefined` |  |  | The divider key used to separate values from one another. By default it is "Enter". Accepts a single key or an array of keys (e.g. `['Enter', ',']`) — any of them commits the current text. |
| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `label` | `string` |  | yes | Text content of the label of the element. |
| `labelMode` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Where the label sits relative to the field: `outside` above it, `inside` within the control, or `floating` (starts inside, lifts on focus/value). Defaults to `config.defaultInputLabelMode`, like the other inputs. |
| `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
| `loading` | `boolean \| undefined` | `false` |  | Sets the component in a loading state, usually triggering some visual styles. |
| `max` | `number \| undefined` |  |  | Maximum number of selected items. |
| `modelValue` | `string[]` |  | yes | Used by v-model. Contains all selected tags. |
| `name` | `string \| undefined` |  |  | Defines the name of the input. |
| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
| `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |

## Events

- `active` — `(event: "active"): void`
- `blur` — `(event: "blur", event: FocusEvent): void`
- `change` — `(event: "change", event: Event): void`
- `click` — `(event: "click", event: MouseEvent): void`
- `compositionend` — `(event: "compositionend", event: CompositionEvent): void`
- `compositionstart` — `(event: "compositionstart", event: CompositionEvent): void`
- `duplicate` — `(event: "duplicate", string: string): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `inactive` — `(event: "inactive"): void`
- `input` — `(event: "input", event: Event): void`
- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
- `keyup` — `(event: "keyup", event: KeyboardEvent): void`
- `max` — `(event: "max", string: string): void`
- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
- `paste` — `(event: "paste", event: ClipboardEvent): void`
- `update:modelValue` — `(event: "update:modelValue", value: string[]): void`

## Slots

- `append` — scope: `Record<string, never>` — Content appended inside the input field wrapper, after the tag chips.
- `append-outer` — scope: `Record<string, never>` — Content appended outside the input field wrapper.
- `label` — scope: `BbTagLabelSlotProps` — Replaces the default label text rendered above the input.
- `prefix` — scope: `Record<string, never>` — Content rendered as an inline prefix inside the input field.
- `prepend` — scope: `Record<string, never>` — Content prepended inside the input field wrapper, before the tag chips.
- `prepend-outer` — scope: `Record<string, never>` — Content prepended outside the input field wrapper.
- `suffix` — scope: `Record<string, never>` — Content rendered as an inline suffix inside the input field.

## Validated variant

Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).

| Prop | Type | Description |
| --- | --- | --- |
| `rules` | `RuleExpression<string[]>` | vee-validate rules for this field. |
| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |

## See Also

- [BbBadge](./BbBadge.md) — Displays a compact inline status counter or label. It sits in the flow — for a bubble or dot anchored OVER another element, use BbIndicator (includes the co-located BbBadgeButton export).
- [BbSelect](./BbSelect.md) — Selects one or many options from structured data.

---

<!-- dist/ai/BbTextarea.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTextarea.md -->

# BbTextarea

## Agent Contract

- Safety level: **Consumer API**
- Group: **Inputs**
- Description: Captures multi-line text values.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbTextarea.md](./source/BbTextarea.md)

## Usage & Guidelines

### When to use

Use `BbTextarea` for free-form text that runs to more than one line: comments,
bios, release notes, support messages, postal addresses. It shares the entire
input-family chrome with `BbTextInput` — `label`, `description`, `hint`,
`errors`, affix icons and slots, `clearable`, `loading` — so the two line up
pixel-for-pixel in the same form.

Pick a sibling when the shape of the data is different:

- one short string (name, email, code) → `BbTextInput`;
- a number with clamping/stepping → `BbNumberInput`;
- a calendar date → `BbDatePickerInput`;
- a value from a known set → `BbSelect` / `BbRadioGroup`.

`v-model` binds a `string | null` — an emptied field emits `null`, never `''`.
`label` is required (hide it visually with `hideLabel`, never drop it).

### Label

`label` names the field for display and accessibility only — it has **no**
effect on the native `name` attribute. Leave `name` unset and the rendered
`<textarea>` carries none at all, so a plain form post silently drops the
value. Pass `name` explicitly whenever the value is submitted via a native
form or read from `FormData`.

- **`hideLabel`** keeps the label for screen readers but removes it visually.
- **`labelPosition`** aligns the label text `left` / `center` / `right`.
- **`labelMode`** sets where the label sits, exactly like the sibling text
  inputs: `outside` (above/beside the field, the library default), `floating`
  (rests in the field and lifts on focus/fill) or `inside` (pinned small
  inside the top edge). Unset, it falls back to
  `config.defaultInputLabelMode` — so a project that floats its single-line
  inputs gets floating textarea labels for free.
- The **`label` slot** replaces the label text and receives `{ text, hasErrors, hasWarning }`
  — e.g. to append a required marker that turns red in the error state.

**Label, hidden label, and a custom label slot**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Member profile</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Label stays required — hide it visually or customize the slot.
			</p>
		</div>
		<BbTextarea
			v-model="bio"
			compact
			label="Bio"
			name="bio"
			placeholder="A short introduction…"
			:rows="3"
		>
			<template #label="{ text, hasErrors }">
				{{ text }}
				<span
					:class="
						hasErrors
							? 'text-[color:var(--bb-danger)]'
							: 'text-[color:var(--bb-text-muted)]'
					"
				>
					*
				</span>
			</template>
		</BbTextarea>
		<BbTextarea
			v-model="releaseNotes"
			compact
			label="Release notes"
			name="release-notes"
			:rows="3"
		/>
		<BbTextarea
			v-model="filter"
			compact
			hide-label
			label="Filter notes"
			name="filter-notes"
			placeholder="Filter notes…"
			:rows="2"
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbTextarea } from 'bitboss-ui';

const bio = ref<string | null>(
	'Product designer, coffee optimist, cat person.'
);
const releaseNotes = ref<string | null>(
	'Fixed a race in the autosave queue and tidied the empty states.'
);
const filter = ref<string | null>(null);
</script>
```

Avoid combining `labelMode="floating"` with a `placeholder` — the resting
label and the placeholder occupy the same spot.

**Floating and inside label modes**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Checkout · shipping</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Floating and inside labels — skip placeholders on floating fields.
			</p>
		</div>
		<BbTextarea
			v-model="shippingNotes"
			compact
			label="Shipping notes"
			label-mode="floating"
			name="shipping-notes"
			:rows="2"
		/>
		<BbTextarea
			v-model="deliveryInstructions"
			compact
			label="Delivery instructions"
			label-mode="inside"
			name="delivery-instructions"
			:rows="2"
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbTextarea } from 'bitboss-ui';

const shippingNotes = ref<string | null>(
	'Leave with the front desk if I am out.'
);
const deliveryInstructions = ref<string | null>(
	'Gate code 4417 — the dog is friendly.'
);
</script>
```

### Description, hint & validation

Three messaging surfaces, three jobs — identical to the rest of the input family:

- **`description`** — always-visible muted text between label and field, linked
  via `aria-describedby`. Use for instructions the user needs _before_ typing.
- **`hint`** — appears below the field while it's focused; `persistentHint`
  keeps it visible. Use for format examples or reassurance.
- **`errors`** — a string or string array rendered below the field in an
  `aria-live="polite"` region and referenced first from the field's
  `aria-describedby`, so new messages are announced when they appear and re-read
  when the field regains focus. **`hasErrors`**
  flips the visual error state and `aria-invalid`; passing a non-empty `errors`
  already implies the error state, so use `hasErrors` alone only when the
  message lives elsewhere (e.g. a form-level summary).
- **`warnings`** — the amber counterpart of `errors`: a string or string array
  rendered below the field in its own `aria-live="polite"` region — and
  referenced from `aria-describedby` while displayed — in amber
  (`--bb-text-warn`), for a valid-but-noteworthy value where a hard error would
  overstate the problem. A non-empty `warnings` implies the warning state, so
  **`hasWarning`** becomes just the force-the-chrome flag (tinted border, focus
  ring, warning icon) for when the message lives elsewhere — parallel to how
  `errors` relates to `hasErrors`. Unlike `errors`, `warnings` do **not** set
  `aria-invalid`, and `errors` win when both are set — the error state shows and
  the warning messages are suppressed, so the field never shows amber and red at
  once.

`required` forwards to the native `<textarea>` for browser validation; your own
validation layer should still drive `errors`.

**Description, persistent hint and validation**

```vue
<template>
	<div class="grid max-w-sm gap-3">
		<div class="grid gap-3 rounded-[var(--bb-radius)] border p-4">
			<div>
				<p class="text-sm font-medium">Public profile</p>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					Description before typing; hint while focused.
				</p>
			</div>
			<BbTextarea
				v-model="bio"
				compact
				description="Shown on your public profile."
				hint="Markdown is supported."
				label="Public bio"
				name="public-bio"
				persistent-hint
				placeholder="Tell people about yourself…"
				:rows="3"
			/>
		</div>
		<div class="grid gap-3 rounded-[var(--bb-radius)] border p-4">
			<div>
				<p class="text-sm font-medium">Request a refund</p>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					INV-2048 · Acme Studio
				</p>
			</div>
			<BbTextarea
				v-model="reason"
				compact
				:errors="reasonErrors"
				label="Reason for refund"
				name="refund-reason"
				placeholder="Required"
				:rows="3"
			/>
		</div>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbTextarea } from 'bitboss-ui';

const bio = ref<string | null>(
	'Staff engineer working on payments infrastructure.'
);
const reason = ref<string | null>(null);
const reasonErrors: string[] = [
	"Tell us why you're requesting a refund",
	'At least 10 characters',
];
</script>
```

### Rows & auto-grow

Two ways to size the box — and they compose:

- **`rows`** alone fixes the visible height and gives the user a native,
  vertically **resizable** scrolling box (drag the corner handle). Use it when
  a stable form layout matters more than seeing every line at once.
- **`autoGrow`** drops the resize handle and grows the field to fit its content
  as the user types (animated via `BbSmoothHeight`) — the right choice when you
  want people to see everything they wrote, e.g. a message composer.
- **Together**, `rows` becomes the minimum: the field starts at the `rows`
  height, grows past it as content demands, and never shrinks below it — so an
  empty composer keeps a comfortable height instead of collapsing to one line.
  Prefer this over a CSS `min-height`.

`rows` accepts a number or numeric string.

**Fixed rows, auto-grow, and rows as a floor**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Issue description</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Fixed rows, auto-grow, or rows as a minimum floor.
			</p>
		</div>
		<BbTextarea
			v-model="fixed"
			compact
			label="Release summary"
			name="release-summary"
			placeholder="Scrolls past 4 lines…"
			:rows="4"
		/>
		<BbTextarea
			v-model="grow"
			auto-grow
			compact
			label="Quick reply"
			name="quick-reply"
			placeholder="Grows as you type…"
		/>
		<BbTextarea
			v-model="floor"
			auto-grow
			compact
			label="Full description"
			name="full-description"
			placeholder="Starts at 2 rows, grows past them…"
			:rows="2"
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbTextarea } from 'bitboss-ui';

const fixed = ref<string | null>(
	'Rolled the 2.4 release, migrated the search index, and closed 12 issues.'
);
const grow = ref<string | null>('Looks good to me — shipping it.');
const floor = ref<string | null>(null);
</script>
```

The classic `autoGrow` home is a comment composer. The textarea stops Enter
from bubbling (see Events & v-model), so the post action lives on a button —
return a promise from its `@click` and `BbButton` shows the pending state
while the comment saves:

**Pull-request comment composer**

```vue
<template>
	<div class="grid max-w-md gap-3 rounded-[var(--bb-radius)] border p-3">
		<div>
			<p class="text-sm font-medium">PR #2048 · Review</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				feat/command-palette · 2 comments
			</p>
		</div>
		<article
			v-for="comment in comments"
			:key="comment.id"
			class="grid gap-0.5 border-t pt-2 first:border-t-0 first:pt-0"
		>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				{{ comment.author }} · {{ comment.postedAt }}
			</p>
			<p class="text-sm">{{ comment.body }}</p>
		</article>
		<BbTextarea
			v-model="draft"
			auto-grow
			compact
			hide-label
			label="Add a comment"
			name="comment"
			placeholder="Leave a comment…"
			:rows="3"
		/>
		<div class="flex justify-end">
			<BbButton :disabled="!draft" variant="primary" @click="post">
				Comment
			</BbButton>
		</div>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbTextarea, BbButton } from 'bitboss-ui';

type Comment = {
	id: number;
	author: string;
	postedAt: string;
	body: string;
};

const comments = ref<Comment[]>([
	{
		id: 1,
		author: 'Elena Vasquez',
		postedAt: '2 days ago',
		body: 'Can we ship this behind the beta-editor flag first?',
	},
	{
		id: 2,
		author: 'Tom Okafor',
		postedAt: 'yesterday',
		body: 'Flag added — ready for another look.',
	},
]);

const draft = ref<string | null>(null);

/** Stand-in mutation; the button spins until the promise settles. */
const post = async () => {
	const body = draft.value;
	if (!body) return;
	await new Promise((resolve) => setTimeout(resolve, 400));
	comments.value.push({
		id: comments.value.length + 1,
		author: 'You',
		postedAt: 'just now',
		body,
	});
	draft.value = null;
};
</script>
```

### Character counters

A live counter belongs in the `suffix` slot (or `append`), next to the value. It
is **visual only** — the textarea does not enforce a limit, so when hitting the
cap is a hard error, also surface it through `errors` so assistive tech is
informed. For a simple inline readout the `suffix` slot is enough:

**Status update with inline counter**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Status update</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Inline suffix counter — visual only, no hard cap.
			</p>
		</div>
		<BbTextarea
			v-model="status"
			auto-grow
			compact
			label="Status"
			name="status"
			placeholder="What's happening?"
			:rows="2"
		>
			<template #suffix>{{ (status || '').length }}/280</template>
		</BbTextarea>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbTextarea } from 'bitboss-ui';

const status = ref<string | null>(null);
</script>
```

For a self-contained, stateful counter with a typed limit — surfacing the cap
through `errors` once it's crossed, so assistive tech hears about it — use a
companion SFC:

**Support message with live counter**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Contact support</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Ticket #4812 · counter is visual; cap is enforced via errors.
			</p>
		</div>
		<BbTextarea
			v-model="message"
			auto-grow
			compact
			:errors="errors"
			hint="Tell us what happened — the more detail, the faster we can help."
			label="How can we help?"
			name="message"
			persistent-hint
			placeholder="Describe the issue…"
			:rows="2"
		>
			<template #suffix>{{ used }}/{{ limit }}</template>
		</BbTextarea>
	</div>
</template>
<script setup lang="ts">
import { ref, computed } from 'vue';
import { BbTextarea } from 'bitboss-ui';

const limit = 280;
const message = ref<string | null>(null);
const used = computed(() => message.value?.length ?? 0);
// The suffix counter is visual only — the hard cap is surfaced through
// `errors`, so assistive tech hears about it too.
const errors = computed(() =>
	used.value > limit
		? [`Keep it under ${limit} characters (currently ${used.value})`]
		: undefined
);
</script>
```

### Icons, affixes & slots

Use `prepend:icon` / `append:icon` for iconography inside the field, and the
`prefix` / `suffix` slots for short inline text. Affixes are decoration — they
never receive focus, so keep interactive controls out of them.

The append-icon position is shared with the field's status indicators, shown one
at a time by priority: **clear button → spinner (`loading`) → error icon
(`hasErrors`) → your `append:icon`**. The warning icon (`hasWarning`) shares the
error icon's slot — shown when `hasWarning` is set and there is no error. Don't
rely on an `append:icon` staying visible on a field that is also `clearable` or
validated.

The full slot ring, inside → out:

- `prefix` / `suffix` — styled inline text hugging the value (a counter's home);
- `prepend` / `append` — free-form content inside the input chrome;
- `prepend-outer` / `append-outer` — content outside the chrome, the right home
  for an adjacent button.

**Prepend icon and an outer action**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Deal notes</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Icons inside the chrome; copy actions sit in append-outer.
			</p>
		</div>
		<BbTextarea
			v-model="note"
			compact
			label="Internal note"
			name="internal-note"
			prepend:icon="lucide:sticky-note"
			:rows="2"
		/>
		<BbTextarea
			compact
			label="Install snippet"
			:model-value="snippet"
			name="install-snippet"
			readonly
			:rows="2"
		>
			<template #append-outer>
				<BbButton
					aria-label="Copy install snippet"
					icon="lucide:copy"
					variant="ghost"
				/>
			</template>
		</BbTextarea>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbTextarea, BbButton } from 'bitboss-ui';

const note = ref<string | null>(
	'Waiting on legal sign-off before we announce.'
);
const snippet = 'npx bitboss-ui ai-init';
</script>
```

### Clearable & loading

`clearable` reveals a clear button while the field has a value and is hovered or
focused; clicking it emits `update:modelValue` with `null` and is suppressed on
`disabled`/`readonly` fields. There is no separate `clear` event — watch the
model for `null`.

`loading` shows a spinner in the append position. It is **visual only** — the
field stays editable, so pair it with your own guard if the value must not
change mid-operation (e.g. an autosave round-trip). They compose freely.

**Clearable draft and a saving state**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Meeting notes</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Q3 roadmap sync · clearable draft and autosave spinner.
			</p>
		</div>
		<BbTextarea
			v-model="draft"
			clearable
			compact
			label="Draft"
			name="draft"
			placeholder="Start writing…"
			:rows="3"
		/>
		<BbTextarea
			v-model="autosaved"
			compact
			hint="Saving…"
			label="Shared notes"
			loading
			name="shared-notes"
			persistent-hint
			:rows="2"
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbTextarea } from 'bitboss-ui';

const draft = ref<string | null>(
	'Draft the launch email and send it to marketing.'
);
const autosaved = ref<string | null>('Reviewed the Q3 roadmap with the leads.');
</script>
```

### Disabled & readonly

`disabled` greys the field and blocks all interaction (also sets
`aria-disabled`); `readonly` keeps the value visible, focusable and copyable but
not editable (`aria-readonly`). Prefer `readonly` for terms text or derived
content — screen-reader and keyboard users can still reach it.

**Readonly terms and a disabled log**

```vue
<template>
	<div class="grid max-w-sm gap-3">
		<div class="grid gap-3 rounded-[var(--bb-radius)] border p-4">
			<div>
				<p class="text-sm font-medium">Refund policy</p>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					Readonly keeps terms focusable and copyable.
				</p>
			</div>
			<BbTextarea
				compact
				label="Terms"
				:model-value="terms"
				name="terms"
				readonly
				:rows="3"
			/>
		</div>
		<div class="grid gap-3 rounded-[var(--bb-radius)] border p-4">
			<div>
				<p class="text-sm font-medium">Deploy log</p>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					Disabled greys the field and blocks interaction.
				</p>
			</div>
			<BbTextarea
				compact
				disabled
				label="System log"
				:model-value="log"
				name="system-log"
				:rows="2"
			/>
		</div>
	</div>
</template>
<script setup lang="ts">
import { BbTextarea } from 'bitboss-ui';

const terms =
	'Refunds are processed within 5–7 business days of approval. Fees are non-refundable.';
const log = '2026-07-11 09:14 UTC — deploy failed: missing env DATABASE_URL';
</script>
```

### Density & layout

`compact` reduces the control height — apply it per view, not per field, so
density stays consistent.

`BbTextarea` honors `direction` and `reverse` as long as the resolved label
mode is `'outside'` (the library default) — like its siblings, the `floating`
and `inside` modes ignore `direction`. `direction="horizontal"` lays the label
beside the field (a 50/50 split); a space-separated pattern like `"xx xxxxx"`
sets the label/field width ratio from the token lengths; `reverse` swaps their
order. This makes it a good pick for label-beside-field settings rows.

**Horizontal layout and compact density**

```vue
<template>
	<div class="grid max-w-md gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Issue properties</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Horizontal outside labels + compact density on the whole panel.
			</p>
		</div>
		<BbTextarea
			v-model="summary"
			compact
			direction="horizontal"
			label="Summary"
			name="summary"
			:rows="3"
		/>
		<BbTextarea
			v-model="changelog"
			compact
			label="Changelog"
			name="changelog"
			:rows="2"
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbTextarea } from 'bitboss-ui';

const summary = ref<string | null>(
	'Adds keyboard navigation to the command palette and fixes focus traps.'
);
const changelog = ref<string | null>(
	'- Fix focus trap\n- Add palette shortcuts'
);
</script>
```

### Events & v-model

- `update:modelValue` — every value change; `string`, or `null` when emptied.
- `focus` / `blur` — forwarded `FocusEvent`s; they also drive the hint's
  show-on-focus behavior.
- `input` — every keystroke (raw DOM event); `change` — on commit (blur), the
  right hook for expensive side effects.
- `keydown`, `keyup`, `click`, `mousedown`, `mouseup`, `paste`,
  `compositionstart`, `compositionend` — forwarded as-is.

Known constraint: the textarea calls `stopPropagation()` on `input` and
`keydown`, so an Enter keystroke won't bubble to an enclosing form or list
handler; wire submit logic to a button, not to Enter-in-the-textarea (see the
comment composer above).

### Global config & platforms

- `compact`, `direction`, `reverse`, `labelMode`, `labelPosition` are the
  layout knobs; there is no size scale. An unset `labelMode` falls back to
  `config.defaultInputLabelMode`, keeping textarea labels in step with the
  rest of the form.
- The component wraps a plain controlled `<textarea>`: SSR-safe in Nuxt, no
  teleports or portals.
- In Inertia apps, bind server-side validation straight into the field:

```vue
<!-- Inertia: useForm drives value and errors -->
<BbTextarea
	v-model="form.notes"
	label="Notes"
	auto-grow
	:errors="form.errors.notes"
	:has-errors="!!form.errors.notes"
/>
```

### Works well with

- `BbTextInput` / `BbNumberInput` / `BbDatePickerInput` — same chrome and
  messaging surface; mix freely in one form (see the invoice form in the
  `BbTextInput` guide, which composes all four).
- `BbButton` — the submit action; wire it to a click handler, not to Enter,
  because the textarea stops Enter from bubbling.
- `useToast` — confirm a successful save after the form clears.

### Gotchas & anti-patterns

- With `autoGrow`, don't reach for a CSS `min-height` — pass `rows` as the
  floor; the field starts there and never shrinks below it.
- Avoid `labelMode="floating"` with `placeholder` — the resting label and the
  placeholder occupy the same spot.
- An emptied field emits `null`, not `''` — write `value ?? ''` when feeding
  APIs that require strings.
- A `suffix` counter does not enforce a limit; add `errors` when the cap is a
  hard rule.
- Don't rely on Enter to submit — it's `stopPropagation`'d; use a button.
- Don't rebuild the clear button in an `append` slot; `clearable` handles
  show/hide and clearing.
- Don't put interactive controls in `prefix`/`suffix` — use
  `append-outer`/`prepend-outer`.

### Accessibility

- Always provide `label`; hide it with `hideLabel` if the design has no room,
  never omit it.
- `errors`, `warnings`, `description` and `hint` are all wired to the textarea through
  `aria-describedby`, in that order: the reason the field is invalid is spoken
  first when it regains focus, and a channel is referenced only while it
  actually has copy. Messages _also_ render in an `aria-live="polite"` region,
  so they are announced the moment they appear — announced on change, re-read
  on focus.
- `hasErrors` (or a non-empty `errors`) sets `aria-invalid`;
  `disabled`/`readonly` set `aria-disabled`/`aria-readonly`.
- A character counter in the `suffix` is visual only — if the limit is a hard
  error, also surface it through `errors` so assistive tech is informed.
- Icon affixes are decorative and hidden from the accessible name; if an icon
  carries meaning, also say it in `hint` or `description`.

## v-model

- `v-model` — type: `string \| null`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
| `autocomplete` | `string \| undefined` |  |  | Guides to the browser as to the type of information expected in the field. |
| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
| `autoGrow` | `boolean \| undefined` | `false` |  | Expands the textarea to match its content. |
| `clearable` | `boolean \| undefined` | `false` |  | Displays a clear button when the input has a value and is being interacted with. |
| `compact` | `boolean \| undefined` | `false` |  | Sets the component in a compact state. |
| `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
| `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `label` | `string` |  | yes | Text content of the label of the element. |
| `labelMode` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Label rendering mode. `'outside'` (default) sits the label above/beside the field; `'floating'`/`'inside'` overlay it, like the other text inputs. |
| `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
| `loading` | `boolean \| undefined` | `false` |  | Sets the component in a loading state, usually triggering some visual styles. |
| `modelValue` | `string \| null` |  | yes | Used by v-model. |
| `name` | `string \| undefined` |  |  | Defines the name of the input. |
| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
| `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
| `rows` | `string \| number \| undefined` |  |  | Sets the number of visible text lines for the control. |
| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |

## Events

- `blur` — `(event: "blur", event: FocusEvent): void`
- `change` — `(event: "change", event: Event): void`
- `click` — `(event: "click", event: MouseEvent): void`
- `compositionend` — `(event: "compositionend", event: CompositionEvent): void`
- `compositionstart` — `(event: "compositionstart", event: CompositionEvent): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `input` — `(event: "input", event: Event): void`
- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
- `keyup` — `(event: "keyup", event: KeyboardEvent): void`
- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
- `paste` — `(event: "paste", event: ClipboardEvent): void`
- `update:modelValue` — `(event: "update:modelValue", value: string \| null): void`

## Slots

- `append` — scope: `Record<string, never>` — Content rendered after the textarea, at the end of the inner container.
- `append-outer` — scope: `Record<string, never>` — Content rendered after the entire textarea control, outside the input chrome.
- `label` — scope: `BbTextareaLabelSlotProps` — Replaces the default label text rendered above the textarea.
- `prefix` — scope: `Record<string, never>` — Inline content rendered at the start of the textarea field area, before the text.
- `prepend` — scope: `Record<string, never>` — Content rendered before the textarea, at the start of the inner container.
- `prepend-outer` — scope: `Record<string, never>` — Content rendered before the entire textarea control, outside the input chrome.
- `suffix` — scope: `Record<string, never>` — Inline content rendered at the end of the textarea field area, after the text.

## Validated variant

Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).

| Prop | Type | Description |
| --- | --- | --- |
| `rules` | `RuleExpression<string \| null>` | vee-validate rules for this field. |
| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |

## See Also

- [BbTextInput](./BbTextInput.md) — Captures single-line text values.
- [BbTag](./BbTag.md) — Captures and displays tag-like token values.

---

<!-- dist/ai/BbTextInput.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTextInput.md -->

# BbTextInput

## Agent Contract

- Safety level: **Consumer API**
- Group: **Inputs**
- Description: Captures single-line text values.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbTextInput.md](./source/BbTextInput.md)

## Usage & Guidelines

### When to use

Reach for `BbTextInput` for any short, single-line string: names, emails, URLs,
search boxes, coupon codes. It owns the shared input chrome — label, description,
hint, validation, affix icons/slots, `clearable`, `loading` and masking — that
the whole form family builds on.

Pick a sibling when the shape of the data is different:

- multi-line prose (bios, notes, messages) → `BbTextarea`;
- numbers with clamping/stepping (quantities, prices) → `BbNumberInput`;
- calendar dates → `BbDatePickerInput`;
- choosing from a known set of options → `BbSelect` / `BbRadioGroup`.

`v-model` binds a `string | null` — an emptied field emits `null`, never `''`.
`label` is required (hide it visually with `hideLabel`, never drop it).

### Label & label modes

`label` names the field for display and accessibility only — it has **no**
effect on the native `name` attribute. Leave `name` unset and the rendered
`<input>` carries none at all, so a plain form post silently drops the value.
Pass `name` explicitly whenever the value is submitted via a native form or
read from `FormData`.

- **`labelMode`** sets where the label sits: `outside` (above the field),
  `floating` (rests inside like a placeholder at reduced opacity, lifts on
  focus/fill) or `inside` (pinned small inside the top of the field). When you
  don't set it, the project-wide `config.defaultInputLabelMode` applies
  (library default: `outside`) — so a project can go all-floating without
  touching call sites.
- **`labelPosition`** aligns the label text `left` / `center` / `right`.
- **`hideLabel`** keeps the label for screen readers but removes it visually —
  the right move for search boxes whose design shows only a placeholder.
- The **`label` slot** replaces the label text and receives
  `{ text, hasErrors, hasWarning }`, e.g. to append a required marker that turns red with
  the error state.

Avoid combining `labelMode="floating"` with a `placeholder` — the resting
label already plays that role and the two would overlap.

**The three label modes**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Profile basics</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Same field, three label placements — pick one per product.
			</p>
		</div>
		<BbTextInput
			v-model="outside"
			label="Outside (default)"
			placeholder="Display name"
		/>
		<BbTextInput v-model="floating" label="Floating" label-mode="floating" />
		<BbTextInput v-model="inside" label="Inside" label-mode="inside" />
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbTextInput } from 'bitboss-ui';

const outside = ref<string | null>('Ada Lovelace');
const floating = ref<string | null>('ada@bitboss.it');
const inside = ref<string | null>('Bitboss');
</script>
```

**Custom label via slot**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Workspace settings</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Required fields mark the label — keep the accessible name intact.
			</p>
		</div>
		<BbTextInput
			v-model="organization"
			description="Appears on invoices and member invites."
			label="Organization"
			name="organization"
			placeholder="Bitboss"
		>
			<template #label="{ text, hasErrors }">
				{{ text }}
				<span
					:class="
						hasErrors
							? 'text-[color:var(--bb-danger)]'
							: 'text-[color:var(--bb-text-muted)]'
					"
				>
					*
				</span>
			</template>
		</BbTextInput>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbTextInput } from 'bitboss-ui';

const organization = ref<string | null>('Bitboss');
</script>
```

### Description, hint & errors

Three messaging surfaces, three jobs:

- **`description`** — always-visible muted text between label and field, linked
  via `aria-describedby`. Use for instructions the user needs _before_ typing.
- **`hint`** — appears below the field while it's focused; `persistentHint`
  keeps it visible. Use for reassurance or format examples.
- **`errors`** — a string or string array rendered below the field in an
  `aria-live="polite"` region and referenced first from the field's
  `aria-describedby`, so new messages are announced when they appear and re-read
  when the field regains focus. **`hasErrors`**
  flips the visual error state and `aria-invalid` — passing `errors` alone
  already implies the error state, so use `hasErrors` by itself when the
  message lives elsewhere (e.g. a form-level summary).
- **`warnings`** — the amber counterpart of `errors`: a string or string array
  rendered below the field in its own `aria-live="polite"` region — and
  referenced from `aria-describedby` while displayed — for a
  valid-but-noteworthy value (unusual, near a limit, soft-flagged) where a hard
  error would overstate the problem. A non-empty `warnings` implies the warning
  state (same as `errors` implies the error state). **`hasWarning`** forces that
  chrome without a message. Either way you get tinted border, focus ring and a
  warning icon in amber (`--bb-warn`) — but, unlike `hasErrors`, **no**
  `aria-invalid`. Errors win when both are set, and the warning messages are
  suppressed, so the field never shows amber and red at once.

`required` forwards to the native input for browser validation; your own
validation layer should still drive `errors`.

**The messaging surface, in one field**

```vue
<div class="max-w-sm">
	<BbTextInput
		v-model="state.displayName"
		label="Display name"
		description="This is the name shown on your public profile."
		hint="2–32 characters, letters and spaces."
		persistentHint
		placeholder="Ada Lovelace"
	/>
</div>
```

**Validation states**

```vue
<template>
	<div class="grid max-w-sm gap-3">
		<div class="grid gap-2 rounded-[var(--bb-radius)] border p-3">
			<p class="text-xs font-medium text-[color:var(--bb-text-muted)]">
				Invite teammate
			</p>
			<BbTextInput
				v-model="email"
				compact
				:errors="['Enter a valid email', 'Use your company domain']"
				label="Work email"
				name="email"
				placeholder="ada@bitboss.it"
				prepend:icon="lucide:mail"
				type="email"
			/>
		</div>
		<div class="grid gap-2 rounded-[var(--bb-radius)] border p-3">
			<p class="text-xs font-medium text-[color:var(--bb-text-muted)]">
				Non-blocking hint
			</p>
			<BbTextInput
				v-model="handle"
				compact
				label="Display name"
				name="handle"
				placeholder="ada"
				:warnings="['This name is very short — is it what you meant?']"
			/>
		</div>
		<div class="rounded-[var(--bb-radius)] border px-2 py-1.5">
			<BbTextInput
				v-model="search"
				class="w-full"
				clearable
				compact
				hide-label
				label="Search"
				placeholder="Search projects…"
				prepend:icon="lucide:search"
				type="search"
			/>
		</div>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbTextInput } from 'bitboss-ui';

const email = ref<string | null>('ada@');
const handle = ref<string | null>('ad');
const search = ref<string | null>('billing');
</script>
```

The second field carries `warnings` — a non-blocking amber hint in an
`aria-live` region and in `aria-describedby`, mirroring `errors`. A non-empty `warnings` lights the state
on its own (use `hasWarning` to force the chrome without messages). When a field
has **both** `errors` and `warnings`, errors win: the field shows error chrome
and only the error messages. The last field shows the common a11y move: a search
box with a _visually_ hidden label (`hideLabel`) — the accessible name survives
for screen readers even though the design shows only a placeholder.

### Icons, affixes & slots

Use `prepend:icon` / `append:icon` for iconography inside the field, and the
`prefix` / `suffix` slots for short inline text (units, fixed URL segments,
currency). Affixes are decoration — they never receive focus, so keep
interactive controls out of them.

The append-icon position is shared with the field's status indicators, one at
a time by priority: **clear button → spinner (`loading`) → error icon
(`hasErrors`) → your `append:icon`**. The warning icon (`hasWarning`) shares the
error icon's slot — shown when `hasWarning` is set and there is no error. Don't
rely on an `append:icon` staying visible on a field that is also `clearable` or
validated.

The full slot ring, inside → out:

- `prefix` / `suffix` — styled inline text hugging the typed value;
- `prepend` / `append` — free-form content inside the input chrome (replaces
  `prefix`/`suffix` when both are given);
- `prepend-outer` / `append-outer` — content outside the chrome, laid out next
  to the field; the right home for an adjacent button.

**Icons and text affixes**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Workspace & billing</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Icons and short affixes live inside the chrome; actions sit outside.
			</p>
		</div>
		<BbTextInput
			v-model="site"
			append:icon="lucide:check"
			compact
			label="Workspace URL"
			name="workspace-url"
		>
			<template #prefix>acme.app/</template>
		</BbTextInput>
		<BbTextInput v-model="price" compact label="Seat price" name="price">
			<template #prefix>$</template>
			<template #suffix>USD</template>
		</BbTextInput>
		<BbTextInput
			compact
			label="API key"
			:model-value="apiKey"
			name="api-key"
			readonly
		>
			<template #append-outer>
				<BbButton
					aria-label="Copy API key"
					icon="lucide:copy"
					variant="ghost"
				/>
			</template>
		</BbTextInput>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbTextInput } from 'bitboss-ui';

const site = ref<string | null>('acme');
const price = ref<string | null>('49.00');
const apiKey = 'sk_live_51Hn3x8Kj2';
</script>
```

### Clearable & loading

`clearable` reveals a clear button while the field has a value and is hovered
or focused; clicking it emits `update:modelValue` with `null` and refocuses the
input. There is no separate `clear` event — watch the model for `null`. The
button is suppressed on `disabled`/`readonly` fields.

`loading` shows a spinner in the append position. It is **visual only** — the
field stays editable, so pair it with your own guard if the value must not
change mid-check (e.g. an async username availability call). They compose: a
clearable field can also be loading.

The classic pairing is a signup handle checker: debounce keystrokes, flip
`loading` while the (simulated) availability call runs, then land the result
in `errors` or `hint`. Because the field stays editable during the check, the
handler tags each request and drops stale responses. Watching the model —
rather than listening to `input` — means the clear button's `null` also resets
the status.

**Async username check**

```vue
<template>
	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Claim your handle</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Debounced check — spinner while pending, hint or error on result.
			</p>
		</div>
		<BbTextInput
			v-model="username"
			clearable
			compact
			:errors="errors"
			:hint="hint"
			label="Username"
			:loading="checking"
			name="username"
			persistent-hint
			placeholder="ada"
		>
			<template #prefix>bitboss.app/</template>
		</BbTextInput>
	</div>
</template>
<script setup lang="ts">
import { ref, watch } from 'vue';
import { BbTextInput } from 'bitboss-ui';

const DEFAULT_HINT = 'Lowercase letters and digits, 3–20 characters.';
const TAKEN = ['ada', 'grace', 'linus'];

const username = ref<string | null>(null);
const checking = ref(false);
const errors = ref<string[]>([]);
const hint = ref(DEFAULT_HINT);

// Simulated availability endpoint — deterministic and fast.
const isTaken = (handle: string) =>
	new Promise<boolean>((resolve) => {
		setTimeout(() => resolve(TAKEN.includes(handle)), 400);
	});

let debounceTimer: ReturnType<typeof setTimeout> | undefined;
let requestId = 0;

// Watching the model (instead of @input) also covers the clear button,
// which emits `null` like any other emptied state.
watch(username, () => {
	errors.value = [];
	hint.value = DEFAULT_HINT;
	clearTimeout(debounceTimer);
	requestId += 1;
	checking.value = false;
	debounceTimer = setTimeout(async () => {
		const value = username.value?.trim().toLowerCase();
		if (!value) return;
		const id = ++requestId;
		checking.value = true;
		const taken = await isTaken(value);
		// `loading` is only a status light: the field stays editable, so a
		// newer keystroke may have superseded this check — drop stale results.
		if (id !== requestId) return;
		checking.value = false;
		if (taken) {
			errors.value = [`"${value}" is already taken`];
		} else {
			hint.value = `bitboss.app/${value} is available`;
		}
	}, 250);
});
</script>
```

### Masked input

Pass a [maska](https://beholdr.github.io/maska/v3) config to `mask` to format
as the user types — card numbers, phone numbers, license keys. By default
`v-model` receives the _unmasked_ value (`'4242424242424242'` for the card
below); set `emitMasked` to persist the formatted string instead. A fully
emptied masked field emits `null`, like every other state of this component.

The mask is live-reactive: changing the `mask` options at runtime reformats the
current value, and toggling `emitMasked` re-emits the model in the new format.

**Credit-card mask**

```vue
<div class="max-w-sm">
	<BbTextInput
		v-model="state.card"
		label="Card number"
		placeholder="4242 4242 4242 4242"
		prepend:icon="lucide:credit-card"
		:mask="{ mask: '#### #### #### ####' }"
	/>
</div>
```

Masks are for _formatting_; they don't validate. Keep `errors` in charge of
telling the user a complete-but-wrong value is invalid.

### Type, keyboard & autofill hints

`type` forwards any native input type (default `text`): use `email`, `url`,
`tel`, `search`, `password`. Don't use `type="number"` or `type="date"` — those
are `BbNumberInput`'s and `BbDatePickerInput`'s jobs.

- `autocomplete` passes through to the browser (`"email"`, `"current-password"`,
  `"one-time-code"`, `"off"`…) — set it on every field in auth and checkout
  flows. **Search and filter fields need `autocomplete="off"` just as much**:
  they are text inputs on a page that has seen a login, so the browser offers
  the saved email or name as a suggestion over the results the user is trying
  to filter. Semantic tokens belong on identity fields; anything that queries a
  list turns autofill off.
- `inputMode` steers mobile keyboards independently of `type` (e.g.
  `inputMode="numeric"` on a masked code field that must stay `type="text"`).
- `autofocus` focuses the field on mount; use at most one per view.

Any attribute you set that isn't one of the props documented above (e.g.
`maxlength`, `pattern`, `minlength`, `spellcheck`) lands on the field's outer
container element, not on the native `<input>` — it will not constrain or
affect typing. Use the documented props for anything the input itself needs
to enforce.

**An OTP field: text type, numeric keyboard, masked**

```vue
<div class="max-w-sm">
	<BbTextInput
		v-model="state.otp"
		label="Verification code"
		autocomplete="one-time-code"
		inputMode="numeric"
		:mask="{ mask: '### ###' }"
		placeholder="123 456"
	/>
</div>
```

There is no `revealable` prop — compose reveal-on-demand from a `ref` that
toggles `type` between `'password'` and `'text'`, plus a ghost icon `BbButton`
in the `#append` slot to flip it:

**Password with reveal toggle**

```vue
<template>
	<div class="max-w-sm">
		<BbTextInput
			v-model="password"
			autocomplete="current-password"
			label="Password"
			name="password"
			:type="revealed ? 'text' : 'password'"
		>
			<template #append>
				<BbButton
					:aria-label="revealed ? 'Hide password' : 'Show password'"
					:icon="revealed ? 'lucide:eye-off' : 'lucide:eye'"
					size="sm"
					variant="ghost"
					@click="revealed = !revealed"
				/>
			</template>
		</BbTextInput>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbTextInput } from 'bitboss-ui';

const password = ref<string | null>('');
const revealed = ref(false);
</script>
```

### Events & v-model

- `update:modelValue` — every value change; `string`, or `null` when emptied
  (with a mask: the unmasked/masked string per `emitMasked`).
- `focus` / `blur` — forwarded `FocusEvent`s; they also drive the hint's
  show-on-focus behavior.
- `input` — every keystroke (raw DOM event); `change` — on commit
  (blur/Enter), the right hook for expensive side effects.
- `keydown`, `keyup`, `click`, `mousedown`, `mouseup`, `paste`,
  `compositionstart`, `compositionend` — forwarded as-is; `paste` is the hook
  for normalizing pasted content, the composition pair for IME-aware logic.

### Disabled & readonly

`disabled` greys the field and blocks all interaction (also sets
`aria-disabled`); `readonly` keeps the value visible, focusable and copyable
but not editable (`aria-readonly`). Prefer `readonly` for derived or
provisioned values — screen-reader and keyboard users can still reach them.

**Disabled vs readonly**

```vue
<div class="grid max-w-sm gap-4">
	<BbTextInput :model-value="'Business (annual)'" label="Plan (managed by billing)" disabled />
	<BbTextInput :model-value="'eu-west-1'" label="Region" readonly hint="Set at workspace creation." persistentHint />
</div>
```

### Density & layout

`compact` reduces the control height — apply it per view, not per field, so
density stays consistent.

The API also exposes `direction` (horizontal/pattern layouts), `reverse` and
`labelPosition`. `direction` works whenever the **resolved** label mode is
`'outside'` — which is the config default, so it works out of the box. With
`labelMode="floating"` or `"inside"` (via prop or
`config.defaultInputLabelMode`) the label is embedded in the field, so those
modes force the vertical layout and ignore `direction`. The same rule applies
to `BbNumberInput`, `BbSelect`, `BbDatePickerInput` and `BbTextarea` — all
five carry `labelMode` and all five fall back to
`config.defaultInputLabelMode` when it is unset.

**Horizontal row via direction (outside label)**

```vue
<template>
	<div class="grid max-w-md gap-3 rounded-[var(--bb-radius)] border p-4">
		<div>
			<p class="text-sm font-medium">Billing contact</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Outside labels only — horizontal rows keep dense forms scannable.
			</p>
		</div>
		<BbTextInput
			v-model="fullName"
			compact
			direction="horizontal"
			label="Full name"
			name="full-name"
			placeholder="Ada Lovelace"
		/>
		<BbTextInput
			v-model="company"
			compact
			direction="xx xxxxxx"
			label="Company"
			name="company"
			placeholder="Bitboss"
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbTextInput } from 'bitboss-ui';

const fullName = ref<string | null>('Ada Lovelace');
const company = ref<string | null>('Bitboss');
</script>
```

`direction="horizontal"` splits label and field 50/50; a pattern string like
`"xx xxxxxx"` sets proportional column widths (here 25% label / 75% field).

**Compact density for dense panels**

```vue
<template>
	<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-3">
		<div>
			<p class="text-sm font-medium">Merino Tee — Black / M</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Product identifiers · compact density
			</p>
		</div>
		<BbTextInput
			v-model="sku"
			compact
			label="SKU"
			name="sku"
			placeholder="TSH-BLK-M"
		/>
		<BbTextInput
			v-model="barcode"
			compact
			label="Barcode"
			name="barcode"
			placeholder="0 12345 67890 5"
		/>
	</div>
</template>
<script setup lang="ts">
import { ref } from 'vue';
import { BbTextInput } from 'bitboss-ui';

const sku = ref<string | null>('TSH-BLK-M');
const barcode = ref<string | null>('0 12345 67890 5');
</script>
```

### Global config & platforms

- `config.defaultInputLabelMode` — project-wide default for `labelMode`
  (also read by `BbNumberInput`, `BbSelect` and `BbDatePickerInput`).
- The component is a plain controlled `<input>`: SSR-safe in Nuxt, no teleports
  or portals, nothing to hydrate carefully.
- In Inertia apps, bind server-side validation straight into the field:

```vue
<!-- Inertia: useForm drives value and errors -->
<BbTextInput
	v-model="form.email"
	label="Email"
	type="email"
	autocomplete="email"
	:errors="form.errors.email"
	:has-errors="!!form.errors.email"
/>
```

### A composed form

The input family shares one chrome, so fields line up cleanly when combined.
This invoice form pairs `BbTextInput` with `BbTextarea`, `BbNumberInput` and
`BbDatePickerInput`, and wires a real validation flow: required checks on
submit, format checks on blur, errors cleared as the user fixes them.

**Invoice form with validation**

```vue
<template>
	<form
		class="grid max-w-md gap-3 rounded-[var(--bb-radius)] border p-4"
		novalidate
		@submit.prevent="submit"
	>
		<div>
			<p class="text-sm font-medium">
				Invoice for {{ customer || 'a new client' }}
			</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Draft INV-2048 · validate on blur / submit, clear as they type
			</p>
		</div>
		<BbTextInput
			v-model="customer"
			clearable
			compact
			:errors="errors.customer"
			label="Bill to"
			name="customer"
			placeholder="Company or person"
			prepend:icon="lucide:user"
			required
			@input="errors.customer = ''"
		/>
		<BbTextInput
			v-model="email"
			autocomplete="email"
			compact
			:errors="errors.email"
			label="Billing email"
			name="email"
			placeholder="billing@company.com"
			prepend:icon="lucide:mail"
			required
			type="email"
			@blur="validateEmail"
			@input="errors.email = ''"
		/>
		<div class="grid gap-3 sm:grid-cols-2">
			<BbDatePickerInput
				v-model="servicePeriod"
				compact
				label="Service period"
				placeholder="Start → end"
				prepend:icon="lucide:calendar"
				range
			/>
			<BbDatePickerInput
				v-model="dueDate"
				compact
				:errors="errors.dueDate"
				label="Due date"
				:min="today"
				placeholder="YYYY-MM-DD"
				prepend:icon="lucide:calendar"
				@update:model-value="errors.dueDate = ''"
			/>
		</div>
		<div class="grid gap-3 sm:grid-cols-2">
			<BbNumberInput
				v-model="quantity"
				compact
				label="Quantity"
				:max="999"
				:min="1"
			/>
			<BbNumberInput
				v-model="unitPrice"
				compact
				label="Unit price"
				:max-precision="2"
				:min="0"
			>
				<template #prefix>$</template>
				<template #suffix>USD</template>
			</BbNumberInput>
		</div>
		<BbTextarea
			v-model="notes"
			auto-grow
			compact
			hint="Shown at the bottom of the invoice."
			label="Notes"
			persistent-hint
			placeholder="Payment terms, PO number…"
		/>
		<div
			class="flex flex-wrap items-center justify-between gap-2 border-t pt-3"
		>
			<p class="text-sm font-medium">
				{{
					queued ? `Queued — ${formattedTotal}` : `Total due: ${formattedTotal}`
				}}
			</p>
			<BbButton variant="primary" @click="submit">Queue invoice</BbButton>
		</div>
	</form>
</template>
<script setup lang="ts">
import { ref, reactive, computed } from 'vue';
import dayjs from 'dayjs';
import {
	BbButton,
	BbTextInput,
	BbTextarea,
	BbNumberInput,
	BbDatePickerInput,
} from 'bitboss-ui';

const customer = ref<string | null>(null);
const email = ref<string | null>(null);
const servicePeriod = ref<string[]>([]);
const dueDate = ref<string | null>(null);
const quantity = ref<number>(1);
const unitPrice = ref<number>(1200);
const notes = ref<string | null>(null);
const queued = ref(false);

const errors = reactive({ customer: '', email: '', dueDate: '' });

const today = dayjs().format('YYYY-MM-DD');

const isValidEmail = (value: string) =>
	/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);

// Format checks run on blur; required checks only on submit — never while
// the user is still typing a first attempt.
const validateEmail = () => {
	if (email.value && !isValidEmail(email.value)) {
		errors.email = 'Enter a valid email address';
	}
};

const submit = () => {
	queued.value = false;
	errors.customer = customer.value ? '' : 'Tell us who to bill';
	errors.email = email.value
		? isValidEmail(email.value)
			? ''
			: 'Enter a valid email address'
		: 'A billing email is required';
	errors.dueDate = dueDate.value ? '' : 'Pick a due date';
	if (!errors.customer && !errors.email && !errors.dueDate) {
		queued.value = true;
	}
};

const formattedTotal = computed(() =>
	new Intl.NumberFormat('en-US', {
		style: 'currency',
		currency: 'USD',
	}).format((quantity.value ?? 0) * (unitPrice.value ?? 0))
);
</script>
```

### Works well with

- `BbButton` — submit actions; an async `@click` handler gets automatic
  loading state while the save is in flight.
- `BbSelect` — when a free-text field grows a known option set, switch
  component instead of validating strings.
- `useToast` — confirm a successful save after the form clears.
- `BbTooltip` — attach extra context to the label via the `label` slot rather
  than cramming it into `description`.
- `BbTextarea` / `BbNumberInput` / `BbDatePickerInput` — same chrome, same
  messaging surface; mix freely in one form.

### Gotchas & anti-patterns

- An emptied field emits `null`, not `''` — write `value ?? ''` when feeding
  APIs that require strings.
- `direction` is ignored under `labelMode="floating"`/`"inside"` — those modes
  embed the label in the field and force the vertical layout (see _Density &
  layout_).
- `loading` does not lock the field — it's a status light, not a guard.
- Don't rebuild the clear button in an `append` slot; `clearable` already
  handles show/hide, clearing and refocusing.
- Don't put buttons in `prefix`/`suffix` — clicks there focus the input; use
  `append-outer`/`prepend-outer` for interactive neighbors.
- Don't validate _while_ the user types their first attempt; validate on
  `blur` or submit, then clear errors on `input` (see the invoice example).
- Masked fields emit the **unmasked** value by default — don't strip
  formatting server-side that was never sent.

### Accessibility

- Always provide `label`. To hide it visually, use `hideLabel` (keeps the
  accessible name) rather than omitting it.
- `errors`, `warnings`, `description` and `hint` are all wired to the input through
  `aria-describedby`, in that order: the reason the field is invalid is spoken
  first when it regains focus, and a channel is referenced only while it
  actually has copy. Messages _also_ render in an `aria-live="polite"` region,
  so they are announced the moment they appear — announced on change, re-read
  on focus. Keep messages meaningful, not decorative.
- `hasErrors` (or a non-empty `errors`) sets `aria-invalid` on the native
  input; `disabled`/`readonly` set `aria-disabled`/`aria-readonly`.
- Prefer real, always-enabled fields; when you must disable one, explain why
  nearby.
- Icon affixes are decorative and hidden from the accessible name — if an icon
  carries meaning (e.g. "verified"), also say it in `hint` or `description`.

## v-model

- `v-model` — type: `string \| null`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
| `autocomplete` | `string \| undefined` |  |  | Guides to the browser as to the type of information expected in the field. |
| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
| `clearable` | `boolean \| undefined` | `false` |  | Displays a clear button when the input has a value and is being interacted with. |
| `compact` | `boolean \| undefined` | `false` |  | Displays the component in a compact version. |
| `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
| `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
| `emitMasked` | `boolean \| undefined` | `false` |  | Emits the masked value of the input. |
| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `inputMode` | `"text" \| "search" \| "email" \| "url" \| "tel" \| "none" \| "numeric" \| "decimal" \| undefined` |  |  | The inputmode of the input. |
| `label` | `string` |  | yes | Text content of the label of the element. |
| `labelMode` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Label rendering mode. |
| `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
| `loading` | `boolean \| undefined` | `false` |  | Sets the component in a loading state, usually triggering some visual styles. |
| `mask` | `MaskInputOptions \| undefined` |  |  | The mask to be applied to the input. Please visit https://beholdr.github.io/maska/v3 for syntax examples. |
| `modelValue` | `string \| null` |  | yes | Used by v-model. |
| `name` | `string \| undefined` |  |  | Defines the name of the input. |
| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
| `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
| `type` | `"text" \| "search" \| "email" \| "url" \| "tel" \| "password" \| undefined` |  |  | Type of the input. Restricted to the textual input types this component supports — use `BbNumberInput` for numbers and `BbDatePickerInput` for dates. |
| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |

## Events

- `blur` — `(event: "blur", event: FocusEvent): void`
- `change` — `(event: "change", event: Event): void`
- `click` — `(event: "click", event: MouseEvent): void`
- `compositionend` — `(event: "compositionend", event: CompositionEvent): void`
- `compositionstart` — `(event: "compositionstart", event: CompositionEvent): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `input` — `(event: "input", event: Event): void`
- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
- `keyup` — `(event: "keyup", event: KeyboardEvent): void`
- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
- `paste` — `(event: "paste", event: ClipboardEvent): void`
- `update:modelValue` — `(event: "update:modelValue", value: string \| null): void`

## Slots

- `append` — scope: `object` — Content rendered after the text input, at the end of the inner container.
- `append-outer` — scope: `object` — Content rendered after the entire text input control, outside the input chrome.
- `label` — scope: `BbTextInputLabelSlotProps` — Replaces the default label text rendered above the input.
- `prefix` — scope: `object` — Inline content rendered at the start of the input field area, before the typed text.
- `prepend` — scope: `object` — Content rendered before the text input, at the start of the inner container.
- `prepend-outer` — scope: `object` — Content rendered before the entire text input control, outside the input chrome.
- `suffix` — scope: `object` — Inline content rendered at the end of the input field area, after the typed text.

## Validated variant

Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).

| Prop | Type | Description |
| --- | --- | --- |
| `rules` | `RuleExpression<string \| null>` | vee-validate rules for this field. |
| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |

## See Also

- [BbTextarea](./BbTextarea.md) — Captures multi-line text values.
- [BbNumberInput](./BbNumberInput.md) — Captures and validates numeric form values, emits a number value.
- [BbColorInput](./BbColorInput.md) — Captures color values through input controls.
- [BbDatePickerInput](./BbDatePickerInput.md) — Combines date selection with text input behavior.

---

<!-- dist/ai/BbTimePicker.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTimePicker.md -->

# BbTimePicker

## Agent Contract

- Safety level: **Consumer API**
- Group: **Overlay**
- Description: Opens hour/minute(/second) columns in a popover on a trigger you own — the time analog of BbDatePicker; also the v-bb-time directive.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbTimePicker.md](./source/BbTimePicker.md)

## Usage & Guidelines

### When to use

`BbTimePicker` is a **picker popover**, not a form field. It renders an activator
_you_ supply and opens floating time columns — with an adaptive bottom sheet on
mobile and optional range selection. The value is a 24-hour string via `v-model`,
the same contract as `BbTimePickerInput`.

Choose between the two time components by _what the control is_:

- A **typed field in a form** — a labelled row where the user reads and edits the
  time as text, with validation and hint/error chrome → **`BbTimePickerInput`**
  (`./BbTimePickerInput.md`). It embeds these exact columns and adds the whole
  segmented text-input surface around them.
- A time **assigned off your own trigger** — a cell in a schedule table, a chip, a
  button — no text field, no wrapper chrome → **`BbTimePicker`** (here). Think
  "set the opening time on this row", not "fill in this field".

For the leanest case, skip the component entirely and use the
[`v-bb-time` directive](#the-v-bb-time-directive).

### The value: 24-hour in, 24-hour out

`modelValue` is `null` (empty), a 24-hour `HH:mm` string (or `HH:mm:ss` with
`seconds`), or a two-element `[start, end]` array when `range` is true. The
`ampm` prop only changes the _display_ (12-hour columns plus an AM/PM column) —
the emitted value stays 24-hour. `min`/`max` (both `HH:mm`) clamp a pick to the
nearest bound and emit a `disabled_time` error.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { BbTimePicker } from 'bitboss-ui';

const opensAt = ref<string | null>(null);
</script>

<template>
	<BbTimePicker v-model="opensAt">
		<template #activator="{ props, value }">
			<button v-bind="props" type="button">
				{{ value ?? 'Set opening time' }}
			</button>
		</template>
	</BbTimePicker>
</template>
```

### The activator contract

Provide your trigger through the `#activator` slot. The scope hands you
everything to render and wire it:

- `props` — **spread onto your clickable element** (`v-bind="props"`). This
  registers the element as the popover reference and attaches the click handler
  and ARIA (`aria-haspopup="dialog"`, `aria-expanded`, `aria-label`) to it.
- `anchorProps` — spread onto a _wrapping_ element when the popover should align
  to something larger than the click target. When unused, the activator is also
  the anchor.
- `open` — whether the columns are currently shown (read-only).
- `value` — the current value, mirroring `modelValue`.
- `disabled` — mirrors the `disabled` prop.

Give it a `label`: it becomes the activator's `aria-label`, essential when your
trigger is an unlabelled cell or icon.

#### Attaching to an element you already have

When the trigger is an existing element or component (not markup you author in
the slot), pass it to the `activator` prop instead of using the slot — the same
click and ARIA wiring is attached programmatically, mirroring `BbDatePicker`.
`anchor` does the same for the positioning element.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { BbTimePicker, BbButton } from 'bitboss-ui';

const time = ref<string | null>('09:00');
const triggerRef = ref();
</script>

<template>
	<BbButton ref="triggerRef" variant="outline">Pick a time</BbButton>
	<BbTimePicker v-model="time" :activator="triggerRef" />
</template>
```

### Range, ampm, seconds, step

`range` turns the value into `[start, end]`; a small toggle above the columns
selects which end you are editing (`start` first by default, drivable via
`v-model:active-segment`). `ampm` renders 12-hour columns plus an AM/PM column
(the model stays 24-hour), `seconds` adds the third column, and `step` sets the
minute-column granularity and arrow stepping.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { BbTimePicker } from 'bitboss-ui';

const shift = ref<string[] | null>(['09:00', '17:00']);
</script>

<template>
	<BbTimePicker v-model="shift" range :step="15">
		<template #activator="{ props, value }">
			<button v-bind="props" type="button">
				{{
					Array.isArray(value) && value.length
						? value.join(' → ')
						: 'Pick a shift'
				}}
			</button>
		</template>
	</BbTimePicker>
</template>
```

### Adaptive and positioning

On mobile the columns open in a bottom off-canvas sheet instead of a floating
popover (`adaptive`, on by default via `config.adaptive`; forward extra sheet
props with `offCanvasProps`). Position the desktop popover with `placement`,
`offset`, `padding`, `boundary`, and `disableFlip` — the same knobs as the other
overlays. Escape and backdrop clicks close it; focus returns to the activator.

### The `v-bb-time` directive

For the leanest case — a time cell in a schedule table where you don't want a
component wrapper per row — attach the `v-bb-time` directive to the element
instead of importing `BbTimePicker`. It is registered globally by the plugin
(`injectDirectives`, on by default) and renders no wrapper.

The value is the picker's **props bag**, spread straight onto the component (same
model as `v-bb-date` / `v-bb-color`). A directive has no `v-model`, so bind
write-back with an `onUpdate:modelValue` callback. A directive argument sets
placement (`v-bb-time:top`); a nullish value attaches nothing, so it is safe to
bind conditionally.

```vue
<template>
	<span
		v-bb-time="{
			modelValue: row.opensAt,
			'onUpdate:modelValue': (t) => patch(row, { opensAt: t }),
		}"
	>
		{{ row.opensAt ?? 'Set time' }}
	</span>
</template>
```

Reach for the **component** (slot or `activator` prop) when you want the
`#activator` slot's scope or a separate `anchor`. Like the other value pickers,
the directive is the shortcut for the bare-trigger cell case, not a replacement
for the component's `v-model` in a form.

### Relationship to BbTimePickerInput

`BbTimePickerInput` _is_ these columns with a segmented text field wrapped around
them: the input owns the typing/validation engine and drives the same popover.
Anything you can select here you can also select there — pick `BbTimePicker` when
there is no text field to type into, `BbTimePickerInput` when there is.

### Accessibility

The activator carries `aria-haspopup="dialog"`, `aria-expanded`, and an
`aria-label` (from `label`, falling back to a localized "Open time picker"). The
columns expose labelled `role="group"` scrollers with keyboard support and digit
typeahead. Always pass a `label` when the trigger is an unlabelled cell or icon.

## v-model

- `v-model:activeSegment` — type: `BbTimePickerSegment \| undefined`
- `v-model` — type: `string \| string[] \| null`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activator` | `ElementOrComponentRef \| undefined` |  |  | External activator element or component ref. When provided, the `activator` slot is not rendered and click + ARIA are attached programmatically to the referenced element — mirroring `BbDatePicker`. |
| `activeSegment` | `BbTimePickerSegment \| undefined` |  |  | Which end the columns edit in range mode (`v-model:active-segment`). Standalone use manages this internally via the in-panel toggle; a host can drive it. Ignored outside `range`. |
| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile, open in a bottom off-canvas sheet instead of a floating popover. When unset, falls back to the global `config.adaptive`. |
| `ampm` | `boolean \| undefined` | `false` |  | 12-hour display with an AM/PM column; emitted values stay 24-hour. |
| `anchor` | `ElementOrComponentRef \| undefined` |  |  | Element or component ref the popover positions itself relative to. Defaults to the activator when omitted (anchor to a larger row while a smaller element stays the click target). |
| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the popover within a bounding element or CSS selector. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the activator and the columns. |
| `disableFlip` | `boolean \| undefined` | `false` |  | Disable the automatic flip to the opposite side on overflow. |
| `eager` | `boolean \| undefined` | `false` |  | Render popover content before it is first shown. |
| `label` | `string \| undefined` |  |  | Accessible label applied to the activator via `aria-label`. |
| `max` | `string \| undefined` |  |  | Maximum selectable time in `HH:mm` format. Values outside the pattern throw during setup to surface configuration mistakes. |
| `min` | `string \| undefined` |  |  | Minimum selectable time in `HH:mm` format. Values outside the pattern throw during setup to surface configuration mistakes. |
| `modelValue` | `string \| string[] \| null` |  | yes | v-model value: `null` for empty, a 24-hour `HH:mm` (or `HH:mm:ss` with `seconds`) string, or a two-element `[start, end]` array when `range` is true. |
| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when adaptive on mobile. |
| `offset` | `number \| undefined` | `4` |  | Space the popover keeps from the activator. |
| `padding` | `number \| undefined` |  |  | Minimum empty space to keep from the edge of the page. |
| `placement` | `Placement \| undefined` |  |  | Position of the popover relative to the activator/anchor. |
| `range` | `boolean \| undefined` | `false` |  | Range selection: the value is a two-element `[start, end]` array. |
| `readonly` | `boolean \| undefined` | `false` |  | Prevents opening while keeping the activator visible. |
| `seconds` | `boolean \| undefined` | `false` |  | Adds the seconds column. |
| `step` | `number \| undefined` | `1` |  | Minute-column granularity and arrow stepping. |
| `transitionDuration` | `number \| undefined` | `250` |  | Popover/sheet transition duration in milliseconds. |

## Events

- `error` — `(event: "error", error: TimePickerInputError): void`
- `time-pick` — `(event: "time-pick", payload: { unit: TimeUnit; value: string; }): void`
- `update:activeSegment` — `(event: "update:activeSegment", value: BbTimePickerSegment): void`
- `update:modelValue` — `(event: "update:modelValue", value: string \| string[] \| null): void`

## Slots

- `activator` — scope: `BbTimePickerActivatorSlotProps` — Custom activator element. Apply `v-bind="props"` to your trigger.

## See Also

- [BbTimePickerInput](./BbTimePickerInput.md) — Segmented time field with hour/minute columns; 24-hour string model.
- [BbDatePicker](./BbDatePicker.md) — Opens an anchored calendar (and optional time rail) popover on a trigger you own — the date analog of BbColorPalette; also the v-bb-date directive.
- [BbColorPalette](./BbColorPalette.md) — Opens an anchored popover color palette for color picking interactions.

---

<!-- dist/ai/BbTimePickerInput.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTimePickerInput.md -->

# BbTimePickerInput

## Agent Contract

- Safety level: **Consumer API**
- Group: **Inputs**
- Description: Segmented time field with hour/minute columns; 24-hour string model.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbTimePickerInput.md](./source/BbTimePickerInput.md)

## Usage & Guidelines

### When to use

Use `BbTimePickerInput` when the user picks a **time with no date attached** —
opening hours, shift boundaries, a daily reminder, a recurring slot. It renders
segmented hour/minute fields (auto-advance, paste distribution, ↑/↓ stepping
that wraps at each segment's bounds — `59` → `00`) plus a popover
with scrollable hour/minute columns, and shares the input-family chrome
(`label`, `description`, `hint`, `errors`, affixes, `clearable`, `loading`).

If the time belongs to a specific calendar day, use
[`BbDatePickerInput`](./BbDatePickerInput.md) with `datetime` instead —
its `v-model:time` uses the exact same string contract as this component's
`v-model`, so the two compose naturally.

`v-model` holds `null` or a 24-hour **`HH:mm`** string (`HH:mm:ss` with
`seconds`); set `range` and bind a `[start, end]` array for a window. `label`
is required.

**A plain time**

```vue
<BbTimePickerInput
	v-model="state.opensAt"
	label="Opens at"
	prepend:icon="lucide:clock"
/>
```

### Value contract

- Always **24-hour strings**, zero-padded: `'09:05'`, `'14:30'`, `'14:30:45'`
  with `seconds`. The `ampm` display never changes the model.
- `null` (or `[]` in range mode) is the empty state.
- A blank seconds segment commits as `:00`; without `seconds`, an incoming
  value carrying seconds displays truncated and zeroes out on the next commit.

### Display options

- **`ampm`** — 12-hour display with an AM/PM segment. Type `A`/`P` or cycle
  with ArrowUp/Down; the columns label hours `12 AM … 11 PM`.
- **`seconds`** — adds the `:ss` segment and a seconds column.
- **`step`** (minutes, default `1`) — shapes the minute column (`:step="15"` →
  00/15/30/45) and constrains what the columns produce, never what typing
  accepts: `10:07` typed under `step: 15` is emitted verbatim and no row
  highlights for it. ↑/↓ on a segment follow the typing rule — they always
  step by one, not by `step`.

**12-hour display, quarter-hour slots**

```vue
<BbTimePickerInput v-model="state.slotAt" ampm :step="15" label="Pickup slot" />
```

### Bounds & ranges

`min` / `max` (`HH:mm`) clamp typed times when interaction ends — the value
snaps to the nearest bound and an `error` event with code `disabled_time`
fires (`{ original, normalized }`). In `range` mode the model is `[start,
end]`; typing an inverted pair swaps it on blur with the usual
`end_before_start` error.

**Business-hours bound**

```vue
<BbTimePickerInput
	v-model="state.callAt"
	min="09:00"
	max="18:00"
	label="Callback time"
	hint="We call between 09:00 and 18:00."
	persistentHint
/>
```

### Platform behaviour

The popover follows the family's adaptive pattern: on mobile (with the global
`config.adaptive`, or the `adaptive` prop) the columns open in a bottom sheet
(`offCanvasProps` forwards extras). `disableWriting` (`true` / `'mobile'` /
`'desktop'`) turns off typing per platform — the columns then carry the
interaction.

### Events & v-model

| Event               | Payload                      | When                                    |
| ------------------- | ---------------------------- | --------------------------------------- |
| `update:modelValue` | `string \| string[] \| null` | every committed change                  |
| `error`             | `TimePickerInputError`       | clamped time, swapped range             |
| `active`/`inactive` | —                            | focus enters / leaves the whole control |
| `focus`             | `FocusEvent`                 | a native field gains focus              |

### Gotchas & anti-patterns

- **Don't parse the value with `new Date('14:30')`** — it's a wall-clock
  string, not an instant. Prepend a date first (`dayjs(`2026-01-01T${t}`)`)
  when you need date maths.
- **`range` needs an array model** — seed and clear with `[]`, never `null`.
- **The model is never 12-hour.** Render `h:mm A` yourself for display copy;
  the field already does it with `ampm`.

### Accessibility

Each segment is a labelled input (`Hour`, `Minute`, `Second`, `AM/PM` — via
the shared locale keys); the clock button announces the current selection and
controls a dialog; the columns are labelled groups whose options expose
`aria-pressed`. The format hint is linked via `aria-describedby`, merged with
the ids the container contributes — `errors`, `warnings`, `description` and
`hint`, in that order, each referenced only while it actually has copy — so the
reason the field is invalid is spoken first when a segment regains focus.
Messages _also_ render in an `aria-live="polite"` region.

## v-model

- `v-model` — type: `string \| string[] \| null`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile the time columns open inside a bottom off-canvas sheet instead of a floating popover. When unset, falls back to the global `config.adaptive`. |
| `ampm` | `boolean \| undefined` | `false` |  | 12-hour display with an AM/PM segment. Purely a field-composition concern: the model stays 24-hour. Type `A`/`P` (or ArrowUp/Down) to set the meridiem. |
| `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
| `autocomplete` | `string \| undefined` |  |  | Guides the browser as to the type of information expected in the field. |
| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
| `clearable` | `boolean \| undefined` | `false` |  | Displays a clear button when the input has a value and is being interacted with. |
| `compact` | `boolean \| undefined` | `false` |  | Sets the component in a compact state. |
| `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Always visible and linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
| `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
| `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` | `false` |  | Disables typing into the input. Use `'mobile'` / `'desktop'` to disable typing on one platform only. |
| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the segment inputs' `aria-descr… |
| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
| `id` | `string \| undefined` |  |  | The identifier of the component. |
| `label` | `string` |  | yes | Text content of the label of the element. |
| `labelMode` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Label rendering mode. |
| `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
| `loading` | `boolean \| undefined` | `false` |  | Sets the component in a loading state, usually triggering some visual styles. |
| `max` | `string \| undefined` |  |  | Maximum selectable time in `HH:mm` format. Values outside the pattern throw during setup to surface configuration mistakes. |
| `min` | `string \| undefined` |  |  | Minimum selectable time in `HH:mm` format. Values outside the pattern throw during setup to surface configuration mistakes. |
| `modelValue` | `string \| string[] \| null` |  | yes | v-model value: `null` for empty, a 24-hour `HH:mm` (or `HH:mm:ss` with `seconds`) string, or a two-element array when `range` is true. |
| `name` | `string \| undefined` |  |  | Defines the name of the input. |
| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile (e.g. `title`, `size`, `persistent`). |
| `persistentHint` | `boolean \| undefined` | `false` |  | Keeps the hint displayed. |
| `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
| `range` | `boolean \| undefined` | `false` |  | Range selection: v-model expects a two-element array `[start, end]`. An inverted pair swaps on finalize with an `end_before_start` error. |
| `readonly` | `boolean \| undefined` | `false` |  | Sets the input in a readonly state. |
| `required` | `boolean \| undefined` | `false` |  | Sets the input as required. |
| `reverse` | `boolean \| undefined` | `false` |  | Reverses the layout: the order of the label and the input is swapped. |
| `seconds` | `boolean \| undefined` | `false` |  | Adds the seconds segment. Without it an incoming value carrying seconds displays truncated and zeroes out on the next user commit. |
| `step` | `number \| undefined` | `1` |  | Minute granularity for the minute column and its arrow stepping. Constrains what the columns produce, never what typing accepts. |
| `transitionDuration` | `number \| undefined` |  |  | Transition duration, in milliseconds, for the popover appearance. |
| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-text-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. While displayed they are… |

## Events

- `active` — `(event: "active"): void`
- `error` — `(event: "error", error: TimePickerInputError): void`
- `focus` — `(event: "focus", event: FocusEvent): void`
- `inactive` — `(event: "inactive"): void`
- `update:modelValue` — `(event: "update:modelValue", value: string \| string[] \| null): void`

## Slots

- `append` — scope: `object` — Content rendered after the time fields (before the clock button).
- `append-outer` — scope: `object` — Content rendered after the entire control, outside the input chrome.
- `label` — scope: `BbTimePickerInputLabelSlotProps` — Replaces the default label text rendered above the input.
- `prefix` — scope: `object` — Inline content at the start of the field area.
- `prepend` — scope: `object` — Content rendered before the time fields, at the start of the inner container.
- `prepend-outer` — scope: `object` — Content rendered before the entire control, outside the input chrome.
- `suffix` — scope: `object` — Inline content at the end of the field area.

## Validated variant

Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).

| Prop | Type | Description |
| --- | --- | --- |
| `rules` | `RuleExpression<string \| string[] \| null>` | vee-validate rules for this field. |
| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |

## See Also

- [BbTimePicker](./BbTimePicker.md) — Opens hour/minute(/second) columns in a popover on a trigger you own — the time analog of BbDatePicker; also the v-bb-time directive.
- [BbDatePickerInput](./BbDatePickerInput.md) — Combines date selection with text input behavior.
- [BbTextInput](./BbTextInput.md) — Captures single-line text values.

---

<!-- dist/ai/BbToast.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbToast.md -->

# BbToast

## Agent Contract

- Safety level: **Consumer API**
- Group: **Feedback**
- Description: Shows transient notification messages (includes the co-located BbToastPortal export).
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbToast.md](./source/BbToast.md)

## Usage & Guidelines

### When to use

A toast is _transient, floating, and self-dismissing_ feedback: "Changes
saved", "Upload complete", "Copied to clipboard". It appears in a screen
corner, stacks with its siblings, and disappears on its own.

Reach for `BbAlert` instead when the message belongs to the page and must stay
put (a form error summary, a persistent banner). The rule of thumb: **`BbToast`
for what just happened, `BbAlert` for the current state of the page.**

Toasts are fired imperatively with the `useToast` composable — you don't place
a `<BbToast>` per message. You mount the host once, then call `toast(...)` from
anywhere. `toast`, `update`, and `dismiss` all operate on one shared
module-level stack, so every `useToast()` call in the app talks to the same
host. The full option table lives in the `useToast` composable doc; this guide
focuses on behaviour and patterns.

### Setup: mount exactly one host, at the app root

`useToast().toast(...)` enqueues into a shared reactive stack, but nothing
renders until a `<BbToast />` host is mounted. Put it **once, at the app root**;
it renders nothing where you place it — regions are teleported to the top layer
(see below).

```vue
<template>
	<RouterView />
	<BbToast />
</template>

<script setup lang="ts">
import { BbToast } from 'bitboss-ui';
</script>
```

On Nuxt the host goes in `app.vue`; on Inertia, in the `createInertiaApp`
render root — one mount above the router, so every page shares it and no page
mounts its own. **Every example on this page mounts its own `<BbToast />` only
because a standalone example has no app root to mount it in; in a real app the
host is already there and the page must not add a second one** (two hosts render
every message twice, and `BbToast` warns about it in DEV).

Toasts are a client-side surface: fire them from event handlers and
resolved requests, never during SSR/setup — on the server there is nothing to
render them into.

The host takes a single prop, `position`, the default corner for toasts that
don't specify their own (see Positioning).

### Firing a toast

Call `toast(...)` from an event handler. The string shorthand shows a plain
title; the object form gives you `title`, `text`, a `variant`, an `icon`, and
per-message options. Built-in variants: `default`, `success`, `info`,
`warning`, `destructive`.

**Saved confirmation and variant tones**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Alex Rivera</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				alex@northwind.co · Product
			</p>
		</div>

		<div class="flex flex-wrap items-center gap-2">
			<BbButton
				prepend:icon="lucide:check"
				variant="primary"
				@click="saveProfile"
			>
				Save profile
			</BbButton>
			<BbButton
				prepend:icon="lucide:info"
				variant="outline"
				@click="notify('info')"
			>
				Info
			</BbButton>
			<BbButton
				prepend:icon="lucide:triangle-alert"
				variant="outline"
				@click="notify('warning')"
			>
				Warning
			</BbButton>
			<BbButton
				prepend:icon="lucide:circle-x"
				variant="outline"
				@click="notify('destructive')"
			>
				Error
			</BbButton>
		</div>

		<!--
			Standalone example: it mounts its own host because it has no app root.
			A real app mounts exactly one <BbToast /> at the app root, and pages
			mount none. See ai/guides/agent-contract.md § Global Host Rule.
		-->
		<BbToast position="bottom-right" />
	</div>
</template>

<script setup lang="ts">
import { BbButton, BbToast, useToast } from 'bitboss-ui';

const { toast } = useToast();

/** Saved confirmation — the everyday toast: tone + matching icon. */
const saveProfile = () =>
	toast({
		title: 'Profile updated',
		text: 'Name and role are live for your team.',
		variant: 'success',
		icon: 'lucide:circle-check',
		position: 'bottom-right',
	});

const copy = {
	info: {
		title: 'Update available',
		text: 'BitBoss 2.4 is ready to install.',
		icon: 'lucide:info' as const,
	},
	warning: {
		title: 'Storage almost full',
		text: 'You have used 92% of the Northwind quota.',
		icon: 'lucide:triangle-alert' as const,
	},
	destructive: {
		title: 'Payment failed',
		text: 'Card ending 4242 was declined. Try another method.',
		icon: 'lucide:circle-x' as const,
	},
} as const;

const notify = (variant: keyof typeof copy) => {
	const { title, text, icon } = copy[variant];
	toast({ title, text, variant, icon, position: 'bottom-right' });
};
</script>
```

Three things worth internalising:

- **Variants tint the icon and set announcement priority — nothing else.** A
  variant toast without an `icon` looks identical to a default one, so pass a
  matching icon (`lucide:circle-check` for success, `lucide:circle-x` for
  destructive…) whenever the tone matters visually. No icon is ever implied —
  dev builds warn when a built-in variant is used without one, since the tone
  is otherwise dropped with no trace.
- `toast(...)` returns the message `id`. Keep it to `update(...)` or
  `dismiss(...)` that toast later; `dismiss()` with no argument clears the
  whole stack.
- `duration` defaults to 4000 ms and must be `> 0` — `toast()` throws
  otherwise. Use `persistent: true` for "never auto-dismiss", not `duration: 0`.
- A toast with no `title`, no `text`, and no `portal` renders an empty card
  (dev builds warn).

#### Project variants

The plugin's `toastVariants` option appends names to the typed union, and any
plain string is accepted at the call site for one-offs. A custom variant only
buys you the `bb-toast-message--<variant>` class hook — style it yourself
(the built-ins just set `--icon-color`). Custom variants announce politely;
only `warning`/`destructive` are assertive.

### Loading, then resolve

Pass `loading: true` to show a spinner and pin the toast open — **`loading`
implies `persistent`**, so it ignores the auto-dismiss timer and swipe. When
the work settles, `update(id, ...)` morphs it in place into a success or error;
the update restarts the auto-dismiss countdown (remember `loading: false`, or
the spinner and the pinning stay).

**Background job: loading to done**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">invoice-INV-1042.pdf</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				248 KB · ready to upload
			</p>
		</div>

		<BbButton prepend:icon="lucide:upload" variant="primary" @click="upload">
			Upload invoice
		</BbButton>

		<!--
			Standalone example: it mounts its own host because it has no app root.
			A real app mounts exactly one <BbToast /> at the app root, and pages
			mount none. See ai/guides/agent-contract.md § Global Host Rule.
		-->
		<BbToast position="bottom-right" />
	</div>
</template>

<script setup lang="ts">
import { BbButton, BbToast, useToast } from 'bitboss-ui';

const { toast, update } = useToast();

/** Background job: loading pins the toast, then update morphs it in place. */
const upload = () => {
	const id = toast({
		title: 'Uploading invoice-INV-1042.pdf…',
		loading: true,
		position: 'bottom-right',
	});

	setTimeout(() => {
		update(id, {
			title: 'Upload complete',
			text: 'invoice-INV-1042.pdf is in the workspace.',
			variant: 'success',
			icon: 'lucide:circle-check',
			loading: false,
		});
	}, 900);
};
</script>
```

`update` on an id that has already left the stack is a safe no-op. For a
message that must never auto-dismiss, pass `persistent: true`; add
`hideClose: true` only when your code will `dismiss(id)` itself — otherwise the
user has no way out.

### Upsert by id: one toast per concern

Passing your own `id` makes `toast(...)` an upsert: if that toast is still
live it is patched in place (and its countdown restarts) instead of stacking a
duplicate. Use a stable id for repeatable events — autosave ticks, connection
status, "copied" — so hammering the action never floods the corner.

**Autosave that never stacks duplicates**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Proposal — Acme Studio</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Draft · last edited just now · {{ saveCount }} saves this session
			</p>
		</div>

		<BbButton prepend:icon="lucide:save" variant="outline" @click="save">
			Save draft
		</BbButton>

		<!--
			Standalone example: it mounts its own host because it has no app root.
			A real app mounts exactly one <BbToast /> at the app root, and pages
			mount none. See ai/guides/agent-contract.md § Global Host Rule.
		-->
		<BbToast position="bottom-right" />
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbToast, useToast } from 'bitboss-ui';

const { toast } = useToast();
const saveCount = ref(0);

// A stable id makes toast() an upsert: repeated saves patch the same
// message (and restart its countdown) instead of stacking duplicates.
const save = () => {
	saveCount.value++;
	toast({
		id: 'draft-autosave',
		title: 'Draft saved',
		text: `Revision #${saveCount.value} stored just now.`,
		variant: 'success',
		icon: 'lucide:cloud-upload',
		position: 'bottom-right',
	});
};
</script>
```

Fields you omit in an upsert keep their previous value; fields you pass
(including `undefined`-able ones like `text` or `icon`) are overwritten. This
is the same mechanism `update(id, ...)` uses — the difference is that `update`
never creates, while `toast({ id })` creates or patches.

### Stacking, timers and dismissal

Behaviour you get for free — don't rebuild any of it:

- Toasts sharing a corner stack as a pile, newest in front; only the front
  three are visible, older ones fade behind.
- Hovering or focusing the stack fans it out and **pauses every auto-dismiss
  timer**; timers also pause while the browser tab is hidden, and resume with
  the time remaining.
- Users dismiss with the ✕ (revealed on hover/focus, unless `hideClose`) or by
  swiping the toast toward its nearest screen edge. Persistent toasts ignore
  swipe so they can't be lost by accident.
- Dismissal plays a ~300 ms exit slide; the pile closes up immediately.
- Under 600 px viewports the stack goes full-width with tighter margins.

### Positioning

A toast renders in one of six corners: `top-left`, `top-center`, `top-right`,
`bottom-left`, `bottom-center`, `bottom-right`. Resolution order per message:

1. `toast({ position })` — per-message override;
2. the host's `position` prop;
3. the plugin's `toastPosition` config (library default `bottom-right`).

```ts
// A single toast, bottom-centre, regardless of the global default:
toast({ title: 'Link copied', position: 'bottom-center' });
```

Pick one corner per product and stick to it; per-message positions are for rare
cases (e.g. a copy control at the top of the screen). Messages with different
positions form independent stacks.

### Action buttons

Pass an `actions` array to render buttons in a row below the text. While a
button's `onClick` runs it shows a spinner, its siblings are disabled, and the
auto-dismiss countdown is held; the toast dismisses itself when the callback
resolves. A rejected callback keeps the toast open and the countdown resumes.
Defaults per button: `variant: 'primary'`, `size: 'sm'`.

The classic application is the **undo pattern** (Gmail's "Conversation deleted
— Undo"): commit the delete immediately, no confirm dialog, and let the toast
carry the escape hatch. The action's closure keeps the removed record; if the
toast expires, the delete simply stands.

**Delete with undo**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Saved replies</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Delete commits immediately — Undo lives on the toast.
			</p>
		</div>

		<ul v-if="replies.length" class="flex flex-col gap-1.5">
			<li
				v-for="reply in replies"
				:key="reply.id"
				class="flex items-center justify-between gap-2"
			>
				<span class="truncate text-sm">{{ reply.title }}</span>
				<BbButton
					icon="lucide:trash-2"
					size="xs"
					variant="ghost"
					@click="removeReply(reply)"
				>
					Delete {{ reply.title }}
				</BbButton>
			</li>
		</ul>
		<p v-else class="text-sm text-[color:var(--bb-text-muted)]">
			No saved replies left.
		</p>

		<!--
			Standalone example: it mounts its own host because it has no app root.
			A real app mounts exactly one <BbToast /> at the app root, and pages
			mount none. See ai/guides/agent-contract.md § Global Host Rule.
		-->
		<BbToast position="bottom-right" />
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbToast, useToast } from 'bitboss-ui';

type Reply = { id: string; title: string };

const { toast } = useToast();

const replies = ref<Reply[]>([
	{ id: 'thanks', title: 'Thanks, we are on it' },
	{ id: 'refund', title: 'Refund processed' },
	{ id: 'escalate', title: 'Escalated to engineering' },
]);

// The delete commits immediately — no confirm dialog. The Undo action's
// closure keeps the removed row; the toast dismisses itself when the
// callback resolves. If the toast expires, the delete simply stands.
const removeReply = (reply: Reply) => {
	const index = replies.value.indexOf(reply);
	replies.value = replies.value.filter((entry) => entry.id !== reply.id);
	toast({
		title: `“${reply.title}” deleted`,
		duration: 5000,
		position: 'bottom-right',
		actions: [
			{
				text: 'Undo',
				size: 'xs',
				onClick: () => {
					replies.value.splice(Math.min(index, replies.value.length), 0, reply);
				},
			},
		],
	});
};
</script>
```

Failure and re-purposing compose into the retry pattern: a **rejected**
handler keeps the toast open for another attempt, and a handler that calls
`update(id, ...)` **takes ownership** — instead of dismissing, the toast
morphs in place with a fresh countdown (e.g. into a success confirmation).

**Retry that fails once, then morphs into success**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Workspace sync</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Northwind · last synced 12 minutes ago
			</p>
		</div>

		<BbButton
			prepend:icon="lucide:refresh-cw"
			size="xs"
			variant="outline"
			@click="sync"
		>
			Sync now (fails once)
		</BbButton>

		<!--
			Standalone example: it mounts its own host because it has no app root.
			A real app mounts exactly one <BbToast /> at the app root, and pages
			mount none. See ai/guides/agent-contract.md § Global Host Rule.
		-->
		<BbToast position="bottom-right" />
	</div>
</template>

<script setup lang="ts">
import { BbButton, BbToast, useToast } from 'bitboss-ui';

const { toast, update } = useToast();

// Fails on the first attempt, succeeds on the second.
let attempts = 0;
const syncApi = () =>
	new Promise<void>((resolve, reject) => {
		attempts += 1;
		setTimeout(
			() => (attempts % 2 ? reject(new Error('offline')) : resolve()),
			900
		);
	});

// Three action behaviours in one toast:
// - while Retry runs it spins, Ignore is disabled, and the countdown is held;
// - a REJECTED handler keeps the toast open (countdown resumes) — first click;
// - a handler that calls update() takes ownership: the toast morphs in place
//   with a fresh countdown instead of dismissing — second click.
const sync = () => {
	attempts = 0;
	const id = toast({
		title: 'Sync failed',
		text: 'Could not reach Northwind. Retry fails once, then succeeds.',
		variant: 'destructive',
		icon: 'lucide:circle-x',
		duration: 10000,
		position: 'bottom-right',
		actions: [
			{
				text: 'Retry',
				variant: 'primary',
				onClick: async () => {
					await syncApi();
					update(id, {
						title: 'Workspace synced',
						text: undefined,
						variant: 'success',
						icon: 'lucide:circle-check',
						actions: [],
						duration: 3000,
					});
				},
			},
			{ text: 'Ignore' },
		],
	});
};
</script>
```

A toast that needs more than one or two actions, or must not be missed, is
usually a `BbDialog`/`BbConfirm`, not a toast.

### Custom content with BbToastPortal

When a toast needs richer content than icon + title + text + actions — an
avatar, a release card, a custom layout — register named content with
`<BbToastPortal>` and fire a toast that references it by `portal` name,
passing data through `portalProps`. Portal content replaces the whole body
(icon, title, text and `actions` are not rendered); the close button still
overlays unless `hideClose`.

**An interactive invite toast**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
	>
		<div class="flex flex-col gap-0.5">
			<p class="text-sm font-medium">Invite teammate</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Portal toast with avatar + custom actions.
			</p>
		</div>

		<BbButton prepend:icon="lucide:user-plus" variant="primary" @click="invite">
			Send invite
		</BbButton>

		<!--
			Standalone example: it mounts its own host because it has no app root.
			A real app mounts exactly one <BbToast /> at the app root, and pages
			mount none. See ai/guides/agent-contract.md § Global Host Rule.
		-->
		<BbToast position="bottom-right" />

		<BbToastPortal v-slot="{ props, close }" name="invite">
			<div class="flex items-center gap-3">
				<BbAvatar size="32">{{ props.initials }}</BbAvatar>
				<div class="min-w-0 flex-1">
					<p class="text-sm font-semibold">{{ props.name }} was invited</p>
					<p class="text-xs text-[color:var(--bb-text-muted)]">
						Northwind · Design
					</p>
					<div class="mt-2 flex gap-2">
						<BbButton size="xs" @click="close">Got it</BbButton>
						<BbButton size="xs" variant="outline" @click="close">Undo</BbButton>
					</div>
				</div>
			</div>
		</BbToastPortal>
	</div>
</template>

<script setup lang="ts">
import {
	BbAvatar,
	BbButton,
	BbToast,
	BbToastPortal,
	useToast,
} from 'bitboss-ui';

const { toast } = useToast();

const invite = () =>
	toast({
		portal: 'invite',
		portalProps: { name: 'Ada Lovelace', initials: 'AL' },
		duration: 8000,
		position: 'bottom-right',
	});
</script>
```

- `<BbToastPortal name="...">` renders nothing where it sits — mount it
  anywhere (the layout next to the host is idiomatic). Its default slot
  receives `{ toast, props, close }`: `props` is the firing call's
  `portalProps`, `close` dismisses that specific toast. One registered portal
  can back many live toasts with different `portalProps`.
- Alternatively pass a component directly: `toast({ portal: MyCard,
portalProps: {...} })`. It receives `portalProps` as props plus a `close`
  function prop.

Use portals sparingly — if all you need is buttons under the message, the
`actions` option above is the lighter tool.

### Top layer, modals and panels

The host teleports its stacks into the browser top layer via the Popover API,
so toasts paint above dialogs, off-canvas panels, and dropdowns. Two behaviours
follow, both automatic:

- **Open modal (`BbDialog`/`BbOffCanvas`):** the region moves _inside_ the
  top-most modal, because a modal makes everything outside itself inert — this
  keeps toasts clickable while the modal is open.
- **Open non-modal panels:** an off-canvas sheet claims its screen edge and
  the toast stack yields — a bottom sheet pushes bottom stacks up, a right
  panel pushes right stacks left — sliding in step with the panel.

There is nothing to configure; just don't fight it with manual `z-index` or by
mounting extra hosts inside overlays.

**Your own docked panels** — a page-shell details sidebar, a filter rail — are
page markup, so the stack cannot see them and will happily land on top. One
call fixes it: `useSafeArea({ side: 'right', size: 352 })` marks
that edge occupied and the stack yields to it exactly as it does to a sheet —
see the `useSafeArea` composable doc.

### Works well with

- `useToast` — the API surface; see its composable doc for the option table.
- `useConfirm` / `BbConfirm` — confirm the destructive action first, toast the
  outcome after.
- `BbDropzone` + `BbProgress` — capture the file in the page, run the upload
  behind a `loading` toast, resolve it with `update`.
- `BbAlert` — mirror anything the user must still act on into the page; the
  toast is gone in four seconds.

### Gotchas & anti-patterns

- **No host, no toasts**: `toast(...)` without a mounted `<BbToast />`
  enqueues silently — and the messages never expire, because the dismiss timer
  lives inside the host. Mount exactly one host, at the app root — never one per
  page or per component.
- Don't hand-roll notification markup or timers; between variants, upsert,
  portals, and persistence the component covers it.
- Don't put must-act information only in a toast — it self-dismisses.
- `hideClose` + `persistent` without a code path to `dismiss(id)` traps the
  message on screen forever.
- A `variant` without an `icon` is invisible tone: it only changes screen
  reader priority.
- Fire toasts from user/network events, not from component `setup()` during
  SSR.

### Accessibility

- Tone maps to live-region semantics per message: `warning` and `destructive`
  announce as `role="alert"` / `aria-live="assertive"`; every other variant
  (including custom ones) uses `role="status"` / `aria-live="polite"`. Don't
  overuse the loud variants.
- Each toast is `aria-atomic`, so an `update(...)` re-announces the whole
  message — the loading → success morph reads correctly.
- The close button carries a localised `aria-label` (plugin `locale`) and is
  keyboard reachable; timers pause while the stack has focus, so keyboard
  users aren't racing the countdown.
- Because toasts self-dismiss, never put information a user _must_ act on only
  in a toast — mirror critical state in the page (a `BbAlert` or inline copy).

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `position` | `BbToastPosition \| undefined` |  |  |  |

## Events

- None.

## Slots

- None.

## See Also

- [BbAlert](./BbAlert.md) — Shows contextual status messages.

---

<!-- dist/ai/BbToastPortal.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbToastPortal.md -->

# BbToastPortal

## Agent Contract

- Safety level: **Consumer API**
- Group: **Feedback**
- Description: Registers named slot content that toast() renders via `portal`.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbToastPortal.md](./source/BbToastPortal.md)

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `name` | `string` |  | yes |  |

## Events

- None.

## Slots

- `default` — scope: `BbToastPortalContext`

## See Also

- [BbToast](./BbToast.md) — Shows transient notification messages (includes the co-located BbToastPortal export).
- [useToast](./composables/useToast.md)

---

<!-- dist/ai/BbTooltip.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTooltip.md -->

# BbTooltip

## Agent Contract

- Safety level: **Consumer API**
- Group: **Overlay**
- Description: Displays contextual helper text on interaction.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbTooltip.md](./source/BbTooltip.md)

## Usage & Guidelines

### When to use

Reach for `BbTooltip` to attach a **short, non-interactive label** to an element
that appears on hover or keyboard focus: the meaning of an icon-only button, a
definition for a jargon term, a hint on a truncated value. It is label-only —
the content is read to assistive tech via `aria-describedby`, and the bubble
itself is never focusable.

Do **not** put interactive content in a tooltip (links, buttons, form fields):

- Interactive floating content that stays open on click → `BbPopover`.
- A menu of actions → `BbDropdown`.

A tooltip is a supplement, never the only source of information — critical text
must live in the page, not hide behind a hover.

### Text via `text` or the default slot

Give the label with the `text` prop or the default slot; wrap your trigger in
the `activator` slot and spread its `props`. This is the classic pairing:
an **icon-only button** (which already needs its own `aria-label`) plus a
tooltip that surfaces the same label visually on hover.

**Label an icon-only button**

```vue
<BbTooltip text="Download CSV">
	<template #activator="{ props }">
		<BbButton
			v-bind="props"
			aria-label="Download CSV"
			icon="lucide:download"
			size="sm"
			variant="outline"
		/>
	</template>
</BbTooltip>
```

The tooltip's label does not replace the button's `aria-label`: the label names
the control for assistive tech, the tooltip describes it. Keep both. (The
`activator` scope also exposes `open`, `placement`, and `disabled` if the trigger
needs to react.)

### Inline help on a term

Use the default slot for the label text and any element as the activator — a
dotted-underline term is a common inline-help pattern. `placement` positions the
bubble (`top` by default; the `top` / `right` / `bottom` / `left` families with
`-start` / `-end` variants), and it auto-flips near a viewport edge.

**Explain a term inline**

```vue
<p class="text-sm">
	Covered under your
	<BbTooltip placement="right">
		<template #activator="{ props }">
			<span v-bind="props" class="cursor-help underline decoration-dotted">SLA</span>
		</template>
		Service Level Agreement — a response within 4 business hours.
	</BbTooltip>.
</p>
```

### Variant

`variant` tints the bubble. Two variants ship styles out of the box:

- `'default'` — the inverted (primary) bubble.
- `'destructive'` — danger-tinted, for a warning-flavored hint.

Registering a name in the vite plugin's `tooltipVariants` array is **not
optional**: `variant` is typed `keyof TooltipVariantRegistry`, so out of the box
only `default` and `destructive` compile and `variant="info"` is a type error —
`info` and `success` being exactly the names people invent. Register the name
(recommended) and the class hook `bb-tooltip--<name>` is interpolated at
runtime for **your** CSS to style. For a genuine one-off, a cast forces it
through; the class is still emitted.

**Default and destructive**

```vue
<div class="flex gap-1.5">
	<BbTooltip text="Duplicate this record">
		<template #activator="{ props }">
			<BbButton v-bind="props" icon="lucide:copy" size="sm" variant="ghost">
				Duplicate
			</BbButton>
		</template>
	</BbTooltip>
	<BbTooltip text="This permanently deletes the record" variant="destructive">
		<template #activator="{ props }">
			<BbButton v-bind="props" icon="lucide:trash-2" size="sm" variant="ghost">
				Delete
			</BbButton>
		</template>
	</BbTooltip>
</div>
```

```ts
// vite.config.ts — register project variants for type-safe autocomplete
bitbossUi({ tooltipVariants: ['info', 'success'] });
```

### A toolbar of labelled icon buttons

The most common real use: a compact row of icon-only actions, each named by a
tooltip. This companion frames a shared-document chrome — title, muted meta, and
`size="xs"` ghost buttons grouped with thin dividers. A `:delay="400"` keeps the
bubbles from flickering while the pointer crosses the dense toolbar.

**Icon toolbar with tooltips**

```vue
<template>
	<div
		class="flex max-w-sm flex-col gap-2 rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
	>
		<div class="flex items-start justify-between gap-2">
			<div class="flex min-w-0 flex-col gap-0.5">
				<span class="truncate text-sm font-medium">Q3 board deck</span>
				<span class="text-xs text-[color:var(--bb-text-muted)]">
					Shared draft · Acme Studio · edited 2h ago
				</span>
			</div>
			<span class="shrink-0 text-xs text-[color:var(--bb-text-muted)]"
				>PDF</span
			>
		</div>

		<div
			aria-label="Document actions"
			class="inline-flex w-fit items-center gap-0.5 rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-0.5"
			role="toolbar"
		>
			<template v-for="action in actions" :key="action.label">
				<span
					v-if="action.startsGroup"
					aria-hidden="true"
					class="mx-0.5 h-4 w-px bg-[color:var(--bb-border)]"
				></span>
				<BbTooltip :delay="400" :text="action.label">
					<template #activator="{ props }">
						<BbButton
							v-bind="props"
							:aria-label="action.label"
							:icon="action.icon"
							size="xs"
							variant="ghost"
						/>
					</template>
				</BbTooltip>
			</template>
		</div>
	</div>
</template>
<script setup lang="ts">
import { BbButton, BbTooltip } from 'bitboss-ui';

type ToolbarAction = {
	label: string;
	icon: string;
	/** Renders a divider before this action. */
	startsGroup?: boolean;
};

const actions: ToolbarAction[] = [
	{ label: 'Undo', icon: 'lucide:undo-2' },
	{ label: 'Redo', icon: 'lucide:redo-2' },
	{ label: 'Copy link', icon: 'lucide:link', startsGroup: true },
	{ label: 'Download PDF', icon: 'lucide:download' },
	{ label: 'Delete', icon: 'lucide:trash-2', startsGroup: true },
];
</script>
```

### Keyboard-shortcut hints

The default slot takes markup, so a tooltip can pair the action name with its
keyboard shortcut — the Slack/Linear-style hint on app-chrome buttons. Style
the `<kbd>` with `border-current` so it inherits the bubble's text color and
works on any variant.

**Shortcut hints on app chrome**

```vue
<div class="flex gap-1">
	<BbTooltip>
		<template #activator="{ props }">
			<BbButton
				v-bind="props"
				aria-label="Search"
				icon="lucide:search"
				size="sm"
				variant="ghost"
			/>
		</template>
		<span class="flex items-center gap-1.5">
			Search
			<kbd class="rounded border border-current px-1 font-mono text-[10px] leading-4 opacity-75">⌘K</kbd>
		</span>
	</BbTooltip>
	<BbTooltip>
		<template #activator="{ props }">
			<BbButton
				v-bind="props"
				aria-label="Toggle sidebar"
				icon="lucide:panel-left"
				size="sm"
				variant="ghost"
			/>
		</template>
		<span class="flex items-center gap-1.5">
			Toggle sidebar
			<kbd class="rounded border border-current px-1 font-mono text-[10px] leading-4 opacity-75">⌘B</kbd>
		</span>
	</BbTooltip>
</div>
```

The slot content is still plain, non-interactive text as far as assistive tech
is concerned — the whole label (shortcut included) is flattened into the
`aria-describedby` description.

### Placement, timing, width and disabling

- `placement` — as above; the `top`/`right`/`bottom`/`left` families with
  `-start`/`-end` variants, auto-flipping near an edge.
- `delay` (ms, default `0`) holds the tooltip back until the pointer settles —
  useful on dense toolbars to avoid a flicker of bubbles while the cursor passes
  over. It delays only the **open**; the close is always a short debounce (so the
  pointer can travel from the trigger into the bubble without it vanishing).
- `width` caps the bubble (pixels, or a percentage of the activator) so long
  hints wrap instead of stretching across the screen.
- `disabled` suppresses the tooltip entirely — and dismisses it if already open,
  so you can bind it to skip a hint when the label is already visible elsewhere.
- Content is **lazy** (rendered on first open); `eager` renders it up front, and
  `transition-duration` (ms) times the fade.

**Delayed, width-capped hint**

```vue
<BbTooltip
	:delay="300"
	text="Regenerates the API key. Existing integrations keep working until you rotate them."
	:width="220"
>
	<template #activator="{ props }">
		<BbButton
			v-bind="props"
			prepend:icon="lucide:key-round"
			variant="outline"
		>
			Rotate key
		</BbButton>
	</template>
</BbTooltip>
```

### The `v-bb-tooltip` directive

**Default to the directive.** For the common case — a plain-text label on an
element — attach the `v-bb-tooltip` directive rather than importing `BbTooltip`
and adding an `activator` slot. It needs no import (registered globally by the
plugin) and renders no wrapper. Escalate to the **component** only when you
genuinely need a slot: a markup label (default slot) or the `activator` slot's
exposed scope. If it's just text, it's the directive.

It is registered automatically when the plugin's `injectDirectives` is on (the
default), or add it explicitly — optionally under a custom name:

```ts
import { BbTooltipDirectivePlugin } from 'bitboss-ui';

app.use(BbTooltipDirectivePlugin); // registers v-bb-tooltip
app.use(BbTooltipDirectivePlugin, 'tooltip'); // or under a custom name: v-tooltip
```

The value grammar has three forms, plus a directive argument for placement:

```vue
<!-- string (or number) shorthand: the value is the tooltip text -->
<span v-bb-tooltip="'North Atlantic Treaty Organization'">NATO</span>

<!-- the directive argument sets placement -->
<BbButton
	v-bb-tooltip:bottom="'Saved automatically'"
	aria-label="Saved"
	icon="lucide:settings"
/>

<!-- object form: a required `text` plus any BbTooltip prop
     (placement, delay, variant, width, disabled, …) -->
<span
	v-bb-tooltip="{
		text: 'Opens after 300ms, anchored right',
		placement: 'right',
		delay: 300,
		variant: 'destructive',
	}"
>
	Hover me
</span>

<!-- an empty value attaches nothing — safe to bind conditionally -->
<span v-bb-tooltip="isTruncated ? label : ''">{{ label }}</span>
```

These grammar fences are intentionally **static** (not runnable): the guide's
live-example compiler mounts a bare template and cannot register a directive.
In a real SFC the directive just works — either globally (plugin) or by
importing `vBbTooltip` in `<script setup>`, which Vue resolves to
`v-bb-tooltip` locally.

The classic directive use case is the **truncated cell**: a fixed-width list
column that clips long values, with the full value surfaced on hover. Binding
an empty string attaches nothing, so rows that don't need the hint skip it —
here a length heuristic stands in for a real truncation check (compare
`scrollWidth` to `clientWidth` in production code). The companion uses the
object form (`{ text, delay: 400 }`) so long attachment names open after a
brief settle, matching dense toolbars.

**Full value on a truncated cell**

```vue
<template>
	<div
		class="max-w-sm overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
	>
		<div
			class="flex items-baseline justify-between gap-2 border-b border-[color:var(--bb-border)] px-3 py-2"
		>
			<span class="text-sm font-medium">Attachments</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]"
				>INV-1042 · 3 files</span
			>
		</div>

		<div class="divide-y divide-[color:var(--bb-border)]">
			<div
				v-for="file in files"
				:key="file.name"
				class="flex items-center gap-2 px-3 py-1.5 text-sm"
			>
				<BbIcon
					class="shrink-0 text-[color:var(--bb-text-muted)]"
					:icon="file.icon"
					size="sm"
				/>
				<span
					v-bb-tooltip="
						file.name.length > 34 ? { text: file.name, delay: 400 } : ''
					"
					class="min-w-0 flex-1 truncate"
				>
					{{ file.name }}
				</span>
				<span class="shrink-0 text-xs text-[color:var(--bb-text-muted)]">{{
					file.size
				}}</span>
			</div>
		</div>
	</div>
</template>
<script setup lang="ts">
import { BbIcon, vBbTooltip } from 'bitboss-ui';

type SharedFile = {
	name: string;
	size: string;
	icon: string;
};

const files: SharedFile[] = [
	{
		name: 'Q3-2026 board deck — revenue and churn summary (final).key',
		size: '8.4 MB',
		icon: 'lucide:file-text',
	},
	{
		name: 'customer-churn-analysis-2026-06-consolidated-draft.xlsx',
		size: '1.2 MB',
		icon: 'lucide:file-spreadsheet',
	},
	{
		name: 'brand-guidelines.pdf',
		size: '640 KB',
		icon: 'lucide:file',
	},
];
</script>
```

### Works well with

- **BbButton** — the classic pairing: icon-only `size="xs"`/`sm` actions in
  toolbars, each named by a tooltip (and its own `aria-label`).
- **BbTable** — the `v-bb-tooltip` directive on truncated cells surfaces the
  full value without wrapping every cell in a component.
- **BbPopover** — the escalation path the moment the content becomes
  interactive or needs to stay open on click.
- **BbDropdown** — when the "hint" is actually a menu of actions.

### Gotchas & anti-patterns

- **No interactive content.** The bubble is never focusable, so a link, button
  or form field inside it is unreachable by keyboard. Switch to `BbPopover`
  when the hint contains one, when the content should stay open on click while
  the user reads or copies it, or when it is really a small panel (settings, a
  mini-form) rather than a one-line label.
- **A tooltip supplements, it never replaces.** Critical information must live
  in the page; hover-only text is invisible to touch users until focused.
- **Keep the activator's `aria-label`.** The tooltip describes the control, it
  does not name it — dropping the label because "the tooltip already says it"
  breaks assistive tech (see Accessibility).
- **Custom variant strings ship no CSS.** Anything beyond `'default'` and
  `'destructive'` is a bare `bb-tooltip--<name>` class hook — if you haven't
  written that CSS, the bubble silently renders with default paint.
- **`delay` only postpones the open.** The close is always a short debounce so
  the pointer can travel into the bubble; don't reach for `delay` to keep a
  tooltip on screen longer.

### Accessibility

- The label is associated with the activator through `aria-describedby`, so it is
  announced on focus — not just on mouse hover. Keyboard users get the hint too.
- The tooltip opens on keyboard focus (`:focus-visible`) and on hover, and closes
  on blur, mouse-leave, or `Escape`. A mouse click does not open it (hover
  already covers the pointer), so it never pops over the thing you just clicked.
- Because the bubble is not focusable and holds no interactive content, never
  place a link or button inside it — use `BbPopover` for that.
- The tooltip supplements an accessible name; it does not provide one. Icon-only
  triggers still need their own `aria-label`.

## v-model

- `v-model` — type: `boolean \| undefined`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `activator` | `ElementOrComponentRef \| undefined` |  |  | External activator element or component ref. When provided, the activator slot is not rendered and event listeners are attached programmatically to the referenced element. |
| `arrowPadding` | `number \| undefined` | `10` |  | Space the arrow will maintain to the edge of the tooltip bubble. Useful when the floating element has border radius so it won't appear broken |
| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the tooltip within a bounding element. When provided, the tooltip will not overflow this container's bounds (e.g. a sidebar). Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
| `delay` | `number \| undefined` | `0` |  | The delay in milliseconds before the tooltip is shown. |
| `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
| `hideArrow` | `boolean \| undefined` | `false` |  | Hides the tooltip arrow. A tooltip shows its arrow by default (it's the one popover-family surface where an arrow is meaningful — a speech bubble pointing at its anchor); set this to drop it. |
| `id` | `string \| undefined` |  |  | Seed for the tooltip's internal id. It is **prefixed** (`bb_<id>`) and set on the inner content element, not on the root — so `document.getElementById(theIdYouPassed)` finds nothing. Pass it to make the generated id stable (SSR snapshots, t… |
| `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to show / hide the tooltip. A tooltip with no `v-model` starts hidden and is driven by hover / focus. |
| `padding` | `number \| undefined` | `10` |  | Minimum empty space to keep from the edge of the page |
| `placement` | `Placement \| undefined` | `"top"` |  | Position of the overlay in respect to the related activator. |
| `text` | `string \| undefined` |  |  | Text content of the component. |
| `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds |
| `variant` | `keyof TooltipVariantRegistry \| undefined` | `"default"` |  | Visual variant. `'default'` is the inverted (primary) bubble, `'destructive'` is the danger-tinted bubble for warnings. Any other string is applied as a `bb-tooltip--<name>` class hook. |
| `width` | `string \| number \| undefined` |  |  | Width of the tooltip bubble in pixels, or as a percentage of the activator. |

## Events

- `update:modelValue` — `(event: "update:modelValue", value: boolean): void`

## Slots

- `activator` — scope: `BbTooltipActivatorSlotProps` — Replaces the default trigger element that opens the tooltip.
- `default` — scope: `object` — Content rendered inside the tooltip bubble.

## See Also

- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements.

---

<!-- dist/ai/BbTree.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/BbTree.md -->

# BbTree

## Agent Contract

- Safety level: **Consumer API**
- Group: **Navigation**
- Description: Renders hierarchical expandable tree structures.
- Usage rule: Prefer this component for consumer-facing implementations.
- Implementation source (only when the contract below is not enough): [source/BbTree.md](./source/BbTree.md)

## Usage & Guidelines

### When to use

Reach for `BbTree` when your data is genuinely hierarchical and of unbounded
depth: a file/folder browser, a docs sidebar, a category picker, an org chart.
Nodes expand and collapse to reveal their children.

- Flat rows that happen to have one level of detail? Use `BbTable` with its
  `#expand` slot — trees are for recursion, not master/detail.
- A short one-off menu? A dropdown or list is lighter than a tree.
- One collapsible section? `BbCollapsible` — a tree of one node is overkill.

`BbTree` renders no visual chrome of its own — no rows, chevrons, icons or
lines. You own every node's markup through slots; the component owns the
structure, expansion state and accessibility wiring.

### The node grammar: `BbTreeItem<Meta>`

Feed `items` a nested array of `BbTreeItem<Meta>`. The envelope is fixed so the
component can reason about the tree; `meta` carries your data and flows to
every slot **fully typed** when you declare the array as
`BbTreeItem<YourMeta>[]`.

```ts
type BbTreeItem<Meta> = {
	meta: Meta; // your data — arrives typed in every slot
	children?: BbTreeItem<Meta>[]; // presence makes the node a branch
	expanded?: boolean; // INITIAL state only; branches default to expanded
	expandable?: boolean | ((item, depth, parent) => boolean); // per-node override
};
```

Rules the component lives by:

- A node with `children` is a branch; one without is a leaf. **Leaves always
  report `expanded: true`** — they have nothing to hide. (This matters for
  lazy loading; see the placeholder-child pattern below.)
- Nothing is expandable by default. Pass `expandable` — a boolean, or a
  function `(item, depth, parent) => boolean` — to decide which nodes get a
  live toggle and `aria-expanded`. The everyday idiom is
  `:expandable="(n) => !!n.children?.length"`; a function can also lock levels
  (`depth > 2`) or gate on `item.meta`. A node's own `expandable` field
  overrides the tree-level prop for that node.
- Non-expandable branches still render their children (expanded, frozen);
  `expandable` controls the _toggle_, not the rendering.
- `expanded` on an item is the initial state only — live state belongs to
  `v-model:expandedItems` (next sections).

The per-node override earns its keep in mixed hierarchies. This team
directory gates toggles with the tree-level function, then pins the
Leadership branch with `expandable: false` on the node itself — its members
render expanded and frozen, no chevron, while departments and teams toggle
normally:

**Team directory with a pinned branch**

```vue
<template>
	<div
		class="w-full max-w-xs overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
	>
		<div
			class="flex items-center gap-1.5 border-b border-[color:var(--bb-border)] px-2.5 py-1.5"
		>
			<BbIcon
				class="text-[color:var(--bb-text-muted)]"
				icon="lucide:users"
				size="sm"
			/>
			<span class="text-xs font-medium">People</span>
			<span class="ml-auto text-xs text-[color:var(--bb-text-muted)]"
				>Acme Studio</span
			>
		</div>

		<BbTree
			class="p-1.5"
			:expandable="(node) => !!node.children?.length"
			item-value="id"
			:items="org"
			style="--indent: 0.875rem; --gap: 0.125rem"
		>
			<template #default="{ meta, item, expanded, expandable, expandProps }">
				<!-- Toggleable group: department or team, with a member count. -->
				<button
					v-if="expandable"
					:aria-label="`${expanded ? 'Collapse' : 'Expand'} ${meta.name}`"
					class="flex w-full items-center gap-1.5 rounded-[var(--bb-radius-sm)] px-1.5 py-0.5 text-left text-sm font-medium hover:bg-[color:var(--bb-surface-hover)]"
					type="button"
					v-bind="expandProps"
				>
					<BbIcon
						class="shrink-0 text-[color:var(--bb-text-muted)]"
						:icon="expanded ? 'lucide:chevron-down' : 'lucide:chevron-right'"
						size="sm"
					/>
					<span class="min-w-0 flex-1 truncate">{{ meta.name }}</span>
					<BbBadge size="sm" variant="secondary">{{
						memberCount(item)
					}}</BbBadge>
				</button>
				<!-- Frozen branch (`expandable: false` on the node): children render
				     expanded with no toggle, so it reads as a pinned section. -->
				<span
					v-else-if="item.children?.length"
					class="flex items-center gap-1.5 px-1.5 py-1 text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
				>
					{{ meta.name }}
				</span>
				<!-- Leaf: a person. -->
				<span v-else class="flex items-center gap-2 px-1.5 py-0.5 text-sm">
					<BbAvatar :alt="meta.name" size="32">
						{{ initials(meta.name) }}
					</BbAvatar>
					<span class="min-w-0 truncate font-medium">{{ meta.name }}</span>
					<span class="shrink-0 text-xs text-[color:var(--bb-text-muted)]">{{
						meta.role
					}}</span>
				</span>
			</template>
		</BbTree>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbTree, BbAvatar, BbBadge, BbIcon } from 'bitboss-ui';
import type { BbTreeItem } from 'bitboss-ui';

type OrgEntry = { id: string; name: string; role?: string };

const initials = (name: string) =>
	name
		.split(' ')
		.map((part) => part[0])
		.join('');

/** Count people under a branch (leaves only), not nested team nodes. */
const memberCount = (node: BbTreeItem<OrgEntry>): number => {
	if (!node.children?.length) return 0;
	return node.children.reduce(
		(sum, child) => sum + (child.children?.length ? memberCount(child) : 1),
		0
	);
};

const org = ref<Array<BbTreeItem<OrgEntry>>>([
	{
		// Node-level override: Leadership is pinned open, no toggle.
		meta: { id: 'leadership', name: 'Leadership' },
		expandable: false,
		children: [
			{ meta: { id: 'ada', name: 'Ada Kim', role: 'CEO' } },
			{ meta: { id: 'grace', name: 'Grace Okafor', role: 'CTO' } },
		],
	},
	{
		meta: { id: 'engineering', name: 'Engineering' },
		children: [
			{
				meta: { id: 'platform', name: 'Platform' },
				children: [
					{ meta: { id: 'maya', name: 'Maya Chen', role: 'Staff engineer' } },
					{ meta: { id: 'tom', name: 'Tom Iversen', role: 'SRE' } },
				],
			},
			{
				meta: { id: 'web', name: 'Web' },
				expanded: false,
				children: [
					{ meta: { id: 'priya', name: 'Priya Nair', role: 'Frontend' } },
					{ meta: { id: 'leo', name: 'Leo Marchetti', role: 'Frontend' } },
				],
			},
		],
	},
	{
		meta: { id: 'design', name: 'Design' },
		expanded: false,
		children: [
			{ meta: { id: 'sofia', name: 'Sofia Duarte', role: 'Product designer' } },
		],
	},
]);
</script>
```

### The default slot: you own every node

The `default` slot renders each node and receives:

- `meta` — the typed data; `item` — the full node including `children`;
  `parent` — the parent node (`undefined` at root); `index` — zero-based
  position among siblings; `depth` — `0` at root; `value` — the node's
  resolved identity (see `item-value`).
- `expanded` / `expandable` — current booleans for this node.
- `toggleExpanded()` — flips this node's expansion.
- `expandProps` — bind onto your toggle element (`v-bind="expandProps"`); it
  wires `aria-expanded`, `aria-controls` (pointing at the children container),
  a click handler (which also stops propagation), and an Enter/Space keydown
  fallback for non-`<button>` elements. Prefer a real `<button>` — it gets
  focus and key activation natively.

Everything in the payload is a one-way snapshot: mutate nothing, and change
expansion only through `toggleExpanded` / `expandProps` (or by writing
`v-model:expandedItems`). Gate the toggle with `expandable` so leaves render
as plain rows.

**A project file browser**

```vue
<template>
	<div
		class="w-full max-w-xs overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
	>
		<div
			class="flex items-center gap-1.5 border-b border-[color:var(--bb-border)] px-2.5 py-1.5"
		>
			<BbIcon
				class="text-[color:var(--bb-text-muted)]"
				icon="lucide:files"
				size="sm"
			/>
			<span class="text-xs font-medium">Explorer</span>
			<span class="ml-auto text-xs text-[color:var(--bb-text-muted)]"
				>acme-web</span
			>
		</div>

		<BbTree
			class="p-1.5"
			:expandable="(node) => !!node.children?.length"
			item-value="path"
			:items="items"
			style="--indent: 0.875rem; --gap: 0.125rem"
		>
			<template #default="{ meta, expanded, expandable, expandProps }">
				<button
					v-if="expandable"
					:aria-label="`${expanded ? 'Collapse' : 'Expand'} ${meta.name}`"
					class="flex w-full items-center gap-1.5 rounded-[var(--bb-radius-sm)] px-1.5 py-0.5 text-left text-sm hover:bg-[color:var(--bb-surface-hover)]"
					type="button"
					v-bind="expandProps"
				>
					<BbIcon
						class="shrink-0 text-[color:var(--bb-text-muted)]"
						:icon="expanded ? 'lucide:chevron-down' : 'lucide:chevron-right'"
						size="sm"
					/>
					<BbIcon
						class="shrink-0 text-[color:var(--bb-text-muted)]"
						:icon="expanded ? 'lucide:folder-open' : 'lucide:folder'"
						size="sm"
					/>
					<span class="truncate font-medium">{{ meta.name }}</span>
				</button>
				<span
					v-else
					class="flex items-center gap-1.5 rounded-[var(--bb-radius-sm)] px-1.5 py-0.5 pl-[1.55rem] text-sm text-[color:var(--bb-text-muted)]"
				>
					<BbIcon
						class="shrink-0 text-[color:var(--bb-text-faint)]"
						icon="lucide:file"
						size="sm"
					/>
					<span class="truncate text-[color:var(--bb-text)]">{{
						meta.name
					}}</span>
				</span>
			</template>
		</BbTree>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbTree, BbIcon } from 'bitboss-ui';
import type { BbTreeItem } from 'bitboss-ui';

type FileNode = { name: string; path: string };

const items = ref<Array<BbTreeItem<FileNode>>>([
	{
		meta: { name: 'src', path: 'src' },
		children: [
			{
				meta: { name: 'components', path: 'src/components' },
				children: [
					{
						meta: { name: 'BbButton.vue', path: 'src/components/BbButton.vue' },
					},
					{
						meta: { name: 'BbTable.vue', path: 'src/components/BbTable.vue' },
					},
				],
			},
			{ meta: { name: 'main.ts', path: 'src/main.ts' } },
		],
	},
	{
		meta: { name: 'public', path: 'public' },
		expanded: false,
		children: [{ meta: { name: 'favicon.ico', path: 'public/favicon.ico' } }],
	},
	{ meta: { name: 'package.json', path: 'package.json' } },
	{ meta: { name: 'vite.config.ts', path: 'vite.config.ts' } },
]);
</script>
```

### Node identity: `item-value`

Set `item-value` to a `meta` key (`item-value="path"`) or a function
`(meta) => value` so each node has a stable identity. The identity is what:

- fills `v-model:expandedItems` (readable entries like `'src/components'`
  instead of whole objects);
- is hashed to track expansion — without `item-value` the **whole `meta`
  object** is hashed, so re-fetching data and recreating objects with a new
  property order or extra fields silently resets expansion state;
- names per-node slots when it resolves to a string or number (next section);
- arrives in every slot as `value`.

Always set it when items come from a server.

### Controlling expansion state

Live expansion is a `v-model:expandedItems` — a list of node **values**, with
the exact verbs of `BbTable`. `update:expandedItems` fires with the full new
list every time a node toggles; you rarely listen to it directly — bind the
model and treat it as state.

Seeding: when a branch node is seen for the first time (initial render, or
appended later), it joins the model automatically **unless** it is marked
`expanded: false` or already tracked. After that first sighting the model is
the single source of truth — later flips of the `expanded` flag are ignored.
Write the model to drive expand-all / collapse-all, persist the open folders,
or restore them on reload.

**Docs sidebar with expand / collapse all**

```vue
<template>
	<div class="w-full max-w-xs">
		<div class="mb-2 flex gap-1.5">
			<BbButton size="sm" variant="outline" @click="expandAll">
				Expand all
			</BbButton>
			<BbButton size="sm" variant="ghost" @click="collapseAll">
				Collapse all
			</BbButton>
		</div>

		<BbTree
			v-model:expanded-items="expandedSections"
			class="rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-1.5"
			:expandable="(node) => !!node.children?.length"
			item-value="id"
			:items="sections"
			style="--indent: 0.75rem; --gap: 0.125rem"
		>
			<template #default="{ meta, expanded, expandable, expandProps }">
				<button
					v-if="expandable"
					:aria-label="`${expanded ? 'Collapse' : 'Expand'} ${meta.label}`"
					class="flex w-full items-center gap-1.5 rounded-[var(--bb-radius-sm)] px-1.5 py-0.5 text-left text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)] hover:bg-[color:var(--bb-surface-hover)]"
					type="button"
					v-bind="expandProps"
				>
					<BbIcon
						class="shrink-0"
						:icon="expanded ? 'lucide:chevron-down' : 'lucide:chevron-right'"
						size="sm"
					/>
					{{ meta.label }}
				</button>
				<!-- Leaf pages navigate through the item itself, never @click. -->
				<BbButton
					v-else
					active-class="docs-sidebar-active"
					class="w-full justify-start"
					:href="meta.href"
					size="sm"
					variant="ghost"
				>
					{{ meta.label }}
				</BbButton>
			</template>
		</BbTree>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbTree, BbButton, BbIcon } from 'bitboss-ui';
import type { BbTreeItem } from 'bitboss-ui';

type NavEntry = { id: string; label: string; href?: string };

const sections = ref<Array<BbTreeItem<NavEntry>>>([
	{
		meta: { id: 'start', label: 'Getting started' },
		children: [
			{ meta: { id: 'install', label: 'Installation', href: '#install' } },
			{ meta: { id: 'theming', label: 'Theming', href: '#theming' } },
		],
	},
	{
		meta: { id: 'components', label: 'Components' },
		expanded: false,
		children: [
			{ meta: { id: 'button', label: 'Button', href: '#button' } },
			{ meta: { id: 'tree', label: 'Tree', href: '#tree' } },
			{ meta: { id: 'dropzone', label: 'Dropzone', href: '#dropzone' } },
		],
	},
]);

/* The identity of every branch node, for expand-all. */
const branchIds = sections.value
	.filter((node) => node.children?.length)
	.map((node) => node.meta.id);

/* Start empty: BbTree seeds it from each branch's `expanded` flag — so
	 "Getting started" opens and "Components" (expanded: false) stays collapsed. */
const expandedSections = ref<string[]>([]);
const expandAll = () => (expandedSections.value = [...branchIds]);
const collapseAll = () => (expandedSections.value = []);
</script>

<style scoped>
/* Primary tint for the current page — follows theme / dark mode. */
.docs-sidebar-active {
	background: color-mix(in oklab, var(--bb-primary) 8%, var(--bb-panel));
	color: var(--bb-text);
	font-weight: 500;
}
</style>
```

Leaves never appear in the model — they are always "expanded". So expand-all
is just "the identities of every branch node", as the sidebar computes.

### Per-node and per-depth slots

Beyond `default`, `BbTree` resolves named slots per node, in priority order:

1. `#<value>` — the node whose resolved identity equals the slot name (only
   for string/number identities, e.g. `#trash` with `item-value="id"`);
2. `#<depth>` — every node at that depth (`#0` for root nodes);
3. `default` — everything else.

Each receives the same payload as `default`. There are also `#<value>-children`
and `#<depth>-children` slots that **replace the children container** of the
matching node — the recursion stops there and your content renders instead,
useful for a custom layout or an inline empty state under one branch.

**Sections, pages and a special trash node**

```vue
<template>
	<BbTree
		class="w-full max-w-xs rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-1.5"
		:expandable="(n) => !!n.children?.length"
		item-value="id"
		:items="pages"
		style="--indent: 0.875rem; --gap: 0.125rem"
	>
		<!-- Depth slot: every top-level node becomes a section header. -->
		<template #0="{ meta, expanded, expandProps }">
			<button
				:aria-label="`${expanded ? 'Collapse' : 'Expand'} ${meta.label}`"
				class="flex w-full items-center gap-1.5 rounded-[var(--bb-radius-sm)] px-1.5 py-0.5 text-left text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)] hover:bg-[color:var(--bb-surface-hover)]"
				type="button"
				v-bind="expandProps"
			>
				<BbIcon
					class="shrink-0"
					:icon="expanded ? 'lucide:chevron-down' : 'lucide:chevron-right'"
					size="sm"
				/>
				{{ meta.label }}
			</button>
		</template>

		<!-- Value slot: one specific node, wherever it sits. Beats the depth slot. -->
		<template #trash="{ meta, expanded, expandProps }">
			<button
				:aria-label="`${expanded ? 'Collapse' : 'Expand'} ${meta.label}`"
				class="knowledge-base-tree__trash flex w-full items-center gap-1.5 rounded-[var(--bb-radius-sm)] px-1.5 py-0.5 text-left text-sm"
				type="button"
				v-bind="expandProps"
			>
				<BbIcon icon="lucide:trash-2" size="sm" />
				<span class="font-medium">{{ meta.label }}</span>
			</button>
		</template>

		<!-- Children slot: replaces the recursion under one node with your own
		     layout — the deleted pages render dimmed, with a retention note. -->
		<template #trash-children="{ item }">
			<ul class="flex flex-col gap-0.5">
				<li
					v-for="page in item.children ?? []"
					:key="page.meta.id"
					class="flex items-center gap-1.5 px-1.5 py-0.5 pl-[1.55rem] text-sm text-[color:var(--bb-text-muted)] line-through"
				>
					<BbIcon icon="lucide:file-x" size="sm" /> {{ page.meta.label }}
				</li>
				<li
					class="px-1.5 pb-1 pl-[1.55rem] text-xs text-[color:var(--bb-text-muted)]"
				>
					Deleted pages are removed for good after 30 days.
				</li>
			</ul>
		</template>

		<!-- Default slot: every remaining node (the pages). -->
		<template #default="{ meta }">
			<span
				class="flex items-center gap-1.5 rounded-[var(--bb-radius-sm)] px-1.5 py-0.5 pl-[1.55rem] text-sm"
			>
				<BbIcon
					class="text-[color:var(--bb-text-faint)]"
					icon="lucide:file-text"
					size="sm"
				/>
				{{ meta.label }}
			</span>
		</template>
	</BbTree>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbTree, BbIcon } from 'bitboss-ui';
import type { BbTreeItem } from 'bitboss-ui';

type KbNode = { id: string; label: string };

const pages = ref<Array<BbTreeItem<KbNode>>>([
	{
		meta: { id: 'handbook', label: 'Handbook' },
		children: [
			{ meta: { id: 'onboarding', label: 'Onboarding' } },
			{ meta: { id: 'benefits', label: 'Benefits' } },
		],
	},
	{
		meta: { id: 'engineering', label: 'Engineering' },
		children: [
			{ meta: { id: 'code-style', label: 'Code style' } },
			{ meta: { id: 'releases', label: 'Release process' } },
		],
	},
	{
		meta: { id: 'trash', label: 'Trash' },
		expanded: false,
		children: [
			{ meta: { id: 'old-roadmap', label: 'Old roadmap' } },
			{ meta: { id: 'draft-copy', label: 'Draft copy' } },
		],
	},
]);
</script>

<style scoped>
.knowledge-base-tree__trash {
	color: var(--bb-danger);
}

.knowledge-base-tree__trash:hover {
	background: color-mix(in oklab, var(--bb-danger) 8%, var(--bb-panel));
}
</style>
```

Here `#0` styles every top-level node as a section header, `#trash` restyles
one specific node (value slots beat depth slots — trash sits at depth 0 too),
and `default` covers the rest. `#trash-children` then replaces the recursion
under that one branch: the deleted pages render as a dimmed custom list with
a retention note, straight from `item.children` — expansion still animates,
but no `BbTreeLevel` is rendered inside.

### Navigation belongs to the node

Because you render each node, wire navigation through the item itself — never
`@click` + `router.push`. Leaf pages are links: render a `BbButton` (or
`BbBaseButton`) with `href`, `to`, and `active-class` so the current page
highlights itself. The sidebar above does exactly this — its pages are
`BbButton variant="ghost" :href="…"`, its sections are expand toggles.

In a Nuxt or Inertia app, swap `href="#…"` for a real target:

```vue
<!-- Vue Router: leaf navigates via `to`, active page auto-highlights -->
<BbButton
	:to="{ name: 'docs', params: { slug: meta.slug } }"
	active-class="is-active"
	variant="ghost"
>
	{{ meta.label }}
</BbButton>
```

```vue
<!-- Inertia: `href` becomes a visit; `method`/`data` are forwarded -->
<BbButton
	:href="`/docs/${meta.slug}`"
	variant="ghost"
>{{ meta.label }}</BbButton>
```

`BbTree` itself is SSR-safe (no browser APIs, no teleports) and reads nothing
from the global plugin config — no locale strings, no `adaptive` behavior.

### Indentation, rhythm and connector lines

Two sealed CSS tokens on `.bb-tree` shape the layout: `--indent` shifts each
child level, `--gap` adds vertical space between siblings. Both default to `0`,
so set them to taste — inline, in a class, or per instance. Expansion animates
out of the box: collapsing is a smooth CSS grid-rows transition, not a remount.

**Tuning --indent and --gap**

```vue
<BbTree
	:items="[
		{
			meta: { name: 'Design' },
			children: [
				{ meta: { name: 'Logo.svg' } },
				{ meta: { name: 'Palette.png' } },
			],
		},
	]"
	:expandable="(n) => !!n.children?.length"
	class="max-w-xs rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-1.5"
	style="--indent:1.5rem; --gap:.375rem"
>
	<template #default="{ meta, expandable, expanded, expandProps }">
		<button
			v-if="expandable"
			v-bind="expandProps"
			type="button"
			class="flex w-full items-center gap-1.5 rounded-[var(--bb-radius-sm)] px-1.5 py-0.5 text-left text-sm font-medium hover:bg-[color:var(--bb-surface-hover)]"
		>
			<BbIcon
				class="text-[color:var(--bb-text-muted)]"
				:icon="expanded ? 'lucide:chevron-down' : 'lucide:chevron-right'"
				size="sm"
			/>
			{{ meta.name }}
		</button>
		<span v-else class="px-1.5 py-0.5 text-sm text-[color:var(--bb-text-muted)]">{{ meta.name }}</span>
	</template>
</BbTree>
```

Connector lines (the elbows joining a parent to its children) are **deliberately
not shipped** — they are a look, not a behavior, and every product wants them
slightly different. Draw them yourself in plain CSS, anchored to `--indent` /
`--gap`, targeting the internal `.bb-tree__node` / `.bb-tree__row` /
`.bb-tree__children` elements (nodes also carry `--depth-<n>`, `--expanded`
and `--leaf` modifier classes to hook onto). This is a documented case where
reaching into the component's internals for styling is expected; keep it
scoped under a wrapper class so it stays local.

**Connector lines drawn in CSS**

```vue
<template>
	<BbTree
		class="connector-tree w-full max-w-xs rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-1.5"
		:expandable="(node) => !!node.children?.length"
		item-value="path"
		:items="items"
	>
		<template #default="{ meta, expanded, expandable, expandProps }">
			<button
				v-if="expandable"
				:aria-label="`${expanded ? 'Collapse' : 'Expand'} ${meta.name}`"
				class="flex items-center gap-1.5 rounded-[var(--bb-radius-sm)] px-1.5 py-0.5 text-sm hover:bg-[color:var(--bb-surface-hover)]"
				type="button"
				v-bind="expandProps"
			>
				<BbIcon
					class="shrink-0 text-[color:var(--bb-text-muted)]"
					:icon="expanded ? 'lucide:folder-open' : 'lucide:folder'"
					size="sm"
				/>
				<span class="font-medium">{{ meta.name }}</span>
			</button>
			<span
				v-else
				class="flex items-center gap-1.5 px-1.5 py-0.5 text-sm text-[color:var(--bb-text-muted)]"
			>
				<BbIcon
					class="shrink-0 text-[color:var(--bb-text-faint)]"
					icon="lucide:file"
					size="sm"
				/>
				<span class="text-[color:var(--bb-text)]">{{ meta.name }}</span>
			</span>
		</template>
	</BbTree>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbTree, BbIcon } from 'bitboss-ui';
import type { BbTreeItem } from 'bitboss-ui';

type FileNode = { name: string; path: string };

const items = ref<Array<BbTreeItem<FileNode>>>([
	{
		meta: { name: 'app', path: 'app' },
		children: [
			{
				meta: { name: 'routes', path: 'app/routes' },
				children: [
					{ meta: { name: 'index.ts', path: 'app/routes/index.ts' } },
					{ meta: { name: 'users.ts', path: 'app/routes/users.ts' } },
				],
			},
			{ meta: { name: 'server.ts', path: 'app/server.ts' } },
		],
	},
]);
</script>

<!--
	The library ships NO connector lines by design — the node markup is entirely
	yours. When a file-browser look calls for them, draw them in plain CSS off the
	--indent / --gap tokens. This is a deliberate, documented style override that
	reaches into the component's internal BEM classes; keep it scoped under a
	wrapper class (.connector-tree) so it never leaks to other trees.
-->
<style>
.connector-tree {
	--indent: 1.25rem;
	--gap: 0.25rem;
	--line: var(--bb-border); /* token-driven: follows the theme */
}

.connector-tree .bb-tree__children > .bb-tree__node {
	position: relative;
}

/* Trunk: vertical line continuing past a node while siblings follow. */
.connector-tree .bb-tree__children > .bb-tree__node:not(:last-child)::before {
	border-left: 1px solid var(--line);
	bottom: 0;
	content: '';
	left: calc(var(--indent) / -2);
	position: absolute;
	top: calc(var(--gap) * -1);
}

/* Elbow: drops from the level above and turns into this node's row. */
.connector-tree .bb-tree__children > .bb-tree__node > .bb-tree__row {
	position: relative;
}

.connector-tree .bb-tree__children > .bb-tree__node > .bb-tree__row::before {
	border-bottom: 1px solid var(--line);
	border-bottom-left-radius: var(--bb-radius-sm);
	border-left: 1px solid var(--line);
	content: '';
	height: calc(50% + var(--gap));
	left: calc(var(--indent) / -2);
	position: absolute;
	top: calc(var(--gap) * -1);
	width: calc(var(--indent) / 2);
}
</style>
```

The same scoped-override mechanism applies to one other case: in a
width-constrained pane (a split-pane detail layout, a narrow sidebar), long
labels can overflow instead of truncating. `.bb-tree__content` is
`flex-grow: 1` with the flex default `min-width: auto`, so it grows to fit
its content rather than shrinking to the row's available width. Force the
row/content min-width to `0` under your own wrapper class, then truncate in
your node markup:

```css
.my-tree .bb-tree__row,
.my-tree .bb-tree__content {
	min-width: 0;
}
```

```vue
<span class="truncate">{{ meta.name }}</span>
```

### Large trees and lazy-loaded branches

The whole tree stays mounted: collapsed branches are hidden by CSS, not
removed, and there is no virtualization. For hundreds of nodes that is fine;
for folders of unbounded size, don't ship the entire hierarchy up front — load
children when a branch first opens. `items` is watched deeply, so appending
`children` to a node updates the tree in place, and newly appeared branches
follow the same seeding rules (`expanded: false` keeps them collapsed).

The pattern: give each unloaded folder a single **placeholder child** (a
loading row) so it is a real branch — remember, a childless node is a leaf
that always reports `expanded: true`, so a chevron driven by `expanded` would
render open before any load. Mark those folders `expanded: false`, or the
seeding rules open them at first sight and every fetch fires at mount. Then
watch `expandedItems`: when an unloaded folder's identity enters the model,
fetch and swap its children.

**Folders that load on first expand**

```vue
<template>
	<div
		class="w-full max-w-xs overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
	>
		<div
			class="flex items-center gap-1.5 border-b border-[color:var(--bb-border)] px-2.5 py-1.5"
		>
			<BbIcon
				class="text-[color:var(--bb-text-muted)]"
				icon="lucide:cloud"
				size="sm"
			/>
			<span class="text-xs font-medium">Remote files</span>
			<span class="ml-auto text-xs text-[color:var(--bb-text-muted)]"
				>lazy load</span
			>
		</div>

		<BbTree
			v-model:expanded-items="expanded"
			class="p-1.5"
			:expandable="(node) => !node.meta.leaf"
			item-value="id"
			:items="tree"
			style="--indent: 0.875rem; --gap: 0.125rem"
		>
			<template #default="{ meta, expanded: isOpen, expandable, expandProps }">
				<button
					v-if="expandable"
					:aria-label="`${isOpen ? 'Collapse' : 'Expand'} ${meta.label}`"
					class="flex w-full items-center gap-1.5 rounded-[var(--bb-radius-sm)] px-1.5 py-0.5 text-left text-sm hover:bg-[color:var(--bb-surface-hover)]"
					type="button"
					v-bind="expandProps"
				>
					<BbIcon
						class="shrink-0 text-[color:var(--bb-text-muted)]"
						:icon="isOpen ? 'lucide:chevron-down' : 'lucide:chevron-right'"
						size="sm"
					/>
					<BbIcon
						class="shrink-0 text-[color:var(--bb-text-muted)]"
						:icon="isOpen ? 'lucide:folder-open' : 'lucide:folder'"
						size="sm"
					/>
					<span class="truncate font-medium">{{ meta.label }}</span>
				</button>
				<span
					v-else-if="meta.loading"
					class="flex items-center gap-1.5 px-1.5 py-0.5 pl-[1.55rem] text-sm text-[color:var(--bb-text-muted)]"
				>
					<BbSpinner size="xs" /> Loading…
				</span>
				<span
					v-else
					class="flex items-center gap-1.5 px-1.5 py-0.5 pl-[1.55rem] text-sm"
				>
					<BbIcon
						class="text-[color:var(--bb-text-faint)]"
						icon="lucide:file"
						size="sm"
					/>
					{{ meta.label }}
				</span>
			</template>
		</BbTree>
	</div>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue';
import { BbTree, BbIcon, BbSpinner } from 'bitboss-ui';
import type { BbTreeItem } from 'bitboss-ui';

type Node = { id: string; label: string; leaf?: boolean; loading?: boolean };

// Each unloaded folder ships with a single placeholder child, so it is a real
// (expandable) branch with a visible loading row until its contents arrive.
const placeholder = (id: string): BbTreeItem<Node> => ({
	meta: { id: `${id}:loading`, label: 'Loading', leaf: true, loading: true },
});

// `expanded: false` matters: branches otherwise seed the model as expanded
// on first sight, which would kick off every fetch at mount.
const tree = ref<Array<BbTreeItem<Node>>>([
	{
		meta: { id: 'src', label: 'src' },
		expanded: false,
		children: [placeholder('src')],
	},
	{
		meta: { id: 'assets', label: 'assets' },
		expanded: false,
		children: [placeholder('assets')],
	},
]);

const expanded = ref<string[]>([]);
const loaded = new Set<string>();

// Fake fetch — swap in a directory listing keyed by the folder id.
const fetchChildren = (id: string): Promise<Array<BbTreeItem<Node>>> =>
	new Promise((resolve) =>
		setTimeout(
			() =>
				resolve([
					{ meta: { id: `${id}/index.ts`, label: 'index.ts', leaf: true } },
					{ meta: { id: `${id}/utils.ts`, label: 'utils.ts', leaf: true } },
				]),
			400
		)
	);

// When an unloaded folder's identity first enters the model, load and swap.
watch(expanded, async (ids) => {
	for (const id of ids) {
		if (loaded.has(id)) continue;
		const branch = tree.value.find((node) => node.meta.id === id);
		if (!branch) continue;
		loaded.add(id);
		branch.children = await fetchChildren(id);
	}
});
</script>
```

### Works well with

- `BbButton` — leaf navigation with `href`/`to` + `active-class`; also the
  natural expand toggle if you want library styling on it.
- `BbIcon` — chevrons, folder/file glyphs keyed off `expanded` and `meta`.
- `BbBadge` — counts on branch rows (unread per folder, items per category).
- `BbTable` — the sibling to reach for when data is flat with one detail
  level (`#expand` slot) instead of recursive.
- `BbCollapsible` — a single expandable section without tree semantics.

### Gotchas and anti-patterns

- `expanded` on an item seeds the initial state only; the component ignores
  later flips. To open a node programmatically, push its value into
  `expandedItems` — don't mutate the flag.
- Without `item-value`, identity is a hash of the whole `meta` object —
  re-created objects (e.g. after a refetch) can orphan the expansion state.
  Set `item-value` whenever items aren't literal constants.
- Collapsed branches remain in the DOM (collapse is a CSS-grid animation), but
  the container is **`inert`**, so everything inside — leaf links, buttons —
  leaves the tab order and the accessibility tree on its own. Do **not**
  hand-roll `:tabindex="parentExpanded ? undefined : -1"`; that advice predates
  the shipped behaviour (D#25) and now only fights it. See § Accessibility.
- No `expandable` prop means no toggles anywhere: the tree renders fully
  expanded and static. If your chevrons don't respond, this is why.
- Don't track expansion in your own `ref` next to the model, and don't decide
  "expandedness" from your own state — `expanded` in the slot payload is
  already live.
- Don't navigate with `@click` + `router.push` in node markup — leaves take
  `href`/`to` through `BbButton`.
- Don't reach into `.bb-tree__*` internals for styling _except_ for the
  sanctioned connector-line/indent hooks and the constrained-width
  `min-width: 0` truncation override above.

### Accessibility

**`BbTree` is a nested disclosure list, not a WAI-ARIA tree — deliberately.**
It renders no `role="tree"`, no `role="treeitem"`, and no
`aria-level`/`aria-posinset`/`aria-setsize`. An APG tree makes the treeitem
itself the one focusable unit under a roving tabindex, which cannot coexist
with a slot-driven component whose nodes hold _your_ links and buttons. So
rather than advertise tree semantics and then ignore the Arrow/Home/End
keyboard contract they promise — a role without its keyboard behaviour is worse
than no role, because assistive tech announces an affordance that isn't there —
the tree claim is simply not made. Each branch is an ordinary disclosure: a
button that shows and hides a region.

What the component renders automatically:

- Each children container gets the `id` that the `aria-controls` in
  `expandProps` points at — that pairing is the whole disclosure wiring.
- A collapsed container is `inert`, so its contents leave the tab order and the
  accessibility tree. Collapsing is CSS-only (`grid-template-rows: 0fr`), which
  hides pixels but not focusability, so without this a collapsed branch's nested
  toggles would stay Tab-reachable while invisible.

What you must add:

- A real focusable toggle per branch: bind `expandProps` to a `<button>`. It
  carries `aria-expanded` and `aria-controls` for you, and Enter/Space work
  natively. On a non-button element `expandProps`' keydown handler covers
  Enter/Space, but you'd still owe it `tabindex="0"` and a role — use a button.
- An `aria-label` on icon-only toggles naming node and action (e.g.
  `Collapse src`) — a bare chevron has no accessible text.

Keyboard users Tab through whatever focusable controls your slots render and
toggle with Enter/Space — the standard disclosure interaction, and there is
nothing tree-specific to learn. Plan your node markup (one focusable control per
row) with that in mind.

## v-model

- `v-model:expandedItems` — type: `any[] \| undefined`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `expandable` | `BbTreeExpandable<Meta> \| undefined` |  |  | Defines nodes as expandable. It can be a global boolean, or a function that receives the node, its depth, and its parent and returns a boolean. |
| `expandedItems` | `any[] \| undefined` | `[]` |  | Live expansion state: the list of expanded node values (see `itemValue`). Branch nodes not explicitly collapsed via `expanded: false` seed the list when they first appear in `items`; from then on this model is the single source of truth. |
| `items` | `BbTreeItem<Meta>[]` | `[]` | yes | Tree-like structure of nodes to render. |
| `itemValue` | `ItemAccessor<Meta> \| undefined` | `the whole `meta` object` |  | Identity of a node, used to hash entries of `expandedItems` and to name per-node slots. A string reads that key from `meta`; a function receives `meta` and returns the value. |

## Events

- `update:expandedItems` — `(event: "update:expandedItems", value: any[]): void`

## Slots

- `default` — scope: `BbTreeNodeSlotProps<Meta>`

## See Also

- [BbTable](./BbTable.md) — Displays tabular data, configurable columns and data mapper.
- [BbAccordion](./BbAccordion.md) — Expands and collapses a content panel.

---

<!-- dist/ai/ChipsBox.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/ChipsBox.md -->

# ChipsBox

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Layout & Utility**
- Description: Layout helper for rendering chip collections.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/ChipsBox.md](./source/ChipsBox.md)

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `disabled` | `boolean \| undefined` | `false` |  | Whether the component is disabled. |
| `options` | `Option[]` |  | yes | List of options to render as chips. |
| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| undefined` |  |  | The size of the chips. |

## Events

- `option:unselected` — `(event: "option:unselected", option: Option): void`

## Slots

- None.

## Exposed (template ref)

- `blur`: `() => void`
- `confirmOption`: `() => void`
- `focusByHash`: `(hash: string) => void`
- `focusFirst`: `() => void`
- `focusFirstSelected`: `() => void`
- `focusLast`: `() => void`
- `focusLastSelected`: `() => void`
- `focusNext`: `() => void`
- `focusPrevious`: `() => Promise<void>`
- `getHighlighted`: `() => Option \| undefined`

---

<!-- dist/ai/ClearableButton.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/ClearableButton.md -->

# ClearableButton

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Inputs**
- Description: Action button for clearing current input value.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/ClearableButton.md](./source/ClearableButton.md)

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `string \| undefined` |  |  | Accessible label announced by screen readers. Falls back to localized `common.clearLabel` when omitted. |

## Events

- None.

## Slots

- None.

---

<!-- dist/ai/CommaBox.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/CommaBox.md -->

# CommaBox

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Layout & Utility**
- Description: Utility for comma-separated content rendering.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/CommaBox.md](./source/CommaBox.md)

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `options` | `Option[]` |  | yes | List of options to render as comma-separated text items. |

## Events

- `option:unselected` — `(event: "option:unselected", option: Option): void`

## Slots

- None.

## Exposed (template ref)

- `blur`: `() => void`
- `confirmOption`: `() => void`
- `focusByHash`: `(hash: string) => void`
- `focusFirst`: `() => void`
- `focusFirstSelected`: `() => void`
- `focusLast`: `() => void`
- `focusLastSelected`: `() => void`
- `focusNext`: `() => void`
- `focusPrevious`: `() => Promise<void>`
- `getHighlighted`: `() => Option \| undefined`

---

<!-- dist/ai/CommonInputWrapper.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/CommonInputWrapper.md -->

# CommonInputWrapper

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Layout & Utility**
- Description: Shared wrapper utility for composed input controls.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/CommonInputWrapper.md](./source/CommonInputWrapper.md)

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `active` | `boolean \| undefined` | `false` |  | Whether the input is in active/focused state (e.g. open dropdown). |
| `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
| `clearable` | `boolean \| undefined` | `false` |  | Whether the input is clearable. |
| `compact` | `boolean \| undefined` | `false` |  | Whether the input is in compact mode. |
| `disabled` | `boolean \| undefined` | `false` |  | Whether the input is disabled. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Whether the input has validation errors. |
| `hasValue` | `boolean \| undefined` | `undefined` |  | Whether the wrapped control currently has a value that can be cleared. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Whether the input has a warning state. Visually identical to `hasErrors` but uses `--bb-warn` chrome; errors take priority when both are set. |
| `loading` | `boolean \| undefined` | `false` |  | Whether the input is in a loading state. |
| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
| `preventFocus` | `boolean \| undefined` | `false` |  | Prevents the wrapper from focusing the inner input on click. |
| `readonly` | `boolean \| undefined` | `false` |  | Whether the input is readonly. |
| `reserveAppendSpace` | `boolean \| undefined` | `false` |  | Keeps trailing action/icon space reserved even when currently empty. |

## Events

- `click:clear` — `(event: "click:clear"): void`
- `container:click` — `(event: "container:click"): void`

## Slots

- `append` — scope: `object` — Wraps the trailing suffix area. Renders a `<span>` containing the `suffix` sub-slot by default.
- `append-outer` — scope: `object` — Content appended outside the inner input container.
- `default` — scope: `object` — The main input element (e.g. `<input>` or `<textarea>`).
- `prefix` — scope: `object` — Content rendered as an inline text prefix inside the prepend span.
- `prepend` — scope: `object` — Wraps the leading prefix area. Renders a `<span>` containing the `prefix` sub-slot by default.
- `prepend-outer` — scope: `object` — Content prepended outside the inner input container.
- `suffix` — scope: `object` — Content rendered as an inline text suffix inside the append span.

---

<!-- dist/ai/CommonPopover.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/CommonPopover.md -->

# CommonPopover

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Overlay**
- Description: Shared popover behavior and structure primitive.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/CommonPopover.md](./source/CommonPopover.md)

## v-model

- `v-model` — type: `boolean \| undefined`

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `anchor` | `any` |  |  | The element the popover positions itself relative to. Accepts an HTMLElement, a Vue component ref, or a virtual element with a `getBoundingClientRect` method. |
| `arrowPadding` | `number \| undefined` |  |  | Space the arrow will maintain to the edge of the dropdown. Useful when the floating element has border radius so it won't appear broken |
| `boundary` | `string \| Record<string, any> \| HTMLElement \| null \| undefined` |  |  | Constrains the popover's *placement* within a bounding element: `flip` and `shift` keep the popover inside these bounds. Does NOT clamp the popover's size — a short boundary (e.g. a single-line nav) will not collapse the bubble. Use {@link … |
| `dialog` | `boolean \| undefined` | `false` |  | Renders the popover as a `<dialog>` element (modal overlay) instead of a `<span>` with the Popover API. |
| `disableFlip` | `boolean \| undefined` | `false` |  | Disables the automatic flip to the opposite side when the popover would overflow (flipping is on by default). |
| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
| `forceAutoUpdate` | `boolean \| undefined` | `false` |  | Keeps floating-ui's `autoUpdate` (scroll/resize/resize-observer tracking) running while the popover is closed. By default the position is only tracked while the popover is open, so idle popovers attach no listeners. Enable this only when th… |
| `hideArrow` | `boolean \| undefined` | `false` |  | Hides the arrow indicator. |
| `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to show / hide the bubble. Closed until the owning component opens it. |
| `offset` | `number \| undefined` |  |  | Space the floating container will maintain from the activator. |
| `overflowBoundary` | `string \| Record<string, any> \| HTMLElement \| null \| undefined` |  |  | Bounding element the `size` middleware measures free space against, driving the `availableHeight`/`availableWidth` slot props. Defaults to the clipping ancestors (ultimately the viewport) when omitted, so the popover can grow to the full av… |
| `padding` | `number \| undefined` | `0` |  | Minimum empty space to keep from the edge of the page |
| `placement` | `Placement \| undefined` |  |  | Position of the overlay in respect to the related activator. |
| `tag` | `PopoverTag \| undefined` | `"div"` |  | Element rendered as the popover wrapper (and as the bubble inside it). Overridden to `dialog` when `dialog` is `true`. The wrapper is `position: fixed` either way, so this only decides markup validity: `div` is correct wherever the bubble h… |
| `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds |

## Events

- `update:modelValue` — `(event: "update:modelValue", value: boolean): void`

## Slots

- `default` — scope: `{ availableWidth: number \| undefined; availableHeight: number \| undefined; }` — Content rendered inside the popover bubble. Receives the free space between the anchor and the boundary edge for the resolved placement, so the content can cap its own scroll container. Both are `undefined` until the first reposition measur…

---

<!-- dist/ai/composables/useBbConfig.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/composables/useBbConfig.md -->

# useBbConfig

## Summary

`useBbConfig` exposes `setConfig`, which patches the library's **runtime-editable**
configuration. The editable surface is deliberately tiny: `DynamicConfig`
contains only `locale`. Everything else (label modes, size maps, variants, link
component names, `toastPosition`, …) is fixed at build time through the Vite
plugin (`bitbossUi({ ... })`) and cannot be changed at runtime.

Use it for exactly one job: switching the locale of locale-aware components
(built-in labels, close buttons, table/pagination strings) while the app runs.

## Import

```ts
import { useBbConfig } from 'bitboss-ui';

const { setConfig } = useBbConfig();
```

## API

### `setConfig(patch)`

```ts
declare function setConfig(patch: Partial<DynamicConfig>): void;
// DynamicConfig = { locale: 'it' | 'en' }
```

Merges the patch into **this app's** config. The change is immediate and
reactive — every mounted component in that app which reads the key updates.

### Per-request locale under SSR

The config is held **per Vue app**, and SSR gives every request its own app,
so a per-visitor locale is correct on the server's first paint. Set it where
the app is created:

```ts
// server entry — one app per request, so this is per-request
const app = createSSRApp(App);
app.use(bitbossUiPlugin, { locale: localeFor(request) });
```

That is the route to prefer. It is right before hydration, so it is what
crawlers index, what a prerendered search index reads, and what a reader with
JS disabled keeps.

**`setConfig` during a server render is the fallback, and it has one rule:**
call it from a component's `setup` (or a composable a component calls), where
it can resolve the current app. Called from module scope there is no app to
address, so the write lands on the process-global build-time defaults and
leaks into other visitors being served concurrently — it warns in dev when it
detects this.

On the client none of this matters: one process is one user, and `setConfig`
from anywhere is fine.

_(Changed in 3.0.0-beta.15 — Q18.2. Before it, the config was a single
process-global object and a per-visitor locale genuinely was impossible.)_

## Usage example

**Two locale sources exist side by side, and a locale switch must move both.**
`setConfig({ locale })` only ever affects strings the _library_ owns (close
buttons, table/pagination labels, the search field's accessible name, …) — it
has no effect on your own app copy. If your app renders text through an i18n
library's `t()` (vue-i18n's `useI18n()` below, or your own equivalent), that
locale has to flip too, in the same handler. A switch that moves only one of
the two looks like it works — the button itself always reflects the last
click — while half the page silently stays in the old language.

```vue
<template>
	<BbButton
		prepend:icon="lucide:languages"
		size="sm"
		variant="ghost"
		@click="toggleLocale"
	>
		{{ locale === 'it' ? 'English' : 'Italiano' }}
	</BbButton>
</template>

<script setup lang="ts">
import { useI18n } from 'vue-i18n';
import { BbButton, useBbConfig } from 'bitboss-ui';

// `locale` (vue-i18n) drives every `t()` call in your own templates;
// `setConfig` drives the library's own built-in strings. Both read from the
// same click — there is no single call that updates both for you.
const { locale } = useI18n<{ message: {} }, 'it' | 'en'>();
const { setConfig } = useBbConfig();

const toggleLocale = () => {
	const next = locale.value === 'it' ? 'en' : 'it';
	locale.value = next;
	setConfig({ locale: next });
};
</script>
```

## Guest locale switcher (auth/guest layouts)

A locale toggle on a login/register/forgot-password screen has no logged-in
user to persist a preference on server-side — the switch has to survive a
reload and a return visit entirely on the client, or it silently resets to
the app default every time the guest navigates. Layer persistence onto the
same dual wiring above, never in place of it:

```ts
// composables/useGuestLocale.ts — call once from the auth/guest layout root
import { useI18n } from 'vue-i18n';
import { useBbConfig } from 'bitboss-ui';

const STORAGE_KEY = 'guest-locale';

export function useGuestLocale() {
	const { locale } = useI18n<{ message: {} }, 'it' | 'en'>();
	const { setConfig } = useBbConfig();

	const setLocale = (next: 'it' | 'en') => {
		locale.value = next; // app copy
		setConfig({ locale: next }); // library strings
		localStorage.setItem(STORAGE_KEY, next); // survives reload, no session yet
	};

	// Restore on boot, before anything renders in the guest's chosen language.
	const saved = localStorage.getItem(STORAGE_KEY);
	if (saved === 'it' || saved === 'en') setLocale(saved);

	return { locale, setLocale };
}
```

A cookie (`SameSite=Lax`, no `httpOnly`) works the same way and is the better
choice when the same preference should also be readable server-side for the
first SSR/Inertia response — `localStorage` alone only takes effect after
hydration, so the very first paint still renders in the default locale.

## Anti-patterns

- **Flipping only a local `ref` for the button's own label.** This changes
  nothing about the app: no `t()` output changes and no library string
  changes, because neither locale source was ever touched — it is a
  decorative toggle that looks functional in a screenshot and does nothing
  on click.
- **Calling `setConfig` without also flipping your i18n library's locale**
  (or the reverse). The two are independent state; a handler that updates
  only one leaves the library's chrome and your app's copy in different
  languages until something else happens to resync them.
- Don't try to patch plugin options (`defaultInputLabelMode`, `mobileMaxWidth`,
  `dialogDefaultSizes`, variant registries, …) through `setConfig` — they are
  not part of `DynamicConfig` and the types will reject them. Set them once in
  `vite.config.ts`.
- Don't call `setConfig` to scope a change to one page: the config is a global
  singleton, not per-component state.

## Related

- [Installation and plugin setup](../guides/installation-and-plugin-setup.md) —
  every plugin option, including the compile-time ones, with defaults.

---

<!-- dist/ai/composables/useBbFormContext.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/composables/useBbFormContext.md -->

# useBbFormContext

## Summary

`useBbFormContext` gives you a live handle on a `<BbForm>` addressed by its
`id`: whether it is valid, dirty, touched, pending or submitting, its current
`values` and `errors`, and the three things you can ask it to do — `submit()`,
`reset()`, `validate()`.

Reach for it when the chrome that reads or drives the form lives **outside** the
`<form>` element: a dialog footer whose submit button sits below the content, a
page toolbar, a "discard changes" affordance in a header, a route-leave guard
that needs to know whether anything is dirty.

For chrome **inside** the form, prefer the default slot's scope — it carries the
same state without an id.

This is `BbForm`'s **only** outside handle: the component intentionally has no
`defineExpose`, so nothing reaches into the instance. Same id-context pattern as
[`useBbTableContext`](./useBbTableContext.md) and `useBbDropdownContext`.

## Import

```ts
import { useBbFormContext } from 'bitboss-ui/validated';
```

It ships from the `validated` entrypoint alongside the controls it belongs to,
and needs the `vee-validate` peer dependency like the rest of that layer.

## Usage

Give the form an explicit `id`, then address it from anywhere:

```vue
<script setup lang="ts">
import { BbButton, BbDialog } from 'bitboss-ui';
import { BbForm, BbTextInput, useBbFormContext } from 'bitboss-ui/validated';

const invite = useBbFormContext('invite-teammate');
</script>

<template>
	<BbDialog v-model="open" title="Invite teammate">
		<BbForm id="invite-teammate" @submit="sendInvite">
			<BbTextInput label="Email" rules="required|email" type="email" />
		</BbForm>

		<template #footer>
			<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
			<BbButton
				:loading="invite.submitting.value"
				variant="primary"
				@click="invite.submit()"
			>
				Invite
			</BbButton>
		</template>
	</BbDialog>
</template>
```

`submit()` routes through the same handler the form's own submit button would
trigger, so validation gates the request in exactly one place and `@submit`
stays the only place the work happens.

## The handle

| Field         | Type                                               | Meaning                                                      |
| ------------- | -------------------------------------------------- | ------------------------------------------------------------ |
| `isReady`     | `ComputedRef<boolean>`                             | A form with this id is mounted.                              |
| `valid`       | `ComputedRef<boolean>`                             | Every field currently passes.                                |
| `dirty`       | `ComputedRef<boolean>`                             | At least one field differs from its initial value.           |
| `touched`     | `ComputedRef<boolean>`                             | At least one field has been interacted with.                 |
| `pending`     | `ComputedRef<boolean>`                             | An async rule is in flight.                                  |
| `submitting`  | `ComputedRef<boolean>`                             | A submit handler is running.                                 |
| `submitCount` | `ComputedRef<number>`                              | Submission attempts so far.                                  |
| `values`      | `ComputedRef<Record<string, unknown>>`             | Current values, keyed by field name (`vid` or from `label`). |
| `errors`      | `ComputedRef<Record<string, string \| undefined>>` | Current messages, keyed by field name.                       |
| `submit()`    | `() => void`                                       | Ask the form to submit (validation still gates it).          |
| `reset()`     | `() => void`                                       | Reset every field to its initial value.                      |
| `validate()`  | `() => Promise<boolean>`                           | Validate now; resolves to whether the form is valid.         |

## Rules and gotchas

- **The id must be explicit.** Auto-generated ids cannot be targeted, and a form
  without an `id` simply has no outside handle — the right default for a
  self-contained form.
- **Callable before the form mounts.** Every field reads a stable baseline
  (`false`, `0`, `{}`) and every action is a no-op until `isReady` flips true, so
  a footer that renders ahead of its dialog's content is safe. Watch `isReady`
  when you need to distinguish "not mounted" from "mounted and invalid".
- **Read-only state, imperative actions.** The fields are computeds; you change
  values through the controls' own `v-model`s, not through the handle.
- **Client-side only.** The registry is module-level and deliberately not
  populated during SSR (it would leak across requests).
- **Ids should be unique per mounted form.** Two mounted forms sharing one id
  both mirror into the same node, so the handle reports whichever wrote last.

## See also

- [Validated Forms](../guides/validated-forms.md) — the whole
  `bitboss-ui/validated` layer: setup, rules, the added props, controls.
- [`useBbTableContext`](./useBbTableContext.md) — the same pattern for `BbTable`.

---

<!-- dist/ai/composables/useBbTableContext.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/composables/useBbTableContext.md -->

# useBbTableContext

## Summary

`useBbTableContext` gives you a live, two-way handle on a `BbTable`'s state —
selection, select-all, unselected items, **sort**, **highlight**, and paging —
addressed by the table's `id`. Any component (a toolbar, a details panel, a
parent page, `BbPagination`) can read or drive that state without being in the
table's subtree and without prop drilling.

It works **alongside** the table's v-models, not instead of them: the table
keeps its bound props in sync with the context in both directions, so you can
use props, the context, or both at once.

Use it when the thing that reads or changes table state lives **outside** the
table — a bulk-action bar above the table, a detail drawer that highlights the
active row, a "clear filters" button that resets sort, a pagination control
rendered elsewhere.

## Import

```ts
import { useBbTableContext } from 'bitboss-ui';
```

## API

```ts
declare function useBbTableContext(
	id: MaybeRefOrGetter<string | undefined>,
	initial?: BbTableContextInitial
): BbTableContext;
```

- **`id`** — `string | Ref<string> | () => string`. Must match the `id` prop
  you pass to `<BbTable id="…">`. This is the rendezvous key; a typo silently
  produces an orphan handle that syncs with nothing (see Gotchas).
- **`initial`** — optional partial state seed: an object with any of the
  handle's writable fields (`selected`, `unselected`, `all`, `highlighted`,
  `sort`, `page`, `perPage`, `totalItems`, `totalPages`). Fields you
  provide are injected into the table on mount (e.g. setting
  `page`/`perPage`/`totalItems` activates the table's `aria-rowcount` /
  `aria-rowindex` accessibility exactly as the equivalent props would); fields
  you omit are filled in by the table from its own props.

### Returned handle

The handle's type is exported as `BbTableContext`. Every field is a
`WritableComputedRef` — read `.value`, assign `.value` to drive the table.

| Field         | Type                                  | Mirrors (table)            | Empty baseline |
| ------------- | ------------------------------------- | -------------------------- | -------------- |
| `selected`    | `any` (array in multiple mode)        | `v-model`                  | `[]`           |
| `unselected`  | `any[]`                               | `v-model:unselected-items` | `[]`           |
| `all`         | `boolean`                             | `v-model:select-all`       | `false`        |
| `highlighted` | `any` (a single item value or `null`) | `v-model:highlighted`      | `null`         |
| `sort`        | `BbTableSortEntry[]`                  | `v-model:sort`             | `[]`           |
| `page`        | `number`                              | `page` / `BbPagination`    | `1`            |
| `perPage`     | `number`                              | `perPage`                  | `0`            |
| `totalItems`  | `number`                              | `totalItems`               | `0`            |
| `totalPages`  | `number`                              | derived / `totalPages`     | `1`            |
| `isReady`     | `ComputedRef<boolean>` (read-only)    | —                          | —              |

**Stable baselines.** Every field reads its empty baseline (never `undefined`)
even before the table mounts or on a handle nobody hosts — so you can read,
iterate, and bind immediately without guards. An explicit `null` (a cleared
single-mode selection/highlight) passes through unchanged.

**`totalPages`** is derived (`ceil(totalItems / perPage)`) whenever a real
`totalItems` is known; otherwise it reads the seeded page count (a `totalPages`
prop on `BbTable` or `BbPagination`, an `initial`, or a write here). Assigning
it stores such a seed — it never overrides a derivation backed by a real
`totalItems`. An array table's inferred `totalItems` (its `items.length`) does
not count as real: an explicit seed outranks it.

**`isReady`** is `true` once the context can answer the page count — a real
`totalItems` (your `initial`, the table's props, or a write) or a seeded
`totalPages` — rather than fallback defaults. It answers "is paging data real
yet", **not** "is a table attached".

## Usage Example — bulk actions from a toolbar

```vue
<template>
	<div class="flex flex-col gap-3">
		<!-- Toolbar OUTSIDE the table subtree, driven by the context -->
		<div v-if="selectedCount" class="flex items-center gap-2">
			<span class="text-sm">{{ selectedCount }} selected</span>
			<BbButton
				prepend:icon="lucide:trash-2"
				size="sm"
				variant="destructive"
				@click="deleteSelected"
			>
				Delete
			</BbButton>
			<BbButton size="sm" variant="ghost" @click="clearSelection">
				Clear
			</BbButton>
		</div>

		<BbTable
			id="members-table"
			v-model="selected"
			caption="Members"
			:columns="[
				{ key: 'name', label: 'Name' },
				{ key: 'role', label: 'Role' },
			]"
			:items="fetchMembers"
			selectable
		/>
	</div>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbButton, BbTable, useBbTableContext } from 'bitboss-ui';

const selected = ref<string[]>([]);
const fetchMembers = () => api.members.list();

// Same id as the table. No prop drilling to the toolbar.
const ctx = useBbTableContext('members-table');

const selectedCount = computed(() => ctx.selected.value?.length ?? 0);
const clearSelection = () => (ctx.selected.value = []);
const deleteSelected = async () => {
	await api.members.deleteMany(ctx.selected.value);
	ctx.selected.value = [];
};
</script>
```

## Gotchas

- **The `id` is a rendezvous key — a mismatch does not error, it orphans.**
  `useBbTableContext('users-tabel')` (typo) and `<BbTable id="users-table">`
  create two independent state nodes. Your handle still returns stable
  baselines and your `initial` still seeds _it_, so the panel looks alive —
  but nothing flows to or from the table. If a context "works" but the table
  never reacts, check the id spelling first. `isReady` being `true` only means
  your `initial` set paging values; it does **not** confirm a table is
  attached.
- **Client-side only.** During SSR the handle operates on a detached, unshared
  state (the table still renders from its props). Cross-component wiring is
  hydration-time onward.
- **Creation order does not matter.** Whoever references the id first (this
  composable, the table, or a `BbPagination` with a matching `table-id`)
  creates the shared node; the rest join it. Call `useBbTableContext` before
  or after the table mounts.
- **`sort` does not reorder data.** The context mirrors the model; you apply
  it to your data source (see the BbTable contract and the Sortable columns
  recipe variation).

## Related

- [BbTable](../BbTable.md) — the props/events/slots this mirrors.
- [BbPagination](../BbPagination.md) — joins the same context via its `table-id` prop.
- [Recipe: CRUD listing page](../recipes/inertia/records-workspace.md) — full server-driven table assembly.
- [useBbTabsContext](./useBbTabsContext.md) — the same by-id pattern for `BbTabs`.

---

<!-- dist/ai/composables/useBbTabsContext.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/composables/useBbTabsContext.md -->

# useBbTabsContext

## Summary

`useBbTabsContext(id)` gives you a live handle on a mounted `BbTabs` /
`BbTabsRoot` group, addressed by the same `id` you gave the component. Any
component on the client — a page header, a "Next section" button in a footer, a
keyboard shortcut handler — can read the active tab or change it without
template refs and without being in the tabs' subtree.

It is the tabs sibling of [`useBbTableContext`](./useBbTableContext.md): same
id-rendezvous pattern, same "call it before or after the component mounts"
ergonomics.

## Import

```ts
import { useBbTabsContext } from 'bitboss-ui';
```

## API

```ts
const tabs = useBbTabsContext<K>(id); // `K` is optional and defaults to `string`
```

- **`id`** — must match the `id` prop on `<BbTabs id="…">` or
  `<BbTabsRoot id="…">`. Give the component an explicit `id`; auto-generated
  ids are not addressable.
- **`K`** — optional union of the tab keys, narrowing `current` and `select`.

### Returned handle (`BbTabsContextHandle<K>`)

Individual computed refs and functions — safe to destructure.

| Member         | Type                                                     | Description                                                                                                                                                                         |
| -------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `isReady`      | `ComputedRef<boolean>`                                   | Whether a tabs instance with this id is currently mounted.                                                                                                                          |
| `current`      | `WritableComputedRef<K \| null>`                         | Active tab key (`null` until the tabs mount). **Writable**: assigning a key selects it, exactly like `select(key)`. Setting `null` warns and is ignored — a tab is always selected. |
| `currentIndex` | `ComputedRef<number>`                                    | Zero-based index of the active tab (`-1` until mount).                                                                                                                              |
| `isFirst`      | `ComputedRef<boolean>`                                   | Active tab is the first item.                                                                                                                                                       |
| `isLast`       | `ComputedRef<boolean>`                                   | Active tab is the last item.                                                                                                                                                        |
| `goTo`         | `(t: 'first' \| 'previous' \| 'next' \| 'last') => void` | Relative navigation; skips `disabled` tabs.                                                                                                                                         |
| `select`       | `(key: K) => void`                                       | Select by key. Unknown keys warn and leave the selection untouched.                                                                                                                 |

Selection through the handle goes through the tabs' full pipeline: the
component's `v-model` is emitted, and URL / Inertia navigation runs when the
tabs have `navigation` — identical to clicking the trigger.

## Usage example — steer tabs from outside

```vue
<template>
	<div class="flex items-center justify-between">
		<h2 class="text-lg font-semibold">Project settings</h2>
		<BbButton
			append:icon="lucide:arrow-right"
			:disabled="isLast"
			size="sm"
			variant="outline"
			@click="goTo('next')"
		>
			Next section
		</BbButton>
	</div>

	<BbTabs
		id="settings-tabs"
		:items="[
			{ key: 'general', label: 'General' },
			{ key: 'security', label: 'Security' },
			{ key: 'billing', label: 'Billing' },
		]"
	>
		<!-- one pane slot per key -->
	</BbTabs>
</template>

<script setup lang="ts">
import { BbButton, BbTabs, useBbTabsContext } from 'bitboss-ui';

// Same id as the tabs. Works from any component on the page.
const { current, goTo, isLast } = useBbTabsContext<
	'general' | 'security' | 'billing'
>('settings-tabs');

// current is writable: current.value = 'billing' jumps straight there.
</script>
```

## Behavior and gotchas

- **Callable before the tabs mount.** The handle starts empty (`isReady`
  `false`, `current` `null`, `currentIndex` `-1`) and auto-populates when the
  tabs render; it empties again on unmount. Actions (`select`, `goTo`, writing
  `current`) on an unmounted id warn and no-op.
- **The id is a rendezvous key.** A typo doesn't error — it just never becomes
  ready. If actions warn about no mounted instance, check the id spelling
  against the component's `id` prop.
- **Duplicate ids are an error.** Two mounted tab groups with the same id log
  an error; the handle resolves to the most recently mounted one.
- **Client-side only.** During SSR the registry stays empty; wire cross-
  component behavior from hydration onward.
- **Don't rebuild navigation on top of it.** For URL-driven tabs use the
  component's own `navigation` / `query-key` / `href` support — the handle then
  rides along. Never `router.push` manually to change a tab.

## Related

- [BbTabs](../BbTabs.md) — batteries-included tabs (strip + panes).
- [BbTabsRoot](../BbTabsRoot.md) — renderless root for split strip/panes layouts; its default slot exposes the same `select` / `goTo` / `isFirst` / `isLast` inside the subtree.
- [useBbTableContext](./useBbTableContext.md) — the same by-id pattern for `BbTable`.

---

<!-- dist/ai/composables/useConfirm.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/composables/useConfirm.md -->

# useConfirm

## Summary

`useConfirm` opens a modal confirm dialog and returns a promise that resolves
with the user's decision. **A new `confirm()` replaces the open dialog**: the
superseded promise resolves `false` and no callback runs. Dialogs do not queue,
so `await` one before opening the next.
Per the design language, every `destructive` action must pass through a confirm.

**Requires exactly one `<BbConfirm />` host, mounted at the app root** (`App.vue`
under Vue, `app.vue` under Nuxt, the `createInertiaApp` render root under
Inertia) — never one per page or per component. With no host, `await confirm(...)`
never settles and the caller hangs silently. With two hosts, every dialog renders
twice. See [Agent Contract § Global Host Rule](../guides/agent-contract.md).

## Import

```ts
import { useConfirm } from 'bitboss-ui';

const { confirm, close, dismissAll } = useConfirm();
```

**Ownership** — when called inside a component (any effect scope), the
returned `confirm`'s dialogs are tied to that scope: if it is disposed while a
dialog is open (browser Back, route change, the component unmounts),
the dialog is dismissed quietly — promise resolved `false`, no callback runs.
Call `useConfirm()` outside a component scope (app setup, store, module level)
for app-lifetime confirms.

## API

### `confirm(message)`

```ts
declare function confirm(message: BbConfirmMessage): Promise<boolean>;
```

Resolves with:

- `true` / `false` for the Yes / No outcome (also `false` on `duration`
  auto-dismiss, on implicit dismiss — backdrop, Escape, X — and on owner-scope
  disposal).
- The clicked button's `onClick` return value when `returning: true`.

Rejects **only** when a button's `onClick` throws.

`false` means _not confirmed_, not necessarily _declined_ — decline-only
behavior belongs in `no.onClick`, not the `if (!ok)` branch.

### `close()`

```ts
declare function close(): void;
```

Hides the current dialog 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
the buttons — a `confirm()` closed this way before any button ran leaves its
promise pending.

### `dismissAll()`

```ts
declare function dismissAll(): void;
```

Quietly dismisses the open dialog, regardless of owner:
pending promises resolve `false`, no callback runs. An imperative escape hatch
for app-level events — logout, a global error boundary, or router wiring in
apps that want route-based dismissal.

## `BbConfirmMessage` options

At least one of `title`, `text`, `portal` should be set (dev warning otherwise).

| Option        | Type                                            | Default     | Description                                                                                                                                                                                                                |
| ------------- | ----------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`       | `string`                                        | —           | Header title. Omit to render no header.                                                                                                                                                                                    |
| `text`        | `string`                                        | —           | Plain-text body. Takes priority over `portal`.                                                                                                                                                                             |
| `yes`         | `false \| string \| ConfirmButtonConfig`        | `'OK'`      | Positive button: `false` hides it, a string relabels it, an object gives full control (see below).                                                                                                                         |
| `no`          | `false \| string \| ConfirmButtonConfig`        | `'Annulla'` | Negative button: same three forms.                                                                                                                                                                                         |
| `variant`     | `ConfirmVariantType`                            | `'default'` | Dialog tone, applied as a CSS modifier class. `'destructive'` also makes the Yes button destructive.                                                                                                                       |
| `returning`   | `boolean`                                       | `false`     | Resolve with the clicked button's `onClick` return value instead of `true`/`false`.                                                                                                                                        |
| `dismissAsNo` | `boolean`                                       | `true`      | Whether user-initiated implicit dismissals (backdrop, Escape, X) invoke `no.onClick`. When `false` they resolve `false` quietly. System-initiated dismissals (`duration`, owner unmount, `dismissAll()`) are always quiet. |
| `autoClose`   | `boolean`                                       | `true`      | Close after the promise settles. Set `false` for multi-step flows ended by `close()`.                                                                                                                                      |
| `duration`    | `number`                                        | —           | Auto-dismiss after N ms, resolving `false` quietly (no callback). Implies `autoClose: true`.                                                                                                                               |
| `persistent`  | `boolean`                                       | `false`     | Block backdrop/Escape/X dismissal. Forced on while a callback runs.                                                                                                                                                        |
| `hideClose`   | `boolean`                                       | `false`     | Hide the X button. Combine with `persistent` to force a Yes/No choice.                                                                                                                                                     |
| `actions`     | `false \| ConfirmButtonConfig[]`                | —           | `false` hides the footer entirely (e.g. a portal owns the buttons). An array replaces Yes/No with custom buttons (see below).                                                                                              |
| `size`        | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` | —           | Maximum dialog width preset.                                                                                                                                                                                               |
| `fullscreen`  | `boolean \| 'mobile'`                           | —           | Fullscreen dialog; `'mobile'` restricts it to small screens.                                                                                                                                                               |
| `focusTarget` | `string`                                        | —           | CSS selector to focus after opening (default: first tabbable element).                                                                                                                                                     |
| `portal`      | `Component \| string`                           | —           | Custom body content. See **Portal modes**.                                                                                                                                                                                 |
| `portalProps` | `Record<string, unknown>`                       | —           | Data for the portal content.                                                                                                                                                                                               |

### `ConfirmButtonConfig`

| Field                          | Type                                | Default                             | Description                                                                                                                            |
| ------------------------------ | ----------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `text`                         | `string`                            | `'OK'` / `'Annulla'`                | Button label. Prefer a verb matching the action (_Delete_, _Publish_).                                                                 |
| `variant`                      | `ButtonVariantType`                 | yes: `'primary'`\*, no: `'outline'` | Button variant. \*Yes inherits `'destructive'` when the confirm variant is.                                                            |
| `size`                         | `BbButtonProps['size']`             | `'md'`                              | Button size.                                                                                                                           |
| `prepend:icon` / `append:icon` | `IconType`                          | —                                   | Icon before/after the label (`lucide:*` preferred).                                                                                    |
| `icon`                         | `IconType`                          | —                                   | Standalone icon button (no label).                                                                                                     |
| `block`                        | `boolean`                           | —                                   | Stretch to full footer width.                                                                                                          |
| `onClick`                      | `() => unknown \| Promise<unknown>` | —                                   | Async work done _before_ the dialog closes; the button spins while it runs. Its return value feeds the promise when `returning: true`. |

## Usage examples

### The destructive gate

```vue
<template>
	<BbButton prepend:icon="lucide:trash-2" variant="destructive" @click="remove">
		Delete
	</BbButton>
</template>

<script setup lang="ts">
import { BbButton, useConfirm } from 'bitboss-ui';

const { confirm } = useConfirm();

const remove = async () => {
	const ok = await confirm({
		title: 'Delete invoice?',
		text: 'Invoice INV-2048 will be permanently removed. This cannot be undone.',
		variant: 'destructive',
		yes: { text: 'Delete', 'prepend:icon': 'lucide:trash-2' },
		no: 'Cancel',
	});
	if (ok) await api.invoices.delete('INV-2048');
};
</script>
```

### Async work before the dialog closes

Put the work in `onClick` instead of after the `await`: the button shows a
spinner and the dialog stays open until it settles. Add `returning: true` to get
the callback's return value.

```ts
const post = await confirm({
	title: 'Publish post?',
	text: 'The post becomes visible to all members.',
	returning: true,
	yes: { text: 'Publish', onClick: () => api.posts.publish(draft.id) },
});
// post is the api result, or false when the user declined
```

### Custom footer actions — more than yes/no

Pass an `actions` array to replace the Yes/No footer with your own buttons.
Clicking any of them resolves `true`; dismissal (backdrop, Escape, X,
`duration`) resolves `false` without invoking any callback. Defaults per
button: `variant: 'outline'`, `size: 'md'`.

```ts
const saved = await confirm({
	title: 'Unsaved changes',
	text: 'Save your edits before leaving?',
	actions: [
		{ text: 'Discard', variant: 'destructive', onClick: discardDraft },
		{ text: 'Save', variant: 'primary', onClick: saveDraft },
	],
});
// saved: true (either button ran) | false (dismissed)
```

With `returning: true` the promise resolves with the clicked button's
`onClick` return value — the promise type is inferred as the union of all the
handlers' return types (buttons without a handler contribute `true`):

```ts
const decision = await confirm({
	title: 'Publish post?',
	returning: true,
	actions: [
		{ text: 'Publish now', variant: 'primary', onClick: () => 'now' as const },
		{ text: 'Schedule', onClick: () => 'later' as const },
	],
});
// decision: 'now' | 'later' | false
// (`as const` keeps the literals; without it each handler infers `string`)
```

An `actions` array owns the footer: `yes` / `no` are ignored (dev warning) and
`dismissAsNo` callbacks never fire. Everything else carries over from yes/no:

- While a handler runs, its button spins, the other actions are disabled, and
  the dialog is locked (`persistent` + `hideClose` forced on).
- A throwing handler **rejects** the promise and closes the dialog — use
  `try/catch` when a handler can fail.
- `duration` still auto-dismisses, resolving `false`.
- Every `ConfirmButtonConfig` field works per action — `prepend:icon` /
  `append:icon`, icon-only via `icon`, `block`, `size`, `variant`.

### Acknowledgement — one button

```ts
await confirm({ title: 'Saved', text: 'Your changes are live.', no: false });
```

### Named portal — inline content with `portalProps`

Declare `<BbConfirmPortal>` anywhere in the tree; its slot receives
`{ yes, no, props }` where `props` is your `portalProps`.

```vue
<template>
	<BbConfirmPortal name="remove-member">
		<template #default="{ props }">
			<div class="text-center">
				<p class="font-semibold">{{ props.name }}</p>
				<p class="text-sm text-gray-500">{{ props.role }}</p>
			</div>
		</template>
	</BbConfirmPortal>
</template>
```

```ts
const ok = await confirm({
	title: 'Remove member?',
	variant: 'destructive',
	portal: 'remove-member',
	portalProps: { name: 'Sofia Esposito', role: 'Editor' },
	yes: 'Remove',
	no: 'Cancel',
});
```

### Portal owning its own buttons

Hide the footer with `actions: false` and resolve from the slot's `yes` / `no`
helpers:

```vue
<BbConfirmPortal name="upload-success">
	<template #default="{ yes }">
		<div class="flex flex-col items-center gap-3">
			<p class="font-semibold">Upload complete</p>
			<BbButton variant="primary" @click="yes">Got it</BbButton>
		</div>
	</template>
</BbConfirmPortal>
```

```ts
await confirm({ portal: 'upload-success', actions: false });
```

### Component portal — reusable body

`portalProps` are forwarded as component props via `v-bind`:

```ts
import DeleteConfirmContent from './DeleteConfirmContent.vue';

const ok = await confirm({
	title: 'Delete file?',
	portal: DeleteConfirmContent,
	portalProps: { fileName: 'report.pdf' },
	yes: 'Delete',
	no: 'Cancel',
});
```

## Portal modes — comparison

|                      | Named portal (`portal: 'name'`)                     | Component portal (`portal: MyComponent`)                           |
| -------------------- | --------------------------------------------------- | ------------------------------------------------------------------ |
| Content defined in   | `<template>` via `<BbConfirmPortal name="...">`     | A separate `.vue` file                                             |
| Reactive local state | Always live — slot closure                          | Snapshot in `portalProps` (pass reactive objects for live updates) |
| `portalProps` access | Via `props` slot argument                           | Via `defineProps` in the component                                 |
| Best for             | One-off dialogs that reference local reactive state | Shared, reusable dialog bodies                                     |

## Required app-root setup

Mount `<BbConfirm />` **once, at the app root** — `App.vue` under Vue, `app.vue`
under Nuxt, the `createInertiaApp` render root under Inertia. A page that calls
`confirm()` mounts nothing; the self-contained examples in this guide each mount
their own host only because an example has no app root to mount it in:

```vue
<template>
	<RouterView />
	<BbConfirm />
</template>

<script setup lang="ts">
import { BbConfirm } from 'bitboss-ui';
</script>
```

`<BbConfirmPortal>` components can be placed anywhere — they register their
content by name and render nothing themselves.

## Related

- [BbConfirm](../BbConfirm.md) — the dialog render target and its guide.
- [BbConfirmPortal](../BbConfirmPortal.md) — named portal registration.
- [BbDialog](../BbDialog.md) — reach for it directly when you need a rich, multi-field modal instead of a decision.
- [useToast](./useToast.md) — when the message is informational, not a decision.

---

<!-- dist/ai/composables/useCountdown.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/composables/useCountdown.md -->

# useCountdown

## Summary

`useCountdown` creates a reactive countdown timer with a fixed 100 ms tick. It tracks elapsed and remaining time, exposes a progress percentage, and provides formatted time broken down by days, hours, minutes, and seconds.

Use it for resend-code timers, session-expiry warnings, auto-save countdowns — anywhere a duration must be displayed while it runs.

## Import

```ts
import { useCountdown } from 'bitboss-ui';
```

## API

### Setup

```ts
type UseCountdownOptions = {
	duration: number; // total duration in milliseconds (required, throws if falsy)
	onStart?: () => void; // called each time the timer starts or restarts
	onStop?: () => void; // called whenever the timer stops: pause, reset, and completion
	onFinish?: () => void; // called on completion, after onStop
};

const countdown = useCountdown(options);
```

The timer does not start on creation — call `start()`. Resolution is the 100 ms
tick, so keep durations in multiples of 100 ms.

### Returned values

| Name                 | Type                                             | Description                                                                                      |
| -------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| `elapsed`            | `ComputedRef<number>`                            | Milliseconds elapsed since start.                                                                |
| `remaining`          | `ComputedRef<number>`                            | Milliseconds remaining.                                                                          |
| `remainingFormatted` | `ComputedRef<{ days, hours, minutes, seconds }>` | Remaining broken into time units.                                                                |
| `progress`           | `ComputedRef<number>`                            | Percentage elapsed (0–100).                                                                      |
| `running`            | `Ref<boolean>`                                   | `true` while the timer is active (paused does not change this).                                  |
| `paused`             | `Ref<boolean>`                                   | `true` while the timer is paused.                                                                |
| `start()`            | `() => void`                                     | Starts, or resumes after `pause()`. No-op while running or once finished — use `restart()` then. |
| `restart()`          | `() => void`                                     | Resets to the full duration and starts immediately.                                              |
| `pause()`            | `() => void`                                     | Pauses without resetting (fires `onStop`).                                                       |
| `reset()`            | `() => void`                                     | Stops and resets elapsed to 0 (fires `onStop` unless paused).                                    |

The timer cleans up its interval automatically via `onBeforeUnmount`.

## Usage Example

```vue
<template>
	<div>
		<p>
			{{ remainingFormatted.minutes }}m {{ remainingFormatted.seconds }}s
			remaining
		</p>
		<BbProgress :model-value="progress" />
		<BbButton @click="start" :disabled="running && !paused">Start</BbButton>
		<BbButton @click="pause" :disabled="!running || paused">Pause</BbButton>
		<BbButton @click="reset">Reset</BbButton>
	</div>
</template>

<script setup lang="ts">
import { BbButton, BbProgress, useCountdown } from 'bitboss-ui';

const { remainingFormatted, progress, running, paused, start, pause, reset } =
	useCountdown({
		duration: 5 * 60 * 1000, // reservation held for 5 minutes
		onFinish: () => releaseReservation(),
	});
</script>
```

## Related Components

- [BbProgress](../BbProgress.md) — visualize `progress` as a progress bar.
- [BbSpinner](../BbSpinner.md) — indicate loading/pending state while timer runs.

---

<!-- dist/ai/composables/useId.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/composables/useId.md -->

# useId

## Summary

`useId` wraps Vue's built-in `useId()` and prefixes the result with `bb-ui-`.
It returns a ref holding the id plus a `refresh()` function that generates a
new one. Because it delegates to Vue's `useId`, the value is stable across
SSR and client hydration.

This is mostly internal glue — every `Bb*` input already wires its own
`id`/`for`/aria attributes. Reach for it only when you write custom markup
that needs an id for accessibility wiring (`aria-labelledby`,
`aria-describedby`, a hand-written `<label for>`). Do **not** use it for
entity ids, `v-for` keys over data, or anything persisted.

## Import

```ts
import { useId } from 'bitboss-ui';
```

## API

```ts
const { id, refresh } = useId();
```

| Name      | Type          | Description                                                     |
| --------- | ------------- | --------------------------------------------------------------- |
| `id`      | `Ref<string>` | The generated id, e.g. `bb-ui-v-0`. HTML5-safe characters only. |
| `refresh` | `() => void`  | Replaces `id.value` with a freshly generated id.                |

Call it during `setup` (a Vue `useId` requirement).

## Usage Example

```vue
<template>
	<section :aria-labelledby="id">
		<h3 :id="id" class="text-sm font-medium">Storage used</h3>
		<BbProgress :model-value="72" />
	</section>
</template>

<script setup lang="ts">
import { BbProgress, useId } from 'bitboss-ui';

const { id } = useId();
</script>
```

## Related

- [BbProgress](../BbProgress.md) — like all library components, manages its own internal ids; you only need `useId` for your own markup.

---

<!-- dist/ai/composables/useMobile.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/composables/useMobile.md -->

# useMobile

## Summary

`useMobile` returns the library-wide `isMobile` signal: `true` while the
viewport width is **below** `config.mobileMaxWidth` (a Vite plugin option,
default `768`). It is the exact same signal adaptive components
(BbDialog, BbDropdown, BbPopover, BbSelect, BbOffCanvas, …) use to switch to
their mobile/sheet presentation, so any JS-level layout decision you base on
it stays in lockstep with theirs.

Use it when custom behavior must agree with the library's adaptive switch —
e.g. collapsing a filter sidebar into an off-canvas on mobile. Do **not**
use it for plain responsive styling: that is CSS's job (Tailwind
breakpoints). Note that Tailwind's `md:` breakpoint (`min-width: 768px`)
happens to align with the default `mobileMaxWidth`.

## Import

```ts
import { useMobile } from 'bitboss-ui';
```

## API

```ts
const { isMobile } = useMobile();
```

| Name       | Type                   | Description                                           |
| ---------- | ---------------------- | ----------------------------------------------------- |
| `isMobile` | `ComputedRef<boolean>` | `true` when viewport width `< config.mobileMaxWidth`. |

The underlying width signal is a single module-level `useWindowSize()` from
`@vueuse/core` — the whole library shares one `resize` listener, so calling
`useMobile` in many components costs nothing.

**SSR:** there is no `window` on the server; the width only becomes real
after client mount. Treat `isMobile` as a client-side signal and avoid
letting it change server-rendered markup, or you invite hydration
mismatches.

## Usage Example

```vue
<template>
	<div class="flex gap-6">
		<aside v-if="!isMobile" class="w-64">
			<MemberFilters v-model="filters" />
		</aside>
		<template v-else>
			<BbButton
				prepend:icon="lucide:filter"
				variant="outline"
				@click="filtersOpen = true"
			>
				Filters
			</BbButton>
			<BbOffCanvas v-model="filtersOpen">
				<MemberFilters v-model="filters" />
			</BbOffCanvas>
		</template>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbOffCanvas, useMobile } from 'bitboss-ui';

const { isMobile } = useMobile();
const filtersOpen = ref(false);
const filters = ref({ status: 'active' });
</script>
```

## Related

- [BbOffCanvas](../BbOffCanvas.md) — the natural home for mobile-only panels.
- [Installation and plugin setup](../guides/installation-and-plugin-setup.md) — where `mobileMaxWidth` is configured.

---

<!-- dist/ai/composables/useSafeArea.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/composables/useSafeArea.md -->

# useSafeArea

## Summary

The library keeps its floating surfaces out from under its **own**
edge-anchored panels: open an off-canvas sheet and the toast stack slides
away from that edge in step with the panel. It cannot do the same for
**your** panels — a page-shell details sidebar, a filter rail, a docked
inspector — because they are ordinary page markup, and unlike a drawer they
are **non-modal**: the page stays interactive beside them, so nothing about
them says "this region is spoken for".

`useSafeArea` is how you say it. Register the panel while it is open and
the toast stack treats that edge as occupied.

Today the toast stack is the only reader, so the practical effect is exactly
that: **toasts stop covering your sidebar**. That is the whole feature — this
is not a layout system, and it moves nothing on your page.

## Import

```ts
import { useSafeArea } from 'bitboss-ui';
```

## API

```ts
const { claim } = useSafeArea({ side, size, active }); // static
const { claim } = useSafeArea({ side, element, active }); // measured
```

| Option    | Type                                                | Default    | Description                                                                     |
| --------- | --------------------------------------------------- | ---------- | ------------------------------------------------------------------------------- |
| `side`    | `'top' \| 'right' \| 'bottom' \| 'left'` (or ref)   | _required_ | The screen edge the panel is docked against.                                    |
| `size`    | `number` (or ref/getter)                            | —          | The panel's extent in px along that axis. `0` claims nothing.                   |
| `element` | `Ref<HTMLElement \| null \| undefined>` (or getter) | —          | Measured alternative to `size`; `null` claims nothing, so `v-if` needs no gate. |
| `active`  | `boolean` (or ref/getter)                           | `true`     | Whether the claim is live — see [Gate it to desktop](#gate-it-to-desktop).      |

| Returns | Type                  | Description                                            |
| ------- | --------------------- | ------------------------------------------------------ |
| `claim` | `ComputedRef<number>` | The current claim in px (`0` when inactive or closed). |

Pass **`size` or `element`, not both** — both together warns and keeps `size`.
The claim is released automatically when the component unmounts.

## Static or measured

**Reach for `size`.** A fixed-width sidebar already knows its number
(`22rem` → `352`), and declaring it means no observers, no measurement, and an
exact claim from the first frame. Keep it in step with the CSS that sizes the
panel — they are two statements of the same fact.

Open/closed can ride on **either** knob — these are the same claim, so use
whichever reads better where you are:

```ts
useSafeArea({ side: 'right', size: 320, active: () => open.value });
useSafeArea({ side: 'right', size: () => (open.value ? 320 : null) });
```

A `size` getter resting at `null` still means "I am declaring the size" — it
will not quietly fall back to measuring an `element`.

**`element` is for a panel whose extent is fluid** — content-driven, a
percentage, a drag-to-resize handle. It measures **not the panel's width but
how far it reaches from the screen edge** (`side: 'right'` →
`viewportWidth - rect.left`), so a panel held off the edge by a rail or a page
gutter claims that gap too — which is what a yielding reader actually has to
clear. Measurement is live: resize, scroll and layout changes all feed it. With
`size` you are declaring that same reach; for a panel flush with the edge (the
usual case) the two agree.

Claims compose by **`max`, never by sum**: each one already measures from the
edge, so the deepest claimant subsumes everything in front of it. Two panels
on one edge, or a panel behind an open off-canvas, cannot double-count.

## Gate it to desktop

Pass `active` for the condition under which the panel really is docked
_beside_ the page. The usual one is `!isMobile`: below the mobile breakpoint
the same sidebar is normally a full-screen overlay, and there is no room to
make — the page is behind it, not next to it.

Nothing breaks if you forget. A reader yields only while it still fits: when
the claim would leave a toast stack no usable room, it stops yielding and
overlaps instead, rather than pinning itself half off-screen. So an oversized
claim degrades to the old behaviour instead of pushing toasts out of reach.

## Usage Example

A fixed-width peek sidebar — the common case, declared:

```vue
<template>
	<div class="flex">
		<div class="flex-1"><slot /></div>

		<transition name="slide">
			<aside v-if="record" class="w-[22rem] shrink-0 border-l">
				<RecordPeek :record="record" />
			</aside>
		</transition>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { useMobile, useSafeArea } from 'bitboss-ui';

const record = ref<Record | null>(null);
const { isMobile } = useMobile();

// 22rem, and only while the sidebar is actually open beside the page.
useSafeArea({
	side: 'right',
	size: 352,
	active: () => !!record.value && !isMobile.value,
});
</script>
```

A resizable panel measures itself instead — same claim, no number to keep in
sync:

```ts
const sidebar = ref<HTMLElement>();
useSafeArea({ side: 'right', element: sidebar });
```

## Gotchas & anti-patterns

- **Don't claim for a `BbOffCanvas`.** Library panels register themselves; a
  second claim over the same panel is redundant (harmless — `max` — but it
  reads as if something else were docked there).
- **Don't claim for a modal overlay.** A dialog or a mobile sheet covers and
  inerts the page; toasts deliberately move _inside_ the top-most modal so
  they stay clickable, and a claim there just narrows where they can sit.
- **Don't expect dialogs to dodge it.** Only the toast stack reads claims
  today. Centring a modal in the leftover strip beside a sidebar would be
  worse, not better, so dialogs ignore claims by design.
- **A claim is not layout.** It moves nothing on the page and reserves no
  space — your panel's own CSS still owns where it sits.
- **Don't pass both `size` and `element`.** It warns and uses `size`; there is
  no merge rule worth guessing at. Pick the one that matches the panel.
- **A stale `size` is a silent wrong claim.** If you declare `352` and later
  change the CSS to `26rem`, nothing fails — the toast just lands 64px into
  the panel. Either keep the two together or switch to `element`.

## Related

- [useToast](./useToast.md) / [BbToast](../BbToast.md) — the reader: what
  actually gets out of the way.
- [BbOffCanvas](../BbOffCanvas.md) — the library panel that claims its edge
  for you, with no wiring at all.
- [Page Shell](../guides/page-shell.md) — the details sidebar this exists
  for; the scaffold already wires it.

---

<!-- dist/ai/composables/useToast.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/composables/useToast.md -->

# useToast

## Summary

`useToast` is the imperative API behind `BbToast`: call `toast(...)` from any
event handler to enqueue a transient, self-dismissing notification. Toasts stack
per viewport corner and disappear on their own (default **4000 ms**).

**Requires exactly one `<BbToast />` host, mounted at the app root** (`App.vue`
under Vue, `app.vue` under Nuxt, the `createInertiaApp` render root under
Inertia) — never one per page or per component. With no host, messages are
enqueued but never rendered _and never expire_, because the dismiss timer lives
inside the host. With two hosts, every message renders once per host. See
[Agent Contract § Global Host Rule](../guides/agent-contract.md).

Rule of thumb: `useToast` for _what just happened_ ("Saved", "Upload complete"),
`BbAlert` for the _current state of the page_ (a form error summary, a banner).

## Import

```ts
import { useToast } from 'bitboss-ui';

const { toast, dismiss, update } = useToast();
```

All three operate on one shared module-level stack — every `useToast()` call in
the app talks to the same host.

## API

### `toast(input)`

Enqueues a toast and returns its `id` (keep it to `update` or `dismiss` that
specific toast later).

```ts
declare function toast(input: string | BbToastOptions): string;
```

The string shorthand shows a plain title: `toast('Changes saved.')`.

### `BbToastOptions`

| Option        | Type                      | Default                          | Description                                                                                                                                                                                         |
| ------------- | ------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`       | `string`                  | —                                | Bold headline. At least one of `title`, `text`, `portal` should be set (dev warning otherwise).                                                                                                     |
| `text`        | `string`                  | —                                | Body copy under the title.                                                                                                                                                                          |
| `variant`     | `BbToastVariant`          | `'default'`                      | Visual tone. Registered variants (`success`, `info`, `warning`, `destructive` in the default setup) are typed; any string works for one-off variants (style `.bb-toast-message--<variant>`).        |
| `icon`        | `IconType`                | —                                | Optional leading icon (`lucide:*` preferred, e.g. `'lucide:circle-check'`). No icon is implied by the variant.                                                                                      |
| `loading`     | `boolean`                 | `false`                          | Shows a spinner and pins the toast open (implies `persistent`). Morph it later with `update(id, ...)`.                                                                                              |
| `duration`    | `number`                  | `4000`                           | Milliseconds before auto-dismiss. Must be `> 0` — `toast()` throws otherwise. Ignored when persistent.                                                                                              |
| `persistent`  | `boolean`                 | `loading`                        | Never auto-dismiss; user closes it, or your code calls `dismiss(id)`.                                                                                                                               |
| `hideClose`   | `boolean`                 | `false`                          | Hides the close button. Only combine with `persistent` when code will dismiss the toast itself.                                                                                                     |
| `position`    | `BbToastPosition`         | host → plugin → `'bottom-right'` | One of the six corners: `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`. Per-message override of the host's `position` prop and the plugin's `toastPosition`. |
| `actions`     | `ActionButtonConfig[]`    | —                                | Buttons rendered in a row below the text (undo, retry…). See **Action buttons** below. Not rendered for portal toasts.                                                                              |
| `portal`      | `Component \| string`     | —                                | Rich custom content: a `<BbToastPortal name="...">` name, or a component rendered in the toast body.                                                                                                |
| `portalProps` | `Record<string, unknown>` | —                                | Data for the portal content (slot `props` for named portals, `v-bind` props for component portals).                                                                                                 |
| `id`          | `string`                  | generated                        | Providing an existing id upserts that toast in place instead of stacking a new one.                                                                                                                 |

### `dismiss(id?)`

```ts
declare function dismiss(id?: string): string | undefined;
```

With an `id`, removes that toast (after its exit transition). **With no
argument, clears the entire stack.**

### `update(id, options)`

```ts
declare function update(id: string, options: Partial<BbToastOptions>): string;
```

Patches a live toast in place — same `BbToastOptions` fields — and restarts its
auto-dismiss countdown. Unknown ids are a safe no-op. This is the
loading-then-resolve primitive: fire with `loading: true`, then `update` into a
success or error when the work settles.

## Required app-root setup

Mount the host **once, at the app root** — `App.vue` under Vue, `app.vue` under
Nuxt, the `createInertiaApp` render root under Inertia:

```vue
<template>
	<RouterView />
	<BbToast />
</template>

<script setup lang="ts">
import { BbToast } from 'bitboss-ui';
</script>
```

## Usage examples

### Fire from an action

```vue
<template>
	<BbButton prepend:icon="lucide:copy" variant="outline" @click="copyLink">
		Copy invite link
	</BbButton>
</template>

<script setup lang="ts">
import { BbButton, useToast } from 'bitboss-ui';

const { toast } = useToast();

const copyLink = async () => {
	await navigator.clipboard.writeText('https://app.example.com/invite/9f2c');
	toast({
		title: 'Link copied',
		variant: 'success',
		position: 'bottom-center',
	});
};
</script>
```

### Loading, then resolve

```vue
<template>
	<BbButton prepend:icon="lucide:upload" variant="primary" @click="upload">
		Upload invoice
	</BbButton>
</template>

<script setup lang="ts">
import { BbButton, useToast } from 'bitboss-ui';

const { toast, update } = useToast();

const upload = async () => {
	const id = toast({ title: 'Uploading invoice.pdf…', loading: true });
	try {
		await api.documents.upload(file);
		update(id, {
			title: 'invoice.pdf uploaded',
			variant: 'success',
			icon: 'lucide:circle-check',
			loading: false,
		});
	} catch {
		update(id, {
			title: 'Upload failed',
			text: 'Check your connection and retry.',
			variant: 'destructive',
			loading: false,
		});
	}
};
</script>
```

### Action buttons — the undo pattern

`actions` takes an array of `ActionButtonConfig` (same shape as the confirm
buttons: `text`, `variant` — default `'outline'` —, `size` — default `'md'` —,
`prepend:icon`/`append:icon`/`icon`, `block`, `onClick`). While a button's
`onClick` runs it shows a spinner, siblings are disabled, and the auto-dismiss
countdown is held; the toast dismisses itself (reason `'action'`) when the
callback resolves. A rejected callback keeps the toast open and the countdown
resumes.

```ts
const removed = list.splice(index, 1)[0]; // commit immediately, no confirm
toast({
	title: `“${removed.name}” deleted`,
	duration: 5000,
	actions: [
		{
			text: 'Undo',
			onClick: () => list.splice(index, 0, removed),
		},
	],
});
```

Failure and re-purposing compose into the retry pattern: a **rejected**
handler keeps the toast open (and the countdown resumes), while a handler
that calls `update(id, ...)` **takes ownership** — instead of dismissing, the
toast morphs in place with a fresh countdown:

```ts
const id = toast({
	title: 'Sync failed',
	variant: 'destructive',
	duration: 10000,
	actions: [
		{
			text: 'Retry',
			variant: 'primary',
			onClick: async () => {
				await api.sync(); // a rejection keeps the toast open for another try
				update(id, {
					title: 'Workspace synced',
					variant: 'success',
					actions: [],
					duration: 3000,
				}); // …and an update morphs it instead of dismissing
			},
		},
		{ text: 'Ignore' },
	],
});
```

## Anti-patterns

- Don't put must-act information only in a toast — it self-dismisses. Mirror
  critical state in the page (`BbAlert` or inline copy).
- Don't mount `<BbToast />` per page or per component; exactly one host, at the
  app root, serves the whole app. Two hosts render every message twice (`BbToast`
  warns about this in DEV). The self-contained examples in this guide each mount
  their own host only because an example has no app root to mount it in.
- Don't hand-roll notification markup — buttons under the message are the
  `actions` option; for richer content use `<BbToastPortal>` (its slot receives
  `{ toast, props, close }`), and even then sparingly. A toast needing more
  than one or two actions is usually a `BbConfirm`.
- `warning`/`destructive` toasts announce assertively (`role="alert"`); use the
  calmer variants for routine confirmations.

## Related

- [BbToast](../BbToast.md) — the host component and portal mechanics.
- [BbAlert](../BbAlert.md) — inline, persistent status messages.
- [useConfirm](./useConfirm.md) — when the user must decide, not just be told.

---

<!-- dist/ai/ErrorIcon.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/ErrorIcon.md -->

# ErrorIcon

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Feedback**
- Description: Renders the reusable error-state icon glyph used in validation UIs.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/ErrorIcon.md](./source/ErrorIcon.md)

## Props

- None.

## Events

- None.

## Slots

- None.

---

<!-- dist/ai/FlatListBox.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/FlatListBox.md -->

# FlatListBox

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Selection**
- Description: Flat listbox renderer for selectable option lists.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/FlatListBox.md](./source/FlatListBox.md)

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `compact` | `boolean \| undefined` | `false` |  | Sets the listbox in a compact state. |
| `id` | `string \| undefined` |  |  | Id applied to the `role="listbox"` element itself (not the wrapper), so a combobox's `aria-controls` reference resolves to the listbox role. |
| `loading` | `boolean \| undefined` | `false` |  | Shows the listbox in a loading state. |
| `loadingText` | `string \| undefined` |  |  | Text shown while options are loading. |
| `multiple` | `boolean \| undefined` | `false` |  | Allows multiple options to be selected simultaneously. |
| `noDataText` | `string \| undefined` |  |  | Text shown when no options are available. |
| `open` | `boolean \| undefined` | `false` |  | Whether the listbox is open (visible). |
| `optionHeight` | `number \| undefined` |  |  | Fixed height (in px) for each option row. Defaults to 28px (24px compact; 44px / 36px on mobile viewports). An explicit value wins on every viewport. |
| `options` | `Option<Item>[]` |  | yes | List of options to display. |
| `transitionDuration` | `number \| undefined` | `250` |  | Duration of open/close transition in milliseconds. |

## Events

- `focused:change` — `(e: "focused:change", id: string \| undefined): void` — Emitted when the keyboard-focused option changes.
- `option:selected` — `(e: "option:selected", option: Option): void` — Emitted when an option is selected by the user.
- `option:unselected` — `(e: "option:unselected", option: Option): void` — Emitted when a previously selected option is deselected.

## Slots

- `loading` — scope: `object` — Content shown while items are loading (replaces the default loading text).
- `no-data` — scope: `object` — Content shown when no options are available (replaces the default "no data" text).
- `option` — scope: `FlatListBoxOptionSlotProps<Item>` — Replaces the default rendering of each option row.
- `options:append` — scope: `object` — Content appended inside the options list, after the last option.
- `options:prepend` — scope: `object` — Content prepended inside the options list, before the first option.

---

<!-- dist/ai/GroupedListBox.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/GroupedListBox.md -->

# GroupedListBox

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Selection**
- Description: Grouped listbox renderer for categorized options.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/GroupedListBox.md](./source/GroupedListBox.md)

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `compact` | `boolean \| undefined` | `false` |  | Sets the listbox in a compact state. |
| `groups` | `GroupedOptions[]` |  | yes | List of option groups to display. |
| `headerHeight` | `number \| undefined` |  |  | Height of group headers (px). Defaults to 32px (24px compact; 36px / 32px on mobile viewports). An explicit value wins on every viewport. |
| `id` | `string \| undefined` |  |  | Id applied to the `role="listbox"` element itself (not the wrapper), so a combobox's `aria-controls` reference resolves to the listbox role. |
| `loading` | `boolean \| undefined` | `false` |  | Shows the listbox in a loading state. |
| `loadingText` | `string \| undefined` |  |  | Text shown while options are loading. |
| `multiple` | `boolean \| undefined` | `false` |  | Allows multiple options to be selected simultaneously. |
| `noDataText` | `string \| undefined` |  |  | Text shown when no options are available. |
| `open` | `boolean \| undefined` | `false` |  | Whether the listbox is open (visible). |
| `optionHeight` | `number \| undefined` |  |  | Fixed height (in px) for each option row. Defaults to 28px (24px compact; 44px / 36px on mobile viewports). An explicit value wins on every viewport. |
| `transitionDuration` | `number \| undefined` | `250` |  | Duration of open/close transition in milliseconds. |

## Events

- `focused:change` — `(e: "focused:change", id: string \| undefined): void` — Emitted when the keyboard-focused option changes.
- `option:selected` — `(e: "option:selected", option: Option): void` — Emitted when an option is selected by the user.
- `option:unselected` — `(e: "option:unselected", option: Option): void` — Emitted when a previously selected option is deselected.

## Slots

- `group` — scope: `GroupedListBoxGroupSlotProps<Item>` — Replaces the default group header rendered above each group of options.
- `loading` — scope: `object` — Content shown while items are loading (replaces the default loading text).
- `no-data` — scope: `object` — Content shown when no options are available (replaces the default "no data" text).
- `option` — scope: `GroupedListBoxOptionSlotProps<Item>` — Replaces the default rendering of each option row within a group.
- `options:append` — scope: `object` — Content appended inside the options list, after the last group.
- `options:prepend` — scope: `object` — Content prepended inside the options list, before the first group.

---

<!-- dist/ai/guides/agent-contract.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/agent-contract.md -->

# Agent Contract

Use this contract before generating any UI code with `bitboss-ui`.

## Default API Boundary

1. Prefer `Bb*` components in consumer-facing code.
2. Treat low-level primitives (`Base*`, `BbBase*`, `Common*`, listbox internals) as reference-only — **except `BbBaseButton`**, which is a first-class consumer component: the unstyled navigable primitive for any clickable surface (cards, rows, custom links) that isn't a variant-first `BbButton`.
3. Use the other reference-only components only when the user explicitly asks for internal composition details.

## Setup-First Rule

Before writing component usage code, verify:

- `bitboss-ui` is installed;
- the build plugin is configured (`bitboss-ui/vite` in Vite/Inertia apps, `bitboss-ui/nuxt` in Nuxt apps) — it serves the `virtual:bitboss-ui/icons` and `virtual:bitboss-ui/config` modules;
- the runtime plugin is installed (`app.use(bitbossUiPlugin)`; the Nuxt module does this for you), which injects `bitboss-ui/styles.css` unless `injectStyles: false`.
- **the plugin's `locale` option is set, if the app is not Italian.** It
  **defaults to `'it'`** — every built-in string (date formats and per-segment
  labels on the date/time pickers, select-all text, `useConfirm`'s OK/Annulla
  labels, and more) ships Italian until `locale` is set explicitly. There is
  no build-time warning for an unset `locale`, only for an unknown one, so
  this ships silently. Set `locale: 'en'` (or the target locale) in
  `vite.config.*` / `nuxt.config.*`, and if the app switches locale at
  runtime, list every locale it can switch to in `enabledLocales` up front —
  narrowing `locale` alone narrows the bundle and makes any other locale a
  compile error at `useBbConfig().setConfig({ locale })`. Details:
  [Installation and Plugin Setup](./installation-and-plugin-setup.md) §
  `locale`.

If setup is missing, provide setup code first ([Installation and Plugin Setup](./installation-and-plugin-setup.md)), then component examples.

## Knowledge Base: Router First, Then Curated Guides

Read the installed package knowledge base before recommending components:

1. **`dist/ai/guides/ai-router.md`** — tiny hop map (which file to open next).
2. **`dist/ai/index.md`** — full catalogue only when the router is not enough.

Every component doc (`dist/ai/<Name>.md`) **leads with a "Usage & Guidelines" section** — a curated, runtime-tested guide with live examples. Read it before the raw props/events/slots tables, and prefer its idioms over anything you would infer from the API surface alone. If a guide shows one way to do something, that is the idiomatic way.

Consumer projects should run `npx bitboss-ui ai-init` once so AGENTS.md / Cursor / Copilot / Claude / Windsurf all point at this corpus.

## Navigation Rule

Offload navigation to the component. The navigation engine lives in `BbBaseButton`, the primitive every button wraps — so `BbButton`, `BbDropdownButton`, `BbBaseButton` itself, and every item-driven surface built on the same core (dropdown items, breadcrumb items, tabs items, pagination in `navigation` mode) all navigate by themselves. Push _as much navigation as possible_ onto this surface — any click whose result is a destination belongs here, not in an `@click` handler:

- `href` — renders an anchor; in an Inertia app it becomes an Inertia visit and accepts `method`, `data`, `headers`, `preserveScroll`, `replace`, …;
- `to` — vue-router `RouteLocationRaw`, rendered as a router link (tabs items use `href`; pagination `navigation` builds per-page `to`/`href` links itself).

**NEVER** write `@click="router.push(...)"` (or `window.location = ...`) for something the component can navigate to itself. Click handlers are for actions; destinations go in `href`/`to`.

## Inline Links & Identity Cells Rule

`BbButton` is **not** an inline link. It is a full button with a box — height and
horizontal padding from the size scale — and `variant="link"` only **recolors**
that box (it does not remove the padding or let it flow inline). Dropped into
running text, a table cell, or a property grid, that button box **breaks the line
height and text flow** around it.

The inline link/button is **`BbBaseButton`**: zero chrome, the same
`href`/`to`/Inertia navigation engine, and its look is **owned by the project's
CSS** — e.g. a `.plain-link` class that adds only an underline. Use it for:

- a clickable **record-identity cell** (a row's name/title column) that must
  truncate and flow inline at the cell's width;
- any **in-text link** inside a table, peek panel, or property grid;
- a link whose appearance is a plain text link, not a button.

Rule: **inline text link → `BbBaseButton` + your own link class; never `BbButton`
(including `variant="link"`).** Reserve `BbButton variant="link"` for a
standalone, button-spaced navigation control sitting among other buttons ("See
pricing", "Forgot password?"). See [BbButton](../BbButton.md) § Choosing a
variant and [design-language](./design-language.md) § the `.plain-link` helper.

## Consult-Stack Rule (records listings)

A listing screen with a peek sidebar is for **consulting** — invoice → its
account → another invoice on that account → back — without leaving the list.
The shell's stack exists for exactly that, and it is opt-in, so agents keep
shipping listings where every row opens one reset peek and every related name
inside it is dead text. Each follow-up question then costs a full-page
navigation, which is the thing the shell was supposed to remove.

Rule: **on any records/approvals/ownership listing, related names are
navigable and the peek stacks.** Concretely:

1. `PeekItem` is one discriminated union covering every related type the rows
   and the peeks expose — not a second shell per type.
2. Row click → `peek(item)` (fresh top-level). Related name → `stackItem(item)`
   (drills, keeps the back arrow). Prefer these named intents over
   `push(item, true)`, whose boolean is what people get backwards.
3. Every related name is a `BbBaseButton` + `.plain-link` (see the rule above),
   in table cells **and** inside peek bodies.
4. `#sidebar-title` follows the top of the stack; the row highlight follows its
   root, so drilling does not un-highlight the row the consult started from.

See [page-shell](./page-shell.md) § The consult stack and the records-workspace
recipe's conformance checklist.

## Item-Driven Components Rule

For components accepting `items`:

- prefer declarative mapping with `item-text` and `item-value`;
- use `dependencies` and `deps-debounce-time` for tied fields;
- use `enforce-coherence` instead of custom watchers for stale model cleanup.

## Icons Rule

External-provider-first: prefer iconify provider icons — default set `lucide:*` — sourced from `@iconify-json/*` packages the consumer installs separately (`npm i -D @iconify-json/lucide`). Use `local:*` SVGs only for brand-specific art placed in the configured `iconDir`. Only reference icons from installed providers or existing local files — **never invent icon names**. Full workflow: [Icons Policy](./icons-policy.md).

## Variants Rule

Unlike icons, variants are **not** a fixed vocabulary you must stay inside. The
shipped names (`primary`, `secondary`, `destructive`, `outline`, …) are the
**floor**; the registries are open on purpose so an app can add the tones its
design needs. When a design calls for a colour the library does not ship — soft
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` (`bitboss-ui/vite` or `bitboss-ui/nuxt`).
   The plugin regenerates the typed registry, so the name type-checks.
2. **Style the class** — `.bb-badge.bb-badge--<name>`, `.bb-button--<name>`, … —
   in a project stylesheet loaded **after** `bitboss-ui/styles.css`. The library
   ships no CSS for names it does not own.

Half the job is a bug in both directions: a registered name with no CSS renders
an unstyled pill (the original "warning badge" hallucination), and CSS with no
registration fails `vue-tsc`. Equally, **do not downgrade the design** — falling
back to `secondary`/`outline` because a status palette "isn't available" is the
wrong fix; registering it is a two-file change you are expected to make.

Never write a variant name that is neither shipped nor registered. Canonical
soft status palette (accents, the shared treatment, and why the selectors are
doubled): [Design Language](./design-language.md) § Getting soft semantic badges.
Where the option goes: [Installation and Plugin Setup](./installation-and-plugin-setup.md).

## Overlay Open-State Rule

Overlay visibility is controlled by the component's **primary `v-model`** — never a separate `v-model:open`. The standalone overlays (`BbDialog`, `BbOffCanvas`, `BbPopover`, `BbTooltip`) expose a boolean `v-model` for open state. The popover-embedded surfaces (`BbDropdown`, `BbSelectPopover`, `BbColorPalette`) keep open state **internal** — drive them through their trigger/activator, not a bound open flag. There is no `v-model:open` anywhere in the library, by design; do not reach for one.

These overlays also return focus to their trigger element on close, by documented default — a consumer `@focus`-reopen handler on that trigger will fight the restore and can loop.

## Global Host Rule

`useToast()` and `useConfirm()` write to **module-level singleton state**, not to a component instance. `<BbToast />` and `<BbConfirm />` are the only things that render that state, and each mounted host renders _all_ of it.

**Mount exactly one `<BbToast />` and one `<BbConfirm />` for the whole application, at the app root** — `App.vue` under Vue, `app.vue` under Nuxt, the `createInertiaApp` render root under Inertia. Never one per page, per route, per layout branch or per component; a page that calls `toast()` or `confirm()` mounts nothing.

- **Zero hosts** — `toast(...)` enqueues silently and the message never expires (the dismiss timer lives inside the host); `await confirm(...)` never settles, so the caller hangs. Neither throws.
- **Two hosts** — every toast and every dialog renders once per host: duplicated DOM, duplicated `role="status"` live regions, duplicated focus traps. `BbToast` warns in DEV; `BbConfirm` does not warn at all.

Standalone examples in this repo (`src/components/*/examples/*.vue`, stories, dev showcases) mount a host inline **because each one is a self-contained root with no application around it**. That is a property of the example harness, not a pattern to copy — in a real app the host is already mounted at the root, and the page must not mount a second one.

## Boolean Prop Defaults Rule

Boolean props default to `false` so the bare `<Comp foo>` shorthand turns the feature **on**. A few props deliberately default to `true` for cross-library keyword clarity — pass `:prop="false"` to opt out:

- `multiple` on `BbTable`, `BbCheckboxGroup`, `BbSwitchGroup` — multi-select is the expected default; `:multiple="false"` forces single-select.
- `selectable` on the option components (`BbSelect`, `BbSelectPopover`, `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`) — options are selectable by default; pass a predicate or `false` to restrict. **Not `BbTable`**: there `selectable` is unset by default and is what renders the selection column at all, so leaving it off means "no checkboxes", not "every row selectable".

These are the only intentional default-`true` booleans; anywhere else, `true` default is a bug (`check-api` flags it).

**Arrows are tooltip-only in v3.** `hideArrow` / `showArrow` / `arrowPadding` were removed from `BbPopover`, `BbSelectPopover`, `BbColorPalette`, and `BbDropdown` (leftover bindings land silently in `$attrs`). Only `BbTooltip` keeps `hideArrow` (default `false` — arrow shown). See [bb-popover.md](./migration/components/bb-popover.md).

## Testing Against bitboss-ui

Two DOM realities of this library trip up headless-browser tests written
against otherwise-correct selectors:

- **Closed floating panels stay in the DOM, not hidden.** Every floating
  panel — `BbPopover`, `BbDropdown`, `BbSelectPopover`, and the select family
  built on it (`BbSelect`) — stays mounted and off-screen when closed
  (`position: fixed; top: -2000px; width: max-content`) rather than being
  removed or `display: none`d — a closed panel is parked, not absent. Two
  consequences: (1) a bare text/role query can match content inside a closed
  panel elsewhere on the page — scope queries to a known open root; (2)
  because these panels are `position: fixed` and can be as wide as their
  longest option, they inflate `document.documentElement.scrollWidth` by
  however wide the _widest ever rendered_ panel is, with zero visible effect
  on the page. **Measure page overflow with `document.body.scrollWidth`,
  never `document.documentElement.scrollWidth`.**
  **Which closed-state signal to await differs by component.**
  `BbPopover` and `BbDropdown` wrap their whole panel in `inert` when closed —
  wait for `.bb-popover__panel[inert]` / `.bb-dropdown__panel[inert]` (not
  `hidden`/detached) to assert closed, and scope open-panel queries to
  `:not([inert])`. The select engine (`BbSelectPopover`, and therefore
  `BbSelect`, which is built on it — the two behave identically) never puts
  `inert` on its listbox; only its optional header/footer chrome goes `inert`.
  Its listbox closes via `opacity: 0` + `grid-template-rows: 0fr` on
  `.bb-listbox__outer-container` (the `bb-listbox--open` class drops). Don't
  wait for `[inert]` there — it never comes; assert on the collapsed state
  (`grid-template-rows`/`opacity`/`bb-listbox--open`) or on option visibility
  instead.
  **`BbDialog` and `BbOffCanvas` are the trap: they DO carry `inert`, but it
  does not mean "closed".** Both render `:inert="(!model && !isVisible) || isCovered"`,
  so a panel is ALSO inert while it is open and merely **covered by another
  modal stacked on top of it** — assert closed with `[inert]` there and the test
  starts passing for the wrong reason the moment two overlays stack. They are
  native `<dialog>` elements driven by `showModal()`/`close()`, so use the
  element's own `open` property (or the `bb-dialog--open` class) as the
  closed-state signal. Mind the transition window too: `inert` only lands once
  `isVisible` has gone false as well, which is after the closing animation, not
  at the click.
- **Segmented date/time inputs are not one field.** `BbDatePickerInput` /
  `BbTimePickerInput` render one native input per segment (day/month/year,
  hour/minute/second/period); the field's own `label` is wired via `for` to
  only the first segment, and every segment additionally carries its own,
  localized `aria-label` ("Month"/"Day"/"Year", or "Mese"/"Giorno"/"Anno"
  under `locale: 'it'`), which wins the accessible-name computation. So
  `getByLabel('<the field's label>')` matches nothing — query each segment by
  its own accessible name (`getByLabel('Month')`, etc., which is
  locale-coupled: it breaks if the app under test switches locale) or by its
  role/position within the field. `aria-valuetext` is **not** emitted by the
  date/time picker family — that signal exists only on `BbSelectPopover`'s
  activator; don't expect it on a segmented input.

## Rebuild Check (before you ship a screen)

Re-read what you hand-wrote and ask whether the library already ships it. This is
the failure with no error message: the component exists, is exported, is in the
picker, and the picker is open — but a picker gets opened to answer _archetype_
questions ("is there a Calendar?"), never "am I about to reinvent something
small?". A pilot builder read the picker four times and hand-rolled an avatar
twice.

Symptoms that mean stop: an `<img>` with an initials/icon fallback →
`BbAvatar` (**circle-only** — a rounded-square avatar really is yours to build);
a hand-written spin animation → `BbSpinner`; a tinted `<span>` pill standing for
a status → `BbBadge` with a registered `soft-*` variant. Full symptom index:
[Component Picker](./component-picker.md) § Am I about to rebuild one of ours?

`npx bitboss-ui check` prints the avatar and spinner shapes
as **advisory hints** — never a build failure, because a round `<img>` is
sometimes a logo — so that much backstops itself on files it scans. The badge
case is not decidable from markup and has no hint.

## Safety Checklist

- [ ] Started from the AI Router (or already knows the next hop).
- [ ] Recommends `Bb*` components by default.
- [ ] Uses only existing props/events/slots from library types.
- [ ] Read the component's "Usage & Guidelines" section before writing usage code.
- [ ] Navigation goes through `href`/`to` on buttons and items — no `router.push` click handlers for plain destinations.
- [ ] Uses only icons from installed `@iconify-json/*` providers or existing `local:*` files.
- [ ] Avoids reference-only imports unless explicitly requested.
- [ ] Uses declarative coherence/dependencies before manual watchers.
- [ ] Mounts exactly one `<BbToast />` and one `<BbConfirm />` host, at the app root — never inside a page or component.
- [ ] Confirmed the plugin's `locale` is set explicitly if the app isn't Italian (default is `'it'`) — see Setup-First Rule.
- [ ] Ran the Rebuild Check over the hand-written markup — nothing reimplements `BbAvatar`, `BbSpinner` or `BbBadge`.

---

<!-- dist/ai/guides/ai-router.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/ai-router.md -->

# AI Router

Read this file first. Open **at most one** deeper file per hop. Do not load
every recipe or every component contract into context.

Knowledge base root (installed package):
`node_modules/bitboss-ui/dist/ai/`

Package export entry: `bitboss-ui/ai` → `dist/ai/index.md`.
Subpaths: `bitboss-ui/ai/components.json`, `bitboss-ui/ai/guides/…`, etc.

**Not installed, or can only fetch URLs?** The same files are served from the
published package at `https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/…`.
If you can make only one request, fetch
[`…@beta/dist/llms-medium.txt`](https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/llms-medium.txt)
— this router plus the agent contract, setup, component picker, design language
and the full component catalogue, in ~110 KB.

---

## Mandatory order (every UI task)

1. **[Agent contract](./agent-contract.md)** — hard rules (Bb\* boundary,
   setup-first, `href`/`to` navigation, icons, coherence).
2. **Setup?** If the project may not have the plugin yet →
   [Installation & Plugin Setup](./installation-and-plugin-setup.md). **Set
   `locale` explicitly if the app is not Italian** — the plugin defaults to
   `'it'` and there is no build-time warning for leaving it unset.
3. **Choose intent:**
   - Whole page / flow → hop to **Recipes** below (one platform file only).
   - Single control → [Component picker](./component-picker.md), then open
     **one** `../<ComponentName>.md` contract (Usage & Guidelines first).
4. **Never invent props.** Confirm names in that contract or in
   [`../components.json`](../components.json).

---

## Recipes (page-level — pick one platform)

Folders: `../recipes/vue/`, `../recipes/nuxt/`, `../recipes/inertia/`.

Same page shapes on each platform; only the data/mutation layer differs.

| Intent                               | Recipe file (kebab)                       |
| ------------------------------------ | ----------------------------------------- |
| Filterable listing + bulk/peek       | `records-workspace.md`                    |
| Create/edit form                     | `record-form.md`                          |
| Inline-edit table / backlog          | `inline-edit-workspace.md`                |
| Hierarchy drill-down (nested tables) | `ownership-atlas.md` (Inertia only today) |
| Approvals / triage inbox             | `approvals-inbox.md`                      |
| Uploads + editable queue             | `upload-center.md`                        |
| Multi-step wizard                    | `wizard-form.md`                          |
| Onboarding checklist                 | `onboarding.md`                           |

No recipe for detail-with-tabs, settings, dashboards, or profile pages —
compose those from the closest listing/form recipe plus the guides
(page shell, tabs, inline-edit playbook) instead of inventing a new shape.

---

## Playbooks (only when the pattern applies)

| Need                                   | Guide                                                 |
| -------------------------------------- | ----------------------------------------------------- |
| 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` / 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)               |
| Upgrading from bitboss-ui 2.x          | [migration/v2-to-v3](./migration/v2-to-v3.md)         |

---

## Full catalogue (last resort)

- [Component index](../index.md) — every consumer + reference-only entry
- [components.json](../components.json) — machine-readable API for validation
- Composables: `../composables/` (`useToast`, `useConfirm`, table/tabs context, …)

Reference-only (`BbBase*` form primitives, listbox internals, …) — **do not
import in consumer apps** unless the user explicitly asks for internals.
Exception documented in the agent contract: **`BbBaseButton` is consumer API**.

---

## Consumer kickstart

In the app repo (once), after installing `bitboss-ui`:

```bash
npx bitboss-ui ai-init
# optional: also register the MCP server (its peers are not installed with the library)
npm i -D @modelcontextprotocol/sdk zod
npx bitboss-ui ai-init --mcp
```

Writes harness-agnostic pointers (`AGENTS.md`) plus Cursor / Copilot / Claude /
Windsurf rules so agents find this router without being told.

After writing Bb\* markup, validate against the installed contract:

```bash
npx bitboss-ui check
# or: npx bitboss-ui check 'src/**/*.{vue,md}' --json
```

Optional MCP (`npx bitboss-ui mcp`): search/get components, list/get recipes,
validate snippets — version-matched to the installed package.
Needs the optional peers `@modelcontextprotocol/sdk` + `zod` (~12 MB, used by
nothing else); the command names them if they are missing.

---

<!-- dist/ai/guides/app-layout.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/app-layout.md -->

# App Layout

The chrome around **every** page: a collapsible left navigation sidebar, the
main region where pages (each wrapped in the
[Page Shell](./page-shell.md)) render, and a fat footer. App code, not a
`bitboss-ui` export — copy once into your project
(conventionally `src/components/layout/`).

**This owns the page's one `<main>` landmark** (`.layout__page` below). The
[Page Shell](./page-shell.md)'s own content wrapper is a plain `<div>` —
deliberately, since nesting a second `<main>` inside this one is invalid HTML
and gives assistive tech two "main content" regions with no way to tell them
apart. Compose the two exactly as shown here and you get exactly one. That
`<main>` is also what the skip link jumps to, so it carries the `id`.

It also owns two CSS hooks other layout pieces rely on:

- `.layout--sidebar-expanded` on the root while the nav is expanded;
- `--sidebar-max-w` — the expanded nav width.

Primary navigation lives in this sidebar, so there is **one** top bar: the
[Page Shell](./page-shell.md) topbar, flush with the viewport (`top: 0`).
**Keep it that way — one topbar per page.** If your product has app-wide
utilities (global search, a user menu, notifications), put them **in** that
single PageShell topbar; do **not** stack a second sticky brand/utility bar
above it. Two stacked top bars double the chrome and burn vertical space for no
gain. (The `--app-bar-h` hook exists only as an escape hatch for a layout that
truly must keep a separate app bar; the default and the recommendation is the
single bar — see [Page Shell](./page-shell.md) § One topbar.)

The page background is left to the theme's UA canvas and flips with the theme
automatically — this layout paints no page background of its own. If you want a
tinted page canvas, wire a **dark-aware** one yourself; see
[Design Tokens § The page canvas](./design-tokens.md).

## The component

```vue
<!-- src/components/layout/AppLayout.vue -->
<template>
	<div class="layout" :class="{ 'layout--sidebar-expanded': expanded }">
		<!-- First focusable thing on the page; hidden until it takes focus. -->
		<a class="layout__skip" href="#main-content">Skip to content</a>

		<aside aria-label="Main navigation" class="layout__nav">
			<div class="layout__nav-head">
				<span v-if="expanded" class="layout__brand">Acme Billing</span>
				<BbButton
					:aria-label="expanded ? 'Collapse navigation' : 'Expand navigation'"
					:icon="
						expanded ? 'lucide:panel-left-close' : 'lucide:panel-left-open'
					"
					size="sm"
					variant="ghost"
					@click="expanded = !expanded"
				/>
			</div>

			<nav class="layout__nav-items">
				<BbBaseButton
					v-for="item in navigation"
					:key="item.href"
					active-class="layout__nav-item--active"
					class="layout__nav-item"
					:href="item.href"
				>
					<BbIcon :icon="item.icon" size="sm" />
					<span v-if="expanded">{{ item.label }}</span>
				</BbBaseButton>
			</nav>
		</aside>

		<div class="layout__main">
			<!-- tabindex="-1" is what makes the skip link actually move focus. -->
			<main id="main-content" class="layout__page" tabindex="-1">
				<!-- Every page renders here, wrapped in its own PageShell. -->
				<slot />
			</main>

			<footer class="layout__footer">
				<div class="layout__footer-cols">
					<div
						v-for="column in footer"
						:key="column.title"
						class="layout__footer-col"
					>
						<span class="layout__footer-title">{{ column.title }}</span>
						<a
							v-for="link in column.links"
							:key="link.href"
							class="layout__footer-link"
							:href="link.href"
						>
							{{ link.label }}
						</a>
					</div>
				</div>
				<div class="layout__footer-meta">
					<span>© 2026 Acme Inc.</span>
					<span>Status: all systems operational</span>
					<span>v2.14.3</span>
				</div>
			</footer>
		</div>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbBaseButton, BbButton, BbIcon } from 'bitboss-ui';

const expanded = ref(true);

const navigation = [
	{ label: 'Dashboard', href: '/dashboard', icon: 'lucide:layout-dashboard' },
	{ label: 'Invoices', href: '/invoices', icon: 'lucide:receipt' },
	{ label: 'Customers', href: '/customers', icon: 'lucide:users' },
	{ label: 'Approvals', href: '/approvals', icon: 'lucide:check-circle-2' },
	{ label: 'Reports', href: '/reports', icon: 'lucide:bar-chart-3' },
	{ label: 'Settings', href: '/settings', icon: 'lucide:settings' },
];

const footer = [
	{
		title: 'Product',
		links: [
			{ label: 'Changelog', href: '/changelog' },
			{ label: 'Roadmap', href: '/roadmap' },
			{ label: 'Pricing', href: '/pricing' },
		],
	},
	{
		title: 'Resources',
		links: [
			{ label: 'Documentation', href: '/docs' },
			{ label: 'API reference', href: '/docs/api' },
			{ label: 'Status', href: '/status' },
		],
	},
	{
		title: 'Company',
		links: [
			{ label: 'About', href: '/about' },
			{ label: 'Support', href: '/support' },
			{ label: 'Legal', href: '/legal' },
		],
	},
];
</script>

<style scoped>
.layout {
	--sidebar-max-w: 240px;
	--sidebar-collapsed-w: 56px;
	--layout-duration: 250ms;

	display: flex;
	min-height: 100dvh;
}

/* ── Skip link ────────────────────────────────────────────────────────── */
.layout__skip {
	background: var(--bb-panel);
	border: 1px solid var(--bb-border);
	border-radius: var(--bb-radius);
	color: var(--bb-text);
	font-size: 0.875rem;
	left: 8px;
	padding: 6px 12px;
	position: fixed;
	text-decoration: none;
	top: 8px;
	/* Off-screen, not display:none — it must stay in the tab order. */
	transform: translateY(calc(-100% - 16px));
	transition: transform var(--layout-duration);
	z-index: 100;
}

.layout__skip:focus {
	transform: translateY(0);
}

/* ── Left nav ─────────────────────────────────────────────────────────── */
.layout__nav {
	background: var(--bb-panel);
	border-right: 1px solid var(--bb-border);
	display: flex;
	flex-direction: column;
	flex-shrink: 0;
	gap: 8px;
	padding: 8px;
	position: sticky;
	top: 0;
	height: 100dvh;
	transition: width var(--layout-duration);
	width: var(--sidebar-collapsed-w);
}

.layout--sidebar-expanded .layout__nav {
	width: var(--sidebar-max-w);
}

.layout__nav-head {
	align-items: center;
	display: flex;
	justify-content: space-between;
	min-height: 28px;
}

.layout__brand {
	font-size: 0.875rem;
	font-weight: 600;
	padding-left: 8px;
	white-space: nowrap;
}

.layout__nav-items {
	display: flex;
	flex-direction: column;
	gap: 2px;
}

.layout__nav-item {
	align-items: center;
	border-radius: var(--bb-radius);
	color: var(--bb-text);
	display: flex;
	font-size: 0.875rem;
	gap: 8px;
	min-height: 28px;
	padding: 0 8px;
	white-space: nowrap;
}

.layout__nav-item:hover {
	background: color-mix(in oklab, var(--bb-text) 6%, transparent);
}

.layout__nav-item--active {
	background: color-mix(in oklab, var(--bb-text) 9%, transparent);
	font-weight: 500;
}

/* ── Main + footer ────────────────────────────────────────────────────── */
.layout__main {
	display: flex;
	flex: 1 1 auto;
	flex-direction: column;
	min-width: 0;
}

.layout__page {
	flex: 1 1 auto;
	min-width: 0;
}

.layout__footer {
	background: var(--bb-panel);
	border-top: 1px solid var(--bb-border);
	display: flex;
	flex-direction: column;
	gap: 24px;
	margin-top: 48px;
	padding: 32px 32px 24px;
}

.layout__footer-cols {
	display: grid;
	gap: 32px;
	grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
	max-width: 720px;
}

.layout__footer-col {
	display: flex;
	flex-direction: column;
	gap: 6px;
}

.layout__footer-title {
	font-size: 0.75rem;
	font-weight: 600;
	letter-spacing: 0.04em;
	text-transform: uppercase;
}

.layout__footer-link {
	color: var(--bb-text);
	font-size: 0.8125rem;
	opacity: 0.7;
	text-decoration: none;
}

.layout__footer-link:hover {
	opacity: 1;
}

.layout__footer-meta {
	border-top: 1px solid var(--bb-border);
	display: flex;
	font-size: 0.75rem;
	gap: 16px;
	opacity: 0.6;
	padding-top: 16px;
}
</style>
```

## Design notes

- **Pages don't know the layout.** Each page wraps itself in the
  [Page Shell](./page-shell.md) and renders into the default slot; the
  layout never reaches into pages and pages never style `.layout__*`.
- **The nav is real navigation** — `BbBaseButton` with the platform's
  link prop (`to` under vue-router/Nuxt, `href` under Inertia) and
  an active-state class, which resolves on every platform. Never
  `@click` + router. **`active-class` matches on a path prefix** (`/invoices`
  stays active on `/invoices/42`); **`exact-active-class` matches only the
  exact path.** Use `exact-active-class` for any item whose target is `/` or
  another route root — with `active-class`, `/` is a prefix of every route,
  so that item paints as active on every page. The example above is safe
  because `Dashboard` targets `/dashboard`, not `/`; if your app makes the
  dashboard the root route, switch it to `exact-active-class`. The choice is
  not only visual: `BbBaseButton` emits `aria-current` (default `page`, tuned
  with `aria-current-value`) **only** on an exact match, so a prefix-active
  item is painted but carries no programmatic signal — see
  [BbBaseButton](../BbBaseButton.md) § Active state.
- **Skip to content, before the nav.** `.layout__skip` is the first focusable
  element in the DOM and is moved off-screen until it takes focus. A dozen nav
  destinations plus the collapse toggle is a dozen-plus Tab stops a keyboard or
  switch user would otherwise cross on **every** page before reaching content —
  WCAG 2.4.1 Bypass Blocks. It targets the `<main>`'s `id`, and `tabindex="-1"`
  on that `<main>` is what makes the jump move focus rather than only scroll.
  Hide it with a transform (or clip), never `display: none` /
  `visibility: hidden` / `hidden` — those drop it out of the tab order, and an
  unreachable skip link is no skip link.
- **Icon-only when collapsed** stays accessible: the label span disappears
  visually but `BbBaseButton` keeps the accessible name via the item —
  add `:aria-label="item.label"` if you strip the text node entirely.
- **The global hosts live above this, at the app root.** Mount exactly one
  `<BbToast />` and one `<BbConfirm />` in `App.vue` / `app.vue` / the
  `createInertiaApp` render root — a sibling of the router outlet, not inside
  this layout and never inside a page. Every recipe lists them as a
  prerequisite and nothing else provides them; see
  [Agent Contract § Global Host Rule](./agent-contract.md).
- **The CSS hooks are a contract.** `.layout--sidebar-expanded` and
  `--sidebar-max-w` size the nav; rename them in one place only.
  `--app-bar-h` is a third hook, read by [Page Shell](./page-shell.md)'s
  topbar — this AppLayout doesn't set it (see above), so PageShell's own
  fallback (`0`) is what actually applies here.
- The footer is intentionally _fat_ — link columns plus a meta row
  (copyright, status, version). Products with thin footers can trim the
  columns; keep the meta row.

## Related

- [Page Shell](./page-shell.md) — the per-page chrome inside this layout.
- [Floating Bottom Panel](./floating-bottom-panel.md) — the selection
  action bar that floats over this shell.
- [Recipes](../recipes/vue/records-workspace.md) — every recipe page
  assumes this chrome exists.

---

<!-- dist/ai/guides/coherence-playbook.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/coherence-playbook.md -->

# Coherence Playbook

Companions: [Options and Items](./options-items-playbook.md) (value identity — coherence matches by the same value hash), [Fetch Items](./fetch-items-playbook.md) (provider call signatures the reconciliation flows use).

## What coherence means

A component is **coherent** when every entry in `modelValue` resolves to an option the user could see and pick:

- `items` array → every model entry hash-matches an item's value;
- `items` function → every model entry hash-matches an item the function has returned (across fetch iterations — on `BbSelect`/`BbSelectPopover`, options **stashed** via the `stash` prop count too);
- an **empty selection is always coherent**: `[]` in multiple mode, `null`/`undefined` in single mode.

## Default strategy

Declare it; don't hand-roll it:

- `dependencies` — reactive values that re-run the items provider on change;
- `deps-debounce-time` — debounce for those reloads (default `0`);
- `enforce-coherence` — after a reload, strip model entries that no longer resolve.

Manual watcher cleanup is a last resort (see below).

## Where it exists

| Component                                            | `dependencies`                               | `enforce-coherence`                                                                                                 |
| ---------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `BbSelect` / `BbSelectPopover`                       | yes                                          | yes — over a non-empty model it also forces the first load (see Laziness)                                           |
| `BbCheckboxGroup` / `BbRadioGroup` / `BbSwitchGroup` | yes                                          | yes                                                                                                                 |
| `BbDropdown` pipeline groups                         | per-group `dependencies` in the group config | per-group `enforceCoherence`, or the dropdown-level `enforce-coherence` prop as the default                         |
| `BbTable`                                            | yes                                          | yes — prunes every row-keyed model after each load; **never combine it with pagination fed through `dependencies`** |

## What enforcement emits

When `enforce-coherence` is on and a reload leaves the model incoherent, the component emits `update:modelValue` with the coherent remainder:

- multiple → the filtered array (coherent entries survive);
- single → `null` (an empty selection is the only coherent fallback);
- dropdown groups → selection keys that no longer map to a loaded option are dropped and surface through the companion's `v-model`. Pruning **never runs against an empty or still-loading item set**, so a slow fetch can't wipe a valid selection.

## Reconciliation flows (verified)

- **`dependencies` (or the `items` prop itself) change** → re-run the provider (debounced `deps-debounce-time`), then enforce. Comparison is value-hash based, not reference based.
- **`modelValue` changes externally** (selects and groups) → if the new value is incoherent, re-run the provider defensively (debounced `model-value-debounce-time`), then enforce. Coherent updates trigger no fetch.
- **First load** → the initial load is a load like any other: enforcement runs on it, so a seeded-but-invalid model is pruned as soon as options exist, not only when something later changes.
- **Laziness, and what overrides it**: nothing above runs before the component has loaded once. Two things guarantee that first load without any `prefill` prop: **array `items`** (no request to defer, so never lazy) and **`enforce-coherence` over a non-empty model** (validating a value is impossible without options, so it loads). An empty model stays lazy — empty is always coherent, so there is nothing to check. Otherwise an untouched `prefill: 'interaction'` select ignores dependency changes until the first interaction; group/table dependency watchers wait for the mount load; a never-opened dropdown group never fetches or prunes. Don't "fix" the quiet period with eager watchers.
- **The cost of enforcement**: `enforce-coherence` opts each _instance_ into its own load. One field, one request; N provider-backed instances, N requests. For many instances (a popover per table row) resolve the options **once at page level** and pass the same array down — then N instances cost zero requests and every one resolves on mount.

## Canonical pattern for tied fields

Region constrains city; changing region reloads the city options and clears a city that no longer fits:

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { BbSelect } from 'bitboss-ui';

const region = ref<string | null>(null);
const city = ref<string | null>(null);

const loadRegions = (): Promise<Region[]> => api.regions.list();

const loadCities = async (
	query: string,
	prefill: boolean,
	modelValue: any // runtime shape follows the v-model: a single value here
): Promise<City[]> => {
	// Component-initiated call: resolve the current selection under the new region.
	if (prefill) {
		return api.cities.list({
			regionId: region.value,
			selectedIds: modelValue ? [modelValue] : [],
		});
	}
	if (!query.trim()) return []; // project-defined idle behavior
	return api.cities.search({ query, regionId: region.value });
};
</script>

<template>
	<div class="grid gap-4 sm:grid-cols-2">
		<BbSelect
			v-model="region"
			label="Region"
			:items="loadRegions"
			item-text="name"
			item-value="id"
		/>
		<BbSelect
			v-model="city"
			label="City"
			:items="loadCities"
			:dependencies="[region]"
			:deps-debounce-time="150"
			enforce-coherence
			item-text="name"
			item-value="id"
		/>
	</div>
</template>
```

Expected behavior: a region change re-runs `loadCities` with `prefill = true`; if the selected city isn't in the merged result (fetched + stashed), `city` is reset to `null`; a still-valid city survives untouched. In multiple mode the same flow filters the array instead. Note the provider's `modelValue` parameter follows the v-model shape — single value here, array with `multiple` — and the prop declares it `any`; annotate it `any` or your own model type ([signatures](./fetch-items-playbook.md)).

## When manual watchers are acceptable

Only for rules the `items` + `dependencies` contract cannot express — cross-component business constraints, server-side revalidation. Keep such watchers **additive** (extra rules on top of `enforce-coherence`), never a replacement, and never blind `city.value = null` resets on every upstream change — that discards selections the reload would have preserved.

`BbTable` has one structural exception: a **paginated** table whose page feeds `dependencies` must keep `enforce-coherence` off (every page turn is a refetch, so cross-page selections and the `select-all` + `unselected-items` pattern would be pruned away). There, reconcile inside the items provider — it is called `(prefill, selected)` with the current selection, which is exactly where the new rows are known.

## What's idiomatic now

- Coherence checks match by **value hash** (same identity rules as option selection) — stable, unique `item-value`s are a prerequisite; see the [Options playbook](./options-items-playbook.md).
- Single-mode enforcement resolves to `null`, so seed single models as `ref<T | null>(null)` and treat `null` as the "nothing valid" state in submit logic.
- `enforce-coherence` + `stash` on selects is the supported way to keep async picks valid across searches — not per-component caches.
- Dropdown selectable groups get coherence from config (`dependencies`, `enforceCoherence` per group, or the dropdown-level prop) — the `BbDropdownGroup` companion carries none of it.

## Anti-patterns

- Watchers that blindly clear values on every dependency change.
- Duplicated cleanup logic across tied components.
- Turning `enforce-coherence` off and replicating it manually.
- Binding many `BbSelectPopover` instances to **one shared ref**: each judges the same value against its own options, and every instance that disagrees emits `null` — the user's pick is overwritten by its neighbours. Give every row its own model.
- Hand-rolling `BbTable` selection pruning after a refetch — it ships `enforce-coherence` too; reserve provider-side reconciliation for paginated tables, where the prop must stay off.

## Validation checklist

- [ ] `enforce-coherence` enabled wherever stale selections are possible (selects, groups, dropdown groups, tables).
- [ ] Dependency lists are explicit and minimal.
- [ ] No manual watcher duplicates built-in coherence.
- [ ] Single-mode models tolerate `null` after enforcement; multiple-mode models tolerate a filtered array.
- [ ] Paginated tables (page in `dependencies`) reconcile in the items provider instead of `enforce-coherence`.

---

<!-- dist/ai/guides/component-picker.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/component-picker.md -->

# Component Picker

Use this guide to map a UI requirement to the correct `bitboss-ui` component before writing any code.

## Rule

Always pick from the **Consumer API** (`Bb*`) components first. Only fall back to base primitives when the user explicitly requests internal composition. Each linked doc leads with a "Usage & Guidelines" section — read it before the API tables.

---

## Am I about to rebuild one of ours?

The rest of this guide is indexed by _need_, which only answers the question you
thought to ask ("is there a Calendar? a Chart?"). The components that get
reinvented are the small ones nobody thinks to look up — a pilot builder opened
this picker four times and hand-rolled an avatar twice while `BbAvatar` sat in
the Data Display table below. So this section is indexed by **symptom**: match it
against the markup you are about to write, not against a need.

| You are about to write                                                                      | Stop — use                                                                                                   |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| An `<img>` with an initials/icon fallback branch, `border-radius: 50%`, `object-fit: cover` | [BbAvatar](../BbAvatar.md) — `src`/`alt`/size, initials slot, icon fallback, load-error handling             |
| `@keyframes spin` / `animation: … spin` on an element that means "waiting"                  | [BbSpinner](../BbSpinner.md) — sized off the control scale, honours `prefers-reduced-motion`                 |
| A `<span>` pill with a tinted background standing for a status                              | [BbBadge](../BbBadge.md) with a registered `soft-*` variant (design-language § Getting soft semantic badges) |

**`BbAvatar` is circle-only.** Its `border-radius: 50%` is in the component's own
CSS and no prop changes it, so a rounded-**square** avatar genuinely has no answer
here — build that one yourself. Everything else about it (fallbacks, load errors,
sizing) still applies, so the honest options are "use it and accept a circle" or
"hand-roll the square one knowingly", not "hand-roll it because you never saw it".

`npx bitboss-ui check` prints the avatar and spinner rows as
**advisory hints** — never a build failure, since a round `<img>` is sometimes a
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.

---

## Text Input

| Need                                    | Component                                                                        |
| --------------------------------------- | -------------------------------------------------------------------------------- |
| Single-line text                        | [BbTextInput](../BbTextInput.md)                                                 |
| Multi-line text                         | [BbTextarea](../BbTextarea.md)                                                   |
| Numeric value with clamping/stepping    | [BbNumberInput](../BbNumberInput.md)                                             |
| Color value in a form                   | [BbColorInput](../BbColorInput.md)                                               |
| Calendar date or date range             | [BbDatePickerInput](../BbDatePickerInput.md)                                     |
| Month or year (a reporting period)      | [BbDatePickerInput](../BbDatePickerInput.md) with `type="month"` / `type="year"` |
| Time or time range                      | [BbTimePickerInput](../BbTimePickerInput.md)                                     |
| Free-form tags / tokens typed by user   | [BbTag](../BbTag.md)                                                             |
| File selection via drag-and-drop/picker | [BbDropzone](../BbDropzone.md)                                                   |

- `BbTag` is for **open vocabularies** (skills, keywords, recipients the user invents). If values come from a known set, use `BbSelect` in multiple mode instead.
- `BbDropzone` captures and validates files; it does **not** upload — pair it with your request layer plus `BbProgress`/`useToast`.

---

## Selection from a List of Options

| Need                                                | Component                                |
| --------------------------------------------------- | ---------------------------------------- |
| Dropdown search, single or multi-select             | [BbSelect](../BbSelect.md)               |
| Picker on a custom trigger (no inline form input)   | [BbSelectPopover](../BbSelectPopover.md) |
| Few exclusive options (radio semantics)             | [BbRadioGroup](../BbRadioGroup.md)       |
| Multiple non-exclusive options (checkbox semantics) | [BbCheckboxGroup](../BbCheckboxGroup.md) |
| Multiple options as live on/off settings            | [BbSwitchGroup](../BbSwitchGroup.md)     |
| Approximate value or range from a bounded interval  | [BbSlider](../BbSlider.md)               |
| Whole-number score out of N (stars, rating)         | [BbRating](../BbRating.md)               |

**Choosing between BbSelect, BbRadioGroup, BbCheckboxGroup, BbSwitchGroup:**

- Large, dynamic, or searchable option sets → `BbSelect` (search and async fetch baked in).
- Small static exclusive choice (≤6 items, worth showing in full) → `BbRadioGroup`.
- 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).

Never hand-assemble a row of `BbCheckbox`/`BbRadio` — the groups give you fieldset semantics, item mapping, and validation for free.

---

## Single Toggle

| Need                                              | Component                      |
| ------------------------------------------------- | ------------------------------ |
| An answer or an agreement (accept terms, opt in)  | [BbCheckbox](../BbCheckbox.md) |
| The on/off state of a thing (notifications, sync) | [BbSwitch](../BbSwitch.md)     |
| One option interleaved with other markup          | [BbRadio](../BbRadio.md)       |

**BbCheckbox vs BbSwitch — choose on what the control _means_, not on when it commits.** A switch is the on/off **state of a thing**: "Email notifications", "Anyone with the link can view", "Auto-renew". A checkbox is an **answer or a selection**: "I accept the terms", "Also send me a copy", a selected row.

**A switch inside a submit-gated form is correct** — it commits with the form, exactly like every other field. This library ships `BbSwitch` from `bitboss-ui/validated` for that case, its own fixtures put one inside `<BbForm>`, and its wizard recipes put one behind a Next button. Do not downgrade a state toggle to a checkbox just because a Save button exists.

The one thing to avoid is **mixing commit models on one surface**: switches that already took effect the moment they were flipped, sitting under a Save button that implies they had not. Pick one — either the whole panel is live, or the whole form commits on submit.

A lone `BbRadio` is an escape hatch only — for a plain stacked group use `BbRadioGroup`.

---

## Buttons and Actions

| Need                                                                                      | Component                                                                 |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| A single action (or link-shaped button)                                                   | [BbButton](../BbButton.md)                                                |
| A clickable/navigable surface that is not a variant button (card, row, tile, custom link) | [BbBaseButton](../BbBaseButton.md)                                        |
| One dominant action + close alternates                                                    | [BbDropdownButton](../BbDropdownButton.md)                                |
| Menu of actions with no dominant one                                                      | [BbDropdown](../BbDropdown.md)                                            |
| Dangerous action requiring confirmation                                                   | [BbConfirm](../BbConfirm.md) + [useConfirm](../composables/useConfirm.md) |

**Choosing by intent:**

- `BbButton` — a single action, nothing else. Also a navigation trigger via `href`/`to` (see Navigation below). It is variant-first: use it when you want something that looks like a button. It is **not an inline link** — even `variant="link"` keeps the full button box (height + padding) and only recolors it, so it breaks the line height and text flow of a table cell, sentence, or property-grid value. For an inline text link, use `BbBaseButton` (next row).
- `BbBaseButton` — any clickable/navigable surface that is _not_ a variant button: a whole card or list row that links somewhere, an inline **record-identity cell** (a row's name that must truncate and flow at cell width), an in-text link, or a control styled entirely by your own CSS. It carries the same navigation engine as `BbButton` (`href`/`to`/Inertia/active classes) with **zero chrome — the project owns its look** (e.g. a `.plain-link` underline class). Prefer it over hand-rolling `@click="router.push(...)"` on a `<div>`/`<a>`, and over `BbButton variant="link"` for anything inline.
- `BbDropdownButton` — _Save / Save as draft / Save as template_: the primary action is one tap away, alternates behind a chevron. If the "alternates" are unrelated commands, it's a plain menu.
- `BbDropdown` — overflow "…" menus, account menus, context menus. Declare rows through `items`; never rebuild rows, dividers, or keyboard handling in markup. When the menu is just an `items` array with no header/footer/per-item slots, attach the `v-bb-dropdown` directive to the trigger instead of importing the component (see the directive note under Overlays).
- Every destructive action must pass through `useConfirm` first.

---

## Feedback and Status

| Need                                | Component                                                         |
| ----------------------------------- | ----------------------------------------------------------------- |
| Inline persistent status message    | [BbAlert](../BbAlert.md)                                          |
| Transient notification (toast)      | [BbToast](../BbToast.md) + [useToast](../composables/useToast.md) |
| Passive status pill, count, or dot  | [BbBadge](../BbBadge.md)                                          |
| Removable token (filter, selection) | [BbBadge](../BbBadge.md) (with `clearable`)                       |
| Clickable pill / filter chip        | [BbBadge](../BbBadge.md) + `BbBadgeButton` in its default slot    |
| Determinate progress bar            | [BbProgress](../BbProgress.md)                                    |
| Indeterminate loading spinner       | [BbSpinner](../BbSpinner.md)                                      |

**BbAlert vs BbToast:** `BbToast` for _what just happened_ (saved, copied, uploaded — transient, floating, self-dismissing, fired via `useToast`); `BbAlert` for _the current state of the page_ (form error summary, quota banner — in normal document flow, stays until read or dismissed).

**BbAlert takes its body from the default slot**, like the rest of the `text`-prop family: `<BbAlert>Something went wrong</BbAlert>`. `text` as a prop is for when a string is all you have; `#text` wins over both. (Before 2026-08-07 children rendered nothing at all — if you are reading older code that passes `text=` everywhere, that is why.)

**BbBadge vs BbTag vs BbIndicator:** `BbTag` _creates_ tokens (an input); `BbBadge` _displays_ tokens — passive by default, removable with `clearable` (renders a clear button), and interactive when a `BbBadgeButton` is slotted into it (the body becomes a real button/link; combine with `clearable` for the press-to-edit / ×-to-remove filter chip); `BbIndicator` pins a count/dot _over_ another element.

**BbBadgeButton vs BbButton:** both are real buttons — pick by the shape the user should see. `BbButton` looks like a button (variant chrome, button sizing); `BbBadgeButton` makes a **pill** clickable, and only exists inside a `BbBadge`.

**BbProgress vs BbSpinner:** `BbProgress` is for measurable completion (`min`→`max`); passing `null` renders an empty bar, not an indeterminate animation — use `BbSpinner` for waits with no measurable end.

---

## Overlays

| Need                                      | Component                                                              |
| ----------------------------------------- | ---------------------------------------------------------------------- |
| Modal dialog (one focused task)           | [BbDialog](../BbDialog.md)                                             |
| Side panel / drawer                       | [BbOffCanvas](../BbOffCanvas.md)                                       |
| Yes/No confirmation dialog                | [BbConfirm](../BbConfirm.md)                                           |
| Anchored floating interactive content     | [BbPopover](../BbPopover.md)                                           |
| Hover/focus label                         | [BbTooltip](../BbTooltip.md)                                           |
| Color picker on a trigger you own         | [BbColorPalette](../BbColorPalette.md)                                 |
| Date/calendar picker on a trigger you own | [BbDatePicker](../BbDatePicker.md)                                     |
| Month/year picker on a trigger you own    | [BbDatePicker](../BbDatePicker.md) with `type="month"` / `type="year"` |
| Time picker on a trigger you own          | [BbTimePicker](../BbTimePicker.md)                                     |

**BbDialog vs BbOffCanvas:** `BbDialog` for one focused task the user must finish (a form, a blocking announcement) — centred, takes focus. `BbOffCanvas` for supplementary content beside the main task (filters, a record's detail panel, settings). They share the same API (v-model, `title`, `header`/`default`/`footer` slots, `size`, `persistent`), so moving between them is mostly a tag swap. A plain yes/no is `BbConfirm`, not a hand-built dialog.

**BbPopover vs BbTooltip:** `BbTooltip` is a short, non-interactive label on hover/focus — never put links, buttons, or fields in it. `BbPopover` opens on click, stays open, and supports interactive content. A standard list of actions is `BbDropdown`, not a popover.

**Prefer the directive over the component for tooltips and dropdowns.** For the common case — plain-text tooltips and menus declared from an `items` array — attach `v-bb-tooltip` / `v-bb-dropdown` directly to the element instead of importing `BbTooltip`/`BbDropdown` and wiring an `activator`. The directives are registered globally by the plugin (`injectDirectives`, on by default), so no import is needed, and they render no wrapper element. Reach for the **component** only when you need something the directive can't express: for tooltips, a markup label (default slot) or the `activator` slot's scope; for dropdowns, `header`/`footer` or per-item slots, or `<BbDropdownGroup>` companions. When you already hold an element/ref, `BbDropdown`'s `activator` **prop** gives the same no-wrapper wiring without a slot. See [BbTooltip](../BbTooltip.md) and [BbDropdown](../BbDropdown.md).

There are also **`v-bb-color`**, **`v-bb-date`**, and **`v-bb-time`** directives for the narrower case of a value picker on a bare trigger in a table cell — a color dot, a date cell, or a schedule cell — attach the directive instead of wrapping each cell in `BbColorPalette` / `BbDatePicker` / `BbTimePicker`. Unlike tooltip/dropdown this is _not_ a blanket "prefer the directive": these components (and `BbColorInput` / `BbDatePickerInput` / `BbTimePickerInput`) have a real `v-model`, so use the component for form fields; the directive is only for bare per-row triggers. A directive can't two-way bind, so write-back rides an `onUpdate:modelValue` callback in the binding value (plus `onUpdate:time` for a datetime picker). See [BbColorPalette](../BbColorPalette.md), [BbDatePicker](../BbDatePicker.md), and [BbTimePicker](../BbTimePicker.md).

---

## Navigation

| Need                                  | Component                            |
| ------------------------------------- | ------------------------------------ |
| Peer views of the same screen (tabs)  | [BbTabs](../BbTabs.md)               |
| Collapsible section (accordion style) | [BbAccordion](../BbAccordion.md)     |
| Togglable region, custom trigger      | [BbCollapsible](../BbCollapsible.md) |
| Breadcrumb path (where am I)          | [BbBreadcrumbs](../BbBreadcrumbs.md) |
| Pagination controls                   | [BbPagination](../BbPagination.md)   |
| Hierarchical tree                     | [BbTree](../BbTree.md)               |

**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. `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):**

- `BbAccordion` — composed header button + collapsible body, ARIA wired for you. The default for FAQ/settings sections.
- `BbCollapsible` — v-model region with **no header**; you bring the trigger (inline "read more" link, toolbar toggle).
- `BbSmoothHeight` — no hide/show at all; only animates height changes (wizard steps, growing lists).

---

## Data Display

| Need                          | Component                  |
| ----------------------------- | -------------------------- |
| Rows of records with columns  | [BbTable](../BbTable.md)   |
| Hierarchical expandable nodes | [BbTree](../BbTree.md)     |
| User or entity avatar         | [BbAvatar](../BbAvatar.md) |
| Standalone SVG icon           | [BbIcon](../BbIcon.md)     |

**BbTable vs BbTree:** flat rows with one level of detail → `BbTable` with its `#expand` slot; genuinely recursive data of unbounded depth (file browser, nested categories) → `BbTree`. For a select-a-value list in a form, use the Selection components — not a selectable table.

**A list of records _without_ columns is not a component here** — it is a `<ul>`/`<dl>` styled with tokens ([design-language](./design-language.md) § Layout), with `BbBaseButton` making the whole row navigable. Reach back for `BbTable` with one or two columns when you want what it owns beyond layout: sorting, skeletons, the empty state, selection.

Whatever you put _inside_ those rows, check the symptom index at the top of this guide first — `BbAvatar` is on this page and still gets rebuilt by hand more often than any other component.

Prefer icon **props** (`icon`, `prepend:icon`, item `icon`) on components over standalone `BbIcon`; reach for `BbIcon` only for iconography the design owns (status glyphs, empty states).

---

## Layout and Utility

| Need                       | Component                              |
| -------------------------- | -------------------------------------- |
| Animated height transition | [BbSmoothHeight](../BbSmoothHeight.md) |

---

## Not in this library

The 58 public `Bb*` components plus the exported `use*` composables are the whole
surface. Everything below is a name agents routinely assume exists, invent, and
then work around — usually by hand-rolling something the library already covers
under a different name. **If a component you want is not in the tables above — or
a composable you want is not in this corpus's `composables/` folder — it is not
here.** Check this list before inventing a name; if the need is genuinely absent,
compose it or write it yourself.

| Assumed component or composable                                | Reality                                                                                                                                                                                                                                                                                                                                   |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BbColumnManager` — show/hide/reorder columns                  | Does not exist as a component. Order is `v-model:order` on `BbTable` (an array of keys any panel can write; `reorderable` adds the built-in header drag + keyboard handle); visibility is still filtering `columns` — the hidden key keeps its slot in the order. Compose the panel from `BbPopover` + `BbCheckbox`.                      |
| `BbKanban` / drag-and-drop board                               | Does not exist. There is no reusable DnD primitive in the library (`BbTable`'s header drag is internal to the table) — compose the board from `BbTable` (a table/list view of the same data) or hand-roll the drag-and-drop interaction 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.                                                                                                                                                                                                         |
| `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`/`--color` 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).                                                                                                                                                                                                                                            |
| `BbList` / `BbListItem` / `BbDescriptionList`                  | Do not exist — a list row is an `<li>` with tokens, and [BbBaseButton](../BbBaseButton.md) makes the whole row navigable. See the note under Data Display.                                                                                                                                                                                |
| `useLiveFeed` / any polling or cross-tab feed helper           | Does not exist, and neither does a cross-tab helper — `useBroadcastChannelInstance` was removed (cross-tab messaging is not a UI concern). Use `useBroadcastChannel` from `@vueuse/core`; the polling and the merge are yours.                                                                                                            |
| `BbStepper` / `BbWizard`                                       | Does not exist as a component; the wizard-form recipe composes one.                                                                                                                                                                                                                                                                       |
| `BbSkeleton` (standalone)                                      | Only `BbTable` ships skeletons, via the column `skeleton` field.                                                                                                                                                                                                                                                                          |
| `BbCommand` / command palette                                  | Does not exist. Compose `BbDialog` + `BbSelectPopover`.                                                                                                                                                                                                                                                                                   |
| `BbCalendar` (month / scheduling view)                         | Does not exist. [BbDatePicker](../BbDatePicker.md) is a picker, not a calendar surface.                                                                                                                                                                                                                                                   |
| `BbChart` / `BbGraph`, `BbCarousel`, `BbTimeline`, `BbDivider` | Do not exist. No charting, carousel or timeline primitive ships here.                                                                                                                                                                                                                                                                     |

App chrome — an app shell, sidebar, page header, selection dock — is
deliberately **not** a component: it is yours to own. The per-platform
[Layout Scaffold](../recipes/inertia/layout-scaffold.md) recipe ships the source
to copy.

---

## Item-Driven Components

The following components accept an `items` prop (array or async provider function) with `item-text`/`item-value` mapping. Consult the items playbooks before wiring them:

- [BbSelect](../BbSelect.md), [BbSelectPopover](../BbSelectPopover.md)
- [BbCheckboxGroup](../BbCheckboxGroup.md), [BbRadioGroup](../BbRadioGroup.md), [BbSwitchGroup](../BbSwitchGroup.md)
- [BbTable](../BbTable.md)

`BbDropdown`, `BbBreadcrumbs`, `BbTabs`, and `BbTree` are also declared through `items`, but with typed item objects (label/key/href/…) rather than arbitrary domain objects.

See:

- [Options and Items Playbook](./options-items-playbook.md)
- [Fetch Data Items Playbook](./fetch-items-playbook.md)
- [Coherence Playbook](./coherence-playbook.md)

---

<!-- dist/ai/guides/design-language.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/design-language.md -->

# Design Language

How to make anything built with `bitboss-ui` look like it belongs to the same
product. Follow these rules whenever you write custom CSS next to the
components or choose component variants.

## Hard Rules

1. **Never hardcode colors** in custom CSS around components. Use the `--bb-*`
   custom properties below so your surfaces follow theme and dark mode.
2. **Never override component internals** (`.bb-*__*` element classes) from
   consumer code. Restyle via tokens, variants, or documented props — the only
   exceptions are extension points a component's own doc sanctions.
3. **One primary action per view region.** Everything else is `secondary`,
   `outline`, or `ghost`.
4. **`destructive` is only for irreversible actions**, and destructive flows
   must go through `useConfirm` first.
5. **Respect the radius**: use `var(--bb-radius)` for any custom container that
   sits next to components; do not invent new corner radii.

## How to style around the library

Three lanes, in order of preference:

1. **Component look → props.** Pick a variant, `size`, `compact`. Never write
   CSS to make a component look different.
2. **Page layout & spacing → Tailwind utilities** (or your project's
   equivalent) on your own wrapper elements — `flex items-end gap-3`,
   `grid gap-6`, `max-w-3xl`. Components size themselves; you only place them.
3. **Genuinely custom visuals → `--bb-*` tokens.** The few CSS rules that
   remain (a custom panel, a status dot) use theme tokens so they follow
   theming and dark mode automatically.

Treat everything inside a component as private API. Where a component is
designed to be extended visually, its own doc names the extension point —
[BbTree](../BbTree.md) has you draw connector lines in consumer CSS anchored
to its `--indent`/`--gap` tokens; [BbTabs](../BbTabs.md) exposes `--list-h`.
Read the per-component doc before writing any CSS that mentions a `.bb-`
class.

## Token Vocabulary

All theme tokens are CSS custom properties defined on `:root` (imported via
`bitboss-ui/styles.css`). One name per token — `.dark` re-declares the knobs
that change and everything derived follows. The full architecture (tiers,
naming rules, the emphasis ladder) lives in
[design-tokens.md](./design-tokens.md); this is the consumer summary.

### 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-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`         | Global elevation shadow                                                                                                           |
| `--bb-panel-p`        | Content padding of large surfaces (dialog, off-canvas); axis split via the locals `--px`/`--py` on `.bb-dialog` / `.bb-offcanvas` |
| `--bb-z-overlay`      | Z-index for overlays (10)                                                                                                         |

### Color semantics

| Token              | Meaning                                                            |
| ------------------ | ------------------------------------------------------------------ |
| `--bb-primary`     | Brand/primary accent (black in light, white in dark by default)    |
| `--bb-primary-fg`  | Foreground on primary surfaces                                     |
| `--bb-danger`      | Errors and destructive intent                                      |
| `--bb-warn`        | Warning **chrome/icons** (`hasWarning`) — warm, ranks below danger |
| `--bb-text-warn`   | Warning **message text** — deeper amber (knob, not derived)        |
| `--bb-text`        | Global text color                                                  |
| `--bb-text-muted`  | Secondary text, hints, placeholders, icons (derived)               |
| `--bb-text-faint`  | Disabled foregrounds (derived)                                     |
| `--bb-ring`        | Focus ring color (derived from primary)                            |
| `--bb-ring-danger` | Focus ring in error states (derived from danger)                   |
| `--bb-ring-warn`   | Focus ring in the warning input state (derived from `--bb-warn`)   |

Rule of thumb: **hover/pressed chrome is neutral; primary tint means
selected.** Never build a hover state from `--bb-primary` — use `--bb-hover`
so themes with loud brand colors keep gray chrome.

### Scale

| Token            | Meaning                                                  |
| ---------------- | -------------------------------------------------------- |
| `--bb-control-h` | Master control height (32px); inputs/buttons/tabs derive |
| `--bb-fs`        | Master font size (14px); component sizes derive          |

### Motion

| Token                    | Meaning                                       |
| ------------------------ | --------------------------------------------- |
| `--bb-transition-fast`   | 150ms — micro-interactions                    |
| `--bb-transition-medium` | 250ms — overlays, most components             |
| `--bb-transition-slow`   | 350ms — large consumer surfaces               |
| `--bb-ease`              | The single easing curve; do not invent others |

Input-family tokens also exist (`--bb-input-h`, `--bb-input-px`,
`--bb-label-fs`…) — see design-tokens.md. Component-specific tokens are
**unprefixed** and defined on each component's root class (e.g. BbTabs'
`--list-h`); override them per instance or at a scope to retune a whole area
coherently instead of styling individual components.

## Dark Mode

Adding the `dark` class on `<html>` or any ancestor flips every token. There
is no JS involved. Custom consumer CSS that uses tokens gets dark mode for
free; custom CSS with hardcoded colors breaks it — which is why Hard Rule 1
exists.

To crossfade instead of switching instantly, add `theme-animated` to the
**same element** that carries the scheme class
(`<html class="dark theme-animated">`) — the color knobs are typed with
`@property`, so they interpolate and everything derived follows.

## Variants

Variant names are typed per family. Built-in sets:

| Family                                               | Built-in variants                                                                             |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `BbButton` / `BbDropdownButton`                      | `primary` `secondary` `outline` `ghost` `destructive` `link` (+ `none` unstyled escape hatch) |
| `BbBadge`                                            | `primary` `secondary` `outline` `ghost` `destructive`                                         |
| `BbAlert`                                            | `primary` `outline` `destructive` `warning`                                                   |
| `BbToast` / `useToast`                               | `default` `success` `info` `warning` `destructive`                                            |
| `BbConfirm` / `useConfirm`, dropdown items, tooltips | `default` `destructive`                                                                       |

What the shared names mean (shadcn-style vocabulary):

| Variant       | Use for                                        |
| ------------- | ---------------------------------------------- |
| `primary`     | The single main action of a view region        |
| `secondary`   | Supporting actions                             |
| `outline`     | Neutral actions on busy surfaces               |
| `ghost`       | Low-emphasis, inline, or icon-only actions     |
| `destructive` | Irreversible/dangerous actions (confirm first) |
| `link`        | Navigation disguised as text (buttons only)    |
| `none`        | Unstyled escape hatch — avoid                  |

Projects can register extra variants through the Vite/Nuxt plugin
(`buttonVariants`, `badgeVariants`, `alertVariants`, `confirmVariants`,
`dropdownItemVariants`, `tooltipVariants`, `toastVariants` 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).
Never invent a variant name that is not built-in or registered in the
project's plugin config — check `vite.config.*` / `nuxt.config.*` first.

## Using color

**Reach for color more than the monochrome default suggests — but make it mean
something.** A calm, mostly-neutral surface with a few deliberate spots of color
reads as modern and confident; color sprinkled for decoration reads as noise.
Add color for one of three reasons, never for prettiness:

1. **Semantic status** — `info`, `success`, `warning`, `error/danger`. A build
   passed, a payment failed, a token is low.
2. **State** — selected / active / dirty / pending / just-changed. Color is a
   fast, pre-verbal "this updated."
3. **Differentiating a small, closed set** — a few statuses, priorities, or
   categories the eye should tell apart at a glance. Only when the set is small
   and fixed; a per-row rainbow of unique colors is noise, not signal.

Keep it **soft and calm**:

- **Chrome stays neutral.** Hover, pressed, and focus chrome use
  `--bb-hover`/`--bb-pressed`/`--bb-ring`; selection uses the primary tint (the
  existing rule). Semantic color goes on the **content** — a status dot, a soft
  badge, a tinted alert — not on interactive chrome. This is what keeps color
  from feeling jarring.
- **Prefer soft tints over saturated fills** on anything bigger than a dot. The
  library's own recipe is `color-mix(in oklab, <hue> ~10–15%, var(--bb-panel))`
  for the fill with the hue itself as text — exactly how `--bb-destructive` is
  built. Mixing toward `--bb-panel` keeps it theme- and dark-mode-aware. Small
  dots may be saturated.
- **One primary action per region still holds.** Semantic color is not a licence
  for five loud buttons.
- **Never color as the _only_ signal.** Pair it with text or an icon — color
  alone fails color-blind users and Hard Rule territory.

### What carries semantic color today (use these first)

| Need                                                | Reach for                                                                             |
| --------------------------------------------------- | ------------------------------------------------------------------------------------- |
| A status marker next to a label/row                 | **BbIndicator** dot — `default` / `success` / `info` / `warning` / `destructive`      |
| A persistent message                                | **BbAlert** — `primary` / `outline` / `warning` / `destructive` (soft tints)          |
| Transient feedback                                  | **BbToast** / `useToast` — `default` / `success` / `info` / `warning` / `destructive` |
| A removable/error tag                               | **BbBadge** `destructive` (soft); neutral tags use `secondary` / `outline`            |
| A form field that needs attention but isn't invalid | any form control's **`warnings`** / **`hasWarning`** props — see below                |

### Meters, ramps, gauges — the project owns every hue (ruled 2026-07-30)

The library ships **no** status-color vocabulary beyond `--bb-danger`,
`--bb-warn`, and `--bb-text-warn` (which exist for its own error/warning
states), and it never will —
no `--bb-success`, no `--bb-good`, no graded ramps. So when a design needs
multi-step color — a password-strength meter, a health score, an SLA bar, a
capacity gauge — the palette is **project CSS, minted by you**, exactly like
the soft badge palette below: local custom properties (`--accent`-style hues,
mixed toward theme tokens with `color-mix(in oklab, …)` so they stay
dark-mode-aware), applied through the component's CSS hooks — e.g.
`BbProgress`'s `--fill`. Reusing `--bb-danger` / `--bb-warn` /
`--bb-text-warn` for the low end of
a ramp is fine if the project chooses to — they are ordinary custom properties —
but that choice, and its contrast, belongs to the project. Do not wait for, or
invent, a library token for the positive end: there isn't one, by ruling.

### Warning input state

Every form control (`BbTextInput`, `BbTextarea`, `BbSelect`, `BbNumberInput`,
`BbColorInput`, the date/time pickers, `BbSlider`, `BbRating`, `BbTag`,
`BbCheckbox`/`BbRadio`/their groups, `BbDropzone`, …) exposes a warning state
that mirrors the error state exactly — two props, parallel to `errors` /
`hasErrors`:

- **`warnings`** (string | string[]) — one or more messages rendered below the
  field in their own `aria-live="polite"` region, in amber (`--bb-text-warn`),
  and referenced from
  the control's `aria-describedby` while displayed (after any `errors`). A non-empty
  `warnings` **implies the warning state** (just as `errors` implies the error
  state), so you rarely set `hasWarning` by hand.
- **`hasWarning`** (boolean) — forces the warning chrome without a message, to
  pre-style a field.

Either way the field gets the **same chrome as the error state** — tinted border
and focus ring, a warning icon in the append stack — but in amber (`--bb-warn` /
`--bb-ring-warn`) instead of danger red. Chrome and icons ride `--bb-warn`
(non-text, ≥3:1); the message copy rides the deeper `--bb-text-warn` (≥4.5:1)
— one token cannot hold both budgets without browning the borders.

Use it for a field that is valid but deserves a second look — a value that is
unusual, near a limit, or soft-flagged — where a hard error (which also sets
`aria-invalid` and blocks submit-shaped flows) would overstate the problem.

- **Errors win when both are set** — a field is never amber and red at once. The
  error chrome takes over and the warning **messages are suppressed** (the
  `warnings` region collapses to zero height); show `errors` and `warnings`
  together and the user sees only the errors.
- Unlike `errors`, `warnings` do **not** set `aria-invalid` — it's a soft "needs
  a second look" state, not an invalid one.
- It is a **field state**, not the badge/button `warning` _variant_ (those stay
  locked — see [the sanctioned custom-variant path](#getting-soft-semantic-badges-the-sanctioned-custom-variant-path)).
- Prefer `warnings` (which carries its own text) over bare `hasWarning` + a
  `hint` — color alone is never the only signal. `warnings` are announced the
  moment they appear (live region) **and** re-read on focus (`aria-describedby`,
  ahead of the hint); a `hint` only ever reads as static description.

```vue
<!-- valid, but worth flagging — amber message, no aria-invalid, no submit block -->
<BbTextInput
	v-model="rate"
	label="Discount"
	:warnings="rate > 50 ? 'That is an unusually large discount.' : undefined"
/>
```

### Badges label state; buttons are actions

A **badge is the right affordance for a status/state marker** — not a `BbButton`,
which is a distinct affordance (an action to perform). When a status marker must
also be **clickable** (opens an editor, filters a list), slot a
**`BbBadgeButton`** into the badge. The badge body becomes a real button in
place, so the pill _is_ the control:

```vue
<BbBadge variant="soft-green" append:icon="lucide:chevron-down">
  <BbBadgeButton v-bind="activatorProps">Done</BbBadgeButton>
</BbBadge>
```

Do **not** wrap the badge in an outer `BbBaseButton` to achieve this (the v2
habit). It nests the interactive element outside the pill, so the hit area and
the focus ring disagree with the visual boundary, and on a `clearable` badge it
nests a button inside a button — invalid markup. `BbBadgeButton` has full
`BbBaseButton` parity (`href`/`to`, Inertia, `disabled`, …), so nothing is lost
by moving the interaction inside.

The badge owns the color, meaning and chrome; the companion owns the
interaction and the focus ring is drawn on the whole pill for you — no
`.my-trigger` class needed. Signal changeability with an **internal** trailing chevron
(`append:icon` on the badge itself) — not a prepend icon and not a separate caret
sitting outside the badge. Make the editable badge a **self-contained component**
with an `editable` prop that hosts its own picker — don't split "button" and
"badge" into two components at the call site. While the picked value saves, set
the badge's `loading` prop: the spinner takes the chevron's place (same size,
nothing shifts) — and in button mode it lands inside the hit target, so the
control never changes shape. Shipped references: the BbTable guide's
inline-editing example ([BbTable](../BbTable.md)) and the
[Inline Edit Playbook](./inline-edit-playbook.md); in-repo live reference:
`src/dev/inline-edit/` — `StatusBadge.vue`, `PriorityBadge.vue`, `AssigneeBadge.vue`
(each a plain badge when not `editable`, a clickable picker when it is). Those
three still use the older wrap-in-`BbBaseButton` form and predate
`BbBadgeButton`; follow the snippet above, not their activator markup.

### Getting soft semantic badges (the sanctioned custom-variant path)

`BbButton` and `BbBadge` ship **no** `success` / `info` / `warning` variants.
The shared status tokens besides `--bb-danger` are `--bb-warn` /
`--bb-text-warn`, and they are
**not** a variant vocabulary — they color the [warning input state](#warning-input-state)
(the `hasWarning` prop and `warnings` messages) and nothing else. There is still **no `--bb-success` /
`--bb-info` token**, and BbIndicator hardcodes its status hues. So:

- **Do not** write `variant="success"` on a badge or button, or invent
  `bb-badge--warning`, **without registering it first** — an unregistered name
  type-errors now, and before the registries existed it shipped no CSS at all
  (the real "warning badge" hallucination that rendered an unstyled pill).
- **Do** register the name via the plugin (`badgeVariants` / `buttonVariants`),
  then style `.bb-badge--<name>` in a **project stylesheet kept separate from the
  library defaults** — the plugin makes the name type-check; you own its CSS.
  Follow the soft recipe above. That is the permanent path — a first-class
  semantic set (`success`/`info`/`warning` variants) was considered and
  rejected (DECISIONS §C 18b): shadcn carries no such vocabulary, and neither
  do we.

**"Locked" means typed, not closed — and registering is part of the job.** The
registries are open by design so each app owns its own tones. If the page you
are writing needs a status palette and the project has not registered one yet,
**add it**: the plugin option and the stylesheet block below are the whole
change, and both belong in the answer. Do not settle for `secondary`/`outline`
because the palette "isn't available" — that silently drops the design intent
(three statuses that must be told apart at a glance become three grey pills).
Just don't do half of it: a registered name with no CSS is the unstyled-pill
bug, and CSS with no registration fails `vue-tsc`.

#### The soft status palette (canonical)

This is the palette to reach for when a design needs semantic status colors on
badges — in examples, recipes, and real apps alike. Five accents, one shared
soft treatment. It mirrors `BbIndicator`'s built-in status hues, plus a slate
neutral the indicator doesn't have:

| Variant      | Accent    | Means                       | Mirrors                             |
| ------------ | --------- | --------------------------- | ----------------------------------- |
| `soft-gray`  | `#64748b` | neutral / idle / paused     | — (slate; no indicator counterpart) |
| `soft-blue`  | `#2563eb` | active / in progress / info | `BbIndicator` `info`                |
| `soft-green` | `#16a34a` | success / done              | `BbIndicator` `success`             |
| `soft-amber` | `#d97706` | attention / high / pending  | `BbIndicator` `warning`             |
| `soft-red`   | `#dc2626` | danger / blocked / failed   | `BbIndicator` `destructive`         |

Register the names in the plugin config, then drop this block into your project
stylesheet (this section is the canonical source — copies elsewhere point back
here):

```css
/* Per-variant accent — the one project-chosen hue each soft variant mixes from.
   Only the library mints `--bb-*` tokens, so the hue lives in a local
   `--accent`; everything derived mixes toward theme tokens, which keeps every
   variant dark-mode-aware with no `.dark` overrides. */
.bb-badge.bb-badge--soft-gray {
	--accent: #64748b;
}
.bb-badge.bb-badge--soft-blue {
	--accent: #2563eb;
}
.bb-badge.bb-badge--soft-green {
	--accent: #16a34a;
}
.bb-badge.bb-badge--soft-amber {
	--accent: #d97706;
}
.bb-badge.bb-badge--soft-red {
	--accent: #dc2626;
}

/* Shared soft treatment — reads the local --accent set above. Percentages sit
   on the emphasis ladder (see design-tokens.md). */
.bb-badge.bb-badge--soft-gray,
.bb-badge.bb-badge--soft-blue,
.bb-badge.bb-badge--soft-green,
.bb-badge.bb-badge--soft-amber,
.bb-badge.bb-badge--soft-red {
	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
	--border-width: 1px;
	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
}
```

Two gotchas the block already encodes:

- **Selectors are doubled (`.bb-badge.bb-badge--x`) on purpose.** The built-in
  variants compile to 2-class specificity (they're nested under `.bb-badge`), so
  a flat `.bb-badge--x` would tie the base `.bb-badge { --bg }` rule and lose on
  injection order. Match their specificity and this layer wins.
- **The accent hex is the project's own hue, held in a local `--accent`** — it
  is not a `--bb-*` token and must not become one (Hard Rule 1: only the library
  mints those). Everything derived mixes toward `--bb-panel` / `--bb-text`, so
  themes and dark mode keep working for free.

## Sizing

The named scale is `xs | sm | md | lg | xl | 2xl`. It applies to `BbButton` /
`BbDropdownButton`, `BbBadge`, `BbIndicator`, `BbDialog`, and `BbOffCanvas`
(off-canvas adds `'auto'`; dialog and off-canvas also accept a CSS length
string or pixel number as escape hatch). Buttons, dialogs, and off-canvas
also accept a responsive record keyed by breakpoint, e.g.
`:size="{ default: 'sm', lg: 'md' }"`. Rules:

- Stay on the named scale; use numeric/custom CSS sizes only when a named
  preset genuinely cannot work.
- **Buttons prefer `md`** — the default (28px, one step under the 32px
  input height). `md` is exactly the height of a `compact` input, so an
  `md` button sits flush beside compact fields in a filter bar or inline
  form. Since it's the default, idiomatic code omits the `size` prop.
  Reach for `sm`/`xs` only inside genuinely dense surfaces — table row
  actions, toolbars, bulk-action bars — and for `lg`+ only on a rare hero
  action.
- Keep pages compact through **density, not button shrinking**: tight gaps
  and the `compact` boolean, not `size="sm"` everywhere.
- Form controls have no `size` prop — they all share `--bb-control-h`. Density
  is the `compact` boolean, shared by the whole input family plus `BbTable`
  and `BbTabs`; use it together across a whole view, not on single
  components.

## Adaptive Behavior

Surface components (`BbDialog`, `BbPopover`, `BbDropdown`, `BbSelect`,
`BbSelectPopover`, the date/time pickers, `BbColorInput`/`BbColorPalette`…)
accept an `adaptive` prop: on mobile viewports the surface
renders as a bottom sheet (`BbOffCanvas`) instead of a floating
popover/dialog. The global default comes from the plugin config
(`config.adaptive`); the prop overrides it per component. Guidance:

- Leave `adaptive` unset unless the user asks otherwise — the project default
  is usually right.
- If you set it, set it deliberately per surface, not globally in a page.

## Layout

The library deliberately ships **no layout primitives** (no grid, container,
or stack components). Compose pages with plain CSS flex/grid in consumer code,
using tokens for anything visual:

```css
.page__filters {
	display: flex;
	gap: 12px;
	flex-wrap: wrap;
	align-items: flex-end;
}

.page__card {
	background: var(--bb-panel);
	border: var(--bb-border-w) solid var(--bb-border);
	border-radius: var(--bb-radius);
	box-shadow: var(--bb-shadow);
}
```

### A trend's colour is its valence, not its direction

"Up is green" is wrong for half the metrics on an ops dashboard. Critical
alerts +12, overdue returns +8, failed jobs +3 — all rising, none good. Paint
the **meaning**, never the arrow:

```ts
// The metric declares which direction is good; the delta only picks the sign.
const kpiDeltaVariant = (metric: Metric, delta: number) => {
	if (delta === 0) return 'soft-gray';
	const rising = delta > 0;
	return rising === metric.risingIsGood ? 'soft-green' : 'soft-red';
};
```

Risk metrics (alerts, overdue, failures, churn) invert: `risingIsGood: false`.
Keep the arrow glyph tied to direction and the colour tied to valence, so a
falling-and-good metric still reads as a down arrow in green. And per the
colour rules above, never let colour carry it alone — the arrow plus the label
have to survive a greyscale print.

### Row tint: a wash the row keeps, orthogonal to selection

A listing row can carry three different states at once — it _is_ something
(overdue, blocked), it is **highlighted** (its peek is open), and it is
**selected** (a bulk action will hit it). Painting all three with the same
primary tint makes them indistinguishable, and painting the semantic one with
the selection colour makes an overdue row look selected.

Keep the axes separate:

- **Row state = a soft semantic wash**, project CSS on the row:
  `background: color-mix(in oklab, var(--bb-danger) 6%, var(--bb-panel))` for
  `.row-danger`, the same recipe over `--bb-warn` for `.row-warn`. Hover
  deepens the same hue (≈10%) rather than switching to the neutral hover, so
  the row does not lose its meaning under the cursor.
- **Selection and highlight stay the library's own chrome** — the checkbox and
  the highlight ring/tint. Never re-tint the row for them.
- **The wash is a background, not a border.** A left border competes with the
  nested-table lead-in and the identity cell's toggle.

Because they are orthogonal, an overdue row that is also selected shows both,
and neither reading is lost:

```css
.row-danger {
	background: color-mix(in oklab, var(--bb-danger) 6%, var(--bb-panel));
}
.row-danger:hover {
	background: color-mix(in oklab, var(--bb-danger) 10%, var(--bb-panel));
}
.row-warn {
	background: color-mix(in oklab, var(--bb-warn) 6%, var(--bb-panel));
}
.row-warn:hover {
	background: color-mix(in oklab, var(--bb-warn) 10%, var(--bb-panel));
}
```

Mix toward `--bb-panel`, not toward transparent, so the wash survives dark mode
and does not stack with the striping.

### Guide helper: `.plain-link`

Define a project-owned `.plain-link` class (not a library variant) for inline
text links in tables, peeks, and property grids — entity-identity cells (a
record's name, number, or title column) above all. Pair it with `BbBaseButton`
so there is no button chrome — faint underline at rest, `currentColor`
underline on hover/focus:

```vue
<BbBaseButton class="plain-link" @click="peekInvoice(item.id)">
	{{ item.number }}
</BbBaseButton>
```

```css
.plain-link {
	color: inherit;
	text-decoration: underline;
	text-underline-offset: 2px;
	text-decoration-color: color-mix(in oklab, var(--bb-text) 25%, transparent);
	transition: text-decoration-color var(--bb-transition-fast) var(--bb-ease);
}
.plain-link:hover,
.plain-link:focus-visible {
	outline: none;
	text-decoration-color: currentColor;
}
```

Do not use `BbButton` `ghost`/`link` for those cells; reserve those variants for
real actions and chrome buttons. `link` in particular keeps button height and
padding, so it never flows or truncates like inline text — wrong for a name
column at cell width (see [BbButton](../BbButton.md) § Choosing a variant).

Spacing convention: use multiples of 4px, favoring 8/12/16/24 gaps. Form
fields stack with 16px gaps; sections separate with 24px.

## Typography

### Display type is for guest surfaces; the workspace inherits

Marketing, auth and other **guest** surfaces may carry a display face on their
titles — that is where a product gets to have a voice. **Workspace** surfaces
(the app behind the login: listings, peeks, forms, dialogs) inherit `--bb-fs`
and the system stack, and get their hierarchy from **weight and colour**, not
from a second family or a jump in size.

The reason is density: an ops screen shows fifty rows of the same shape, and a
display face at 15px costs legibility for nothing. A title that needs to stand
out in the workspace goes to `font-weight: 600` and `--bb-text`, with
supporting text at `--bb-text-muted` — the same two-step the components already
use internally.

So: one display face, scoped to the guest layout's headings. Never on a table,
a peek title, a dialog title, or a field label.

Component typography is token-driven (`--bb-fs`: 14px, from which
`--bb-label-fs` and `--bb-input-fs` derive). For consumer text next to
components: 14px body in data-dense UIs, `--bb-text-muted` for secondary
text, `--bb-label-weight`
(500) for emphasis. Don't introduce new font sizes below 12px.

---

<!-- dist/ai/guides/design-tokens.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/design-tokens.md -->

# Design Tokens

This is the spec for how every visual value in the library is expressed. It is
deliberately small: we are not shipping a design system, we are shipping
**affordances**. A token earns its place only when overriding it is a decision
a real consumer would make. Everything else is a formula.

## Principles

1. **Cheap by default.** Reuse an existing token (possibly through `calc()` /
   `color-mix()`) before minting a new one. The `:root` block is the public
   API surface _and_ what crowds the devtools console — it must stay readable
   in one screen.
2. **Elastic derivation.** Secondary values derive from primary knobs
   (`calc(var(--bb-radius) - var(--p))`, `calc(var(--bb-control-h) - 4px)`).
   Turning one knob retunes the whole library coherently — this is the theme
   builder contract.
3. **Two names, two tiers.**
   - `--bb-*` — theme tokens. Global, defined in `variables.css`, themable.
   - `--*` (no prefix) — component tokens. Defined on the component's root
     class, in the component's own CSS file. Never in `:root`.
     `--bb-tab-card-radius-md` must never exist.
4. **One accent at a time.** A component resolves _which_ color it is using
   (primary, danger, a variant color) into a local token once, then every
   state derives from that local via the emphasis ladder.
5. **Grays stay gray: primary tint means _selected_.** Neutral chrome —
   hovers, pressed fills, secondary buttons, scrollbars — derives from
   text/panel, never from primary. Primary appears only where the state is
   genuinely brand-selected (solid primary buttons, links, rings, calendar
   selected day/range, focused chips, today marker). This is what makes a
   yellow theme produce gray hovers and yellow selections instead of a
   yellow-washed UI.
6. **Mixes interpolate in `oklab`.** Perceptually even steps; srgb muddies
   saturated brand colors. Enforced by the checker.

## Tier 1 — theme tokens (`--bb-*`)

The complete inventory. If a value is not here, it is not globally themable —
that is a feature.

### Brand knobs (what a theme builder sets)

| Token               | Default (light)    | Dark               | Meaning                                                               |
| ------------------- | ------------------ | ------------------ | --------------------------------------------------------------------- |
| `--bb-primary`      | `rgb(0 0 0)`       | `white`            | Brand accent                                                          |
| `--bb-primary-fg`   | `white` (fallback) | `black` (fallback) | Text/icons **on** primary — **auto-contrasts** (see note)             |
| `--bb-danger`       | `rgb(217 59 48)`   | rose-400           | Errors, destructive intent                                            |
| `--bb-warn`         | `rgb(240 131 88)`  | amber-500          | Warning **chrome/icons** (`hasWarning`) — ranks below danger          |
| `--bb-text-warn`    | `rgb(180 83 9)`    | amber-500          | Warning **message text** — deeper amber, text-contrast budget         |
| `--bb-panel`        | `rgb(255 255 255)` | `#313638`          | Raised surfaces (cards, inputs, popovers, dialogs)                    |
| `--bb-text`         | `rgb(0 0 0)`       | `white`            | Foreground                                                            |
| `--bb-border`       | zinc-300           | zinc-600           | Hairlines; pair with `--bb-border-w`                                  |
| `--bb-ring-opacity` | `15%`              | `40%`              | Ring strength; `--bb-ring`/`--bb-ring-danger`/`--bb-ring-warn` follow |

**`--bb-warn` / `--bb-text-warn` are the only shared status tokens besides
`--bb-danger`.** They color the **warning input state** as a chrome/text split,
because the two halves answer to different requirements. `--bb-warn` paints
borders, focus rings and the warning glyph: decorative reinforcement of a
state the icon's SHAPE and the message text already carry, so WCAG 1.4.11's
≥3:1 does not bind it (1.4.11 covers indicators that are the ONLY way to
perceive a control's state). What binds it instead is severity legibility —
warning must not read as danger. The shipped salmon sits ΔE 0.148 from
`--bb-danger` in oklab; a 1.4.11-compliant orange-600 sat at 0.071, half the
separation and close enough to be mistaken for an error (owner ruling
2026-08-06). `--bb-text-warn` paints the messages in the `aria-live` region
and IS real text, so it keeps the ≥4.5:1 budget (amber-700, 5.0:1). A single
token dark enough for the copy browns the chrome, so there are two. Every form control
takes `warnings` (messages, also referenced from the control's
`aria-describedby` while displayed) and `hasWarning` (force the chrome),
mirroring `errors`/`hasErrors`; `errors` win and suppress warnings when both
are set. It is deliberately **not** a badge/button `warning` _variant_ (those
stay locked — see design-language.md); there is still no
`--bb-success`/`--bb-info`. All three status tokens carry their own dark-theme
values (rose-400 / amber-500 / amber-500) so 13-14px status text keeps ≥4.5:1
contrast on the dark panel — amber-500 clears both budgets there (5.7:1), so
the chrome/text split is a light-theme distinction only.

**This set is closed by ruling (2026-07-30): state colors are project-owned.**
The library ships `--bb-danger`, `--bb-warn`, and `--bb-text-warn` because its
**own** built-in states consume them (error/warning input chrome and message
text, `destructive` variants) — and it will not grow the vocabulary: no
`--bb-success`, no `--bb-info`, no `--bb-good`, no color ramps or meter/gauge
palettes. A design that needs status color beyond those — a strength meter, a
health score, an SLA bar, a capacity gauge, a multi-step ramp — mints its
**own** accents in project CSS (the local-`--accent` recipe in
design-language.md's soft-palette section is the sanctioned shape). Reusing
`--bb-danger`/`--bb-warn`/`--bb-text-warn` inside project CSS is allowed —
they are ordinary custom properties — but that reuse is the project's call and
the project's contrast budget; the library only promises their meaning within
its own components.

**`--bb-primary-fg` auto-contrasts.** Where the browser supports CSS
`contrast-color()`, `--bb-primary-fg` is derived to black or white — whichever
reads on `--bb-primary` — so setting only `--bb-primary` still yields legible
text/icons on primary fills. The light/dark values in the table are the
**fallback** used when `contrast-color()` is unsupported; a theme that targets
those browsers should set a matching fallback for its brand color. Setting
`--bb-primary-fg` explicitly always wins over both (normal cascade), so a theme
can pin an exact foreground.

### Derived colors (follow the knobs automatically; still overridable)

| Token                | Formula (all `in oklab`)                                     | Used for                                                                                                                                                                        |
| -------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--bb-muted`         | `mix(var(--bb-text) 6%, var(--bb-panel))`                    | Static subtle fills: disabled surfaces                                                                                                                                          |
| `--bb-track`         | `mix(var(--bb-text) 15%, var(--bb-panel))`                   | Recessed control-track surface (switch/slider rails, input wells) — a distinct surface that must contrast a panel-coloured thumb, so it sits **above** the 2/4/6/8 chrome fills |
| `--bb-hover`         | `mix(var(--bb-text) 4%, var(--bb-panel))`                    | Hover fill for **affordances** — ghost/outline buttons, pagination, nav links                                                                                                   |
| `--bb-surface-hover` | `mix(var(--bb-text) 2%, var(--bb-panel))`                    | Hover fill for **passive surfaces** — table rows, list items, picker day cells (fainter)                                                                                        |
| `--bb-pressed`       | `mix(var(--bb-text) 8%, var(--bb-panel))`                    | Neutral pressed/active fill                                                                                                                                                     |
| `--bb-text-muted`    | `mix(var(--bb-text) 60%, transparent)`                       | Secondary text, icons, placeholders, hints                                                                                                                                      |
| `--bb-text-faint`    | `mix(var(--bb-text) 45%, transparent)`                       | Disabled foregrounds                                                                                                                                                            |
| `--bb-ring`          | `mix(var(--bb-primary) var(--bb-ring-opacity), transparent)` | Focus ring — primary & link variants                                                                                                                                            |
| `--bb-ring-danger`   | same formula over `--bb-danger`                              | Focus ring in error states (destructive)                                                                                                                                        |
| `--bb-ring-warn`     | same formula over `--bb-warn`                                | Focus ring in the warning input state (`hasWarning`)                                                                                                                            |
| `--bb-ring-neutral`  | same formula over `--bb-text`                                | Focus ring for the neutral variants (secondary/outline/ghost) — grey, never primary-tinted                                                                                      |

These neutral-chrome percentages (2/4/6/8) are deliberately off the emphasis
ladder: they live only in `variables.css`, which the checker exempts as the
home of the sanctioned derivation formulas.

### The page canvas — deliberately not a token

Every surface token above bottoms out at `--bb-panel`, which is a **raised
surface** (cards, inputs, popovers, dialogs). There is deliberately **no
page-canvas token** — no `--bb-bg`, `--bb-canvas`, `--bb-background`, `--bb-page`.
This is the same posture as the closed status vocabulary above: the library ships
tokens only for surfaces its **own** components paint; the page **behind** those
components is the project's to own.

Just as important, **the library paints no page background at all.** It sets no
`background` on `html`, `body`, or `:root`. Instead it declares
`color-scheme: light` / `dark` on the theme classes (`.light` / `.dark`), which
ties the **browser's UA canvas** — the default fill behind any element with no
authored background — to the active theme. So the correct default is to **author
no page background** and let the UA canvas show through: it is theme-correct and
**flips automatically** when the theme toggles, with zero tokens and zero CSS.
An app that never paints `body` gets dark mode right for free.

You only need a token when you deliberately want a **tinted/recessed canvas** —
a subtly off-panel page so white cards visibly float above it. That is a project
decision, so mint it in project CSS. The one rule: **make it dark-aware**, or a
light-only value will leave your headings unreadable the moment the theme flips.
The safe way is to derive it from the theme tokens so it flips on its own, rather
than hardcoding a hex:

```css
/* Project CSS — a recessed canvas that flips with the theme for free,
   because it is mixed FROM --bb-panel/--bb-text, which the theme redefines. */
:root {
	--app-canvas: color-mix(in oklab, var(--bb-text) 3%, var(--bb-panel));
}
body {
	background: var(--app-canvas);
}
```

Reusing `--bb-panel`/`--bb-text` this way is fine — they are ordinary custom
properties — but the canvas name, its tint, and its contrast budget are yours;
the library only promises the meaning of its own surface tokens.

A theme builder normally never touches these — they track the knobs. They are
tokens (not inlined formulas) because they are consumed in dozens of places,
and because each is a **pinnable scale step**: a theme that wants
Radix-precision grays can override any of them with a hand-tuned value while
cheap themes keep the derivation. Components with a multi-step neutral
progression (e.g. the secondary button's rest→hover→pressed) write the raw
ladder formulas instead of these tokens, so a state name never lies.

### Shape & elevation

| Token                 | Default                                  | Notes                                                               |
| --------------------- | ---------------------------------------- | ------------------------------------------------------------------- |
| `--bb-radius`         | `8px`                                    | THE knob — controls tier: buttons, inputs, tab strips               |
| `--bb-radius-surface` | `calc(var(--bb-radius) * 1.8)`           | Surfaces tier: dialogs, off-canvas sheets                           |
| `--bb-radius-sm`      | `max(4px, calc(var(--bb-radius) * 0.6))` | Nested-bits tier: table controls, toast close, calendar footer btns |
| `--bb-border-w`       | `1px`                                    |                                                                     |
| `--bb-ring-size`      | `2px`                                    | Focus ring thickness                                                |
| `--bb-shadow`         | soft 2-layer                             | The single elevation shadow                                         |

Radius is tiered **by role, not by size**; both extra tiers derive from the
one knob (still individually pinnable). Two more radius rules: concentric
nesting is always `outer radius − padding` (the tabs pill), and per-size
ramps inside a component (badge, chip) derive from `--bb-radius` with
multipliers — never literals.

### Scale

| Token            | Default | Notes                                                                                                                                                                                                                                                                                         |
| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--bb-control-h` | `32px`  | Master control height. Inputs are exactly this; buttons/tabs derive their size scale from it via `calc()` offsets                                                                                                                                                                             |
| `--bb-fs`        | `14px`  | Master font size. Component font sizes derive via `calc()` offsets                                                                                                                                                                                                                            |
| `--bb-panel-p`   | `16px`  | Content padding of large surfaces (dialog, off-canvas; header/footer paddings derive from it). Axis split via the component locals `--px`/`--py` on `.bb-dialog` / `.bb-offcanvas`, each branching off `var(--bb-panel-p)`; set the pair (on the component's class) only when the axes differ |

### Motion

| Token                       | Default                                                |
| --------------------------- | ------------------------------------------------------ |
| `--bb-transition-immediate` | `0s` — motion off (see below)                          |
| `--bb-transition-fast`      | `150ms` — micro-interactions                           |
| `--bb-transition-medium`    | `250ms` — overlays, most moves                         |
| `--bb-ease`                 | `cubic-bezier(0.4, 0, 0.2, 1)` — the only easing curve |

(`--bb-transition-slow`: `350ms`, for large-surface consumer animations —
the library itself uses `medium` for those.)

**`--bb-transition-immediate` is not a fourth speed — it is OFF**, and it exists
so the `prefers-reduced-motion` branches name what they are doing instead of
each hardcoding a magic `0.01ms`. That idiom exists only to keep `transitionend`
firing when a transition is effectively cancelled; nothing in this library
listens for that event, so the token is a true `0s`. If you override it, override
it to another instant value — a consumer who sets it to `200ms` has re-enabled
motion for people who asked for none.

**Durations are a closed ladder.** Reach for a token, never a raw `0.2s`. A value
that genuinely has no token on the ladder is a signal to discuss the ladder, not
to hardcode past it.

### Overlays

| Token               | Default            | Notes                               |
| ------------------- | ------------------ | ----------------------------------- |
| `--bb-overlay`      | `rgb(0 0 0 / 0.1)` | Backdrop dim color+opacity in one   |
| `--bb-overlay-blur` | `2px`              | Backdrop blur                       |
| `--bb-z-overlay`    | `10`               | Overlay z-index                     |
| `--bb-arrow`        | `1`                | Popover arrows on (`1`) / off (`0`) |

### Input family

Form controls are ~half the library and must agree with each other, so their
shared metrics are global — but they derive from the scale knobs:

```css
--bb-input-h: var(--bb-control-h);
--bb-input-h-compact: calc(var(--bb-control-h) - 4px);
--bb-input-px: 8px;
--bb-input-py: 3px;
--bb-input-py-compact: 2px;
--bb-input-spacing: 8px; /* gap between the parts of an input */
--bb-input-icon: 20px; /* prepend/append icon box */
--bb-input-prefix-w: 20px; /* prefix/suffix column */
--bb-input-fs: var(--bb-fs);
--bb-input-fs-mobile: max(var(--bb-input-fs), 16px); /* defeats iOS zoom */
--bb-leading: calc(var(--bb-input-fs) * 1.5);
--bb-label-fs: var(--bb-fs);
--bb-label-fs-sm: calc(var(--bb-fs) - 2px); /* inside & floating labels */
--bb-label-weight: 500;
--bb-label-spacing-y: 6px; /* compact derives: - 2px */
--bb-label-spacing-x: 8px;
--bb-label-lh: calc(var(--bb-label-fs) + 4px);
--bb-label-lh-sm: max(16px, calc(var(--bb-label-fs-sm) * 1.5));
```

The theme layer stays small — **91 `--bb-*` tokens** today (the number
`npm run check:tokens` prints; the canonical, complete list is
`src/assets/css/variables.css`), down from ~140 in v2. The blocks above show the
representative groups, not every token.

## Tier 2 — component tokens (`--*`)

Defined on the component's **root class** in the component's own CSS file.
Rules:

1. **No `--bb-` prefix.** Ever.
2. **A token must be defined in the same file that consumes it** (usually on
   the root class). Since custom properties inherit, this is what prevents a
   `--gap` set by an outer component from leaking into an inner one — every
   component seals itself.
3. **Short names are for self-consumption only.** `--h`, `--px`, `--gap`,
   `--fs`, `--r` are fine while the rules using them target the component's
   own boxes. If a value must be read _inside a nested foreign component_,
   prefer moving the formula to an element the component owns, or a
   distinctive name. One ruled exception (2026-08-25): the dialog/off-canvas
   padding pair `--px`/`--py` is read by the nested close button's inset
   formula — safe because `BbCloseButton` declares neither, a constraint that
   component must keep (minting `--px`/`--py` there would silently mask the
   surface's value and break the inset).
4. **Mint only what varies.** A size variant that overrides four locals is
   four tokens, not four × six sizes. Per-size lookup tables
   (`--h-xs … --h-2xl`) are allowed only when a responsive matrix genuinely
   needs to re-point them.
5. **JS bridges use the same short names.** A value measured/parsed in JS and
   set as an inline style (dropdown width, popover max height, icon size)
   is just another component token: `--w`, `--max-h` — never
   `--dropdown-width`. The component-name prefix bought nothing (a nested
   dropdown inherits `--dropdown-max-height` exactly as easily as `--max-h`);
   what actually protects the name is sealing — consume it with a fallback
   (`var(--max-h, none)`) or declare a default on the root class
   (`--w: initial` on `.bb-icon`), so an ancestor's value can never inherit
   in. Cross-component bridges (ListBox publishing `--option-height` for
   SelectPopover to read) keep a distinctive name per rule 3.

Component tokens are still real affordances: a consumer can retune one
instance (`<BbTabs style="--list-h: 40px">`) or a whole page scope. They are
just not global namespace.

### Overriding one from a consumer app

Three rules, in order of how often they are broken.

**1. Override only what you actually render.** Several components expose a
per-size lookup table (`--icon-size-xs … --icon-size-2xl`, `--h-xs … --h-2xl`)
plus an _active_ token the size class re-points. Setting the whole family
because you want one value is not "thorough" — it silently opts you out of the
size scale for variants you may start using later, and it buries the one line
that mattered. Retune the sizes you use:

```css
/* we render sm and md buttons; leave the rest on the library's scale */
.bb-button {
	--icon-size-sm: 12px;
	--icon-size-md: 12px;
}
```

**2. Override the per-size entry, not the active token.** The active token is
re-resolved by the size class, which is _more specific_ than the root class:

```css
.bb-button {
	--icon-size: var(--icon-size-md);
} /* 0,1,0 */
.bb-button--sm {
	--icon-size: var(--icon-size-sm);
} /* 0,2,0 — nested */
```

So `.bb-button { --icon-size: 12px }` appears to work on default buttons and
silently does nothing on every `size="sm"` one — the confusing half-failure that
sends people to the shotgun in rule 1. The per-size entry has no competing
declaration, so it always wins. (A scope selector of equal-or-greater
specificity also works, but you have to keep winning that race; overriding the
entry does not.)

**3. Scope it to the component, never `:root`.** Short names are deliberately
reused across components — `--icon-size` is read by `BbButton`, `BbBadge` and
`CloseIcon`; `--gap`, `--px`, `--h` are everywhere. Hoisting one to `:root`
retunes every component that happens to share the name, which is exactly what
tier-2's sealing rule exists to prevent. Put it on the component's class, a page
scope, or the instance's `style=`.

## The emphasis ladder

All translucency/tinting goes through **one ladder** of `color-mix()`
percentages. No other percentages are allowed in a `color-mix()` with a
semantic color:

| Stop  | Meaning                               | Example                            |
| ----- | ------------------------------------- | ---------------------------------- |
| `8%`  | Resting tint fill                     | secondary button bg, tab strip     |
| `15%` | Hover tint fill                       | secondary/destructive button hover |
| `25%` | Pressed/selected tint, tinted borders | `aria-pressed` bg, danger border   |
| `45%` | Disabled foreground, placeholder-ish  | disabled button text               |
| `60%` | Muted text (= `--bb-text-muted`)      | secondary copy, icons              |
| `75%` | Strong-but-secondary foreground       | toast icon, alert secondary copy   |

Two composition modes, chosen by context:

```css
/* Opaque fill — when the element owns its background */
background: color-mix(in oklab, var(--accent) 8%, var(--bb-panel));

/* Translucent fill — when it must sit on an unknown background */
background: color-mix(in oklab, var(--accent) 8%, transparent);
```

Solid (non-tinted) interactive surfaces darken instead:

```css
&:hover {
	background: color-mix(in oklab, var(--accent) 90%, black);
}
&:active {
	background: color-mix(in oklab, var(--accent) 80%, black);
}
```

### The state recipe

Every interactive component follows the same four-state progression:

| State    | Neutral chrome (default)                 | Tinted variants (danger, selected) | Solid variants | Plus                                                   |
| -------- | ---------------------------------------- | ---------------------------------- | -------------- | ------------------------------------------------------ |
| rest     | transparent (or `8%` if filled)          | `8%`                               | `100%`         |                                                        |
| hover    | `var(--bb-hover)`                        | `15%`                              | `90% + black`  |                                                        |
| pressed  | `var(--bb-pressed)`                      | `25%`                              | `80% + black`  |                                                        |
| focused  | hover/pressed values                     | hover values                       | hover values   | `box-shadow: 0 0 0 var(--bb-ring-size) var(--bb-ring)` |
| disabled | bg `var(--bb-muted)`, fg at the 45% stop | same                               | same           | `cursor: not-allowed`                                  |

Per principle 5, the tinted column applies only to states that _mean_
something — danger variants and brand-selected states — never to plain
interaction chrome. Error variants swap the accent
(`--accent: var(--bb-danger)`) and the ring (`--bb-ring-danger`) — nothing
else changes.

## Dark mode

One name per token. `:root`/`.light` declares light values; `.dark`
re-declares **only the knobs that change** (primary, primary-fg, panel, text,
border, ring opacity). Component tokens and ladder formulas follow
automatically because they are declared on the components themselves. The
old `--x-light`/`--x-dark`/`--x` triple is gone.

The `:root`/`.light` and `.dark` blocks also each set the UA `color-scheme`
(`light` / `dark`) alongside the tokens. This is deliberate and load-bearing:
`color-scheme` governs not just form-control chrome but the **default canvas
fill** of any element with no authored background. Declaring it unconditionally
as `light dark` (letting the browser pick from the OS/browser appearance
preference) would decouple it from this library's actual class-based active
theme — a `.dark`-classed document under a light OS preference would flip
`--bb-text` to white while the UA canvas underneath any unpainted region
stayed white too, making transparent-background elements (outline/ghost
buttons) invisible. `color-scheme` therefore always follows the class, never
`prefers-color-scheme` directly.

One CSS mechanic to respect: **a custom property resolves its `var()`
references on the element where it is declared, not where it is consumed.**
That is why the derived color tokens (`--bb-hover`, `--bb-ring`…) are
declared on _both_ scheme scopes in variables.css — declared only on
`:root` they would bake in the light knobs and `.dark` would inherit stale
values. The same applies to consumers: overriding a knob on an arbitrary
scope (`.brand { --bb-primary: … }`) does not re-derive them — re-apply the
`light`/`dark` class on that scope, or override the derived tokens directly.
Root-level theming (what the theme builder emits) is unaffected.

### Registered knobs (`@property`)

Nine tokens are registered in `variables.css`: the eight color knobs with
`syntax: '<color>'`, and `--bb-ring-opacity` with `syntax: '<percentage>'`.
All are `inherits: true`.

**Registration types them, and a typed property rejects.** A declaration that
does not parse as the declared syntax is invalid at computed-value time — the
value is discarded, and because these inherit, an override at `:root` (no
parent to inherit from) lands on the registered `initial-value`. That is the
fail-soft half: an unparseable `--bb-panel` falls back instead of detonating
every derivation that mixes it. It is also the trap. Write

```css
:root {
	--bb-ring-opacity: 0.15;
} /* wrong: not a <percentage> */
```

and nothing errors — not the build, not the console. The declaration is
discarded and the token lands on the registered `initial-value: 15%` — which
happens to be the very value this override asked for, so a light page looks
right by accident. Write `0.4` on a dark page instead and the ring quietly
drops from the shipped `40%` to `15%` (opacity is the ring's strength; its
thickness is `--bb-ring-size`).
Percentages need the `%`; colors must be a `<color>` (`transparent` and
`currentColor` qualify, `none` and a mistyped hex do not). Nothing in the
toolchain catches it either: `bitboss-ui check` reads `.vue`/`.md`, never
stylesheets.

Fail-soft is only soft when the initial value is close to the real one. Every
registered knob — `--bb-ring-opacity` included — is registered at its light
default, so a rejected override renders the library's own light theme. On a
dark page that is still visible: a rejected `--bb-ring-opacity` lands on the
light `15%` against the shipped dark `40%`.

Typed knobs are also **animatable**. Add `.theme-animated`
(main.css) to the element that carries the scheme class or theme overrides:

```html
<html class="theme-animated dark"></html>
```

Scheme toggles and theme-builder changes then crossfade over
`--bb-transition-medium`; every derived mix re-derives per interpolated
frame. The class must sit on the same element as the toggle (a transition
only runs where the property changes), it owns that element's `transition`,
and the whole subtree repaints while it runs — a deliberate cost for
toggles/previews, so it stays opt-in. Browsers without `@property` simply
switch instantly. Component tokens stay unregistered (see "Why not
`@property`").

This is also the theme-builder contract: a theme is _two small blocks of the
same ~10 declarations_. Changing `--bb-primary`, `--bb-radius`,
`--bb-control-h`, `--bb-panel`, `--bb-danger` overhauls the entire library
with no other edits.

## Reading tokens outside CSS

Charts, `<canvas>`, and WebGL consumers (ECharts, Chart.js, D3, three.js, …)
don't go through the cascade — they read a token's computed value as a string
and parse it themselves. That is a trap: **21 shipped `--bb-*` tokens are
`color-mix(in oklab, …)` values** (`--bb-text-muted`, `--bb-text-faint`,
`--bb-muted`, `--bb-hover`, `--bb-pressed`, `--bb-track`, the `--bb-secondary*`
/ `--bb-destructive*` / `--bb-ring*` families, `--bb-primary-hover` /
`--bb-primary-pressed`, `--bb-surface-hover`), and neither obvious JS read path
hands back something a color parser accepts:

- `getComputedStyle(el).getPropertyValue('--bb-text-muted')` returns the
  **unresolved** token string — `color-mix(in oklab, rgb(0, 0, 0) 60%,
transparent)` — because custom properties don't get `var()`/`color-mix()`
  substitution from `getPropertyValue`.
- `getComputedStyle(el).color` (having set `color: var(--bb-text-muted)`)
  _does_ resolve the mix, but Chromium serializes the result as
  `oklab(0.599996 0.0000273407 0.0000120521)` — a syntax most canvas-based
  chart libraries never learned to parse, because `oklab()` is younger than
  their color parser.

Both strings reach a canvas `fillStyle` (or an SVG/WebGL color uniform) as
garbage input. The failure mode is worse than an error: canvas **silently
ignores** an unparseable `fillStyle` and keeps whatever color was already set
— so a chart doesn't throw, it just paints the _previous_ color, or black on
a fresh context, with nothing in the console to point at why.

**The fix is to resolve through the one thing that already understands every
CSS color: an offscreen canvas.** Set the token as `fillStyle` on a 1×1
canvas 2D context, `fillRect`, then read the pixel back with
`getImageData` — the browser's own color parser does the work, and the
output is a plain `rgba()` any chart library can consume:

```ts
function resolveCssColor(value: string): string {
	const canvas = document.createElement('canvas');
	canvas.width = canvas.height = 1;
	const ctx = canvas.getContext('2d')!;
	ctx.fillStyle = '#000'; // known baseline, so a silent no-op is detectable
	ctx.fillStyle = value; // browser parses+resolves here; invalid input is ignored
	ctx.fillRect(0, 0, 1, 1);
	const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
	return `rgba(${r}, ${g}, ${b}, ${(a / 255).toFixed(3)})`;
}

// pass the *resolved* token, not the raw custom property:
resolveCssColor(
	getComputedStyle(el).getPropertyValue('--bb-text-muted').trim()
);
```

**Rule: never pipe a raw `--bb-*` custom-property string into a chart
config.** Resolve every color you read this way — including plain-looking
ones. The eight brand knobs registered with `@property … syntax:"<color>"`
(`--bb-primary`, `--bb-danger`, `--bb-panel`, `--bb-text`, …) happen to
compute to ordinary `rgb()` today and look safe to pipe straight through, but
nothing marks a token as "derived" from the outside — a consumer who resolves
only the obviously-mixed tokens and pipes `--bb-text-muted` or
`--bb-text-faint` raw still gets bitten, because those two are exactly the
ones a dashboard reaches for first (axis labels, legends, muted marks). Treat
`resolveCssColor()` as the mandatory last step for **every** token a
canvas/WebGL consumer touches, not a spot-fix for the ones you noticed were
mixes.

## Safe areas (occupied edges)

Toasts avoid open off-canvas panels: a bottom sheet pushes bottom toasts up,
a right panel pushes right-anchored toasts left, and so on per edge — in
step with the panel's slide. The model (implemented in
`src/composables/useSafeArea.ts`, read by `BbToastRegion`):

- **Claims are "occupied up to X px from this screen edge"**, derived from
  the off-canvas stack registry (direction + measured size + stack peeks),
  and composed by `max`, never sum — a claim measures from the screen edge,
  so nothing double-counts.
- **Priority is one-directional: sheets claim, toasts yield.** A
  deliberately-opened surface never moves for an unsolicited notification.
- **Last-ditch rule, per axis:** when a claim leaves the stack no room
  (claim + stack extent + margins > viewport), the toast stops yielding on
  that axis and overlaps the sheet instead.
- **Settle, not per-frame:** claims update on open/close/resize; a live drag
  rides on `transform` and never touches the registry.
- **Edge scalars, not corner lanes:** a bottom claim spans the whole bottom
  edge. Corner-aware lanes were considered and deferred (every OS insets
  system ships edge scalars; the over-yielding failure mode is mild).
- Centered dialogs claim nothing. Adaptive picker sheets currently claim
  like any off-canvas — revisit if toasts jumping under open selects proves
  more distracting than overlap.

**The rejected public half (recorded so it isn't re-litigated blind):** an
earlier design published composed totals as `--bb-safe-*` tokens so consumer
floating UI (a FAB) could dodge sheets and be "gently pushed" by toasts.
Dropped because every surface here is _modal_ — the backdrop covers and
inerts the page, so consumer UI can't be interacted with while a claim
exists; helping it dodge is pointless. Reopen if either lands: non-modal /
inline docked panels, or persistent floating consumer UI that should dodge
_toasts_ (Material's snackbar-pushes-FAB rule — toast claims do interact
with live UI). The public shape would be `--bb-safe-top/right/bottom/left`
on `:root` defaulting to `env(safe-area-inset-*)`, with explicit claim
priorities. The mobile keyboard can join as another bottom claimant with no
API change.

Top-layer & inertness note: a modal (`showModal()`) makes everything outside
itself **inert** — and inertness follows DOM ancestry, not paint order, so a
body-hosted toast region can render above a modal yet be frozen to input.
BbToast therefore teleports its regions _into_ the top-most open modal
(BbDialog and BbOffCanvas register with `useTopLayer`), and each region
re-shows its popover after the move (a DOM move auto-hides popovers; the
re-promotion also keeps toasts painted above the host). Regions re-home to
`<body>` when the last modal starts closing. Being top-layer popovers, they
escape the host dialog's `overflow: hidden` and centering transform.

## Migration from the old tokens

| Old                                                                                                                                                              | New                                                                          |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| primary-tinted hovers/pressed fills (`mix(--bb-primary 8-25%, --bb-panel)`)                                                                                      | `--bb-hover` / `--bb-pressed` (neutral, text-derived)                        |
| `color-mix(in srgb, …)`                                                                                                                                          | `color-mix(in oklab, …)` everywhere                                          |
| dialog/offcanvas `--radius-multiplier` ×1.8, literal `6px`/`8px`/`0.375rem` radii                                                                                | `--bb-radius-surface` / `--bb-radius-sm`                                     |
| `--bb-contrasting`                                                                                                                                               | `--bb-primary-fg`                                                            |
| hard-coded `cubic-bezier()` literals (v2 exposed no easing token)                                                                                                | `--bb-ease`                                                                  |
| `--bb-panel-disabled`, `--bb-input-bg-secondary`                                                                                                                 | `--bb-muted`                                                                 |
| `--bb-muted-color`, `--bb-hint`, `--bb-placeholder`, `--bb-icon-color`, `--bb-prefix-color`                                                                      | `--bb-text-muted`                                                            |
| `--bb-input-color`, `--bb-input-bg`                                                                                                                              | `--bb-text`, `--bb-panel`                                                    |
| `--bb-input-font-size` / `--bb-input-mobile-font-size`                                                                                                           | `--bb-input-fs` / `--bb-input-fs-mobile`                                     |
| `--bb-input-compact-h` / `--bb-input-compact-py`                                                                                                                 | `--bb-input-h-compact` / `--bb-input-py-compact`                             |
| `--bb-label-size` / `--bb-label-inside-size` / `--bb-label-floating-size`                                                                                        | `--bb-label-fs` / `--bb-label-fs-sm` (merged)                                |
| `--bb-label-line-height` / `--bb-label-inside-line-height`                                                                                                       | `--bb-label-lh` / `--bb-label-lh-sm`                                         |
| `--bb-overlay-color` + `--bb-overlay-opacity`                                                                                                                    | `--bb-overlay` (one color with alpha)                                        |
| `--bb-overlay-z-index`                                                                                                                                           | `--bb-z-overlay`                                                             |
| inline ring `color-mix()` formulas                                                                                                                               | `--bb-ring` / `--bb-ring-danger` (strength knob: `--bb-ring-opacity`)        |
| `--bb-dialog-px/pt/pb/gap/…`                                                                                                                                     | `--bb-panel-p` + the local axis pair `--px`/`--py` on the surface roots      |
| `--bb-button-*`, `--bb-tabs-*`, `--bb-checkbox-*`, `--bb-radio-*`, `--bb-switch-*`, `--bb-rating-*`, `--bb-slider-*`, `--bb-table-cell-h`, `--bb-progress-track` | unprefixed locals in each component's CSS                                    |
| `--bb-table-offset-*` (JS plumbing)                                                                                                                              | unprefixed locals on `.bb-table` (`--offset-*`)                              |
| `--bb-table-fill`, `--bb-table-natural-width`                                                                                                                    | **removed** with the grid substrate — nothing publishes them any more (v3.0) |
| `--bb-table-{id}-track-{key}` (parent→nested width bridge)                                                                                                       | `--table-{id}-track-{key}` (distinctive cross-component name, rule 3)        |
| `--bb-select-option-*`, `--bb-primary-base`, all `--x-light`/`--x-dark` shadows                                                                                  | deleted (dead)                                                               |

**This table maps names, not values.** A token that is absent from it survived
the rename — which is not the same as surviving unchanged. Six kept their v2
name and their global scope and moved default anyway (input height, input
vertical padding, prefix column width, label weight, ring size, leading); the
before/after numbers are tabled in the v2→v3 migration guide, §3. The rule
generalizes past this migration: a `--bb-*` name is a slot in the derivation
graph, not a promise about the number in it. An override you carried forward
keeps working and keeps your old look; an override you deleted because "the
name still exists" hands you whatever `variables.css` declares today. Check
each survivor against `variables.css` and delete only the ones that were
restating a default.

## Enforcement

`npm run check:tokens` (see `scripts/check-tokens.mjs`) fails the build when:

- a file _introduces_ a `--bb-*` name outside `variables.css` (re-declaring a
  known theme token at a scope is fine — that's theming);
- a `--bb-*` token is consumed but not declared in `variables.css`;
- a component CSS file consumes an unprefixed token it never declares and
  without a `var()` fallback (seal-rule violation; tokens that are JS-set or
  inherited by design are annotated with an `/* @inherit --name */` note);
- a `color-mix()` over a token is not `in oklab`, or uses a percentage off
  the ladder (8/15/25/45/60/75 + 80/90; 0/100 anchors allowed).
  `variables.css` itself is exempt — it hosts the sanctioned derivation
  formulas (`--bb-muted` at 6%, `--bb-hover` at 2%).

### Why not `@property`?

Registering component tokens (`@property --w { inherits: false; … }`) looks
like it would replace the seal rule structurally, but it breaks the system:

- `inherits: false` stops the root→descendant flow _inside_ a component
  (declare on `.bb-base-switch`, consume on `__icon` — that is inheritance),
  which is also what makes `style="--list-h: 40px"` overrides work. CSS
  cannot express "inherit within my subtree but not into nested components".
- A registered property always has a value, so `var(--max-h, none)`
  fallbacks never fire again — our sealing pattern dies.
- Registrations are page-global, one meaning per name per document. Short
  names are deliberate local homonyms here (`--w` is icon width, dropdown
  width, switch width; one must inherit, one must not), and a library
  registering `--w`/`--gap`/`--size` tramples the host page's names.

## Open questions (iterate here)

- Should `--bb-danger-fg` exist for a future solid-danger button, or is the
  tinted destructive variant the only sanctioned form?
- Is `--bb-control-h` the right master, or should it be `--bb-density` with
  controls deriving both height and paddings from it?
- Should `--bb-bg` (page background) exist as a third neutral anchor, so
  page↔panel contrast is a managed relationship? Currently no consumers.

---

<!-- dist/ai/guides/fetch-items-playbook.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/fetch-items-playbook.md -->

# Fetch Data Items Playbook

Use this playbook when `items` is dynamic: pass a **function** instead of an array and the component runs it, tracks loading, and discards stale responses. Static arrays bypass the provider entirely.

Companions: [Options and Items](./options-items-playbook.md) (mapping, seeding), [Coherence](./coherence-playbook.md) (what happens to `modelValue` when fetched options change).

## Provider signatures (as implemented)

### Query-aware — `BbSelect`, `BbSelectPopover`

```ts
type QueryItemsProvider<T> = (
	query: string,
	prefill: boolean,
	modelValue: any // your v-model: array when `multiple`, single value otherwise
) => T[] | Promise<T[]>;
```

`modelValue` is your v-model passed as-is, and the prop declares it `any`: an array in `multiple` mode, the raw model value (possibly `null`) in single mode. Annotate it `any` (or your own model type) and branch on the shape you know you passed.

### Non-query — `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`, `BbTable`

```ts
type ItemsProvider<T> = (
	prefill: boolean,
	modelValue?: any // groups: the v-model; BbTable: the current selection
) => T[] | Promise<T[]>;
```

### `BbDropdown` pipeline groups

```ts
type DropdownGroupItemsGetter = (
	prefill: boolean,
	modelValue?: any // the group's selection: array when `multiple`, single value otherwise
) => any[] | Promise<any[]>;
```

The same non-query shape as groups and `BbTable`. `modelValue` is the group's current selection — the `<BbDropdownGroup>` `v-model` when there is a companion. Read anything else the request needs (filters, the parent record) from your own refs.

## When each provider runs (verified call matrix)

| Trigger                            | `BbSelect` / `BbSelectPopover`                                                                         | Groups                                      | `BbTable`                     | Dropdown pipeline group            |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------- | ----------------------------- | ---------------------------------- |
| Initial load                       | `(query, true, modelValue)` — see `prefill` prop below                                                 | `(true, modelValue)` on mount               | `(true, selected)` on mount   | `(true, modelValue)` on first open |
| User types in the search field     | `(query, false, modelValue)`, debounced `query-debounce-time` (default 500ms)                          | —                                           | —                             | —                                  |
| `dependencies` (or `items`) change | `(query, true, modelValue)`, debounced `deps-debounce-time`                                            | `(true, modelValue)`, debounced             | `(true, selected)`, debounced | `(true, modelValue)`, debounced    |
| External `modelValue` change       | `(query, true, modelValue)` — only when the value is incoherent, debounced `model-value-debounce-time` | `(true, modelValue)` — only when incoherent | —                             | —                                  |

**`prefill === false` means exactly one thing, everywhere: _the user typed_.** Every fetch a component starts itself — mount/first-open load, dependency change, coherence refetch — passes `true`, and expects the current selection to stay resolvable in the response. Components without a search field (groups, `BbTable`, dropdown groups) therefore always pass `true`; the argument is in their signature so one provider can be shared with a `BbSelect` and branch identically.

The corollary: **`prefill` cannot tell you an initial load from a dependency refetch.** If a provider must reconcile the selection against a new result set, do it on every call (your provider closes over the filter, so it already knows what it is fetching) — see the `BbTable` pattern below. A dropdown group the user never opens still never fetches.

### The `prefill` prop (`BbSelect` / `BbSelectPopover`)

`prefill` controls **when** the initial load happens: `'interaction'` (default) waits for the first user interaction, `true` loads on mount (SSR-friendly — it also runs in `onServerPrefetch`), `false` is **search-first** — nothing loads until the user types, so opening the panel fetches nothing and the list shows a "search to begin" hint until the first query. Groups and tables always load on mount.

Reach for `false` when the result set is too large or expensive to browse and the query is the only sensible entry point. Note that `false` and `'interaction'` differ **only** on this point: both skip the mount load, but `'interaction'` fetches on open and `false` waits for a query.

Four cases ignore `prefill` and load anyway, because deferring would buy nothing or break a promise you made:

- **`items` is an array** — there is no request to defer, so the selection resolves on mount and coherence can run immediately.
- **`enforce-coherence` over a non-empty model** — validating a value is impossible without options. An empty model stays lazy (empty is always coherent).
- **`false` + writing disabled** — `disable-writing` hides the search field, so a search-first load could never be triggered. Falls back to loading on open.
- **`false` + a non-empty model** — the selection's text has to resolve to render. Falls back to loading (on mount for `BbSelect`, per the upgrade below).

`BbSelect` additionally upgrades any non-empty model to an immediate prefill so the in-field selection can render its text. A standalone `BbSelectPopover` does **not**: with a _provider_ and no `enforce-coherence`, a seeded model stays lazy and resolves on first open. Don't reach for `prefill: true` to fix that — the trigger is yours, so label it from your own state ([BbSelectPopover guide](../BbSelectPopover.md)).

## Runtime guarantees

- **Race protection**: out-of-order responses are discarded — only the latest request may write `items`.
- **Loading**: the component tracks in-flight requests itself; don't add your own `loading` ref for option fetching.
- **Errors**: a rejected provider is logged (`console.error`) and the previous items are kept. Surface fetch failures yourself (e.g. `useToast`) if the user must know.
- **Dependency comparison is value-based** (hashed), not reference-based — `:dependencies="[filters]"` re-fetches only when the content actually changes, no matter how often the array identity does.

## Canonical provider patterns

Query components — branch explicitly and return the **same item shape** from every path:

```ts
const searchMembers = async (
	query: string,
	prefill: boolean,
	modelValue: string[]
): Promise<Member[]> => {
	// Component-initiated: keep the current selection resolvable.
	if (prefill && modelValue.length) {
		return api.members.byIds(modelValue);
	}
	if (!query.trim()) return []; // project-defined idle behavior
	return api.members.search({ query });
};
```

Non-query components (groups, `BbTable`, dropdown groups) — same shape minus `query`, selection-aware. `prefill` is always `true` here; it exists so the provider can be shared with a select:

```ts
const fetchRoles = (_prefill: boolean, selected?: string[]) =>
	api.roles.list({ selectedIds: selected });
```

`BbTable` **does** ship `enforce-coherence` (ruled C.12, 2026-07-16): turn it on and, after every load, row-keyed models drop the entries the new result set no longer contains. Reach for it before writing reconciliation by hand — the provider only owns the cases the prop cannot see. Do it unconditionally — `prefill` won't tell you a refetch from the initial load, and the provider already closes over the filter that changed:

```ts
const fetchMembers = async (_prefill: boolean, selectedIds?: string[]) => {
	const rows = await api.members.list({ role: role.value });
	if (selectedIds?.length) {
		selected.value = selectedIds.filter((id) => rows.some((r) => r.id === id));
	}
	return rows;
};
// <BbTable v-model="selected" :items="fetchMembers" :dependencies="[role]" ... />
```

`BbTable` on a server-driven screen — forward the page state and refetch via `dependencies` (never a manual `watch`):

```ts
const fetchInvoices = async (): Promise<Invoice[]> => {
	const res = await api.invoices.list({
		search: search.value,
		status: status.value,
		orderBy: sort.value, // the v-model:sort array, forwarded as-is
		page: page.value,
	});
	totalItems.value = res.total;
	return res.data;
};
// <BbTable :items="fetchInvoices" :dependencies="[search, status, sort]" ... />
// page is NOT listed: a provider table already refetches when the shared
// (table-id) page moves — list only your own filters and sort here.
```

## Idle-state decisions (query components)

- **Empty query, nothing selected**: return `[]` (explicit empty state) or a default/sample list (guided discovery). Pick one per app and keep it deterministic.
- **Empty query, values selected**: return at least the selected items (alone or merged with a default list) so the selection is never orphaned. Enabling `stash` on the select keeps already-picked options resolvable across searches without re-including them in every response.
- Fill the panel states with `loading-text` / `no-data-text` (or the `#loading` / `#no-data` slots).

## What's idiomatic now

- The `prefill` flag means the same thing in every family: `false` only when the user typed. It is **not** "initial load" — a dependency refetch also passes `true`, so never use it to detect one (see the call matrix).
- Seed multiple-mode `v-model`s with arrays before wiring a provider — multiple components throw on non-array models ([details](./options-items-playbook.md)).
- Coherence work belongs to `dependencies` + `enforce-coherence`, not to defensive code inside the provider. Coherence is **lazy**: a component that has not loaded once (an untouched `prefill: 'interaction'` select, an un-searched `prefill: false` one, a never-opened dropdown group) ignores dependency changes until it does — don't duplicate it with eager watchers ([details](./coherence-playbook.md)). Any first load ends the quiet period, including a user's first search.

## Anti-patterns

- Ad-hoc `watch(filter, refetch)` when `dependencies` already covers it.
- Different item shapes across the prefill/search/idle branches.
- Side effects in the provider beyond the fetch itself (navigation, toasts on success, state writes other than pagination totals).
- Hand-rolled debouncing around the provider — use `query-debounce-time` / `deps-debounce-time` / `model-value-debounce-time`.

## Validation checklist

- [ ] Provider signature matches the component family (query vs non-query vs dropdown).
- [ ] `prefill` and the empty query are handled explicitly, with the family's semantics.
- [ ] All branches return the same item shape.
- [ ] Field-tied fetching uses `dependencies` (+ `deps-debounce-time`), no manual watchers.
- [ ] Selected values stay resolvable on component-initiated calls (or `stash` is enabled on selects).

---

<!-- dist/ai/guides/floating-bottom-panel.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/floating-bottom-panel.md -->

# Floating Bottom Panel

The bulk-action surface of a modern listing page (Linear, Gmail): select
rows and a toolbar **hugs its content and floats up from the bottom**,
showing the count and the actions that apply to the selection; empty the
selection and it slides away. It floats over the content, never pushes
layout, and never stretches edge to edge — a full-bleed bar reads as broken
viewport chrome instead of a response to your selection.

App code, not a `bitboss-ui` export — copy it into your project
(conventionally `src/components/layout/`). The listing recipes wire it to
table selection per platform.

## Where the code is

**The implementation lives in the scaffold recipe, not here.**

- [Layout Scaffold (Vue)](../recipes/vue/layout-scaffold.md)
- [Layout Scaffold (Nuxt)](../recipes/nuxt/layout-scaffold.md)
- [Layout Scaffold (Inertia)](../recipes/inertia/layout-scaffold.md)

Copy the file from there verbatim. Those recipes are generated from the
fixtures this library's own end-to-end suite drives, so the code you copy is
code that is known to run. This guide used to carry its own copy of
`FloatingBottomPanel.vue`; it drifted into a _different_ component — extra
`size`/`label` props that don't exist on the shipped one, and a dark,
raw-hex pill (`#26262a` background, `0 8px 24px rgb(0 0 0 / 0.25)` shadow)
instead of the token-driven, panel-colored surface the recipe actually
ships. One implementation, in one place, is the fix — same as
[Page Shell](./page-shell.md).

The component takes exactly one prop, `open?: boolean` — visibility is a
plain boolean, the panel owns _how_ it appears, the page owns _when_.

## Usage

Inside the panel, `sm` buttons are the right density — this is a compact
toolbar, the documented exception to the `md`-first button rule (see the
[Design Language guide](./design-language.md)).

```vue
<template>
	<FloatingBottomPanel :open="selectedCount > 0">
		<span class="floating-bottom-panel__count"
			>{{ selectedCount }} selected</span
		>
		<BbButton
			prepend:icon="lucide:check"
			size="sm"
			variant="ghost"
			@click="markPaid"
		>
			Mark as paid
		</BbButton>
		<BbButton
			prepend:icon="lucide:send"
			size="sm"
			variant="ghost"
			@click="sendReminders"
		>
			Send reminder
		</BbButton>
		<div class="floating-bottom-panel__right">
			<BbButton size="sm" variant="destructive" @click="deleteSelected"
				>Delete</BbButton
			>
			<BbButton
				aria-label="Clear selection"
				icon="lucide:x"
				size="sm"
				variant="ghost"
				@click="clear"
			/>
		</div>
	</FloatingBottomPanel>
</template>
```

`.floating-bottom-panel__right` is a convention the scaffold's CSS already
keys off of: anything slotted with that class gets a leading divider and
sits at the trailing edge of the bar, so destructive/dismiss actions read as
a separate group from the primary bulk actions.

Where `selectedCount` comes from depends on the platform:

- **Vue / Nuxt** — the library's
  [`useBbTableContext`](../composables/useBbTableContext.md) by table id:
  the bar takes zero props from the table.
- **Inertia** — the app-side selection context from the
  [Inertia Helpers](./inertia-helpers.md) toolkit
  (`useTableSelectionContext`), which also models select-all-across-pages.

The listing recipes show the full wiring, including the confirm-guarded
destructive path and clearing the selection after a bulk action.

## Design notes and enhancements

- **One concern.** The panel is presentation: position, elevation, surface,
  enter/leave motion. Counting, action dispatch and confirmation belong to
  the page (via its selection context) — don't grow props for them here.
- **Actions open surfaces, they don't inline them.** A bulk action needing
  input opens a `BbDialog`/`BbOffCanvas`; destructive ones go through
  `useConfirm` with the count in the message ("Delete 12 invoices?").
- Worthwhile enhancements, left out of the baseline:
  - **Top-layer rendering** via the Popover API (`popover="manual"` +
    `showPopover()` on open) instead of `z-index`, so the bar can never be
    stacked over by page chrome.
  - **Sidebar-aware centering**: offset the bar so it stays centered over
    the _visible_ content rather than the full viewport when an
    [App Layout](./app-layout.md) sidebar or a [Page Shell](./page-shell.md)
    peek panel is open, and compensate for scrollbar width. Neither shipped
    implementation does this today — it centers on the viewport.
  - **Keyboard path**: pair with `useDeleteCmd` from the
    [Inertia Helpers](./inertia-helpers.md) (works on any platform) so
    Delete triggers the same guarded bulk delete.

## Related

- [Recipe: Records Workspace (Vue)](../recipes/vue/records-workspace.md) /
  [(Nuxt)](../recipes/nuxt/records-workspace.md) /
  [(Inertia)](../recipes/inertia/records-workspace.md) — full wiring per
  platform.
- [Page Shell](./page-shell.md) — the per-page chrome this panel floats
  over.
- [BbToast](../BbToast.md) — feedback after a bulk action completes.

---

<!-- dist/ai/guides/icons-policy.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/icons-policy.md -->

# Icons Policy

Mandatory for AI-generated code.

## Rules

1. **Prefer provider icons.** The house UI set is `lucide:*`. Provider sets are
   plain npm packages the consumer sources separately
   (`npm install -D @iconify-json/lucide`); the plugin resolves them
   automatically — no registration step.
2. **`local:*` is for brand-specific art only** — logos, custom marks, one-off
   illustrations. They are SVG files in the configured `iconDir`.
3. **Never invent icon names.** Use only names that exist in an installed
   `@iconify-json/*` set or as files in `iconDir`. A missing icon throws at
   mount (dev shows a Vite error overlay with the exact fix).
4. **Icon names must be static string literals.** Production builds scan source
   for `provider:name` literals and bundle only those — a name assembled at
   runtime (`` `lucide:${kind}` ``) will be missing in production. Map dynamic
   state to literals instead (e.g. a lookup object of full names).
5. **Never hand-place `BbIcon` where a component already accepts an icon** via
   a prop, item field, or dedicated slot (catalog below).

## How resolution works

The `bitbossUi` Vite plugin (`iconDir` option) — or the Nuxt module (config key
`bitboss`, default `iconDir: './assets/icons'`) — serves every icon through the
`virtual:bitboss-ui/icons` module that `bitbossUiPlugin` provides to `BbIcon`:

- **Provider sets**: every `@iconify-json/*` package found in `node_modules` is
  auto-discovered. Installing `@iconify-json/lucide` makes every valid
  `lucide:<name>` available; removing it makes them all errors. Nothing to
  configure.
- **Dev**: all icons of installed sets are registered. Referencing an
  uninstalled prefix or a non-existent name fails loudly with an actionable
  message (`"lucide:fo" requires "@iconify-json/lucide" — run: npm install -D …`
  or `icon "x" does not exist in the lucide icon set`).
- **Build**: source files (`.vue`/`.ts`/`.js`/`.tsx`/`.jsx`; tests and stories
  excluded) are scanned for static `provider:name` literals; each referenced
  icon is emitted as its own lazy chunk. This is why rule 4 exists — and why an
  icon used only in a `.stories.ts`/`.test.ts` file must also appear as a
  literal in a scanned source file.
- **Local icons**: `iconDir` is scanned recursively; each `.svg` becomes
  `local:<basename-without-extension>`. A bare, unprefixed name normalizes to
  `local:`. Adding/removing files is picked up live in dev, and the plugin
  maintains a collection JSON plus the VS Code `iconify.customCollectionJsonPaths`
  setting so the Iconify editor extension previews local icons too.
- **Raw SVG escape hatch**: `BbIcon`'s `icon` prop also accepts a full
  `<svg>…</svg>` string (e.g. an asset imported with `?raw`) for a one-off mark
  that lives in no collection.

Gotcha: heroicons `-20-`/`-16-` size-variant names are hard-filtered (CSS
controls size, so they are redundant). Use base names — `heroicons:check`, not
`heroicons:check-16-solid`.

### Discovery workflow

1. List installed sets: look for `@iconify-json/*` in the consumer's
   `package.json`. If none fits, propose installing one (default suggestion:
   `@iconify-json/lucide`).
2. Verify each name exists in that set's `icons.json` (or its `aliases`) before
   using it.
3. For `local:*`, list the `.svg` files in the configured `iconDir`.

## Where the library accepts icons — full catalog

### Standalone `BbIcon`

Only for iconography the design owns — a status glyph in a table cell,
empty-state art, a custom composition. Every surface below is preferred when it
exists.

```html
<BbIcon icon="lucide:circle-check" size="sm" label="Paid" />
```

### Button icons

- `BbButton` — `prepend:icon` / `append:icon` beside the label; `icon` renders
  an icon-only button. The label content (default slot, preferred over `text`)
  still supplies the accessible name — it is just rendered `sr-only`. Use
  `aria-label` only to override that name, not as the default.

```html
<BbButton prepend:icon="lucide:plus">New invoice</BbButton>
<BbButton variant="outline" append:icon="lucide:download">Export</BbButton>
<!-- Accessible name from slot content, hidden visually — no aria-label needed. -->
<BbButton variant="ghost" icon="lucide:settings">Settings</BbButton>
```

- `BbDropdownButton` — `prepend:icon` / `append:icon` on the main action;
  `right:icon` replaces the chevron inside the split toggle.

```html
<BbDropdownButton
	text="Export"
	prepend:icon="lucide:download"
	:items="exportFormats"
/>
```

### Input affix icons

Every batteries-included input takes `prepend:icon` / `append:icon`; the input
wrapper places, sizes, and colors the glyph (the append side may already host
clear/stepper/toggle controls — prefer `prepend:icon` when in doubt):

```html
<BbTextInput
	v-model="query"
	label="Search members"
	prepend:icon="lucide:search"
/>
<BbNumberInput v-model="amount" label="Amount" prepend:icon="lucide:euro" />
<BbSelect
	v-model="plan"
	label="Plan"
	:items="plans"
	prepend:icon="lucide:layers"
/>
<BbDatePickerInput
	v-model="dueDate"
	label="Due date"
	prepend:icon="lucide:calendar"
/>
<BbColorInput
	v-model="brandColor"
	label="Brand color"
	append:icon="lucide:pipette"
/>
<BbTextarea
	v-model="notes"
	label="Internal notes"
	prepend:icon="lucide:sticky-note"
/>
```

### Status and metadata surfaces

- `BbAlert` — `icon` (plus `iconSize`):
  `<BbAlert variant="warning" icon="lucide:triangle-alert" text="Subscription expires in 3 days." />`
- `BbToast` — `icon` in the `useToast()` options (variants set tone only, no
  default glyph):
  `toast({ title: 'Invoice sent', variant: 'success', icon: 'lucide:send' })`
- `BbBadge` — `prepend:icon` / `append:icon` beside the default-slot label;
  `icon` makes an icon-only badge (the other two are then ignored):
  `<BbBadge variant="primary" prepend:icon="lucide:credit-card">Paid</BbBadge>`
- `BbTag` (tokens input) — `prepend:icon` / `append:icon` on the field, like
  the other inputs: `<BbTag v-model="skills" label="Skills" prepend:icon="lucide:tag" />`

### Item-config icons (declared in data, not markup)

`BbDropdown` entries — items **and** group headers — carry `'prepend:icon'` /
`'append:icon'` fields. `append:icon` is ignored when the item opens a submenu
(chevron) or sits in a selectable group (check).

```ts
const memberActions = [
	{ key: 'edit', text: 'Edit member', 'prepend:icon': 'lucide:pencil' },
	{
		key: 'delete',
		text: 'Delete',
		variant: 'destructive',
		'prepend:icon': 'lucide:trash-2',
	},
];
```

`BbDropdownButton` reuses the same `items` shape, so its menu entries get icons
the same way.

### Slot-injected icons (components with no icon prop)

These surfaces take arbitrary content, so you place a `BbIcon` (or richer
markup) yourself:

- `BbTabs` / `BbTabsList` — per-tab `label-{key}` slot (or the generic `label`
  fallback):

```html
<BbTabs v-model="tab" :items="tabs">
	<template #label-billing="{ text }">
		<BbIcon icon="lucide:file-text" size="sm" /> {{ text }}
	</template>
</BbTabs>
```

- `BbBreadcrumbs` — `item:prepend` / `item:append` around every item, or a
  named slot per `item.key` to replace one item's content:

```html
<BbBreadcrumbs :items="trail">
	<template #item:prepend="{ index }">
		<BbIcon v-if="index === 0" icon="lucide:home" size="sm" />
	</template>
</BbBreadcrumbs>
```

- `BbRating` — the `icon` slot replaces each star glyph (slot props include
  `checked`, `value`, `size`):

```html
<BbRating v-model="score">
	<template #icon="{ checked }">
		<BbIcon
			icon="lucide:heart"
			:class="checked ? 'text-red-500' : 'text-[color:var(--bb-text-faint)]'"
		/>
	</template>
</BbRating>
```

- `BbSwitch` — the `icon` slot replaces the toggle track visual (rarely
  needed; the default track is correct for almost every case).
- `BbDropdown` — `item:prepend` / `item:append`, or per-entry
  `${key}:prepend` / `${key}:append` slots, when an entry's leading/trailing
  region needs more than a named icon (e.g. an avatar).

## Sizing and color

- Icons paint in `currentColor`: they inherit the parent's text color. Color
  the **container** (token-driven utility class), never the icon markup itself.
- `BbIcon` `size` accepts the scale `xs`–`2xl` (12/16/24/28/36/40 px by
  default; consumers can override via the plugin's `iconDefaultSizes` option),
  a number (px), or a CSS length (`"1.5rem"`).
- Icons placed through props/item fields are sized and aligned by the host
  component to match its own size — don't fight that with custom CSS.

## Accessibility

- Decorative icon next to visible text (affixes, button prepend/append,
  dropdown items): no label — the text already announces it; a label would
  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`.
- 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
  have a name from _one_ of the two.

## Anti-patterns

- Hand-placing `BbIcon` in a slot when the component has an icon prop or item
  field for that exact spot.
- Wrapping `BbIcon` in a raw `<button>` — use `BbButton` with `icon` + a label
  (slot content or `text`; `aria-label` only to override).
- Inventing or guessing icon names; assuming a set is installed without
  checking `package.json`.
- Runtime-composed icon names (template strings / concatenation) — invisible to
  the build scanner, broken in production.
- Setting `color`/`fill` on the icon element instead of the parent.
- Falling back to random provider sets when a needed `local:` asset is missing —
  ask for the SVG (or approval to substitute) instead.

---

<!-- dist/ai/guides/inertia-helpers.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/inertia-helpers.md -->

# Inertia Helpers

A curated toolkit of composables for **Laravel + Inertia (Vue 3)** apps built
on bitboss-ui. These are _app-side_ code: copy the ones you need into your
project (conventionally `src/composables/`) — they are not exported by the
`bitboss-ui` package. The [Inertia recipes](../recipes/inertia/records-workspace.md)
assume this toolkit.

Why it exists: in Inertia there is no client data layer — data arrives as
**page props** and changes through **visits**. These helpers give that model
a clean, typed API so pages stay thin: props read through one surface,
filters live in the URL, paginated data and selection are shared through
keyed contexts instead of prop drilling, and forms return promises that
bitboss-ui buttons and dialogs can await.

Copying this toolkit pulls in real npm dependencies beyond the app's own
`@inertiajs/vue3`/`vue` — install them explicitly rather than relying on them
already being hoisted transitively through `bitboss-ui`'s own `dependencies`
(that works today by npm hoisting luck, and breaks under pnpm/Yarn PnP or the
next time `bitboss-ui` changes what it depends on):

```
npm i @vueuse/core object-code query-string
```

`@vueuse/core` backs every keyed context's `injectLocal`/`provideLocal`
(`usePaginatedResponseContext`, `useTableSelectionContext`, `useTableContext`,
`usePageShellContext`) and `useDeleteCmd`/`useScreenSizes`; `object-code`
powers the `isEqual` hash-comparison utility below; `query-string` backs
`useQuery`/`useRouteQuery`/`useQueryObject`. A few tiny utilities are assumed
under `@/utils` and defined below.

## Shared types and utilities

```ts
// src/types/index.ts — the Laravel paginator shape and base page props
export type PaginatedResponse<T> = {
	data: T[];
	meta: {
		total: number;
		per_page: number;
		current_page: number;
		last_page: number;
	};
};

export type BasePageProps = {
	[key: string]: unknown;
};
```

`PaginatedResponse<T>` is a genuine Laravel shape — but it is **not** what a
bare `$query->paginate()` serialises to (that flattens `current_page` /
`data` / `total` / `per_page` at the top level, no `meta` key). It's what an
**API Resource collection built by hand** looks like. See the controller
snippet under [`usePaginatedResponseContext`](#usepaginatedresponsecontext)
below before wiring a paginated prop — passing a raw paginator straight
through leaves `meta` `undefined` and the composable silently reads zeros.

```ts
// src/utils/index.ts — micro-utilities the helpers share
import { hash } from 'object-code';

export const isNil = (value: unknown): value is null | undefined =>
	value === null || value === undefined;

export const isNotNil = <T>(value: T | null | undefined): value is T =>
	!isNil(value);

export const isEmpty = (value: unknown): boolean =>
	isNil(value) || value === '' || (Array.isArray(value) && value.length === 0);

export const noop = (): void => undefined;

/** Deep equality by structural hash — cheap and dependency-light. */
export const isEqual = (a: unknown, b: unknown): boolean => hash(a) === hash(b);

export const isPlainObject = (
	value: unknown
): value is Record<string, unknown> =>
	typeof value === 'object' &&
	value !== null &&
	Object.getPrototypeOf(value) === Object.prototype;
```

---

## Page props

### useProp / useOptionalProp

Typed, reactive access to a page prop by path. `useProp` throws when the
path is missing (a controller contract violation should fail loudly);
`useOptionalProp` returns `undefined` instead.

```ts
// src/composables/useProp.ts
import { usePage } from '@inertiajs/vue3';
import { computed, type ComputedRef } from 'vue';

const walk = <T>(
	source: unknown,
	path: string[]
): { found: boolean; value: T | undefined } => {
	let current: unknown = source;
	for (const segment of path) {
		if (
			current === null ||
			typeof current !== 'object' ||
			!(segment in current)
		) {
			return { found: false, value: undefined };
		}
		current = (current as Record<string, unknown>)[segment];
	}
	return { found: true, value: current as T };
};

const toPath = (propPath: string | string[]): string[] =>
	typeof propPath === 'string' ? propPath.split('.') : propPath;

/** Reactive page prop by path. Throws when the path is not present. */
export const useProp = <T>(propPath: string | string[]): ComputedRef<T> => {
	const page = usePage();
	const path = toPath(propPath);

	return computed(() => {
		const { found, value } = walk<T>(page.props, path);
		if (!found) {
			throw new Error(`Page prop "${path.join('.')}" is missing.`);
		}
		return value as T;
	});
};

/** Like useProp, but resolves to `undefined` when the path is missing. */
export const useOptionalProp = <T>(
	propPath: string | string[]
): ComputedRef<T | undefined> => {
	const page = usePage();
	const path = toPath(propPath);

	return computed(() => walk<T>(page.props, path).value);
};
```

### useLazyProp

Reads a prop the server marked lazy (`Inertia::lazy()` / `optional()`).
The returned `value` is self-loading: the first template or computed that
reads it triggers a partial reload (`only: [propName]`) and the ref updates
when the data lands. `loading`/`loaded`/`error` expose the fetch state;
`execute()` forces the load imperatively.

```ts
// src/composables/useLazyProp.ts
import { isEqual, isNil, isNotNil } from '@/utils';
import { router, usePage } from '@inertiajs/vue3';
import type { Ref } from 'vue';
import { customRef, onBeforeUnmount, readonly, ref, watch } from 'vue';

export type UseLazyPropOptions = {
	/** Keep the last non-nil value across visits that reset the prop. Default true. */
	cache?: boolean;
	headers?: Record<string, string>;
};

export function useLazyProp<T>(
	propName: string,
	initialValue?: T,
	options: UseLazyPropOptions = {}
): {
	value: Ref<T | undefined>;
	loaded: Readonly<Ref<boolean>>;
	loading: Readonly<Ref<boolean>>;
	error: Readonly<Ref<Error | null>>;
	execute: () => Promise<void>;
} {
	const page = usePage<{ [key: string]: T | undefined }>();
	const { cache = true } = options;
	const loading = ref(false);
	const loaded = ref(page.props[propName] !== undefined);
	const error = ref<Error | null>(null);
	let inFlightPromise: Promise<void> | null = null;
	let isUnmounted = false;
	let cached = page.props[propName];

	onBeforeUnmount(() => {
		isUnmounted = true;
	});

	const loadProp = (onSuccess: () => void): Promise<void> => {
		if (inFlightPromise) return inFlightPromise;

		error.value = null;

		inFlightPromise = new Promise<void>((resolve) => {
			router.reload({
				only: [propName],
				replace: true,
				headers: options.headers,
				onStart: () => {
					loading.value = true;
				},
				onSuccess: () => {
					if (!isUnmounted) {
						loaded.value = true;
						cached = page.props[propName];
						onSuccess();
					}
				},
				onError: (errors) => {
					if (!isUnmounted) {
						error.value =
							errors instanceof Error
								? errors
								: new Error(`Failed to load lazy prop "${propName}"`);
					}
				},
				onFinish: () => {
					if (!isUnmounted) {
						loading.value = false;
					}
					inFlightPromise = null;
					resolve();
				},
			});
		});

		return inFlightPromise;
	};

	/** Self-loading ref: reading it while the prop is absent starts the fetch. */
	const value = customRef<T | undefined>((track, trigger) => ({
		get() {
			track();
			const isMissing = page.props[propName] === undefined;

			if (isMissing && !loaded.value && !loading.value) {
				loading.value = true;
				void loadProp(trigger);
			}

			if (isMissing && !loaded.value) {
				return initialValue;
			}
			if (cache && cached !== undefined) {
				return cached;
			}
			return page.props[propName];
		},
		set() {
			throw new Error(`Lazy prop "${propName}" is read-only.`);
		},
	}));

	const execute = () => loadProp(noopTrigger);

	watch(
		() => page.props[propName],
		(newVal, oldVal) => {
			if (isUnmounted) return;
			// Persist shape changes into the cache…
			if (isNotNil(newVal) && !isEqual(newVal, oldVal) && cache) {
				cached = newVal;
			}
			// …reset state when a navigation clears the prop (uncached mode)…
			if (isNil(newVal) && isNotNil(oldVal) && !cache) {
				loaded.value = false;
				loading.value = false;
				error.value = null;
			} else if (isNotNil(newVal) && isNil(oldVal)) {
				// …and mark loaded when the value first arrives.
				loaded.value = true;
				loading.value = false;
				error.value = null;
			}
		}
	);

	return {
		value,
		loaded: readonly(loaded),
		loading: readonly(loading),
		error: readonly(error),
		execute,
	};
}

const noopTrigger = () => undefined;
```

Gotchas:

- Inertia partial reloads only target **top-level** props — you cannot lazy
  load `stats.revenue`, only `stats`.
- Filter navigations reset lazy props server-side; with `cache: true`
  (default) the last value keeps rendering while the fresh one loads.

### useLazyPropGetter

Adapts a lazy prop into an **async getter** — exactly the items-provider
shape `BbSelect` / `BbSelectPopover` / `BbCheckboxGroup` accept. The prop
loads on first demand (e.g. when the select opens) instead of inflating the
initial page load.

```ts
// src/composables/useLazyPropGetter.ts
import {
	useLazyProp,
	type UseLazyPropOptions,
} from '@/composables/useLazyProp';
import { isNil } from '@/utils';
import type { Ref } from 'vue';

export function useLazyPropGetter<T, U = T>(
	propName: string,
	formatter?: (value: T) => U,
	options?: UseLazyPropOptions
): {
	getter: () => Promise<U>;
	loaded: Readonly<Ref<boolean>>;
	loading: Readonly<Ref<boolean>>;
} {
	const { value, loaded, loading, execute } = useLazyProp<T>(
		propName,
		undefined,
		options
	);

	const getter = async (): Promise<U> => {
		if (!loaded.value) {
			await execute();
		}
		if (isNil(value.value)) {
			throw new Error(`Could not load lazy prop "${propName}"`);
		}
		if (isNil(formatter)) return value.value as unknown as U;
		return formatter(value.value);
	};

	return { getter, loaded, loading };
}
```

```vue
<!-- The controller shares `roles` as a lazy prop; the select loads it on open. -->
<script setup lang="ts">
const { getter: fetchRoles } = useLazyPropGetter<Role[]>('roles');
</script>

<template>
	<BbSelect
		v-model="role"
		item-text="name"
		item-value="id"
		:items="fetchRoles"
		label="Role"
	/>
</template>
```

---

## URL state

In Inertia the URL is the only client state that survives a visit — filters,
page numbers and sort orders belong there, not in refs that reset on
navigation.

### useQuery

Parses the current page URL's query string into an object. Snapshot, not
reactive — used by the writers below.

```ts
// src/composables/useQuery.ts — requires: npm i query-string
import { usePage } from '@inertiajs/vue3';
import qs, { type StringifyOptions } from 'query-string';

export const useQuery = ({
	arrayFormat = 'comma',
}: { arrayFormat?: StringifyOptions['arrayFormat'] } = {}): Record<
	string,
	unknown
> => {
	const { url } = usePage();
	const [, queryString] = url.split('?');
	if (!queryString) return {};
	return qs.parse(decodeURIComponent(queryString), {
		arrayFormat,
		decode: true,
	});
};
```

**Don't swap `query-string` for a hand-rolled `URLSearchParams` reader.** It
looks like a free dependency saving and it is not: `URLSearchParams` yields
`Record<string, string>`, so `?tags=a,b` reads back as the string `'a,b'`
instead of `['a', 'b']`, and the `arrayFormat` option disappears along with
it. `useQueryObject` _writes_ arrays with that same option, so the reader and
the writer stop agreeing on what a multi-value filter looks like in the URL,
and every consumer of one — filter chips, a `BbSelectPopover` with
`multiple` — has to re-split by hand at each read site. The three composables
here and the [Inertia recipes](../recipes/inertia/records-workspace.md) all
assume the parsed-array shape. Install the dependency.

### useRouteQuery

A single query parameter as a **writable ref**. Reading tracks the current
URL; writing merges the parameter and performs a (replace) visit, so the
server re-renders with the new value. Writing the current value is a no-op —
safe to sync from server responses without visit loops.

```ts
// src/composables/useRouteQuery.ts — requires: npm i query-string
import { router, usePage } from '@inertiajs/vue3';
import qs from 'query-string';
import { computed, type WritableComputedRef } from 'vue';

type Options<T> = {
	/** Parse the raw string (e.g. `Number`). Defaults to identity. */
	transform?: (value: string) => T;
	preserveScroll?: boolean;
	preserveState?: boolean;
};

export function useRouteQuery<T = string>(
	key: string,
	defaultValue: string,
	options: Options<T> = {}
): WritableComputedRef<T> {
	const {
		transform = (value) => value as unknown as T,
		preserveScroll = true,
		preserveState = true,
	} = options;
	const page = usePage();

	const readRaw = (): 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 computed<T>({
		get: () => transform(readRaw()),
		set: (next) => {
			const nextRaw = String(next);
			if (nextRaw === readRaw()) return;

			const [path, queryString = ''] = page.url.split('?');
			const query = qs.parse(queryString);
			if (nextRaw === defaultValue) {
				delete query[key]; // keep URLs clean at the default
			} else {
				query[key] = nextRaw;
			}
			const stringified = qs.stringify(query);
			router.visit(stringified ? `${path}?${stringified}` : path, {
				preserveScroll,
				preserveState,
				replace: true,
			});
		},
	});
}
```

### useQueryObject

The **filter engine**: watch a filters object and mirror its non-empty
values into the query string with an Inertia visit per change. Keys it has
seen are cleaned up when they empty out; the `page` parameter resets on
every filter change so results are never hidden on an out-of-range page.

```ts
// src/composables/useQueryObject.ts — requires: npm i query-string
import { useQuery } from '@/composables/useQuery';
import { isEmpty, isNil } from '@/utils';
import { router, usePage } from '@inertiajs/vue3';
import qs, { type StringifyOptions } from 'query-string';
import { toValue, watch, type MaybeRefOrGetter } from 'vue';

type Options<T> = {
	transform?: (value: Partial<T>) => Partial<T>;
	/** Reset the `page` parameter on change. Default true. */
	resetPage?: boolean;
	/** Additional query keys removed whenever the object changes. */
	resetKeys?: string[];
	/** Inertia partial reload prop names (supports reactive getter). */
	only?: MaybeRefOrGetter<string[]>;
	/**
	 * When it resolves to `false` the watcher keeps tracking keys but skips
	 * the navigation — use it when another owner performs the visit during a
	 * programmatic transition, to avoid competing self-cancelling requests.
	 */
	shouldNavigate?: MaybeRefOrGetter<boolean>;
	arrayFormat?: StringifyOptions['arrayFormat'];
	preserveState?: boolean;
	preserveScroll?: boolean;
	replace?: boolean;
};

export function useQueryObject<T extends Record<string, unknown>>(
	object: MaybeRefOrGetter<T>,
	options: Options<T> = {}
): void {
	const {
		transform,
		resetPage = true,
		resetKeys = [],
		preserveState = true,
		preserveScroll = true,
		replace = true,
		only: onlyOption = [],
		shouldNavigate = true,
		arrayFormat = 'comma',
	} = options;

	const filterValidValues = (obj: T): Partial<T> => {
		const filtered: Partial<T> = {};
		Object.entries(obj).forEach(([key, val]) => {
			if (!isNil(val) && val !== '') {
				(filtered as Record<string, unknown>)[key] = val;
			}
		});
		return filtered;
	};

	/** Every key this composable has ever managed, for stable URL cleanup. */
	const seenKeys = new Set<string>(Object.keys(toValue(object) ?? {}));

	watch(
		() => toValue(object),
		(newObject) => {
			if (!newObject) return;

			Object.keys(newObject).forEach((key) => {
				if (!seenKeys.has(key)) {
					console.warn(
						`[useQueryObject] Key "${key}" appeared after initialization. ` +
							`Initialize the object with all possible keys for stable URL cleanup.`
					);
				}
				seenKeys.add(key);
			});

			const validValues = filterValidValues(newObject);
			const transformedValues = transform
				? transform(validValues)
				: validValues;

			// Start from the existing query to preserve keys owned elsewhere.
			const existingQuery = useQuery({ arrayFormat });
			seenKeys.forEach((key) => delete existingQuery[key]);
			if (resetPage) delete existingQuery.page;
			resetKeys.forEach((key) => delete existingQuery[key]);

			Object.entries(transformedValues).forEach(([key, val]) => {
				if (!isEmpty(val)) existingQuery[key] = val;
			});

			const stringified = qs.stringify(existingQuery, { arrayFormat });
			const newUrl = stringified
				? [window.location.pathname, stringified].join('?')
				: window.location.pathname;

			if (newUrl === usePage().url) return;
			if (!toValue(shouldNavigate)) return;

			router.visit(newUrl, {
				preserveState,
				preserveScroll,
				only: toValue(onlyOption),
				replace,
			});
		},
		/*
		 * Default flush, deliberately NOT `sync`. Vue batches a tick's mutations
		 * into one watcher run, so a `clearFilters()` that blanks three keys
		 * fires ONE visit instead of three (measured: 3 writes → 3 runs under
		 * `sync`, 1 under the default). The two it saves used to self-cancel,
		 * but they were still sent.
		 *
		 * This does NOT make typing cheap — one visit per settled keystroke is
		 * still one visit per keystroke. Debounce the source for that; see the
		 * note below.
		 */
		{ deep: true }
	);
}
```

```ts
// A listing page's whole filter wiring:
const filters = reactive({ search: '', status: null as string | null });
useQueryObject(filters, { only: ['invoices'] });
// Bind BbTextInput / BbSelectPopover to `filters.*` — every change becomes a
// partial reload and the server re-renders the `invoices` prop.
```

> **It does not debounce.** "An Inertia visit per change" is literal: a text
> field bound straight to `filters.search` fires one `router.visit` per
> keystroke. It DOES batch within a tick — the watcher uses Vue's default
> flush, so a `clearFilters()` that blanks three keys fires one visit, not
> three — but batching cannot help a burst spread across ticks, which is what
> typing is. If a recipe or a comment says "debounced", the debounce is the
> caller's to add:
>
> - **Typing** — debounce the _source_, and pass a getter so the helper only
>   ever sees settled values:
>
> ```ts
> import { refDebounced } from '@vueuse/core';
>
> const search = ref(''); // bind BbTextInput to this — it stays instant
> const debouncedSearch = refDebounced(search, 300);
> const filters = reactive({ status: null as string | null });
>
> useQueryObject(() => ({ ...filters, search: debouncedSearch.value }), {
> 	only: ['invoices'],
> });
> ```
>
> - **Programmatic multi-key writes** (reset, apply-a-saved-view) — gate them
>   with `shouldNavigate` and perform the one visit yourself once the object is
>   settled. That is what the option is for: the watcher keeps tracking keys
>   for URL cleanup while the navigation is yours.

---

## Shared page data (contexts)

These share **server data** across a page by string key — the Inertia
counterpart of the component-state context
[`useBbTableContext`](../composables/useBbTableContext.md). Rule of thumb:
`useBbTableContext` mirrors what the _table widget_ is doing (selection,
sort, highlight); these contexts own what the _server sent_ (items, meta)
and survive being read from any component on the page. First caller creates
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.

```ts
// src/composables/usePaginatedResponseContext.ts
import { useRouteQuery } from '@/composables/useRouteQuery';
import type { PaginatedResponse } from '@/types';
import { isNotNil } from '@/utils';
import type { PageProps } from '@inertiajs/core';
import { router, usePage } from '@inertiajs/vue3';
import { injectLocal, provideLocal } from '@vueuse/core';
import { computed, onScopeDispose, ref, type ComputedRef, type Ref } from 'vue';

export type PaginatedResponseContext<T> = {
	totalItems: ComputedRef<number>;
	perPage: Ref<number>;
	page: Ref<number>;
	totalPages: ComputedRef<number>;
	/** Current page items. Writable for optimistic edits; resets on navigation. */
	items: Ref<T[]>;
};

const toContextKey = (key: string): string => `${key}:paginatedResponse`;

export const usePaginatedResponseContext = <T = object>(
	dataKey: string
): PaginatedResponseContext<T> => {
	const existing = injectLocal<PaginatedResponseContext<T> | null>(
		toContextKey(dataKey),
		null
	);
	if (isNotNil(existing)) return existing;

	// `usePage<TPageProps extends PageProps = PageProps>()` requires the
	// generic to satisfy `PageProps` — an app that augments `PageProps` via
	// declaration merging (the mainstream Inertia convention: `declare module
	// '@inertiajs/core' { interface PageProps { auth: Auth; flash: Flash } }`)
	// makes that constraint require `auth`/`flash`, which a bare
	// `{ [key: string]: PaginatedResponse<T> }` doesn't have and fails
	// `TS2344`. Intersecting with `PageProps` keeps the constraint satisfied
	// either way, augmented or not.
	const paginated = computed(
		() =>
			usePage<PageProps & Record<string, PaginatedResponse<T>>>().props[dataKey]
	);

	const items = ref<T[]>(paginated.value.data ?? []) as Ref<T[]>;
	const totalItems = computed(() => paginated.value.meta.total ?? 0);
	const totalPages = computed(() => paginated.value.meta.last_page ?? 0);

	const perPage = useRouteQuery(
		'per_page',
		`${paginated.value.meta.per_page ?? 10}`,
		{
			transform: Number,
		}
	);
	const page = useRouteQuery(
		'page',
		`${paginated.value.meta.current_page ?? 1}`,
		{
			transform: Number,
		}
	);

	const context: PaginatedResponseContext<T> = {
		totalItems,
		perPage,
		page,
		totalPages,
		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;
		items.value = data.data ?? [];
		page.value = data.meta?.current_page ?? 1;
		perPage.value = data.meta?.per_page ?? 10;
	});
	onScopeDispose(unbind);

	provideLocal(toContextKey(dataKey), context);

	return context;
};
```

**The controller must produce the `{ data, meta }` shape explicitly** — a
bare `$query->paginate()` passed straight to `Inertia::render()` serialises
_flat_ (`current_page`, `data`, `total`, `per_page` all top-level, no `meta`
key), so `paginated.value.meta` above reads `undefined` and every field the
composable exposes silently falls back to its default. Wrapping a paginator
in an API Resource collection (`UserResource::collection($paginator)`) does
**not** fix this on its own either — Inertia resolves it through
`toArray()`, which drops the pagination `links`/`meta` that Laravel only
adds in `PaginatedResourceResponse::toResponse()` (an HTTP-response-only
path Inertia doesn't call). Build the shape by hand instead:

```php
// UsersController.php
public function index(Request $request)
{
	$paginator = User::query()->paginate(20)->withQueryString();

	return Inertia::render('Admin/Users/Index', [
		'users' => [
			'data' => UserResource::collection($paginator)->resolve(),
			'meta' => [
				'total' => $paginator->total(),
				'per_page' => $paginator->perPage(),
				'current_page' => $paginator->currentPage(),
				'last_page' => $paginator->lastPage(),
			],
		],
	]);
}
```

A small `App\Support\PaginatedResponse::wrap($paginator, $resourceClass)`
helper is a reasonable way to avoid repeating this at every call site — the
composable only cares about the resulting `{ data, meta }` shape, not how
the controller built it.

> **`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`
item lists plus the `all` flag ("select-all across pages" semantics — when
`all` is true, `selected` does **not** enumerate every row; the server
combines `all` + `unselected` instead). Bind these to `BbTable`'s
`v-model`, `v-model:unselected-items` and `v-model:select-all`.

```ts
// src/composables/useTableSelectionContext.ts
import { isNotNil } from '@/utils';
import { injectLocal, provideLocal } from '@vueuse/core';
import { ref, type Ref } from 'vue';

export type TableSelectionContext<U> = {
	/** The select-all checkbox state. Does not enumerate items. */
	all: Ref<boolean>;
	/** Items manually selected. NOT the full list when `all` is true. */
	selected: Ref<U[]>;
	/** Items manually unselected while `all` is true. */
	unselected: Ref<U[]>;
	resetSelection: () => void;
};

const toSelectionKey = (key: string): string => `${key}:selection`;

/** Bare selection state, no provide/inject — for callers that own sharing. */
export const createSelectionContext = <
	U = unknown,
>(): TableSelectionContext<U> => {
	const all = ref(false);
	const selected = ref<U[]>([]) as Ref<U[]>;
	const unselected = ref<U[]>([]) as Ref<U[]>;

	const resetSelection = (): void => {
		all.value = false;
		selected.value = [];
		unselected.value = [];
	};

	return { all, selected, unselected, resetSelection };
};

export const useTableSelectionContext = <U = unknown>(
	key: string
): TableSelectionContext<U> => {
	const selectionKey = toSelectionKey(key);
	const existing = injectLocal<TableSelectionContext<U> | null>(
		selectionKey,
		null
	);
	if (isNotNil(existing)) return existing;

	const context = createSelectionContext<U>();
	provideLocal(selectionKey, context);
	return context;
};
```

### useTableContext

The composition of the two above — one keyed context carrying a listing
page's whole server-data spine: items, pagination, and selection. This is
what the [Inertia CRUD listing recipe](../recipes/inertia/records-workspace.md)
builds on.

```ts
// src/composables/useTableContext.ts
import {
	usePaginatedResponseContext,
	type PaginatedResponseContext,
} from '@/composables/usePaginatedResponseContext';
import {
	useTableSelectionContext,
	type TableSelectionContext,
} from '@/composables/useTableSelectionContext';
import { isNotNil } from '@/utils';
import { injectLocal, provideLocal } from '@vueuse/core';

export type TableContext<T, U> = TableSelectionContext<U> &
	PaginatedResponseContext<T>;

const toTableKey = (key: string): string => `${key}:table`;

export const useTableContext = <T = object, U = T>(
	dataKey: string
): TableContext<T, U> => {
	const existing = injectLocal<TableContext<T, U> | null>(
		toTableKey(dataKey),
		null
	);
	if (isNotNil(existing)) return existing;

	const context: TableContext<T, U> = {
		...useTableSelectionContext<U>(dataKey),
		...usePaginatedResponseContext<T>(dataKey),
	};

	provideLocal(toTableKey(dataKey), context);
	return context;
};
```

Gotchas:

- The key is a rendezvous string (use the page-prop name, e.g.
  `'invoices'`). Like the library's table context, a typo doesn't error —
  it silently creates a second, orphan context.
- Each composite context provides under a namespaced key
  (`invoices:table`, `invoices:selection`, `invoices:paginatedResponse`),
  so the pieces can also be joined individually.

---

## Forms and guards

> **`onError` is not "the request failed".** Inertia splits failure three ways
> and they arrive on three different callbacks: **`onError`** fires when the
> server answered with **validation** errors (the ordinary 422), populating
> `form.errors`; **`onHttpException`** when it answered with an unhandled
> server error; and **`onNetworkError`** when the request never reached the
> server at all — offline, DNS failure, connection reset. Code that only wires
> `onError` — which is most code, because it is the one everybody knows —
> shows the user nothing whatsoever when the connection drops, and the submit
> button just goes quiet. Wire `onNetworkError` to a toast at minimum.
>
> These are `router.visit()` / `useForm()` options. **They are not `<Link>`
> props** — Inertia's `Link` component declares `onError` and nothing else from
> this trio, so passing `on-network-error` to a link-shaped `BbButton` does
> nothing at all. If you need to tell a dead connection from a 422, make it a
> form submit or an explicit visit.

### usePromiseForm

Inertia's `useForm` with **promise semantics**: `post/put/patch/remove`
resolve on success and reject on validation errors, so you can `await` a
submit, chain a toast, or hand the promise to a `BbButton` `@click` /
`useConfirm` `onClick` for automatic busy states. `form` is the underlying
Inertia form — `form.errors`, `form.isDirty`, `form.reset()` all work.

**Declare the draft shape as a `type` alias, not an `interface`.** The generic
is constrained to `Record<string, FormValue>` (what Inertia can serialize), and
TypeScript gives an implicit index signature to object _type aliases_ only — an
`interface` never satisfies that constraint, however form-encodable its fields
are. The same applies to any nested shape (a line-item row, say). It is a
TypeScript quirk, not a statement about your data.

```ts
// src/composables/usePromiseForm.ts
import { useLoading } from '@/composables/useLoading';
import {
	useForm,
	type InertiaForm,
	type InertiaFormProps,
} from '@inertiajs/vue3';

type FormValue =
	| string
	| number
	| boolean
	| null
	| File
	| undefined
	| FormValue[]
	| { [key: string]: FormValue };

type Options = Parameters<InertiaFormProps<object>['get']>[1];

export const usePromiseForm = <T extends Record<string, FormValue>>(
	initialData: T
) => {
	// @ts-expect-error - typed as InertiaForm<T> to avoid fighting the type system
	const form = useForm(initialData) as InertiaForm<T>;

	const { fn: submit, loading: isSubmitting } = useLoading(
		(
			url: string,
			method: 'get' | 'post' | 'put' | 'patch' | 'delete' = 'post',
			options: Options = {}
		): Promise<void> =>
			new Promise<void>((resolve, reject) => {
				const { onFinish: userOnFinish, ...visitOptions } = options;

				form[method](url, {
					...visitOptions,
					onSuccess: () => resolve(),
					onError: (errors: unknown) => reject(errors),
					onFinish: (
						...args: Parameters<NonNullable<NonNullable<Options>['onFinish']>>
					) => {
						userOnFinish?.(...args);
						// A non-Inertia response (e.g. a 423 entity lock or a 419
						// CSRF mismatch) fires neither onSuccess nor onError, only
						// onFinish. Settle here so isSubmitting is released instead
						// of hanging the form forever. No-op once already settled.
						reject(new Error('Inertia visit did not return a valid response.'));
					},
				});
			})
	);

	const post = (url: string, options?: Options) => submit(url, 'post', options);
	const put = (url: string, options?: Options) => submit(url, 'put', options);
	const patch = (url: string, options?: Options) =>
		submit(url, 'patch', options);
	const remove = (url: string, options?: Options) =>
		submit(url, 'delete', options);

	return { form, submit, post, put, patch, remove, isSubmitting };
};
```

> **`post`/`put`/`patch`/`remove` reject on validation errors — never call
> them fire-and-forget.** A 422 (or the non-Inertia-response fallback above)
> rejects the promise, and Vue does not surface a rejected promise you didn't
> await or `.catch()` — it becomes a silent `Uncaught (in promise)` in the
> console instead of a message the user sees. This bites hardest on the
> failure paths you're least likely to test by hand: a wrong TOTP code, a
> rate-limited or unknown email, an expired invite token. Always either
> `await` inside a `try/catch` (see `sendInvites`/`createProject` in the
> [Onboarding](../recipes/inertia/onboarding.md) recipe), or chain
> `.catch(() => {})` when `form.errors` already renders the failure and you
> have nothing else to do on rejection. Every call site in this guide and its
> recipes follows one of those two shapes — copy them, not a bare `post(...)`.

**Seeding a draft: `NullableKeys<T>`, not a hand-rolled `| null` on every
field.** Don't declare a bespoke `Draft` type that bolts `| null` onto each
string prop by hand — that's what produces empty-string drafts (`''`
instead of `null`) when a field gets missed. Instead, derive the draft from
the real request type with one small **app-owned** mapped type (it is not
shipped by bitboss-ui — paste it once per app) that nulls only scalar
leaves and leaves arrays/booleans/nested objects' own leaves alone:

```ts
// src/types/nullable-keys.ts (app-owned)
export type NullableKeys<T> = {
	[K in keyof T]: T[K] extends boolean
		? T[K]
		: T[K] extends unknown[]
			? T[K]
			: T[K] extends object
				? NullableKeys<T[K]>
				: T[K] | null;
};
```

```ts
import { usePromiseForm } from '@/composables/usePromiseForm';
import type { NullableKeys } from '@/types/nullable-keys';
import type { InvoiceRequest } from '@/types';

// InvoiceRequest's own fields are non-null (it's what the server accepts);
// NullableKeys widens only its scalar leaves to `T | null` for the draft.
const { form } = usePromiseForm<NullableKeys<InvoiceRequest>>({
	customerId: null,
	projectId: null,
	issuedAt: null,
	dueDate: null,
	taxRate: null,
	lineItems: [], // array leaf — stays non-null, seed with []
	notes: null,
});
```

### useHasChanged

Deep dirty-checking against a snapshot baseline — for edit screens whose
state is not a single Inertia form (multiple forms, ad-hoc refs). For a
single `usePromiseForm`, prefer the built-in `form.isDirty`.

```ts
// src/composables/useHasChanged.ts
import { isEqual } from '@/utils';
import { computed, ref, toValue, type WatchSource } from 'vue';

export function useHasChanged<T extends WatchSource<unknown>[]>(
	dependencies: T
) {
	/*
	 * Baselines are JSON round-trips, NOT `structuredClone`. This composable's
	 * documented inputs are refs and reactive objects, and `structuredClone`
	 * throws `DataCloneError` on every one of them — a Vue proxy is not a
	 * structured-cloneable type. It took the page down at setup.
	 *
	 * The comparison needs no copy at all: `isEqual` is hash-based and reads
	 * straight through a proxy, so the live value can be hashed as-is. Only the
	 * BASELINE needs detaching from live state, which is what the round-trip is
	 * for.
	 */
	const snapshot = (dep: WatchSource<unknown>) =>
		JSON.parse(JSON.stringify(toValue(dep)));

	const baselineValues = ref<unknown[]>(dependencies.map(snapshot));

	/** Re-baseline (call after a successful save). */
	const takeSnapshot = (): void => {
		baselineValues.value = dependencies.map(snapshot);
	};

	const hasChanged = computed(() =>
		dependencies.some(
			(dep, index) => !isEqual(toValue(dep), baselineValues.value[index])
		)
	);

	return { hasChanged, takeSnapshot };
}
```

### useConfirmOnRouteLeave

A dirty-state navigation guard: intercepts Inertia visits and asks through
[`useConfirm`](../composables/useConfirm.md) before leaving. Requires
`<BbConfirm />` mounted in the app root. Server redirects after a
whitelisted action carry the `X-Whitelisted-Action` header so a saving
visit's redirect is never blocked by its own guard.

```ts
// src/composables/useConfirmOnRouteLeave.ts
import { router } from '@inertiajs/vue3';
import { useConfirm } from 'bitboss-ui';
import { onScopeDispose, toValue, type MaybeRefOrGetter } from 'vue';

type Visit = {
	url: URL;
	headers?: Record<string, string>;
	[key: string]: unknown;
};

type Options = {
	/** URLs that bypass the dialog (e.g. the form's own submit target). */
	whitelist?: MaybeRefOrGetter<string[]>;
	/** Disable the guard (bind to `!hasChanged` / `!form.isDirty`). */
	disabled?: MaybeRefOrGetter<boolean>;
	/** Runs synchronously before the dialog; return false to allow the visit. */
	onBefore?: (visit: Visit) => unknown;
	/** Runs after the user confirms leaving. */
	onLeave?: (visit: Visit) => unknown;
	title?: string;
	text?: string;
};

const normalizeUrl = (value: string | URL) => {
	const url = new URL(value.toString(), window.location.origin);
	return url.pathname.replace(/\/+$/, '') || '/';
};

const getHeaderValue = (
	headers: Record<string, string> | undefined,
	headerName: string
) => {
	if (!headers) return undefined;
	const normalized = headerName.toLowerCase();
	const matched = Object.keys(headers).find(
		(key) => key.toLowerCase() === normalized
	);
	return matched ? headers[matched] : undefined;
};

export const WHITELIST_HEADER = 'X-Whitelisted-Action';

export const useConfirmOnRouteLeave = ({
	whitelist = [],
	disabled = false,
	onBefore = () => true,
	onLeave = () => true,
	title = 'Unsaved changes',
	text = 'You have unsaved changes. Leave without saving?',
}: Options = {}) => {
	// Captured in setup so the built-in dialog is owned by the guarded page:
	// if the page unmounts anyway, the dialog dismisses itself quietly.
	const { confirm } = useConfirm();
	let bypassNextVisit = false;

	const unbind = router.on('before', (event) => {
		const visit = event.detail.visit as Visit;

		if (bypassNextVisit) {
			bypassNextVisit = false;
			return;
		}

		if (toValue(disabled)) return;
		if (getHeaderValue(visit.headers, WHITELIST_HEADER) === '1') return;

		const nextPath = normalizeUrl(visit.url.href);
		if (nextPath === normalizeUrl(window.location.href)) return;
		if (toValue(whitelist).map(normalizeUrl).includes(nextPath)) return;

		if (onBefore(visit) === false) return false;
		event.preventDefault();

		void (async () => {
			const confirmed = await confirm({
				variant: 'destructive',
				title,
				text,
				yes: 'Discard changes',
				no: 'Keep editing',
			});
			if (!confirmed) return;

			await onLeave(visit);
			bypassNextVisit = true;
			router.visit(visit.url, {
				...(visit as Parameters<typeof router.visit>[1]),
				headers: { ...(visit.headers ?? {}), [WHITELIST_HEADER]: '1' },
			});
		})();
	});

	// 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.
	onScopeDispose(unbind);
};
```

---

## Async utilities

### useLoading

Wraps any async function with a concurrent-safe `loading` flag (a counter,
so overlapping calls don't flicker it off early).

```ts
// src/composables/useLoading.ts
import { computed, ref } from 'vue';

export const useLoading = <TArgs extends unknown[], TResult>(
	fn: (...args: TArgs) => Promise<TResult> | TResult
) => {
	const counter = ref(0);
	const loading = computed(() => counter.value > 0);

	const fnWithLoading = async (...args: TArgs) => {
		counter.value++;
		try {
			return await fn(...args);
		} finally {
			counter.value--;
		}
	};

	return { loading, fn: fnWithLoading };
};
```

### useAsyncFn

A full async-state engine for **non-Inertia** requests (JSON endpoints,
exports): `data` / `error` / `loading` / `aborted` state, an `AbortSignal`
per run, auto-abort of the previous run on re-execute, and abort on
unmount.

```ts
// src/composables/useAsyncFn.ts
import { isPlainObject } from '@/utils';
import {
	onBeforeMount,
	onBeforeUnmount,
	shallowRef,
	type ShallowRef,
} from 'vue';

type BaseOptions = {
	/** Run on mount. Default true. */
	immediate?: boolean;
	/** Swallow AbortError instead of exposing it on `error`. Default true. */
	abortSilently?: boolean;
};

type AsyncFnParams = {
	setError: (err: string) => void;
	setErrorData: (err: Record<string, unknown>) => void;
	signal: AbortSignal;
};

type AsyncFnReturn<D> = {
	data: ShallowRef<D>;
	error: ShallowRef<Error | null>;
	errorData: ShallowRef<Record<string, unknown> | null>;
	loading: ShallowRef<boolean>;
	aborted: ShallowRef<boolean>;
	execute: () => Promise<D>;
	stop: () => void;
};

type AsyncFn<T> = (params: AsyncFnParams) => Promise<T> | T;

export function useAsyncFn<T>(
	fn: AsyncFn<T>,
	options: BaseOptions & { defaultValue: T }
): AsyncFnReturn<T>;
export function useAsyncFn<T>(
	fn: AsyncFn<T>,
	options?: BaseOptions & { defaultValue?: undefined }
): AsyncFnReturn<T | null>;
export function useAsyncFn<T>(
	fn: AsyncFn<T>,
	{
		immediate = true,
		abortSilently = true,
		defaultValue,
	}: BaseOptions & { defaultValue?: T } = {}
) {
	const data = shallowRef(defaultValue ?? null);
	const error = shallowRef<Error | null>(null);
	const errorData = shallowRef<Record<string, unknown> | null>(null);
	const loading = shallowRef(false);
	const aborted = shallowRef(false);
	let abortController: AbortController | null = null;

	const setError = (err: string) => {
		error.value = new Error(err);
	};
	const setErrorData = (err: Record<string, unknown>) => {
		errorData.value = err;
	};

	const isAbortError = (err: unknown): boolean =>
		err instanceof DOMException && err.name === 'AbortError';

	const execute = async () => {
		abortController?.abort();
		abortController = new AbortController();
		loading.value = true;
		aborted.value = false;
		error.value = null;
		errorData.value = null;

		try {
			data.value = await fn({
				setError,
				setErrorData,
				signal: abortController.signal,
			});
		} catch (err) {
			if (isAbortError(err)) {
				aborted.value = true;
				if (!abortSilently) error.value = err as Error;
			} else if (err instanceof Error) {
				error.value = err;
			} else if (typeof err === 'string') {
				error.value = new Error(err);
			} else if (isPlainObject(err)) {
				// Laravel validation bag: surface the first message.
				const firstKey = Object.keys(err)[0];
				error.value = new Error(String(err[firstKey]));
			}
		} finally {
			loading.value = false;
		}

		return data.value;
	};

	if (immediate) onBeforeMount(execute);

	const stop = () => {
		abortController?.abort();
		abortController = null;
	};
	onBeforeUnmount(stop);

	return { data, error, errorData, loading, aborted, execute, stop };
}
```

### useResourceContext

"Given an id, keep its resource loaded": re-fetches whenever the id
changes, resets to `null` when the id clears, exposes `loading` and
`refresh()`. The natural engine for a detail sidebar or peek panel — feed
it the highlighted row's id.

```ts
// src/composables/useResourceContext.ts
import { useLoading } from '@/composables/useLoading';
import { noop } from '@/utils';
import { ref, toValue, watch, type MaybeRefOrGetter, type Ref } from 'vue';

type UseResourceContextOptions<T, ID> = {
	immediate?: boolean;
	disabled?: MaybeRefOrGetter<boolean>;
	onReset?: () => void | Promise<void>;
	onSuccess?: (data: T, resourceId: ID) => void | Promise<void>;
	onError?: (error: unknown, resourceId: ID) => void | Promise<void>;
	onFinish?: (resourceId: ID) => void | Promise<void>;
};

export function useResourceContext<T, ID = string>(
	id: MaybeRefOrGetter<ID | null | undefined>,
	fn: (id: ID) => Promise<T>,
	options: UseResourceContextOptions<T, ID> = {}
) {
	const data = ref<T | null>(null) as Ref<T | null>;
	const {
		immediate = true,
		disabled = false,
		onSuccess = noop,
		onError = (error: unknown) => {
			console.error('Failed to fetch resource:', error);
		},
		onReset = noop,
		onFinish = noop,
	} = options;

	const { loading, fn: fetch } = useLoading((resourceId: ID) => fn(resourceId));

	const load = async (resourceId: ID) => {
		try {
			const result = await fetch(resourceId);
			data.value = result;
			await onSuccess(result, resourceId);
		} catch (error) {
			data.value = null;
			await onError(error, resourceId);
		} finally {
			await onFinish(resourceId);
		}
	};

	watch(
		() => ({ resourceId: toValue(id), isDisabled: toValue(disabled) }),
		async ({ resourceId, isDisabled }) => {
			if (!resourceId) {
				data.value = null;
				await onReset();
				return;
			}
			// Keep already-loaded data while disabled.
			if (isDisabled) return;
			await load(resourceId as ID);
		},
		{ immediate }
	);

	const refresh = async () => {
		const currentId = toValue(id);
		if (toValue(disabled) || !currentId) return;
		await load(currentId as ID);
	};

	return { data, loading, refresh };
}
```

Gotchas:

- **`data === null` means EITHER "not loaded yet" OR "failed"** — the default
  `onError` only logs to the console and resets `data` to `null`, which is
  exactly what an unloaded resource looks like. If the fetcher's loading
  branch renders `<BbSpinner />` while `data` is `null`, a permanent failure
  (a 403/404 the id is reachable for) renders a permanent spinner. Pass your
  own `onError` (a local `ref<boolean>` a peek can branch on, as the
  [Records Workspace](../recipes/inertia/records-workspace.md) recipe does)
  when the fetcher can fail.
- **Check `res.ok` in the fetcher.** `fetch(...).then((res) => res.json())`
  never rejects on a non-2xx response — a 403/404 body still parses as JSON
  (or throws inside `.json()`, which is _also_ swallowed by `useResourceContext`
  the same way). Throw when `!res.ok` so `onError` actually fires.

## UI utilities

### useDeleteCmd

Fires a callback on Delete/Backspace — unless an input, textarea, select or
contenteditable is focused. Pairs with table selection: select rows, hit
Delete, dispatch the same confirm-guarded bulk action as the button.

```ts
// src/composables/useDeleteCmd.ts
import { useMagicKeys, whenever } from '@vueuse/core';
import { toValue, type MaybeRefOrGetter } from 'vue';

export type UseDeleteCmdOptions = {
	disabled?: MaybeRefOrGetter<boolean>;
};

const isInteractiveElementFocused = (): boolean => {
	const active = document.activeElement;
	if (!active) return false;
	const tag = active.tagName.toLowerCase();
	if (tag === 'input' || tag === 'textarea' || tag === 'select') return true;
	return active.getAttribute('contenteditable') === 'true';
};

export function useDeleteCmd(
	onDelete: () => void,
	options: UseDeleteCmdOptions = {}
) {
	const keys = useMagicKeys();

	const handleDelete = () => {
		if (isInteractiveElementFocused()) return;
		if (!toValue(options.disabled)) onDelete();
	};

	whenever(keys['delete'], handleDelete);
	whenever(keys['backspace'], handleDelete);
}
```

### useScreenSizes

Shared reactive breakpoints aligned with Tailwind `md`/`lg` — one window
listener for the whole app via `createSharedComposable`.

```ts
// src/composables/useScreenSizes.ts
import { useWindowSize } from '@vueuse/core';
import { createSharedComposable } from '@vueuse/shared';
import { computed } from 'vue';

/** Tailwind md breakpoint (px). Mobile when width < 768. */
export const SCREEN_BREAKPOINT_MD = 768;
/** Tailwind lg breakpoint (px). Tablet when 768 <= width < 1024. */
export const SCREEN_BREAKPOINT_LG = 1024;

const useScreenSizesImpl = () => {
	const { width } = useWindowSize();

	const isMobile = computed(() => width.value < SCREEN_BREAKPOINT_MD);
	const isTablet = computed(
		() =>
			width.value >= SCREEN_BREAKPOINT_MD && width.value < SCREEN_BREAKPOINT_LG
	);
	const isDesktop = computed(() => width.value >= SCREEN_BREAKPOINT_LG);

	return { width, isMobile, isTablet, isDesktop };
};

export const useScreenSizes = createSharedComposable(useScreenSizesImpl);
```

### useIndexById

Index an item list by key for O(1) lookups — e.g. mapping the ids in a
selection context back to full rows for a bulk-action payload.

```ts
// src/composables/useIndexById.ts
import { computed, unref, type MaybeRef } from 'vue';

type Options<TItem> = {
	items: MaybeRef<readonly TItem[]>;
	/** The item property holding the id (e.g. 'id'). */
	key: keyof TItem & string;
};

export const useIndexById = <TItem>({ items, key }: Options<TItem>) => {
	const data = computed<Record<string, TItem>>(() => {
		const map: Record<string, TItem> = {};
		for (const item of unref(items)) {
			map[String(item[key])] = item;
		}
		return map;
	});

	const get = (id: string | number): TItem | undefined =>
		data.value[String(id)];

	return { data, get };
};
```

### useUntil

A ref that flips once, the first time a condition becomes true, then stops
watching — for one-shot reveals ("has ever loaded", onboarding hints).

```ts
// src/composables/useUntil.ts
import { noop } from '@/utils';
import { ref, toValue, watch, type MaybeRefOrGetter } from 'vue';

type Options<T, U> = {
	initialValue?: T;
	nextValue?: U;
	onChange?: VoidFunction;
};

export const useUntil = <T = boolean, U = boolean>(
	condition: MaybeRefOrGetter<boolean>,
	{
		initialValue = false as T,
		nextValue = true as U,
		onChange = noop,
	}: Options<T, U> = {}
) => {
	const value = ref<T | U>(initialValue);

	const stopWatching = watch(
		() => toValue(condition),
		(met) => {
			if (met) {
				onChange();
				value.value = nextValue;
				stopWatching();
			}
		}
	);

	return value;
};
```

---

## Related

- [Recipe: Records Workspace (Inertia)](../recipes/inertia/records-workspace.md) —
  these helpers assembled into a full page.
- [Recipe: Record Form (Inertia)](../recipes/inertia/record-form.md) —
  `usePromiseForm` + `useConfirmOnRouteLeave` in practice.
- [Page Shell](./page-shell.md) and
  [Floating Bottom Panel](./floating-bottom-panel.md) — the app-side layout
  components these pages sit in.
- [useBbTableContext](../composables/useBbTableContext.md) — the library's
  by-id context for table _widget_ state; complements, not replaces, the
  keyed data contexts here.

---

<!-- dist/ai/guides/inline-edit-playbook.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/inline-edit-playbook.md -->

# Inline Edit Playbook

Use this playbook whenever a table or dense form edits values **in place** —
no edit page, no modal form. It answers the one question every inline-edit
surface must answer before a line of code: **who owns the uncommitted value?**

Companions: [BbTable](../BbTable.md) (the Inline editing section has a live
example), [BbSelectPopover](../BbSelectPopover.md) (the one-popover-per-row
canon), [Fetch Data Items](./fetch-items-playbook.md) (the provider behind a
search-backed cell), [Design language](./design-language.md) (the editable
badge grammar and the soft status palette).

## The question: who owns the edit?

There are exactly three possible owners for a value the user has changed but
the server hasn't confirmed:

1. **The rows themselves** — the cell writes straight back into the row object
   (write-back). Terse at the cell, and wrong everywhere else; see the
   anti-pattern section.
2. **A page-level draft map** — edits accumulate in a map keyed by row id, and
   an explicit Save sends them (draft map).
3. **Nobody** — every commit persists immediately and optimistically; the
   server is the only truth (autosave).

A single static select flatters all three equally. The costs only separate
once a row can be **partially** dirty, once a field is backed by an **async
search**, and once a field changes **on every keystroke**. Design for those
three stressors and the right owner falls out.

## Ground rules — every pattern, no exceptions

- **Typed inputs commit on `@change` (blur/Enter), never `v-model`.** A text
  or number cell bound with `v-model` fires per keystroke; autosaving that is
  one request per character. Bind `:model-value` down and commit in `@change`.
  Don't reach for `@blur` + `@keydown.enter` as a substitute for `@change` —
  binding both fires the commit **twice** for the ordinary Enter-then-blur
  sequence (pressing Enter commits, and the field still blurs right after,
  which is a second, separate event on the same control). A "value unchanged"
  guard in the handler does not save you: the first commit's request is still
  in flight when the blur fires, so the handler is comparing the draft against
  a _stale_ prop that hasn't round-tripped yet, finds a difference, and sends
  a second, identical request. `@change` fires once for that whole sequence —
  that's the reason to prefer it over composing the two events yourself.
- **Pickers commit on pick.** For a select-backed cell the click already IS
  the commit — there is nothing to debounce and no blur to wait for.
- **Slot rows are read-only.** Props down, events up: the cell reads
  `item.field` (or a read-through, below) and emits/calls an action. The
  moment a cell needs `(item as any).field = value`, the types are telling you
  the ownership model is wrong.
- **Options resolve once, at page level, as an array — never a per-row
  provider.** Fifty rows with a shared statuses array cost zero requests;
  fifty rows each owning a provider cost fifty. The exception is a genuinely
  query-driven picker (an assignee search): share **one** provider function
  across all rows so each row's popover stays lazy and unopened rows cost
  nothing. See [BbSelectPopover](../BbSelectPopover.md) § One popover per
  table row.
- **Label the trigger from the row, never from the popover's `text`.** A lazy
  provider has no items until first open, so `text` is empty — but the row
  already knows its value.

## Pattern: draft map keyed by id (explicit save)

The page owns a `drafts` map; rows are never mutated. The map **is** the dirty
set **and** the save payload — no snapshot, no diff, no field list, and it
survives a refetch (a filter change or a poll cannot destroy edits).

```ts
import { reactive } from 'vue';

type Patch = Partial<Pick<Row, 'title' | 'estimate' | 'status' | 'assignee'>>;

const drafts = reactive<Record<string, Patch>>({});

/**
 * Read-through: the draft wins, the row is the fallback. Use a `key in`
 * check, NOT `??` — a field legitimately drafted to `null` (a cleared
 * number) is nullish, and `??` would silently fall through to the row.
 */
const valueOf = <K extends keyof Patch>(item: Row, key: K) => {
	const draft = drafts[item.id];
	return draft && key in draft ? (draft[key] as Row[K]) : item[key];
};

/** One setter covers every field and control kind. */
const setField = <K extends keyof Patch>(
	item: Row,
	key: K,
	value: Patch[K]
) => {
	if (JSON.stringify(value) === JSON.stringify(item[key])) {
		// Re-picking the original value un-dirties for free.
		delete drafts[item.id]?.[key];
		if (drafts[item.id] && !Object.keys(drafts[item.id]).length)
			delete drafts[item.id];
		return;
	}
	(drafts[item.id] ??= {})[key] = value;
};

const save = async () => {
	await api.bulkPatch(drafts); // the map IS the payload
	Object.keys(drafts).forEach((id) => delete drafts[id]);
	refreshKey.value += 1;
};
```

Cells read `valueOf(item, key)` and call `setField`; a field is dirty exactly
when `drafts[item.id]?.[key] !== undefined` — drive the dirty ring from that.
The Save button is dirty-gated (`Object.keys(drafts).length`).

**Reach for it when** the domain wants review-before-save: accounting lines,
settings pages, anything where a half-finished batch must not hit the server.
Assembled example: the line-item editor in the
[record form recipe](../recipes/vue/record-form.md) (drafted rows, one
explicit Save).

## Pattern: autosave — optimistic per-field (the flagship)

No dirty state exists at all. Each commit writes an **optimistic overlay**
for that one field, fires a single-field PATCH, and refreshes; failure rolls
back just that field. Two fields on the same row can be in flight
independently.

```ts
import { reactive, ref } from 'vue';

const pending = reactive<Record<string, Patch>>({});
const failed = ref(new Set<string>()); // keyed `${id}:${field}`
const refreshKey = ref(0);

// `key in` rather than `??`: an overlay holding a committed `null` (a
// cleared number mid-flight) must still win over the row.
const valueOf = <K extends keyof Patch>(item: Row, key: K) => {
	const patch = pending[item.id];
	return patch && key in patch ? (patch[key] as Row[K]) : item[key];
};

const persistField = async <K extends keyof Patch>(
	item: Row,
	key: K,
	value: Patch[K]
) => {
	const previous = valueOf(item, key); // snapshot for Undo, before the write
	if (JSON.stringify(value) === JSON.stringify(previous)) return; // no-op commit
	(pending[item.id] ??= {})[key] = value; // optimistic: the UI moves now
	failed.value.delete(`${item.id}:${key}`);
	try {
		await api.patch(item.id, { [key]: value });
		refreshKey.value += 1; // reload; the fetch retires the overlay (below)
		// NOTE: bumping this puts BbTable into its loading state, and loading
		// rows are `inert` by default — an open editor two rows down goes dead
		// for the length of the refetch. That is right for a user-triggered
		// reload and wrong for an autosave: pass `interactive-while-loading`
		// on the table so a background refresh never interrupts typing
		// (BbTable guide § Loading and empty states).
		// Auto-undo: a soft success toast whose action PATCHes the old value
		// back. The Undo is itself a persistField call, so it can be redone.
		// Re-resolve the row by id inside the action — the `item` captured here
		// goes stale after the refetch, and the no-op guard above would then
		// compare the revert against the stale value and swallow it.
		toast({
			title: `${String(key)} updated`,
			variant: 'success',
			actions: [
				{
					text: 'Undo',
					onClick: () => {
						const current = rows.value.find((r) => r.id === item.id) ?? item;
						return persistField(current, key, previous);
					},
				},
			],
		});
	} catch {
		// Rollback: drop just this field — the cell reverts to the row's value.
		delete pending[item.id]?.[key];
		if (pending[item.id] && !Object.keys(pending[item.id]).length)
			delete pending[item.id];
		failed.value = new Set(failed.value).add(`${item.id}:${key}`);
		toast({ title: 'Save failed', variant: 'destructive' });
	}
};
```

**Wire Undo into every commit.** A silent autosave leaves the user no way back
from a fat-fingered pick; a soft success toast carrying an **Undo** action —
which just PATCHes the snapshotted previous value back — makes every inline
edit reversible in one click (and re-doable, since Undo is itself a
`persistField` call). The toast `actions` array is the only primitive the
library ships for this; the snapshot + revert-PATCH is yours to wire, and it is
a few lines per page. Prefer this over a confirm dialog for reversible edits.

### Overlay retirement — the subtlety that bites

**Retire the overlay in the fetch, and only for fields the response actually
confirms — never when the save resolves.** Between the save landing and the
reload arriving, the table still holds the OLD row; clearing the overlay early
makes the cell revert to the stale value for the whole reload — visibly,
new → old → new. Fields still in flight are left alone:

```ts
const fetchRows = async (): Promise<Row[]> => {
	const rows = await api.list(filters);
	for (const row of rows) {
		const patch = pending[row.id];
		if (!patch) continue;
		for (const key of Object.keys(patch) as (keyof Patch)[]) {
			if (JSON.stringify(patch[key]) === JSON.stringify(row[key]))
				delete patch[key]; // the server's own data carries it now
		}
		if (!Object.keys(patch).length) delete pending[row.id];
	}
	return rows;
};
```

**Reach for it when** the product is a workspace with no Save button — the
Linear model. Assembled example: the
[inline-edit workspace recipe](../recipes/vue/inline-edit-workspace.md)
(also [nuxt](../recipes/nuxt/inline-edit-workspace.md) /
[inertia](../recipes/inertia/inline-edit-workspace.md)).

## Anti-pattern: write-back + snapshot diff

The terse-looking third option — the cell writes straight into the slot row —
is the one that never survives contact:

```ts
// The cast is the contract telling you no.
const writeBack = (item: Row, key: EditableKey, value: unknown) => {
	(item as any)[key] = value;
};
// Dirty set and save patch are REDISCOVERED by a diff against a snapshot,
// which must enumerate every editable field — forever.
```

Three structural failures: the dirty set and the patch are rediscovered by a
diff that must enumerate every editable field; the write needs an `any` cast
(slot rows are typed read-only for a reason); and the edits live in the rows,
so **any refetch — a filter change, a poll — silently destroys them**. Recipe
code additionally bans `as any` outright, so this pattern is unshippable by
doctrine, not just by taste.

## Save feedback: the editable badge grammar

Option-backed cells share one visual grammar (see
[Design language](./design-language.md) § Badges label state):

- The cell is a **self-contained component** (`StatusCell`, `RoleCell`) with
  `editable` / `dirty` / `loading` props: a plain `BbBadge` when not editable,
  and a `BbBadge` hosting a **`BbBadgeButton`** (bound to its own
  `BbSelectPopover` activator) when it is — never a button and a badge
  assembled at the call site, and never an outer button wrapping the badge.
- Changeability is signalled by an **internal trailing chevron**
  (`append:icon="lucide:chevron-down"` on the badge itself).
- While the commit is in flight, set the badge's **`loading`** — the spinner
  takes the chevron's place ([BbBadge](../BbBadge.md) § Loading state; the
  swap is same-size, nothing shifts).
- **The dirty ring belongs to explicit-save patterns; the spinner belongs to
  autosave.** A draft-map cell shows a `box-shadow: 0 0 0 2px var(--bb-primary)`
  ring meaning "changed, unsaved"; an autosave cell has no such state — its
  only transient is "saving", which the spinner carries. Never show both on
  one surface.
- Status colors come from the **soft palette** in
  [Design language](./design-language.md) § Using color — five accents
  (`soft-gray/blue/green/amber/red`), one shared treatment. The library ships
  none of them, so **register the names you use** in the plugin's
  `badgeVariants` **and** style `.bb-badge.bb-badge--<name>` in the project
  stylesheet. That registration is part of building this page, not a
  prerequisite someone else must have done — an editable status cell whose
  statuses are all `outline` has lost the signal the cell exists to carry.

## Which fields earn an editable cell — and which do not

**Inline edit is the default grammar for a mutable listing, but "mutable" is a
per-field judgement, not a blanket rule.** Turning every column into a control
is its own failure: the row stops reading as a record and starts reading as a
form, every cell grows a hit target competing with row selection and row
navigation, and the one field the user actually came to change is buried among
eleven they did not.

Ruled 2026-08-07: the library does **not** carry a hard rule that a writable
field must be an autosave cell. Use the shape of the decision instead.

**Earns an editable cell** — the edit is the reason someone opened the list:

- **Triage fields.** Status, assignee, priority, due date: changed often, from
  the list, without opening anything.
- **Small bounded values.** An estimate, a quantity, a short title — a full
  round trip through a detail page costs more than the edit is worth.
- **Anything a user would otherwise open a record just to change.** That trip is
  the cost inline edit exists to remove.

**Stays read-only** — an editable cell here is noise or a hazard:

- **Identity.** The name/reference column is the row's handle and its link to
  the record. Make it navigate; do not make it a text box.
- **Derived and computed values.** Totals, counts, age, "last seen". Editing
  the output of a calculation is not an edit, it is a corruption.
- **Server-owned facts.** Created-at, ids, audit fields, anything the user does
  not author.
- **Consequential or validated-in-context changes.** Anything needing
  confirmation, a reason, a permission check, or the rest of the record for
  context. Those belong in a peek or a detail form, where the user can see what
  they are agreeing to. A per-field autosave has no natural place to put a
  confirm step.
- **Fields whose validity depends on a sibling field.** Autosave commits one
  field at a time and cannot express "these two must agree".

A read-only cell in an otherwise editable table is not an inconsistency to
apologise for — it is information. The rule of thumb: if a column is a _fact
about_ the record rather than a _decision on_ it, leave it alone.

## Choosing — the decision table

|                    | Write-back                   | Draft map                  | Autosave                   |
| ------------------ | ---------------------------- | -------------------------- | -------------------------- |
| Who owns the edit  | the rows (mutated)           | a page-level map           | nobody — the server        |
| Survives a refetch | **no — edits destroyed**     | yes                        | yes (overlay + retirement) |
| Requests per save  | 1 bulk (after a diff)        | 1 bulk (the map)           | 1 per field commit         |
| State you maintain | snapshot + diff + field list | one map                    | overlay + failed set       |
| Save button        | yes                          | yes, dirty-gated           | none                       |
| Feedback grammar   | dirty ring                   | dirty ring                 | spinner in the chevron     |
| Reach for it       | never                        | review-before-save domains | Linear-style workspaces    |

## Where to see it assembled

- [BbTable](../BbTable.md) § Inline editing — a live, tested autosave example
  (commit-on-blur title cell + spinner-in-the-chevron status cell).
- [inline-edit workspace recipe](../recipes/vue/inline-edit-workspace.md) —
  the full autosave page (sprint backlog, every cell persists itself).
- [upload center recipe](../recipes/vue/upload-center.md) — one-click badge
  pickers (§6.1) plus commit-on-blur text/number/date cells on a mixed queue.
- [Fetch Data Items](./fetch-items-playbook.md) — the provider contract behind
  a search-backed assignee cell.

---

<!-- dist/ai/guides/installation-and-plugin-setup.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/installation-and-plugin-setup.md -->

# Installation and Plugin Setup

Source of truth for integrating `bitboss-ui`. Two pieces are always required:

1. a **build plugin** (`bitboss-ui/vite` or `bitboss-ui/nuxt`) that serves the `virtual:bitboss-ui/icons` and `virtual:bitboss-ui/config` modules, scans local SVG icons, and generates typed variant registries;
2. the **runtime plugin** (`bitbossUiPlugin` — installed automatically by the Nuxt module) that injects styles, provides the icon registry, and registers the `v-bb-tooltip`, `v-bb-dropdown`, `v-bb-color`, `v-bb-date` and `v-bb-time` directives.

## 1) Install

```bash
# v3 is a prerelease — a dist-tag is REQUIRED.
# A bare `npm install bitboss-ui` still resolves to v2, which has no build
# plugin and no `dist/ai` knowledge base, so everything below silently fails.
npm install bitboss-ui@beta
# recommended default icon set (any @iconify-json/* works)
npm install -D @iconify-json/lucide
```

Confirm you got v3 before continuing — `npm ls bitboss-ui` must report a
`3.0.0-*` version. If it reports `2.x`, nothing in this guide applies.

**`@beta` is the current v3 channel.** `@alpha` still resolves, but it is
frozen at the last alpha and does not receive fixes — it is not simply an older
copy of the same line. `@latest` is the **v2** line and always will be until v3
goes stable, so never reach for it here.

Peer dependency: `vue ^3.5.12` — the only required one. `@inertiajs/vue3` is an **optional** peer, needed only in Inertia apps.

`@iconify/collections` is an **optional** peer too, and npm never installs
optional peers automatically — install it yourself if you want the dev-time
provider-icon diagnostics:

```bash
npm install -D @iconify/collections
```

Without it the plugin has no list of valid Iconify prefixes, so the dev-overlay
errors below (the "install `@iconify-json/<prefix>`" hint and the "did you
mean …?" suggestion for a mistyped icon name) never fire — a wrong provider
icon then surfaces only as `BbIcon`'s generic runtime `Icon "…" does not exist.`
Nothing else changes: icons that resolve still render, in dev and in production.

**Known-good toolchain:** TypeScript **5.x or 6.x** if your build gate runs
`vue-tsc`. Both type-check cleanly against the shipped `.d.ts`; the library
itself builds on TypeScript 6 with `vue-tsc` 3. TypeScript **7** is the one to
avoid for now — it changed its package layout in a way `vue-tsc` (not a peer of
this library, but the typical `--noEmit` gate) cannot load, failing with
`ERR_PACKAGE_PATH_NOT_EXPORTED` on `./lib/tsc`. This library doesn't pin
TypeScript for you (it isn't `vue-tsc`'s maintainer), but a bare
`npm i -D typescript` in a fresh project can resolve to 7.x today — pin
`typescript: ^5` or `^6` yourself if `vue-tsc` is part of your gate.

**`vue-tsc` must be 3.x — 2.x is not "an older version that still works", it
is a gate that reports success while checking less than you think.** The
library's declarations are emitted by Vue Language Tools 3, and every component
declared with `generic="T"` emits as a generic _function_ (`declare const
__VLS_export: <T = any>(__VLS_props …) => VNode`) rather than the
`DefineComponent<…>` object non-generic components get. Vue Language Tools 2
does not read props out of that shape, so under `vue-tsc` 2 the template
type-checker silently type-checks **nothing** about the props of these nine
public components:

`BbSelect` · `BbSelectPopover` · `BbTable` · `BbTabs` · `BbTabsRoot` ·
`BbTree` · `BbRadioGroup` · `BbCheckboxGroup` · `BbSwitchGroup`

(and their `BbBase*` primitives). Missing required props, misspelled props,
wrong value types — all pass. The trap is that the failure is partial and
invisible: unknown-**component** checking still fires, non-generic components
like `BbButton` and `BbTextInput` still reject bad props, so the gate is
visibly working and you conclude the generic nine are covered too. A real
consumer shipped `<BbRadioGroup label="…">` (the prop is `legend`) through six
release slices on `vue-tsc@^2.2.12` with a green `--noEmit`; the same file under
`vue-tsc` 3.2.8 fails immediately with TS2345 + TS2322.

There is no runtime symptom to catch it later either — an unknown prop just
lands in `$attrs`. Upgrade the gate, don't work around it:

```bash
npm i -D vue-tsc@^3
```

### Browser support

The library targets **evergreen browsers** and ships **no polyfills**. The
floor is set by the native [Popover API](https://developer.mozilla.org/docs/Web/API/Popover_API),
which every floating surface (selects, dropdowns, popovers, tooltips, color
palette) renders through:

| Engine        | Minimum            |
| ------------- | ------------------ |
| Chrome / Edge | **114** (May 2023) |
| Safari        | **17** (Sep 2023)  |
| Firefox       | **125** (Apr 2024) |

Also relied on, all older than that floor: `<dialog>`, the `inert` attribute,
`ResizeObserver`, and CSS `grid-template-rows` transitions. On older engines
the floating surfaces simply don't render — there is no degraded mode — so if
your fleet includes browsers below the floor, this library is not a fit
without your own polyfill strategy (untested, unsupported).

## 2) Vite + Vue

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { bitbossUi } from 'bitboss-ui/vite';

export default defineConfig({
	plugins: [
		vue(),
		bitbossUi({
			iconDir: './src/assets/icons',
		}),
	],
});
```

```ts
// main.ts
import { createApp } from 'vue';
import App from './App.vue';
import { bitbossUiPlugin } from 'bitboss-ui';

const app = createApp(App);
app.use(bitbossUiPlugin);
app.mount('#app');
```

If the icon folder does not exist yet, create it (`mkdir -p src/assets/icons`) and keep the path aligned with `iconDir`.

## 3) Nuxt

The Nuxt module wraps the same Vite plugin and auto-registers the runtime plugin — no `app.use` needed:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
	modules: ['bitboss-ui/nuxt'],
	bitboss: {
		iconDir: './assets/icons', // module default
	},
});
```

All options below go under the `bitboss` config key. `nuxtLinkName` controls which globally registered component renders router links (default `'NuxtLink'`).

This module supersedes the standalone `@bitboss-dev/bitboss-ui-nuxt` package, which was the v2 Nuxt integration — uninstall it (see [Migration v2 → v3](./migration/v2-to-v3.md)).

### `autoImport?: boolean | { components?: boolean; composables?: boolean; validated?: boolean }` (default: `false`, Nuxt only)

Registers the library's components and composables with Nuxt's auto-import system, so templates write `<BbButton>` and `useToast()` with no import line:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
	modules: ['bitboss-ui/nuxt'],
	bitboss: {
		iconDir: './assets/icons',
		autoImport: true,
	},
});
```

`true` means `{ components: true, composables: true }`. Pass the object form to
narrow it, or to add `validated: true` — which resolves the form controls from
[`bitboss-ui/validated`](./validated-forms.md) instead of `bitboss-ui`, so
`<BbTextInput>` is the vee-validate-bound wrapper and takes `rules`, and adds
`BbForm`, `BbAsterisk`, `useBbFormContext` and `useValidatedField`. It needs the
`vee-validate` peer installed.

**It is off by default on purpose, and leaving it off is the better setup.**
Explicit imports are what make `vueCompilerOptions.checkUnknownComponents` (see
section 9) able to fail the build on a mistyped or unimported `Bb*` tag; with
auto-imports on, every `Bb*` tag resolves and that gate goes quiet. Reach for it
when you are moving an app off `@bitboss-dev/bitboss-ui-nuxt`, whose templates
were written against auto-imported components, and adding the imports is a
separate commit from the upgrade.

Two things it deliberately does not do. It never overrides your own components:
a `~/components/BbButton.vue` in the app keeps winning, and the library only
fills names the app has not claimed. And it never registers the library's
`useId` — Nuxt already auto-imports Vue's, and shadowing it would silently
redirect every existing `useId()` call in the app; import that one explicitly if
you want it.

## 4) Inertia

Inertia apps are Vite apps: configure `bitboss-ui/vite` exactly as in section 2, install `@inertiajs/vue3`, then install the runtime plugin in `createInertiaApp`:

```ts
createInertiaApp({
	// ...resolve/setup
	setup({ el, App, props, plugin }) {
		createApp({ render: () => h(App, props) })
			.use(plugin)
			.use(bitbossUiPlugin)
			.mount(el);
	},
});
```

That is the whole setup — **you do not need to register a link component**. When
the build plugin sees `@inertiajs/vue3` in your app, it imports Inertia's `Link`
on your behalf, so `href` on buttons/items performs Inertia visits (`method`,
`data`, `headers`, `preserveScroll`, …) out of the box.

If your app registers its **own** link wrapper globally — one with baked-in
defaults, analytics, whatever — that keeps winning: a component registered under
`inertiaLinkName` (default `'Link'`) is always preferred over the imported one.
Register it under a different name and point `inertiaLinkName` at it.

## 5) Styling

Two runtime options control CSS:

- `injectStyles` (default `true`) — auto-injects the library stylesheet (equivalent to `bitboss-ui/styles.css`: base styles + design tokens);
- `resetCss` (default `false`) — opt-in injection of the reset stylesheet.

Guaranteed order when injected: **reset → library styles → all other stylesheets**, so app-local CSS can always override the library.

`resetCss` stays opt-in because Tailwind projects already ship Preflight — a second reset is usually unnecessary.

**Tailwind v4 cascade layers vs. scoped `<style>`:** Tailwind v4's `@import
'tailwindcss'` puts every utility class in `@layer utilities`. A Vue SFC's
`<style scoped>` block is **unlayered** CSS, and per the cascade, unlayered
rules always beat layered rules of equal specificity — regardless of source
order. So a component with its own scoped layout-affecting rule silently
defeats a Tailwind utility applied to it from outside, with no warning from
`bitboss-ui check`, `eslint`, or `vue-tsc`:

```vue
<!-- Parent -->
<CategoryTree class="hidden lg:block" />

<!-- CategoryTree.vue -->
<style scoped>
.category-tree {
	display: flex; /* unlayered — always wins over the layered `hidden` utility */
}
</style>
```

`CategoryTree` never actually hides. Prefer `v-if`/JS conditionals over
utility classes for hide/show behavior on components (yours or ones built on
top of `bitboss-ui`) that carry their own layout-affecting scoped styles:

```vue
<CategoryTree v-if="showSidebar" />
```

Manual alternatives:

```ts
// with injectStyles: false — import once, before your own CSS
import 'bitboss-ui/styles.css';
// explicit reset instead of resetCss: true
import 'bitboss-ui/reset.css';
```

**Exception — an app that needs its own CSS to load _before_ the library.**
Auto-injection is library-first and not configurable: the runtime plugin
inserts its `<style>` **before the first** `style`/`link[rel="stylesheet"]`
already in `<head>` (`src/utils/injectLibraryStyles.ts`), so the guaranteed
order above is exactly what you get and every app stylesheet — your Tailwind
entry included — lands after the library. There is no option to inject later.

That is the order most apps want. It is the wrong order if you need library
rules to beat Tailwind's Preflight **by source order**, which is the case on
**Tailwind v3**: `@tailwind base` compiles to ordinary unlayered CSS, so under
auto-injection Preflight sits after the library sheet and its element resets
(`button`, `input`, `h1`, …) win every equal-specificity tie. `injectStyles:
false` + `resetCss: false` (the default) disables injection entirely and hands
you the order:

```ts
// vite.config.ts / the `bitboss` key in nuxt.config.ts
bitbossUi({ iconDir: '…', injectStyles: false, resetCss: false });
```

```ts
// app entry — order is yours now
import './app.css'; // your Tailwind entry
import 'bitboss-ui/styles.css'; // after Tailwind, so library rules win the ties
```

Leave `resetCss` at `false` here — Preflight already reset everything.
Nothing else about the plugin changes; `injectStyles` controls only whether the
library injects its own `<style>`.

**Tailwind v4 apps do not need this** — source order does not decide their ties
at all. `@import 'tailwindcss'` puts Preflight in a real `@layer base` and
utilities in `@layer utilities`, and layered rules lose to unlayered rules of
equal specificity **regardless of source order**. `dist/styles.css` declares no
`@layer`, so the library wins those ties wherever it is injected: leave
auto-injection on. The same mechanic bites the other way, and silently — a
utility cannot re-size a Bb component either. `<BbButton class="h-12 px-6">`
loses to the library's own `.bb-button { height: var(--h); padding-left:
var(--px); padding-right: var(--px) }` (equal specificity, unlayered), with no
warning from anything. Size Bb components through their props and tokens, never
utilities. (Same trap as the scoped-`<style>` case above, one level up.)

## 6) Icons

- `iconDir` (required) is scanned recursively for `.svg` files; each file becomes `local:<basename>`.
- Provider icons (`lucide:pencil`, `mdi:home`, …) require the matching `@iconify-json/<prefix>` package installed in the consumer app. Missing packages/icons produce actionable dev-overlay errors **only when the optional `@iconify/collections` peer is installed** (see [Install](#1-install)); otherwise you get `BbIcon`'s generic runtime error instead. Production builds report neither — this is a dev-time aid.
- Production builds bundle **only statically referenced** provider icons — write icon names as literal strings (`icon="lucide:trash-2"`), never assemble them dynamically.
- The plugin also writes `node_modules/.bitboss-ui/local-icons.json` and (in dev, unless `vscodeSettings: false`) wires `.vscode/settings.json` so the Iconify editor extension previews local icons.

Policy for choosing icons: [Icons Policy](./icons-policy.md).

## 7) Complete Option Reference

Options are the same for `bitboss-ui/vite` and the `bitboss` key in Nuxt.

### `iconDir: string` (required)

Path to local SVG icons, absolute or relative to project root. Scanned recursively; file basename (without extension) becomes the icon name, addressable as `local:<name>`.

### `injectStyles?: boolean` (default: `true`)

Auto-inject the library stylesheet at runtime. If `false`, you must `import 'bitboss-ui/styles.css'` manually.

### `resetCss?: boolean` (default: `false`)

Inject the reset stylesheet (always ordered before the library stylesheet). Keep `false` and import `bitboss-ui/reset.css` if you prefer explicit control.

### `injectDirectives?: boolean` (default: `true`)

Registers the global `v-bb-tooltip`, `v-bb-dropdown`, `v-bb-color`, `v-bb-date` and `v-bb-time` directives when the runtime plugin installs — all five, on both the Vue and the Nuxt runtime. Each registration is skipped if the app already declared a directive under that name, so disable the option only if you want none of them.

### `adaptive?: boolean` (default: `true`)

Default for the `adaptive` prop of surface components (BbDialog, BbPopover, BbDropdown, BbSelect): when true they open as a bottom sheet on mobile (below `mobileMaxWidth`) instead of their floating surface. An explicit per-component `adaptive` prop always wins.

### `vscodeSettings?: boolean` (default: `true`)

When `true`, the **dev server** adds `./node_modules/.bitboss-ui/local-icons.json` to `"iconify.customCollectionJsonPaths"` in the project's `.vscode/settings.json` on boot, so the Iconify IntelliSense extension previews your local icons. The write is idempotent (it happens at most once) and splice-based — comments, formatting, and key order in a hand-written JSONC file all survive — and the plugin logs exactly what it changed the one time it does. Set to `false` if the plugin should never touch `.vscode/settings.json`; in that case add the entry manually to keep the previews.

### `mcp?: boolean` (default: `false`)

When `true`, the **dev server** registers the bitboss-ui MCP server in each project-scoped agent-harness config on boot — `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), and `.vscode/mcp.json` (VS Code / Copilot) — so agents can query the knowledge base with no manual setup. The write is merge-safe (leaves other servers alone) and idempotent (only logs when it actually changes a file). Windsurf is intentionally **not** written here: its config is global (`~/.codeium`), and silently editing a home-dir file that affects every project on the machine from a dev-server boot would be surprising — run `npx bitboss-ui ai-init --mcp` to register Windsurf too. This flag is the zero-command equivalent of that command's project-scoped writes. The MCP server's own runtime — `@modelcontextprotocol/sdk` and `zod` — ships as **optional peer dependencies** (~12 MB, more than every runtime dependency of the library combined, and loaded by nothing else), so install them with `npm i -D @modelcontextprotocol/sdk zod` before the harness first launches the server; both this flag and `ai-init --mcp` warn when they are missing.

**MCP is a convenience, not a requirement, and skipping it costs no
knowledge.** The server is a reader over files the install already put on disk
— every tool `readFileSync`s out of `node_modules/bitboss-ui/dist/ai/` (plus
`dist/styles.css` for the token lookup). An agent that opens that directory
itself has the identical knowledge base, `npx bitboss-ui check` runs without the
peers, and `ai-init` (no `--mcp`) still writes the harness pointers. If you are
migrating under a "no new dependencies" constraint, leave `mcp` at `false`,
skip `--mcp`, and point your agent at `dist/ai/guides/ai-router.md`.

### `inertiaLinkName?: string` (default: `'Link'`)

Global component name used for Inertia links. **Optional** — when nothing is
registered under this name, the library falls back to the `Link` the build
plugin imported from your `@inertiajs/vue3` install. Set it only when you want a
wrapper of your own to be used instead.

### `nuxtLinkName?: string` (default: `'NuxtLink'`)

Global component name used for Nuxt link rendering.

### `linkActiveClass?: string` (default: `'router-link-active'`)

### `linkExactActiveClass?: string` (default: `'router-link-exact-active'`)

Class names applied to active / exact-active links in router-aware components. Align them with your router configuration.

### `mobileMaxWidth?: number` (default: `768`)

Pixel breakpoint for the library's mobile behavior (including `adaptive` surfaces).

### `ssrViewportWidth?: number` (default: `1024`)

The viewport width the library assumes while rendering **on the server**, where
the real screen size is unknowable. The default `1024` is a desktop width, so
server output is desktop-first. On the client the real `window.innerWidth` is
used from the first paint.

**Client-only SPA?** Ignore this — the real width is known from the first paint,
so `adaptive` surfaces are correct immediately.

**Server-rendering (Nuxt / Inertia SSR)?** By default the server renders
desktop-shaped; a mobile visitor's first paint is desktop-shaped and adjusts
once the client measures the real width (for closed overlays this is invisible —
they're not on screen yet; a Vue hydration warning may appear in dev). Set this
to a different width if your app is primarily consumed on a known form factor:

```ts
// vite.config.ts — build-time, applied to every server render.
bitbossUi({
	// ...other options,
	ssrViewportWidth: 768,
});
```

This is a **single global default baked in at build time** (it comes from the
Vite plugin config), so it is the same for every request — it is _not_ a
per-request value. There is no per-request/per-visitor override: the viewport
signal is a process-wide singleton, so a mobile layout that must be correct on
the server's first paint (e.g. a modal already open on load) needs a client
adjustment after hydration, or a fixed `ssrViewportWidth` matching your
audience. (Unlike `locale`, which **is** per-request — see below. A width
cannot be derived from a request without UA sniffing; a locale can.)

### `defaultInputLabelMode?: 'outside' | 'floating' | 'inside'` (default: `'outside'`)

Default label rendering mode for input-like components; set globally instead of repeating per field.

### `requiredAsterisk?: boolean` (default: `false`)

Marks required fields with a red asterisk beside the label/legend. Presentational only — it keys off the standard `required` prop and changes neither validation nor native `required` semantics. The marker is applied by the [`bitboss-ui/validated`](./validated-forms.md) controls — a field that is `required`, or whose `rules` contain a `required` rule; other rules never raise it, because they only apply once a value exists. Core controls ignore the flag, so on a hand-wired form render the exported `BbAsterisk` in your own label content.

### `locale?: LocaleKey` (default: `'it'`)

Global locale for the library's built-in strings (empty states, close/clear
labels, screen-reader announcements, confirm buttons, …). The library ships
**22 built-in dictionaries** — it, en, es, fr, de, pt (Brazilian-leaning), nl,
pl, tr, ru, uk, cs, ro, hu, el, sv, da, nb, fi, ja, ko, zh-cn — but shipping ≠
bundling: only the **enabled** locales enter your build (next option). Runtime
switching: `useBbConfig().setConfig({ locale })` — to a locale you enabled.

**Per-request locale under SSR** is supported as of 3.0.0-beta.15: the config
is held per Vue app, and SSR builds one app per request, so pass it where you
create the app — `app.use(bitbossUiPlugin, { locale: localeFor(request) })`.
That is correct on the server's first paint, which is what crawlers index and
what a JS-disabled reader keeps. `setConfig` still works for runtime switching;
during a server render call it from a component's `setup`, where it can resolve
the current app. From module scope there is no app to address, the write lands
on the build-time defaults, and it leaks between concurrent visitors — it warns
in dev when it sees that.

Note this is a **different rule** from `ssrViewportWidth` above, which really
is a build-time global: a width cannot be known per request without sniffing,
a locale can.

### `enabledLocales?: BuiltinLocaleKey[]` (default: your `locale` + `'en'`)

Which built-in dictionaries (and their dayjs calendar packs) actually ship in
the bundle. The unset default is the minimal set — the `locale` you configured
plus `en` (the per-key fallback anchor) — roughly 4KB of strings, so a
single-language app pays for exactly what it uses without configuring
anything. Apps that switch locales at runtime list what they offer:

```ts
bitbossUi({
	iconDir: './src/assets/icons',
	locale: 'it',
	enabledLocales: ['it', 'en', 'de', 'fr'], // ~4 dictionaries + 4 dayjs packs
});
```

Your `locale` and `'en'` are always auto-included, so the list never needs to
repeat them.
There is deliberately **no catch-all** ("all") value — it would hide the
bundle cost. Wanting every built-in means writing the list, so the cost is
visible in your config where reviewers can see it.

**Selecting a non-enabled locale is a compile error**, not a silent runtime
fallback: the generated `locale-registry.d.ts` registers only the enabled
built-ins, so `setConfig({ locale: 'ja' })` fails to type-check until `'ja'` is
enabled. Run dev once after changing the list.

### Custom locales are not a supported surface

The library ships **22 dictionaries** and that is the whole set:

```
cs da de el en es fi fr hu it ja ko nb nl pl pt ro ru sv tr uk zh-cn
```

There is no `additionalLocales` option and no `npx bitboss-ui locale` blueprint
generator — both were removed deliberately (owner ruling, 2026-08-08). If your
language is not on that list, the supported answer is to ask for it to be
added upstream rather than to author a dictionary in your app.

Locale selection is **build-time**: `enabledLocales` decides what ships, and
only the active `locale` switches at runtime, among what the build enabled.

### `toastPosition?: BbToastPosition` (default: `'bottom-right'`)

Default viewport corner for toasts when neither the toast nor the `<BbToast>` host specify one. One of `'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'`.

### `iconDefaultSizes?: Partial<Sizes>`

Default icon size scale used by `BbIcon` and avatar dimensions. Partial overrides merge onto:

`{ xs: 12, sm: 16, md: 24, lg: 28, xl: 36, '2xl': 40 }`

### `dialogDefaultSizes?: Partial<Sizes>`

### `offCanvasDefaultSizes?: Partial<Sizes>`

Global size maps (pixels) for BbDialog / BbOffCanvas. Both default to:

`{ xs: 320, sm: 384, md: 448, lg: 512, xl: 576, '2xl': 672 }`

Provide only the keys you want to override, e.g. `dialogDefaultSizes: { md: 500, xl: 680 }`.

### Variant registries

Each option **appends** custom names to the default set (trimmed, deduplicated) and regenerates a typed union (`*-variants.d.ts`) on build start. Unstyled custom variants only add a class hook — supply their CSS yourself.

**The generated `*-variants.d.ts` files are per-project output, not a portable
variant list.** They mirror the plugin config of the project that last ran the
plugin in that folder, and are rewritten by every build/dev/test process. Your
project's registry is what **your** plugin config declares — never trust names
read out of another checkout's copy (e.g. the library repo's own tracked seeds
list variants that exist only in its dev showcase). Each generated file now
says this in its header.

| Option                 | Defaults                                                | Class hook for custom entries       |
| ---------------------- | ------------------------------------------------------- | ----------------------------------- |
| `buttonVariants`       | `primary, outline, secondary, ghost, destructive, link` | `bb-button--<name>`                 |
| `alertVariants`        | `outline, primary, destructive, warning`                | `bb-alert--<name>`                  |
| `badgeVariants`        | `primary, secondary, destructive, outline`              | `bb-badge--<name>`                  |
| `indicatorVariants`    | `default, success, info, warning, destructive`          | `bb-indicator--<name>`              |
| `confirmVariants`      | `default, destructive`                                  | `bb-confirm--<name>`                |
| `dropdownItemVariants` | `default, destructive`                                  | `bb-dropdown__item--variant-<name>` |
| `tooltipVariants`      | `default, destructive`                                  | `bb-tooltip--<name>`                |
| `toastVariants`        | `default, success, info, warning, destructive`          | `bb-toast-message--<name>`          |

Variant props are locked to the registered set (`keyof <X>VariantRegistry`):
an unregistered name is a compile error, not a silently unstyled render.
Register custom names here (typed, autocompleted), or force a one-off with an
explicit cast — the runtime class is still plain interpolation, so its CSS
applies either way.

**Adding a variant is a normal, expected consumer change** — the defaults are a
floor, not a vocabulary you must stay inside. A page that needs a tone the
library doesn't ship registers it here **and** styles its class hook in a
project stylesheet loaded after `bitboss-ui/styles.css`; both halves, or you get
an unstyled pill (CSS missing) or a compile error (registration missing). If the
design calls for semantic status colors, take the canonical palette from
[Design Language](./design-language.md) § Getting soft semantic badges rather
than inventing hues.

## 8) AI Knowledge Base

The package ships its agent docs in `node_modules/bitboss-ui/dist/ai/`. **Start at** `guides/ai-router.md`, then the catalogue `index.md`. Run `npx bitboss-ui ai-init` in the consumer project to inject harness-agnostic pointers (AGENTS.md, Cursor rules, Copilot instructions, Claude skill, Windsurf rules) so coding agents discover them without a vendor lock-in. After generating Bb\* markup, run `npx bitboss-ui check` (supports `--json`) so unknown props fail before review.

**Three tiers ship under `dist/ai/`**, and the third one is easy to miss:
`guides/` + `recipes/` are the authored prose; `<Name>.md` at the root is the
generated typed contract for each component (props, slots, events, examples);
`source/<Name>.md` is that same component's **complete implementation** —
`.vue` template, `types.ts` and `index.css` in one file, one per component
including the internal ones the package does not export. Read the source tier
when the contract cannot answer the question — the usual case is rebuilding
chrome around a control the library does not ship, since the class names such a
template emits are already styled by the public `bitboss-ui/styles.css`.

Add `--mcp` to also register a live MCP server (`npx bitboss-ui@<installed version> mcp`, pinned so npx can never fetch a different version from the registry) the harness launches on demand — it merges the entry (never overwriting other servers) into `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), `.vscode/mcp.json` (VS Code / Copilot), and `~/.codeium/windsurf/mcp_config.json` (Windsurf). **Windsurf's config is global** — it has no per-project scope, so registering it affects every project on the machine; that is why only the explicit `ai-init --mcp` command writes it, while the plugin's `mcp: true` dev-server flag (§7) auto-registers the project-scoped harnesses only. Install the server's optional peers first — `npm i -D @modelcontextprotocol/sdk zod` — they are not dependencies of the library (~12 MB used only by the MCP server); the command warns if they are absent. **`--mcp` is optional and skipping it loses you nothing but the transport** — the server only reads the `dist/ai/` files listed above, so run plain `ai-init` and let the agent read that directory if you cannot add the peers (see `mcp?: boolean` in §7).

For a human-in-the-loop (and agent) safety net, add the `bitboss-ui/eslint-plugin` flat-config plugin (`...bitbossUi.configs.recommended`) so unknown/removed `Bb*` props surface as ESLint errors in the editor and CI — the same manifest checks as `bitboss-ui check`, reusing your `eslint-plugin-vue` parser. Real HTML attributes fall through untouched; escape hatches are the standard `<!-- eslint-disable-next-line bitboss-ui/no-unknown-attributes -->` and the rule's `allowAttributes` / `allowComponents` options. **`eslint --fix` also auto-migrates deprecated v2 props** (renames, boolean-polarity inversions like `allowWriting`→`disableWriting`, value remaps like BbToast `placement`→`position`, and deletion of inert removed props); structural migrations that need a slot/directive/CSS are reported but left by hand. One deliberate boundary: the rule's "did you mean `<prop>`?" hints for a mistyped/unknown attribute are advisory message text, not fixes — `eslint --fix` (including an unattended run in a pre-commit hook) never applies them; only the registered v2→v3 migrations above are auto-fixed. A guess applied blind across a codebase would be a silent behavior change, so acting on a hint is always a per-site decision. **This library is TS-first (recipes ship `<script setup lang="ts">`, some with `generic="T"`), so wire `@typescript-eslint/parser` for both `.ts` and `.vue` files** — without it `vue-eslint-parser` throws a `Parsing error` on those files, which means no rule (including `no-unknown-attributes`) runs on them at all. See the README "ESLint plugin" section for the full config snippet (both parser blocks + the `npm i -D @typescript-eslint/parser` line) and the fix table. `recommended` also enables `bitboss-ui/no-active-class-on-root-link`: `active-class` on a link-capable `Bb*` component (`BbButton`/`BbBaseButton`/`BbBadgeButton`) matches by path PREFIX, so a link whose target is the literal root (`href="/"` / `to="/"`) reads as "active" on every URL — the rule flags that combination and points you at `exact-active-class` instead.

**The manifest ships with the package** — `dist/ai/components.json` is inside
the tarball, and the rules resolve it relative to their own file, so a normal
install needs no configuration. If it ever cannot be read (a broken install, a
source checkout with no build, or an explicit `manifestPath` pointing at
nothing), the rules cannot check anything: they now **warn once** saying they
are inactive rather than passing silently. Pass `failClosed: true` to a rule's
options if you would rather CI stop than under-check.

It also enables `bitboss-ui/require-partner-prop`: an opt-in prop set without its documented required partner — BbTable `keyboard-navigation` / `v-model:highlighted` without `row-class` (the shipped tint says "current row"; `row-class` says why, and is how you override it), or `loading-text` without `:loading` bound — compiles and mounts clean and just does nothing; the rule names the missing partner and quotes why.

## 9) Setup Verification Checklist

- [ ] package installed (plus `@iconify-json/*` packages for every provider prefix used);
- [ ] build plugin configured: `bitboss-ui/vite` plugin or `bitboss-ui/nuxt` module (`bitboss` config key);
- [ ] `iconDir` points at an existing SVG folder;
- [ ] runtime plugin installed: `app.use(bitbossUiPlugin)` (automatic in Nuxt);
- [ ] style strategy chosen: auto injection (default) or `injectStyles: false` + `import 'bitboss-ui/styles.css'` — auto injection is always library-first, so a Tailwind **v3** app that needs Preflight to load before the library must take the second option (§5);
- [ ] if a reset is required: `resetCss: true` or `import 'bitboss-ui/reset.css'`;
- [ ] Inertia apps: `@inertiajs/vue3` installed (no link registration needed; set `inertiaLinkName` only if you register your own link wrapper).
- [ ] building the [Layout Scaffold](../recipes/vue/layout-scaffold.md)? `npm i @vueuse/core` — `usePageShellContext.ts` imports `injectLocal`/`provideLocal` from it. This library depends on it too, so it can resolve via hoisting without being declared — don't rely on that; declare it in your own `package.json` or a strict installer (pnpm, Yarn PnP) will fail to resolve it.
- [ ] `vite.config.ts` (and any other build config, e.g. `eslint.config.js`) is inside your project's type-check scope — a `tsconfig.node.json` project reference is the conventional shape. Otherwise `bitbossUi(...)`'s typed options (`locale`, the `*Variants` registries, `iconDefaultSizes`, …) are never checked by `vue-tsc --noEmit`, silently defeating the compile-time guarantees this guide documents (e.g. "selecting a non-enabled locale is a compile error").
- [ ] `vue-tsc` is **3.x** (`npx vue-tsc --version`). On 2.x the template type-checker cannot read props off the generic-function declarations this library emits for `BbSelect`, `BbSelectPopover`, `BbTable`, `BbTabs`, `BbTree`, `BbRadioGroup`, `BbCheckboxGroup` and `BbSwitchGroup`, so their props go **entirely unchecked** — missing, misspelled and wrongly-typed props all pass — while unknown-component checking and every non-generic component keep erroring normally, which is exactly why a 2.x gate reads as healthy. See "Known-good toolchain" in [1) Install](#1-install).
- [ ] `tsconfig.json` sets `"vueCompilerOptions": { "checkUnknownComponents": true }`. Vue Language Tools 3 (`vue-tsc`) treats unknown-component checking as **opt-in** — without this flag, a `<BbTabs>` used without its import (or after a typo, or dropped by a bad auto-import config) type-checks clean, lints clean, and passes `bitboss-ui check` (none of the three gates resolve component tags), then renders as a silent unregistered custom element in the browser: no error anywhere, just a missing widget in production. With the flag, `vue-tsc --noEmit` names the exact tag and line (`Property 'BbTabs' does not exist on type '{}'.`) on the offending file, with no false positives from the library itself — nothing in `bitboss-ui`'s runtime plugin globally registers `Bb*` components (only the `v-bb-*` directives are global), so every `Bb*` tag in your templates is expected to resolve through an explicit import.

If one of the checks fails, fix setup before creating component examples.

---

<!-- dist/ai/guides/migration/components/bb-alert.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-alert.md -->

# BbAlert — v2 → v3

## Changes

| v2                                      | v3                                                                                                   | Kind                                       |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `showClose?: boolean` (default `true`)  | `hideClose?: boolean` (default `false`)                                                              | rename, polarity inverted                  |
| `theme?: string`                        | `variant?: AlertVariantType` (default `outline`; built-ins `outline, primary, destructive, warning`) | typed — unregistered names fail to compile |
| `ariaAtomic?: boolean` (default `true`) | removed                                                                                              | correct live-region behavior hardcoded     |
| `icon?: BbIconProps['type']`            | `icon?: IconType` (also accepts raw `?raw` SVG)                                                      | widened                                    |
| —                                       | `role`, `ariaLive`, `transitionDuration`                                                             | additive (auto-derived from variant)       |

Also fixed, worth knowing if you worked around it: the `#text` slot's scope
prop now actually carries `text` (v2 mistakenly passed `title`).

## Edits

```diff
- <BbAlert :show-close="false" title="Saved" text="All changes stored." />
+ <BbAlert hide-close title="Saved" text="All changes stored." />

  <!-- passing showClose's default -->
- <BbAlert show-close … />
+ <BbAlert … />

- <BbAlert theme="warning" title="Quota almost reached" />
+ <BbAlert variant="warning" title="Quota almost reached" />
```

A hand-applied `class="bb-alert--warning"` also becomes `variant="warning"` —
see [main guide §7](../v2-to-v3.md). Custom `theme` names: register via the
plugin's `alertVariants` option and keep your CSS.

## ⚠ `theme` painted nothing in v2 — and now two identical call sites diverge

v2's stylesheet shipped **zero** `.bb-alert--*` rules. The component emitted
`bb-alert--${theme}` faithfully, but unless your own CSS defined the rule, every
value rendered the same default surface. `theme="success"`, `theme="blue"` and
`theme="warning"` were the same alert.

In v3 the string is live, and what happens next depends on nothing but whether
the name collides with a built-in (`outline`, `primary`, `destructive`,
`warning`):

```diff
  <!-- these two rendered identically in v2 -->
- <BbAlert theme="success" title="Saved" />
+ <BbAlert variant="success" title="Saved" />
  <!-- `success` is not an alert built-in → compile error until you register it. You will notice. -->

- <BbAlert theme="warning" title="Quota almost reached" />
+ <BbAlert variant="warning" title="Quota almost reached" />
  <!-- `warning` IS a built-in → compiles, and silently repaints amber (#fffbea on #fee685). You will not. -->
```

The rename diff above is a **visual change** for `warning`, not a no-op. Before
converting any `theme=` value, grep your own stylesheets for
`.bb-alert--<value>`:

- **Nothing styled it** → the value was decoration. Drop the prop and take the
  v3 default, or register the name via `alertVariants` and ship no CSS for it,
  which holds v2's appearance exactly.
- **Your CSS styled it** → register the name and keep your rule; `warning` is
  the one case where your rule now lands on top of a library skin, so check
  that you override every property it sets (background, border, `--main-color`,
  `--muted-color`) and not just the ones your v2 rule needed.

The same trap applies to `BbTooltip` and `toast()` — v2 styled none of their
theme classes either.

---

<!-- dist/ai/guides/migration/components/bb-avatar.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-avatar.md -->

# BbAvatar — v2 → v3

## Changes

| v2               | v3                                                                                            | Kind                                                                                                |
| ---------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `color?: string` | removed                                                                                       | the fallback surface paints from two locals on `.bb-avatar` — `--bg-color` / `--text-color` (below) |
| `timeout`        | unchanged (SSR image grace period — **not** renamed; only `BbTooltip.timeout` became `delay`) | —                                                                                                   |

## Edits

```diff
- <BbAvatar :src="user.photo" :alt="user.name" color="#7c3aed" />
+ <BbAvatar :src="user.photo" :alt="user.name" />
```

## Where the color went

`.bb-avatar` declares three locals and reads them for the fallback (initials,
slotted content, or the built-in person glyph — an image covers all of them):

| local                  | default                                    | paints                      |
| ---------------------- | ------------------------------------------ | --------------------------- |
| `--bg-color`           | `var(--bb-primary)`                        | the avatar background       |
| `--text-color`         | `var(--bb-primary-fg)`                     | initials / slotted fallback |
| `--default-icon-color` | 80% mix of `--bb-primary-fg` over the fill | the built-in person glyph   |

Set them on a scope, not on the component:

```css
.team-avatar .bb-avatar {
	--bg-color: #7c3aed;
	--text-color: #fff;
}
```

⚠ Set **both**. `--bg-color` alone leaves the initials at `--bb-primary-fg`,
which is the contrast pair for the _primary_ color, not for yours — the symptom
is white-on-pale or black-on-dark initials.

Use this for a color that genuinely varies per instance (per-team, per-tenant).
If the v2 `color` was your brand color repeated at every call site, retheme
`--bb-primary` / `--bb-primary-fg` once instead and write no per-avatar rules.
That is the order the BbAvatar usage guide prescribes: retheme the tokens
first, reach for the locals only when the value is per-instance.

## `.bb-avatar--square` was never a library modifier

If your app has a `.bb-avatar--square` rule, it is **your** CSS. v2 shipped no
such modifier — its entire avatar stylesheet was four rules, all hardcoding
`border-radius: 50%`, and the string `square` appears nowhere in the v2
package. v3 bakes in the same circle.

So nothing was removed and there is no v3 modifier to rename to. Your rule
keeps working: it has the same specificity as the library's `.bb-avatar` rule
and the library sheet is injected above your app CSS, so yours wins the tie.
Rename the class to an app-owned block (`.p-avatar--square`) anyway, so the
next reader does not take it for library API and go hunting for a `shape` prop.

---

<!-- dist/ai/guides/migration/components/bb-badge.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-badge.md -->

# BbBadge — v2 → v3

**The name changed meaning.** This is the one place in v3 where the same tag
renders a different component:

- **v2 `BbBadge`** anchored a floating count/dot to a wrapped element
  (notification-bubble pattern). That component is now **`BbIndicator`**.
- **v3 `BbBadge`** is an inline pill/label with `variant`, `icon`, `loading`,
  `clearable` — it also absorbs the removed `BbChip`.

Every v2 `<BbBadge>` in your codebase must be reviewed: rename it to
`BbIndicator`, or — if it was actually used as a standalone colored label —
re-express it with the new badge's `variant` API.

## v2 BbBadge → v3 BbIndicator

| v2 `BbBadge`                         | v3 `BbIndicator`                                                                                     |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| `content?: string \| number \| null` | `text?: string \| number` — plus new `max?: number` (renders `${max}+`)                              |
| `color?: string` (free-form)         | `variant?: IndicatorVariantType` (`default, success, info, warning, destructive`; default `default`) |
| `dot`, `left`, `bottom`              | unchanged — including precedence: `dot` renders a contentless bubble and **suppresses** the label    |
| `floating`                           | removed — the indicator always positions against its slotted anchor                                  |
| `#content` slot                      | dropped — use `text`                                                                                 |

```diff
- <BbBadge :content="unread" color="#dc2626" floating>
+ <BbIndicator :text="unread" :max="99" variant="destructive">
    <BbButton icon="lucide:bell" variant="ghost" />
- </BbBadge>
+ </BbIndicator>
```

If you styled `.bb-badge` in CSS for this use, the block is now
`.bb-indicator` (`--dot`, `--left`, `--bottom`, `--<variant>` modifiers).

### `dot` beats the label — in both versions

`dot` and the label are not additive and never were. v2 rendered the content
span only when `dot` was false; v3 does the same with `text`. Passing both has
always produced a bare dot.

The trap is on the way out, not the way in. A v2 call site that toggled the dot
off a count —

```diff
- <BbBadge :content="unread" :dot="unread !== null" />
+ <BbIndicator :text="unread" :dot="unread !== null" />
```

— shipped a **dot**, never the number, and the port above keeps it that way.
Drop `dot` and port `content` to `:text="unread"` alone and the number appears
where it never did before. Carry `dot` across unchanged unless you mean to
change the design.

Nothing renders at all when `dot` is false and `text` is `null`/`undefined`, so
`:text="count || undefined"` is the way to hide a zero.

## v2 BbChip → v3 BbBadge

Same role (dismissible token), two functional deltas: `clearable` is now
**opt-in** (chips defaulted clearable), and the label is the **default slot**
— there is **no `text`/`content` prop** on the v3 badge.

```diff
- <BbChip :text="tag.name" @click:clear="remove(tag)" />
+ <BbBadge clearable @click:clear="remove(tag)">{{ tag.name }}</BbBadge>
```

`clearableLabel` and the `click:clear` event carry over unchanged. CSS:
`.bb-chip*` → `.bb-badge*` (`.bb-chip__clear-button` → `.bb-badge__clear-button`).

### Clickable chips: `BbBadgeButton`

A v2 chip that was _also_ clickable was typically hand-built — a `<button>`
wrapping the chip, or a chip inside an `@click` div. v3 has a first-class form:
slot a **`BbBadgeButton`** as a direct child and the badge body becomes a real
`<button>`, while the clear control stays a separate sibling button.

```diff
- <button class="chip-button" @click="edit(filter)">
-   <BbChip :text="filter.label" @click:clear="remove(filter)" />
- </button>
+ <BbBadge clearable @click:clear="remove(filter)">
+   <BbBadgeButton @click="edit(filter)">{{ filter.label }}</BbBadgeButton>
+ </BbBadge>
```

The v2 nesting was invalid markup (a `<button>` may not contain another
button); the v3 form is two sibling controls, so both are keyboard-reachable.
`BbBadgeButton` composes `BbBaseButton`, so `href`/`to`/Inertia navigation and
`disabled` work on it too. It must be a **direct child** of the badge.

## The v3 badge itself

`variant?: BadgeVariantType` (default `primary`; built-ins
`primary, secondary, destructive, outline`), `size` (default `md`), `icon` /
`prepend:icon` / `append:icon`, `loading`. Unregistered variant names are
compile errors — register custom ones via the plugin's `badgeVariants` option
([main guide §4](../v2-to-v3.md)).

Hand-built pills (`<span class="bb-badge bb-badge--secondary">`) should become
real `<BbBadge variant="secondary">` elements — see
[main guide §7](../v2-to-v3.md).

### Internal DOM changed (CSS only)

The badge now renders two side wrappers so the body and the clear control can
be independent controls:

```html
<span class="bb-badge">
	<span class="bb-badge__body">…icon + <span class="bb-badge__content" /></span>
	<span class="bb-badge__trailing">…append icon + clear button</span>
</span>
```

All existing class hooks (`.bb-badge`, `.bb-badge__content`,
`.bb-badge__clear-button`, `.bb-badge__prepend-icon`, `.bb-badge__append-icon`,
every `--<variant>` / `--<size>` modifier) are unchanged and still match. **Only
direct-child selectors break** — `.bb-badge > .bb-badge__content` must become a
descendant selector, since the content span now sits inside `.bb-badge__body`.

Two related CSS shifts, both invisible unless you overrode them: the pill's
inline padding moved onto the side wrappers (via new `--pad-left` /
`--pad-right` custom properties) so each hit area runs flush to the border, and
the clear button's hover wash moved from the button onto its glyph, so the
button can span the full pill height while only the circle looks interactive.

---

<!-- dist/ai/guides/migration/components/bb-breadcrumbs.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-breadcrumbs.md -->

# BbBreadcrumbs — v2 → v3

## Changes

| v2                                | v3                                                                                           | Kind                                                                                                                |
| --------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| item `key: string \| number`      | `key: string`                                                                                | retype — numeric keys fail `vue-tsc`; wrap in `String(...)` (runtime already stringified, so behavior is unchanged) |
| `divider?: string` (text divider) | removed                                                                                      | the divider is slot-driven; use the divider slot for custom glyphs                                                  |
| `dividerWidth` default `5`        | default `16`                                                                                 | visual — only matters if you tuned overflow math around the old default                                             |
| per-item slots by raw `key`       | by `slotKey(key)` — `#Order History` → `#order_history`                                      | **⚠ silent** — stale raw names render fallback content                                                              |
| —                                 | item `prepend:icon` / `append:icon`, per-key `:prepend`/`:append` slots, overflow forwarding | additive                                                                                                            |

## Edits

```diff
- <BbBreadcrumbs :items="[{ key: 1, text: 'Home', href: '/' }]" divider=">">
+ <BbBreadcrumbs :items="[{ key: 'home', text: 'Home', href: '/' }]">
-   <template #Order History>…</template>
+   <template #order_history>…</template>
  </BbBreadcrumbs>
```

---

<!-- dist/ai/guides/migration/components/bb-button.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-button.md -->

# BbButton — v2 → v3

## Changes

| v2                                              | v3                                                | Kind                                                               |
| ----------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------ |
| `autoLoading?: boolean` (default `false`)       | `disableAutoLoading?: boolean` (default `false`)  | **⚠ silent behavior flip** — auto loading is now **on** by default |
| `tooltip`, `tooltipPlacement`, `tooltipTimeout` | removed                                           | built-in tooltip dropped                                           |
| `theme?: string`                                | removed                                           | use `variant` (typed) or a class                                   |
| `variant?: string`-ish                          | `variant?: ButtonVariantType` (default `primary`) | unregistered names are now compile errors; `none` opts out         |
| `size`                                          | `Responsive<Sizes>`, gains `'2xl'`                | additive; per-breakpoint maps use `{ default: 'md', lg: 'xl' }`    |
| `tag: string`                                   | `'button' \| 'div' \| 'span' \| 'label'`          | narrowed to the tags the button actually supports                  |

## The loading flip

In v2 a button with an `async` `@click` handler did nothing special unless you
passed `auto-loading`. In v3 every async handler shows the spinner and
disables the button until the promise settles.

- If you passed `auto-loading` in v2: **delete the prop** — it's the default.
- If you relied on the button staying enabled during an async handler
  (double-submit flows, fire-and-forget clicks): pass `disable-auto-loading`,
  or `interactive-while-loading` if you want the spinner but not the disable.
- If you hand-rolled loading (`:loading="saving"` + a `saving` ref around an
  await): you can usually delete the ref — the button does it now.

```diff
- <BbButton auto-loading @click="save">Save</BbButton>
+ <BbButton @click="save">Save</BbButton>

  <!-- v2 behavior preserved explicitly -->
- <BbButton @click="fireAndForget">Ping</BbButton>
+ <BbButton disable-auto-loading @click="fireAndForget">Ping</BbButton>
```

## Tooltip props

```diff
- <BbButton tooltip="Delete forever" tooltip-placement="top" variant="destructive" />
+ <BbButton v-bb-tooltip:top="'Delete forever'" variant="destructive" />
```

The `v-bb-tooltip` directive is registered by the runtime plugin (see the
[main guide](../v2-to-v3.md) §1). For rich content, wrap in `BbTooltip`.

## Class overrides

`<BbButton class="bb-button--outline">` → `<BbButton variant="outline">`.
See [main guide §7](../v2-to-v3.md) for the full pattern and how to register
custom variant names.

## Skin colors: four locals became six theme tokens per variant

v2 shipped **no** variant CSS — `.bb-button--outline`, `--secondary`, `--ghost`
and friends had zero rules in the library sheet. If your app has buttons that
look like anything but the primary fill, your stylesheet built the skin, by
setting locals that `.bb-button` read:

```css
/* v2 theming.css — you wrote this, and it was the whole variant */
.bb-button--outline {
	--color: #fff;
	--border-color: #d1d5db;
	--text-color: #111827;
	/* hover / pressed / focus were DERIVED from --color automatically */
}
```

v3 reads none of those four names. Each variant paints from its own `--bb-*`
family, declared in `variables.css` and overridable globally or on any scope:

| v2 local on `.bb-button`                   | v3                       |
| ------------------------------------------ | ------------------------ |
| `--color` (fill)                           | `--bb-<variant>`         |
| `--text-color`                             | `--bb-<variant>-fg`      |
| `--border-color`                           | `--bb-<variant>-border`  |
| `--ring-color`                             | `--bb-<variant>-ring`    |
| _derived_ `mix(--color 90%, black)`, hover | `--bb-<variant>-hover`   |
| _derived_ `mix(--color 80%, black)`, press | `--bb-<variant>-pressed` |

`<variant>` is `primary`, `secondary`, `outline`, `ghost`, `destructive` or
`link`.

⚠ Note the last two rows. v2 **derived** hover and pressed from the fill; v3
**states** them. Port only `--bb-outline` and the button keeps the library's
default hover, which will not be a shade of your color.

```css
/* v3 equivalent of the v2 block above */
:root {
	--bb-outline: #fff;
	--bb-outline-border: #d1d5db;
	--bb-outline-fg: #111827;
	--bb-outline-hover: #f3f4f6;
	--bb-outline-pressed: #e5e7eb;
}
```

Silent by construction: a rule setting `--color` on `.bb-button` still parses,
still applies, and is read by nothing. `rg -n -- '--color|--text-color|--border-color|--ring-color'`
across your CSS and find the ones scoped to a button.

Don't confuse this with the `--bb-button-*` row in
[main guide §3](../v2-to-v3.md): the button's **dimensions** went down into
component locals, its **colors** went up into global theme tokens. Opposite
directions, same component.

## `loading-text` was never a BbButton prop

Not in v2, not in v3. If you find `loading-text` on a v2 button it was landing
in `$attrs` and rendering nothing — delete it rather than looking for the
replacement. The prop is real on the list and group surfaces — `BbSelect`,
`BbCheckboxGroup`, `BbRadioGroup`, `BbTable`, `BbSelectPopover` — where it
carries over to v3 under the same name.

---

<!-- dist/ai/guides/migration/components/bb-checkbox-group.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-checkbox-group.md -->

# BbCheckboxGroup / BbRadioGroup / BbSwitchGroup — v2 → v3

The three groups share their surface (`BbSwitchGroup` re-exports
`BbCheckboxGroupProps`); everything below applies to all three unless noted.

## Changes

| v2                                                                              | v3                                                      | Kind                                                                                                              |
| ------------------------------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `labelPosition?: 'left' \| 'center' \| 'right'`                                 | `legendPosition`                                        | rename                                                                                                            |
| per-item `disabled` honored (with a deprecation warning)                        | **inert** — plain data, no warning                      | **⚠ silent** — use `selectable?: boolean \| ((item) => boolean)`                                                  |
| `color?: string`                                                                | removed                                                 | style via tokens/CSS                                                                                              |
| `#option:prepend` / `#option:append` slots                                      | removed                                                 | use the `#label` slot (scoped `{ item, text, checked }`) to decorate options                                      |
| `items` provider unions, `itemText` / `itemValue`                               | unified provider signature + `ItemAccessor`             | retype — plain arrays and `(prefill) => Promise<T[]>` providers unchanged                                         |
| `name: string` required (**BbRadioGroup** only; the other two already optional) | `name?: string` (auto-generated per group when omitted) | relaxation — the generated name is unique per group instance, so options still group and two groups never collide |
| —                                                                               | `legendMode: 'outside' \| 'inside'`, `description`      | additive                                                                                                          |
| `BbSwitchGroup` `multiple: false` silently ignored (always array emit)          | honored — emits a bare value in single-select mode      | **⚠ behavioral** (bugfix: the prop was advertised but never forwarded; fixed 2026-07-18)                          |
| `disabled` / `selectable: false` left a **selected** option interactive         | a selected option is disabled like any other            | **⚠ behavioral** (bugfix, 2026-08-31 — see below)                                                                 |

`max` (checkbox/switch), `required` (radio), and `multiple` defaults are
unchanged.

## Edits

```diff
- <BbCheckboxGroup
-   v-model="plans"
-   :items="tiers.map(t => ({ ...t, disabled: t.soldOut }))"
-   label-position="left"
-   color="#0ea5e9"
- >
-   <template #option:append="{ item }">
-     <BbBadge v-if="item.popular">Popular</BbBadge>
-   </template>
- </BbCheckboxGroup>
+ <BbCheckboxGroup
+   v-model="plans"
+   :items="tiers"
+   :selectable="(t) => !t.soldOut"
+   legend-position="left"
+ >
+   <template #label="{ item, text }">
+     {{ text }}
+     <BbBadge v-if="item.popular" variant="secondary">Popular</BbBadge>
+   </template>
+ </BbCheckboxGroup>
```

The `item.disabled` change is the dangerous one: nothing errors, options that
used to render disabled simply become selectable. Grep item-building code for
`disabled:` near these groups.

## `disabled` now disables the selection too

Until 2026-08-31 a **selected** option in a `disabled` (or
`selectable: false`) group stayed interactive: it rendered without the native
`disabled` attribute, and clicking it emitted `update:modelValue` with the
option removed. So a fieldset switched off to prevent edits still let the user
clear the value it was showing.

```vue
<!-- before: "a" was clickable, and clicking it emitted [] -->
<BbCheckboxGroup v-model="picked" disabled :items="items" legend="Plan" />
```

The resolver short-circuited on `selected` above both checks. That escape
exists for the **`max` swap affordance** — at the cap, already-selected options
stay live so the user can trade one for another — and it now sits only above
the `max` check, where it belongs. Unchanged:

```vue
<!-- still works: at max, selected options remain tradeable -->
<BbCheckboxGroup v-model="picked" :max="1" :items="items" legend="Plan" />
```

**What to check when you upgrade.** If you relied on the old behaviour to let
someone _remove_ a value from an otherwise locked group, `disabled` is no
longer the prop for that — it now means what it says. Use `readonly`, which
keeps the options focusable and announced (`aria-readonly`) while blocking
every change, or leave the group enabled and gate on your own handler.

## DOM: the shared `bb-cr-container` block split three ways

v2 rendered one prefix for all three groups — `bb-cr-container` ("checkbox /
radio") — so a rule written for one group hit all of them. v3 gives each group
its own block; the suffixes are otherwise identical.

| v2                                    | v3 (`{checkbox,radio,switch}`)            |
| ------------------------------------- | ----------------------------------------- |
| `.bb-cr-container`                    | `.bb-base-{checkbox,radio,switch}-group`  |
| `.bb-cr-container--horizontal`        | `.bb-base-…-group--horizontal`            |
| `.bb-cr-container--vertical`          | `.bb-base-…-group--vertical`              |
| `.bb-cr-container--errors`            | `.bb-base-…-group--errors`                |
| `.bb-cr-container__container`         | `.bb-base-…-group__container`             |
| `.bb-cr-container__loading-container` | `.bb-base-…-group__loading-container`     |
| `.bb-cr-container__no-data-container` | `.bb-base-…-group__no-data-container`     |
| `.bb-cr-container-option`             | `.bb-base-…-group-option`                 |
| `.bb-cr-container-option__text`       | `.bb-base-…-group-option__text`           |
| —                                     | `.bb-base-…-group--warnings` (new)        |
| —                                     | `.bb-base-…-group-option--selected` (new) |

Nothing in v3 renders any `bb-cr-container` class, and nothing warns — the rules
simply stop matching. **Grep your CSS and test selectors for `bb-cr-container`.**

One rule that used to cover three components is now three rules. If you were
relying on the shared prefix, group the selectors:

```css
.bb-base-checkbox-group-option__text,
.bb-base-radio-group-option__text,
.bb-base-switch-group-option__text {
	font-weight: 500;
}
```

**`BbRating` is not in this family.** v2's stylesheet carried
`.bb-rating … .bb-cr-container__container` rules, but the component never
rendered those classes on either version — it has always used
`.bb-base-rating__inner-container` / `.bb-base-rating__option`. See
[bb-rating.md](./bb-rating.md).

## `legend` is required — and always was

`legend: string` is a required prop on `BbCheckboxGroup`, `BbRadioGroup` and
`BbSwitchGroup` in **v2 and v3 alike** (v2 `dist/components/BbCheckboxGroup/types.d.ts`
declares `legend: string`, not `legend?`). If the upgrade surfaced missing-legend
errors across your app, that is a pre-existing bug the stricter v3 build made
visible — not a v3 break, and not something to "fix" as part of the upgrade.

Treat it as its own change, separately from the migration. One migration team
added `legend` to six groups mid-upgrade; supplying it let the generic `T`
resolve properly, which unblocked type inference on the whole subtree and
surfaced a cascade of unrelated downstream type errors. They reverted the lot.
Land the migration first, then add legends one component at a time.

---

<!-- dist/ai/guides/migration/components/bb-checkbox.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-checkbox.md -->

# BbCheckbox / BbRadio / BbSwitch — v2 → v3

The three single controls share their prop surface (`BbSwitch` re-exports
`BbCheckboxProps`); every change below applies to all three unless noted.

## Changes

| v2                                                                           | v3                                                          | Kind                                                                                                                           |
| ---------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `reverse?: boolean` (default `true`)                                         | `reverse?: boolean` (default `false`, **meaning inverted**) | **⚠ silent** — see below                                                                                                       |
| `checked?: boolean \| 'true' \| 'false'`                                     | `checked?: boolean`                                         | retype — string forms fail to compile (`checked="false"` was truthy anyway; this failure is loud where the old one was silent) |
| `color?: string`                                                             | removed                                                     | style via theme tokens / CSS                                                                                                   |
| `indeterminate` loose type (checkbox)                                        | `boolean`                                                   | retype                                                                                                                         |
| `name: string` required (**BbRadio** only; checkbox/switch already optional) | `name?: string` (auto-generated per button when omitted)    | relaxation — a hand-composed group still needs one shared explicit `name`, since generated ones differ per button              |
| —                                                                            | `description`                                               | additive (all three)                                                                                                           |
| —                                                                            | `compact` — **group components only**                       | additive on `BbCheckboxGroup` / `BbRadioGroup` / `BbSwitchGroup`; the three single controls have no `compact` prop             |

## The `reverse` flip, precisely

Both versions render the **same default layout** (control first, then label).
What inverted is what the prop _means_:

- v2: `reverse` defaulted `true`; passing `:reverse="false"` produced the
  swapped (label-first) layout.
- v3: `reverse` defaults `false` = the same standard layout; passing
  `reverse` now _opts into_ the swapped layout.

So explicit values translate **by inversion**:

| v2 usage                      | v3 equivalent                 |
| ----------------------------- | ----------------------------- |
| (unset)                       | (unset) — identical rendering |
| `reverse` / `:reverse="true"` | delete the prop               |
| `:reverse="false"`            | `reverse`                     |

```diff
- <BbCheckbox v-model="ok" :reverse="false" label="I agree" color="#16a34a" />
+ <BbCheckbox v-model="ok" reverse label="I agree" />
```

`rg -n 'reverse' --type vue` and review each hit on these components — the
compiler cannot catch a boolean that changed meaning.

---

<!-- dist/ai/guides/migration/components/bb-chip.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-chip.md -->

# BbChip — removed in v3

The component and its exports (`BbChipProps`, …) no longer exist. The
reasoning: a clearable chip is a dismissible badge, and a non-clearable chip
_is_ a badge — so the library ships one component.

| v2                                                            | v3                                                           |
| ------------------------------------------------------------- | ------------------------------------------------------------ |
| `<BbChip :text="label" />` (default `clearable`)              | `<BbBadge clearable>{{ label }}</BbBadge>`                   |
| `<BbChip :text="label" :clearable="false" />`                 | `<BbBadge variant="secondary">{{ label }}</BbBadge>`         |
| `clearableLabel`, `@click:clear`                              | unchanged on `BbBadge`                                       |
| `.bb-chip`, `.bb-chip__content`, `.bb-chip__clear-button` CSS | `.bb-badge`, default slot content, `.bb-badge__clear-button` |

Two gotchas:

- `clearable` **defaults flipped**: chips were clearable unless told otherwise;
  badges are not clearable unless told so. A bare swap silently loses the ×.
- The label moves from the `text` prop to the **default slot** — the v3 badge
  has no text/content prop, and a prop passed anyway renders an empty pill.

Do not reach for `BbTag` — despite the name it is an unrelated multi-value
_input_ (`v-model: string[]`), not a display token.

If your chip was **clickable as well as dismissible** (a filter chip: press the
body to edit, press the × to remove), that is now `BbBadgeButton` slotted into
the badge — see [bb-badge.md](./bb-badge.md#clickable-chips-bbbadgebutton).
Don't reproduce the v2 habit of wrapping the whole chip in a `<button>`: with
`clearable` that nests a button inside a button, which is invalid markup.

Full badge/indicator picture: [bb-badge.md](./bb-badge.md).

---

<!-- dist/ai/guides/migration/components/bb-collapsible.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-collapsible.md -->

# BbCollapsible — v2 → v3

## Changes

| v2                                          | v3        | Kind                                                                                                                                                         |
| ------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `tag?: string` (default `'div'`)            | removed   | the root is a **`span`** (`display: grid`) — an inline element, so it is valid inside a `<p>`; wrap in a semantic element if you passed `tag="section"` etc. |
| `modelValue`, `eager`, `transitionDuration` | unchanged | —                                                                                                                                                            |

## Edits

```diff
- <BbCollapsible v-model="open" tag="section">…</BbCollapsible>
+ <section>
+   <BbCollapsible v-model="open">…</BbCollapsible>
+ </section>
```

Reminder (unchanged from v2, but often misread): the component is fully
controlled — it renders `modelValue` and never toggles itself; the trigger
stays in your markup.

---

<!-- dist/ai/guides/migration/components/bb-color-input.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-color-input.md -->

# BbColorInput — v2 → v3

## Changes

| v2                                   | v3                                       | Kind                                                        |
| ------------------------------------ | ---------------------------------------- | ----------------------------------------------------------- |
| `picker?: boolean` (default `false`) | `eyeDropper?: boolean` (default `false`) | rename (same feature; `BbColorPalette` got the same rename) |
| `direction`                          | `InputDirection`                         | family-wide retype                                          |
| —                                    | `labelMode`, `description`               | additive                                                    |

## Edits

```diff
- <BbColorInput v-model="brand" picker />
+ <BbColorInput v-model="brand" eye-dropper />
```

`alpha` and `swatches` are unchanged.

---

<!-- dist/ai/guides/migration/components/bb-color-palette.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-color-palette.md -->

# BbColorPalette — v2 → v3

## Changes

| v2                                           | v3                                                                 | Kind                                                                                               |
| -------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `flip?: boolean` (default `true`)            | `disableFlip?: boolean` (default `false`)                          | rename, polarity inverted                                                                          |
| `showArrow?: boolean` (default `false`)      | removed                                                            | arrows are tooltip-only in v3; **⚠ silent** — a leftover `show-arrow` lands in `$attrs`            |
| `arrowPadding`                               | removed                                                            | dead with the arrow                                                                                |
| `picker?: boolean`                           | `eyeDropper?: boolean`                                             | rename (same eyedropper feature)                                                                   |
| `update:open` event                          | removed                                                            | track open state via the activator slot's `open` if you need it                                    |
| `update:modelValue` payload `string \| null` | `string` — the palette always emits a concrete color, never `null` | **behavior** — clearing is the consumer's job now; handlers narrowing on `null` have dead branches |
| activator slot prop `color`                  | `value`                                                            | rename                                                                                             |

## Edits

```diff
- <BbColorPalette v-model="color" :flip="false" show-arrow picker @update:open="track">
-   <template #activator="{ props, color }">
-     <button v-bind="props" :style="{ background: color }" />
+ <BbColorPalette v-model="color" disable-flip eye-dropper>
+   <template #activator="{ props, value, open }">
+     <button v-bind="props" :style="{ background: value }" />
    </template>
  </BbColorPalette>
```

---

<!-- dist/ai/guides/migration/components/bb-date-picker-input.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-date-picker-input.md -->

# BbDatePickerInput — v2 → v3

## Changes

| v2                                                        | v3                                                                                                                         | Kind                                                             |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `allowWriting?: boolean \| 'not-mobile'` (default `true`) | `disableWriting?: boolean \| 'mobile' \| 'desktop'` (default `false`)                                                      | rename, polarity inverted, **token set changed**                 |
| `hidePopover?: boolean \| 'not-mobile'`                   | `disableCalendar?: boolean \| 'mobile' \| 'desktop'` (default `false`)                                                     | rename, same polarity, **token set changed**                     |
| `width?: number \| string`                                | removed                                                                                                                    | calendar sizes itself; use CSS on `.bb-date-picker*` if you must |
| day slots by raw date                                     | `#<slotKey(date)>` — `#2024-03-15` → `#2024_03_15` (plus new scoped `day` / `append:day` slots)                            | **⚠ silent** — stale raw-date slot names render fallback         |
| non-floating output: UTC `Z` (`2025-12-31T23:00:00.000Z`) | local-offset ISO (`2026-01-01T00:00:00+01:00`); new `utc` prop restores the v2 output                                      | **⚠ silent** — same instant, different digits (see below)        |
| —                                                         | `adaptive` (mobile bottom sheet, on by default), `offCanvasProps`, `labelMode`, `description`, `transitionDuration`, `utc` | additive                                                         |
| `datetime?: boolean` _(v3 alphas ≤ 4)_                    | `type?: 'date' \| 'datetime' \| 'month' \| 'year'` (default `'date'`)                                                      | **hard rename**, and the axis grew two new values                |

`floating` (plain-date output), `range`, `min`/`max`, `selectable`,
`firstDayOfWeek` are unchanged.

## `datetime` became `type` (v3 alpha, 2026-08-05)

The boolean is gone — there is no alias and nothing warns at runtime beyond the
register, so **grep for it**. It was folded into a single `type` axis because
the two facts it encoded (what the value _is_, how precise it is) turned out to
be one fact, and because `datetime` could never be combined with the month and
year units that now live on the same prop.

```diff
- <BbDatePickerInput v-model="startsAt" v-model:time="time" datetime />
+ <BbDatePickerInput v-model="startsAt" v-model:time="time" type="datetime" />
```

`seconds`, `ampm`, `step` and `v-model:time` are unchanged — they still ride
along, now gated on `type="datetime"` instead of the boolean. The same rename
applies to `BbDatePicker` and to the `v-bb-date` directive's props bag.

Two new values come with it, both emitting **calendar labels rather than
instants** (`floating` is forced, `utc` is ignored):

| `type`  | segments  | emits     | range emits              |
| ------- | --------- | --------- | ------------------------ |
| `month` | `MM/YYYY` | `2026-08` | `['2026-01', '2026-03']` |
| `year`  | `YYYY`    | `2026`    | `['2026', '2028']`       |

`min`/`max` follow the same shape (`min="2026-03"`); a finer bound is accepted
and rounded outward to the unit with a DEV warning, so `min="2026-03-15"` under
`type="month"` still leaves the whole of March selectable.

> **`range` requires an array modelValue.** As in v2, range mode's value must
> always be an array — use `[]` for the empty state, never `null`/`undefined`.
> Binding a non-array throws _"Date picker is set to select multiple dates but
> modelValue is not an array."_ If a filter models "unset" as `null` elsewhere,
> seed and clear this field to `[]`.

## The allowWriting mapping

| v2                                                    | v3                                |
| ----------------------------------------------------- | --------------------------------- |
| unset / `allow-writing`                               | unset (typing allowed everywhere) |
| `:allow-writing="false"`                              | `disable-writing`                 |
| `allow-writing="not-mobile"` (typing only on desktop) | `disable-writing="mobile"`        |

```diff
- <BbDatePickerInput v-model="date" allow-writing="not-mobile" :width="320" />
+ <BbDatePickerInput v-model="date" disable-writing="mobile" />
```

## The hidePopover mapping

Same polarity (`true` still means "no calendar"), but the platform token
changed: v2's `'not-mobile'` meant "hidden where not mobile", which is v3's
`'desktop'`.

| v2                                                    | v3                           |
| ----------------------------------------------------- | ---------------------------- |
| unset / `:hide-popover="false"`                       | unset (calendar everywhere)  |
| `hide-popover` / `:hide-popover="true"`               | `disable-calendar`           |
| `hide-popover="not-mobile"` (calendar only on mobile) | `disable-calendar="desktop"` |

```diff
- <BbDatePickerInput v-model="date" disable-writing="mobile" hide-popover="not-mobile" />
+ <BbDatePickerInput v-model="date" disable-writing="mobile" disable-calendar="desktop" />
```

> v2 additionally threw on the `disable-writing="mobile"` +
> `hide-popover="not-mobile"` combination even though its own error message
> recommended it (the mobile guard misread `'not-mobile'`). v3's guard is
> coherent: the pair above is the blessed "type on desktop, tap the calendar
> on mobile" split.

## Non-floating output: local offset instead of UTC `Z`

v2 emitted `value.toISOString()` — always UTC. A Berlin user picking Jan 1
emitted `2025-12-31T23:00:00.000Z`, so backends doing `substring(0, 10)` got
the wrong day. v3 emits the same instant with the local offset —
`2026-01-01T00:00:00+01:00` — so the emitted digits match what the user sees
in the fields.

- **Reading is unaffected.** Incoming values parse identically whether they
  carry `Z`, an offset, or no zone at all — stored v2 values keep working.
- **If your backend requires `Z` output**, add the `utc` prop: it restores
  the exact v2 emission and changes nothing else (fields still display local
  time).
- `utc` is ignored (with a DEV warning) when `floating` is set — a plain date
  carries no zone.

```diff
  <!-- keep v2's UTC output -->
- <BbDatePickerInput v-model="date" />
+ <BbDatePickerInput v-model="date" utc />
```

## DOM: the segmented field has one neutral class family (2026-08-07)

**This is a breaking DOM change for the date input.** The date and time inputs
render the same segmented anatomy — sizers, native fields, separators, a
trailing trigger. They now share one set of element names, owned by neither
control. If you have CSS targeting `.bb-base-date-picker-input__field` and
friends, rename it:

| v2 / early v3 alpha                                                                         | v3                                                      |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `.bb-base-date-picker-input__fields`                                                        | `.bb-segmented-field__fields`                           |
| `…__fields--empty` / `…__fields--range`                                                     | `.bb-segmented-field__fields--*`                        |
| `.bb-base-date-picker-input__placeholder`                                                   | `.bb-segmented-field__placeholder`                      |
| `.bb-base-date-picker-input__field-sizer`                                                   | `.bb-segmented-field__field-sizer`                      |
| `.bb-base-date-picker-input__field` (+ `--day`, `--month`, `--year`, `--start`, `--end`, …) | `.bb-segmented-field__field` (same modifiers)           |
| `…__separator`, `…__separator--range`                                                       | `.bb-segmented-field__separator(--range)`               |
| `.bb-base-date-picker-input__calendar-btn`                                                  | `.bb-segmented-field__trigger-btn`                      |
| `…__calendar-btn--active`                                                                   | `.bb-segmented-field__trigger-btn--active`              |
| `.bb-base-date-picker-input__calendar-icon`                                                 | `.bb-segmented-field__trigger-icon`                     |
| `…__calendar--sheet`                                                                        | `.bb-base-time-picker-input__panel--sheet` (time input) |
| `.bb-base-date-picker-input__inner-wrapper`                                                 | **removed** — see below                                 |

`__inner-wrapper` has no v3 counterpart. It was a bare layout box
(`flex: auto; display: block`) between the input chrome and the fields; v3
drops the element and `.bb-segmented-field__fields` carries the layout. A rule
hanging off it stops matching with nothing to rename it to — delete it, and if
it was doing real work, move the declarations onto `__fields`.
| `…__calendar`, `…__calendar--shown` | removed — they were styled nowhere |
| `.bb-base-time-picker-input__clock-btn` | removed — use `.bb-segmented-field__trigger-btn` |

**The block names are unchanged.** `.bb-base-date-picker-input` and
`.bb-base-time-picker-input` are still the roots, so a rule that has to reach
exactly one control still can:

```css
/* only the time input's fields */
.bb-base-time-picker-input .bb-segmented-field__field {
	…
}
```

Anything outside the shared field anatomy stays component-owned and did not
move: `__accessible-description` on both, and `__panel`, `__panel--sheet`,
`__popover` on the time input.

---

<!-- dist/ai/guides/migration/components/bb-dialog.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-dialog.md -->

# BbDialog — v2 → v3

v2's `BbDialog` was a re-export of `BaseDialog`; v3 makes it first-class
(deprecated `BaseDialogProps`-style type aliases remain for one major).

## Changes

| v2                                                  | v3                                                                                                                                  | Kind                                                                                                      |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `showClose?: boolean` (default `true`)              | `hideClose?: boolean` (default `false`)                                                                                             | rename, polarity inverted                                                                                 |
| `description`                                       | removed                                                                                                                             | put it in the default slot / `header` slot                                                                |
| `#description` slot                                 | removed                                                                                                                             | same — and the `aria-describedby` wiring goes with it                                                     |
| `#close` slot                                       | removed                                                                                                                             | a custom close control goes inside `#header`, which replaces the default ✕ — no `hide-close` alongside it |
| `hideHeader`                                        | removed                                                                                                                             | omit `title` and the header collapses; or use the `header` slot                                           |
| `compact`                                           | removed                                                                                                                             | spacing is token-driven now (`--bb-panel-p`)                                                              |
| `overlayClasses`, `panelClasses` (deprecated in v2) | removed                                                                                                                             | use normal `class` / CSS on `.bb-dialog*`                                                                 |
| `size?: 'sm' \| 'md' \| 'lg'`                       | `size?: Responsive<'xs'…'2xl' \| CSS length>`                                                                                       | widened — **but defaults changed, see below**                                                             |
| `transitionDuration` default `300`                  | default `250`                                                                                                                       | visual                                                                                                    |
| —                                                   | `adaptive` (default from config, **on**), `offCanvasProps`, `stack`, `fullscreen`, `persistent`, `disabled`, `focusTarget`, `eager` | additive                                                                                                  |

## ⚠ The two silent ones

1. **Widths.** The size presets resolve from config, and the defaults changed:
   v2 `{ sm: 384, md: 652, lg: 896 }` → v3
   `{ xs: 320, sm: 384, md: 448, lg: 512, xl: 576, '2xl': 672 }`. A
   `size="md"` dialog loses ~200px. Pin the old values via
   `dialogDefaultSizes` in the plugin if your layouts assumed them
   ([main guide §2](../v2-to-v3.md)).
2. **Mobile.** With `adaptive` on by default, dialogs render as a bottom sheet
   below the mobile breakpoint. Opt out per dialog (`:adaptive="false"`) or
   globally (`adaptive: false` plugin option).

## Edits

```diff
- <BbDialog v-model="open" :show-close="false" size="md" description="Review before sending">
+ <BbDialog v-model="open" hide-close size="md">
+   <template #header="{ titleId }">
+     <h2 :id="titleId">Review before sending</h2>
+   </template>
    …
  </BbDialog>
```

## CSS and tokens

The `--bb-dialog-*` family is gone. Padding comes from the shared
`--bb-panel-p` and the local axis pair `--px` / `--py` on `.bb-dialog`; the
rest are unprefixed locals on `.bb-dialog` or plain CSS rules. `BbOffCanvas`
is identical throughout with `.bb-offcanvas__*` parts and the same `--px` /
`--py` names.

| v2 token                                     | v3                                                                                     |
| -------------------------------------------- | -------------------------------------------------------------------------------------- |
| `--bb-dialog-px` / `--bb-dialog-py` (`24px`) | local `--px` / `--py` on `.bb-dialog`, each branching off `--bb-panel-p` (`16px`)      |
| `--bb-dialog-close` (`12px`)                 | **delete it** — v3's default already reproduces v2's control size                      |
| `--bb-dialog-title-size` (`18px`)            | local `--dialog-title-fs` on `.bb-dialog`, default `calc(var(--bb-fs) + 2px)` = `16px` |
| `--bb-dialog-title-weight` (`600`)           | no knob — `500` is hard-coded; override with a CSS rule                                |
| —                                            | local `--dialog-gap`, default `--py` — the body↔footer vertical rhythm                 |

### `--bb-dialog-close` → delete it

v2's `--bb-dialog-close` was the close **icon** width; the button around it
added `padding: 8px`, so the control measured `12 + 16 = 28px`. v3 inverts the
relationship: `.bb-close-button { --size }` is the whole control box and the
glyph is derived — `max(--size - 2 × --p, 10px)`. Inside a dialog v3 already
ships `--size: 28px; --p: 7px`, a 14px glyph in the same 28px control v2's
default produced.

So carrying the old number across shrinks the target: `--size: 12px` gives a
12×12px control, well under the 24px WCAG 2.5.8 minimum. To get the old 12px
glyph back, widen the padding — never shrink the box:

```css
/* 12px glyph, still a 28px control */
.my-dialog .bb-dialog__header > .bb-close-button {
	--p: 8px;
}
```

The library rule is `.bb-dialog .bb-dialog__header > .bb-close-button` (0,3,0),
so your selector needs three classes to win. A headerless dialog puts the ✕ at
`.bb-dialog__body:first-child .bb-dialog__body-content > .bb-close-button`.

### The title

```css
.my-dialog {
	--dialog-title-fs: 18px; /* v2 --bb-dialog-title-size; drives line-height too */
}
.my-dialog .bb-dialog__header .bb-dialog__title {
	font-weight: 600; /* v2 --bb-dialog-title-weight */
}
```

There is no weight token in v3. `500` is hard-coded on
`.bb-dialog .bb-dialog__header .bb-dialog__title` (0,3,0), so match that
specificity — a two-class `.my-dialog .bb-dialog__title` loses.

### Asymmetric padding

The local pair `--px` / `--py` splits the axes; each branches off
`var(--bb-panel-p)`, so setting `--bb-panel-p` alone still moves both. Like
every unprefixed component token, set the pair on the component's class, never
`:root` (other components also use `--px` as a sealed local of their own, so a
dialog-scoped value never leaks into the buttons or alerts inside). v2's `--bb-dialog-px` / `--bb-dialog-py` map onto it directly:

```css
/* v2: --bb-dialog-px: 24px; --bb-dialog-py: 10px */
.my-dialog {
	--px: 24px; /* horizontal padding + close-button inline inset */
	--py: 10px; /* vertical padding + close-button block inset */
}
```

Per-**part** vertical differences (header `py: 10px`, body `py: 20px`) work by
scoping the token to the part class — the padding rules resolve it on the part
elements and the token inherits:

```css
.my-dialog .bb-dialog__header {
	--py: 10px; /* top 10px, bottom py/2 = 5px; the × inset follows */
}
.my-dialog .bb-dialog__body-content {
	--py: 20px; /* bottom padding, and top in the headerless case */
}
```

Derived spacings scale with it (header bottom is `py / 2`; the close button's
block inset tracks the header's `py`). For exact literals instead of those
ratios, use a `padding-block` rule on the part class — `padding-block`, not
the `padding` shorthand, so the horizontal half keeps tracking
`--px`. Library selectors are `.bb-dialog .bb-dialog__header`
(0,2,0), `.bb-dialog__body-content` (0,1,0),
`.bb-dialog__body:first-child .bb-dialog__body-content` (0,2,1) and
`.bb-dialog .bb-dialog__footer` (0,2,0) — a three-class app rule beats all
four.

### `--dialog-gap`

If only the vertical rhythm _between parts_ differs, `--dialog-gap` does it
without a padding rule — it replaces `--py` in the body's bottom
padding and the footer's block padding:

```css
.my-dialog {
	--dialog-gap: 8px;
}
```

It does **not** reach the header's top padding, any horizontal padding, or the
body's top padding in the headerless case; those still read `--py` (and
`--px` for the horizontal slots).

### `.bb-confirm`

`confirm()` renders through the same `.bb-dialog__*` parts, so everything above
reaches it. Its own button hooks changed — see
[use-confirm.md](./use-confirm.md).

---

<!-- dist/ai/guides/migration/components/bb-dropdown-button.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-dropdown-button.md -->

# BbDropdownButton — v2 → v3

## Changes

| v2                                                | v3                                               | Kind                                                                                                             |
| ------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `autoLoading?: boolean` (default `true`)          | `disableAutoLoading?: boolean` (default `false`) | rename, polarity inverted — same effective default                                                               |
| `disabledWhileLoading?: boolean` (default `true`) | removed                                          | always disabled while loading now; `BbButton`'s `interactive-while-loading` is the escape hatch on plain buttons |
| `theme?: string`                                  | removed                                          | use `variant` (shares `ButtonVariantType`)                                                                       |
| `arrowPadding`                                    | removed                                          | dead prop (no arrow on dropdown surfaces)                                                                        |
| —                                                 | `right:icon?: IconType`                          | additive — replaces the default toggle chevron                                                                   |

## Edits

```diff
- <BbDropdownButton :auto-loading="false" :items="items">Actions</BbDropdownButton>
+ <BbDropdownButton disable-auto-loading :items="items">Actions</BbDropdownButton>

  <!-- passing autoLoading's default -->
- <BbDropdownButton auto-loading :items="items">Actions</BbDropdownButton>
+ <BbDropdownButton :items="items">Actions</BbDropdownButton>

  <!-- disabledWhileLoading had no opt-out replacement -->
- <BbDropdownButton :disabled-while-loading="false" … />
+ <BbDropdownButton … />  <!-- accept the disable; it prevents racing the pending action -->
```

---

<!-- dist/ai/guides/migration/components/bb-dropdown.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-dropdown.md -->

# BbDropdown / `v-bb-dropdown` — v2 → v3

## Changes

| v2                                   | v3                                                                                                                                                                                                                        | Kind                                                                                                                                                                |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| items extended `BaseButtonProps`     | items extend `BbBaseButtonProps`                                                                                                                                                                                          | transparent unless you typed items with the old export                                                                                                              |
| item label conventions               | `text` is the expected label field; `description` renders a second line                                                                                                                                                   | check items built as plain link objects                                                                                                                             |
| `arrowPadding`                       | removed                                                                                                                                                                                                                   | dead prop (dropdowns never show an arrow)                                                                                                                           |
| exposed `loading` (via template ref) | removed                                                                                                                                                                                                                   | read in-flight async state from the activator slot scope (`loading`) instead of a component ref. **⚠ silent**: a stale `dropdownRef.value?.loading` is `undefined`. |
| —                                    | item `variant?: DropdownItemVariantType` (`default, destructive`), recursive `items` submenus, config-driven **groups** (titled/selectable/async sections via `BbDropdownGroup`), `adaptive` + `offCanvasProps`, `anchor` | additive                                                                                                                                                            |
| floating wrapper/bubble as `<span>`  | rendered as `<div>`                                                                                                                                                                                                       | DOM only — the menu is block content. Class hooks unchanged; only element selectors like `span.bb-common-popover` break.                                            |

## Edits

```diff
  <BbDropdown :items="[
-   { text: 'Rename', onClick: rename },
-   { text: 'Delete', onClick: destroy, class: 'text-red-600' },
+   { text: 'Rename', onClick: rename },
+   { text: 'Delete', onClick: destroy, variant: 'destructive' },
  ]">
```

The hand-colored destructive item is the dropdown flavor of the
class-override pattern — `variant: 'destructive'` is the typed form, and
custom names register via the plugin's `dropdownItemVariants` option
([main guide §7](../v2-to-v3.md)).

`adaptive` is on by default: on mobile the menu opens as a bottom sheet. Pass
`:adaptive="false"` to keep the floating menu everywhere.

---

<!-- dist/ai/guides/migration/components/bb-dropzone.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-dropzone.md -->

# BbDropzone — v2 → v3

## Changes

| v2                                                                  | v3                                                                                                                                                                             | Kind                                                                                                                                                                                                                                              |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `modelValue: any`                                                   | `File \| File[] \| null`                                                                                                                                                       | retype                                                                                                                                                                                                                                            |
| `accept: string[]` — non-array **threw**; extensions mapped eagerly | MIME (`'image/png'`), wildcards (`'image/*'`), extensions (`'.png'`) **and bare tokens** (`'png'`); never throws — unknown tokens dev-warn and fall back to extension matching | behavior (more permissive; validation is queued until rules resolve, so early drops are still validated correctly)                                                                                                                                |
| hidden submittable `<input type="file">` always rendered            | rendered **only when `name` is set**; mirrors the model (including pre-seeded values)                                                                                          | **⚠ silent** — a native `<form>` post that relied on the hidden input without a `name`… actually posted nothing useful in v2 either, but if you passed `name`, behavior improves; if you _removed_ `name` thinking it inert, the input disappears |
| `error` event / `errors` round-trip (`DropZoneError` union)         | unchanged                                                                                                                                                                      | —                                                                                                                                                                                                                                                 |
| —                                                                   | default-slot `open()` callback (opens the native picker)                                                                                                                       | additive                                                                                                                                                                                                                                          |
| `tag: string` (any non-void element)                                | `'div' \| 'span'`                                                                                                                                                              | narrowed — wrap the dropzone in your own element for anything else                                                                                                                                                                                |

## Edits

```diff
- <BbDropzone v-model="file" :accept="['application/pdf']" name="attachment" />
+ <BbDropzone v-model="file" :accept="['pdf']" name="attachment" />
```

Keep `name` wherever a surrounding `<form>` submits natively — without it v3
renders no hidden input at all.

---

<!-- dist/ai/guides/migration/components/bb-icon.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-icon.md -->

# BbIcon — v2 → v3

## Changes

| v2                                                   | v3                                                                     | Kind                                                              |
| ---------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `type: IconType` (required)                          | `icon: IconType`                                                       | rename                                                            |
| `color?: string`                                     | removed                                                                | icons render `currentColor` — set `color` on a wrapper, or in CSS |
| size key `xxl`                                       | `2xl`                                                                  | retype (shared `Sizes` scale)                                     |
| type export `Size`                                   | `BbIconSize`                                                           | rename                                                            |
| `IconType` restricted by `IconRegistry` augmentation | plain `string` (`provider:name` or `local:name`, raw `<svg>` accepted) | see icon setup in the [main guide §1](../v2-to-v3.md)             |

## Edits

```diff
- <BbIcon type="mdi:home" color="#6b7280" size="xxl" />
+ <BbIcon icon="mdi:home" size="2xl" class="text-[color:var(--bb-text-muted)]" />
```

Provider prefixes now require the matching `@iconify-json/<prefix>` dev
dependency, and names must be **literal strings** (the build scans statically;
dynamically assembled names won't be bundled).

## Your own icon plugin is probably redundant now

Most v2 apps hand-rolled one, because v2 shipped no registry:

```ts
// resources/js/plugins/icons.ts — the v2 shape: glob the SVG folder yourself,
// build a name → loader map, hand it to BbIcon under the string key.
const icons = import.meta.glob('../../assets/icons/*.svg', { as: 'raw' });
app.provide('icons', toRegistry(icons));
```

v3 does both halves itself. The **build** plugin scans `iconDir` recursively
and turns every `.svg` into `local:<basename>`; the **runtime** plugin provides
that registry to `BbIcon`. If your plugin scanned the same folder and provided
it under `'icons'`, it is now duplicating both.

⚠ It is not merely duplicate — it is **inert for `BbIcon`, silently**.
`bitbossUiPlugin` provides the registry under a Symbol
(`bitboss-ui:icons`) _and_ under the legacy string key `'icons'`, and `BbIcon`
reads `inject(Symbol.for('bitboss-ui:icons')) ?? inject('icons')`. The Symbol wins,
so your map is shadowed rather than merged. Any glyph that exists only in your
map stops rendering and nothing warns.

Check before you delete — the plugin is dead only if both hold:

1. **Every SVG it registers also lives under `iconDir`.** Diff the two folders.
   If the plugin globbed a different directory (`resources/js/icons`,
   a package's `assets/`), move those files into `iconDir` first — otherwise
   deletion and non-deletion both leave you with missing icons.
2. **Nothing else injects `'icons'`.** `rg -n "inject\(['\"]icons['\"]\)"` — an
   app component reading the map to render `<img>` or to enumerate names is
   real usage, not `BbIcon` usage. It now receives whichever provide ran last
   (yours, if you `app.use()` your plugin after `bitbossUiPlugin`), which is a
   coin-flip you do not want to keep. Rewrite those call sites to import your
   map as a plain module export — or, if what they want is the library's
   registry, `inject(Symbol.for('bitboss-ui:icons'))`. The key is not exported
   from the package, but it is a `Symbol.for`, so recreating it resolves the
   same symbol.

The string key `'icons'` is a compatibility shim kept for one release. Do not
build on it.

## Prefix your own icons with `local:` while you are in there

A v2 `type` naming an icon from your own `iconDir` was bare — `type="user-circle"`.
Carry it over **with the prefix**:

```diff
- <BbIcon type="user-circle" />
+ <BbIcon icon="local:user-circle" />
```

This is not a functional change: `BbIcon` already resolves a name with no `:`
as `local:<name>`, so both spellings render the same icon. It is a **tooling**
change, and worth doing across the whole app in one pass:

- The Iconify editor extension keys off `prefix:name`. Spelled `local:user-circle`
  it renders an inline preview and autocompletes the name in the template; spelled
  `user-circle` it sees an ordinary string and shows nothing.
- It reads unambiguously next to `mdi:home` / `lucide:check` — same shape, and the
  source of every icon is legible at a glance instead of inferred from absence.

Apply it wherever the name is written **literally in a template**. Leave names that
arrive through a variable, a map, or props alone — the prefix buys nothing there
(no extension preview to gain), and rewriting data is out of scope for a rename.
The same goes for any component prop that takes an icon (`prepend:icon`,
`append:icon`, `icon` on buttons, dropdown items, toasts…), not just `<BbIcon>`.

---

<!-- dist/ai/guides/migration/components/bb-intersection.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-intersection.md -->

# BbIntersection — v2 → v3

**`BbIntersection` is removed in v3.** It was a headless wrapper around
`IntersectionObserver` — no markup of its own beyond a `<div>`, no styling, no
design-system surface. Everything it did is one composable call, so it is not
worth a component in a UI library.

There is **no `Bb*` replacement**. Two supported paths:

1. **`useIntersectionObserver` from `@vueuse/core`** — the direct equivalent,
   and what the library itself would use.
2. **Copy the v2 component into your app** if you want to keep the exact
   event/slot shape. It was ~40 lines; `git show v2:src/components/BbIntersection/BbIntersection.vue`.

## Changes

| v2                                                          | v3          | Kind                                                                                                                                                                                                                                                 |
| ----------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<BbIntersection>` component                                | **removed** | no replacement — use `useIntersectionObserver`                                                                                                                                                                                                       |
| `BbIntersectionProps` / `BbIntersectionEvents` type exports | **removed** | delete the imports                                                                                                                                                                                                                                   |
| `debounceTime?: number` (default `0`)                       | —           | it throttled, despite the name. `useIntersectionObserver` does not throttle; wrap the callback yourself if you relied on it.                                                                                                                         |
| `options?: IntersectionObserverInit`                        | —           | passes straight through as `useIntersectionObserver`'s third argument. **The v2 default was `{ root: null, threshold: [0, 0.2, 0.4, 0.6, 0.8, 1] }`** — VueUse's default is a single `0` threshold, so pass the array if you need ratio granularity. |
| `tag` (default `'div'`)                                     | —           | you render the observed element yourself now                                                                                                                                                                                                         |

### Events and slot props

The three events had specific thresholds that are easy to get wrong when
reimplementing:

| v2                          | Fired when                                               | Equivalent                                  |
| --------------------------- | -------------------------------------------------------- | ------------------------------------------- |
| `@shown`                    | intersection ratio reaches **exactly 1** (fully visible) | `ratio === 1`                               |
| `@hidden`                   | element leaves the viewport **entirely**                 | `!entry.isIntersecting`                     |
| `@intersected="(pct) => …"` | on every ratio change; payload is **0–100**, not 0–1     | `Math.trunc(entry.intersectionRatio * 100)` |

The default slot exposed `{ shown, hidden, percentage }` with the same
semantics (`percentage` also 0–100).

## Edits

The common case was an infinite-scroll sentinel:

```diff
- <BbIntersection @shown="loadMore">
-   <span />
- </BbIntersection>
+ <span ref="sentinel" />
```

```ts
import { useIntersectionObserver } from '@vueuse/core';
import { useTemplateRef } from 'vue';

const sentinel = useTemplateRef('sentinel');

useIntersectionObserver(sentinel, ([entry]) => {
	if (entry?.isIntersecting) loadMore();
});
```

Note the threshold change: `@shown` required **full** visibility, while the
snippet above fires as soon as any part of the sentinel appears. That is
usually what you want for infinite scroll — it triggers earlier — but if you
depended on the stricter behaviour, pass `{ threshold: 1 }` and check
`entry.intersectionRatio === 1`.

---

<!-- dist/ai/guides/migration/components/bb-offcanvas.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-offcanvas.md -->

# BbOffCanvas — v2 → v3

## Changes

| v2                                                                      | v3                                                                                                         | Kind                                                                                                                                                                                                     |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `direction?: 'left' \| 'top' \| 'right' \| 'bottom'` (default `'left'`) | `side?: 'left' \| 'top' \| 'right' \| 'bottom'` (default `'left'`)                                         | **⚠ silent** — a leftover `direction` is ignored and the panel falls back to `'left'`                                                                                                                    |
| `showClose?: boolean` (default `true`)                                  | `hideClose?: boolean` (default `false`)                                                                    | rename, polarity inverted                                                                                                                                                                                |
| `description?: string`                                                  | removed                                                                                                    | put the copy in the default slot or own the header via `#header`; the `aria-describedby` wiring goes with it                                                                                             |
| `#description` slot                                                     | removed                                                                                                    | same — nothing links body copy to the panel automatically now                                                                                                                                            |
| `#close` slot                                                           | removed                                                                                                    | a custom close control goes inside `#header`, see below                                                                                                                                                  |
| `size?: 'sm' \| 'md' \| 'lg'`                                           | `size?: Responsive<'xs'…'2xl' \| 'auto' \| CSS length>`                                                    | widened — **defaults changed**, same trap as BbDialog: v2 `{ sm: 384, md: 652, lg: 896 }` → v3 `{ xs: 320, sm: 384, md: 448, lg: 512, xl: 576, '2xl': 672 }`. Pin via `offCanvasDefaultSizes` if needed. |
| —                                                                       | `draggable`, `stack` / `stackGap`, `persistent`, `disabled`, `fullscreen`, `eager`, `focusTarget`, `title` | additive                                                                                                                                                                                                 |

`direction` → **`side`** is a pure rename that aligns the kit's positioning
vocabulary (`side` for edge-docked surfaces, `position` for BbToast's viewport
corners, `placement` for anchor-relative popovers). Same value set, same
default.

```diff
- <BbOffCanvas v-model="open" direction="right" :show-close="false" size="md" title="Filters" />
+ <BbOffCanvas v-model="open" side="right" hide-close size="md" title="Filters" />
```

If the panel was sized to fit content designed for 652px, either pass
`offCanvasDefaultSizes: { md: 652 }` to the plugin or move to `size="xl"`
(576px) / an explicit CSS length.

**Adaptive surfaces** — components that render a BbOffCanvas drawer on mobile
(`BbDialog`, `BbPopover`, `BbDropdown`, `BbSelectPopover`) configure it through
`offCanvasProps` (`Partial<BbOffCanvasProps>`). The nested `direction` there
renames to `side` for the same reason:

```diff
- <BbDialog :off-canvas-props="{ direction: 'bottom' }" />
+ <BbDialog :off-canvas-props="{ side: 'bottom' }" />
```

**The two leftovers fail differently — check both.** Measured with `vue-tsc`
against this repo:

- **Inside `offCanvasProps`** (`:off-canvas-props="{ direction: 'bottom' }"`) a
  typed template **does** catch it: the value is a fresh object literal typed
  `Partial<BbOffCanvasProps>`, so TypeScript's excess-property check fires —
  `TS2353: 'direction' does not exist in type 'Partial<BbOffCanvasProps>'`.
- **As an attribute on the component** (`<BbOffCanvas direction="right">`) it is
  **silent**, and `vue-tsc` does **not** catch it by default: an unknown
  attribute is legal Vue, lands on `$attrs`, and type-checks clean. Verified —
  a made-up `totallyBogusProp` passes too. The panel just falls back to
  `'left'`.

For that second case `vueCompilerOptions.checkUnknownProps` would catch it, but
it is blunt: it also rejects legitimate fallthrough like `aria-label` /
`aria-describedby`, which these guides tell you to use. Prefer
**`npx bitboss-ui check`**, which knows the difference, or
`bitboss-ui/eslint-plugin`, which catches it everywhere and
**`eslint --fix` auto-renames it**. Grep: `rg -i 'direction' --type vue` in
offcanvas markup.

## Adaptive-drawer config prop unified → `offCanvasProps`

The prop that configures the mobile drawer on adaptive components was spelled
two ways — `canvasProps` (BbDialog) and `offcanvasProps` (BbSelect,
BbSelectPopover, BbDropdown, BbPopover, BbDatePickerInput). Both are unified to
**`offCanvasProps`** (camelCase reflecting the `BbOffCanvas` component name).
Pure rename — the `Partial<BbOffCanvasProps>` object is unchanged.

```diff
- <BbDialog :canvas-props="{ side: 'bottom' }" />
+ <BbDialog :off-canvas-props="{ side: 'bottom' }" />

- <BbSelect :offcanvas-props="{ size: 'lg' }" />
+ <BbSelect :off-canvas-props="{ size: 'lg' }" />
```

Also silent on upgrade; `eslint --fix` auto-renames it.

## `description` and `#close` are gone

v3's slot set is `header | title | default | footer` — no `#close`, no
`#description`, and no `description` prop. Same removal as
[BbDialog](./bb-dialog.md).

`description` copy moves into the default slot. Nothing wires
`aria-describedby` for you any more; add it yourself if a screen reader needs
the panel described rather than just labelled.

**`#header` replaces the ✕, so `hide-close` is redundant beside it.** The
default header renders `#title` + a `CloseButton`; providing `#header` replaces
both, which is why a custom close control belongs inside it. The slot receives
`{ titleId, close, title }` — put `titleId` on your title element to keep
`aria-labelledby` intact, and call `close` from your own control.

```diff
- <BbOffCanvas v-model="open" title="Edit" :show-close="true">
-   <template #close><SaveGuardIcon /></template>
- </BbOffCanvas>
+ <BbOffCanvas v-model="open" title="Edit">
+   <template #header="{ titleId, close, title }">
+     <span :id="titleId" class="bb-offcanvas__title">{{ title }}</span>
+     <button @click="guardUnsaved(close)"><SaveGuardIcon /></button>
+   </template>
+ </BbOffCanvas>
```

A header renders when `title` is set **or** `#header` is provided, so the slot
alone is enough — you do not also need a `title`.

---

<!-- dist/ai/guides/migration/components/bb-pagination.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-pagination.md -->

# BbPagination — v2 → v3

## Changes

| v2                                           | v3                                                              | Kind                                                                                                                                   |
| -------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `querykey?: string`                          | `queryKey?: string` (default `'page'`)                          | **⚠ silent** — a leftover `querykey` is ignored; URL sync moves to `?page=`, breaking deep links and server code reading the old param |
| `loading?: boolean`                          | removed                                                         | use `disabled` while a page loads if you need to block interaction                                                                     |
| `label` default `'Paginazione'` (hard-coded) | localized default                                               | cosmetic unless you asserted on it                                                                                                     |
| —                                            | `tableId` (binds to a `BbTable` context and derives page count) | additive                                                                                                                               |

## Edits

```diff
- <BbPagination v-model="page" :total-pages="pages" querykey="p" :loading="fetching" />
+ <BbPagination v-model="page" :total-pages="pages" query-key="p" :disabled="fetching" />
```

`rg -i 'querykey'` finds every case, including kebab usage.

There is **no `total` prop** on either version — the page count comes from
`total-pages`, or from `total-items` + `per-page` (v3 only), which wins when
both are given. A `:total` binding is not a compile error: it falls through to
the DOM as a stray attribute and the pager silently stays on one page.

## `useBbTableContext().total` became `.totalItems` (v3 alpha, 2026-08-06)

A pager bound with `table-id` shares its state with the `useBbTableContext`
handle, whose row-count field was renamed `total` → `totalItems` to match the
`total-items` prop both components already accept. Hard rename, no alias — the
full before/after is in
[BbTable](./bb-table.md#usebbtablecontexttotal-became-totalitems-v3-alpha-2026-08-06).
The `total-items` / `total-pages` **props** are unchanged.

---

<!-- dist/ai/guides/migration/components/bb-popover.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-popover.md -->

# BbPopover — v2 → v3

## Changes

| v2                                                                               | v3                                                                                                                    | Kind                                                                                                                                                                                                                                |
| -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `showClose`, `closeLabel`                                                        | removed                                                                                                               | render your own close control with the default slot's `close` callback                                                                                                                                                              |
| `restoreFocus?: boolean` (default `true`)                                        | removed                                                                                                               | focus restoration is built-in behavior now, not a knob                                                                                                                                                                              |
| `theme?: string`                                                                 | removed                                                                                                               | style via class/CSS                                                                                                                                                                                                                 |
| `block`                                                                          | removed                                                                                                               | dead prop                                                                                                                                                                                                                           |
| `hideArrow` (default `true`), `arrowPadding`                                     | removed                                                                                                               | **arrows are tooltip-only in v3.** A popover never shows one. If you passed `:hide-arrow="false"` to get a pointing bubble, that UI is now `BbTooltip`'s job. **⚠ silent**: a leftover `hide-arrow` binding just lands in `$attrs`. |
| `activator` / `boundary` loose types                                             | `ElementOrComponentRef` / `…OrSelector`                                                                               | transparent in templates                                                                                                                                                                                                            |
| imperative template-ref API (`popoverRef.value.show()` / `.close()` / `.isOpen`) | removed → `v-model`                                                                                                   | write `true`/`false` to open/close; the popover writes it back on dismiss (the BbDialog/BbOffCanvas pattern). **⚠ silent**: a stale `popoverRef.value?.show()` is `undefined` at runtime (no compile error in untyped templates).   |
| —                                                                                | `adaptive` + `offCanvasProps` (mobile bottom sheet, on by default), `header` / `footer` slots, `show` / `hide` events | additive                                                                                                                                                                                                                            |
| floating wrapper/bubble rendered as `<span>`                                     | rendered as `<div>` (`<dialog>` in dialog mode, as before)                                                            | DOM only — the bubble holds block content, so `<span>` was invalid markup. Class hooks (`.bb-common-popover`, `.bb-common-popover__bubble`) are unchanged; only element selectors like `span.bb-common-popover` break.              |

## Edits

```diff
- <BbPopover :activator="btn" show-close close-label="Dismiss">
-   <p>Saved searches let you…</p>
+ <BbPopover :activator="btn">
+   <template #default="{ close }">
+     <p>Saved searches let you…</p>
+     <BbButton variant="ghost" size="sm" @click="close">Dismiss</BbButton>
+   </template>
  </BbPopover>

  <!-- v2 arrow popover = v3 tooltip -->
- <BbPopover :activator="info" :hide-arrow="false">Short hint text</BbPopover>
+ <BbTooltip :activator="info">Short hint text</BbTooltip>
```

For the imperative case, the template-ref expose is gone — drive the popover
with `v-model` instead (it writes the model back on every dismiss, so reading it
stays accurate):

```diff
- <BbPopover ref="popoverRef">…</BbPopover>
+ <BbPopover v-model="open">…</BbPopover>

- popoverRef.value?.show();
+ open.value = true;   // open.value = false to close; reads true only while open
```

Remember `adaptive`: on mobile the popover becomes a bottom sheet by default —
opt out with `:adaptive="false"` if the floating panel must persist.

---

<!-- dist/ai/guides/migration/components/bb-rating.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-rating.md -->

# BbRating — v2 → v3

## Changes

| v2                        | v3                                                                                    | Kind                                                    |
| ------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `color?: string`          | removed                                                                               | stars follow `currentColor` / theme tokens              |
| `name: string` (required) | `name?: string` (auto-generated when omitted)                                         | relaxation — keep passing it only for native form posts |
| —                         | `clearable` (click the current value to zero the rating), `legendMode`, `description` | additive                                                |

## Edits

```diff
- <BbRating v-model="score" name="score" color="#eab308" />
+ <BbRating v-model="score" clearable />
```

Adding `clearable` is recommended: the old "re-click to clear" folklore is
now a visible affordance.

`legend` is required here too, in v2 as in v3 — see the note in
[bb-checkbox-group.md](./bb-checkbox-group.md); a missing one is a pre-existing
bug, not an upgrade break.

## DOM

The block name is unchanged; the star's state modifier is not.

| v2                                     | v3                                                      |
| -------------------------------------- | ------------------------------------------------------- |
| `.bb-base-rating__option--highlighted` | `.bb-base-rating__option--filled` / `--empty`           |
| —                                      | `.bb-base-rating__option--disabled`, `--readonly` (new) |
| —                                      | `.bb-base-rating--warnings`, `--forced-clear` (new)     |

v2 styled unfilled stars with `:not(--highlighted)`; v3 gives them a positive
name. `--empty` is a **hook for your CSS**, not a painted default: the shipped
sheet has no `&--empty` rule, because an empty star is just the base
`__option` colour. So porting `:not(--highlighted)` to `--empty` works, and
writing nothing also works.

Everything else survives unchanged: `.bb-base-rating`, `--disabled`,
`--errors`, `--readonly`, `--has-value`, `__inner-container`, `__option`,
`__label-text`. Nothing warns — a `--highlighted` rule just stops matching.

`BbRating` is not part of the checkbox/radio/switch `bb-cr-container` tree, and
was not in v2 either despite v2 shipping rules that said otherwise (below).
Target `.bb-base-rating__inner-container` and `.bb-base-rating__option`.

## `input-position="right"` / `"center"` now does something

v2 shipped the alignment rules under `.bb-rating … .bb-cr-container__container`
— a class `BbRating` never rendered (its container was already
`.bb-base-rating__inner-container`). So the prop was accepted and typed on both
versions but was a **no-op in v2**. v3 repoints the rules at the element the
component actually renders.

If your app worked around the dead prop with a hand-rolled alignment rule, that
rule now fights the library's. Delete the workaround and keep the prop.

## Tokens

`--bb-rating-size` was a `:root` global in v2, read as
`.bb-base-rating { --size: var(--bb-rating-size) }`. v3 drops the global and
hard-defaults the local to **`24px`** (`BbBaseRating/index.css:4`). Move your
override off `:root` and onto the block — the value itself is yours to keep:

```diff
- :root { --bb-rating-size: 32px; }
+ .bb-base-rating { --size: 32px; }
```

Set it on `.bb-base-rating` itself (or on a rule that also matches it) — the
local is declared on that block, so a value inherited from an ancestor is
overridden before it is read. `--spacing` (star gap) is the companion local;
v2's `--bb-base-rating-spacing` was referenced but never declared anywhere in
the shipped sheet, so it never worked.

---

<!-- dist/ai/guides/migration/components/bb-select-popover.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-select-popover.md -->

# BbSelectPopover — v2 → v3

## Props

| v2                                                          | v3                                                                                                                | Kind                                                                                                                                        |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `flip?: boolean` (default `true`)                           | `disableFlip?: boolean` (default `false`)                                                                         | rename, polarity inverted                                                                                                                   |
| `allowWriting?: boolean \| 'not-mobile'` (default `true`)   | `disableWriting?: boolean \| 'mobile' \| 'desktop'` (default `false`)                                             | rename, polarity inverted, token set changed                                                                                                |
| `hideArrow` (default `true`), `arrowPadding` (default `10`) | removed                                                                                                           | arrows are tooltip-only in v3; **⚠ silent** — `:hide-arrow="false"` (the only meaningful v2 use) now lands in `$attrs` and no arrow renders |
| `transitionDuration` default `300`                          | default `250`                                                                                                     | visual — the panel now animates on the shared `transitions.medium` scale, like `BbDialog`                                                   |
| `filterBy` union (fn, `false`, `'not_stashed'`, …)          | `filterBy?: string[]` (default `[]`)                                                                              | retype — filter your `items`/provider instead                                                                                               |
| `itemText` / `itemValue`                                    | `ItemAccessor<Item, …>`                                                                                           | retype                                                                                                                                      |
| per-item `disabled`                                         | inert — use `selectable`                                                                                          | **⚠ silent**                                                                                                                                |
| —                                                           | `anchor`, `adaptive` + `offCanvasProps`, `selectable`, `active` event, activator scope `text` / `selectedOptions` | additive                                                                                                                                    |

## Slots

`#options:prepend`, `#options:append` and their `:outer` twins are removed —
the panel now has `#header` / `#footer`.

## Behavior (shared with BbSelect — same engine)

- Single-select second click re-picks instead of clearing; use the slot-scope
  `clear` callback for an explicit clear affordance.
- `enforce-coherence` + a seeded model forces the first load and prunes
  invalid values **on mount**.
- Array `items` resolve on mount regardless of `prefill` — activator `text`
  is reliable from first paint for arrays. Provider-backed popovers stay lazy
  by default (0 requests until opened) — that per-row affordability is a
  feature; don't blanket-add `prefill: true`.
- `prefill: false` is **search-first**: with a provider, opening the panel no
  longer performs the initial fetch — nothing loads until the user types, and
  the list shows a "search to begin" hint. **⚠ silent** — v2's `false` still
  fetched on first open; if that's what you wanted, drop the prop (it's the
  default). Falls back to load-on-open when writing is disabled, `items` is an
  array, or the model is non-empty.

## Edits

```diff
- <BbSelectPopover
-   v-model="row.status"
-   :items="statuses"
-   :flip="false"
-   :hide-arrow="false"
-   :allow-writing="false"
- />
+ <BbSelectPopover
+   v-model="row.status"
+   :items="statuses"
+   disable-flip
+   disable-writing
+ />
```

See `bb-select.md` § "DOM: listbox option classes lose their v2 `autocomplete-` names" — the same rename applies here, since both components share the select engine and its listboxes.

---

<!-- dist/ai/guides/migration/components/bb-select.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-select.md -->

# BbSelect — v2 → v3

## Props

| v2                                                                            | v3                                                                                                                                                                       | Kind                                                                                                                                                                                                                                           |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allowWriting?: boolean \| 'not-mobile'` (default `true`)                     | `disableWriting?: boolean \| 'mobile' \| 'desktop'` (default `false`)                                                                                                    | rename, polarity inverted, token set changed (`'not-mobile'` → `disable-writing="mobile"`)                                                                                                                                                     |
| `showChevron?: boolean` (default `true`)                                      | removed                                                                                                                                                                  | the chevron is standard trim now                                                                                                                                                                                                               |
| `updateOnAnimationFrame?: boolean`                                            | removed                                                                                                                                                                  | positioning is handled internally                                                                                                                                                                                                              |
| `filterBy: string \| string[] \| false \| 'not_stashed' \| fn`                | `filterBy?: string[]` (default `[]`)                                                                                                                                     | retype — **function/`false`/`'not_stashed'` forms removed.** For custom logic, filter the `items` you pass (or do it in the provider) instead of filtering inside the select.                                                                  |
| `prefill?: boolean \| 'focus'` (default `'focus'`)                            | `prefill?: boolean \| 'interaction'` (default `'interaction'`)                                                                                                           | value renamed; `'focus'` no longer compiles. Unset now genuinely inherits the default (v2's wrapper silently coerced an unset prop to `false`).                                                                                                |
| `prefill: false` (fetched on first open)                                      | `prefill: false` is **search-first**: with a provider, nothing fetches until the user types — opening shows a "search to begin" hint (`select.searchToStart`)            | **⚠ silent** — a v2 `prefill: false` select opens to the hint instead of options. If you meant "load on open", delete the prop: that is the default. Falls back to load-on-open for array `items`, `disable-writing`, or a non-empty model.    |
| `transitionDuration` default `300`                                            | default `250`                                                                                                                                                            | visual — the panel now animates on the shared `transitions.medium` scale, like `BbDialog`                                                                                                                                                      |
| `itemText` / `itemValue`                                                      | `ItemAccessor<T, …>`                                                                                                                                                     | retype — keys autocomplete, functions unchanged                                                                                                                                                                                                |
| per-item `disabled` honored (deprecated)                                      | inert — use `selectable?: boolean \| ((item) => boolean)`                                                                                                                | **⚠ silent** — see below                                                                                                                                                                                                                       |
| —                                                                             | `adaptive` + `offCanvasProps` (mobile sheet, on by default), `labelMode`, `description`, and the new `active` event (fires when the panel opens; `inactive` pre-existed) | additive                                                                                                                                                                                                                                       |
| `name` + empty selection posts `name=null` (single) / omits the field (multi) | empty selection (`null`/`[]`) posts **no field**, like a native `<select multiple>` with nothing chosen                                                                  | **⚠ behavioral** (bugfix 2026-07-18) — backends reading the literal `"null"` string must treat the absent field as empty. Note: `required` never participated in native validation here (hidden inputs are barred from constraint validation). |

## Slots

| v2                                                                                       | v3                                                      |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `#chevron`                                                                               | removed                                                 |
| `#options:prepend`, `#options:append`, `#options:prepend:outer`, `#options:append:outer` | removed — use the new `#header` / `#footer` panel slots |
| `#prepend` / `#append` (± `-outer`)                                                      | unchanged; scope gains `close`                          |

## Behavior

1. **Second click no longer clears.** Clicking the already-selected option in
   single mode re-picks and closes; v2 emitted `null` and emptied the field.
   If click-to-clear was your only clear affordance, add `clearable`.
2. **`enforce-coherence` prunes on mount.** A seeded value the first load
   can't resolve is cleared immediately (v2 let it linger until the next
   change). If values "clear on load" after upgrading, your provider isn't
   resolving the current selection on `prefill === true` calls — honor that
   contract or enable `stash`.
3. **Array `items` resolve on mount** regardless of `prefill` — the field's
   text renders correctly from first paint.
4. **Disabled options:** a `disabled` field on an item object no longer does
   anything (v2 honored it with a deprecation warning). Pass a predicate:

```diff
- <BbSelect :items="users.map(u => ({ ...u, disabled: !u.active }))" … />
+ <BbSelect :items="users" :selectable="(u) => u.active" … />
```

## Edits

```diff
- <BbSelect
-   v-model="assignee"
-   :items="searchUsers"
-   :allow-writing="false"
-   :show-chevron="false"
-   :filter-by="(v, item, q) => item.name.includes(q)"
-   prefill="focus"
- />
+ <BbSelect
+   v-model="assignee"
+   :items="searchUsers"
+   disable-writing
+   :filter-by="['name']"
+ />
```

## DOM: listbox option classes lose their v2 `autocomplete-` names (2026-08-07)

Option rows used to carry **two** class names for the same element — the modern
`bb-listbox__option` and the v2-era `autocomplete-option`, left over from when
this component was called "autocomplete". The state modifiers and the inner
parts lived only on the legacy name, so the correct name had no states at all.
The legacy name is gone; everything is now on the block it belongs to:

| v2 / early v3                    | v3                              |
| -------------------------------- | ------------------------------- |
| `.autocomplete-option`           | `.bb-listbox__option`           |
| `.autocomplete-option--focused`  | `.bb-listbox__option--focused`  |
| `.autocomplete-option--selected` | `.bb-listbox__option--selected` |
| `.autocomplete-option--disabled` | `.bb-listbox__option--disabled` |
| `.autocomplete-option__label`    | `.bb-listbox__option-label`     |
| `.autocomplete-option__check`    | `.bb-listbox__option-check`     |

The two inner parts flatten with a hyphen rather than a second `__`: they are
parts of an element, and BEM has no element-of-an-element. This matches the
block's existing `bb-listbox__group-header-label`.

Applies to every surface built on the select engine — `BbSelect`,
`BbSelectPopover`, and the flat/grouped listboxes. **Grep for
`autocomplete-option` in your CSS and test selectors**; nothing warns, the rules
simply stop matching.

## Tokens: `--bb-select-option-px` / `--bb-select-option-py` are gone

v2 declared both on `:root` (`16px` / `8px`) and read them in the option row, the
group header and the no-results row. v3 declares neither, and — unlike most of
the retired component globals — **nothing replaced them with a local**.
`.bb-listbox__option` hard-codes its inline padding:

```css
/* src/components/BbSelectPopover/index.css */
.bb-listbox__option {
	height: var(--option-h);
	padding-left: 0.5rem;
	padding-right: 0.5rem;
}
```

So `--bb-select-option-px`, and the `--px` local you might expect by analogy with
`BbButton` or `BbDialog`, are both silent no-ops — no rule in the select tree
reads either. Override with a plain declaration instead. The library's rule is
six classes deep, so a two-class app rule loses the cascade; match the chain or
force it:

```css
/* specificity-matched — needs your sheet to load after the library's */
.bb-select-popover
	.bb-listbox
	.bb-listbox__outer-container
	.bb-listbox__inner-container
	span[role='listbox']
	.bb-listbox__option {
	padding-inline: 1rem;
}

/* or, order-independent */
.bb-listbox__option {
	padding-inline: 1rem !important;
}
```

Row **height** is not yours to set in CSS. `--option-h` reads `--option-height`,
which the component writes inline because the same number feeds the
virtualizer's `estimateSize`; a CSS override desynchronises the paint from the
scroll math and the list mispositions. Use `item-height` / `header-height` (or
`compact`) instead — they move both halves together.

The panel is **not** teleported — there is no `Teleport` anywhere in
`BbSelect`, `BbBaseSelect` or `BbSelectPopover` — so it stays inside your
`<BbSelect>` and a wrapper class does reach it. Scoping on `.bb-select-popover`
is still the clearer target, and CSS custom properties inherit into the panel
either way.

---

<!-- dist/ai/guides/migration/components/bb-slider.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-slider.md -->

# BbSlider — v2 → v3

## Changes

| v2                                                 | v3                                                                                                                                                                                                | Kind                                                         |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `thumbTranslate?: boolean` (default `true`)        | `disableThumbTranslate?: boolean` (default `false`)                                                                                                                                               | rename, polarity inverted — same effective default           |
| `modelValue: number \| number[] \| string \| null` | `number \| number[] \| null`                                                                                                                                                                      | retype — string models fail to compile; parse before binding |
| `color?: string`                                   | removed                                                                                                                                                                                           | style via tokens/CSS                                         |
| —                                                  | `labelMode: 'outside' \| 'inside'` (floating unsupported — an explicit `'floating'` warns and falls back to `'outside'`), `maxPrecision` (forwarded to the companion number input), `description` | additive                                                     |

## Edits

```diff
- <BbSlider v-model="volume" :thumb-translate="false" color="#f59e0b" />
+ <BbSlider v-model="volume" disable-thumb-translate />
```

If your global config sets `defaultInputLabelMode: 'floating'`, sliders
silently degrade to `'outside'` — expected, not a bug.

---

<!-- dist/ai/guides/migration/components/bb-smooth-height.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-smooth-height.md -->

# BbSmoothHeight — v2 → v3

## Changes

| v2                                            | v3                | Kind                                                              |
| --------------------------------------------- | ----------------- | ----------------------------------------------------------------- |
| `tag: string` (any non-void element)          | `'div' \| 'span'` | narrowed — invalid tags are now compile errors                    |
| inner `.bb-smooth-height__content` always div | mirrors `tag`     | DOM — `tag="span"` now yields span-in-span instead of span-in-div |

## Why the tag list shrank

The wrapper animates `height`, and the element inside it exists purely to
measure content. Those two boxes are always the same element type now, so any
tag with a restricted content model would nest invalidly inside itself — `ul >
ul`, `p > p`. Restricting the prop to `div | span` makes every combination
valid by construction.

Both elements are forced to `display: block` in CSS, so a `span` measures and
animates exactly like a `div`; the choice is purely about the markup the
surrounding context accepts.

```diff
- <BbSmoothHeight tag="section">
+ <section>
+   <BbSmoothHeight>
      …
+   </BbSmoothHeight>
+ </section>
- </BbSmoothHeight>
```

If you passed `ul`, note the v2 output was already invalid (`ul > div > li`),
because the inner measuring element was a hardcoded `<div>`. Wrap the component
in your own element instead of asking for it via `tag`.

## CSS

`.bb-smooth-height` and `.bb-smooth-height__content` are unchanged. Only
element-qualified selectors break — `div.bb-smooth-height__content` no longer
matches when `tag="span"`.

---

<!-- dist/ai/guides/migration/components/bb-spinner.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-spinner.md -->

# BbSpinner — v2 → v3

## Changes

| v2               | v3                                                      | Kind                                          |
| ---------------- | ------------------------------------------------------- | --------------------------------------------- |
| `color?: string` | removed                                                 | inherits `currentColor` — style the parent    |
| —                | `label?: string` (sr-only `role="status"` announcement) | additive, recommended for standalone spinners |

## Edits

```diff
- <BbSpinner color="#2563eb" size="lg" />
+ <BbSpinner size="lg" class="text-blue-600" label="Loading results" />
```

Note for tests/CSS: idle `BbButton`s no longer contain a mounted spinner node
— `.bb-spinner` only matches while a button is actually loading.

## DOM: the dot modifiers are namespaced (2026-08-07)

The per-dot stagger classes in the shipped SVG were bare modifiers with no
block. They now carry the block they belong to:

| v2 / early v3 | v3                        |
| ------------- | ------------------------- |
| `.circle--1`… | `.bb-spinner__circle--1`… |

`.bb-spinner__circle` (the unmodified dot) is unchanged. Only CSS or tests
targeting the numbered dots directly are affected — a rare thing to do, since
the numbering is an animation-delay detail rather than a documented hook.

Reduced motion is now honoured: under `prefers-reduced-motion: reduce` the dots
stop pulsing and hold at full size. They are deliberately NOT hidden — the
animation's resting state is `scale(0)`, so simply dropping the animation would
have made the spinner invisible and removed the page's only busy signal.

---

<!-- dist/ai/guides/migration/components/bb-table.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-table.md -->

# BbTable — v2 → v3

## Changes

| v2                                                                                                                    | v3                                                                                                                                                                                                                                           | Kind                                                                                                    |
| --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `allowSelectAll?: boolean` (default `true`)                                                                           | `disableSelectAll?: boolean` (default `false`)                                                                                                                                                                                               | rename, polarity inverted                                                                               |
| refetch with rows → skeleton                                                                                          | refetch keeps rows visible (dimmed + progress bar)                                                                                                                                                                                           | **behavior** — the skeleton only shows when there is nothing to display                                 |
| rows interactive while loading                                                                                        | header + rows go `inert` while loading                                                                                                                                                                                                       | **behavior** — opt out with `interactive-while-loading`                                                 |
| `#loading` slot fired on every load                                                                                   | fires on the **first load only** (it replaces the skeleton, so it follows the skeleton's rule)                                                                                                                                               | **⚠ silent** for anyone styling refetches through it                                                    |
| `#no-data` replaced the empty-state `<tr>`                                                                            | fills the table's own full-width cell (`aria-colspan` counted, centred)                                                                                                                                                                      | **behavior** — pass content, not a row                                                                  |
| `<table>` / `<thead>` / `<tbody>` / `<tr>` / `<th>` / `<td>` markup _(v2 and v3 ≤ beta.5)_                            | a CSS grid of `<div>`s carrying `role="table\|rowgroup\|row\|columnheader\|cell"`; `.bb-table__table` / `__head` / `__body` / `__foot` are the new containers, every `.bb-table*` class survives                                             | **⚠ silent** for element selectors, `#thead`/`#tbody`/`#tfoot` markup, copy/paste and print — see below |
| `--fill` / `--natural-width` published on `.bb-table` _(v3 ≤ beta.5)_                                                 | **removed** — nothing publishes them                                                                                                                                                                                                         | **⚠ silent** — see below                                                                                |
| —                                                                                                                     | props `enforceCoherence` (prunes row-keyed models after each load; incompatible with pagination-via-`dependencies`), `expandedItems` + `#expand`, `sort`, `keyboardNavigation`, `highlighted`, `rowClass`, `order` (v-model) + `reorderable` | additive                                                                                                |
| —                                                                                                                     | **column** fields `sortable?: boolean`, `rowClass?: ColumnClasses`                                                                                                                                                                           | additive, **collides** — see below                                                                      |
| `useBbTableContext(id).total` _(v3 alphas ≤ 4)_                                                                       | `useBbTableContext(id).totalItems`                                                                                                                                                                                                           | **hard rename** on the composable handle — see below                                                    |
| `@click:row` / `@contextmenu:row` / `@dblclick:row` handlers receive `(event, item, selected)` _(v2 and v3 ≤ beta.5)_ | `(event, item)` — `item` is now your raw record (was the internal row wrapper, record at `row.item`); the trailing `selected` boolean is gone                                                                                                | **payload slimmed** — see below                                                                         |
| `--bb-table-*` custom properties                                                                                      | same names without the `bb-` prefix                                                                                                                                                                                                          | **⚠ silent** for nested-table layouts — see below                                                       |

## Columns gained `sortable` and `rowClass` — check yours first

v2's `BbTableColumn` had neither field (`grep sortable` over the whole 2.1.135
`BbTable/types.d.ts` exits empty), and extra fields on a column object were
inert — so apps parked their own data there. A backend sort key named
`sortable`. A per-column class named `rowClass`. Both are now real library
fields, and both break in two directions at once: the **type** stops compiling
and the **behaviour** silently changes.

### The type collision

Your column type is almost certainly an intersection:

```ts
type Column = BbTableColumn<Patient> & { sortable?: string }; // backend sort key
```

The intersection makes `sortable` `boolean & string` — i.e. `never`, whose
optional form TypeScript reports as `undefined`. Every column literal in your
app fails, and the message never mentions `BbTableColumn`:

```
error TS2322: Type 'string' is not assignable to type 'undefined'.
```

If your field is **required** (`{ sortable: string }`, no `?`) the whole object
type collapses to `never` and you get one error per property per literal:

```
error TS2322: Type '"id"' is not assignable to type 'never'.
error TS2322: Type 'string' is not assignable to type 'never'.
```

That fan-out is why a single shared column type produced 166 errors in one real
migration. Fix it at the type, not at the call sites:

```diff
- type Column = BbTableColumn<Patient> & { sortable?: string };
+ type Column = BbTableColumn<Patient> & { sortKey?: string };

  // or keep the name and take the field off the library type
+ type Column = Omit<BbTableColumn<Patient>, 'sortable'> & { sortable?: string };
```

`Omit` compiles, but read the next section before choosing it.

### The behaviour half — a truthy `sortable` turns on the built-in sort UI

`BbTable` coerces the field (`sortable: !!column.sortable` in `BbTable.vue`), so
**any** truthy value counts — including a sort-key string like
`'patients.created_at'`. The header stops rendering a plain label and renders a
`.bb-table-sort` button instead, and the header cell (`.bb-table-header`,
`role="columnheader"`) gains `aria-sort="none"`. An app
that already ships its own sortable-header UI now draws two.

The damage is bounded: `sort` is a controlled model (`v-model:sort`), so the
extra button emits and does nothing else — it cannot reorder your rows behind
your back. But it is visible, focusable, and announced.

So `Omit` silences the compiler and keeps the bug. Rename the field, or strip
it at the `BbTable` boundary:

```ts
const tableColumns = computed(() =>
	columns.value.map(({ sortable, ...rest }) => rest)
);
```

Column `rowClass` is the same shape of trap without the type error, because
`ColumnClasses` already accepts `string`: a leftover `rowClass: 'w-40'` you
meant for the column typechecks fine and is now merged onto the whole row
(`.bb-table-data__row`), alongside the table-level `rowClass` prop. A
non-`Classes` shape
(`rowClass?: { colspan: number }`) does error, with the same `undefined`
wording.

Grep both before you start:

```sh
rg -n 'sortable|rowClass' --type ts --type vue    # keep the hits on column objects
```

## Edits

```diff
- <BbTable :items="provider" :columns="columns" multiple :allow-select-all="false" />
+ <BbTable :items="provider" :columns="columns" multiple disable-select-all />

  <!-- passing allowSelectAll's default -->
- <BbTable … allow-select-all />
+ <BbTable … />
```

If a flow _depends_ on interacting with rows mid-refetch (rare, e.g. rapid
inline edits over a polling table):

```diff
- <BbTable :items="provider" :dependencies="[filters]" />
+ <BbTable :items="provider" :dependencies="[filters]" interactive-while-loading />
```

If you used `#loading` to show a custom refetch treatment, that role is gone —
the built-in dim + progress bar covers refetches; `#loading` is now only the
first-paint placeholder.

### `#no-data` is content, not a row

v2 handed the slot the whole empty-state `<tr>`, so anything that was not a
row — the usual `<div>` with a message and a "clear filters" button — landed
loose inside `<tbody>` and rendered left-aligned at content width instead of
spanning the table. v3 owns the row/cell shell itself
(`.bb-table-no-data__row[role=row]` > `.bb-table-no-data__cell[role=cell]`,
spanning every column with `grid-column: 1 / -1` and an `aria-colspan` that
already counts the selection and actions columns) and puts the slot inside it,
so that same markup now centres across the full width. A v2 `<tr>`/`<td>`
passed here is not just redundant any more — it is table markup inside a
grid, which is why the diff below deletes it rather than keeping it.

```diff
  <BbTable :items="rows" :columns="columns" selectable actions>
    <template #no-data>
-     <tr>
-       <td :colspan="columns.length + 2">
-         <p>No invoices match the current filters.</p>
-       </td>
-     </tr>
+     <p>No invoices match the current filters.</p>
    </template>
  </BbTable>
```

Only tables that hand-rolled the row shell need editing — content-only slots
(the overwhelmingly common case) are correct as they stand, and simply start
rendering where they always should have.

### `useBbTableContext().total` became `.totalItems` (v3 alpha, 2026-08-06)

The composable is new in v3, so this only affects apps written against the v3
alphas. Of the four pagination facts the shared context tracks, three already
carried their prop names across the prop/context boundary (`page`, `perPage`,
`totalPages`) and one did not: the row count was `total` on the handle while
the prop on **both** `BbTable` and `BbPagination` is `total-items`. It is now
`totalItems` everywhere — handle field, `initial` seed key, and the internal
host field.

```diff
- const { page, perPage, total } = useBbTableContext('invoices-table');
+ const { page, perPage, totalItems } = useBbTableContext('invoices-table');

- const ctx = useBbTableContext('invoices-table', { perPage: 25, total: 0 });
+ const ctx = useBbTableContext('invoices-table', { perPage: 25, totalItems: 0 });

  const fetchInvoices = async () => {
  	const response = await api.invoices.list();
- 	ctx.total.value = response.total;
+ 	ctx.totalItems.value = response.total;
  };
```

**Hard rename, no alias.** Reading `ctx.total` is now `undefined` and
`ctx.total.value = n` throws `Cannot set properties of undefined` — loud, not
silent. A seed passed as `{ total: 100 }` is a **type error** on
`BbTableContextInitial`; in an untyped call site it is simply ignored, and the
context stays not-ready (`isReady` false), so a paired `BbPagination` draws one
page. Grep: `rg '\.total\b' --type ts --type vue` and keep the hits that come
off a `useBbTableContext` handle — an API envelope's own `response.total` is
unrelated and does not change.

`BbPagination` consumers see the same rename through `table-id`; see
[BbPagination](./bb-pagination.md).

### Row events carry `(event, item)` — your raw record (v3 beta, 2026-08-26)

`click:row`, `contextmenu:row` and `dblclick:row` used to pass **the table's
internal row wrapper** (cells, classes, selection/highlight/expansion flags,
value hash — your record buried at `row.item`) plus a third `selected`
argument. Both are gone: the payload is the native event and **the record
exactly as you passed it in `items`**, nothing else. Selection state is
already yours through the `v-model` / `unselected-items` models, so the
handler read it from a second source of truth — and the owner wants row events
to carry the row, not a state dump.

```diff
- <BbTable @click:row="(event, row, selected) => open(row.item, selected)" />
+ <BbTable @click:row="(event, item) => open(item, selectedIds.includes(item.id))" />
```

Two silent JavaScript failures and one loud one: `row.item` is now
`undefined` (the record has no `.item` field unless yours does), the third
parameter is simply `undefined`, and any handler typed against `BbTableEvents`
with three parameters is a **type error** under `vue-tsc` 3. Grep:
`rg '(click|contextmenu|dblclick):row' --type vue` and inspect every handler
for `.item` reads and a third parameter.

### Highlight is opt-in — bind `ref(null)`, not `ref()` (v3 beta, 2026-08-27)

Row highlight used to run whether or not you bound it. With nothing bound the
table wrote to `defineModel`'s **local** fallback, so clicking any row applied
`bb-table-data__row--highlighted` and `aria-current="true"` and drove a state
your app could neither read nor clear. Invisible while the class shipped
unstyled; once a default cursor shipped, every table in the app started tinting
rows on click.

Highlight is now inert until something is connected, and **the model's value is
the switch**: `undefined` means "never initialised" (off), `null` means
"initialised and currently empty" (on).

```diff
- const highlighted = ref();
+ const highlighted = ref(null);
  // <BbTable v-model:highlighted="highlighted" … />
```

A bound-but-`undefined` model **warns in dev** naming the fix, so this does not
fail silently. A value seeded through the context counts the same and needs no
prop:

```ts
const highlighted = ref(null);
useBbTableContext('invoices-table', { highlighted });
```

Two things that did **not** change: `click:row` still fires on every row click,
connected or not — if you only wanted click notifications you never needed the
model and nothing breaks; and a table that already binds a real value or `null`
behaves exactly as before.

What to check: any table relying on the free highlight **without** binding the
model — styling `.bb-table-data__row--highlighted` yourself, or reading
`aria-current` in a test or E2E selector. Those now need the model bound.
`rg 'bb-table-data__row--highlighted|aria-current' --type vue --type css` and
keep the hits on tables whose `highlighted` is unbound. A `toggleHighlighted`
call from a cell slot on an unconnected table does nothing and warns once.

## The table is a CSS grid, not a `<table>` (v3 beta, 2026-08-26)

`BbTable` no longer renders a single `<table>` element. The substrate is a CSS
grid of `<div>`s: the root owns `grid-template-columns` (the column tracks
_are_ the width API — `columns[].width`, `fixed`, `inherit-column-widths` and
`snap` all resolve to tracks), and every row group and row is a `subgrid` of
it, so a cell lands on its column through two levels without a width of its
own. Nothing about the props, slots, events or models changed for this; what
changed is everything that touched the **markup** — CSS element selectors,
the markup you hand to `#thead` / `#tbody` / `#tfoot`, two published custom
properties, and a handful of things browsers do for real tables that they do
not do for grids (copy/paste, print, global element CSS).

### What renders now

```
.bb-table                                   container (div, or fieldset when selectable) — unchanged: [data-bb-table-id], aria-busy, overflow-x: auto
  legend.sr-only                            (selectable) — unchanged
  .bb-table-caption[id]                     replaces <caption>; sr-only unless display-caption; sits BEFORE the grid root
  .bb-table__table[role=table]              grid root — aria-labelledby → the caption, aria-rowcount
    .bb-table__head[role=rowgroup]          replaces <thead>; goes inert while loading; hosts the busy bar
      .bb-table-header-row[role=row]
        .bb-table-header[role=columnheader] (+ --select / --actions / --edge-start / --edge-end, aria-sort)
    .bb-table__body[role=rowgroup]          replaces <tbody>
      .bb-table-data__row[role=row]         tabindex / aria-rowindex / aria-current / inert / row events — as before
        .bb-table-data__cell[role=cell]     (+ --select / --edge-start / --edge-end)
        .bb-table__cell.bb-table__cell--actions[role=cell]
      .bb-table-expand__row[role=row]       id="expanded_{hash}" (the aria-controls target) — unchanged
        .bb-table-expand__cell[role=cell]   aria-colspan=N, grid-column: 1 / -1
      .bb-table-no-data__row  > .bb-table-no-data__cell[role=cell]      aria-colspan=N, grid-column: 1 / -1
      .bb-table-skeleton__row > .bb-table-skeleton__cell[role=cell]
      .bb-table-loading__row  > .bb-table-loading__cell[role=cell] > span.bb-table-loading__text[role=status][aria-live=polite]
    .bb-table__foot                         replaces <tfoot>; always rendered, role=rowgroup only when #tfoot is provided
```

**Every `.bb-table*` class survives on the equivalent node** — including the
asymmetric `bb-table__cell--actions` and the caption's `bb-table-caption` (no
`__`). The one exception is the transient `bb-table--measuring` state class,
which was never documented and existed only to hide the old probe's
scrollbar flash: it is gone with the probe. Four container classes are new: `.bb-table__table`, `.bb-table__head`,
`.bb-table__body`, `.bb-table__foot`. Every row carries `role="row"`, every
header cell `role="columnheader"`, every body/foot cell `role="cell"`. The
role chain `table → rowgroup → row → columnheader|cell` is what assistive
technology reads as a table; without it the whole tree is a pile of generic
`div`s. `aria-colspan` replaces the deleted `colspan` on the three full-width
cells (expand, no-data, loading).

### Selector translation

Element selectors are the break. Nothing throws: a rule on `tbody td` matches
nothing, the browser applies nothing, and the page renders with the
override silently missing. Translate every element name under `.bb-table`:

| v2 element                                                      | v3 selector                                                                                                                                       |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `table`                                                         | `.bb-table__table`                                                                                                                                |
| `thead`                                                         | `.bb-table__head`                                                                                                                                 |
| `tbody`                                                         | `.bb-table__body`                                                                                                                                 |
| `tfoot`                                                         | `.bb-table__foot`                                                                                                                                 |
| `caption`                                                       | `.bb-table-caption`                                                                                                                               |
| `tr`                                                            | `[role=row]` — or `.bb-table-data__row` for data rows only (the old bare `tr` matched every row kind: header, skeleton, no-data, expand, loading) |
| `th`                                                            | `[role=columnheader]` / `.bb-table-header`                                                                                                        |
| `td`                                                            | `[role=cell]` / `.bb-table-data__cell`                                                                                                            |
| `:first-child` / `:last-child` / `:not(.bb-table-expand__cell)` | **verbatim** — cells stay siblings inside their row                                                                                               |
| `td:nth-of-type(n)`                                             | `:nth-child(n)` — the children are type-uniform now, so `nth-of-type` and `nth-child` mean the same thing                                         |
| `colgroup` / `col`                                              | **gone** — use `columns[].width`                                                                                                                  |

`[role=row]`, `[role=cell]` and `[role=columnheader]` are **supported styling
hooks**, not incidental markup: the role tree is pinned by the component's own
tests, so a future move to `role="grid"` would be a deliberate selector break,
not an accident. There are no `data-*` hooks and no shim classes — the roles
plus the four container classes are the whole translation.

**Specificity caveat.** `[role=cell]` is an attribute selector, specificity
(0,1,0); `td` was a type selector, (0,0,1). A translated rule is therefore
_stronger_ than the one it replaces, and an override that used to lose to a
library rule (or to another of your own rules) by one type-selector point can
now win. Diff any page where two rules targeted the same cell, and prefer the
class forms (`.bb-table-data__cell`) when you need the old ordering back.

The library's own body-cell rules are deliberately held at **(0,2,0)** — the
row step is wrapped in `:where()` — so a scoped override of yours that beat
the old `.bb-table tbody tr td` (0,1,3) at (0,2,0) or better keeps winning.
An override written at exactly (0,1,x) (one class plus type selectors) is
the only band that loses ground: give it one more class.

The one idiom that dominates real apps — a full-bleed table that re-adds the
page inset on its outermost cells, scoped with direct-child combinators so a
nested table inheriting the parent's tracks is not touched — translates like
this:

```diff
- .table-flush :deep(> table > thead > tr > th:first-child),
- .table-flush :deep(> table > tbody > tr > td:first-child:not(.bb-table-expand__cell)) {
+ .table-flush :deep(> .bb-table__table > .bb-table__head > [role='row'] > :first-child),
+ .table-flush :deep(> .bb-table__table > .bb-table__body > [role='row'] > :first-child:not(.bb-table-expand__cell)) {
  	padding-inline-start: var(--page-inset);
  }

- .table-flush :deep(> table > tbody > tr > td.bb-table-expand__cell) {
+ .table-flush :deep(> .bb-table__table > .bb-table__body > [role='row'] > .bb-table-expand__cell) {
  	padding-inline: 0;
  }
```

The direct-child chain matters exactly as before: `.table-flush` lands on the
container, `.bb-table__table` is its direct child, and a nested table lives
inside `.bb-table-expand__cell`, so `>` at every step keeps the override off
the child's cells (whose padding is the alignment mechanism).

Grep for the hits: element names inside `:deep()`, inside `.bb-table` rules,
and — easy to miss — any **global** table CSS (`table { … }`, `td { padding }`,
`.prose table`), which reached the v2 markup and now reaches nothing (see
"Global element CSS" below).

### `#thead` / `#tbody` / `#tfoot` take role-complete rows

These three slots replace a whole row group, and the markup you pass into them
is now grid markup: a `<div role="row">` per row holding one
`<div role="columnheader">` (head) or `<div role="cell">` (body, foot) per
column — **never** a `<tr>` / `<th>` / `<td>`. A `<tr>` inside a grid is not
just wrong semantically: the `<tr>` is blockified into a single grid item and
the browser wraps its `<td>`s in an anonymous CSS table (under SSR the parser
drops the tags outright), so the cells never land on the tracks.

Rows are subgrid rows, so a cell takes the matching column track with no
width of its own. A cell that spans columns uses `grid-column`, not `colspan`:
the slot's `columnCount` (total rendered columns, selection and actions
included) is still handed to `#tfoot`, and it now feeds `grid-column: span N`
/ `grid-column: 1 / -1` instead of a `colspan` attribute. Add `aria-colspan`
on a spanning cell so column math stays right for assistive technology.

```diff
  <template #tfoot="{ columnCount }">
-   <tr>
-     <td :colspan="columnCount - 1">Total</td>
-     <td class="text-right">{{ total }}</td>
-   </tr>
+   <div role="row">
+     <div
+       role="cell"
+       :aria-colspan="columnCount - 1"
+       :style="{ gridColumn: `span ${columnCount - 1}` }"
+     >
+       Total
+     </div>
+     <div role="cell" class="text-right">{{ total }}</div>
+   </div>
  </template>
```

A full-width row is `grid-column: 1 / -1` on its single cell (plus
`aria-colspan="columnCount"`). Keep the invariant the component keeps: no
role-bearing element between the row group and the row, and every child of a
row is a `cell` or `columnheader`. **Nothing lints this** — a slot ported to
`<div>`s without roles renders fine and ships a table screen readers cannot
read; the docs are the only guard, hence the emphasis.

Two side effects of replacing the header: the table measures its column
tracks off the header cells, so with a custom `#thead` it falls back to the
first row with one child per track (the first data row) — **a custom header
over an empty table publishes no tracks**, and a nested table cannot inherit
from it until rows arrive. And under `fixed-headers`, a `#thead` with several
rows now sticks as a block (all rows stack); the old cell-level sticky stacked
them on top of each other.

### `--fill` and `--natural-width` are removed, not renamed

Both were plumbing for the `table-layout: fixed` self-correction loop (a
measured natural width the table could never shrink below, and a fill
correction that compensated fixed-layout arithmetic). The grid has no such
loop: tracks are sized by the engine from the declarations, in one layout
pass, with no offscreen probe. Republishing the sum of the resolved tracks
under the same names would publish the _container_ width under a name
promising the _natural_ width — wrong by 2× in the panel's probe — so they
are dropped outright, the same treatment `--available-height` got. No consumer
outside the component's own stylesheet ever read them; a
`var(--natural-width)` in your CSS now resolves to its fallback.

### Column widths: what holds and what drifts

Frozen widths (`columns[].width`) hold **exactly**: a `120px` column is
120px. The overflow threshold (the container width at which the table starts
scrolling) and the wrap floor (the narrowest a column gets before its text
wraps) are **pixel-identical** to table auto layout — the panel measured 905px
against 905px. `fixed` still splits the width equally (`minmax(0, 1fr)` per
column). Everything else below is documented drift, each with the numbers
from the panel's probes (`plans/BBTABLE-GRID.md` § Tracks and § v2.1), so
you know what a screenshot diff is showing you:

- **Roomy containers share the surplus equally, not proportionally to
  content.** Two auto columns that the table sized 748px / 52px now come out
  544px / 256px. Short columns get wider; long ones narrower. Add a `width` to
  any column whose proportion you relied on.
- **Constrained wrapping distributes differently.** When several wrappable
  columns compete for a narrow container, tracks grow in equal increments up
  to their max-content instead of proportionally — the longest column ends up
  ~22% narrower and its rows taller. The table starts scrolling at the same
  width as before; only the split before that point moved.
- **Frozen + auto mixes drift ≤ ~19px per column** — the fixed-layout regime
  where declared widths sat next to unfrozen ones.
- **All-frozen tables inflate their data columns exactly as before, but not
  the structural ones.** When every column declares a width and the sum is
  below the container, the surplus is still shared in proportion to the
  declared widths (`[100, 200, 100]` at 600px → `[150, 300, 150]`, `%` too),
  so the table keeps filling. The selection and actions columns stay at
  content width instead of inflating with the rest.
- **A cell that is its own scroll container no longer floors the column.**
  Under table auto layout an `overflow: hidden` / `auto` cell still
  contributed its content width to the column. Under grid it does not — which
  means native `text-overflow: ellipsis` finally works in a cell — **and the
  classic table trick `max-width: 0` breaks**: the cell collapses to its
  padding. Delete every `max-width: 0` you added to make ellipsis work.
- **Percentage widths in an overflowing table resolve against the grid's
  min-content width**, not the container: a `30%` column that the table gave
  181px gets 303px once the table overflows. Non-overflowing tables are
  identical. (`width: fit-content` on the grid root keeps the root's box
  covering its tracks only without `%` tracks under overflow — a `%`-wide
  overflowing table is the one case where row backgrounds can paint short of
  the scroll width.)
- **Expand-row content never widens the parent's columns.** A wide nested
  table or a long unbroken string in `#expand` used to push an auto-layout
  parent's columns apart (a 300px track became 500px in the probe); the grid
  contains the full-width cells (`contain: inline-size`), so the parent's
  tracks hold and the content overflows into the scrollport instead. Fixed
  layout was already immune; auto layout was not; the grid always is.
- **A `snap` on a column whose table has no parent** used to fall into an
  accidental equal split. It now sizes like any other unfrozen column
  (`auto`).
- **Nested tables align by contract, at any depth.** A child's select/actions
  cell is widened to the parent's region (`minmax(region, max-content)` — two
  equal cells, controls at the row's end); a child without one folds the
  region into its edge cell's padding. A child cell _wider_ than the parent's
  is reclaimed from the adjacent content column only. What each table
  publishes to its own children is the pure content rails plus the two
  regions, so a grandchild aligns with the root — previously the middle
  table's padding compensation was invisible to its children. The fill
  column now only ever grows (`minmax(<its rail>, 1fr)`); it no longer
  shrinks to absorb a wider actions column.

### Copy-to-spreadsheet degrades

Selecting rows in a real `<table>` and pasting into a spreadsheet gave one
cell per column. Chrome's selection serializer keys off the computed
`display`, not the element or its role, so a grid pastes **one value per
line** — the columns are lost. Accepted: the substrate is not going to carry a
hidden `<table>` for the clipboard. The sanctioned path is an app-level
"copy as TSV" action built from the **items model** (the same rows you gave
`items`, joined with tabs and newlines and written with `navigator.clipboard`)
— a recipe for it is queued (FOLLOWUPS Q7.4); do not scrape the DOM for it.

### Print: header repetition is gone

Browsers repeat a `<thead>` at the top of every printed page; there is no
grid equivalent, so a long table prints its header once. Data rows carry
`break-inside: avoid` so a row is never split across pages, which is the most
the substrate can do. No `@media print` rule exists in the library, so nothing
of yours is fighting one — but if a printed report depended on the repeated
header, that is a real regression to plan for (a print-specific view, or
paginated sections with their own headers).

### Global element CSS no longer reaches the table

Any CSS that reached `BbTable` through element names now misses it: a reset
(`table { border-collapse: … }`, `td, th { padding: 0 }`), Tailwind's
`.prose table` typography, a stray `td { vertical-align: top }` in a legacy
sheet. This cuts both ways. It is an **immunity** — the table no longer
inherits whatever global table styling the app carries — and it is a **silent
change** on every page where that global CSS was, knowingly or not, part of
the look. Diff those pages; then re-express what you actually wanted on
`.bb-table-data__cell` / `[role=cell]` scoped to a table.

### Browser floor

The table requires `grid-template-columns: subgrid`: **Chrome/Edge 117,
Firefox 71, Safari 16**. There is no `@supports` fallback and none is planned —
maintaining two substrates defeats the rewrite. Cell content is centred
vertically with `align-content` on a block container, which lands one notch
higher: **Chrome 123, Safari 17.4, Firefox 125**. Below that, cells still lay
out correctly but content sits at the top of the cell instead of the middle.

All of this sits inside the library-wide floor — **Chrome/Edge 114, Safari 17,
Firefox 125**, set by the native Popover API (see
`installation-and-plugin-setup.md` § Browser support) — so the only engine the
grid actually raises is Chrome/Edge, 114 → 117 (123 for centred cells).

### Do not override

- **Do not hide cells with `display: none`** (a `thClass`/`tdClass` of
  `hidden`, the v2/early-v3 narrow-screen recipe). A hidden grid item leaves
  its track in place: every following cell shifts one track over and the last
  track collapses. Hide a column by removing it from `columns` at the
  breakpoint, which removes the track.
- **`contain: inline-size` on `.bb-table-expand__cell`,
  `.bb-table-no-data__cell` and `.bb-table-loading__cell`.** It is the only
  thing keeping a full-width cell's content from resizing the column tracks —
  `min-width: 0` and `width: 100%` wrappers do not work here, and with a nested
  inheriting table inside the expand row the result without it is a feedback
  loop. Removing it (or setting `contain: none` on a cell) is not a styling
  choice.
- **`gap: 0` on `.bb-table__table`.** A gap set on the root cannot be undone
  from a subgrid level; it opens gutters between every column.
- **`display: grid` on the root, row groups and rows**, and the
  `grid-column: 1 / -1` on the full-width cells — the geometry.
- **`white-space: nowrap` on `.bb-table__cell--actions`** — the actions track
  is `max-content`, and `nowrap` is what makes that the width of the controls
  side by side rather than a wrapped stack.
- **`position: sticky` on `.bb-table__head`** under `fixed-headers`: sticky
  lives on the row group, not on cells — a sticky cell inside the subgrid
  cannot stick in any engine.

### Small semantic and visual changes

- **Pinned cells and the stuck header are opaque.** `fixed-columns` cells and
  the `fixed-headers` band used to be transparent, so scrolled content showed
  through them. They now paint the table's surface local `--bg` (default
  `var(--bb-panel)`); a pinned cell also paints its row's hover/highlight
  tint. On a non-panel surface set `.bb-table { --bg: … }` once. The
  highlighted row's left accent bar moved from the row onto its first cell
  (same position; an opaque pinned first column would have hidden it).
- **The sort glyph is one arrow.** The two-chevron `sort.svg` (with its
  inner `sort-icon__asc` / `sort-icon__desc` paths) is gone; the sort button
  renders an inline `<svg class="bb-table-sort__icon">` — a single arrow,
  hidden at rest, faint on hover/focus, solid when sorted: up for ascending,
  rotated down for descending (the AG Grid convention). Apps that copied the old glyph to rebuild
  a header no longer need to (use the header prepend/append slots); any CSS
  on `.sort-icon__asc` / `.sort-icon__desc` matches nothing.
- **Caption reading order.** The caption is now a `div` _before_ the table
  role, named through `aria-labelledby`, rather than a `<caption>` inside it.
  The accessible name is identical; a screen reader reading linearly meets the
  caption text just before the table instead of as its first child.
- **The busy bar rides with a stuck header.** With `fixed-headers`, the
  refetch progress bar is anchored to the sticky head row group, so it stays
  at the header/body boundary while you scroll. It used to anchor to the
  in-flow `<thead>` box and scroll away while the header cells stuck — the
  documented intent, now the behavior.
- **Multi-row `#thead` heads stack when stuck** (above).
- **`aria-rowcount` now counts the header row**: it is `totalItems + 1`, so
  the last row's `aria-rowindex` no longer exceeds the count. Anything
  asserting the old value must add one.
- **Row heights change with the wrapping drift** — expect it in screenshot
  diffs of narrow, text-heavy tables.

## The custom properties the table _publishes_ lost the `bb-` prefix

These are not theming inputs — they are values `BbTable` measures at runtime and
writes onto its own DOM, for the table's CSS and for descendants to read. You
reach for them for exactly one reason: aligning a nested table's columns to its
parent's. They all dropped the prefix.

| v2                                          | v3                                                 |
| ------------------------------------------- | -------------------------------------------------- |
| `--bb-table-{id}-track-{key}`               | `--table-{id}-track-{key}`                         |
| `--bb-table-offset-start` / `-end`          | `--offset-start` / `--offset-end`                  |
| `--bb-table-offset-internal-start` / `-end` | `--offset-internal-start` / `-internal-end`        |
| `--bb-table-offset-external-start` / `-end` | `--offset-external-start` / `-external-end`        |
| `--bb-table-fill`                           | **removed** (was `--fill` in v3 ≤ beta.5)          |
| `--bb-table-natural-width`                  | **removed** (was `--natural-width` in v3 ≤ beta.5) |
| `--bb-table-cell-h`                         | `--cell-h`                                         |

Only the track bridge keeps a `table-` segment, because it crosses component
boundaries; the rest are plain locals on `.bb-table`. `--fill` and
`--natural-width` were the fixed-layout self-correction values; the grid
substrate (next section) has no such loop, so they are gone rather than
republished under a name that would lie about what they hold. `--padding-x`,
`--padding-y` and `--actions-spacing` were already unprefixed in v2 and keep
their names (their _values_ tightened: `16px`/`8px` → `12px`/`6px`, and the cell
height `42px` → `36px`).

**Every one of these fails silently.** They are read as
`var(--offset-internal-start)` with a fallback, so a v2 override lands on a name
nothing consumes and the layout quietly falls back to its default. The worst
case is code that _scans_ for them — a nested-table helper matching
`/--bb-table-[\w-]+-track/` over `element.style` matches nothing at all, no
error, just columns that no longer line up:

```diff
- const track = /--bb-table-[\w-]+-track/;
+ const track = /--table-[\w-]+-track/;
```

Grep your app CSS and any style-scanning JS for `--bb-table-` — no name with
that prefix exists in v3.

The table is not the only component this happened to. Four more published
variables lost the prefix the same way: `--bb-select-popover-width` → `--w` on
`.bb-select-popover` (and the supported path is now the `width` prop, not a CSS
override), `--bb-icon-dimensions-w` → `--w` on `.bb-icon`,
`--bb-breadcrumbs-flex-basis` / `-flex-grow` → `--flex-basis` / `--flex-grow`,
and `--bb-picker-preview-color` → `--picker-preview-color`. Widen the grep
accordingly: `--bb-select-popover-`, `--bb-icon-dimensions-`, `--bb-breadcrumbs-`,
`--bb-picker-`. See
[design-tokens.md](../../design-tokens.md#migration-from-the-old-tokens) for the
theming-token side of the same rename.

## `caption` names the selection fieldset when `legend` is absent

A `selectable` table wraps itself in a `<fieldset>` and needs an accessible
name. v3 resolves it as `legend`, then `caption`, then a generic localized
string — so a table that already has a `caption` is correctly named and does not
need a `legend`.

`npx bitboss-ui check` (and the ESLint rule behind it) still asks for `legend`
specifically, so `<BbTable selectable caption="Patients" />` fails the check
even though its fieldset is named. That one is a **quality nudge, not a broken
affordance** — unlike the other partner-prop pairs, ignoring it does not leave
anything silently doing nothing. Pass a `legend` when it says something the
caption does not ("select invoices to export" vs "Invoices"); otherwise suppress
the rule at the call site rather than duplicating the caption into a `<legend>`.

---

<!-- dist/ai/guides/migration/components/bb-tabs.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-tabs.md -->

# BbTabs — v2 → v3

The component `BbTab` is renamed **`BbTabs`** (types too; `BbTabProps`-style
aliases survive as deprecated re-exports, the tag name does not).

## Changes

| v2                                       | v3                                                      | Kind                                                                                    |
| ---------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `<BbTab>`                                | `<BbTabs>`                                              | rename                                                                                  |
| `querykey?: string`                      | `queryKey?: string` (default `'tab'`)                   | **⚠ silent** — a leftover `querykey` is ignored and URL sync moves to `?tab=`           |
| `animateX` / `animateY` (default `true`) | `disableAnimateX` / `disableAnimateY` (default `false`) | polarity rename — bare `animate-x` → delete; `:animate-x="false"` → `disable-animate-x` |
| label slot `#label-<key>`                | `#label:<slotKey(key)>`                                 | rename + normalization                                                                  |
| pane slot `#<key>` (raw)                 | `#<slotKey(key)>`                                       | normalization                                                                           |
| URL value = raw key                      | URL value = normalized slug                             | **⚠ breaking for deep links**                                                           |
| tab/panel DOM ids from raw key           | normalized (also fixes invalid ids for spaced keys)     | check E2E selectors                                                                     |
| `.bb-tab*` CSS                           | `.bb-tabs*` / `.bb-tabs-list*` / `.bb-tabs-panes`       | **⚠ silent** — the whole BEM tree renamed, see below                                    |
| —                                        | `block` (full-width, equal-width triggers)              | additive — replaces hand-rolled full-width classes                                      |

`slotKey(key)` lowercases and replaces every non-word run with `_`:
`"In Review"` → `in_review`, `"2024-03-15"` → `2024_03_15`. Keys that are
already lowercase slugs are untouched — then only the `label-` → `label:`
rename applies.

**What stays raw:** `v-model` and the item `key`. `v-model="'In Review'"`
still selects that tab; only slots, ids, and the URL use the slug.

## Edits

```diff
- <BbTab :items="items" navigation querykey="section" :animate-x="false">
+ <BbTabs :items="items" navigation query-key="section" disable-animate-x>
-   <template #label-in-review="{ item }">…</template>
+   <template #label:in_review="{ item }">…</template>
-   <template #In Review>…</template>            <!-- was never valid HTML anyway -->
+   <template #in_review>…</template>
- </BbTab>
+ </BbTabs>
```

**Server side:** if backend code reads the tab query param, it now receives
the normalized slug (`?section=in_review`, not `?section=In%20Review`).
Existing bookmarks with raw values fall back to the default tab — add a
redirect if those links matter.

## CSS: every class renamed with the component

The component rename took the whole BEM tree with it. v2 kept everything under
one block, `.bb-tab`; v3 splits it into `.bb-tabs` (root) plus two blocks of
their own, `.bb-tabs-list` (the strip) and `.bb-tabs-panes` (the pane wrapper).
**No `.bb-tab*` selector survives**, and nothing warns — your v2 tab CSS just
stops matching and the shipped styling shows through.

| v2                                        | v3                                                                |
| ----------------------------------------- | ----------------------------------------------------------------- |
| `.bb-tab`                                 | `.bb-tabs`                                                        |
| `.bb-tab--horizontal`                     | `.bb-tabs--horizontal` (+ `.bb-tabs-list--horizontal`)            |
| `.bb-tab--vertical`                       | `.bb-tabs--vertical` (+ `.bb-tabs-list--vertical`)                |
| `.bb-tab--disabled`                       | `.bb-tabs--disabled` (+ `.bb-tabs-list--disabled`)                |
| `.bb-tab__label-boundary`                 | `.bb-tabs-list`                                                   |
| `.bb-tab__label-container`                | `.bb-tabs-list__tablist`                                          |
| `.bb-tab__label-container--no-transition` | `.bb-tabs-list__tablist--no-transition`                           |
| `.bb-tab__btn`                            | `.bb-tabs__trigger`                                               |
| `.bb-tab__btn--active`                    | `.bb-tabs__trigger--active`                                       |
| `.bb-tab__label`                          | `.bb-tabs__trigger-label`, wrapped in `.bb-tabs__trigger-content` |
| `.bb-tab__panes-container`                | `.bb-tabs-panes`                                                  |
| `.bb-tab__pane`                           | `.bb-tabs__pane`                                                  |
| `.bb-tab__pane--shown`                    | `.bb-tabs__pane--shown`                                           |

New in v3 with no v2 counterpart: `.bb-tabs--block` / `.bb-tabs-list--block`,
`.bb-tabs--compact` / `.bb-tabs-list--compact`, `.bb-tabs-list__prepend` and
`__append`, `.bb-tabs-list__tablist--measuring`.

Four things to know while porting rules:

- **The nesting did not change.** `.bb-tab__label-container` and
  `.bb-tabs-list__tablist` are the same `<ul>`. The sliding active pill is
  still that element's `::before`, still positioned from `--left` / `--top` /
  `--width` / `--height` set inline on it. A v2 pill override moves by name
  only, not up or down a level.
- **`.bb-tabs--horizontal` is rendered.** The direction modifier is applied
  unconditionally (`bb-tabs--${direction}`, default `'horizontal'`), so a
  renamed v2 rule keeps working. The library ships no _rule_ for the horizontal
  modifier — only `--vertical` is styled — but that does not affect your
  selectors. Do **not** rewrite these as `:not(.bb-tabs--vertical)`.
- **The `<ul>` is no longer an only child.** `.bb-tabs-list` is a grid holding
  `__prepend`, the tablist, and `__append`. A v2 rule written as
  `.bb-tab__label-boundary > *` now over-matches; target
  `.bb-tabs-list__tablist` by name.
- **Block naming is not uniform** between the two new blocks: the pane wrapper
  is `.bb-tabs-panes`, but the pane inside it is an element of the root,
  `.bb-tabs__pane`. There is no `.bb-tabs-panes__pane`.

Grep for survivors — this catches every v2 name and no v3 one:

```sh
rg -n 'bb-tab(__|--)|\.bb-tab\b'
```

## `block` replaces hand-rolled full-width tabs

v2 shipped no full-width tab list, so apps minted their own class — commonly a
`bb-tab--full-width` / `bb-tabs--full-width` rule stretching the `<ul>` and
setting `flex: 1` on each button. v3 has the prop:

```diff
- <BbTab :items="items" class="bb-tabs--full-width">
+ <BbTabs :items="items" block>
```

`block` sets `.bb-tabs--block` and `.bb-tabs-list--block`: the strip stretches
to 100% and every trigger takes an equal share of the free space, floored at
the widest trigger's measured width (published as `--eq` on the tablist) so the
triggers stay equal even when the strip overflows and scrolls. Horizontal only
— the vertical strip skips the measurement.

Delete the hand-rolled rule when you switch. Left in place it fights `--block`
over the same `flex` and `min-width` declarations, and because your class name
is now unrecognised (`bb-tabs--full-width` collides with nothing the library
ships) neither the checker nor ESLint will tell you which one won.

---

<!-- dist/ai/guides/migration/components/bb-tag.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-tag.md -->

# BbTag — v2 → v3

## Changes

| v2                                    | v3                                               | Kind                                                                                                                              |
| ------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `modelValue: any`                     | `modelValue: string[]`                           | retype — non-array/typed-object models fail to compile; map to strings at the boundary                                            |
| `multiple?: boolean` (default `true`) | removed                                          | always a multi-value array input                                                                                                  |
| `divider?: KeyboardEvent['key']`      | `KeyboardEvent['key'] \| KeyboardEvent['key'][]` | widened — e.g. `:divider="['Enter', ',']"`                                                                                        |
| duplicate handling: exact match       | trimmed + **case-insensitive** dedup by default  | **behavior** — `'Vue'` then `'vue'` now triggers `duplicate` instead of adding both; pass `case-sensitive` to restore v2 matching |
| —                                     | `max` event, `caseSensitive`, extra input events | additive                                                                                                                          |

## Edits

```diff
- <BbTag v-model="tags" :multiple="true" divider="," />
+ <BbTag v-model="tags" :divider="[',']" />

  <!-- v2 exact-match dedup preserved -->
+ <BbTag v-model="tags" case-sensitive />
```

If your model held objects (`{ id, label }[]`), keep the objects in your own
state and bind a mapped `string[]`, syncing on `update:modelValue`.

---

<!-- dist/ai/guides/migration/components/bb-text-input.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-text-input.md -->

# BbTextInput — v2 → v3

## Changes

| v2                                                                               | v3                                                                                                                                                               | Kind                                                                                                                                                                                                      |
| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type?: HTMLInputElement['type']` (any string)                                   | `type?: 'text' \| 'email' \| 'url' \| 'tel' \| 'search' \| 'password'`                                                                                           | retype — other values fail to compile                                                                                                                                                                     |
| `direction?: string`-ish                                                         | `InputDirection` (`'auto' \| 'horizontal' \| 'vertical' \| 'xx xxxx'`) — in a two-token pattern the tokens' **character counts** are the ratio, not their values | family-wide retype — typos now fail to compile                                                                                                                                                            |
| imperative template-ref API (`inputRef.value.focus()` / `.blur()` / `.select()`) | removed                                                                                                                                                          | no consumer-facing expose; use the native `autofocus` prop, or reach the underlying `<input>` for the rare programmatic focus. **⚠ silent**: a stale `inputRef.value?.focus()` is `undefined` at runtime. |
| —                                                                                | `description`, extra keyboard/composition events                                                                                                                 | additive                                                                                                                                                                                                  |

## Edits

```diff
- <BbTextInput v-model="qty" type="number" label="Quantity" />
+ <BbNumberInput v-model="qty" label="Quantity" />

- <BbTextInput v-model="when" type="date" label="Due" />
+ <BbDatePickerInput v-model="when" label="Due" />
```

Values that were never text-like (`checkbox`, `file`, `range`, …) were always
the wrong component; the type now says so.

The sibling **`BbNumberInput`** likewise dropped its `increase()` / `decrease()`
template-ref API: build an in-affix stepper from the `prepend`/`append`/`prefix`/
`suffix` slot scope (`{ increase, decrease }`), and for an external stepper drive
`v-model` directly (`model += step`).

Also relevant here: the shared input wrapper's CSS block was renamed — any CSS
or test selectors on `.bb-common-input-inner-container*` must move to
`.common-input-wrapper--*` (see [main guide §5](../v2-to-v3.md)).

## `floating` is not a prop — it is a value of `label-mode`

```diff
- <BbTextInput v-model="email" label="Email" floating />
+ <BbTextInput v-model="email" label="Email" label-mode="floating" />
```

`labelMode?: 'outside' | 'floating' | 'inside'` — same in v2 as in v3. A bare
`floating` was never a `BbTextInput` prop on either version; it falls through
`$attrs` onto the root element and does nothing, silently. Applies to the whole
input family, which shares `labelMode`.

`bitboss-ui check` flags it, but points the wrong way:

> prop `floating` is not in BbTextInput's API — `floating` belongs to
> BbDatePicker, BbDatePickerInput, not BbTextInput

That is true and irrelevant. Those two do declare a real `floating` boolean, and
it means something else entirely there (emit plain calendar strings instead of
zoned ISO instants). The answer is `label-mode="floating"` on the component you
already have.

## DOM: `--hidden-label` layout class removed (2026-08-07)

`BbBaseInputContainer` — the wrapper behind every labelled control in the
family — no longer renders `bb-base-input-container__layout--hidden-label`. It
was applied on exactly the same condition as
`bb-base-input-container__layout--reverse`, was styled nowhere in the library,
and its name did not describe what it meant. Anything targeting it should
target `--reverse`.

---

<!-- dist/ai/guides/migration/components/bb-toast.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-toast.md -->

# BbToast / `toast()` — v2 → v3

## The host component

| v2                                                         | v3                                                                                                         | Kind                          |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------- |
| `placement?: 'bottom' \| 'bottom-start' \| … \| 'top-end'` | `position?: BbToastPosition` — `top-left, top-center, top-right, bottom-left, bottom-center, bottom-right` | rename + new value vocabulary |

Value mapping: `bottom` → `bottom-center`, `bottom-start` → `bottom-left`,
`bottom-end` → `bottom-right` (same for `top-*`). Unset now falls back to the
plugin's `toastPosition` config (default `bottom-right`).

```diff
- <BbToast placement="top-end" />
+ <BbToast position="top-right" />
```

## `toast()` options

| v2                                     | v3                                                                                                         | Kind                      |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------- |
| `theme?: string`                       | `variant?: ToastVariantType` (built-ins `default, success, info, warning, destructive`)                    | typed rename              |
| `timeout?: number`                     | `duration?: number`                                                                                        | rename                    |
| `showClose?: boolean` (default `true`) | `hideClose?: boolean` (default `false`)                                                                    | rename, polarity inverted |
| `persistent`                           | unchanged                                                                                                  |                           |
| `title`, `text`, `icon`                | unchanged (`text` is now optional)                                                                         |                           |
| —                                      | `position`, `loading`, `id` + `updateToast()`, `dismissToast(reason)`, `portal` / `portalProps`, `actions` | additive                  |

`timeout` → `duration` is the one to grep for. It is an options-object key, not
a template attribute, so neither `bitboss-ui check` nor the eslint plugin sees
it; TS catches a literal `toast({ timeout: 8000 })` on excess-property grounds,
but a JS call site — or options built up in a variable — just drops the key and
takes the default, which also shortened: **v2 6000ms, v3 4000ms**. Same rule at
both ends: a non-positive value throws. `rg -n 'timeout' --type ts --type js`
over your toast call sites.

`showClose` inverts, it does not disappear: `showClose: false` → `hideClose: true`,
and `showClose: true` was the default so **delete it**.

```diff
- toast({ title: 'Deleted', theme: 'success', timeout: 4000, showClose: false });
+ toast({ title: 'Deleted', variant: 'success', duration: 4000, hideClose: true });

  // the hand-rolled undo pattern collapses to:
+ toast({ title: 'Deleted', actions: [{ text: 'Undo', onClick: restore }] });
```

`toast('plain string')` still works. The `BbToastMessage` type export is gone
— type options as `BbToastOptions` (and a partial update as `BbToastUpdate`).

## What `useToast()` returns

| v2                               | v3                                                           |
| -------------------------------- | ------------------------------------------------------------ |
| `{ toast, dismiss, dismissAll }` | `{ toast, dismiss, update }`                                 |
| `dismiss(id)` — id required      | `dismiss(id?, reason?)` — **no argument dismisses them all** |
| `dismissAll()`                   | removed — call `dismiss()` with no argument                  |
| —                                | `update(id, options)`                                        |

```diff
- const { toast, dismissAll } = useToast();
- dismissAll();
+ const { toast, dismiss } = useToast();
+ dismiss();
```

Nothing catches this for you — `dismissAll` is not a template attribute, so
`bitboss-ui check` and the eslint plugin never see it. Grep:
`rg -n 'dismissAll' --type ts --type js --type vue`. Hits on a `useConfirm()`
destructure are fine: `dismissAll` is **new** there, and unrelated.

Notes on `actions` (additive but with rules): handlers run with a spinner and
sibling-disable, and hold the dismiss timer; portal toasts ignore `actions`.
Styling hooks moved from `theme` classes to `bb-toast-message--<variant>` —
custom looks register through the plugin's `toastVariants` option
([main guide §4](../v2-to-v3.md)).

---

<!-- dist/ai/guides/migration/components/bb-tooltip.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-tooltip.md -->

# BbTooltip / `v-bb-tooltip` — v2 → v3

## Changes

| v2                                     | v3                                                                         | Kind                                                                                                                  |
| -------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `timeout?: number`                     | `delay?: number` (default `0`)                                             | rename (`BbAvatar.timeout` is unrelated and keeps its name)                                                           |
| `theme?: string` (deprecated)          | `variant?: TooltipVariantType` (`default, destructive`; default `default`) | typed rename                                                                                                          |
| arrow via undeclared fall-through      | `hideArrow?: boolean` (default `false` — arrow shown)                      | now a real, typed prop                                                                                                |
| `activator` / `boundary` loose types   | `ElementOrComponentRef*`                                                   | transparent in templates                                                                                              |
| `showClose?: boolean` (default `true`) | removed                                                                    | **the tooltip has no close button.** ⚠ Do **not** rewrite to `hide-close` — that prop does not exist here. Delete it. |
| `block`                                | removed                                                                    | dead prop — it styled nothing (same as `BbPopover.block`)                                                             |
| —                                      | `modelValue` + `update:modelValue`                                         | additive — a tooltip can now be opened/closed programmatically                                                        |

The tooltip is the **only** surface that kept its arrow — popovers, selects,
dropdowns and the color palette dropped theirs (see
[bb-popover.md](./bb-popover.md)).

### `showClose` is a delete, not a rename

The tooltip used to render its own close button, and `showClose` (default
`true`) controlled it. It was dropped on the v2 line in **2.1.125** and never
existed in v3 — a tooltip is dismissed by moving the pointer or pressing
Escape, so there is nothing to show or hide.

The trap: v3 inverted `showClose` → `hideClose` on `BbAlert`, `BbDialog` and
`BbOffCanvas`, which makes the rename look library-wide. It is not. On
`BbTooltip` (and on `BbPopover`) the prop was **removed**, so both spellings are
wrong in v3:

```diff
- <BbTooltip :activator="el" :show-close="false" text="Careful" />
- <BbTooltip :activator="el" hide-close text="Careful" />   <!-- ✗ invented prop -->
+ <BbTooltip :activator="el" text="Careful" />
```

If you were passing `:show-close="false"` you already had the v3 behaviour —
deleting the prop changes nothing visually. `npx bitboss-ui check` flags both
spellings and names this file.

## Edits

```diff
- <BbTooltip :activator="el" :timeout="300" theme="destructive">Careful</BbTooltip>
+ <BbTooltip :activator="el" :delay="300" variant="destructive">Careful</BbTooltip>

  <!-- directive form: object options follow the same prop names -->
- <span v-bb-tooltip="{ text: 'Careful', timeout: 300 }">…</span>
+ <span v-bb-tooltip="{ text: 'Careful', delay: 300 }">…</span>
```

The directive itself is unchanged (`v-bb-tooltip:placement`), but in v3 it is
registered by the runtime plugin — drop any manual
`app.use(BbTooltipDirectivePlugin)` ([main guide §1](../v2-to-v3.md)).

---

<!-- dist/ai/guides/migration/components/bb-tree.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/bb-tree.md -->

# BbTree — v2 → v3

The tree was redesigned around a typed item shape. This is the heaviest
per-component rewrite in v3 — the old items don't fit the new mold field by
field.

## Item model

| v2 `TreeItem`                       | v3 `BbTreeItem<Meta>`                                       |
| ----------------------------------- | ----------------------------------------------------------- |
| arbitrary fields on the node itself | node payload lives under **`meta`** (typed via the generic) |
| `open?: boolean`                    | `expanded?: boolean` (seeds the expansion model)            |
| `children?: TreeItem[]`             | `children?: BbTreeItem<Meta>[]`                             |
| —                                   | `expandable?: boolean`                                      |

`TreeItem` survives only as a deprecated type alias.

## Props / slots

| v2                                     | v3                                                                       | Kind                                                   |
| -------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------ |
| `identifier?: string` (default `'id'`) | `itemValue: ItemAccessor` — key name or `(item) => id`                   | rename + widened                                       |
| `parent`, `depth` (leaked internals)   | removed                                                                  | were never meant to be public                          |
| expansion = mutate `open` on your data | `v-model:expandedItems` (array of node values)                           | state moved out of the data                            |
| per-node slots by raw value            | per-node slots by `slotKey(value)` — `#Order History` → `#order_history` | **⚠ silent** — stale raw names render fallback content |

## ARIA: it's a disclosure list now, not a WAI-ARIA tree

v3 removes every tree role the v2 markup claimed: no `role="tree"` on the
root, no `role="treeitem"` / `aria-level` / `aria-posinset` / `aria-setsize` /
node-level `aria-expanded` on nodes, no `role="group"` on children containers.
The roles promised a keyboard contract (roving tabindex, Arrow/Home/End) that
was never implemented, and completing it is incompatible with slot-driven
nodes that hold your own links and buttons — so the claim is gone rather than
fulfilled. What remains is a plain disclosure pattern: your toggle button
(bound via `expandProps`) owns `aria-expanded` + `aria-controls`, and the
children region carries the matching `id`.

**⚠ silent** — anything selecting on the removed attributes matches nothing
now: tests keying on `[role="treeitem"]`, CSS on `[role="tree"]`,
`aria-expanded` read from the node container instead of the toggle button.
Re-key on `.bb-tree__node` / your own markup, and read `aria-expanded` from
the element you bound `expandProps` to. If you bound `expandProps` to a
`<button>` (the documented contract), nothing changes for you.

New in the same pass: a collapsed branch's children container is now `inert`,
so links/buttons inside it leave the Tab order and the accessibility tree —
v2 left them focusable while invisible. If a test tabbed "through" a
collapsed branch, it will (correctly) stop doing so.

## Edits

```diff
- const items = [
-   { id: 'docs', label: 'Documents', open: true, children: [
-     { id: 'q3', label: 'Q3 Reports' },
-   ]},
- ];
+ const expanded = ref<string[]>(['docs']);
+ const items: BbTreeItem<{ label: string }>[] = [
+   { meta: { id: 'docs', label: 'Documents' }, expanded: true, children: [
+     { meta: { id: 'q3', label: 'Q3 Reports' } },
+   ]},
+ ];

- <BbTree :items="items" identifier="id" />
+ <BbTree :items="items" :item-value="(i) => i.id" v-model:expandedItems="expanded" />
```

Branches default to expanded; per-node `expanded` seeds the model. Connector
lines are deliberately not built in — draw them in your own CSS against the
`--indent` / `--gap` tokens if you had them.

---

<!-- dist/ai/guides/migration/components/use-broadcast-channel-instance.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/use-broadcast-channel-instance.md -->

# `useBroadcastChannelInstance` — v2 → v3

**Removed in v3.** It was a typed wrapper around the `BroadcastChannel` API: no
markup, no styling, no design-system surface, and **not used by a single
component in the library**. Cross-tab messaging is application architecture, not
a UI concern, so it does not belong in a component library. Same reasoning that
removed [`BbIntersection`](./bb-intersection.md).

## Replacement

Use **`useBroadcastChannel` from `@vueuse/core`**. It is better maintained, it
is the same shape, and it is already in your dependency tree — bitboss-ui
depends on `@vueuse/core` itself, so adopting it adds nothing to your install.

```diff
- import { useBroadcastChannelInstance } from 'bitboss-ui';
+ import { useBroadcastChannel } from '@vueuse/core';

- const { useBroadCastChannel } = useBroadcastChannelInstance<Messages>('sync');
- const { on, post, close } = useBroadCastChannel();
- on('record:updated', (params) => refresh(params));
- post('record:updated', { id });
+ const { data, post, close } = useBroadcastChannel({ name: 'sync' });
+ watch(data, (message) => { if (message?.type === 'record:updated') refresh(message.params); });
+ post({ type: 'record:updated', params: { id } });
```

## Two behaviours that do NOT carry over — check these

**1. Handler auto-removal on unmount.** Ours removed subscribers registered with
`on(...)` automatically via `onBeforeUnmount` (unless you passed
`removeonUnmount: false`). VueUse gives you a `data` ref instead, so the
"subscription" is whatever watcher you write — and a watcher created in `setup`
is already tied to the component scope. If you were relying on
`removeonUnmount: false` to keep a subscription alive past unmount, create the
watcher outside the component scope (e.g. in a store) instead.

**2. There was never any reference counting**, despite what the v2 guide said.
Each `useBroadCastChannel()` call opened its own channel and `close()` closed
only that one; an earlier shared-instance counter was removed because gating on
it leaked every non-last instance's channel. VueUse behaves the same way — one
channel per call — so if you wrote code around the documented (but fictional)
refcount, it was already not doing what you thought.

## Why not keep it

Every argument for keeping it was an argument about consumer convenience, and
none of them survived contact with the cost: in one review cycle this composable
produced a channel leak, an unclosed-channel finding, and the same false
refcount claim in its own documentation **twice**. That is three defects from a
composable that renders nothing and that no component in the library consumed.

---

<!-- dist/ai/guides/migration/components/use-confirm.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/components/use-confirm.md -->

# `confirm()` / `useConfirm` — v2 → v3

## Options

| v2                                                                                   | v3                                                                                          | Kind                                                                                                                                |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `yes?: boolean`, `yesText?: string`, `onYes?: () => …`                               | `yes?: false \| string \| ConfirmButtonConfig` (`{ text, variant, size, icon?, onClick? }`) | collapsed — **`yes: false` still hides the button, unchanged from v2.** Leave it alone; only `yesText`/`onYes` move into the config |
| `no?: boolean`, `noText?: string`, `onNo?: () => …`                                  | `no?: false \| string \| ConfirmButtonConfig`                                               | collapsed — same: **`no: false` is a no-op migration**, it hides the button exactly as in v2                                        |
| `actions?: boolean`                                                                  | `actions?: false \| ConfirmButtonConfig[]`                                                  | `false` hides the footer; an array replaces the yes/no pair with custom buttons                                                     |
| default labels `"OK"` / `"Annulla"` (hard-coded)                                     | localized via the active `locale`                                                           | **⚠ silent** — English apps stop showing Italian "Annulla"; apps that _wanted_ the literals must pass them                          |
| footer buttons `lg`                                                                  | footer buttons default `md`                                                                 | visual                                                                                                                              |
| `size`                                                                               | `size?: keyof DialogSizes` — forwards to `BbDialog`                                         | see the dialog width change in [main guide §2](../v2-to-v3.md)                                                                      |
| `theme?: string`                                                                     | `variant?: ConfirmVariantType` (built-ins `default`, `destructive`)                         | typed rename — unregistered names are a compile error; add yours via the plugin's `confirmVariants`                                 |
| `timeout?: number`                                                                   | `duration?: number`                                                                         | rename — auto-dismisses, resolves `false` quietly (no `no.onClick`), and implicitly forces `autoClose: true`                        |
| `autoClose?: boolean` — **opt-in**, omitted means the dialog stays open              | `autoClose?: boolean` — **default `true`**                                                  | **⚠ silent behavior flip** — a v2 multi-step flow that kept the dialog open after resolve must now pass `autoClose: false`          |
| `hideHeader?: boolean` (a union that made `title` required when `false`)             | removed — `title` is plain optional; omit it and no header renders                          | removed                                                                                                                             |
| `useConfirm().setLoading(value)`                                                     | removed — busy state is driven by the button's `onClick` promise                            | removed — `useConfirm()` now returns `{ confirm, close, dismissAll }`                                                               |
| —                                                                                    | `hideClose`, `portal` / `portalProps` (mutually exclusive with `text`)                      | additive                                                                                                                            |
| second `confirm()` while one is open: first promise **never settled** (hung forever) | the superseded promise resolves `false` (implicit dismiss, no callbacks)                    | **⚠ behavioral** (bugfix 2026-07-18; the replace-not-queue semantics are unchanged)                                                 |

`title`, `text`, and the returned promise semantics otherwise carry over.
`autoClose` does **not** — see its row above.

Grep for the collapsed keys: `rg -n 'yesText|noText|onYes|onNo|hideHeader|setLoading|autoClose|timeout' --type ts --type js --type vue`.
TypeScript catches all of them (excess-property checks on the options literal,
a hard property error on `setLoading`); a JS app gets no signal at all.

## Edits

```diff
- const ok = await confirm({
-   title: 'Delete record?',
-   yesText: 'Delete',
-   onYes: destroy,
-   noText: 'Keep',
- });
+ const ok = await confirm({
+   title: 'Delete record?',
+   variant: 'destructive',
+   yes: { text: 'Delete', variant: 'destructive', onClick: destroy },
+   no: 'Keep',
+ });

  <!-- hide ONE button -->
- confirm({ title: '…', yes: false })       // v2 boolean
+ confirm({ title: '…', yes: false })       // unchanged — still hides just the OK button

  <!-- hide the footer entirely -->
- confirm({ title: '…', actions: false })   // v2 boolean
+ confirm({ title: '…', actions: false })   // unchanged — but true is no longer meaningful; omit it
```

**Do not "migrate" `yes: false` to `actions: false`.** They are different:
`yes: false` drops the positive button and keeps the negative one, `actions: false`
drops the whole footer. Both spellings survive v2 → v3 untouched.

If you only ever called `confirm('Are you sure?')`, nothing changes except the
(localized) button labels and their size.

## CSS hooks

| v2                                          | v3                                                                                    |
| ------------------------------------------- | ------------------------------------------------------------------------------------- |
| `.bb-confirm__content`, `.bb-confirm__text` | unchanged — still the right targets for the body copy                                 |
| `.bb-confirm__no` / `.bb-confirm__yes`      | **gone** — the footer buttons render as bare `BbButton`s with no confirm class        |
| `.bb-confirm .bb-base-dialog__*`            | `.bb-confirm .bb-dialog__*` — plus `.bb-offcanvas__*`, the adaptive sheet's parts     |
| —                                           | `.bb-confirm--<variant>` on the dialog root — the lever for per-variant confirm skins |

`.bb-confirm__text` survives, so a v2 rule targeting the body copy still lands;
do not relocate it onto `.bb-dialog__body`.

The cancel button is the one that lost its hook. Restyle it per call instead of
in CSS — v3 defaults it to `size: 'md', variant: 'outline'`, and the Yes button
to `primary` (or `destructive` when the confirm `variant` is `destructive`):

```diff
- .bb-confirm .bb-base-dialog__footer .bb-confirm__no:hover:not(:disabled) {
-   --color: var(--bb-primary);
- }
+ confirm({ title: '…', no: { text: 'Keep', variant: 'ghost' } });
```

For a whole-skin change, register a confirm variant and hang the rules off
`.bb-confirm--<name>` rather than reaching for the old element classes.

---

<!-- dist/ai/guides/migration/v2-to-v3.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/migration/v2-to-v3.md -->

# Migrating from bitboss-ui 2.x to 3.0

v3 is a single coordinated break: the library moved from a plain component
package to a **build-plugin + runtime-plugin architecture**, replaced the
free-form `theme`/`color` styling props with **typed variant registries**,
overhauled the design-token system, and flipped a family of boolean props to
a consistent **opt-in polarity** (props default `false`; `disable*`/`hide-*`
turn a default behavior off).

This guide covers everything cross-cutting. Component-specific breaks live in
the per-component guides under [`migration/components/`](./components/) —
only components with **functional** changes have one; if a component has no
guide there, nothing about it needs migration.

**Which version to migrate to.** v3 is still a prerelease, so install it by
dist-tag:

```bash
npm install bitboss-ui@beta
```

`@beta` is the current v3 channel. Do **not** pin an exact alpha: the alpha line
is frozen and several of its version numbers were tagged but never published, so
`npm install bitboss-ui@3.0.0-alpha.8` fails outright with `ETARGET`. And a bare
`npm install bitboss-ui` resolves to **v2** — `@latest` stays on the 2.x line
until v3 goes stable. Verify with `npm ls bitboss-ui` before you change a single
file; if it reports `2.x`, nothing below applies.

**How to read the tables:** every row is a hard break — old names are gone,
with no alias and no deprecation shim. Where the break is _silent_ (the app
compiles and runs but behaves differently), the row is marked **⚠ silent**;
these are the rows you cannot find by waiting for errors, so grep for them
explicitly (section 8).

## 0. Upgrade strategy — do it in this order

1. **Swap the setup** (section 1): install the build plugin and the runtime
   plugin. Nothing renders correctly until this is done.
2. **Move your config** (section 2): everything you passed to
   `useBbConfig().setConfig()` except `locale` now lives in the build-plugin
   options.
3. **Re-base your theme** (section 3): the token system changed names and
   defaults — including the primary color itself. Your brand theme must be
   re-declared before visual review makes any sense.
4. **Fix what the compiler finds** (sections 4–6): with typed templates
   (`vue-tsc`), renamed props, removed props, and unregistered variants all
   fail loudly. Fix them component by component with the per-component guides.
5. **Audit what the compiler cannot find** (section 8): untyped templates,
   `v-bind` objects, and behavioral flips are silent. Run the grep playbook.
6. **Convert class overrides to variants** (section 7): userland
   `class="bb-button--outline"`-style overrides keep _working_ but are now the
   wrong pattern — the variant prop exists, is typed, and is the only form the
   registry validates.

## 1. The plugin pattern

### What v2 looked like

v2 was a plain ESM library: named exports, one manual CSS import, optional
manual directive registration. There was no Vite plugin and no `app.use`.

Nuxt apps were the exception: they installed a **separate companion package**,
`@bitboss-dev/bitboss-ui-nuxt`, which wrapped v2 in a Nuxt module. v3 absorbs
that package — the module now ships inside the library as `bitboss-ui/nuxt`.
See [Nuxt](#nuxt) below for the option-by-option move.

```ts
// v2 main.ts
import { createApp } from 'vue';
import 'bitboss-ui/styles.css';
import {
	BbTooltipDirectivePlugin,
	BbDropdownDirectivePlugin,
} from 'bitboss-ui';

const app = createApp(App);
app.use(BbTooltipDirectivePlugin); // only if you used v-bb-tooltip
app.use(BbDropdownDirectivePlugin); // only if you used v-bb-dropdown
app.mount('#app');
```

### What v3 requires

Two pieces, both mandatory:

1. the **build plugin** — `bitboss-ui/vite` (or the `bitboss-ui/nuxt` module,
   which wraps it). It serves the virtual config/icon modules, scans your
   local SVG icons, and generates the typed variant registries;
2. the **runtime plugin** — `bitbossUiPlugin` via `app.use` (automatic in
   Nuxt). It injects the stylesheet, provides the icon registry, and registers
   the `v-bb-tooltip`, `v-bb-dropdown`, `v-bb-color`, `v-bb-date` and
   `v-bb-time` directives.

```ts
// v3 vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { bitbossUi } from 'bitboss-ui/vite';

export default defineConfig({
	plugins: [
		vue(),
		bitbossUi({
			iconDir: './src/assets/icons', // required — create the folder
		}),
	],
});
```

```ts
// v3 main.ts
import { createApp } from 'vue';
import { bitbossUiPlugin } from 'bitboss-ui';

const app = createApp(App);
app.use(bitbossUiPlugin);
app.mount('#app');
```

Migration deltas, one by one:

| v2                                                                         | v3                                                                                                                                                                                                                                        |
| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `import 'bitboss-ui/styles.css'` in the entry file                         | **Delete it.** The runtime plugin auto-injects styles (`injectStyles` defaults `true`). Keep a manual import only if you set `injectStyles: false` — see the Tailwind exception below.                                                    |
| No build plugin                                                            | **Add `bitbossUi({ iconDir })`** to `vite.config.ts` (or the `bitboss-ui/nuxt` module). The app does not build without it — components import the virtual config module.                                                                  |
| `app.use(BbTooltipDirectivePlugin)` / `app.use(BbDropdownDirectivePlugin)` | **Delete both.** `bitbossUiPlugin` registers `v-bb-tooltip` and `v-bb-dropdown` itself (opt out with `injectDirectives: false` if the names collide).                                                                                     |
| No reset stylesheet                                                        | Optional: `resetCss: true` or `import 'bitboss-ui/reset.css'`. Skip in Tailwind apps — Preflight already does this.                                                                                                                       |
| Icons registered by augmenting the `IconRegistry` type                     | **Gone** (the `IconRegistry` export no longer exists — see section 5). Drop `.svg` files into `iconDir` and reference them as `local:<name>`; provider icons (`lucide:*`, `mdi:*`, …) need the matching `@iconify-json/*` dev dependency. |
| A hand-rolled icon plugin doing `app.provide('icons', { … })`              | **Delete it** and move the art into `iconDir`. See the shadowing warning below — this one is silent.                                                                                                                                      |

### ⚠ silent — a hand-rolled `provide('icons', …)` is shadowed, not merged

`bitbossUiPlugin` provides the icon registry under two keys: a Symbol
(`bitboss-ui:icons`) and the legacy string key `'icons'` — the same key an app
icon plugin typically uses. `BbIcon` reads the **Symbol first**
(`inject(ICONS_INJECTION_KEY) ?? inject('icons')`), so once the library plugin
is installed your own `provide('icons', …)` map never wins. Any glyph that
existed only in that map stops resolving, and nothing warns. Move those SVGs
into `iconDir` and reference them as `local:<name>`.

App code that still calls `inject('icons')` now receives the **library's**
registry object, not yours. The string key is a one-release compatibility shim
— migrate those call sites off it or delete them.

### ⚠ Tailwind Preflight cannot load before the library when styles are injected

Auto-injection always puts the library sheet at the **top** of `<head>` — the
guaranteed order is reset → library styles → every other stylesheet, because
the injector inserts before the first existing `<style>` / `<link
rel="stylesheet">`. Preflight is an app sheet like any other, so it lands
_after_ the library and wins every specificity tie. There is no option to
inject later.

If your v2 app depended on the opposite order (the manual
`import 'bitboss-ui/styles.css'` placed after your Tailwind entry), keep the
manual import and turn injection off:

```ts
// vite.config.ts
bitbossUi({ iconDir: './src/assets/icons', injectStyles: false });
```

```ts
// main.ts — the order is yours again
import './app.css'; // your Tailwind entry (@import 'tailwindcss')
import 'bitboss-ui/styles.css'; // after Tailwind, so library rules win the ties
```

Leave `resetCss` at its `false` default here — Preflight already resets.
`injectStyles` controls only whether the library injects its own `<style>`;
nothing else about the plugin changes.

### Nuxt

v3 ships a module that does both halves — do **not** also call `app.use`:

```ts
// v3 nuxt.config.ts
export default defineNuxtConfig({
	modules: ['bitboss-ui/nuxt'],
	bitboss: {
		iconDir: './assets/icons',
	},
});
```

#### Coming from `@bitboss-dev/bitboss-ui-nuxt`

That package was the v2 Nuxt story. It is superseded: **uninstall it** and
delete it from `modules`. Everything it did is now inside `bitboss-ui/nuxt`,
under the same `bitboss` config key — so the migration is mostly renaming keys,
not rewriting setup.

| `@bitboss-dev/bitboss-ui-nuxt` option | v3 `bitboss-ui/nuxt`                                                                                                                                                    |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `icons.path`                          | `iconDir`. Same job, one level up.                                                                                                                                      |
| `icons.enabled: false`                | **Gone** — the icon pipeline is not optional in v3; components import the virtual icon module. Point `iconDir` at an empty folder if you ship no local art.             |
| `styles.enabled`                      | `injectStyles` (still defaults `true`).                                                                                                                                 |
| `styles.index`                        | **Gone**, and nothing replaces it — see the ordering note below.                                                                                                        |
| `link.name`                           | `nuxtLinkName` (still defaults `'NuxtLink'`).                                                                                                                           |
| `link.enabled: false`                 | **Gone.** The runtime plugin only registers the configured name when the app has not already claimed it, so there is nothing to switch off.                             |
| `components.enabled`                  | `autoImport` — see below. Note the **default flipped**: v2's module auto-imported components, v3 does not.                                                              |
| `components.validation: true`         | `autoImport: { validated: true }`, or explicit imports from `bitboss-ui/validated`. The wrappers moved into the library and gained `BbForm` + `useValidatedField`.      |
| `components.requiredAsterisk`         | `requiredAsterisk`, same meaning, one level up.                                                                                                                         |
| `composables`                         | Folded into `autoImport`. `useBroadcastChannelInstance`, `useQueue` and `useWizard` are **not exported by v3** — the module registered names the library no longer has. |
| `logLevel`                            | **Gone.** The v3 module has nothing to log at setup; build-plugin diagnostics go through Vite.                                                                          |

**⚠ silent — auto-imports are off by default.** The v2 module registered every
`Bb*` component with Nuxt, so templates used them with no import line. v3 does
not: an unmigrated template compiles, and each unresolved `<BbButton>` renders
as an empty unknown element with no error anywhere. Either add explicit imports,
or opt back in:

```ts
// v3 nuxt.config.ts — the closest equivalent of the v2 module's defaults
export default defineNuxtConfig({
	modules: ['bitboss-ui/nuxt'],
	bitboss: {
		iconDir: './assets/icons',
		autoImport: { validated: true }, // drop `validated` if you had no vee-validate
	},
});
```

Set `"vueCompilerOptions": { "checkUnknownComponents": true }` in `tsconfig.json`
before you start either way — it is what turns that silent empty element into a
`vue-tsc` error naming the file and line.

**Style ordering.** `styles.index` let you splice `bitboss-ui/styles.css`
anywhere in Nuxt's `css` array. v3 injects the sheet at runtime and always puts
it **first** in `<head>`, ahead of every other stylesheet — so your own CSS is
always later and always wins, which is the order `styles.index` was normally
used to obtain. If you need the opposite (library rules winning over yours),
raise specificity in your own sheet rather than reordering; if you genuinely
need the library sheet elsewhere in the cascade, set `injectStyles: false` and
import `bitboss-ui/styles.css` yourself at the position you want.

### Inertia

Inertia apps configure `bitboss-ui/vite` exactly like plain Vite, install
`@inertiajs/vue3` (now an optional peer), and add the runtime plugin inside
`createInertiaApp`:

```ts
createInertiaApp({
	setup({ el, App, props, plugin }) {
		createApp({ render: () => h(App, props) })
			.use(plugin)
			.use(bitbossUiPlugin)
			.mount(el);
	},
});
```

Full option reference:
[Installation & Plugin Setup](../installation-and-plugin-setup.md).

## 2. Runtime config moves into the build plugin

In v2 all configuration was runtime and mutable:

```ts
// v2 — anywhere, usually App.vue setup
import { useBbConfig } from 'bitboss-ui';

useBbConfig().setConfig({
	locale: 'en',
	inertiaLinkName: 'Link',
	mobileMaxWidth: 768,
	dialogDefaultSizes: { md: 700 },
});
```

In v3 `setConfig` accepts **only `locale`**. Every other key is a build-plugin
option — same names, set once in `vite.config.ts` / the `bitboss` Nuxt key:

```ts
// v3
bitbossUi({
	iconDir: './src/assets/icons',
	inertiaLinkName: 'Link',
	mobileMaxWidth: 768,
	dialogDefaultSizes: { md: 700 },
});

// runtime — locale only (e.g. reacting to a user preference)
useBbConfig().setConfig({ locale: 'en' });
```

**Under SSR, set the locale where the app is created.** The runtime config is
held **per Vue app** (3.0.0-beta.15), and SSR builds one app per request, so
this is per-visitor and correct on the first paint — which is what crawlers
index and what a JS-disabled reader keeps:

```ts
const app = createSSRApp(App);
app.use(bitbossUiPlugin, { locale: localeFor(request) });
```

`setConfig` still works for runtime switching. During a server render, call it
from a component's `setup` so it can resolve the current app; from module scope
there is no app to address, the write lands on the build-time defaults shared
by the whole process, and it warns in dev. (Before beta.15 the config was a
single process-global object, so a per-visitor locale was not possible at all —
if you carried a workaround for that, you can drop it.)

| v2 `setConfig` key                            | Where it goes in v3                                                            |
| --------------------------------------------- | ------------------------------------------------------------------------------ |
| `locale`                                      | stays runtime (`setConfig`) — the only survivor                                |
| `inertiaLinkName`, `nuxtLinkName`             | build-plugin option, same name                                                 |
| `linkActiveClass`, `linkExactActiveClass`     | build-plugin option, same name                                                 |
| `mobileMaxWidth`                              | build-plugin option, same name                                                 |
| `dialogDefaultSizes`, `offCanvasDefaultSizes` | build-plugin option, same name — **but the default values changed, see below** |
| `documentationURL`                            | removed — no v3 equivalent                                                     |

**⚠ silent — the size maps changed shape and values.** v2 defaulted
`{ sm: 384, md: 652, lg: 896 }`; v3 defaults
`{ xs: 320, sm: 384, md: 448, lg: 512, xl: 576, '2xl': 672 }`. A
`<BbDialog size="md">` that was 652px wide in v2 renders **448px** in v3
without any error. If your app relied on the v2 widths, pin them explicitly:

```ts
bitbossUi({
	iconDir: '…',
	dialogDefaultSizes: { md: 652, lg: 896 },
	offCanvasDefaultSizes: { md: 652, lg: 896 },
});
```

v3 also adds config that v2 didn't have — notably `adaptive` (default `true`:
dialogs/popovers/dropdowns/selects open as a bottom sheet on mobile),
`defaultInputLabelMode`, `toastPosition`, `iconDefaultSizes`. `adaptive`
defaulting **on** is itself a behavior change for surfaces on small viewports;
set `adaptive: false` at the plugin level to keep v2-like floating behavior
everywhere, or per component with the `adaptive` prop.

## 3. Design tokens and theming

The token architecture was rebuilt (full doctrine:
[Design Tokens](../design-tokens.md)). What it means for a migrating theme:

### The triple is gone

v2 themed through `--x-light` / `--x-dark` / `--x` triples plus dozens of
global per-component variables in `:root`. v3 has **one name per token** and
two tiers:

- **`--bb-*` theme tokens** — the public theming surface, declared only in
  the library's `variables.css`. You override these.
- **unprefixed component tokens** (`--indent`, `--track`, …) — scoped to each
  component's root class. You override them _on the component's class_, not
  globally.

Dark mode is no longer a parallel token set: `.dark` re-declares only the
knobs that change, and derived tokens follow automatically. Delete every
`--x-light`/`--x-dark` override; re-express as `.light { … }` / `.dark { … }`
blocks. Note: overriding a knob on an arbitrary selector does **not**
re-derive dependent tokens — re-apply the `.light`/`.dark` block on that
scope instead.

### ⚠ silent — two visual defaults changed

- `--bb-primary` is now **black** (`rgb(0 0 0)`), not v2's blue
  (`rgb(37, 29, 255)`). If you never overrode the primary because the blue
  suited you, your whole app changes color on upgrade. Set your brand color
  explicitly.
- `--bb-radius` went `4px` → `8px`.

Six more tokens changed value **without changing name**, so they are invisible
to the rename map and to every grep below — see
["Tokens that kept their name but changed"](#tokens-that-kept-their-name-but-changed).

### Token rename map

| v2 override                                                                                                                                                            | v3 replacement                                                                                                                                                                                                                                                                                                                                             |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--bb-primary-base`                                                                                                                                                    | deleted — set `--bb-primary` directly                                                                                                                                                                                                                                                                                                                      |
| `--bb-contrasting` / `--bb-contrasting-dark`                                                                                                                           | `--bb-primary-fg`                                                                                                                                                                                                                                                                                                                                          |
| `--bb-panel-disabled`, `--bb-input-bg-secondary`                                                                                                                       | `--bb-muted`                                                                                                                                                                                                                                                                                                                                               |
| `--bb-hint`, `--bb-icon-color`, `--bb-placeholder`, `--bb-prefix-color`, `--bb-muted-color`                                                                            | `--bb-text-muted`                                                                                                                                                                                                                                                                                                                                          |
| `--bb-input-color`, `--bb-input-bg`                                                                                                                                    | `--bb-text`, `--bb-panel`                                                                                                                                                                                                                                                                                                                                  |
| `--bb-input-font-size`, `--bb-input-mobile-font-size`                                                                                                                  | `--bb-input-fs`, `--bb-input-fs-mobile`                                                                                                                                                                                                                                                                                                                    |
| `--bb-label-size`                                                                                                                                                      | `--bb-label-fs`                                                                                                                                                                                                                                                                                                                                            |
| `--bb-label-compact-spacing-y`                                                                                                                                         | `--bb-label-spacing-y-compact`                                                                                                                                                                                                                                                                                                                             |
| `--bb-input-compact-h`, `--bb-input-compact-py`                                                                                                                        | `--bb-input-h-compact`, `--bb-input-py-compact` — the `compact` qualifier moved from infix to suffix                                                                                                                                                                                                                                                       |
| `--bb-input-compact-px`, `--bb-input-compact-prefix-w`, `--bb-input-compact-floating-py`, `--bb-input-prefix`, `--bb-input-prefix-px`                                  | **deleted, no counterpart.** v3's compact mode re-points only height and vertical padding (the two tokens in the row above); horizontal padding and the prefix column keep their normal-size values, and the prefix's own font-size/padding knobs are gone.                                                                                                |
| `--bb-overlay-color` + `--bb-overlay-opacity`                                                                                                                          | `--bb-overlay` (one color with alpha)                                                                                                                                                                                                                                                                                                                      |
| `--bb-overlay-z-index`                                                                                                                                                 | `--bb-z-overlay`                                                                                                                                                                                                                                                                                                                                           |
| _(no v2 equivalent)_                                                                                                                                                   | `--bb-ease` — new in v3. v2 hard-coded seven different `cubic-bezier()` curves and exposed no easing token, so there is nothing to rename; set `--bb-ease` once if you want a house curve.                                                                                                                                                                 |
| `--bb-dialog-px`, `--bb-dialog-py`                                                                                                                                     | the local pair `--px` / `--py` on `.bb-dialog` / `.bb-offcanvas` — a direct map, set on the component's class (never `:root`). Both branch off `--bb-panel-p`, so if your v2 px = py, set `--bb-panel-p` alone. See "Asymmetric surface padding" below.                                                                                                    |
| `--bb-dialog-close`                                                                                                                                                    | **delete it** — do not map it onto `.bb-close-button { --size }`; v3's default already reproduces the v2 control. See below.                                                                                                                                                                                                                               |
| `--bb-dialog-title-size`                                                                                                                                               | the local `--dialog-title-fs` on `.bb-dialog` / `.bb-offcanvas` (default `calc(var(--bb-fs) + 2px)`)                                                                                                                                                                                                                                                       |
| `--bb-dialog-title-weight`                                                                                                                                             | **no knob** — the title is hardcoded `font-weight: 500`. Override with a CSS rule, see below.                                                                                                                                                                                                                                                              |
| `--bb-button-h`, `--bb-button-icon`, `--bb-checkbox-*`, `--bb-radio-*`, `--bb-switch-*`, `--bb-rating-*`, `--bb-slider-*`, `--bb-table-cell-h`, `--bb-select-option-*` | **no longer global.** Component dimensions hang off `--bb-control-h`, `--bb-fs`, `--bb-radius`; anything finer is an unprefixed local on the component's own class — with one exception: `--bb-select-option-px/-py` have **no** v3 local, the listbox option's inline padding is a literal (`.bb-listbox__option { padding-inline: … }` in your own CSS). |

**Most `--bb-input-*` and `--bb-label-*` tokens survive — but only these
exact names:** `--bb-input-h`, `--bb-input-px`, `--bb-input-py`,
`--bb-input-spacing`, `--bb-input-icon`, `--bb-input-prefix-w`,
`--bb-label-spacing-x`, `--bb-label-spacing-y`, `--bb-label-weight`,
`--bb-leading`. Those are still global v3 theme tokens, declared in
`variables.css` and read across the whole form family — do not delete them
(several changed default value; the drift table below lists which). Everything
else in the two families either renamed (`--bb-label-size` → `--bb-label-fs`,
the compact pair — rows above) or is deleted outright, so a declaration that
is not in this list and not in the rename map is inert: it looks correct and
does nothing. §8's retired-token grep catches every deleted name.

**When a v2 global becomes a component token, resize only what you use.** That
last row is the trap: a v2 global like `--bb-button-icon` had ONE value for
every button because v2 had no size scale. v3 does, so the same value now lives
in a per-size family (`--icon-size-xs … --icon-size-2xl`) that the size class
re-points. Two mistakes follow, and both were made on a real migration:

- Overriding the _active_ token (`.bb-button { --icon-size: 12px }`) appears to
  work on default buttons and silently does nothing on `size="sm"` ones — the
  size selector is more specific. Override the per-size entry instead.
- Reacting to that by setting the **whole family** to one value. That restores
  the v2 look exactly, and permanently opts the app out of v3's icon scale — an
  `xl` button gets a 12px glyph where the scale intends 20px.

Set only the sizes the app actually renders, scoped to the component's class
(never `:root` — `--icon-size` is also read by `BbBadge` and `CloseIcon`). Full
doctrine in `design-tokens.md` § "Overriding one from a consumer app". And check
first whether the v2 value was a real customisation: if it merely restated v2's
default, the migration is to **delete it** and inherit the v3 scale.

**Asymmetric surface padding.** v3 splits the axes with the local pair
`--px` / `--py`, declared on both surface roots (`.bb-dialog`,
`.bb-offcanvas`) and each branching off `var(--bb-panel-p)`. Like every
unprefixed component token, you override them _on the component's class_,
never `:root`. v2's `--bb-dialog-px` / `--bb-dialog-py` map onto them
directly:

```css
/* v2: --bb-dialog-px: 24px; --bb-dialog-py: 10px */
.my-dialog {
	--px: 24px; /* horizontal padding + the close button's inline inset */
	--py: 10px; /* vertical padding + the close button's block inset */
}
```

Setting only `--bb-panel-p` still moves both axes together (the pair defaults
to it, resolved on the component root, so a scoped `--bb-panel-p` override
keeps working too). Per-**part** asymmetry (header `py: 10px`, body
`py: 20px`) works by scoping the token to the part class — the padding rules
resolve it on the part elements and the pair inherits:

```css
.my-dialog .bb-dialog__header {
	--py: 10px; /* header block padding (bottom is py/2); × inset follows */
}
.my-dialog .bb-dialog__body-content {
	--py: 20px; /* body bottom padding, and its top in the headerless case */
}
```

Derived spacings scale with it — the header's bottom padding is `py / 2` and
the close button's block inset tracks the header's `py`. If you need exact
literals instead of those ratios, a `padding-block` rule on the part class
still works (use `padding-block`, not the `padding` shorthand, so the
horizontal half keeps tracking `--px`; the library part selectors are
at most (0,2,1) specific, so a three-class app selector beats them all).
`BbOffCanvas` is identical with `.bb-offcanvas__*` and the same `--px` /
`--py` names.

**Scope the pair to the surface, and it stays the surface's.** `--px` is also
a local on other components (`BbButton`, `BbAlert`, `BbTooltip`,
`BbBaseSlider`), but each of those re-declares it on its own root class, so a
dialog-scoped `--px` never leaks into the buttons or alerts inside the dialog
— and, symmetrically, never set the pair on `:root` or an arbitrary ancestor:
the surface roots' own defaults mask it there, and you would be reaching into
every other `--px`-reading component anyway. (`--pt` remains dead — nothing
reads it.)

If only the **vertical rhythm between parts** differs, the local `--dialog-gap`
(default `--py`) already does it without a padding rule: it drives the gap
below the body content and the footer's block padding on `.bb-dialog` and
`.bb-offcanvas`. It does **not** cover the header's top padding, or the body's
top padding in the headerless case — those still take `--py`.

**`--bb-dialog-close` maps to nothing — delete it.** In v2 it was the close
**icon** width (`12px`) and the button around it added `8px` of padding, so the
control was 28px. v3 inverts the relationship: `.bb-close-button { --size }` is
the whole control box and the icon is derived as `max(--size - 2 × --p, 10px)`.
Inside a dialog v3 already ships `--size: 28px; --p: 7px` (a 14px glyph) — the
same 28px control v2's default produced. Feeding v2's `12px` into `--size`
yields a **12×12px** control, well under the WCAG 2.5.8 minimum target size. If
you must match the old glyph exactly, widen the padding instead of shrinking
the box:

```css
/* 12px glyph, 28px control */
.my-dialog .bb-dialog__header > .bb-close-button {
	--p: 8px;
}
```

That selector needs at least three classes to beat the library's
`.bb-dialog .bb-dialog__header > .bb-close-button` (0,3,0).

**`--bb-dialog-title-weight` has no v3 home.** The title is `font-weight: 500`,
hardcoded. Restore v2's `600` with a rule that outweighs the library's
`.bb-dialog .bb-dialog__header .bb-dialog__title` (0,3,0):

```css
.my-dialog .bb-dialog__header .bb-dialog__title {
	font-weight: 600;
}
```

A complete v3 theme is typically two small blocks of ~10 declarations
(`--bb-primary`, `--bb-radius`, `--bb-control-h`, `--bb-panel`, `--bb-text`,
`--bb-border`, `--bb-danger`, …) — one in `:root, .light`, the changed knobs
again in `.dark`. If your v2 theme was long, most of it maps to "delete".

### Tokens that kept their name but changed

The rename map above is keyed by _the name you must change_. These tokens kept
their v2 name and stayed global, so they appear in no rename row and no grep
finds them — the only symptom is that the app renders differently.

**Values that drifted.** Same name, same meaning, new default:

| token                 | v2                                    | v3                                                                            |
| --------------------- | ------------------------------------- | ----------------------------------------------------------------------------- |
| `--bb-input-h`        | `36px`                                | `32px` (via `--bb-control-h`)                                                 |
| `--bb-input-py`       | `4px`                                 | `3px`                                                                         |
| `--bb-input-prefix-w` | `40px`                                | `20px`                                                                        |
| `--bb-label-weight`   | `400`                                 | `500`                                                                         |
| `--bb-ring-size`      | `4px`                                 | `2px`                                                                         |
| `--bb-leading`        | `24px` (`--bb-input-font-size` × 1.5) | `21px` (`--bb-input-fs` × 1.5, and `--bb-input-fs` is now `14px`, not `16px`) |

The consequence cuts both ways, which is what makes it easy to get wrong: an
app that **carried its v2 theme forward** keeps the v2 look (36px inputs, 4px
rings) and never sees v3's proportions; an app that **deleted its theme as
redundant** silently shifts to shorter inputs, half-width prefix columns and a
half-thickness focus ring. Re-check each of these six against the v3 default
and delete only the declarations that merely restated a **v2** default.

**A type that narrowed.** `--bb-ring-opacity` survives by name but v3 registers
it with `@property … syntax: '<percentage>'`:

| token               | v2 form                                                  | v3 form                          | symptom                                                                                                                                                                                                                                                                                    |
| ------------------- | -------------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--bb-ring-opacity` | unitless `0.25` / `0.4`, multiplied by `100%` internally | `25%` / `40%` — a `<percentage>` | ⚠ silent: a unitless override is invalid at computed-value time, so it is discarded and the token falls back to the registered `initial-value: 15%` — v3's own light default, so a light page silently renders the stock ring, while a dark page lands on `15%` against the shipped `40%`. |

Nothing reports this — not `vue-tsc`, not the eslint plugin, not
`npx bitboss-ui check` (none of them read CSS), and not the browser console:
an invalid registered-property value is not a parse error, so it logs nothing.
Grep your stylesheets for `--bb-ring-opacity` and check **both directions of
every hit**:

- every **write** must carry a `%` (`0.15` → `15%`), and
- every **read** must stop multiplying by `100%`. The v2 idiom for consuming
  the unitless form was exactly that —
  `calc(100% - var(--bb-ring-opacity) * 100%)` — and under v3 it multiplies a
  percentage by a percentage, which is invalid in `calc()`. The invalid math
  takes the whole declaration down (typically a `color-mix()` ring), so the
  failure is _worse_ than the write side: a stale write still produces a ring
  at the fallback strength, a stale read produces **no ring at all**, equally
  silently. Delete the `* 100%`.

Nine tokens are `@property`-registered in v3 — the eight color knobs
(`syntax: '<color>'`) plus `--bb-ring-opacity`. Each rejects values outside its
declared syntax the same silent way, so treat any future registration as the
same class of break.

### Button and variant skin colors moved the other way

The "no longer global" row sends per-component values _down_ into unprefixed
locals. The button **skin** colors went the opposite direction — up into global
theme tokens. In v2 a skin was four locals set on your own modifier class:

```css
/* v2 theming.css */
.bb-button--outline {
	--color: #fff;
	--border-color: #d1d5db;
	--text-color: #111827;
	/* hover / pressed / ring were derived from --color automatically */
}
```

v3 reads none of those — the old locals are inert, so a skin ported verbatim
silently reverts to the library defaults. Each variant has its own `--bb-*`
family, declared in `variables.css` and overridable globally or on any scope:

| v2 local on `.bb-button`                     | v3 token family (per variant)       |
| -------------------------------------------- | ----------------------------------- |
| `--color` (fill)                             | `--bb-<variant>`                    |
| `--text-color`                               | `--bb-<variant>-fg`                 |
| `--border-color`                             | `--bb-<variant>-border`             |
| `--ring-color`                               | `--bb-<variant>-ring`               |
| _derived_ `mix(--color 90%, black)` on hover | `--bb-<variant>-hover` (explicit)   |
| _derived_ `mix(--color 80%, black)` on press | `--bb-<variant>-pressed` (explicit) |

`<variant>` is one of `primary`, `secondary`, `outline`, `ghost`,
`destructive`, `link`. Note the last two rows: v2 _derived_ hover and pressed
from the fill, v3 states them. Porting only `--bb-outline` leaves the hover
state on the library's default.

```css
/* v3 equivalent of the block above */
:root {
	--bb-outline: #fff;
	--bb-outline-border: #d1d5db;
	--bb-outline-fg: #111827;
	--bb-outline-hover: #f3f4f6;
	--bb-outline-pressed: #e5e7eb;
}
```

## 4. Variants: from `theme` strings and class overrides to typed registries

### What changed

v2 components had **no `variant` prop**. Styling hooks were:

- the free-form `theme?: string` prop (generated an arbitrary class), and
- a free-form `color?: string` on the old badge,
- …which in practice meant userland applied the library's internal modifier
  classes directly: `<BbButton class="bb-button--outline">`.

v3 replaces all of that with per-component `variant` props whose types are
**locked to a registry** — built-in names plus whatever your build plugin
registers. An unregistered name is a **compile error** (v2's silent
render-unstyled behavior is gone by design), and the `theme` prop is gone.

**⚠ v2 shipped no variant CSS at all, so adopting a variant is additive.** Grep
the v2 stylesheet and the only `bb-button--*` rules are `group`, `icon` and
`loading`; there are no `bb-alert--*`, no appearance-level `bb-badge--*`, no
`bb-tooltip--*` and no `bb-toast-message--*` rules. v2's components _emitted_
those names (`bb-alert--${theme}`, `bb-tooltip--${theme}`,
`bb-toast-message--${theme}`) and the library never styled them. In v2 the
class and the `theme` string meant **"whatever your app's CSS says, and nothing
else."** In v3 every one of those names is a real skin, so converting hands the
library a styling role it did not have — wherever your CSS does not override
every property v3 sets (background, border, foreground, hover, pressed, focus
ring), the appearance drifts. Diff a screenshot; do not assume. Section 7
covers the class-to-prop rewrite itself.

Built-in sets and the class each name maps to:

| Plugin option          | Built-in variants                                                             | Class hook                          |
| ---------------------- | ----------------------------------------------------------------------------- | ----------------------------------- |
| `buttonVariants`       | `primary, outline, secondary, ghost, destructive, link` (+ `none` to opt out) | `bb-button--<name>`                 |
| `alertVariants`        | `outline, primary, destructive, warning`                                      | `bb-alert--<name>`                  |
| `badgeVariants`        | `primary, secondary, destructive, outline`                                    | `bb-badge--<name>`                  |
| `indicatorVariants`    | `default, success, info, warning, destructive`                                | `bb-indicator--<name>`              |
| `toastVariants`        | `default, success, info, warning, destructive`                                | `bb-toast-message--<name>`          |
| `confirmVariants`      | `default, destructive`                                                        | `bb-confirm--<name>`                |
| `dropdownItemVariants` | `default, destructive`                                                        | `bb-dropdown__item--variant-<name>` |
| `tooltipVariants`      | `default, destructive`                                                        | `bb-tooltip--<name>`                |

### Picking a v3 name for a v2 `theme` value

v2's `theme` was free-form, so most apps carry names that are not in the table
above (`error`, `danger`, `info`, `success`, `blue`, …). Work through it in
this order:

1. **Name is in the table, and your app never styled it** → use the built-in
   `variant`. This is the only genuinely free conversion.
2. **Name is in the table, but your app styled it itself** → v3's built-in now
   paints underneath your rules, and **registering the name does not stop it**.
   The registries feed the type-checker only: `alertVariants: ['warning']`
   regenerates the typed union and nothing else — no CSS is generated and none
   is suppressed; the built-in `.bb-alert--warning` skin ships unconditionally
   in `styles.css` and still applies, so every property your CSS does not
   explicitly set shows through as the library's. Decide explicitly: accept
   v3's look and delete your CSS, or keep your look — which requires your rules
   to **win the cascade** over the library's. Note the library's skin
   selectors are not uniform: some families compile single-class
   (`.bb-alert--warning`, `.bb-toast-message--*` — (0,1,0)), others
   block-scoped (`.bb-button.bb-button--outline`, `.bb-badge.bb-badge--*`,
   `.bb-indicator.bb-indicator--*`, `.bb-tooltip.bb-tooltip--*` — (0,2,0)).
   The pattern that wins everywhere: author your override at block+modifier
   (`.bb-alert.bb-alert--warning`, or nest the modifier under the block) **and**
   load your sheet after `styles.css` — that outweighs the single-class
   families and ties-then-wins-on-order against the block-scoped ones. Or
   sidestep the collision by renaming to a name not in the table, which moves
   you to case 3, where your CSS genuinely is the sole source. Whichever you pick,
   still register the name: that part is required for the type-check either
   way.
3. **Name is not in the table** → register it and keep your CSS. **Do not remap
   onto the "nearest" built-in.** `error → destructive`, `danger →
destructive`, `info → primary` all compile, all look plausible in review,
   and all silently replace your palette with the library's. Remap only as a
   deliberate redesign decision, never as a mechanical migration step.
4. **Name was never styled by anyone** → see the next subsection.

Registering is cheap — one array entry per name — and for a name **not** in
the table it is the behaviour-preserving default: the library has no rule for
an unknown name, so your CSS is the sole styling source. For a name that **is**
in the table, registering buys the type-check and nothing else — behaviour
preservation there is a cascade question (case 2 above). When unsure, prefer a
non-colliding name.

### ⚠ silent — a `theme` value that did nothing in v2 may do something in v3

Because v2 shipped no variant CSS, unless your app defined the rule the `theme`
prop was **inert**: every value rendered the same default surface. In v3 the
same string is a live skin, and whether it stays inert depends entirely on
whether the name happens to collide with a v3 built-in:

```
both of these rendered an identical plain alert in v2:

  <BbAlert theme="success" />   v3: not an alert built-in → compile error, you WILL notice
  <BbAlert theme="warning" />   v3: built-in → silently becomes an amber alert, you will NOT
```

So two identical-looking v2 call sites migrate to opposite outcomes. Before
converting any `theme=` value, check whether _anything_ styled it in v2 — your
stylesheet, since the library did not. If nothing did, the value was
decoration:

- register it as an empty custom variant (`alertVariants: ['success', 'blue']`)
  to hold v2's appearance exactly, or
- drop the prop entirely and let the v3 default apply, or
- convert it and accept the new look **on purpose**.

What you must not do is convert it mechanically and assume nothing moved.

### Custom variants are first-class

If your v2 app invented its own look (a `theme="brand"` or a hand-written
modifier class), register the name and ship its CSS:

```ts
// vite.config.ts
bitbossUi({
	iconDir: '…',
	buttonVariants: ['brand'],
	badgeVariants: ['soft-blue'],
});
```

```css
/* your CSS — the registered name is just a class hook */
.bb-button--brand {
	background: var(--bb-primary);
	/* … */
}
```

The plugin regenerates the typed union on build start, so `variant="brand"`
type-checks and autocompletes. A one-off that you refuse to register still
works with a visible cast (`variant="brand" as ButtonVariantType` won't
compile — cast the value, not the prop), but the registry is the intended
path.

**A name you keep as a plain class should not stay in the `bb-*` namespace.**
An app-minted `bb-button--pressed` or `bb-table--borderless` is squatting on
the library's prefix and collides the day the library ships that name. Either
register it as a variant, or rename it into your own prefix
(`app-button--pressed`). Section 7 has the decision table.

## 5. API-wide changes

These patterns repeat across many components. The per-component guides list
every occurrence; this section explains each pattern once.

### 5.1 Components renamed, split, or removed

| v2                                                                            | v3                                                                        | What to do                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BbBadge` (floating count/dot anchored to an element)                         | **`BbIndicator`**                                                         | `content` → `text`, `color` → `variant`, `floating` removed. New `max` prop renders `${max}+`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `BbChip`                                                                      | **removed** — use `BbBadge`                                               | v3 `BbBadge` is the inline pill/token: same `click:clear` event and `clearableLabel`, but `clearable` is now **opt-in** (v2 chips defaulted clearable).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| —                                                                             | **`BbBadge`** (repurposed)                                                | The v3 badge is a new component in an old name: inline label with `variant`, `icon`, `loading`, `clearable`. Any v2 `<BbBadge>` you have is an _indicator_ — rename it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `BbTab`                                                                       | **`BbTabs`**                                                              | Component and types renamed (`BbTabProps` → `BbTabsProps`; deprecated type aliases remain, the component name does not).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `Base*` internals (`BaseButton`, `BaseDialog`, `BaseCheckbox`, `BaseTag`, …)  | **`BbBase*`**                                                             | If you imported any base primitive or targeted its BEM block in CSS (`.base-btn` → `.bb-base-button`), rename. `BbBaseButton` is now a supported public export.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `BbCheckboxIcon` / `BbRadioIcon` / `BbSwitchIcon`                             | **`BbBaseCheckboxIcon`** / **`BbBaseRadioIcon`** / **`BbBaseSwitchIcon`** | Rename import + BEM block (`.bb-base-checkbox-container__icon` → `.bb-base-checkbox-icon`; see §5.6).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `BbBase*` input controls + `CommonInputWrapper` / `CommonInputOuterContainer` | **no longer exported** — use the full public component                    | v2 exposed the styled base inputs (`BbBaseTextInput`, `BbBaseSelect`, `BbBaseSwitch`, `BbBaseDatePickerInput`, …) and the input-chrome wrappers because a few full inputs were missing. v3 ships a full public component for every input, so these are internal now. Use `BbTextInput` / `BbSelect` / `BbSwitch` / … ; for a bare/inline control with no label gap, pass **`hideLabel`**. Still exported: `BbBaseButton` and the glyphs (`BbBaseCheckboxIcon` / `BbBaseRadioIcon` / `BbBaseSwitchIcon`).<br><br>**These primitives were also restructured, not just un-exported.** The outer+inner pair merged into one `CommonInputWrapper` (`.common-input-wrapper` / `__inner`), `BbBaseInputContainer` gained an inner `__layout` element that now carries the orientation modifiers, and `__input` became `__control`. Anything anchored to the old DOM — app CSS, test selectors, JS positioning a floating panel off `.bb-base-input-container__input` — fails silently: nothing throws, the element is simply never found. See §5.6.<br><br>**Built a custom control on the chrome?** If your app composed `BaseInputContainer` + `CommonInputOuterContainer` + `CommonInputInnerContainer` around an element the library does not ship (a highlight-overlay textarea, a field with a bespoke floating panel), there is no public v3 component to swap in — those wrappers exist in v3 but are internal. The sanctioned fallback is to **copy** the chrome into your app from the implementation source that ships with the package: `node_modules/bitboss-ui/dist/ai/source/BbBaseInputContainer.md` and `dist/ai/source/CommonInputWrapper.md` carry the complete `.vue` template, `types.ts` and `index.css` for each (89 components have one). Those files are banner-marked "Reference Only - Internal" — that bans _importing_ the internal component, not copying its template and CSS into a component of your own, which is the supported route here. The class names a copied template emits are styled by the public `bitboss-ui/styles.css`, so it inherits library chrome for free. Check first whether v3 already ships what you built — `BbTimePickerInput` and `BbTimePicker` are new in v3. |
| `useWizard` (+ `Step`, `WizardState`, `wizardInjectionKey`)                   | **removed**                                                               | No replacement — it was unused scaffolding. Copy the v2 implementation into your app if you depended on it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `BbIntersection` (+ `BbIntersectionProps` / `BbIntersectionEvents`)           | **removed**                                                               | No replacement — it wrapped `IntersectionObserver` in ~40 lines and carried no styling. Use `@vueuse/core`'s `useIntersectionObserver`, or copy the v2 component. Full mapping of the `shown`/`hidden`/`intersected` events and the slot props: [components/bb-intersection.md](./components/bb-intersection.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `useBroadcastChannelInstance`                                                 | **removed**                                                               | Same reasoning: a typed wrapper over a browser API, no markup, no styling, used by no component here. Cross-tab messaging is app architecture. Use `useBroadcastChannel` from `@vueuse/core` — already in your tree, since this library depends on it. **Two behaviours do not carry over** (handler auto-removal on unmount, and the refcount the v2 docs described but never had): [components/use-broadcast-channel-instance.md](./components/use-broadcast-channel-instance.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `BbRatio` (+ `BbRatioProps`, `.bb-ratio`)                                     | **removed**                                                               | No replacement — it was a one-rule wrapper. Use the `aspect-ratio` CSS property, or copy the v2 component.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `useQueue`, `useQuery`                                                        | **removed**                                                               | Both were public v2 exports and neither has a v3 equivalent; the import fails at build. Copy the v2 implementations out of the 2.1.135 tarball (`dist/composables/useQueue.d.ts`, `useQuery.d.ts`) into your app, or replace them with `@vueuse/core` equivalents.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `BbToastMessage` type export                                                  | **removed**                                                               | Use `BbToastOptions` (the `toast()` options shape).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `IconRegistry` / `IconNameFromRegistry` exports                               | **removed**                                                               | Icon names are plain strings now. Local art goes in `iconDir` as `local:<name>`; delete your `IconRegistry` augmentation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

### 5.2 The polarity wave: booleans now read as opt-in

v3 rule: **boolean props default `false` and their name states what turning
them on does.** Props that defaulted `true` were renamed to their inverse.
Consequence: if you passed the old prop with its default (`:show-close="true"`),
just delete it; if you passed the non-default (`:show-close="false"`), switch
to the new name (`hide-close`).

> **This is a per-component rename, not a find-and-replace.** Check the
> Component(s) column of the table below before rewriting a prop — a few
> components dropped the feature outright instead of inverting it, and there the
> correct migration is to **delete** the prop, not rename it. The one that bites:
> **neither `BbPopover` nor `BbTooltip` has a close button in v3**, so
> `show-close` (and `close-label` on the popover) are removed rather than
> renamed — `hide-close` on either is not a valid prop. `showClose` → `hideClose`
> applies to **`BbAlert`, `BbDialog` and `BbOffCanvas` only**. See §5.4 and the
> per-component files. `npx bitboss-ui check` catches both spellings if you slip.

| Component(s)                                       | v2 prop (default)                                         | v3 prop (default)                                                                                                                                                                                                               |
| -------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BbAlert`, `BbDialog`, `BbOffCanvas`               | `showClose` (`true`)                                      | `hideClose` (`false`) — also on `toast()` options, where v2 had `showClose` too and the same inversion applies (`showClose: false` → `hideClose: true`, `showClose: true` → delete). Genuinely **new** on `confirm()` options.  |
| `BbTable`                                          | `allowSelectAll` (`true`)                                 | `disableSelectAll` (`false`)                                                                                                                                                                                                    |
| `BbTabs`                                           | `animateX` / `animateY` (`true`)                          | `disableAnimateX` / `disableAnimateY` (`false`)                                                                                                                                                                                 |
| `BbButton`                                         | `autoLoading` (`false`)                                   | `disableAutoLoading` (`false`) — **⚠ silent behavior flip:** async `@click` handlers now show the loading spinner and disable the button automatically. Pass `disable-auto-loading` to keep v2 behavior.                        |
| `BbDropdownButton`                                 | `autoLoading` (`true`)                                    | `disableAutoLoading` (`false`)                                                                                                                                                                                                  |
| `BbDropdownButton`                                 | `disabledWhileLoading` (`true`)                           | **removed** — always disabled while loading now                                                                                                                                                                                 |
| `BbSlider`                                         | `thumbTranslate` (`true`)                                 | `disableThumbTranslate` (`false`)                                                                                                                                                                                               |
| `BbColorPalette`, `BbSelectPopover`                | `flip` (`true`)                                           | `disableFlip` (`false`)                                                                                                                                                                                                         |
| `BbSelect`, `BbSelectPopover`, `BbDatePickerInput` | `allowWriting` (`true`, tokens `boolean \| 'not-mobile'`) | `disableWriting` (`false`, tokens `boolean \| 'mobile' \| 'desktop'`) — `allow-writing="not-mobile"` becomes `disable-writing="mobile"`                                                                                         |
| `BbCheckbox`, `BbRadio`, `BbSwitch`                | `reverse` (`true`)                                        | `reverse` (`false`, **meaning inverted**) — unset renders identically, but explicit values flip: v2 `:reverse="false"` → v3 `reverse`; v2 `reverse` → delete. **⚠ silent** — see [bb-checkbox.md](./components/bb-checkbox.md). |
| `BbAlert`                                          | `ariaAtomic` (`true`)                                     | **removed** — correct live-region behavior is hardcoded                                                                                                                                                                         |
| `BbChip`                                           | `clearable` (`true`)                                      | **removed with the component** — `BbBadge.clearable` defaults `false`                                                                                                                                                           |

### 5.3 Straight renames

| Component                                          | v2                                | v3                                                                                                                                                                             |
| -------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `BbPagination`, `BbTabs`                           | `querykey`                        | `queryKey` — **⚠ silent**: a leftover `querykey` falls through to the DOM and the component uses the default key (`'page'` / `'tab'`), quietly moving your URL params.         |
| `BbTooltip`                                        | `timeout`                         | `delay`                                                                                                                                                                        |
| `toast()`, `confirm()` options                     | `timeout`                         | `duration` — same meaning (ms before auto-dismiss). `toast()` throws on `duration <= 0`; on `confirm()` it resolves the promise `false` quietly and implies `autoClose: true`. |
| `useToast()`                                       | `dismissAll()`                    | `dismiss()` with **no argument**. The v3 return shape is `{ toast, dismiss, update }`.                                                                                         |
| `BbIcon`                                           | `type` (required)                 | `icon`                                                                                                                                                                         |
| `BbColorPalette`, `BbColorInput`                   | `picker`                          | `eyeDropper`                                                                                                                                                                   |
| `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup` | `labelPosition`                   | `legendPosition`                                                                                                                                                               |
| `BbSelect`                                         | `prefill: 'focus'`                | `prefill: 'interaction'` (value rename; same default)                                                                                                                          |
| `BbToast` (host)                                   | `placement` (e.g. `bottom-start`) | `position` (corner set: `top-left` … `bottom-right`)                                                                                                                           |
| `BbAlert`, `BbTooltip`, `toast()`, `confirm()`     | `theme`                           | `variant` (typed — see section 4). On `confirm()` the v2 type was a free-form `theme?: string`; v3's is `ConfirmVariantType` (`default`, `destructive`).                       |

### 5.4 Removed props (no replacement needed — behavior became default or moved)

- **`theme` everywhere it existed** (`BbButton` family, `BbPopover`,
  `BbDropdownButton`, …): replaced by the variant system or simply gone.
  Reproduce one-off looks with a normal `class` plus your own CSS, or register
  a custom variant.
- **`color` everywhere**: gone from `BbAvatar`, `BbIcon`, `BbSpinner`,
  `BbCheckbox`, `BbRadio`, `BbSwitch`, `BbSlider`, `BbRating` and all three
  groups. Components inherit `currentColor` / theme tokens; style via CSS or
  the token knobs. `BbAvatar`'s knobs are named: set **both** `--bg-color` and
  `--text-color` on `.bb-avatar` (plus `--default-icon-color` for the built-in
  icon fallback) — setting only the background leaves the initials painted
  `--bb-primary-fg` on top of it.

  ```css
  .team-avatar .bb-avatar {
  	--bg-color: #7c3aed;
  	--text-color: #fff;
  }
  ```

- **`BbSelect`**: `showChevron` and `updateOnAnimationFrame` removed; the
  `#chevron` slot and the four `#options:prepend/append(:outer)` slots are
  gone (use the new `#header` / `#footer` panel slots). Same options-slot
  removal on `BbSelectPopover`.
- **Group option affix slots** (`#option:prepend` / `#option:append` on the
  checkbox/radio/switch groups): removed — decorate options through the
  scoped `#label` slot.
- **`BbDatePickerInput`**: `width` removed. **⚠ silent**: non-floating output
  now carries the local offset (`2026-01-01T00:00:00+01:00`) instead of UTC
  `Z` — same instant, different digits; the new `utc` prop restores the v2
  emission (reading accepts both forms either way). Details in the
  [component page](./components/bb-date-picker-input.md).
- **`BbTag`**: `multiple` removed (always an array input).
- **Built-in tooltip on `BbButton`** (`tooltip`, `tooltipPlacement`,
  `tooltipTimeout`): use the `v-bb-tooltip` directive or wrap in `BbTooltip`.
- **Arrow props on non-tooltip surfaces**: `hideArrow`
  (`BbPopover`/`BbSelectPopover`), `showArrow` (`BbColorPalette`) and
  `arrowPadding` are gone — arrows are a tooltip-only affordance now.
  **⚠ silent**: a stray `hide-arrow`/`show-arrow` lands in `$attrs`, nothing
  warns.
- **`BbPopover`**: `showClose`, `closeLabel`, `restoreFocus`, `block` removed —
  render your own close affordance in the content (`#default="{ close }"`).
- **`BbDialog`**: `description`, `hideHeader`, `compact`, `overlayClasses`,
  `panelClasses` removed (use the `header` slot and normal classes). The
  `#description` and `#close` **slots** are gone too — v3's slot set is
  `header | title | default | footer`, and a custom close control goes inside
  `#header`, which replaces the whole default header including the ✕ (so
  `hide-close` is not needed alongside it).
- **`BbOffCanvas`**: the same `description` prop and the same `#description` /
  `#close` slots were removed, with the same replacements. The
  `aria-describedby` wiring `description` used to provide is gone — put the
  copy in the default slot.
- **`BbBreadcrumbs`**: string `divider` removed (slot-driven now);
  `dividerWidth` default changed `5` → `16`.
- **`BbPagination`**: `loading` removed.
- **`BbCollapsible`**: `tag` removed.
- **Per-item `disabled` on option components**: item data no longer carries UI
  state — pass the `selectable` predicate
  (`boolean | ((item) => boolean)`) on `BbSelect`, `BbSelectPopover`,
  `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`. **⚠ silent**: a
  `disabled` field on an item object is plain data in v3; nothing warns.
  (`BbTabs` keeps its tab-level `item.disabled` — different feature.)

### 5.5 Types tightened (compile errors that are doing you a favor)

- **Variant props are registry-locked** (section 4): unknown strings fail
  `vue-tsc` instead of rendering unstyled.
- **`BbBreadcrumbs` item `key`: `string | number` → `string`** — wrap numeric
  keys in `String(...)`.
- **`checked` on `BbCheckbox`/`BbRadio`/`BbSwitch`: `boolean | 'true' | 'false'`
  → `boolean`** — the string forms no longer compile.
- **`size` unions**: responsive maps (`Responsive<…>`) accepted everywhere the
  concept applies; `BbButton` gains `'2xl'`; `BbIcon`'s `xxl` key is now
  `'2xl'`.
- **`itemText` / `itemValue`** unified on `ItemAccessor<T, R>` — top-level keys
  autocomplete, functions unchanged; deep dot-paths still work but are
  unchecked.
- **`BbTextInput.type`** narrowed to the text-like set
  (`text, email, url, tel, search, password`) — `type="number"` / `"date"`
  belong to `BbNumberInput` / `BbDatePickerInput`.
- **`filterBy`** (`BbSelect`, `BbSelectPopover`): `string[]` only — the
  function, `false`, `'not_stashed'` and single-string forms are gone; filter
  the items you pass instead.
- **Models**: `BbTag.modelValue` is `string[]`; `BbDropzone.modelValue` is
  `File | File[] | null`; `BbSlider.modelValue` drops its `string` member.
- **`direction`** on inputs: the exported `InputDirection` union — keyword
  typos now fail to compile; two-word ratio strings (`'1 2'`) still work.

### 5.5b Fields added to public object types

An **added** optional field breaks a consumer as hard as a removed one, and the
error text does not say so. If your app intersects a library object type to
carry its own metadata — `BbTableColumn & { sortable?: string }` for a backend
sort key, say — the intersection does not widen the property, it **collapses**
it: `string & undefined` is `undefined`, and every column literal then fails
with

```
error TS2322: Type 'string' is not assignable to type 'undefined'.
```

which names neither the field nor the library. That one line is worth
searching your build log for. The fix is to rename your field (`sortKey`) or to
subtract the library's first:
`Omit<BbTableColumn, 'sortable'> & { sortable?: string }`.

The collision-prone additions in v3:

| type              | added in v3                                               | hazard                                                                                                                                                                                                                                                                     |
| ----------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BbTableColumn`   | `sortable?: boolean`                                      | intersection collapse (above), **and** a behavior flip: v3 reads it as `!!column.sortable`, so a truthy sort-key string switches on the built-in header sort button. An app with its own sort UI then renders two. Strip the field at the `BbTable` boundary or rename it. |
| `BbTableColumn`   | `rowClass?: ColumnClasses<Item>`                          | same collapse. Note this is the **column-level** field — the table-level `rowClass` prop is separate and both accumulate.                                                                                                                                                  |
| `BbDropdown` item | `description?: string`                                    | collapse, plus it now renders as a second line on the item.                                                                                                                                                                                                                |
| `BbDropdown` item | `group?: never`, `selectable?: never`, `multiple?: never` | harder than a collapse: these discriminate item-from-group, so `group: 'admin'` on a plain item literal is a **direct** type error, no intersection required. Rename the field or nest your metadata under one custom key.                                                 |

Everything else added in v3 lands on `*Props` / `*Slots` / internal projections
— shapes you pass or read rather than intersect — so this list is deliberately
short.

### 5.6 Renamed CSS blocks

If app CSS or test selectors target library internals, these blocks moved. This
is the complete set — a class-by-class diff of the v2 stylesheet against v3
leaves nothing else orphaned. All of it is **silent**: a selector on a class
nobody emits matches nothing and throws nothing.

One caution when auditing on your own: absence from `styles.css` answers _"is
it styled"_, not _"is it emitted"_. Some classes carry no library rule but are
still rendered as styling hooks for you (`.bb-base-input-container__hint-text`
is one: its wrapper `__hint-wrap` carries the rules, the inner text node is
bare) — those are correct targets and correctly
absent from this table, which maps only classes that moved or died. Before
filing a class as removed, check the component's markup, not just the
stylesheet.

**Input chrome**

| v2                                                                                                                                | v3                                                                                                                                                                                                                                                                                                                                       |
| --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.bb-common-input-inner-container` (+ `--clearable`, `__prefix`, `__suffix`, `__prepend-icon`, `__append-icon`)                   | `.common-input-wrapper` (+ the same suffixes) — modifiers `--active --compact --disabled --errors --loading --readonly --clearable --warnings` (note: no `bb-` prefix)                                                                                                                                                                   |
| `.bb-common-input-outer-container`                                                                                                | merged away — the v2 outer/inner pair is one `.common-input-wrapper`, whose inner span is `.common-input-wrapper__inner`                                                                                                                                                                                                                 |
| `.bb-base-input-outer-container` (+ `--compact`)                                                                                  | merged into `.bb-base-input-container` (+ `--compact`)                                                                                                                                                                                                                                                                                   |
| `.bb-base-input-container__input` (+ `--left --center --right`)                                                                   | `.bb-base-input-container__control` (+ the same modifiers)                                                                                                                                                                                                                                                                               |
| `.bb-base-input-container--horizontal` / `--vertical` / `--reverse` (on the root)                                                 | `.bb-base-input-container__layout--horizontal` / `--vertical` / `--reverse` — v3 inserts an inner `__layout` element and the orientation modifiers moved onto it; the root keeps only state modifiers (`--disabled --errors --warnings --loading --readonly --compact --floating-label --inside-label` …)                                |
| `.bb-base-input-container--label-mode-floating`                                                                                   | `.bb-base-input-container--floating-label`                                                                                                                                                                                                                                                                                               |
| `.bb-base-input-container__errors-outer`                                                                                          | `.bb-base-input-container__errors-wrap`                                                                                                                                                                                                                                                                                                  |
| `.bb-base-input-container__hint-container`                                                                                        | `.bb-base-input-container__hint-wrap`                                                                                                                                                                                                                                                                                                    |
| `.base-btn`, `.base-btn--block`, …                                                                                                | `.bb-base-button*`                                                                                                                                                                                                                                                                                                                       |
| `.bb-base-checkbox-container` / `.bb-base-radio-container` / `.bb-base-switch-container`                                          | `.bb-base-checkbox` / `.bb-base-radio` / `.bb-base-switch` (the `--disabled` modifier survives)                                                                                                                                                                                                                                          |
| `.bb-base-checkbox-container__icon` / `.bb-base-radio-container__icon` / `.bb-base-switch-container__icon` (+ `__icon-thumb`)     | `.bb-base-checkbox-icon` / `.bb-base-radio-icon` / `.bb-base-switch-icon` (+ `.bb-base-switch-icon__thumb`)                                                                                                                                                                                                                              |
| `.bb-cr-container*` — the shared checkbox/radio/switch group tree (root, `--vertical`, `__container`, `-option`, `-option__text`) | split into per-control blocks: `.bb-base-checkbox-group*` / `.bb-base-radio-group*` / `.bb-base-switch-group*`, same suffixes (`--warnings`, `__loading-container`, `__no-data-container`, `-option--selected` are new). **`BbRating` no longer shares the block** — use `.bb-base-rating__inner-container` / `.bb-base-rating__option`. |

**Dialogs, off-canvas, popovers**

| v2                                                                                                          | v3                                                                                                                                                                                                                                                                                                    |
| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.bb-base-dialog` (+ `--deny-close --fullscreen --open`, `__header __title __body __body-content __footer`) | `.bb-dialog` / `.bb-dialog__*` — 1:1 on every one of those                                                                                                                                                                                                                                            |
| `.bb-base-dialog__close` / `__close-icon`, `.bb-offcanvas__close` / `__close-icon`, `.bb-popover__close`    | `.bb-close-button` — one shared button, used by the dialog, the off-canvas and the popover alike                                                                                                                                                                                                      |
| `.bb-common-popover--scrollable`                                                                            | `.bb-popover__panel--scrollable` (the rest of `.bb-common-popover*` is unchanged)                                                                                                                                                                                                                     |
| `.bb-confirm__no`                                                                                           | **removed** — the cancel button is a plain `BbButton` with no class of its own. Restyle it through `no: { variant: … }` on the call, or through the root's `.bb-confirm--<variant>` modifier. `.bb-confirm__text` and `.bb-confirm__content` are unchanged and still the right targets for body copy. |

**Tabs** — the whole tree was renamed, and v2's block name was `bb-tab`, not
`bb-tabs`, so nothing of a v2 tab theme survives untouched:

| v2                                               | v3                                                                                                                                                                                                                                           |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.bb-tab`                                        | `.bb-tabs`                                                                                                                                                                                                                                   |
| `.bb-tab--vertical` / `--horizontal`             | `.bb-tabs--vertical` / `--horizontal` (+ `.bb-tabs-list--vertical` / `--horizontal` on the strip)                                                                                                                                            |
| `.bb-tab__label-boundary`                        | `.bb-tabs-list`                                                                                                                                                                                                                              |
| `.bb-tab__label-container` (+ `--no-transition`) | `.bb-tabs-list__tablist` (+ `--no-transition`) — the sliding active pill is still this element's `::before`, so a v2 `.bb-tab__label-boundary .bb-tab__label-container:before` rule becomes the single-class `.bb-tabs-list__tablist:before` |
| `.bb-tab__btn` (+ `--active`)                    | `.bb-tabs__trigger` (+ `--active`), with new inner `.bb-tabs__trigger-content` / `.bb-tabs__trigger-label`                                                                                                                                   |
| `.bb-tab__pane` (+ `--shown`)                    | `.bb-tabs__pane` (+ `--shown`)                                                                                                                                                                                                               |
| `.bb-tab__panes-container`                       | `.bb-tabs-panes`                                                                                                                                                                                                                             |

v2 had no full-width tab strip, so apps hand-rolled one (commonly a
`bb-tabs--full-width` class). v3 ships it: `<BbTabs block>` sets
`.bb-tabs--block` / `.bb-tabs-list--block` and gives the triggers equal widths.
Delete the hand-rolled modifier rather than porting it.

**BbTable** — no class was renamed, but the markup under `.bb-table` is no
longer a `<table>`: it is a CSS grid of `<div>`s carrying ARIA roles. Every
**element** selector on it (`table`, `thead`, `tbody`, `tfoot`, `caption`,
`tr`, `th`, `td`, `colgroup`/`col`) matches nothing in v3 — silently. The
classes all survive; four containers and the roles are the translation:

| v2 element                            | v3 selector                                                                                  |
| ------------------------------------- | -------------------------------------------------------------------------------------------- |
| `table` / `thead` / `tbody` / `tfoot` | `.bb-table__table` / `.bb-table__head` / `.bb-table__body` / `.bb-table__foot`               |
| `caption`                             | `.bb-table-caption`                                                                          |
| `tr` / `th` / `td`                    | `[role=row]` / `[role=columnheader]` / `[role=cell]` (or the `.bb-table-*` row/cell classes) |
| `colgroup` / `col`                    | gone — `columns[].width`                                                                     |

Full table, the `.table-flush` idiom rewrite, the `#thead`/`#tbody`/`#tfoot`
markup contract and the layout drift that comes with the substrate:
[bb-table.md](./components/bb-table.md#the-table-is-a-css-grid-not-a-table-v3-beta-2026-08-26).

**Everything else**

| v2                                                                                                                                                                                                                                            | v3                                                                                                                                                                                                                            |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.bb-chip*`                                                                                                                                                                                                                                   | `.bb-badge*` (component replaced)                                                                                                                                                                                             |
| `.bb-badge*` used as a floating count/dot (`--dot --floating --positioned --left --bottom --empty`, `__wrapper`, `__content-container`)                                                                                                       | `.bb-indicator*` (component renamed)                                                                                                                                                                                          |
| `.bb-color-palette__*` (canvas, canvas-thumb, canvas-wrap, controls, eyedropper, preview, preview--alpha, preview-wrap, slider-thumb, slider-track, slider-wrap, slider-wrap--alpha, sliders, swatch, swatch--active, swatch-group, swatches) | `.bb-base-color-palette__*` — 1:1 on every one                                                                                                                                                                                |
| `.bb-toast--top-start` / `--top` / `--top-end` / `--bottom-start` / `--bottom` / `--bottom-end`                                                                                                                                               | `.bb-toast--top-left` / `--top-center` / `--top-right` / `--bottom-left` / `--bottom-center` / `--bottom-right` (matching the `position` prop's corner set)                                                                   |
| `.bb-toast-message__icon-container`                                                                                                                                                                                                           | **removed** — style `.bb-toast-message__icon` directly                                                                                                                                                                        |
| `.bb-tree--open`                                                                                                                                                                                                                              | `.bb-tree__node--expanded`                                                                                                                                                                                                    |
| `.bb-tree-row`                                                                                                                                                                                                                                | `.bb-tree__row`                                                                                                                                                                                                               |
| `.bb-tree-main-content`                                                                                                                                                                                                                       | `.bb-tree__content`                                                                                                                                                                                                           |
| `.bb-dropdown-button__dropdown-chevron`                                                                                                                                                                                                       | `.bb-dropdown-button__chevron`                                                                                                                                                                                                |
| `.bb-dropdown-button--loading` / `__content` / `__icon` / `__prepend-icon` / `__append-icon`                                                                                                                                                  | **removed** — the split button delegates to `BbButton`'s internals; target `.bb-button__*` inside it                                                                                                                          |
| `.bb-dropdown__wrapper`                                                                                                                                                                                                                       | **removed** — the extra wrapper element is gone                                                                                                                                                                               |
| `.bb-select-popover__search-spinner`                                                                                                                                                                                                          | `.bb-select-popover__search-icon` (one element, spinner state included)                                                                                                                                                       |
| `.bb-base-date-picker__header` (the tinted banner holding the month/year controls)                                                                                                                                                            | `.bb-base-date-picker__controls` (+ the inner `__nav-center`) — the banner is gone; the controls sit on the calendar surface. `__header-container` and `__header-cell` are unrelated and unchanged: they are the weekday row. |
| `.bb-base-date-picker__control` / `__year-control`                                                                                                                                                                                            | `.bb-base-date-picker__nav-btn`                                                                                                                                                                                               |
| `.bb-base-date-picker__month-button` / `__year-button`                                                                                                                                                                                        | `.bb-base-date-picker__heading-btn` (+ `--active`)                                                                                                                                                                            |
| `.bb-base-date-picker__weekday`                                                                                                                                                                                                               | `.bb-base-date-picker__header-cell`                                                                                                                                                                                           |
| `.bb-base-date-picker__monthday`                                                                                                                                                                                                              | `.bb-base-date-picker__date` (+ the inner `__date-button`)                                                                                                                                                                    |
| `.bb-base-date-picker__year-container`                                                                                                                                                                                                        | `.bb-base-date-picker__year-selector`                                                                                                                                                                                         |
| `.bb-base-date-picker__header--hidden`, `__selected-day-label`                                                                                                                                                                                | **removed**                                                                                                                                                                                                                   |
| `.bb-commabox-item--has-comma`                                                                                                                                                                                                                | the select's comma list renders `.bb-base-select__comma-item` (`.bb-commabox-item` itself survives; `--has-comma` and `.bb-chipsbox-item--focused` do not)                                                                    |

The date **input**'s own field tree (`.bb-base-date-picker-input__field`,
`__fields`, `__placeholder`, `__separator`, `__calendar-btn`) moved to a shared
`.bb-segmented-field__*` block — full table in
[bb-date-picker-input.md](./components/bb-date-picker-input.md).

**Removed with no counterpart:** `.bb-base-dialog--compact`,
`.bb-offcanvas--compact`, `.bb-base-textarea--compact` (compact now lives on
`.common-input-wrapper--compact`), `.bb-base-select--active` / `--compact` /
`__inner-wrapper` / `__input-container` / `__text-input` (the select activator
was rebuilt — nearest hooks are `.bb-base-select__activator`, `__value`,
`__display-value`; `--shown` survives. `__text-input` was v2's combobox typing
field inside the activator; v3's activator is a `type="button"` overlay with no
typable field, and typing moved into the panel's
`.bb-select-popover__search-input` — restyle that instead, knowing it now sits
in the popover, not the field), `.bb-base-rating__option--highlighted` (v3 uses
`--filled` / `--empty`), `.bb-progress--horizontal` (`.bb-progress` /
`.bb-progress-bar` are the blocks), `.bb-ratio` (component removed).

### 5.7 Renamed custom properties the library WRITES

Section 3 covers the tokens you set. These are variables the library **writes
onto the DOM** at runtime for you to read — the usual reason to touch them is
nested-table column alignment. They all dropped the `bb-` prefix, and every one
of them is consumed through `var(name, fallback)`, so a v2 name silently
resolves to the fallback instead of failing.

| v2                                                    | v3                                                                                        |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `--bb-table-{id}-track-{key}`                         | `--table-{id}-track-{key}`                                                                |
| `--bb-table-offset-start` / `-end`                    | `--offset-start` / `--offset-end`                                                         |
| `--bb-table-offset-internal-start` / `-end`           | `--offset-internal-start` / `--offset-internal-end`                                       |
| `--bb-table-fill`                                     | **removed in 3.0.0** (briefly `--fill` in the betas; the grid substrate has no fill loop) |
| `--bb-table-natural-width`                            | **removed in 3.0.0** (briefly `--natural-width` in the betas)                             |
| `--bb-select-popover-width` (on `.bb-select-popover`) | `--w` — and the supported path is now the `width` prop, not a CSS override                |
| `--bb-icon-dimensions-w` (on `.bb-icon`)              | `--w`                                                                                     |
| `--bb-breadcrumbs-flex-basis` / `-flex-grow`          | `--flex-basis` / `--flex-grow`                                                            |
| `--bb-picker-preview-color`                           | `--picker-preview-color`                                                                  |

A regex matching the old shape (`/--bb-table-[\w-]+-track/`) matches nothing in
v3. Search your app for `--bb-table-`, `--bb-select-popover-`,
`--bb-icon-dimensions-`, `--bb-breadcrumbs-` and `--bb-picker-` — none of those
names exist in v3 and all of them fail quietly. `--available-height`,
`--inner-width`, `--overlay-min-height`, `--bb-table-fill` and
`--bb-table-natural-width` were dropped outright — the last two because
`BbTable` is a CSS grid in 3.0.0 and the fixed-layout self-correction they fed
no longer exists (see
[bb-table.md](./components/bb-table.md#--fill-and---natural-width-are-removed-not-renamed)).

If you re-published track variables by hand to align a deeply nested table,
delete that code: `inherit-column-widths` takes a **table id**
(`inherit-column-widths="<ancestor-id>"`), not just `true`, and walks the whole
ancestor chain — it is not limited to the immediate parent.

## 6. Behavior changes you will feel at runtime

Nothing here fails to compile — these change what existing code does.

1. **`BbButton` tracks async click handlers by default.** An `async @click`
   now disables the button and shows a spinner until it settles. Opt out per
   button with `disable-auto-loading`.
2. **Single-select no longer clears on a second click**
   (`BbSelect`, `BbSelectPopover`): re-clicking the selected option re-picks
   and closes; it used to emit `null` and empty the field. If your UX relied on
   click-to-clear, add `clearable` (or the `clear` slot callback). Multiple
   mode still toggles.
3. **`enforce-coherence` prunes on mount.** A seeded-but-invalid model value is
   now cleared on the first load, not on the next change. If "my value clears
   on load" appears after upgrading, your provider isn't resolving the current
   selection on `prefill === true` calls — honor that contract or enable
   `stash`.
4. **Array `items` are never lazy**: they resolve on mount regardless of
   `prefill`, so activator `text` is reliable from first paint.
   And **`prefill: false` is search-first** on provider-backed selects: nothing
   fetches until the user types (the panel shows a "search to begin" hint). A
   v2 `prefill: false` select fetched on first open — if that's what you
   wanted, delete the prop; load-on-open is the default. Details in
   [bb-select.md](./components/bb-select.md).
5. **A loading `BbTable` with rows keeps them visible** (dimmed, with a
   progress bar) instead of flashing to skeleton — and the rows and header go
   `inert` during the refetch. Escape hatch: `interactive-while-loading`. The
   `#loading` slot fires on the **first load only** now.
6. **A truthy column `sortable` switches on v3's own sort UI.** `BbTable` reads
   the field as `!!column.sortable`, so a column carrying a backend sort key
   (`sortable: 'created_at'`) renders the built-in header sort button and sets
   `aria-sort` — an app with its own sort control then shows two. Sorting stays
   a controlled model (`v-model:sort`), so nothing reorders on its own; the
   button appears and emits. Strip or rename the field at the `BbTable`
   boundary. The compile-time half of the same collision is in §5.5b.
7. **Dynamic slot names are normalized** via
   `slotKey(key) = key.split(/\W+/g).join('_').toLowerCase()` in
   `BbBreadcrumbs`, `BbTree`, `BbTabs`, and the date-picker day slots.
   `#Order History` → `#order_history`. **⚠ silent**: a stale raw-key slot
   simply renders fallback content. `BbTabs` goes further: the label slot is
   renamed (`#label-<key>` → `#label:<slotKey>`), the URL query value is the
   normalized slug (`?tab=In%20Review` → `?tab=in_review` — update deep links
   and server code), and tab/panel DOM ids are normalized. Only `v-model` /
   item `key` stay raw.
8. **Dialogs, popovers, dropdowns and selects open as bottom sheets on mobile**
   by default (`adaptive`, default `true`). Set `adaptive: false` in the
   plugin, or per component, for v2-like floating behavior.
9. **`confirm()` buttons**: default labels are localized (no more hard-coded
   "OK"/"Annulla") and footer buttons default to `md`.
10. **`confirm()` closes itself now.** `autoClose` was opt-in in v2 — after
    `resolve`/`reject` the dialog stayed up until you called `close()`. In v3 it
    defaults to `true`. ⚠ silent: the promise settles exactly as before, the
    dialog just disappears. A multi-step flow that kept it open between steps
    has to pass `autoClose: false`.
11. **Invalid enum-ish prop values** (`size`, `direction`, `BbSlider.labelMode`)
    now warn in dev and fall back to the documented default instead of
    rendering broken or throwing.
12. **`BbTree` is a disclosure list, not an ARIA tree**: the unfulfilled
    `role="tree"` / `treeitem` / `aria-level` markup is gone, and a collapsed
    branch's children are now `inert` (out of the Tab order). Tests or CSS
    keyed on the removed roles match nothing — see
    [bb-tree.md](./components/bb-tree.md).
13. **`BbTable` is a CSS grid, not a `<table>`.** Column widths hold their
    overflow threshold, wrap floor and frozen widths exactly, but leftover
    space is shared equally between auto columns rather than proportionally
    to content, and a few table-only tricks stop working (`max-width: 0` for
    ellipsis collapses the cell). Copying rows into a spreadsheet pastes one
    value per line, and a printed table no longer repeats its header on each
    page. `#thead`/`#tbody`/`#tfoot` take `<div role="row">` rows, never
    `<tr>`. Requires subgrid (Chrome/Edge 117, Firefox 71, Safari 16) — no
    fallback. Full detail and the selector translation in
    [bb-table.md](./components/bb-table.md#the-table-is-a-css-grid-not-a-table-v3-beta-2026-08-26).

## 7. Class overrides → variants

### The v2 pattern to hunt down

v2 had no typed variant affordance, so project code commonly reached for the
library's internal modifier classes (or invented look-alikes):

```vue
<!-- v2 userland -->
<BbButton class="bb-button--outline">Cancel</BbButton>
<BbAlert class="bb-alert--warning" title="Heads up" />
<span class="bb-badge bb-badge--secondary">Draft</span>
```

These keep _rendering_ in v3 (the class hooks still exist), but they are now
the wrong layer: they bypass the typed registry, silently drift when the
library renames internals, and duplicate what a prop expresses. Convert them.

**But the conversion is additive, not neutral.** v2 shipped no variant CSS
(§4): those class names carried your rules and nothing else. In v3 each one is
a real skin, so every rewrite below slides the library's rules _underneath_
yours — background, border, foreground, hover, pressed, focus ring. Wherever
your CSS does not override all of them, the appearance drifts. Diff a
screenshot; do not assume. Two consequences before you start:

- **Leaving the class alone is not a safe holding position.** `variant`
  defaults to `primary`, so in v3 `<BbButton class="bb-button--outline">`
  renders `bb-button--primary bb-button--outline` — the built-in skin and your
  class fighting in the cascade. For a pure class override, pass
  `variant="none"`; it is the one value that emits no variant class.
- **A name that collides with a v3 built-in is the dangerous case, not the easy
  one.** If your app owned the look of `warning` / `destructive` / `secondary`,
  converting to the same-named `variant` hands that look to the library — and
  registering the name does **not** take it back: registration is type-only
  (§4), the built-in skin stays in `styles.css`. Keep your look by winning the
  cascade over the library's skin rules — author at block+modifier and load
  after `styles.css` (§4 case 2 has the specificity detail) — or convert to a
  non-colliding custom name.

### Finding them

Run in the consumer project:

```bash
# any hand-applied bitboss modifier class in templates
rg -n 'class="[^"]*bb-[a-z-]+--' --type vue
rg -n ":class=\"[^\"]*'bb-[a-z-]+--" --type vue
# free-form theme props (removed in v3)
rg -n '(:?theme)=' --type vue
# the same prop as an option-object key — toast()/confirm() live in .ts
rg -n 'theme' --type ts --type js
# raw component markup rebuilt from classes (no <BbX> tag on the same line)
rg -n 'class="bb-(button|badge|alert|toast-message|tooltip|indicator)\b' --type vue
```

### Correcting them

| Found                                                                                               | Rewrite as                                                                                                                                                                                                                                                                                                                                                                      |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<BbButton class="bb-button--outline">`                                                             | `<BbButton variant="outline">` (same for `secondary`, `ghost`, `destructive`, `link`)                                                                                                                                                                                                                                                                                           |
| `<BbAlert class="bb-alert--warning">` / v2 `theme="warning"`                                        | `<BbAlert variant="warning">`                                                                                                                                                                                                                                                                                                                                                   |
| `class="bb-badge bb-badge--secondary"` on a `<span>`                                                | `<BbBadge variant="secondary">` — the real component, not markup cosplay                                                                                                                                                                                                                                                                                                        |
| `bb-toast-message--success` styling / v2 `theme` on toasts                                          | `toast({ variant: 'success' })`                                                                                                                                                                                                                                                                                                                                                 |
| `bb-tooltip--destructive`                                                                           | `<BbTooltip variant="destructive">` / `v-bb-tooltip="{ text, variant: 'destructive' }"`                                                                                                                                                                                                                                                                                         |
| A **custom** modifier (`bb-button--brand`, any name not in section 4's table)                       | Register it: `buttonVariants: ['brand']` in the plugin, keep your CSS, pass `variant="brand"`.                                                                                                                                                                                                                                                                                  |
| A modifier your app **styled itself**, whatever its name                                            | Decide before you convert: accept v3's built-in look and delete your CSS, or keep yours. Keeping it is free for a non-built-in name (register it, done — there is no library rule to fight); for a built-in name registering only satisfies the type-check, and your rules must also win the cascade over the library's skin (§4, case 2). Converting silently does the former. |
| A **state** modifier that stacks on a variant (`bb-button--pressed` alongside `bb-button--outline`) | Not convertible — `variant` holds exactly one value. Keep it a class and rename it out of `bb-*` (`app-button--pressed`). If it marks a real toggle, `v-model` on `BbButton` owns the state: it sets `aria-pressed` and emits `bb-button--active`, which the library deliberately leaves unstyled for you.                                                                      |
| A class that overrides _layout_, not look (widths, margins)                                         | Leave it — classes remain the right tool for layout; variants own _appearance semantics_.                                                                                                                                                                                                                                                                                       |

Rule of thumb: if the class name encodes a **meaning** (state, emphasis,
severity), it should be a variant; if it encodes **geometry**, it stays a
class.

Whatever stays a class should not stay in the `bb-*` namespace. An app-minted
`bb-table--borderless` or `bb-avatar--square` is squatting on the library's
prefix — neither name has ever shipped, and the day one does, your rule and the
library's collide silently. Rename them into your own prefix.

## 8. The silent-failure audit

Everything the compiler cannot catch, in one grep pass. Run each in the
consumer project; every hit needs a decision, not necessarily a change.

Two surfaces have no other net. **Composable option objects live in `.ts`** —
`toast({ … })` and `confirm({ … })` inside stores, interceptors and helpers —
and neither gate reaches them: `npx bitboss-ui check` opens only `.vue` and
`.md`, and the eslint plugin walks template ASTs. **Nothing reads CSS at all**,
not the CLI, not eslint, not `vue-tsc`, not the browser console. The
`--type ts --type js` lines and the token/class lines below are the whole
safety net for those two. (ripgrep's `js` type already covers `*.vue`, so
adding `--type vue` to them is redundant.)

**Props, slots and markup**

```bash
rg -in 'querykey'                         # → queryKey (URL params silently move)
rg -n 'show-close|showClose'              # → hide-close (inverted) on BbAlert/BbDialog/BbOffCanvas and in toast() options, which had showClose in v2 too. On BbPopover and BbTooltip the close button is GONE: delete the prop, never rename it
rg -n 'allow-select-all|allowSelectAll'   # → disable-select-all, inverted
rg -n 'auto-loading|autoLoading'          # BbButton behavior flip / rename
rg -n 'disabled-while-loading|disabledWhileLoading'  # removed
rg -n 'animate-x|animate-y|animateX|animateY'        # → disableAnimate*, now default-on
rg -n 'thumb-translate|thumbTranslate'    # → disable-thumb-translate
rg -n ':flip=|flip="'                     # → disable-flip on palette/select-popover
rg -n 'hide-arrow|show-arrow|arrow-padding|hideArrow|showArrow|arrowPadding'  # removed off tooltips
rg -n '<BbChip'                           # component removed → BbBadge clearable
rg -n '<BbBadge'                          # v2 badges are v3 indicators — review each
rg -n '<BbTab\b'                          # → BbTabs (\b so a tag name alone on its line still matches, and <BbTabs does not)
rg -n '#label-'                           # BbTabs label slot → #label:<slotKey>
rg -n 'reverse' --type ts --type js       # BbRadio/BbSwitch default flipped
rg -n 'timeout' --type vue                # BbTooltip → delay (BbAvatar keeps timeout); no ':' so static attrs match too
rg -nU '<BbIcon[^>]*type='                # → icon=, and prefix your own icons `local:` (bb-icon.md). -U so a multi-line tag matches
rg -n '(icon|type)="[a-z][a-z0-9-]*"'     # bare icon names in templates → `local:<name>` so the Iconify extension previews them
rg -n 'allow-writing|allowWriting'        # → disable-writing, inverted + new tokens
rg -n 'show-chevron|showChevron|updateOnAnimationFrame|update-on-animation-frame'  # removed
rg -n 'label-position|labelPosition'      # groups → legend-position
rg -n 'prefill="focus"|prefill: .focus.'  # → 'interaction'
rg -n ':prefill="false"|prefill: false'   # now search-first, not load-on-open
rg -n 'role="tree|treeitem'               # BbTree ARIA roles removed
rg -n 'filter-by|filterBy'                # function/string filterBy → string[] (camelCase spelling lives in .ts option objects)
rg -n 'option:prepend|option:append|options:prepend|options:append|#chevron'  # removed slots
rg -n '<Bb(Checkbox|Radio|Switch|Slider|Rating|Avatar|Icon|Spinner)[^>]*color='  # removed color props
rg -n 'disabled:' --type ts --type vue    # item.disabled near option components → selectable
rg -n 'picker' --type ts --type js        # color input/palette → eye-dropper
```

**Composable option objects and imports (`.ts` / `.js`)**

```bash
rg -n 'timeout' --type ts --type js       # toast()/confirm() options → duration
rg -n 'theme' --type ts --type js         # toast()/confirm() options → variant
rg -n 'dismissAll'                        # useToast().dismissAll() → dismiss() with no argument. useConfirm() has a NEW dismissAll — check which one each hit is
rg -n 'autoClose|auto-close'              # confirm(): opt-in in v2, default true in v3 (section 6)
rg -n 'yesText|noText|onYes|onNo|hideHeader|setLoading' --type ts --type js  # confirm() options collapsed into the yes/no configs
rg -n 'BbTableColumn\s*&|DropdownItem\s*&' --type ts  # intersections that collapse to `undefined` (§5.5b)
rg -n "provide\('icons'|inject\('icons'"  # a hand-rolled icon registry is shadowed, not merged, by the plugin's (section 1)
rg -n 'IconRegistry|BbToastMessage|useWizard|useQueue|useQuery|useBroadcastChannelInstance|BaseButtonProps|BaseDialog'  # removed exports
rg -n 'setConfig'                         # only locale survives at runtime
```

**CSS: tokens and class names**

```bash
rg -n -- '--bb-(contrasting|hint|icon-color|primary-(base|dark)|panel-(light|dark|disabled)|border-(light|dark|hover)|text-(light|dark|secondary|tertiary)|input-(color|compact-|font-size|inner-h|prefix(-px)?([^-a-zA-Z0-9]|$))|label-(size|compact-spacing-y)|overlay-(color|opacity|z-index)|dialog-|button-|badge-|checkbox-w|radio-space|switch-|rating-size|base-rating-spacing|slider-|table-|select-option-|select-popover-|progress-track|toast-m|breadcrumbs-|picker-|icon-dimensions-)'  # every retired v2 token — v3 declares none of them (sections 3 and 5.7)
rg -n -- '--bb-ring-opacity'              # survives by name; every value must now carry a % (section 3)
rg -n 'bb-base-dialog|bb-tab__|bb-tab--|bb-cr-container|bb-common-input-outer-container|bb-common-input-inner-container|bb-base-input-container__input|bb-base-(checkbox|radio|switch)-container|bb-tree-row|bb-tree-main-content|bb-confirm__no|bb-dropdown__wrapper|bb-offcanvas__close|bb-popover__close|bb-ratio'  # renamed or deleted CSS blocks — nothing in v3 emits any of these (§5.6)
rg -n 'bb-color-palette__'                # → .bb-base-color-palette__*; only __popover survives under the old name
rg -n '\b(table|thead|tbody|tfoot|caption|colgroup|col|tr|th|td)\b' --type css --type vue  # element selectors aimed at BbTable (`.bb-table table`, `:deep(> table > tbody …)`, a global `td { padding }`, `.prose table`) — BbTable is a div grid in v3, none of them reach it; translate per bb-table.md § Selector translation. Expect noise from `<table>` markup of your own and from words in comments — judge each hit
rg -n 'bb-tabs--'                         # v3's own modifiers are --horizontal --vertical --block --compact --disabled; anything else is app-minted, and a hand-rolled full-width tab list is now <BbTabs block>
```

⚠ That first pattern is exact on purpose, and the near-misses are the point: a
looser one (`input-`, `overlay-`, `dialog-p`) sweeps up tokens that are still
live globals, and deleting those overrides shifts the layout silently. All of
these survive in v3 under the same name — do not remove them because a pattern
matched: `--bb-input-h`, `-px`, `-py`, `-icon`, `-spacing`, `-prefix-w`,
`--bb-leading`, `--bb-label-spacing-x` / `-spacing-y`, `--bb-label-weight`,
`--bb-ring-size`, `--bb-ring-opacity`, `--bb-arrow`, `--bb-radius`,
`--bb-primary`, `--bb-panel`, `--bb-text`, `--bb-border`, `--bb-danger`,
`--bb-ring`, `--bb-surface-hover` (and `--bb-overlay-blur`, new in v3). Six of
them changed **default value** — the drift table in section 3 says which.

Also review, with no greppable signature: dialog/off-canvas **widths**
(section 2), the **primary color** (section 3), `adaptive` bottom sheets on
mobile (section 6), and any UX that relied on second-click-to-clear selects.

## 9. Per-component guide index

Detailed old→new tables and edit outlines live in
[`migration/components/`](./components/). Components not listed have **no
functional changes** — nothing to migrate beyond the family-wide notes above.
That no-migration set is: `BbNumberInput`, `BbTextarea`, `BbProgress` — with
one caveat: the family-wide CSS renames in §5.6 still reach them
(`.bb-base-textarea--compact`, `.bb-progress--horizontal` and the input-chrome
blocks all moved), so check your stylesheet even for these three.

`BbSmoothHeight` is **not** in it: its `tag` narrowed from any non-void element
to `'div' | 'span'`, so anything else is now a compile error — see
[BbSmoothHeight](./components/bb-smooth-height.md).

| Area              | Guides                                                                                                                                                                                                                                                    |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Actions           | [BbButton](./components/bb-button.md) · [BbDropdownButton](./components/bb-dropdown-button.md)                                                                                                                                                            |
| Badges & status   | [BbBadge / BbIndicator](./components/bb-badge.md) · [BbChip (removed)](./components/bb-chip.md)                                                                                                                                                           |
| Feedback          | [BbAlert](./components/bb-alert.md) · [BbToast / toast()](./components/bb-toast.md) · [confirm()](./components/use-confirm.md) · [BbSpinner](./components/bb-spinner.md)                                                                                  |
| Surfaces          | [BbDialog](./components/bb-dialog.md) · [BbOffCanvas](./components/bb-offcanvas.md) · [BbPopover](./components/bb-popover.md) · [BbTooltip](./components/bb-tooltip.md) · [BbCollapsible](./components/bb-collapsible.md)                                 |
| Navigation & data | [BbDropdown](./components/bb-dropdown.md) · [BbTabs](./components/bb-tabs.md) · [BbTable](./components/bb-table.md) · [BbTree](./components/bb-tree.md) · [BbBreadcrumbs](./components/bb-breadcrumbs.md) · [BbPagination](./components/bb-pagination.md) |
| Media             | [BbAvatar](./components/bb-avatar.md) · [BbIcon](./components/bb-icon.md)                                                                                                                                                                                 |
| Layout            | [BbSmoothHeight](./components/bb-smooth-height.md)                                                                                                                                                                                                        |
| Text-ish inputs   | [BbTextInput](./components/bb-text-input.md) · [BbColorInput](./components/bb-color-input.md) · [BbDatePickerInput](./components/bb-date-picker-input.md) · [BbColorPalette](./components/bb-color-palette.md)                                            |
| Selects           | [BbSelect](./components/bb-select.md) · [BbSelectPopover](./components/bb-select-popover.md)                                                                                                                                                              |
| Choice controls   | [BbCheckbox / BbRadio / BbSwitch](./components/bb-checkbox.md) · [the three groups](./components/bb-checkbox-group.md)                                                                                                                                    |
| Other inputs      | [BbSlider](./components/bb-slider.md) · [BbRating](./components/bb-rating.md) · [BbTag](./components/bb-tag.md) · [BbDropzone](./components/bb-dropzone.md)                                                                                               |
| Removed           | [BbIntersection](./components/bb-intersection.md) · [useBroadcastChannelInstance](./components/use-broadcast-channel-instance.md)                                                                                                                         |

---

<!-- dist/ai/guides/options-items-playbook.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/options-items-playbook.md -->

# Options and Items Playbook

Applies to every component with an `items` prop:

- [BbSelect](../BbSelect.md) / [BbSelectPopover](../BbSelectPopover.md) — searchable pickers
- [BbCheckboxGroup](../BbCheckboxGroup.md) / [BbRadioGroup](../BbRadioGroup.md) / [BbSwitchGroup](../BbSwitchGroup.md) — always-visible groups
- [BbTable](../BbTable.md) — rows are items; `item-value` is row identity
- [BbDropdown](../BbDropdown.md) — selectable **pipeline groups** declared inside `items`

Companion playbooks: [Fetch Items](./fetch-items-playbook.md) (async providers), [Coherence](./coherence-playbook.md) (keeping `modelValue` valid when options change).

## First: which of the two item vocabularies applies

`items` means two different things in this library, and picking the wrong one is
the most common early mistake. Ask **whose data is it?**

|                       | **Accessor mode** — _your data_                                                   | **Authored mode** — _your UI_                                                                                     |
| --------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Components            | `BbSelect`, `BbSelectPopover`, `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup` | `BbDropdown`, `BbDropdownButton`, `BbTabs`, `BbBreadcrumbs`, `BbTree`                                             |
| Shape                 | any shape — raw API rows                                                          | entries you write, each carrying its own caption (`text` on dropdown items, `label` on tabs / breadcrumbs / tree) |
| Caption               | you point at a field: `item-text`, `item-value`                                   | it is on the entry itself                                                                                         |
| Rest of this playbook | **applies**                                                                       | mostly does **not** — no accessors, no hash-matching                                                              |

```vue
<!-- Accessor mode: customers came from an API, keep their field names. -->
<BbSelect
	v-model="customerId"
	:items="customers"
	item-text="name"
	item-value="id"
/>

<!-- Authored mode: a menu you typed out. The caption lives on the entry. -->
<BbDropdown :items="[{ text: 'Edit', value: 'edit' }]" />
```

**Why two, deliberately.** A picker lists records that arrive with their own
field names (`full_name`, `uuid`), so forcing them into `{ text, value }` would
mean a pointless `.map()` on every list — and it cannot work at all for the
async form, where the component fetches the items itself and never sees your
array. A dropdown or a tab strip is the opposite: you are writing those captions
by hand anyway, so an accessor would be indirection with nothing to point at.

`BbTable` sits between the two: rows stay **raw data** (accessor mode —
`item-value` is row identity), but the captions live on `columns[].label`, not
on the rows.

## Canonical item contract

> Scope: **accessor-mode** components (the first column above). Authored-mode
> entries carry their own caption and none of this applies to them.

Pass backend/domain items **as-is** to `items` and resolve text/value declaratively:

- `item-text="path.to.label"` or `:item-text="(item) => ..."` — display text
- `item-value="path.to.id"` or `:item-value="(item) => ..."` — the value stored in `v-model`

Never pre-map accessor-mode items into `{ label, value }` arrays. Matching is hash-based on the extracted value, so component-native extraction stays robust and the raw item remains available to slots (`#option`, cell slots) untouched.

### Mapping modes

1. **Primitive items** (`string[]`, `number[]`): omit both props; the value is the primitive itself.
2. **Dot paths** for nested objects: `item-text="profile.fullName"`, `item-value="profile.id"`.
3. **Extractor functions** only when a path can't express it:

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { BbSelect } from 'bitboss-ui';
import type { Member } from '@/types';

const assignee = ref<string | null>(null);
const members = ref<Member[]>([]); // raw API rows

const memberText = (m: Member) => `${m.firstName} ${m.lastName}`;
</script>

<template>
	<BbSelect
		v-model="assignee"
		label="Assignee"
		:items="members"
		:item-text="memberText"
		item-value="uuid"
	/>
</template>
```

## How options resolve (verified semantics)

- Default `item-value` is the **whole item**; default `item-text` is the string itself for strings, `JSON.stringify(item)` otherwise. For object items, always set both props.
- Selection matching compares `hash(itemValue(item))` against `hash(modelValue entry)` — a **deep value** comparison, not reference identity. Object values match structurally, but prefer primitive ids: they are stable across refetches and cheap to submit.
- Items resolving to a **duplicate value are silently dropped** (first occurrence wins). Guarantee unique `item-value` per option.
- `modelValue` holds the resolved value(s), never the option wrapper. Slots receive the raw `item` plus resolved `text` / `value`.
- **Clicking the selected option never clears a single select.** A second click on the current option re-picks it and closes the panel — the value does not change. Emptying is always an explicit affordance: `clearable` on `BbSelect`, or the `clear` callback on `BbSelectPopover`'s activator/panel slots. **Multiple mode still toggles**: clicking a selected option removes it, which is the whole interaction there.

## Seed the model — `multiple` hard-throws on non-arrays

Components in multiple mode **throw at setup** when `modelValue` is not an array. Seeded arrays are mandatory:

```ts
const channels = ref<string[]>([]); // correct
const channels = ref(); // throws: "multiple ... but modelValue is not an array"
```

| Component                           | `multiple` default | Seeding rule                                                                 |
| ----------------------------------- | ------------------ | ---------------------------------------------------------------------------- |
| `BbSelect` / `BbSelectPopover`      | `false`            | with `multiple`, seed `ref([])`; single mode seeds `ref(null)`               |
| `BbCheckboxGroup` / `BbSwitchGroup` | **`true`**         | always seed `ref([])` unless you explicitly set `:multiple="false"`          |
| `BbRadioGroup`                      | single-only        | seed with `null` (e.g. `ref<string \| null>(null)`)                          |
| `BbTable`                           | **`true`**         | `modelValue` defaults to `[]`; only throws if you bind a non-array `v-model` |

## Modelling an "All" / "Any" option (`null` as a real value)

A single select whose top row means _"everything"_ — "All locations", "Any status", the no-filter row. **Not** the same as a select-all button, which fills a `multiple` array with every value ([select-all pattern](../BbSelect.md#panel-actions-header-footer-and-select-all)).

Model it as a real option with `value: null`, returned by your provider or present in your array like any other option — the components never synthesise it. It resolves and renders as the selection: `useBaseOptions` matches on `hash(value)` and marks selection with `!== undefined`, so `null` is a legitimate option value.

**The rule — with a function `items`, set `prefill: true`:**

```vue
<!-- null means "All", and items is a provider → say so -->
<BbSelect v-model="location" :items="loadLocations" :prefill="true" … />

<!-- array items: nothing needed, arrays are never lazy -->
<BbSelect v-model="location" :items="locations" … />
```

Why: `null` is also the value the library reads as **nothing selected**, so the "model has a value → load eagerly" upgrade does not fire for it. With a provider nothing loads, no text resolves, and `BbSelect` renders its **placeholder** — greyed, indistinguishable from an empty field, while the model holds a real choice. The library cannot know `null` means "All" in your app without loading the options to look, so you tell it. `BbSelectPopover` is unaffected in practice (you own the trigger and label it from your own state), but the same rule applies if you read the slot's `text`.

**What you inherit by overloading `null`** (the component cannot distinguish the two meanings):

| Behaviour                            | Consequence                                                                  |
| ------------------------------------ | ---------------------------------------------------------------------------- |
| `clear` emits `null`                 | The clear affordance **selects "All"**                                       |
| empty is always coherent             | `enforce-coherence` **never prunes** the "All" value                         |
| single-mode enforcement emits `null` | A prune of some _other_ stale value **widens to "All"** — not to "nothing"   |
| `null` reads as empty                | A null model **stays lazy** even with `enforce-coherence` (nothing to check) |

Accept those and it is a clean, supported pattern. If "everything" and "nothing" must stay **distinct** — a required field, or a filter where silently widening is unsafe — use a **sentinel** (`value: 'all'`) instead. Then `null` keeps meaning empty, but the sentinel must appear in **every** provider response or `enforce-coherence` prunes it, and it counts as a value so it triggers the eager-prefill upgrade by itself.

Worked example (provider + prefill), runnable: [BbSelect → An "All" / "Any" option](../BbSelect.md#an-all--any-option-null-as-a-real-value).

## Disabling options — what's idiomatic now

A `disabled` field on the item object (`{ id: 1, label: '…', disabled: true }`) has **no UI meaning**: it is plain domain data, ignored by every options component (the old deprecated per-item behavior was removed). The supported surface is:

- `disabled` prop — the whole control.
- `selectable` prop — per-option gating on `BbCheckboxGroup`, `BbRadioGroup`, `BbSwitchGroup`, `BbSelect`, `BbSelectPopover` and `BbTable`. Either a global boolean (`false` disables every option) or a predicate `(item) => boolean`; options the predicate rejects render disabled. Defaults to `true` on the option components; on `BbTable` it is unset until you pass it — and an unset `selectable` there means "no selection column", not "every row selectable".
- `max` — caps a multiple selection: at the cap, unselected options auto-disable while **selected options never disable**, so the user can always deselect.
- `BbDropdown` items are buttons, not options — `disabled` there is a regular button prop and stays supported (on plain items and pipeline-group rows alike).

If your domain data carries an availability flag, feed it to the predicate — e.g. `:selectable="(item) => !item.disabled"` or `:selectable="(user) => user.active"` — or filter the items out entirely when a dead row would add noise.

## Component-specific notes

- **`BbTable`** — always set `item-value`: selection, expansion (`v-model:expanded-items`) and highlight track rows by that value, so state survives refetches where object references change.
- **`BbDropdown` pipeline groups** — the group is fully declared in the host's `items` (getter + `itemText` / `itemValue` / `max`, camelCase — it's data, not template props). The `<BbDropdownGroup>` companion is only `id` + `v-model`; its `id` matches the group's `key`:

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbDropdown, BbDropdownGroup } from 'bitboss-ui';

const assignee = ref<string | null>(null);
const items = [
	{ key: 'edit', text: 'Edit invoice', href: '/invoices/42/edit' },
	{
		key: 'assignee',
		text: 'Assign to',
		selectable: true,
		items: () => api.members.list(),
		itemText: 'name',
		itemValue: 'id',
	},
];
</script>

<template>
	<BbDropdown :items="items">
		<template #activator="{ props }">
			<BbButton
				v-bind="props"
				aria-label="Invoice actions"
				icon="lucide:ellipsis-vertical"
				variant="ghost"
			/>
		</template>
		<BbDropdownGroup id="assignee" v-model="assignee" />
	</BbDropdown>
</template>
```

## Items that navigate

When an item is a link, the component navigates — never your code. `BbDropdown` items take `href` (anchor / Inertia visit with `method`, `data`, …) or `to` (vue-router); table row links are a `BbButton` with `href`/`to` in a cell or `#actions` slot. Never `onClick: () => router.push(...)` on an item, and never a row `@click` that sets `window.location`.

## Anti-patterns

- `items.map(...)` to build UI-only option objects, or parallel "option DTO" types.
- Inline map/filter in template bindings; mutating server rows in templates.
- Storing whole objects in `modelValue` when an id is enough.
- Expecting a `disabled` field on items to disable the option — it is inert data; use the `selectable` predicate.
- Unseeded `v-model` refs on multiple-mode components (throws).
- A `null` "All" option behind a **function** `items` without `prefill: true` — nothing loads, so `BbSelect` shows its placeholder and the "All" choice is invisible.
- Synthesising the "All" row inside the component's own slots instead of returning it from `items` — it then has no value to match, so it can never render as the selection.

## Validation checklist

- [ ] Object items set both `item-text` and `item-value` (dot-path first, function only when needed).
- [ ] `item-value` resolves to a stable, unique, preferably primitive identity.
- [ ] Multiple-mode `v-model` refs are seeded with arrays.
- [ ] No manual option mapping or template-level reshaping.
- [ ] Unavailability handled via `disabled`, `max`, the `selectable` prop/predicate, or filtering — never via a `disabled` field on items (inert data).
- [ ] Link-like items navigate via `href`/`to`, not click handlers.
- [ ] A `null` "All"/"Any" option is returned by `items` like any other option, and — if `items` is a function — `prefill: true` is set so it can render.
- [ ] Where "everything" and "nothing" must stay distinct, a sentinel (`'all'`) is used instead of `null`, and it is present in every provider response.

---

<!-- dist/ai/guides/page-shell.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/page-shell.md -->

# Page Shell

An app-side layout component that gives every page the same chrome: a
**topbar**, the **content**, and a right **details sidebar** that slides in
to "peek" a record without navigating — the Linear-style inspector. The
sidebar is driven by a stack context, so any component on the page can push
a record into it (a table row, a search result, a link _inside the sidebar
itself_ — that's what the stack is for: drill-down with back).

This is app code, not a `bitboss-ui` export: copy it once into your project
(conventionally `src/components/layout/`) and wrap every page in it. The
[page recipes](../recipes/inertia/records-workspace.md) **import it directly**
— they do not work without it.

**The content wrapper is a `<div>`, not `<main>`.** The
[App Layout](./app-layout.md) around it already owns the page's one `<main>`
landmark; a second one here would nest `<main><main>`, which is invalid HTML
and gives assistive tech two indistinguishable "main content" regions.

## Where the code is

**The implementation lives in the scaffold recipe, not here.**

- [Layout Scaffold (Vue)](../recipes/vue/layout-scaffold.md)
- [Layout Scaffold (Nuxt)](../recipes/nuxt/layout-scaffold.md)
- [Layout Scaffold (Inertia)](../recipes/inertia/layout-scaffold.md)

Copy the files from there verbatim. Those recipes are generated from the
fixtures this library's own end-to-end suite drives, so the code you copy is
code that is known to run. This guide used to carry its own copy of
`PageShell.vue` and `usePageShellContext.ts`; the two drifted apart until they
were different components with different APIs under the same name, and pages
built from the guide did not fit the recipes that import the scaffold. One
implementation, in one place, is the fix.

## The context, in one paragraph

The sidebar is a **navigation stack**, not a boolean. Two named intents cover
almost every call: **`peek(item)`** opens a fresh top-level peek — what a row
click does — and **`stackItem(item)`** drills from the open peek into a related
record, keeping the back arrow. Both are thin aliases over `push(item, reset?)`,
which stays available; prefer the named pair, because `push(item, true)` reads
at the call site as "push, and something about true", and getting that boolean
backwards silently resets a stack you meant to drill into. `pop()` goes back one
level; `close()` empties the stack, because a closed sidebar must never hide
stale history. `current` is the record being peeked (`null` when closed) and
`depth` drives the back arrow. Provide/inject is idempotent — the first caller
creates the context and later callers join it, so the page context and
`PageShell` share one instance without passing it around.

Deeper components need no props or events for this: `InvoicePeek` can call
`usePageShellContext<Invoice>()` itself and push a related record.

## Usage

```vue
<template>
	<PageShell>
		<template #topbar>
			<AppTopbar />
		</template>

		<InvoicesTable @peek="(invoice) => shell.push(invoice)" />

		<template #sidebar>
			<InvoicePeek v-if="shell.current.value" :invoice="shell.current.value" />
		</template>

		<template #dialogs>
			<EditInvoiceDialog />
		</template>
	</PageShell>
</template>

<script setup lang="ts">
import PageShell from '@/components/layout/PageShell.vue';
import { usePageShellContext } from '@/components/layout/usePageShellContext';
import type { Invoice } from '@/types';

const shell = usePageShellContext<Invoice>();
</script>
```

## One topbar

The `#topbar` slot is the page's **single** top command bar — breadcrumbs/title
on the left, page commands (search, the primary action) on the right, one
uniform-height row. Do **not** stack a second sticky bar above it. Primary
navigation belongs in the [App Layout](./app-layout.md) sidebar, not a second
horizontal bar; app-wide utilities (global search, a user menu) go **into** this
same topbar. Two stacked top bars (a brand/utility bar plus a page toolbar) are
the pattern to avoid — they double the chrome and eat vertical space for no gain.

Each page owns its own topbar (a per-page topbar component that carries that
page's context is the right shape — don't try to stretch one bar across every
page). If your product keeps a persistent app bar rendered by an ancestor, keep
the page's commands in this one PageShell topbar rather than adding a second
sticky row above it — one bar, uniform height, per page.

## The consult stack — a peek that only opens once is half a shell

A listing screen exists to be _consulted_: invoice → its account → another
invoice on that account, and back, without ever leaving the list. That is what
the stack is for, and a page that opens one reset peek per row and renders every
related name as dead text throws it away — each follow-up question becomes a
full-page navigation.

Treat this as a **completion criterion**, not a flourish. A records listing is
finished when:

1. **The peek item is a union of everything the row and the peek expose.** One
   `PeekItem = Invoice | Customer | Payment` discriminated by `kind`, not a
   separate shell per type (see "One shell per page" below).
2. **Every related name is a link that stacks.** In table cells and inside peek
   bodies alike: `BbBaseButton` + your `.plain-link` class calling
   `stackItem(related)` — never a `BbButton`, which is a padded button that
   breaks inline flow.
3. **The row highlight tracks the root of the stack**, not `current`. Drilling
   invoice → customer must not un-highlight the invoice row the consult
   started from; find the bottom-most stack entry that matches a row.
4. **`#sidebar-title` follows the top of the stack**, so the chrome names what
   is actually showing after a drill-down.

```vue
<!-- in the table: open a fresh peek -->
<BbBaseButton
	class="plain-link"
	@click="shell.peek({ kind: 'invoice', ...row })"
>
	{{ row.number }}
</BbBaseButton>

<!-- inside the peek: drill, keeping the back arrow -->
<BbBaseButton
	class="plain-link"
	@click="shell.stackItem({ kind: 'customer', ...invoice.customer })"
>
	{{ invoice.customer.name }}
</BbBaseButton>
```

## Every peek names itself

**Wire `#sidebar-title`.** The slot renders a spacer when absent, so a peek
without it opens with back and close flanking empty space — and the entity name
ends up as an `h2` inside the body, where it reads as a second title under a
blank header.

The title is the entity's name or number; status, dates and meta stay in the
body. With a stack, it follows `current`, so it renames itself on every
drill-down.

It is also the panel's accessible name: the scaffold points the `<aside>`'s
`aria-labelledby` at that `h2`. Skip the slot and the panel falls back to a
generic "Details" — a screen reader announces the region without saying which
record is in it.

## The keyboard baseline is already in the scaffold

The peek is a **docked, non-modal panel**: on desktop it sits beside the page
and the page stays live and clickable. The scaffold ships the four things that
shape owes, so you do not have to add them per page:

- **A name** — `aria-labelledby` → the `#sidebar-title` heading (above).
- **Focus lands in the panel** whenever `current` changes. Not only on open: a
  drill-down or a Back destroys the control that was focused, and focus would
  otherwise fall to `<body>` in the middle of a consult. Landing on the panel
  also re-announces its title, which is the record that just changed.
- **Focus goes back** to the page-side control that opened the peek when it
  closes — remembered on open, and only restored if that element is still in
  the document (a filtered-away row would silently drop focus on `<body>`).
- **Escape closes it**, from anywhere inside the panel. Library overlays take
  Escape at the document in the capture phase and stop it there, so a dropdown
  or popover open _inside_ the peek closes first, on its own Escape.

**Do not add a focus trap to the desktop panel.** Trapping Tab in a non-modal
region strands the keyboard in something the user can see past. Containment is
a question for the mobile sheet form only — see the enhancements below.

## Toasts keep off the open sidebar

The sidebar is **docked in the page, not floating over it**, so nothing in the
library can tell it is there — and a bottom-right toast would land squarely on
top of it. The scaffold fixes that in a few lines: while the sidebar is open on
desktop it claims the right edge, and the toast stack slides clear of it.

```ts
const SIDEBAR_W = 352; // 22rem — keep in step with the sidebar's own width
const { isMobile } = useMobile();
useSafeArea({
	side: 'right',
	size: () => (shell.current.value ? SIDEBAR_W : null),
	active: () => !isMobile.value,
});
```

A declared `size` cannot tell whether the panel is on screen, so the stack says
it: `null` while closed means nothing is docked. `active` carries the other
condition — below the mobile breakpoint the scaffold's own media query turns the
panel into a full-screen sheet (next section), so there is no right edge left to
claim. (A resizable panel would pass `element` instead of `size` and be measured
live.)

It is already in the code you copy from the scaffold recipes — you only need
this if you are hand-rolling a shell or adding a **second** docked panel (a
filter rail on the left, a docked console at the bottom): claim its edge the
same way. See [useSafeArea](../composables/useSafeArea.md) for what exactly gets
claimed and why an oversized claim is harmless.

## Below the mobile breakpoint the peek is a sheet

There is no room for a 22rem column beside the content on a phone, so the
scaffold's stylesheet flips the panel to `position: fixed; inset: 0` under
`@media (max-width: 767.98px)` — it covers the page, chrome included, and its
own header carries Back and Close.

Two things in that rule are load-bearing if you change it:

- **The breakpoint is `config.mobileMaxWidth` (768) minus a hair — the exact
  query `useMobile()` runs.** Move one without the other and you get a band of
  widths where the safe-area claim still thinks a panel is docked at the right
  edge while the CSS has it covering the page.
- **The sheet's background is opaque**, where the docked form is translucent
  over the page grid. A sheet that covers content must not let it show through.
  Its `z-index` clears the page topbar and the floating bottom panel for the
  same reason: while the sheet is up, it _is_ the page.

## Design notes and enhancements

- **One shell per page, one stack type.** The context is typed per page
  (`usePageShellContext<Invoice>()`); if a page peeks two different record
  types, use a discriminated union, not two shells.
- **The `dialogs` slot** exists so page-level dialogs live in the shell's
  DOM subtree — one conventional place, no dialog markup scattered through
  tables and toolbars.
- **Peek is not navigation.** A full record page must stay reachable via a
  real link (`href`/`to`) inside the sidebar content.
- Worthwhile enhancements, deliberately left out of the baseline for
  clarity — add when the app needs them:
  - **Scroll-aware stickiness**: track the topbar's viewport position and
    offset the sidebar so it starts below the topbar and sticks while the
    page scrolls (rAF-scheduled scroll/resize listeners + a ResizeObserver).
  - **Modal semantics for the mobile sheet**: below the breakpoint the panel
    covers the page, which is the one shape where containment is right —
    `role="dialog"` + `aria-modal="true"` and a focus trap (`useFocusTrap` from
    `@vueuse/integrations`) while that media query applies, and neither when it
    does not. The baseline ships the non-modal set only, because it is correct
    at both sizes.
  - **Detached mode**: render the sidebar via the Popover API
    (`popover="manual"` + `showPopover()`) so it sits in the browser's
    top layer with a native `::backdrop` — no z-index management.

## Related

- [Floating Bottom Panel](./floating-bottom-panel.md) — the selection
  action bar that floats over this shell.
- [Recipe: Records Workspace (Inertia)](../recipes/inertia/records-workspace.md)
  — a full page inside the shell.
- [BbOffCanvas](../BbOffCanvas.md) — the library primitive to reach for
  when you need a one-off drawer rather than page-wide chrome.

---

<!-- dist/ai/guides/validated-forms.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/validated-forms.md -->

# Validated Forms

`bitboss-ui/validated` ships the standard form controls wrapped with
[vee-validate](https://vee-validate.logaretm.com/v4/) field binding. Import from
`bitboss-ui/validated` **only** where you want validation — the core `bitboss-ui`
entrypoint never pulls vee-validate into apps that don't use it.

```bash
npm i vee-validate                        # required peer for /validated
npm i @vee-validate/rules @vee-validate/i18n   # recommended: standard rules + messages
```

## 1. Define rules once (global)

The recommended, effort-free setup: `defineRule` your rules once as a
side-effect module imported from your app entry, then reference them as plain
strings on every field.

```ts
// app/validators.ts
import { configure, defineRule } from 'vee-validate';
import { localize, setLocale } from '@vee-validate/i18n';
import en from '@vee-validate/i18n/dist/locale/en.json';
import {
	required,
	email,
	min_value,
	max_value,
	numeric,
	min,
	max,
} from '@vee-validate/rules';

defineRule('required', required);
defineRule('email', email);
defineRule('min_value', min_value);
defineRule('max_value', max_value);
defineRule('numeric', numeric);
defineRule('min', min);
defineRule('max', max);

// Project-specific rules — same (value, params, ctx) signature:
defineRule('password', (v: unknown) =>
	typeof v === 'string' && v.length > 0 && v.length < 8
		? 'Password must be at least 8 characters'
		: true
);

configure({ generateMessage: localize({ en }) }); // swap `en` for your locale JSON
setLocale('en');
```

vee-validate's i18n is a **separate registry** from bitboss-ui's locale — they
don't share keys, so there is no automatic bridge. Register a message locale for
each language you support and set the active one; if you switch language at
runtime, call `setLocale` yourself in step with it.

```ts
// main.ts — import once for its side effects
import './app/validators';
```

## 2. Build the form

Wrap fields in `<BbForm>` (a thin `useForm` host). Give each field a `label`
(or `legend`) and `rules`. The field name is auto-derived from the label, so
you don't write `vid`:

```vue
<script setup lang="ts">
import { reactive, ref } from 'vue';
import { BbButton } from 'bitboss-ui';
import {
	BbForm,
	BbTextInput,
	BbNumberInput,
	BbCheckbox,
} from 'bitboss-ui/validated';

const form = reactive({ email: null, quantity: null, terms: false });
// `@submit` hands you the collected values, so the ref must be able to hold
// them — a bare `ref(null)` infers `Ref<null>` and the assignment won't compile.
const submitted = ref<Record<string, unknown> | null>(null);
</script>

<template>
	<BbForm v-slot="{ isSubmitting }" @submit="(v) => (submitted = v)">
		<BbTextInput v-model="form.email" label="Email" rules="required|email" />
		<BbNumberInput
			v-model="form.quantity"
			label="Quantity"
			rules="required|min_value:1"
		/>
		<BbCheckbox v-model="form.terms" label="Accept terms" rules="required" />
		<BbButton type="submit" :loading="isSubmitting">Submit</BbButton>
	</BbForm>
</template>
```

`@submit` fires **only when every field passes**, with the collected values.
`<BbForm>` also exposes `isSubmitting` / `submitCount` / `values` / `validate` /
`resetForm` in its slot — enough for any chrome that lives _inside_ the form.

For chrome that lives **outside** it (a dialog footer, a page toolbar, a leave
guard), give the form an explicit `id` and read it with
[`useBbFormContext(id)`](../composables/useBbFormContext.md) — the same id-context
pattern as `useBbTableContext` / `useBbDropdownContext`. There is no template-ref
handle: `useBbFormContext` is the only outside surface, by design.

Prefer strings, but a one-off inline function still works:
`:rules="(v) => !!v || 'Required'"`.

**`vid` is an escape hatch.** The field name is derived from the label
(`"Preferred time"` → `preferredtime`), so set `vid` only when that wouldn't be
unique — v-for'd rows, or array `v-model`s sharing a label:

```vue
<BbTextInput
	v-for="(_, i) in form.attendees"
	:key="i"
	v-model="form.attendees[i]"
	label="Attendee"
	:vid="`attendee_${i}`"
/>
```

`BbDropzone` has no label, so it always needs `vid`.

## The three added props

| Prop         | Type                         | Notes                                                                     |
| ------------ | ---------------------------- | ------------------------------------------------------------------------- |
| `rules`      | `RuleExpression<modelValue>` | A rule string (`"required\|email"`), function, or object.                 |
| `validateOn` | timing array                 | When to re-validate; per-control default below.                           |
| `vid`        | `string`                     | Escape hatch — explicit field name; normally auto-derived from the label. |

External errors compose: whatever you pass to the base `errors` prop is
**merged** with the vee-validate messages, so server-side errors and rule
messages show together.

## `validateOn` defaults

| Default                                 | Controls                                                                                                                |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `['blur']`                              | BbTextInput, BbNumberInput, BbTextarea, BbColorInput, BbDropzone                                                        |
| `['inactive']`                          | BbSelect, BbTag, BbSlider, BbRating, BbDatePickerInput, BbTimePickerInput, BbCheckboxGroup, BbSwitchGroup, BbRadioGroup |
| `['update:modelValue','change','blur']` | BbCheckbox, BbSwitch                                                                                                    |

`BbDropzone` has no label, so it **requires** `vid`.

## Required asterisk

Turn on the plugin option to mark required fields with a red `*`:

```ts
// vite.config.ts
bitbossUi({ requiredAsterisk: true });
```

It shows on any `/validated` control that is `required`, or whose `rules`
contain a **`required` rule** — rendered in the control's `#label`/`#legend`
slot. Rules alone are not enough, and deliberately so: every other rule is
conditional on a value being present (`max:5` passes on an empty field, which is
what makes "optional, but at most 5 if filled" expressible), so raising the
asterisk for any rule would mark optional fields as mandatory and contradict the
engine.

Both rule shapes are read — the string form (`'required|email'`, arguments
allowed: `'required:true'`) and the object form (`{ required: true }`, where
`{ required: false }` correctly shows nothing). `required_if` and friends do
**not** count: conditionally required is not required. A validator function or a
typed schema (yup/zod) is opaque to this check, so set `required` explicitly on
schema-driven fields that should carry the marker.

Core (non-validated) components ignore the option. The marker is the exported
`BbAsterisk` component — drop it into your own label content when you build a
bespoke field.

## Controls

BbTextInput · BbNumberInput · BbTextarea · BbSelect · BbTag · BbCheckbox ·
BbCheckboxGroup · BbSwitch · BbSwitchGroup · BbRadioGroup · BbRating · BbSlider ·
BbDatePickerInput · BbTimePickerInput · BbColorInput — plus `BbForm` and the
`useValidatedField` composable for wrapping your own controls.

A live, end-to-end demo lives in `fixtures/vue/pages/ValidatedForm` (with global
rules in `fixtures/vue/app/validators.ts`), asserted by
`fixtures/vue/e2e/validated-form.e2e.mjs`.

---

<!-- dist/ai/GuidesComponent.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/GuidesComponent.md -->

# GuidesComponent

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Layout & Utility**
- Description: Dev-only showcase that auto-collects examples/*.vue files with live preview and extractable source. Not part of the consumer API.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/GuidesComponent.md](./source/GuidesComponent.md)

## Props

- None.

## Events

- None.

## Slots

- None.

---

<!-- dist/ai/index.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/index.md -->

# AI Knowledge Base

This index helps agents quickly find component intent and authored guides before opening full files.

## Start here

- **[AI Router](./guides/ai-router.md)** — tiny hop map (contract → picker/recipe → one contract file). Read it before this catalogue.

## Agent Rules

- Default policy: recommend `Bb*` components first and treat low-level/internal primitives as reference-only.
- Setup policy: verify installation + plugin setup before proposing usage code.
- Icon policy: discover available icons first and use only existing icon names.
- Contract-first policy: each component link below is a typed contract (props/events/slots/v-model). Read `source/<Name>.md` only when the contract is not enough.
- Machine-readable manifest: [components.json](./components.json) lists every component API surface for programmatic validation.
- Package path: use `dist/ai/guides/ai-router.md` (then `dist/ai/index.md`) inside the installed `bitboss-ui` package (`node_modules/bitboss-ui/dist/ai/`).

## Recipes (Page-Level Assemblies)

Start from a recipe when building a whole page or flow — they encode the idiomatic composition of multiple components. Fall back to individual contracts for the details.

- [Approvals Inbox (Inertia)](./recipes/inertia/approvals-inbox.md) - Keyboard-first expense-approvals triage for Laravel + Inertia — `keyboard-navigation` with highlight-opens-peek, one-click approve, reject-with-reason and snooze dialogs via promise-wrapped visits, bulk approve/reject with select-all-across-pages, and an `A`/`R`/`S` shortcut bar, all through one page context that coopts the Inertia Helpers toolkit.
- [Approvals Inbox (Nuxt)](./recipes/nuxt/approvals-inbox.md) - Keyboard-first expense-approvals triage for Nuxt — `keyboard-navigation` with highlight-opens-peek, one-click approve, reject-with-reason and snooze dialogs backed by `useAsyncData`/`$fetch`, bulk approve/reject, and an `A`/`R`/`S` shortcut bar, filters URL-synced, all through one coopting page context.
- [Approvals Inbox (Vue)](./recipes/vue/approvals-inbox.md) - Keyboard-first expense-approvals triage for a vue-router SPA — `keyboard-navigation` with highlight-opens-peek, one-click approve, reject-with-reason and snooze dialogs, bulk approve/reject, and an `A`/`R`/`S` shortcut bar, all through one coopting page context.
- [Command Palette (Inertia)](./recipes/inertia/command-palette.md) - A ⌘K/Ctrl+K global command palette — BbDialog framing BbSelectPopover's search-and-pick engine — for keyboard-triggered, grouped, server-fed search across pages, records and actions.
- [Command Palette (Nuxt)](./recipes/nuxt/command-palette.md) - A ⌘K/Ctrl+K global command palette — BbDialog framing BbSelectPopover's search-and-pick engine — for keyboard-triggered, grouped, server-fed search across pages, records and actions.
- [Command Palette (Vue)](./recipes/vue/command-palette.md) - A ⌘K/Ctrl+K global command palette — BbDialog framing BbSelectPopover's search-and-pick engine — for keyboard-triggered, grouped, server-fed search across pages, records and actions.
- [Inline-Edit Workspace (Inertia)](./recipes/inertia/inline-edit-workspace.md) - Linear-style sprint backlog for Laravel + Inertia where every cell autosaves — optimistic per-field overlay with rollback retired where the fresh page prop lands, commit-on-blur text cells, spinner-in-the-chevron badge pickers, URL-driven filters and tabs, bulk bar and peek workbench, all through one coopting page context.
- [Inline-Edit Workspace (Nuxt)](./recipes/nuxt/inline-edit-workspace.md) - Linear-style sprint backlog for Nuxt where every cell autosaves — optimistic per-field overlay with rollback, commit-on-blur text cells, spinner-in-the-chevron badge pickers, an async assignee search, bulk bar and peek workbench, filters URL-synced and data fetched with useAsyncData (the overlay retires in its transform), all through one coopting page context.
- [Inline-Edit Workspace (Vue)](./recipes/vue/inline-edit-workspace.md) - Linear-style sprint backlog for a vue-router SPA where every cell autosaves — optimistic per-field overlay with rollback, commit-on-blur text cells, spinner-in-the-chevron badge pickers, an async assignee search, bulk bar and peek workbench, all through one coopting page context.
- [Layout Scaffold (Inertia)](./recipes/inertia/layout-scaffold.md) - The three app-owned chrome files every page recipe imports — the peek-stack context, the PageShell frame that renders it, and the FloatingBottomPanel selection dock. Build these before any page recipe; every recipe's `@/components/layout/*` imports resolve to them.
- [Layout Scaffold (Nuxt)](./recipes/nuxt/layout-scaffold.md) - The three app-owned chrome files every page recipe imports — the peek-stack context, the PageShell frame that renders it, and the FloatingBottomPanel selection dock. Build these before any page recipe; every recipe's `@/components/layout/*` imports resolve to them.
- [Layout Scaffold (Vue)](./recipes/vue/layout-scaffold.md) - The three app-owned chrome files every page recipe imports — the peek-stack context, the PageShell frame that renders it, and the FloatingBottomPanel selection dock. Build these before any page recipe; every recipe's `@/components/layout/*` imports resolve to them.
- [Ownership Atlas (Inertia)](./recipes/inertia/ownership-atlas.md) - Nested-table ownership atlas for Laravel + Inertia — expandable owner rows whose holdings render as a child BbTable snapped onto the parent's column tracks (inherit-column-widths + per-column snap), select-all-across-pages bulk transfer, region-visit tabs, URL-mirrored filters, expand/collapse-all, and a row-highlight owner peek, all through one page context that coopts the Inertia Helpers toolkit.
- [Record Form (Inertia)](./recipes/inertia/record-form.md) - Full-anatomy invoice create/edit form for Laravel + Inertia — sectioned fields with tied selects, usePromiseForm + form.errors for 422 mapping, an inline-editing line-items table, a useConfirmOnRouteLeave dirty guard, a sticky action row, and a customer peek sidebar, all through one coopting page context.
- [Record Form (Nuxt)](./recipes/nuxt/record-form.md) - Full-anatomy invoice create/edit form for Nuxt — sectioned fields with tied selects and FetchError 422 mapping, an inline-editing line-items table, a useAsyncData-backed dirty-snapshot route-leave guard, a sticky action row, and a customer peek sidebar, all through one coopting page context.
- [Record Form (Vue)](./recipes/vue/record-form.md) - Full-anatomy invoice create/edit form for a vue-router SPA — sectioned fields with tied selects and 422 error mapping, inline-editing line-item rows, a dirty-snapshot route-leave guard, a sticky action row, and a customer peek sidebar, all through one coopting page context.
- [Records Workspace (Inertia)](./recipes/inertia/records-workspace.md) - Full-anatomy invoices workspace for Laravel + Inertia — breadcrumbs + page search, chip filter rail (one Filters menu + editable filter chips), server-visit tabs with counts, one-click status cells via promise-wrapped visits, bulk bottom panel with select-all-across-pages, and a stacked peek sidebar, all through one page context that coopts the Inertia Helpers toolkit.
- [Records Workspace (Nuxt)](./recipes/nuxt/records-workspace.md) - Full-anatomy invoices workspace for Nuxt — breadcrumbs + page search, chip filter rail (one Filters menu + editable filter chips), href tabs with counts, one-click status cells, bulk bottom panel, and a stacked peek sidebar, filters URL-synced and data fetched with useAsyncData, all through one coopting page context.
- [Records Workspace (Vue)](./recipes/vue/records-workspace.md) - Full-anatomy invoices workspace for a vue-router SPA — breadcrumbs + page search, chip filter rail (one Filters menu + editable filter chips), href tabs with counts, one-click status cells, bulk bottom panel, and a stacked peek sidebar, all through one coopting page context.
- [Upload Center (Inertia)](./recipes/inertia/upload-center.md) - Full-anatomy expense-receipts upload center for Laravel + Inertia — multi-file dropzone into an inline-editable table (text, category popover, amount, date cells), per-file progress with inline retry via a direct fetch/XHR upload path, submit-all with count via promise-wrapped visits, bulk bottom panel, and a stacked receipt/merchant peek sidebar, all through one page context that coopts the Inertia Helpers toolkit.
- [Upload Center (Nuxt)](./recipes/nuxt/upload-center.md) - Full-anatomy expense-receipts upload center for Nuxt — multi-file dropzone into an inline-editable table (text, category popover, amount, date cells), per-file progress with inline retry, submit-all with count, bulk bottom panel, and a stacked receipt/merchant peek sidebar, filters URL-synced and drafts fetched with useAsyncData while the upload queue stays client-only, all through one coopting page context.
- [Upload Center (Vue)](./recipes/vue/upload-center.md) - Full-anatomy expense-receipts upload center for a vue-router SPA — multi-file dropzone into an inline-editable table (text, category popover, amount, date cells), per-file progress with inline retry, submit-all with count, bulk bottom panel, and a stacked receipt/merchant peek sidebar, all through one coopting page context.
- [Wizard Form (Inertia)](./recipes/inertia/wizard-form.md) - Mailchimp-grade 4-step campaign wizard for Laravel + Inertia — BbBaseButton stepper with done/current/upcoming/locked states, per-step validation gating Next behind a BbAlert summary merging form.errors, BbSmoothHeight step swaps, the step mirrored into the URL with no extra visit, a usePromiseForm draft with save-draft everywhere, and useConfirmOnRouteLeave guarding unsaved changes, all through one coopting page context.
- [Wizard Form (Nuxt)](./recipes/nuxt/wizard-form.md) - Mailchimp-grade 4-step campaign wizard for Nuxt — BbBaseButton stepper with done/current/upcoming/locked states, per-step validation gating Next behind a BbAlert summary, BbSmoothHeight step swaps, the step mirrored into the URL with navigateTo, useAsyncData + FetchError 422 handling merged into the same validation summary, save-draft everywhere and a dirty route-leave guard, all through one coopting page context.
- [Wizard Form (Vue)](./recipes/vue/wizard-form.md) - Mailchimp-grade 4-step campaign wizard — BbBaseButton stepper with done/current/upcoming/locked states, per-step validation gating Next behind a BbAlert summary, BbSmoothHeight step swaps, the step in the URL, save-draft everywhere and a dirty route-leave guard, all through one coopting page context.
- [Workspace Onboarding (Inertia)](./recipes/inertia/onboarding.md) - Full-anatomy workspace onboarding for Laravel + Inertia — a live BbProgress header, an accordion checklist whose steps do the real work inline (integration switches, tag-input invites, a mini project form, CSV import via useForm multipart), the checklist seeded from a page prop and mutations resolved through promise-wrapped visits, all through one page context that coopts the Inertia Helpers toolkit.
- [Workspace Onboarding (Nuxt)](./recipes/nuxt/onboarding.md) - Full-anatomy workspace onboarding for Nuxt — a live BbProgress header, an accordion checklist whose steps do the real work inline (integration switches, tag-input invites, a mini project form, CSV import with real byte progress), data loaded with useAsyncData and mutations resolved through $fetch + refresh(), all through one coopting page context.
- [Workspace Onboarding (Vue)](./recipes/vue/onboarding.md) - Full-anatomy workspace onboarding for a vue-router SPA — a live BbProgress header, an accordion checklist whose steps do the real work inline (integration switches, tag-input invites, a mini project form, CSV import), per-step done/skip, and step previews in the peek sidebar, all through one coopting page context.

## Components (Consumer API)

### Data Display

- [BbAvatar](./BbAvatar.md) - Displays an avatar and has a fallback content slot.
- [BbIcon](./BbIcon.md) - Renders an icon either from the local icon folder or from a provider.
- [BbTable](./BbTable.md) - Displays tabular data, configurable columns and data mapper.

### Feedback

- [BbAlert](./BbAlert.md) - Shows contextual status messages.
- [BbBadge](./BbBadge.md) - Displays a compact inline status counter or label. It sits in the flow — for a bubble or dot anchored OVER another element, use BbIndicator (includes the co-located BbBadgeButton export).
- [BbBadgeButton](./BbBadgeButton.md) - Makes a badge's body interactive: slotted as a direct child of BbBadge it renders the badge body as a real button/link with full BbBaseButton parity, leaving `clearable` free to remain a separate control.
- [BbIndicator](./BbIndicator.md) - Anchors a notification bubble (count/short text) or a dot over a wrapped element.
- [BbProgress](./BbProgress.md) - Visualizes task or operation progress state.
- [BbSpinner](./BbSpinner.md) - Indicates ongoing loading or pending operations.
- [BbToast](./BbToast.md) - Shows transient notification messages (includes the co-located BbToastPortal export).
- [BbToastPortal](./BbToastPortal.md) - Registers named slot content that toast() renders via `portal`.

### Inputs

- [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.
- [BbButton](./BbButton.md) - Button with loading state, tooltip, and icon support.
- [BbColorInput](./BbColorInput.md) - Captures color values through input controls.
- [BbDatePickerInput](./BbDatePickerInput.md) - Combines date selection with text input behavior.
- [BbDropzone](./BbDropzone.md) - Supports drag-and-drop file input flows.
- [BbForm](./BbForm.md) - Form host for `bitboss-ui/validated`: owns the vee-validate form (useForm), validates every field on submit, and emits `submit` with the collected values only when the form is valid.
- [BbNumberInput](./BbNumberInput.md) - Captures and validates numeric form values, emits a number value.
- [BbTag](./BbTag.md) - Captures and displays tag-like token values.
- [BbTextarea](./BbTextarea.md) - Captures multi-line text values.
- [BbTextInput](./BbTextInput.md) - Captures single-line text values.
- [BbTimePickerInput](./BbTimePickerInput.md) - Segmented time field with hour/minute columns; 24-hour string model.

### Layout & Utility

- [BbSmoothHeight](./BbSmoothHeight.md) - Animates height transitions for dynamic content.

### Navigation

- [BbAccordion](./BbAccordion.md) - Expands and collapses a content panel.
- [BbBreadcrumbs](./BbBreadcrumbs.md) - Renders hierarchical navigation paths.
- [BbCollapsible](./BbCollapsible.md) - Toggles visibility of collapsible content blocks.
- [BbPagination](./BbPagination.md) - Navigates paginated data sets by page index.
- [BbTabs](./BbTabs.md) - Switches between tabbed content views (shadcn-like strip; the co-located BbTabsRoot / BbTabsList / BbTabsPanes exports enable split layouts).
- [BbTabsList](./BbTabsList.md) - The trigger strip of a split BbTabsRoot layout (renders the tab buttons only).
- [BbTabsPanes](./BbTabsPanes.md) - The pane host of a split BbTabsRoot layout (renders the tab content only).
- [BbTabsRoot](./BbTabsRoot.md) - Provide/inject root that lets BbTabsList and BbTabsPanes live in separate layout slots.
- [BbTree](./BbTree.md) - Renders hierarchical expandable tree structures.

### Other

- [BbAsterisk](./BbAsterisk.md) - Presentational required-field marker (red "*"). No props/slots/events; placed in custom label content.

### Overlay

- [BbColorPalette](./BbColorPalette.md) - Opens an anchored popover color palette for color picking interactions.
- [BbConfirm](./BbConfirm.md) - Prompts users to confirm or cancel critical actions (includes co-located BbConfirmPortal export).
- [BbConfirmPortal](./BbConfirmPortal.md) - Registers named slot content that confirm() renders via `portal`.
- [BbDatePicker](./BbDatePicker.md) - Opens an anchored calendar (and optional time rail) popover on a trigger you own — the date analog of BbColorPalette; also the v-bb-date directive.
- [BbDialog](./BbDialog.md) - Presents modal dialogs for focused user interactions.
- [BbDropdown](./BbDropdown.md) - Displays contextual action menus and menu content (includes the co-located BbDropdownGroup export, which is how a selectable group is bound).
- [BbDropdownButton](./BbDropdownButton.md) - A button with primary action and all other actions collected in a dropdown.
- [BbDropdownGroup](./BbDropdownGroup.md) - Renderless v-model companion for a group declared in BbDropdown.items, bound by id.
- [BbOffCanvas](./BbOffCanvas.md) - Shows side-panel overlay content outside normal layout flow.
- [BbPopover](./BbPopover.md) - Anchors floating content to reference elements.
- [BbTimePicker](./BbTimePicker.md) - Opens hour/minute(/second) columns in a popover on a trigger you own — the time analog of BbDatePicker; also the v-bb-time directive.
- [BbTooltip](./BbTooltip.md) - Displays contextual helper text on interaction.

### Selection

- [BbBaseCheckboxIcon](./BbBaseCheckboxIcon.md) - Standalone checkbox glyph (box + checkmark SVG). Presentational only — no input, no events. Compose it into a fully custom checkbox design, or let BbCheckbox/BbBaseCheckbox render it.
- [BbBaseRadioIcon](./BbBaseRadioIcon.md) - Standalone radio glyph (ring + dot). Presentational only — no input, no events. Compose it into a fully custom radio design, or let BbRadio/BbBaseRadio render it.
- [BbBaseSwitchIcon](./BbBaseSwitchIcon.md) - Standalone switch glyph (track + thumb). Presentational only — no input, no events. Compose it into a fully custom switch design, or let BbSwitch/BbBaseSwitch render it.
- [BbCheckbox](./BbCheckbox.md) - Toggles a single boolean option.
- [BbCheckboxGroup](./BbCheckboxGroup.md) - Manages multiple checkbox options as a group.
- [BbRadio](./BbRadio.md) - Represents a single choice in exclusive options.
- [BbRadioGroup](./BbRadioGroup.md) - Coordinates exclusive selection among radio options.
- [BbRating](./BbRating.md) - Collects scalar ratings through interactive icons.
- [BbSelect](./BbSelect.md) - Selects one or many options from structured data.
- [BbSelectPopover](./BbSelectPopover.md) - Provides popover-driven option selection and search.
- [BbSlider](./BbSlider.md) - Selects numeric values across a bounded range.
- [BbSwitch](./BbSwitch.md) - Toggles two-state values with switch semantics.
- [BbSwitchGroup](./BbSwitchGroup.md) - Manages grouped switch options with shared behavior.

## Components (Reference Only - Internal)

Do not use these components directly in consumer code unless the user explicitly asks for internal composition details.

### Feedback

- [ErrorIcon](./ErrorIcon.md) - Renders the reusable error-state icon glyph used in validation UIs.
- [WarningIcon](./WarningIcon.md) - Renders the reusable warning-state icon glyph used in validation UIs.

### Inputs

- [BbBaseColorPalette](./BbBaseColorPalette.md) - Internal low-level color palette panel used by BbColorPalette and BbColorInput.
- [ClearableButton](./ClearableButton.md) - Action button for clearing current input value.

### Layout & Utility

- [ChipsBox](./ChipsBox.md) - Layout helper for rendering chip collections.
- [CommaBox](./CommaBox.md) - Utility for comma-separated content rendering.
- [CommonInputWrapper](./CommonInputWrapper.md) - Shared wrapper utility for composed input controls.
- [GuidesComponent](./GuidesComponent.md) - Dev-only showcase that auto-collects examples/*.vue files with live preview and extractable source. Not part of the consumer API.
- [OptionsContainer](./OptionsContainer.md) - Container utility for option list composition.

### Overlay

- [CommonPopover](./CommonPopover.md) - Shared popover behavior and structure primitive.

### Reference Only - Base Primitive

- [BbBaseCheckbox](./BbBaseCheckbox.md) - Internal low-level checkbox primitive.
- [BbBaseCheckboxGroup](./BbBaseCheckboxGroup.md) - Internal low-level grouped checkbox primitive.
- [BbBaseColorInput](./BbBaseColorInput.md) - Internal low-level color input primitive.
- [BbBaseDatePicker](./BbBaseDatePicker.md) - Internal low-level date picker primitive.
- [BbBaseDatePickerInput](./BbBaseDatePickerInput.md) - Internal low-level date-picker input primitive.
- [BbBaseInputContainer](./BbBaseInputContainer.md) - Internal wrapper for labels, hints, validation, and shared input layout.
- [BbBaseNumberInput](./BbBaseNumberInput.md) - Internal low-level numeric input primitive.
- [BbBaseRadio](./BbBaseRadio.md) - Internal low-level radio primitive.
- [BbBaseRadioGroup](./BbBaseRadioGroup.md) - Internal low-level radio-group primitive.
- [BbBaseRating](./BbBaseRating.md) - Internal low-level rating primitive.
- [BbBaseSelect](./BbBaseSelect.md) - Internal low-level select/listbox primitive.
- [BbBaseSlider](./BbBaseSlider.md) - Internal low-level slider primitive.
- [BbBaseSwitch](./BbBaseSwitch.md) - Internal low-level switch primitive.
- [BbBaseSwitchGroup](./BbBaseSwitchGroup.md) - Internal low-level grouped switch primitive.
- [BbBaseTag](./BbBaseTag.md) - Internal low-level tag input primitive.
- [BbBaseTextarea](./BbBaseTextarea.md) - Internal low-level textarea primitive.
- [BbBaseTextInput](./BbBaseTextInput.md) - Internal low-level text input primitive.
- [BbBaseTimePickerInput](./BbBaseTimePickerInput.md) - Internal low-level time-picker input primitive.

### Selection

- [FlatListBox](./FlatListBox.md) - Flat listbox renderer for selectable option lists.
- [GroupedListBox](./GroupedListBox.md) - Grouped listbox renderer for categorized options.
- [ListBox](./ListBox.md) - Accessible listbox interaction primitive.

## Composables

- [useBbConfig](./composables/useBbConfig.md) - Patch the library's runtime-editable configuration — today that is exactly one key, locale.
- [useBbFormContext](./composables/useBbFormContext.md) - Read and drive a BbForm from anywhere by id — validity, dirtiness, values, errors, plus submit/reset/validate — with no template ref and no shared subtree.
- [useBbTableContext](./composables/useBbTableContext.md) - Drive and read a BbTable's state (selection, sort, highlight, pagination) from anywhere by id — no prop drilling, no template refs.
- [useBbTabsContext](./composables/useBbTabsContext.md) - Read and drive a BbTabs/BbTabsRoot group from anywhere by id — writable current tab, goTo/select, no template refs.
- [useConfirm](./composables/useConfirm.md) - Promise-based confirm dialogs — await the user's yes/no, with yes/no button configs, async onClick busy states, and portal content. Requires exactly one <BbConfirm /> host, mounted at the app root.
- [useCountdown](./composables/useCountdown.md) - Reactive countdown timer with start, pause, reset, and formatted time output.
- [useId](./composables/useId.md) - Generate a unique, hydration-safe DOM id (prefixed bb-ui-) for aria wiring in custom markup.
- [useMobile](./composables/useMobile.md) - Reactive isMobile flag using the same viewport breakpoint the library's adaptive components use.
- [useSafeArea](./composables/useSafeArea.md) - Declare that an app-side docked panel occupies a screen edge, so toasts slide clear of it instead of landing on top.
- [useToast](./composables/useToast.md) - Fire, update, and dismiss transient toast notifications from anywhere — returns { toast, dismiss, update }. Requires exactly one <BbToast /> host, mounted at the app root.

## Guides

- [Agent Contract](./guides/agent-contract.md) - Mandatory rules for AI agents using bitboss-ui in consumer projects.
- [AI Router](./guides/ai-router.md) - Tiny start-here map for any coding agent — which file to open next, in which order, without loading the full catalogue.
- [App Layout](./guides/app-layout.md) - App-side chrome around every page — collapsible left nav sidebar and a fat footer, owning the page's one <main> landmark and the CSS hooks (.layout--sidebar-expanded, --sidebar-max-w) that size the nav.
- [Coherence Playbook](./guides/coherence-playbook.md) - Declarative coherence for tied inputs — enforce-coherence, dependencies and debounce props instead of manual watchers, with per-component availability.
- [Component Picker](./guides/component-picker.md) - Decision guide for choosing the right component for common UI needs.
- [Design Language](./guides/design-language.md) - Token vocabulary, variants, sizing, dark mode, and how to style around the components when building on-system UIs.
- [Design Tokens](./guides/design-tokens.md) - The token architecture of bitboss-ui — tiers, naming rules, the emphasis ladder, and the theming contract.
- [Fetch Data Items Playbook](./guides/fetch-items-playbook.md) - Item-provider signatures as actually invoked per component family, prefill semantics, dependencies-driven refetching, and canonical API request patterns.
- [Floating Bottom Panel](./guides/floating-bottom-panel.md) - App-side selection action bar — a panel-colored dock that floats up from the bottom when table rows are selected and dispatches bulk actions. The implementation ships in the per-platform Layout Scaffold recipe; this guide covers when and how to use it.
- [Icons Policy](./guides/icons-policy.md) - Provider-first icon usage (`lucide:*` via `@iconify-json/*` packages), `local:*` for brand art, how the plugin resolves names, and a catalog of every surface that accepts an icon.
- [Inertia Helpers](./guides/inertia-helpers.md) - App-side toolkit for Laravel + Inertia apps — typed page props, lazy props, URL-driven filters, paginated/selection page contexts, promise forms, and navigation guards that pair with bitboss-ui pages.
- [Inline Edit Playbook](./guides/inline-edit-playbook.md) - Who owns the edit? Choosing between draft-map, autosave, and write-back persistence for inline-editing tables — commit rules per control kind, optimistic overlays with rollback, and the dirty-ring / chevron-to-spinner feedback grammar.
- [Installation and Plugin Setup](./guides/installation-and-plugin-setup.md) - Canonical installation, style handling, and full plugin option reference for Vite, Nuxt, and Inertia consumers.
- [Migration v2 → v3](./guides/migration/v2-to-v3.md) - Complete upgrade guide from bitboss-ui 2.x to 3.0 — plugin-based setup, token overhaul, variant registries, global behavioral changes, and the silent-failure audit playbook.
- [Migration v2→v3: BbAlert](./guides/migration/components/bb-alert.md) - showClose inverted to hideClose, theme replaced by typed variant.
- [Migration v2→v3: BbAvatar](./guides/migration/components/bb-avatar.md) - The color prop is removed — retheme the fallback through the --bg-color / --text-color locals.
- [Migration v2→v3: BbBadge (and where your v2 badges went)](./guides/migration/components/bb-badge.md) - The v2 BbBadge (floating count/dot) is now BbIndicator; the v3 BbBadge is a new inline pill that also replaces BbChip.
- [Migration v2→v3: BbBreadcrumbs](./guides/migration/components/bb-breadcrumbs.md) - Item keys must be strings, the text divider prop is gone, per-item slot names are normalized.
- [Migration v2→v3: BbButton](./guides/migration/components/bb-button.md) - Async click handlers now auto-track loading (behavior flip), built-in tooltip props removed, variant locked to the registry.
- [Migration v2→v3: BbCheckbox / BbRadio / BbSwitch](./guides/migration/components/bb-checkbox.md) - reverse polarity inverted (explicit values flip, default layout unchanged), checked narrowed to boolean, color removed, BbRadio's name no longer required.
- [Migration v2→v3: BbCheckboxGroup / BbRadioGroup / BbSwitchGroup](./guides/migration/components/bb-checkbox-group.md) - labelPosition renamed legendPosition, per-item disabled is now inert (use selectable), color and the option affix slots removed, BbRadioGroup's name no longer required, and the shared bb-cr-container CSS block split into one per group.
- [Migration v2→v3: BbChip (removed)](./guides/migration/components/bb-chip.md) - BbChip is gone — BbBadge with clearable is the replacement; non-clearable chips were badges all along.
- [Migration v2→v3: BbCollapsible](./guides/migration/components/bb-collapsible.md) - The tag prop is removed; the root is always a span.
- [Migration v2→v3: BbColorInput](./guides/migration/components/bb-color-input.md) - picker renamed to eyeDropper.
- [Migration v2→v3: BbColorPalette](./guides/migration/components/bb-color-palette.md) - flip inverted to disableFlip, showArrow removed, picker renamed eyeDropper, update:open dropped, model updates never emit null.
- [Migration v2→v3: BbDatePickerInput](./guides/migration/components/bb-date-picker-input.md) - allowWriting inverted to disableWriting and hidePopover renamed to disableCalendar, both with a changed token set; the width prop is removed; adaptive mobile sheet by default; non-floating output carries the local offset instead of UTC `Z` (new `utc` prop restores v2 output).
- [Migration v2→v3: BbDialog](./guides/migration/components/bb-dialog.md) - showClose inverted to hideClose, several presentation props and the #close/#description slots removed, default widths changed, adaptive bottom sheet on mobile by default, --bb-dialog-* tokens replaced by --bb-panel-p plus locals.
- [Migration v2→v3: BbDropdown](./guides/migration/components/bb-dropdown.md) - Items now expect text as the label and can carry variants/submenus; arrowPadding removed; adaptive mobile sheet on by default.
- [Migration v2→v3: BbDropdownButton](./guides/migration/components/bb-dropdown-button.md) - autoLoading renamed to disableAutoLoading, disabledWhileLoading and theme removed.
- [Migration v2→v3: BbDropzone](./guides/migration/components/bb-dropzone.md) - modelValue is typed, accept no longer throws and takes bare tokens, and the hidden native-submit input only renders when name is set.
- [Migration v2→v3: BbIcon](./guides/migration/components/bb-icon.md) - The required prop is renamed type→icon, color is removed, and the xxl size key becomes 2xl.
- [Migration v2→v3: BbIntersection](./guides/migration/components/bb-intersection.md) - Removed with no replacement — it wrapped IntersectionObserver and carried no styling; use @vueuse/core's useIntersectionObserver.
- [Migration v2→v3: BbOffCanvas](./guides/migration/components/bb-offcanvas.md) - direction→side; showClose→hideClose; description and the #close/#description slots removed; size defaults change; adaptive drawer configs unify on offCanvasProps.
- [Migration v2→v3: BbPagination](./guides/migration/components/bb-pagination.md) - querykey renamed to queryKey; the loading prop is removed.
- [Migration v2→v3: BbPopover](./guides/migration/components/bb-popover.md) - Built-in close button, restoreFocus, theme, and the arrow are gone; close affordances move into your content.
- [Migration v2→v3: BbRating](./guides/migration/components/bb-rating.md) - color removed; name no longer required; the star state modifier renamed --highlighted to --filled/--empty; --bb-rating-size demoted to a local --size; input-position finally works.
- [Migration v2→v3: BbSelect](./guides/migration/components/bb-select.md) - allowWriting inverted to disableWriting, filterBy narrowed to string[], prefill value renamed, chevron/options slots removed, and two behavior changes (second click, mount-time coherence).
- [Migration v2→v3: BbSelectPopover](./guides/migration/components/bb-select-popover.md) - flip and allowWriting inverted, arrow props removed, filterBy narrowed, options slots replaced by header/footer; shares BbSelect's behavior changes.
- [Migration v2→v3: BbSlider](./guides/migration/components/bb-slider.md) - thumbTranslate inverted to disableThumbTranslate; string model values and color removed.
- [Migration v2→v3: BbSmoothHeight](./guides/migration/components/bb-smooth-height.md) - The `tag` prop is narrowed to `div | span`, and the inner measuring element now mirrors it instead of always being a `<div>`.
- [Migration v2→v3: BbSpinner](./guides/migration/components/bb-spinner.md) - The color prop is removed; spinners follow currentColor.
- [Migration v2→v3: BbTable](./guides/migration/components/bb-table.md) - The table renders as a CSS grid of divs with ARIA roles, not a <table> — every element selector (table/thead/tbody/tr/th/td) under .bb-table matches nothing, #thead/#tbody/#tfoot take role-complete div rows, --fill/--natural-width are gone, column widths drift within documented bounds, copy-to-spreadsheet and print header repetition degrade; allowSelectAll inverted to disableSelectAll; loading no longer blanks populated tables and now inerts rows; #loading is first-load-only; #no-data fills a full-width cell instead of replacing the row; row events drop the selected argument; columns gained sortable + rowClass, which collide with same-named consumer fields.
- [Migration v2→v3: BbTabs (was BbTab)](./guides/migration/components/bb-tabs.md) - Component renamed; querykey→queryKey; animations default on; label slots renamed and all dynamic names/URL slugs normalized; the entire .bb-tab BEM tree renamed to .bb-tabs / .bb-tabs-list / .bb-tabs-panes.
- [Migration v2→v3: BbTag](./guides/migration/components/bb-tag.md) - modelValue is strictly string[] now, multiple is removed, and duplicates are rejected case-insensitively by default.
- [Migration v2→v3: BbTextInput](./guides/migration/components/bb-text-input.md) - The type prop narrows to the text-like input types — number/date values must move to their dedicated components; a bare `floating` attribute was never a prop, the spelling is label-mode="floating".
- [Migration v2→v3: BbToast and toast()](./guides/migration/components/bb-toast.md) - Host placement becomes position with a corner-based value set; toast() options rewritten (variant, duration, actions, portal).
- [Migration v2→v3: BbTooltip](./guides/migration/components/bb-tooltip.md) - timeout renamed to delay; theme replaced by typed variant; hideArrow is now a declared prop; block removed; modelValue is new.
- [Migration v2→v3: BbTree](./guides/migration/components/bb-tree.md) - Item model rewritten — payload moves under meta, open becomes expanded, identifier becomes itemValue, expansion is a v-model.
- [Migration v2→v3: confirm() / useConfirm](./guides/migration/components/use-confirm.md) - yesText/onYes/noText/onNo collapse into yes/no configs, actions becomes an array-or-false, theme→variant, timeout→duration, autoClose flips to default-true, labels are localized, footer buttons default md.
- [Migration v2→v3: useBroadcastChannelInstance](./guides/migration/components/use-broadcast-channel-instance.md) - Removed — cross-tab messaging is not a UI concern; use useBroadcastChannel from @vueuse/core.
- [Options and Items Playbook](./guides/options-items-playbook.md) - How item-driven components turn raw domain items into options — mapping, value identity, model seeding, and the supported ways to disable choices.
- [Page Shell](./guides/page-shell.md) - App-side page layout — topbar, content, and a right details sidebar driven by a stack-based context (push a record to peek it, pop to go back). The implementation ships in the per-platform Layout Scaffold recipe; this guide covers when and how to use it.
- [Validated Forms (vee-validate)](./guides/validated-forms.md) - The `bitboss-ui/validated` entrypoint — form controls pre-wired to vee-validate. Global rules give an effort-free `rules="required|email"` string syntax; BbForm hosts the form; requiredAsterisk marks required fields.

---

<!-- dist/ai/ListBox.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/ListBox.md -->

# ListBox

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Selection**
- Description: Accessible listbox interaction primitive.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/ListBox.md](./source/ListBox.md)

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `compact` | `boolean \| undefined` | `false` |  | Sets the listbox in a compact state. |
| `groups` | `GroupedOptions[] \| undefined` |  |  | Grouped option list. When provided, the grouped listbox is rendered. |
| `headerHeight` | `number \| undefined` |  |  | Height of group headers in the listbox (px). |
| `id` | `string \| undefined` |  |  | Id applied to the `role="listbox"` element itself (not the wrapper), so a combobox's `aria-controls` reference resolves to the listbox role. |
| `loading` | `boolean \| undefined` | `false` |  | Shows the listbox in a loading state. |
| `loadingText` | `string \| undefined` |  |  | Text shown while options are loading. |
| `multiple` | `boolean \| undefined` | `false` |  | Allows multiple options to be selected simultaneously. |
| `noDataText` | `string \| undefined` |  |  | Text shown when no options are available. |
| `open` | `boolean \| undefined` | `false` |  | Whether the listbox is open (visible). |
| `optionHeight` | `number \| undefined` |  |  | Fixed height (in px) for each option row. Defaults to 28px (24px compact; 44px / 36px on mobile viewports). An explicit value wins on every viewport. |
| `options` | `Option<Item>[] \| undefined` |  |  | Flat option list. Used when `groups` is not provided. |
| `transitionDuration` | `number \| undefined` |  |  | Duration of open/close transition in milliseconds. |

## Events

- `focused:change` — `(e: "focused:change", id: string \| undefined): void` — Emitted when the keyboard-focused option changes.
- `option:selected` — `(e: "option:selected", option: Option): void` — Emitted when an option is selected by the user.
- `option:unselected` — `(e: "option:unselected", option: Option): void` — Emitted when a previously selected option is deselected.

## Slots

- `group` — scope: `ListBoxGroupSlotProps<Item>` — Replaces the default group header (only used when `groups` is provided).
- `loading` — scope: `object` — Content shown while items are loading (replaces the default loading text).
- `no-data` — scope: `object` — Content shown when no options are available (replaces the default "no data" text).
- `option` — scope: `ListBoxOptionSlotProps<Item>` — Replaces the default rendering of each option row.
- `options:append` — scope: `object` — Content appended inside the options list, after the last option or group.
- `options:prepend` — scope: `object` — Content prepended inside the options list, before the first option or group.

---

<!-- dist/ai/OptionsContainer.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/OptionsContainer.md -->

# OptionsContainer

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Layout & Utility**
- Description: Container utility for option list composition.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/OptionsContainer.md](./source/OptionsContainer.md)

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `classPrefix` | `string` |  | yes | Base class prefix applied to the root element and all internal elements. The parent passes its own BEM block name so the generated markup uses parent-scoped class names instead of the container's own namespace. |
| `direction` | `"horizontal" \| "vertical" \| undefined` |  |  | Direction of the layout of the inputs inside the fieldset. |
| `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
| `hasWarning` | `boolean \| undefined` | `false` |  | Define if the component should be in a warning state. Attaches a `--warnings` CSS class; suppressed when `hasErrors` is true. |
| `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides the label of the input while maintaining accessibility. |
| `loading` | `boolean \| undefined` | `false` |  | Shows the container in a loading state. |
| `loadingText` | `string \| undefined` |  |  | String displayed while items are being loaded. |
| `noDataText` | `string \| undefined` |  |  | String displayed when there are no items to display. |
| `options` | `Option<T>[]` |  | yes | List of options to render. |

## Events

- None.

## Slots

- `append` — scope: `object` — Content rendered after the last option, inside the options container.
- `input` — scope: `OptionsContainerInputSlotProps<T>` — The actual input element for each option (e.g. radio or checkbox).
- `label` — scope: `OptionsContainerLabelSlotProps<T>` — Replaces the default label text for each option.
- `loading` — scope: `object` — Content shown while options are loading (replaces the default loading text).
- `no-data` — scope: `object` — Content shown when no options are available (replaces the default "no data" text).
- `prepend` — scope: `object` — Content rendered before the first option, inside the options container.

---

<!-- dist/ai/recipes/inertia/approvals-inbox.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/inertia/approvals-inbox.md -->

# Recipe: Approvals Inbox (Inertia)

The densest advanced-page recipe in the folder, adapted for **Laravel +
Inertia**: the same Linear-triage × Expensify-approvals expense inbox —
`keyboard-navigation` with the highlight driving the peek, one-click
approve, reject-with-reason and snooze dialogs, a floating bulk-action bar
with select-all-across-pages, and an `A`/`R`/`S` shortcut bar — but the list
is a page prop via [`useTableContext`](../../guides/inertia-helpers.md),
filters mirror into the URL through
[`useQueryObject`](../../guides/inertia-helpers.md), tabs are real,
partial-reloaded server visits, and every mutation is a promise-wrapped
`router.visit`. Anatomy, components, the context shape, copy and data are
identical to the Vue recipe; only the data/URL/mutation layer changes.

Sibling recipes: [Vue](../vue/approvals-inbox.md) ·
[Nuxt](../nuxt/approvals-inbox.md).

## Prerequisites

> **The inline shortcut bar here is the exception, not the default.** This is a
> triage queue: the bindings _are_ the primary UI, so they stay on screen. Every
> other screen puts shortcuts behind the topbar keyboard popover documented in
> the [Layout Scaffold](./layout-scaffold.md) — a permanent hint bar is chrome
> for information read once.

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell`, `usePageShellContext` and `FloatingBottomPanel` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
- `<BbConfirm />` and `<BbToast />` mounted once in the `createInertiaApp` render root — never in a page.
- From the [Inertia Helpers](../../guides/inertia-helpers.md) toolkit:
  `useTableContext`, `useQueryObject`, `useResourceContext`, `useProp`,
  `useQuery`.
- Controller: `Inertia::render('Approvals/Index', ['expenses' =>
ExpensePaginator::make(...), 'tabCounts' => [...]])` — `expenses` is a
  standard Laravel paginator (`PaginatedResponse<Expense>`) and `tabCounts`
  a plain `{ needsApproval, approved, rejected, all }` map. Both are re-sent
  on every partial reload the page triggers
  (`only: ['expenses', 'tabCounts']`). Mutation routes are plain Laravel
  routes (`PATCH /expenses/:id/approve`, `POST /expenses/:id/reject`,
  `PATCH /expenses/:id/snooze`, `PATCH /expenses/bulk/approve`,
  `POST /expenses/bulk/reject`) that redirect back; small JSON GET
  endpoints (`GET /expenses/:id/peek`, `GET /submitters/:id/peek`,
  `GET /submitters/search`) back the sidebar peeks and the submitter filter
  pill so opening one is not a full-page visit.

## Key ideas

- **Highlight drives the peek — but it is a plain local ref here.** The
  Inertia data context (`useTableContext`) mirrors only what the server
  sent (items, pagination, selection); it has no concept of "the row under
  the roving tabindex" because the server never sends that. So
  `ctx.highlighted` is a small local ref bound to `BbTable`'s own
  `v-model:highlighted`, watched in `context.ts` exactly like the Vue/Nuxt
  `table.highlighted` — every highlight change still replaces the
  sidebar's stack with that expense, and `keyboard-navigation`'s
  Enter/Space still shares the mouse's code path for free.
- **One coopting page context.** `provideApprovalsInbox()` joins the
  page-shell stack **and** the keyed `useTableContext('expenses')` once,
  owns filters/tab/dialogs/highlight, and exposes complete actions. Every
  leaf calls `useApprovalsInbox()` and nothing else.
- **The table has no client-side fetch at all.** `expenses` arrives as a
  page prop; `useTableContext('expenses')` turns it into `items` +
  `totalItems`/`page`/`perPage` (URL-backed) + `selected`/`unselected`/`all`
  (select-all-across-pages), and `BbTable` binds directly to that handle —
  no `dependencies`, no items function.
- **Filters mirror into the URL with `useQueryObject`.** Typing in a pill
  filter performs a partial Inertia visit
  (`only: ['expenses', 'tabCounts']`); the server is the single source of
  filtered, paginated truth.
- **Tabs are real visits.** `BbTabs` items carry `href` + `server: true`
  (component-level `navigation` is required alongside it) so switching tabs
  is a genuine, partial-reloaded Inertia visit — not a client-only URL
  change.
- **Mutations are promise-wrapped `router.visit` calls.** A tiny local
  `visit()` helper turns Inertia's callback-based API into a promise, so
  context actions stay `async function`s exactly like the Vue/Nuxt
  versions — `await ctx.approve(...)` reads the same everywhere.
- **Three dispatch surfaces, one set of actions.** Approve / reject /
  snooze are reachable from the row, from inside the peek, and from the
  `A`/`R`/`S` keyboard shortcuts — all three call the exact same context
  functions (`approve`, `openReject`, `openSnooze`), so there is exactly
  one place each action's visit, refresh and toast live.
- **Reason and date are dialogs, not confirms.** Reject needs a typed
  reason and snooze needs a date, so both open a small `BbDialog` (the
  dialog itself is the confirmation gate) — a plain `useConfirm` is
  reserved for actions that need no input.
- **Bulk actions carry the full select-all-across-pages payload**
  (`ids`/`all`/`unselected`) so "select all, deselect three, approve" sends
  the same semantics the table itself models.
- **The shortcut bar mirrors `useDeleteCmd`'s guard.** A small keydown
  handler in the context checks `isInteractiveElementFocused()` before
  firing — typing "reason" in the reject textarea never triggers `R`. This
  code is byte-for-byte identical across all three platforms.
- **Clicking a submitter's name always stacks**, fetched from a small JSON
  endpoint via `useResourceContext` — not a full-page visit, so opening the
  sidebar never replaces the list underneath it.
- **Buttons are `md` by default**; `sm`/`xs` apply only where the doctrine
  allows it — table rows, the peek footers, the bulk bar, the shortcut bar.

## Page anatomy

```
ApprovalsInbox/
	Index.vue            ← assembly: PageShell slots, table, tabs, pagination
	context.ts            ← coopting page context (shell + useTableContext + filters + highlight + shortcuts + actions)
	FilterRail.vue         ← pill filters + clear-all
	ShortcutsHint.vue       ← A / R / S icon buttons, tooltip-labelled, act on the highlighted row
	ReceiptThumbnail.vue   ← receipt image/placeholder cell
	RowActions.vue         ← per-row approve / reject / snooze icon buttons
	SelectionBar.vue       ← bulk approve / reject in the floating bottom panel
	RejectDialog.vue       ← single-row reject, required reason
	BulkRejectDialog.vue   ← bulk reject, required reason
	SnoozeDialog.vue       ← single-row snooze, date picker
	ExpensePeek.vue         ← sidebar workbench, stack level 1 (opens from highlight)
	SubmitterPeek.vue       ← stacked peek, back arrow via the shell
```

Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
(left nav + fat footer), [Page Shell](../../guides/page-shell.md),
[Floating Bottom Panel](../../guides/floating-bottom-panel.md).

## Action inventory

| #   | Action                           | Trigger                                                | Mechanism                                                       |
| --- | -------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------- |
| 1   | Page search (merchant/submitter) | topbar right                                           | `filters.search` → `useQueryObject` partial visit               |
| 2   | Filter by submitter              | filter rail pill                                       | `BbSelectPopover` single, query-aware (small JSON endpoint)     |
| 3   | Filter by category               | filter rail pill                                       | `BbSelectPopover` multiple                                      |
| 4   | Quick filter: amount over        | filter rail pill                                       | `BbSelectPopover` single, preset thresholds                     |
| 5   | Clear filters                    | rail right (only when active)                          | context `clearFilters()`                                        |
| 6   | Switch tab                       | server-visit tabs with counts                          | `BbTabs` `href` + `server: true` visit                          |
| 7   | Arrow through rows               | `keyboard-navigation` roving tabindex                  | table's own Arrow/Home/End                                      |
| 8   | Preview an expense               | highlight a row (click, Enter/Space, arrow-then-Enter) | `ctx.highlighted` watcher → `peekExpense` (replace), JSON fetch |
| 9   | Approve (one click)              | row icon button, peek footer, key `A`                  | `approve(expense)` — promise-wrapped visit + toast              |
| 10  | Reject with reason               | row icon button, peek footer, key `R`                  | `openReject` → `RejectDialog` (required `BbTextarea`)           |
| 11  | Snooze                           | row icon button, peek footer, key `S`                  | `openSnooze` → `SnoozeDialog` (`BbDatePickerInput`)             |
| 12  | Select rows / select all         | table checkboxes                                       | `useTableContext` selection (across pages)                      |
| 13  | Bulk approve                     | floating bottom panel                                  | `bulkApprove()` on `table.selected`/`all`/`unselected`          |
| 14  | Bulk reject with reason          | floating bottom panel                                  | `BulkRejectDialog`, destructive                                 |
| 15  | Stack a submitter                | submitter cell / peek property                         | `stackSubmitter(id)` → shell stack, JSON fetch                  |
| 16  | Stack an expense from a profile  | recent-expense row inside `SubmitterPeek`              | `stackExpense(id)` → shell stack, JSON fetch                    |
| 17  | View full-size receipt           | peek "View receipt" link                               | navigation (`href`, new tab)                                    |
| 18  | Open full expense                | peek footer                                            | navigation (`href="/expenses/:id"`)                             |
| 19  | Back / close peek                | shell chrome                                           | shell stack pop / close                                         |

Nineteen distinct actions, spanning inline one-click mutation (9),
input-gated mutation via dialog (10, 11, 14), bulk mutation (13, 14),
keyboard dispatch (7, 9, 10, 11), navigation (17, 18, 19) and contextual
drill-down (15, 16) — well past the ≥ 12 bar.

## The code

### context.ts

```ts
// ApprovalsInbox/context.ts
import {
	computed,
	inject,
	provide,
	reactive,
	ref,
	watch,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import { router } from '@inertiajs/vue3';
import type { RequestPayload } from '@inertiajs/core';
import { useMagicKeys, whenever } from '@vueuse/core';
import { useConfirm, useToast } from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import {
	useTableContext,
	type TableContext,
} from '@/composables/useTableContext';
import { useQueryObject } from '@/composables/useQueryObject';
import { useProp } from '@/composables/useProp';
import { useQuery } from '@/composables/useQuery';
import type { Expense, ExpenseCategory } from '@/types';

/** What the stacked sidebar can show. Clicking a name pushes one of these. */
export type PeekItem =
	| { type: 'expense'; id: number }
	| { type: 'submitter'; id: number };

export type ApprovalsTab = 'needsApproval' | 'approved' | 'rejected' | 'all';

export interface ApprovalsFilters {
	search: string;
	submitterId: number | null;
	categories: ExpenseCategory[];
	/** Preset threshold from the quick filter (`50`, `100`, `250`…), or `null`. */
	amountOver: number | null;
}

const RELOAD_PROPS = ['expenses', 'tabCounts'] as const;

export interface ApprovalsInboxContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	table: TableContext<Expense, number>;
	/**
	 * The row under the roving tabindex. A plain local ref — the data context
	 * above mirrors only what the server sent, and highlight is not server
	 * data — bound to `BbTable`'s own `v-model:highlighted`.
	 */
	highlighted: Ref<number | null>;
	// -- Page-owned state --------------------------------------------------------
	filters: ApprovalsFilters;
	hasActiveFilters: ComputedRef<boolean>;
	tab: Ref<ApprovalsTab>;
	tabCounts: ComputedRef<Record<ApprovalsTab, number>>;
	dialogs: {
		reject: Ref<Expense | null>;
		bulkReject: Ref<boolean>;
		snooze: Ref<Expense | null>;
	};
	/** Bumped after every mutation — peeks watch it to re-fetch their JSON detail. */
	refreshKey: Ref<number>;
	/** The expense under the roving tabindex, resolved from the current page's items. */
	highlightedExpense: ComputedRef<Expense | null>;
	// -- Peek grammar ----------------------------------------------------------
	// (peekExpense — the highlight-driven replace — is internal to the watcher
	// below, not part of the public surface: leaves never open the peek
	// directly, only highlight drives it.)
	stackExpense: (id: number) => void;
	stackSubmitter: (id: number) => void;
	// -- Actions (complete: visit + refresh + toast) -----------------------------
	clearFilters: () => void;
	approve: (expense: Expense) => Promise<void>;
	openReject: (expense: Expense) => void;
	reject: (expense: Expense, reason: string) => Promise<void>;
	openSnooze: (expense: Expense) => void;
	snooze: (expense: Expense, until: string) => Promise<void>;
	bulkApprove: () => Promise<void>;
	openBulkReject: () => void;
	bulkReject: (reason: string) => Promise<void>;
	// -- Keyboard-shortcut dispatch (mirrors the row/peek buttons) --------------
	approveHighlighted: () => void;
	rejectHighlighted: () => void;
	snoozeHighlighted: () => void;
}

const key: InjectionKey<ApprovalsInboxContext> = Symbol('approvals-inbox');

/** Mirrors `useDeleteCmd`'s guard: skip shortcuts while the user is typing. */
const isInteractiveElementFocused = (): boolean => {
	const active = document.activeElement;
	if (!active) return false;
	const tag = active.tagName.toLowerCase();
	if (tag === 'input' || tag === 'textarea' || tag === 'select') return true;
	return active.getAttribute('contenteditable') === 'true';
};

/** Comma-joined query value → typed array (or `[]` when absent). */
const toArray = <T = string>(value: unknown): T[] => {
	if (value == null || value === '') return [];
	const raw = Array.isArray(value) ? value : String(value).split(',');
	return raw as T[];
};

/** Inertia's callback-based visit, wrapped as a promise — so every context
 * action stays `async`, exactly like the Vue/Nuxt versions. Always a
 * partial reload of the props this page depends on. */
const visit = (
	method: 'post' | 'put' | 'patch' | 'delete',
	url: string,
	// Inertia's own payload type — strings/numbers/booleans/arrays/files.
	// (`Record<string, unknown>` does not satisfy it.)
	data: RequestPayload = {}
): Promise<void> =>
	new Promise((resolve, reject) => {
		router.visit(url, {
			method,
			data,
			only: [...RELOAD_PROPS],
			preserveScroll: true,
			preserveState: true,
			onSuccess: () => resolve(),
			onError: (errors) => reject(errors),
		});
	});

export function provideApprovalsInbox(): ApprovalsInboxContext {
	const { toast } = useToast();
	const { confirm } = useConfirm();

	// -- Coopt the specific contexts: once, here, for the whole page. ----------
	const shell = usePageShellContext<PeekItem>();
	// `Expense, number`: BbTable's `item-value="id"` resolves selection to
	// expense ids, matching the Vue/Nuxt `table.selected: number[]` shape.
	const table = useTableContext<Expense, number>('expenses');
	// Highlight is not server data, so it does not live on `table` — a plain
	// local ref bound to BbTable's own `v-model:highlighted`.
	const highlighted = ref<number | null>(null);

	// -- Filters: seeded from the current URL, mirrored back by useQueryObject. -
	const query = useQuery();
	const filters = reactive<ApprovalsFilters>({
		search: (query.search as string) ?? '',
		submitterId: query.submitterId ? Number(query.submitterId) : null,
		categories: toArray<ExpenseCategory>(query.categories),
		amountOver: query.amountOver ? Number(query.amountOver) : null,
	});
	useQueryObject(filters, { only: [...RELOAD_PROPS] });

	const hasActiveFilters = computed(
		() =>
			filters.search !== '' ||
			filters.submitterId !== null ||
			filters.categories.length > 0 ||
			filters.amountOver !== null
	);
	const clearFilters = () => {
		filters.search = '';
		filters.submitterId = null;
		filters.categories = [];
		filters.amountOver = null;
	};

	// Tab: seeded from the URL; BbTabs' own `href` + `server` visit updates
	// the URL, and its `v-model` write keeps this ref in sync with the click.
	const tab = ref<ApprovalsTab>((query.tab as ApprovalsTab) ?? 'needsApproval');
	const tabCounts = useProp<Record<ApprovalsTab, number>>('tabCounts');

	const refreshKey = ref(0);
	const dialogs = {
		reject: ref<Expense | null>(null),
		bulkReject: ref(false),
		snooze: ref<Expense | null>(null),
	};

	// -- Peek grammar -----------------------------------------------------------------
	// peekX replaces the stack (from the list / highlight); stackX drills down.
	const peekExpense = (id: number) => shell.push({ type: 'expense', id }, true);
	const stackExpense = (id: number) => shell.push({ type: 'expense', id });
	const stackSubmitter = (id: number) => shell.push({ type: 'submitter', id });

	// Highlighting IS the peek trigger: arrowing (or clicking) a row opens it,
	// clearing the highlight closes it.
	watch(highlighted, (id) => {
		if (id == null) {
			shell.close();
		} else {
			peekExpense(id);
		}
	});

	const highlightedExpense = computed<Expense | null>(
		() =>
			table.items.value.find((expense) => expense.id === highlighted.value) ??
			null
	);

	// -- Actions ----------------------------------------------------------------------
	const refresh = () => {
		refreshKey.value++;
	};
	const clearSelection = () => {
		table.resetSelection();
	};

	const approve = async (expense: Expense) => {
		await visit('patch', `/expenses/${expense.id}/approve`);
		refresh();
		toast({
			title: `Approved ${expense.merchant} — $${expense.amount.toFixed(2)}.`,
			variant: 'success',
		});
	};

	const openReject = (expense: Expense) => {
		dialogs.reject.value = expense;
	};
	const reject = async (expense: Expense, reason: string) => {
		await visit('post', `/expenses/${expense.id}/reject`, { reason });
		dialogs.reject.value = null;
		refresh();
		toast({ title: `Rejected ${expense.merchant}.`, variant: 'success' });
	};

	const openSnooze = (expense: Expense) => {
		dialogs.snooze.value = expense;
	};
	const snooze = async (expense: Expense, until: string) => {
		await visit('patch', `/expenses/${expense.id}/snooze`, { until });
		dialogs.snooze.value = null;
		refresh();
		toast({ title: `${expense.merchant} snoozed.`, variant: 'success' });
	};

	// Bulk actions carry the full select-all-across-pages payload — the
	// server combines `all` + `unselected` the same way BbTable does.
	const bulkPayload = () => ({
		ids: table.selected.value,
		all: table.all.value,
		unselected: table.unselected.value,
	});
	const bulkCount = () =>
		table.all.value
			? table.totalItems.value - table.unselected.value.length
			: table.selected.value.length;

	const bulkApprove = async () => {
		const count = bulkCount();
		await visit('patch', '/expenses/bulk/approve', bulkPayload());
		clearSelection();
		refresh();
		toast({ title: `${count} expenses approved.`, variant: 'success' });
	};

	const openBulkReject = () => {
		dialogs.bulkReject.value = true;
	};
	const bulkReject = async (reason: string) => {
		const count = bulkCount();
		const ok = await confirm({
			variant: 'destructive',
			title: 'Reject expenses',
			text: `Reject ${count} expenses? The submitters are notified.`,
			yes: 'Reject',
			no: 'Cancel',
		});
		if (!ok) return;
		await visit('post', '/expenses/bulk/reject', { ...bulkPayload(), reason });
		dialogs.bulkReject.value = false;
		clearSelection();
		refresh();
		toast({ title: `${count} expenses rejected.`, variant: 'success' });
	};

	// -- Keyboard-shortcut dispatch: same actions, resolved against the row
	// under the roving tabindex. Guarded exactly like `useDeleteCmd`.
	const keys = useMagicKeys();
	const withHighlighted = (run: (expense: Expense) => void) => {
		if (isInteractiveElementFocused()) return;
		if (
			dialogs.reject.value ||
			dialogs.bulkReject.value ||
			dialogs.snooze.value
		)
			return;
		const expense = highlightedExpense.value;
		if (expense) run(expense);
	};
	const approveHighlighted = () =>
		withHighlighted((expense) => void approve(expense));
	const rejectHighlighted = () => withHighlighted(openReject);
	const snoozeHighlighted = () => withHighlighted(openSnooze);

	whenever(keys['a'], approveHighlighted);
	whenever(keys['r'], rejectHighlighted);
	whenever(keys['s'], snoozeHighlighted);

	const ctx: ApprovalsInboxContext = {
		shell,
		table,
		highlighted,
		filters,
		hasActiveFilters,
		tab,
		tabCounts,
		dialogs,
		refreshKey,
		highlightedExpense,
		stackExpense,
		stackSubmitter,
		clearFilters,
		approve,
		openReject,
		reject,
		openSnooze,
		snooze,
		bulkApprove,
		openBulkReject,
		bulkReject,
		approveHighlighted,
		rejectHighlighted,
		snoozeHighlighted,
	};
	provide(key, ctx);
	return ctx;
}

export function useApprovalsInbox(): ApprovalsInboxContext {
	const ctx = inject(key);
	if (!ctx)
		throw new Error('useApprovalsInbox() called outside ApprovalsInbox');
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- ApprovalsInbox/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left, page search right. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs
					class="min-w-0 flex-auto"
					:items="[
						{ key: 'dashboard', text: 'Dashboard', href: '/dashboard' },
						{ key: 'finance', text: 'Finance', href: '/finance' },
						{ key: 'approvals', text: 'Approvals' },
					]"
				/>
				<BbTextInput
					v-model="ctx.filters.search"
					autocomplete="off"
					class="shrink-0"
					clearable
					compact
					hide-label
					label="Search expenses"
					placeholder="Search merchant or submitter…"
					prepend:icon="lucide:search"
				/>
			</div>
		</template>

		<div class="flex flex-col gap-3 p-4">
			<FilterRail />

			<div class="flex items-center justify-between gap-2">
				<!-- Tabs are real visits: href + server (component-level `navigation`
				     is required alongside per-item `server`), each carrying the same
				     partial-reload prop list as the filter watcher. Each href is
				     built from `tabHref()`, NOT a bare `?tab=` literal:
				     `preserve-state` keeps `ctx.filters` alive across the visit, so
				     if the href dropped the filter query keys the server would
				     render an unfiltered page while the (unchanged) filter chips
				     kept claiming the old filters still applied. -->
				<BbTabs
					v-model="ctx.tab.value"
					compact
					navigation
					preserve-scroll
					preserve-state
					replace
					:items="[
						{
							key: 'needsApproval',
							label: `Needs approval · ${ctx.tabCounts.value.needsApproval}`,
							href: tabHref('needsApproval'),
							server: true,
							only: ['expenses', 'tabCounts'],
						},
						{
							key: 'approved',
							label: `Approved · ${ctx.tabCounts.value.approved}`,
							href: tabHref('approved'),
							server: true,
							only: ['expenses', 'tabCounts'],
						},
						{
							key: 'rejected',
							label: `Rejected · ${ctx.tabCounts.value.rejected}`,
							href: tabHref('rejected'),
							server: true,
							only: ['expenses', 'tabCounts'],
						},
						{
							key: 'all',
							label: `All · ${ctx.tabCounts.value.all}`,
							href: tabHref('all'),
							server: true,
							only: ['expenses', 'tabCounts'],
						},
					]"
				/>
				<ShortcutsHint />
			</div>

			<!-- No dependencies/items-fn: `expenses` is a page prop, selection
			     (across pages) binds straight onto the keyed table context, and
			     highlight is a plain local ref since the server never sends it. -->
			<BbTable
				v-model="ctx.table.selected.value"
				v-model:highlighted="ctx.highlighted.value"
				v-model:select-all="ctx.table.all.value"
				v-model:unselected-items="ctx.table.unselected.value"
				actions
				caption="Expense approvals"
				:columns="columns"
				compact
				item-value="id"
				:items="ctx.table.items.value"
				keyboard-navigation
				legend="Select expenses"
				loading-text="Loading expenses…"
				:row-class="rowClass"
				selectable
			>
				<template #receipt="{ item }">
					<ReceiptThumbnail :expense="item" />
				</template>

				<template #merchant="{ content }">
					<span class="font-medium">{{ content }}</span>
				</template>

				<template #submitter_name="{ item }">
					<BbButton
						size="sm"
						variant="ghost"
						@click="() => ctx.stackSubmitter(item.submitter.id)"
					>
						{{ item.submitter.name }}
					</BbButton>
				</template>

				<template #category="{ item }">
					<BbBadge variant="outline">{{ item.category }}</BbBadge>
				</template>

				<template #status="{ item }">
					<BbBadge variant="outline">{{ statusLabel(item.status) }}</BbBadge>
				</template>

				<template #actions="{ item }">
					<RowActions :expense="item" />
				</template>

				<template #no-data>
					<div class="flex flex-col items-center gap-2 p-6 text-center">
						<p class="text-sm text-[color:var(--bb-text-muted)]">
							No expenses match
							{{
								ctx.hasActiveFilters.value ? 'the current filters' : 'this tab'
							}}.
						</p>
						<BbButton
							v-if="ctx.hasActiveFilters.value"
							variant="ghost"
							@click="ctx.clearFilters"
						>
							Clear filters
						</BbButton>
					</div>
				</template>
			</BbTable>

			<!-- No table-id: the keyed table context is the page count here. -->
			<BbPagination
				v-model="ctx.table.page.value"
				label="Expense approvals pagination"
				:total-pages="ctx.table.totalPages.value"
			/>
		</div>

		<SelectionBar />

		<!-- Stacked peek sidebar: highlight opens the expense; names drill down. -->
		<template #sidebar>
			<ExpensePeek
				v-if="ctx.shell.current.value?.type === 'expense'"
				:expense-id="ctx.shell.current.value.id"
			/>
			<SubmitterPeek
				v-else-if="ctx.shell.current.value?.type === 'submitter'"
				:submitter-id="ctx.shell.current.value.id"
			/>
		</template>

		<template #dialogs>
			<RejectDialog />
			<BulkRejectDialog />
			<SnoozeDialog />
		</template>
	</PageShell>
</template>

<script setup lang="ts">
import {
	BbBadge,
	BbBreadcrumbs,
	BbButton,
	BbPagination,
	BbTable,
	BbTabs,
	BbTextInput,
} from 'bitboss-ui';
import qs from 'query-string';
import PageShell from '@/components/layout/PageShell.vue';
import { useQuery } from '@/composables/useQuery';
import { provideApprovalsInbox, type ApprovalsTab } from './context';
import BulkRejectDialog from './BulkRejectDialog.vue';
import ExpensePeek from './ExpensePeek.vue';
import FilterRail from './FilterRail.vue';
import ReceiptThumbnail from './ReceiptThumbnail.vue';
import RejectDialog from './RejectDialog.vue';
import RowActions from './RowActions.vue';
import SelectionBar from './SelectionBar.vue';
import ShortcutsHint from './ShortcutsHint.vue';
import SnoozeDialog from './SnoozeDialog.vue';
import SubmitterPeek from './SubmitterPeek.vue';
import type { Expense, ExpenseStatus } from '@/types';

const ctx = provideApprovalsInbox();

// Merge `tab` into the *current* query instead of replacing it: `useQuery()`
// reads the live URL, which already carries every filter `useQueryObject`
// mirrored there, so switching tabs keeps `search`/`submitterId`/
// `categories`/`amountOver` intact instead of silently resetting the results
// to unfiltered.
const tabHref = (tab: ApprovalsTab): string =>
	`/approvals?${qs.stringify({ ...useQuery(), tab }, { arrayFormat: 'comma' })}`;

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
const shortDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
	});
const statusLabel = (status: ExpenseStatus) =>
	({
		needsApproval: 'Needs approval',
		approved: 'Approved',
		rejected: 'Rejected',
		snoozed: 'Snoozed',
	})[status];

const columns = [
	{ key: 'receipt', label: 'Receipt', width: 48 },
	{ key: 'merchant', label: 'Merchant' },
	{ key: 'submitter.name', label: 'Submitter' },
	{ key: 'category', label: 'Category' },
	{
		key: 'amount',
		label: 'Amount',
		align: 'right' as const,
		formatter: (value: number) => currency.format(value),
	},
	{ key: 'submittedAt', label: 'Submitted', formatter: shortDate },
	{ key: 'status', label: 'Status' },
];

// A default highlight tint ships out of the box; row-class customizes it.
const rowClass = (item: Expense) =>
	ctx.highlighted.value === item.id
		? 'bg-indigo-50 dark:bg-indigo-950/20'
		: undefined;
</script>
```

### FilterRail.vue

```vue
<!-- ApprovalsInbox/FilterRail.vue -->
<template>
	<div class="flex flex-wrap items-center gap-2">
		<!-- Submitter: single, query-aware search against a small JSON endpoint. -->
		<BbSelectPopover
			v-model="ctx.filters.submitterId"
			item-text="name"
			item-value="id"
			:items="searchSubmitters"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filter by submitter"
					append:icon="lucide:chevron-down"
					size="sm"
					variant="outline"
				>
					{{ submitterLabel }}
				</BbButton>
			</template>
		</BbSelectPopover>

		<!-- Category: multi-select pill. -->
		<BbSelectPopover
			v-model="ctx.filters.categories"
			:items="['travel', 'meals', 'software', 'office', 'client', 'other']"
			multiple
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filter by category"
					append:icon="lucide:chevron-down"
					size="sm"
					variant="outline"
				>
					Category{{
						ctx.filters.categories.length
							? ` · ${ctx.filters.categories.length}`
							: ''
					}}
				</BbButton>
			</template>
		</BbSelectPopover>

		<!-- Amount over: a quick-filter pill from preset thresholds. -->
		<BbSelectPopover
			v-model="ctx.filters.amountOver"
			disable-writing
			:items="[50, 100, 250, 500, 1000]"
			width="160px"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filter by amount"
					append:icon="lucide:chevron-down"
					size="sm"
					variant="outline"
				>
					{{
						ctx.filters.amountOver
							? `Over $${ctx.filters.amountOver}`
							: 'Amount'
					}}
				</BbButton>
			</template>
		</BbSelectPopover>

		<!-- Clear-all renders only while something is active. -->
		<BbButton
			v-if="ctx.hasActiveFilters.value"
			class="ml-auto"
			prepend:icon="lucide:x"
			size="sm"
			variant="ghost"
			@click="ctx.clearFilters"
		>
			Clear filters
		</BbButton>
	</div>
</template>

<script setup lang="ts">
import { computed, ref, watchEffect } from 'vue';
import { BbButton, BbSelectPopover } from 'bitboss-ui';
import { useApprovalsInbox } from './context';
import type { Submitter } from '@/types';

const ctx = useApprovalsInbox();

// Query-aware items function: BbSelectPopover calls it with the search text.
// A small JSON endpoint, not an Inertia visit — searching a filter pill
// must not re-render the page.
const searchSubmitters = (query: string): Promise<Submitter[]> =>
	fetch(`/submitters/search?q=${encodeURIComponent(query)}`).then((res) =>
		res.json()
	);

// The trigger labels itself from page state (the popover is lazy by design
// and cannot know the selected label before its first open).
const selectedSubmitter = ref<Submitter | null>(null);
watchEffect(async () => {
	selectedSubmitter.value =
		ctx.filters.submitterId == null
			? null
			: await fetch(`/submitters/${ctx.filters.submitterId}/peek`).then((res) =>
					res.json()
				);
});
const submitterLabel = computed(
	() => selectedSubmitter.value?.name ?? 'Submitter'
);
</script>
```

### ShortcutsHint.vue

```vue
<!-- ApprovalsInbox/ShortcutsHint.vue -->
<template>
	<div class="flex items-center gap-1">
		<span class="mr-1 text-xs text-[color:var(--bb-text-muted)]"
			>Shortcuts</span
		>
		<BbTooltip>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Approve highlighted expense"
					:disabled="!ctx.highlightedExpense.value"
					icon="lucide:check"
					size="xs"
					variant="ghost"
					@click="ctx.approveHighlighted"
				/>
			</template>
			<span class="flex items-center gap-1.5">
				Approve
				<kbd
					class="rounded border border-current px-1 font-mono text-[10px] leading-4 opacity-75"
					>A</kbd
				>
			</span>
		</BbTooltip>
		<BbTooltip>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Reject highlighted expense"
					:disabled="!ctx.highlightedExpense.value"
					icon="lucide:x"
					size="xs"
					variant="ghost"
					@click="ctx.rejectHighlighted"
				/>
			</template>
			<span class="flex items-center gap-1.5">
				Reject
				<kbd
					class="rounded border border-current px-1 font-mono text-[10px] leading-4 opacity-75"
					>R</kbd
				>
			</span>
		</BbTooltip>
		<BbTooltip>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Snooze highlighted expense"
					:disabled="!ctx.highlightedExpense.value"
					icon="lucide:clock"
					size="xs"
					variant="ghost"
					@click="ctx.snoozeHighlighted"
				/>
			</template>
			<span class="flex items-center gap-1.5">
				Snooze
				<kbd
					class="rounded border border-current px-1 font-mono text-[10px] leading-4 opacity-75"
					>S</kbd
				>
			</span>
		</BbTooltip>
	</div>
</template>

<script setup lang="ts">
import { BbButton, BbTooltip } from 'bitboss-ui';
import { useApprovalsInbox } from './context';

const ctx = useApprovalsInbox();
</script>
```

### ReceiptThumbnail.vue

```vue
<!-- ApprovalsInbox/ReceiptThumbnail.vue -->
<template>
	<img
		v-if="expense.receiptUrl"
		:alt="`Receipt from ${expense.merchant}`"
		class="h-8 w-8 rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] object-cover"
		:src="expense.receiptUrl"
	/>
	<div
		v-else
		aria-hidden="true"
		class="flex h-8 w-8 items-center justify-center rounded-[var(--bb-radius)] border border-dashed border-[color:var(--bb-border)] text-[color:var(--bb-text-muted)]"
	>
		<BbIcon icon="lucide:receipt" size="14" />
	</div>
</template>

<script setup lang="ts">
import { BbIcon } from 'bitboss-ui';
import type { Expense } from '@/types';

defineProps<{ expense: Expense }>();
</script>
```

### RowActions.vue

```vue
<!-- ApprovalsInbox/RowActions.vue -->
<template>
	<div class="flex items-center gap-1">
		<BbTooltip text="Approve">
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Approve"
					:disabled="resolved"
					icon="lucide:check"
					size="xs"
					variant="ghost"
					@click="() => ctx.approve(expense)"
				/>
			</template>
		</BbTooltip>
		<BbTooltip text="Reject">
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Reject"
					:disabled="resolved"
					icon="lucide:x"
					size="xs"
					variant="ghost"
					@click="() => ctx.openReject(expense)"
				/>
			</template>
		</BbTooltip>
		<BbTooltip text="Snooze">
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Snooze"
					:disabled="resolved"
					icon="lucide:clock"
					size="xs"
					variant="ghost"
					@click="() => ctx.openSnooze(expense)"
				/>
			</template>
		</BbTooltip>
	</div>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbTooltip } from 'bitboss-ui';
import { useApprovalsInbox } from './context';
import type { Expense } from '@/types';

const props = defineProps<{ expense: Expense }>();

const ctx = useApprovalsInbox();

const resolved = computed(
	() =>
		props.expense.status === 'approved' || props.expense.status === 'rejected'
);
</script>
```

### RejectDialog.vue

```vue
<!-- ApprovalsInbox/RejectDialog.vue -->
<template>
	<BbDialog
		:model-value="expense !== null"
		size="sm"
		:title="expense ? `Reject — ${expense.merchant}` : ''"
		@show="reason = ''"
		@update:model-value="close"
	>
		<form
			v-if="expense"
			class="flex flex-col gap-3"
			novalidate
			@submit.prevent="submit"
		>
			<BbTextarea
				v-model="reason"
				label="Reason"
				label-mode="outside"
				placeholder="Why is this expense being rejected?"
				rows="3"
			/>
			<div class="mt-1 flex justify-end gap-2">
				<BbButton type="button" variant="ghost" @click="close">Cancel</BbButton>
				<BbButton
					:disabled="reason.trim().length < 3"
					type="submit"
					variant="destructive"
				>
					Reject expense
				</BbButton>
			</div>
		</form>
	</BbDialog>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbButton, BbDialog, BbTextarea } from 'bitboss-ui';
import { useApprovalsInbox } from './context';

const ctx = useApprovalsInbox();

// The dialog's subject lives in the page context — the row action and the
// peek's reject button both just assign it.
const expense = computed(() => ctx.dialogs.reject.value);
const close = () => {
	ctx.dialogs.reject.value = null;
};

const reason = ref('');
const submit = () =>
	expense.value ? ctx.reject(expense.value, reason.value.trim()) : undefined;
</script>
```

### BulkRejectDialog.vue

```vue
<!-- ApprovalsInbox/BulkRejectDialog.vue -->
<template>
	<BbDialog
		:model-value="ctx.dialogs.bulkReject.value"
		size="sm"
		:title="`Reject ${count} expenses`"
		@show="reason = ''"
		@update:model-value="close"
	>
		<form class="flex flex-col gap-3" novalidate @submit.prevent="submit">
			<BbTextarea
				v-model="reason"
				label="Reason"
				label-mode="outside"
				placeholder="Applied to every selected expense."
				rows="3"
			/>
			<div class="mt-1 flex justify-end gap-2">
				<BbButton type="button" variant="ghost" @click="close">Cancel</BbButton>
				<BbButton
					:disabled="reason.trim().length < 3"
					type="submit"
					variant="destructive"
				>
					Reject {{ count }} expenses
				</BbButton>
			</div>
		</form>
	</BbDialog>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbButton, BbDialog, BbTextarea } from 'bitboss-ui';
import { useApprovalsInbox } from './context';

const ctx = useApprovalsInbox();

const count = computed(() => (ctx.table.selected.value as number[]).length);
const close = () => {
	ctx.dialogs.bulkReject.value = false;
};

const reason = ref('');
const submit = () => ctx.bulkReject(reason.value.trim());
</script>
```

### SnoozeDialog.vue

```vue
<!-- ApprovalsInbox/SnoozeDialog.vue -->
<template>
	<BbDialog
		:model-value="expense !== null"
		size="xs"
		:title="expense ? `Snooze — ${expense.merchant}` : ''"
		@show="until = tomorrow"
		@update:model-value="close"
	>
		<form
			v-if="expense"
			class="flex flex-col gap-3"
			novalidate
			@submit.prevent="submit"
		>
			<BbDatePickerInput
				v-model="until"
				floating
				label="Snooze until"
				label-mode="outside"
				:min="tomorrow"
			/>
			<div class="mt-1 flex justify-end gap-2">
				<BbButton type="button" variant="ghost" @click="close">Cancel</BbButton>
				<BbButton type="submit" variant="secondary">Snooze</BbButton>
			</div>
		</form>
	</BbDialog>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbButton, BbDatePickerInput, BbDialog } from 'bitboss-ui';
import { useApprovalsInbox } from './context';

const ctx = useApprovalsInbox();

const expense = computed(() => ctx.dialogs.snooze.value);
const close = () => {
	ctx.dialogs.snooze.value = null;
};

const tomorrow = new Date(Date.now() + 86_400_000).toISOString().slice(0, 10);
const until = ref(tomorrow);
const submit = () =>
	expense.value ? ctx.snooze(expense.value, until.value) : undefined;
</script>
```

### SelectionBar.vue

```vue
<!-- ApprovalsInbox/SelectionBar.vue -->
<template>
	<FloatingBottomPanel :open="selectedCount > 0">
		<span class="px-2 text-sm">{{ selectedCount }} selected</span>
		<BbButton
			prepend:icon="lucide:check"
			size="sm"
			variant="ghost"
			@click="ctx.bulkApprove"
		>
			Approve
		</BbButton>
		<div class="floating-bottom-panel__right flex items-center gap-1">
			<BbButton size="sm" variant="destructive" @click="ctx.openBulkReject">
				Reject
			</BbButton>
			<BbButton
				aria-label="Clear selection"
				icon="lucide:x"
				size="sm"
				variant="ghost"
				@click="ctx.table.resetSelection"
			/>
		</div>
	</FloatingBottomPanel>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton } from 'bitboss-ui';
import { useApprovalsInbox } from './context';
import FloatingBottomPanel from '@/components/layout/FloatingBottomPanel.vue';

const ctx = useApprovalsInbox();

// `all` (select-all-across-pages) does not enumerate rows, so the visible
// count is the total minus whatever the user manually deselected.
const selectedCount = computed(() =>
	ctx.table.all.value
		? ctx.table.totalItems.value - ctx.table.unselected.value.length
		: ctx.table.selected.value.length
);
</script>
```

### ExpensePeek.vue

```vue
<!-- ApprovalsInbox/ExpensePeek.vue -->
<template>
	<div v-if="expense" class="flex flex-col gap-4 text-sm">
		<!-- Header: identity + amount + status. -->
		<header class="flex flex-col gap-1.5">
			<div class="flex items-center justify-between gap-2">
				<h2 class="text-base font-semibold">{{ expense.merchant }}</h2>
				<BbBadge variant="outline">{{ statusLabel(expense.status) }}</BbBadge>
			</div>
			<p class="text-xl font-semibold">{{ currency.format(expense.amount) }}</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Submitted {{ longDate(expense.submittedAt) }}
			</p>
		</header>

		<!-- Receipt: bigger than the row thumbnail, with a full-size link out. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Receipt
			</h3>
			<img
				v-if="expense.receiptUrl"
				:alt="`Receipt from ${expense.merchant}`"
				class="h-40 w-full rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] object-cover"
				:src="expense.receiptUrl"
			/>
			<p v-else class="text-xs text-[color:var(--bb-text-muted)]">
				No receipt attached.
			</p>
			<BbButton
				v-if="expense.receiptUrl"
				append:icon="lucide:arrow-up-right"
				:href="expense.receiptUrl"
				size="sm"
				target="_blank"
				variant="ghost"
			>
				View full-size receipt
			</BbButton>
		</section>

		<!-- Properties: submitter name drills DOWN — stacked peek, back arrow. -->
		<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
			<dt class="text-[color:var(--bb-text-muted)]">Submitter</dt>
			<dd>
				<!-- A person's NAME is an identity cell: an inline link, never a
				     padded button (BTG-015 / agent-contract § Inline Links). -->
				<BbBaseButton
					class="plain-link"
					@click="() => ctx.stackSubmitter(expense!.submitter.id)"
				>
					{{ expense.submitter.name }}
				</BbBaseButton>
			</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Category</dt>
			<dd class="capitalize">{{ expense.category }}</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Memo</dt>
			<dd>{{ expense.memo ?? '—' }}</dd>
		</dl>

		<!-- Activity feed. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Activity
			</h3>
			<ul class="flex flex-col gap-2">
				<li
					v-for="entry in expense.activity"
					:key="entry.id"
					class="flex gap-2"
				>
					<BbIcon
						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
						:icon="entry.icon"
						size="14"
					/>
					<div class="flex flex-col">
						<span>{{ entry.text }}</span>
						<span class="text-xs text-[color:var(--bb-text-muted)]"
							>{{ entry.actor }} · {{ longDate(entry.at) }}</span
						>
					</div>
				</li>
			</ul>
		</section>

		<!-- Peek is a workbench: the same three actions as the row, plus the real page. -->
		<footer class="mt-2 flex flex-wrap items-center gap-2 border-t pt-3">
			<BbButton
				:disabled="resolved"
				prepend:icon="lucide:check"
				size="sm"
				variant="secondary"
				@click="() => ctx.approve(expense!)"
			>
				Approve
			</BbButton>
			<BbButton
				:disabled="resolved"
				prepend:icon="lucide:x"
				size="sm"
				variant="destructive"
				@click="() => ctx.openReject(expense!)"
			>
				Reject
			</BbButton>
			<BbButton
				:disabled="resolved"
				prepend:icon="lucide:clock"
				size="sm"
				variant="outline"
				@click="() => ctx.openSnooze(expense!)"
			>
				Snooze
			</BbButton>
			<BbButton
				append:icon="lucide:arrow-up-right"
				class="ml-auto"
				:href="`/expenses/${expense.id}`"
				size="sm"
				variant="ghost"
			>
				Open full expense
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { computed, watch } from 'vue';
import { BbBadge, BbBaseButton, BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
import { useResourceContext } from '@/composables/useResourceContext';
import { useApprovalsInbox } from './context';
import type { ExpenseDetail, ExpenseStatus } from '@/types';

const props = defineProps<{ expenseId: number }>();

const ctx = useApprovalsInbox();

// A small JSON endpoint, not a page visit — opening the peek never
// re-renders the list underneath it. Re-fetches whenever the stack shows a
// different expense; `refreshKey` makes mutations (approve/reject/snooze)
// reflect here immediately.
const { data: expense, refresh } = useResourceContext<ExpenseDetail, number>(
	() => props.expenseId,
	(id) => fetch(`/expenses/${id}/peek`).then((res) => res.json())
);
watch(() => ctx.refreshKey.value, refresh);

const resolved = computed(
	() =>
		expense.value?.status === 'approved' || expense.value?.status === 'rejected'
);

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
const longDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
		year: 'numeric',
	});
const statusLabel = (status: ExpenseStatus) =>
	({
		needsApproval: 'Needs approval',
		approved: 'Approved',
		rejected: 'Rejected',
		snoozed: 'Snoozed',
	})[status];
</script>
```

### SubmitterPeek.vue

```vue
<!-- ApprovalsInbox/SubmitterPeek.vue -->
<template>
	<div v-if="submitter" class="flex flex-col gap-4 text-sm">
		<header class="flex items-center gap-3">
			<BbAvatar :alt="submitter.name" :src="submitter.avatarUrl" />
			<div class="flex flex-col">
				<h2 class="text-base font-semibold">{{ submitter.name }}</h2>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					{{ submitter.email }} · {{ submitter.team }}
				</p>
			</div>
		</header>

		<!-- Stat strip. -->
		<div class="grid grid-cols-3 gap-2">
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Submitted (YTD)</p>
				<p class="font-semibold">
					{{ currency.format(submitter.totalSubmitted) }}
				</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Pending</p>
				<p class="font-semibold">{{ submitter.pendingCount }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Approval rate</p>
				<p class="font-semibold">{{ submitter.approvalRate }}%</p>
			</div>
		</div>

		<!-- Recent expenses: names drill down again — the stack keeps growing. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Recent expenses
			</h3>
			<ul class="flex flex-col">
				<li
					v-for="recent in submitter.recentExpenses"
					:key="recent.id"
					class="flex items-center justify-between gap-2 border-b py-1.5 last:border-b-0"
				>
					<BbBaseButton
						class="plain-link"
						@click="() => ctx.stackExpense(recent.id)"
					>
						{{ recent.merchant }}
					</BbBaseButton>
					<BbBadge variant="outline">{{ recent.status }}</BbBadge>
					<span class="text-xs text-[color:var(--bb-text-muted)]">{{
						currency.format(recent.amount)
					}}</span>
				</li>
			</ul>
		</section>

		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				append:icon="lucide:arrow-up-right"
				:href="`/people/${submitter.id}`"
				size="sm"
				variant="ghost"
			>
				Open profile
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import {
	BbAvatar,
	BbBadge,
	BbBaseButton,
	BbButton,
	BbSpinner,
} from 'bitboss-ui';
import { useResourceContext } from '@/composables/useResourceContext';
import { useApprovalsInbox } from './context';
import type { SubmitterDetail } from '@/types';

const props = defineProps<{ submitterId: number }>();

const ctx = useApprovalsInbox();

const { data: submitter } = useResourceContext<SubmitterDetail, number>(
	() => props.submitterId,
	(id) => fetch(`/submitters/${id}/peek`).then((res) => res.json())
);

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
</script>
```

## Why it is built this way

- **The context coopts, leaves consume.** `shell` and the keyed
  `useTableContext('expenses')` are joined once in
  `provideApprovalsInbox()`; twelve components share filters, selection,
  highlight, the peek stack, the keyboard shortcuts and every action
  through one `useApprovalsInbox()` call.
- **Highlight is a plain local ref, not part of the data context.** Per
  the [Inertia Helpers](../../guides/inertia-helpers.md) rule of thumb, the
  keyed data contexts "own what the server sent" — items, pagination,
  selection — while anything the table widget does on its own (sort,
  highlight) is not server data. `ctx.highlighted` is bound to `BbTable`'s
  own `v-model:highlighted` and watched exactly like `table.highlighted`
  in the Vue/Nuxt recipes, so the peek grammar and the keyboard dispatch
  are unchanged.
- **`expenses` is a page prop, not a client fetch.** `useTableContext`
  turns the Laravel paginator into `items`/`totalItems`/`page`/`perPage`
  (URL-backed) plus `selected`/`unselected`/`all`; `BbTable` binds directly
  to that handle with `v-model`/`v-model:select-all`/`v-model:unselected-items`
  — there is no items function and no `dependencies` array, because the
  server already did the filtering, sorting and paging before the props
  arrived.
- **One watcher for filters, one visit mechanism for tabs.**
  `useQueryObject(filters, { only: ['expenses', 'tabCounts'] })` is the
  entire filter-to-URL wiring; `BbTabs`' `href` + `server: true` items (with
  the required component-level `navigation`) make tab switches real,
  partial-reloaded visits with the same `only` list — one source of
  server truth, reached two ways. Each `href` is built by `tabHref()`, which
  merges `tab` into the current query rather than replacing it — `href:
'/approvals?tab=all'` alone would drop every active filter, and because
  `preserve-state` keeps this page instance (and `ctx.filters`) alive across
  the visit, the chips would keep showing the old filters as active over an
  unfiltered result set.
- **The `visit()` helper is the promise-wrapped router-visit pattern**
  called for by the base recipe's platform notes: it turns Inertia's
  `onSuccess`/`onError` callbacks into a promise so every context action
  (`approve`, `reject`, `snooze`, the bulk actions, …) stays an `async
function` — identical call sites to the Vue/Nuxt recipes,
  `await ctx.approve(...)`.
- **Bulk actions carry the full select-all-across-pages payload**
  (`ids`/`all`/`unselected`) so "select all, deselect three, approve" sends
  the same semantics the table itself models — never just an enumerated id
  list that silently drops rows outside the current page.
- **Peeks are JSON fetches, not visits.** `useResourceContext` re-fetches
  on id change and exposes a `refresh()` the peek re-runs whenever
  `ctx.refreshKey` bumps (every mutation bumps it) — opening or updating a
  peek never re-renders the list page underneath it.
- **`item-value="id"`** is what lets `table.selected`/`table.unselected`
  and `ctx.highlighted` all hold plain ids instead of whole objects — the
  keyboard handler and the peek both resolve the full `Expense` from
  `table.items` (the current page's server-sent rows).
- **One dispatch path per action, three entry points.** `approve`,
  `openReject` and `openSnooze` are called identically from `RowActions`,
  `ExpensePeek`'s footer, and the `A`/`R`/`S` keyboard handlers
  (`approveHighlighted` etc. are the same functions, resolved against
  `highlightedExpense` instead of a row prop).
- **Reason and date are dialogs, not confirms**, exactly as in the Vue
  recipe: `ctx.dialogs.reject` holds the subject `Expense`, not a boolean,
  so the row action and the peek's reject button both just assign it.
- **The shortcut guard mirrors `useDeleteCmd`.** `isInteractiveElementFocused()`
  is copied verbatim from the [Inertia Helpers](../../guides/inertia-helpers.md)
  guide's `useDeleteCmd` (which the guide notes "works on any platform") so
  typing a rejection reason never fires `R`; the handler also bails while
  any dialog is open. This is the natural home to promote the guard into
  the shared toolkit as a reusable `useSingleLetterCmd`-shaped helper
  (reported, not patched here — see Report below).
- **`peekX` vs `stackX` is the whole stack grammar**, unchanged from the
  Vue recipe: highlighting always **replaces** (`peekExpense`, `true`),
  clicking a submitter's name always **pushes** (`stackSubmitter`), and the
  shell renders the back arrow once depth > 1.
- **Sizing:** topbar and rail follow `md`-first; `sm`/`xs` appear exactly
  where the doctrine allows — table rows, the shortcut bar, the peek
  footers and the bulk bar.
- **No `variant="primary"` on this page.** Triage has no "create" action —
  every action here is either a one-click mutation, a gated mutation via
  dialog, a bulk mutation, or navigation.

## Variations

- **No snooze**: drop `SnoozeDialog.vue`, the `S` shortcut, and the
  `snoozed` tab state — the remaining approve/reject pair still clears the
  ≥ 12 action bar on its own via the bulk/keyboard/peek spread.
- **Auto-advance after action**: after `approve`/`reject` resolves, set
  `ctx.highlighted.value = nextExpenseId` (the id following the acted-on
  row in `table.items.value`) so triage keeps moving without a
  re-highlight — the classic "Superhuman" flow.
- **Per-category routing**: seed `filters.categories` from a saved view
  per approver role (a store-backed default) instead of starting empty.
- **Lazy tab counts**: if `tabCounts` is expensive to compute, share it as
  `Inertia::lazy()` and read it with `useLazyProp` instead of a plain
  prop — the tab labels resolve once it lands instead of blocking the
  first render.

---

<!-- dist/ai/recipes/inertia/command-palette.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/inertia/command-palette.md -->

# Recipe: Command Palette (Inertia)

`BbCommand` does not exist — the [component picker](../../guides/component-picker.md)
says to compose `BbDialog` + `BbSelectPopover`, and this recipe is that
composition, worked end to end: a `⌘K`/`Ctrl+K` shortcut (plus an optional
visible topbar trigger) opens a dialog; inside it, `BbSelectPopover`'s
search-and-pick engine — debouncing, race protection, grouping — drives a
single query against your backend and returns **grouped** results (Pages,
Records, Actions, or whatever taxonomy fits your app). Picking a result
navigates and closes the palette. No new component ships anywhere in this
recipe — it is `BbDialog` and `BbSelectPopover`'s existing engine, wired.

Sibling recipes: [Vue](../vue/command-palette.md) ·
[Nuxt](../nuxt/command-palette.md).

## Prerequisites

- `<BbConfirm />` and `<BbToast />` mounted once in the `createInertiaApp`
  render root — never in a page. `CommandPalette.vue` (below) mounts the same
  way, once, in the same root — the shortcut must work from every page, not
  just ones that remember to render it.
- A backend search endpoint that returns **grouped** results — this recipe
  assumes `GET /search?q=…` responding
  `{ pages: Result[], records: Result[], actions: Result[] }` where each
  `Result` is `{ id, title, subtitle?, href, icon }`. Shape it to your own
  taxonomy; only the "grouped array of navigable rows" contract matters
  below. Use a **plain JSON route**, not an Inertia page — a full Inertia
  visit per keystroke would replace the whole page component instead of
  answering a query.

## Key ideas

- **`BbSelectPopover` is the documented tool for this.** Its own guide says
  outright: "It is the right tool for command-palette and inline-edit
  patterns." This recipe does not fight that — it gives the popover a real,
  on-screen activator inside a dialog, not a hidden one.
- **The activator must be real and visible, never `sr-only`.** `BbSelectPopover`
  closes itself when its activator's intersection ratio drops below 1 (it
  assumes an off-screen/invisible trigger means "the anchor scrolled away, so
  close"). A hidden activator forced open programmatically opens and then
  immediately auto-closes — a broken pattern worth naming so nobody reaches
  for it. This recipe's activator is a normal, painted search button sitting
  inside the open dialog, so its intersection ratio is always 1.
- **`BbSelectPopover` has no imperative `ref.open()`** (its `defineExpose` is
  empty) — the only way to open it from outside its own activator slot is a
  real DOM interaction on that activator. So the dialog's `@shown` handler
  (fires after the native `showModal()` call and initial focus — later than
  `@show`, so the trigger is guaranteed painted) calls `.click()` on our own
  template ref to the trigger button. This is not a workaround; it is how the
  popover is designed to be opened.
- **A fresh popover instance every open.** `BbSelectPopover` keeps its typed
  query and open state internally with no external reset hook. Keying the
  popover on an integer that increments on `@show` remounts it cleanly each
  time the palette opens, so a stale query from the last search never
  reappears.
- **`prefill: false`** makes the provider **search-first**: nothing loads on
  open, and the panel shows a "type to search" hint until the first
  keystroke — exactly right for a palette where browsing the full result set
  makes no sense. Debouncing (default 500ms), race protection and loading
  state are the popover's built-in guarantees; this recipe does not
  re-implement any of them.
- **Options here have no `href`/`to`.** Unlike `BbDropdown` (or `BbButton`),
  `BbSelectPopover`'s options are picked, not linked — there is no
  navigation prop to reach for. Picking updates `v-model` with the chosen
  `href`, and the `update:model-value` handler is where navigation actually
  happens — the one place in this recipe a click handler drives routing
  instead of a `to`/`href` prop, and it is the only place that could. On
  Inertia that means `router.visit`, not a raw `window.location` assignment.
- **A shared `open` ref, not a prop.** `useCommandPalette()` is a tiny
  module-level singleton so both the `⌘K` shortcut and an optional visible
  topbar "Search" button flip the same state — see
  [Layout Scaffold](./layout-scaffold.md#topbar-value-pickers-account-menu-theme-warehouse)
  for the account-menu neighbourhood this typically sits in.
- **The search fetch bypasses Inertia on purpose.** `fetch()` against a plain
  JSON route keeps every keystroke off the Inertia visit/history stack — the
  page component never re-renders and the browser URL never changes while
  you type. Only the final pick becomes a real `router.visit`.

## The code

### `resources/js/composables/useCommandPalette.ts`

```ts
// resources/js/composables/useCommandPalette.ts
import { ref } from 'vue';

// Module-level singleton: one palette per app. The `⌘K` shortcut and any
// visible "Search" trigger (topbar button, empty-state CTA, …) all flip this
// same ref instead of each owning their own boolean.
const open = ref(false);

export function useCommandPalette() {
	return { open };
}
```

### `resources/js/components/CommandPalette.vue`

```vue
<!-- CommandPalette.vue — mount once in the createInertiaApp render root,
     alongside BbConfirm/BbToast -->
<template>
	<BbDialog v-model="open" size="lg" title="Search" @shown="onShown">
		<BbSelectPopover
			:key="instance"
			:adaptive="false"
			group-by="group"
			item-text="title"
			item-value="href"
			:items="search"
			:model-value="null"
			no-data-text="No results."
			placement="bottom-start"
			:prefill="false"
			width="100%"
			@update:model-value="onPick"
		>
			<template #activator="{ props }">
				<!-- The real, painted activator — see "Key ideas" for why it must
				     be visible, not `sr-only`. -->
				<button
					ref="triggerRef"
					v-bind="props"
					class="command-palette__trigger"
					type="button"
				>
					<BbIcon icon="lucide:search" />
					<span>Type to search…</span>
				</button>
			</template>

			<template #option="{ item }">
				<div class="command-palette__option">
					<BbIcon :icon="item.icon" />
					<div class="flex min-w-0 flex-col">
						<span class="truncate">{{ item.title }}</span>
						<span
							v-if="item.subtitle"
							class="truncate text-xs text-[color:var(--bb-text-muted)]"
						>
							{{ item.subtitle }}
						</span>
					</div>
				</div>
			</template>

			<template #no-data="{ query }">
				<p class="p-3 text-sm text-[color:var(--bb-text-muted)]">
					{{ query ? `No results for "${query}".` : 'Type to search.' }}
				</p>
			</template>
		</BbSelectPopover>
	</BbDialog>
</template>

<script setup lang="ts">
import { nextTick, ref } from 'vue';
import { useMagicKeys, whenever } from '@vueuse/core';
import { router } from '@inertiajs/vue3';
import { BbDialog, BbIcon, BbSelectPopover } from 'bitboss-ui';
import { useCommandPalette } from '@/composables/useCommandPalette';

interface Result {
	id: string;
	title: string;
	subtitle?: string;
	href: string;
	icon: string;
	group: 'Pages' | 'Records' | 'Actions';
}

const { open } = useCommandPalette();

// `⌘K` on Mac, `Ctrl+K` elsewhere; `preventDefault` stops the browser's own
// address-bar shortcut (Firefox/Edge) from firing alongside ours.
const keys = useMagicKeys({
	passive: false,
	onEventFired(event) {
		if (event.key === 'k' && (event.metaKey || event.ctrlKey)) {
			event.preventDefault();
		}
	},
});
whenever(keys['cmd+k'], () => (open.value = true));
whenever(keys['ctrl+k'], () => (open.value = true));

// Remounting the popover on every open (see "Key ideas") clears its typed
// query and closed state without hand-rolling a reset API it doesn't expose.
const instance = ref(0);
const triggerRef = ref<HTMLButtonElement>();
const onShown = () => {
	instance.value++;
	void nextTick(() => triggerRef.value?.click());
};

// A plain `fetch` — not an Inertia visit — so typing never touches the
// history stack or re-renders the current page (see "Key ideas").
const search = async (query: string): Promise<Result[]> => {
	if (query.trim() === '') return [];
	const data: { pages: Result[]; records: Result[]; actions: Result[] } =
		await fetch(`/search?q=${encodeURIComponent(query)}`).then((res) =>
			res.json()
		);
	return [
		...data.pages.map((r) => ({ ...r, group: 'Pages' as const })),
		...data.records.map((r) => ({ ...r, group: 'Records' as const })),
		...data.actions.map((r) => ({ ...r, group: 'Actions' as const })),
	];
};

// The one place this recipe navigates from a handler instead of `to`/`href`
// — see "Key ideas": select options carry no navigation prop.
const onPick = (href: string | null) => {
	if (href == null) return;
	open.value = false;
	router.visit(href);
};
</script>

<style scoped>
.command-palette__trigger {
	align-items: center;
	background: var(--bb-panel);
	border: 1px solid var(--bb-border);
	border-radius: var(--bb-radius);
	color: var(--bb-text-muted);
	display: flex;
	gap: 0.5rem;
	padding: 0.5rem 0.75rem;
	width: 100%;
}

.command-palette__option {
	align-items: center;
	display: flex;
	gap: 0.5rem;
	min-width: 0;
}
</style>
```

### An optional visible trigger, anywhere

Any button can open the same palette without touching the shortcut logic —
this is the button that replaces "a top-bar link to `/search`":

```vue
<script setup lang="ts">
import { BbButton } from 'bitboss-ui';
import { useCommandPalette } from '@/composables/useCommandPalette';

const { open } = useCommandPalette();
</script>

<template>
	<BbButton
		aria-label="Search (⌘K)"
		icon="lucide:search"
		size="sm"
		variant="ghost"
		@click="open = true"
	/>
</template>
```

## Why it is built this way

- **The popover's own guide already names this use case** — reaching for
  `BbSelectPopover` here is not a stretch of its design, it is the
  documented one.
- **Visibility, not exposed imperative methods, is what opens the panel.**
  `BbSelectPopover` deliberately exposes nothing on its component ref; the
  only supported way in is a real interaction on the activator you rendered.
  Clicking a real, on-screen `triggerRef` from `@shown` **is** that
  interaction, not a bypass of it.
- **`@shown`, not `@show`.** `@show` fires the instant the model flips to
  `true`, before the dialog's native `showModal()` call and before the
  trigger is guaranteed painted; `@shown` fires after both, so the
  programmatic click always lands on a real, visible element.
- **Grouping is server-shaped, not client-invented.** `group-by="group"`
  buckets the flattened response exactly the way `BbSelect`'s "Group
  options" playbook describes — no bespoke section-rendering markup.
- **`router.visit`, never a raw href assignment.** Consistent with the rest
  of the Inertia recipes: navigation always goes through Inertia's router so
  history and shared props stay coherent.

## Gotchas

- **Escape inside the search field closes the popover, not the dialog.**
  The search input's own `keydown.esc` handler stops propagation, so the
  first `Escape` clears/closes the panel and a second one closes the dialog.
  This mirrors most native command palettes (clear query, then dismiss) —
  do not "fix" it by removing the popover's own Escape handling.
- **`fetch('/search?q=…')` is a placeholder route.** Swap it for your app's
  real search endpoint; keep the grouped-array response shape or adjust
  `group-by`/`item-text`/`item-value` to match your own. Keep it a plain
  JSON route, not an Inertia page endpoint.
- **Do not read `text`/`selectedOptions` for the trigger label.** This
  recipe's trigger is static ("Type to search…") on purpose — a command
  palette's activator never needs to reflect a "current selection" the way a
  filter pill does.
- **`BbSelectPopover` has no `placeholder` prop.** The search field only
  carries an accessible name (from `config.locale`) — there is no visible
  placeholder text to set. The trigger's own "Type to search…" label is
  what carries that instruction, not a prop on the popover.
  </content>

---

<!-- dist/ai/recipes/inertia/inline-edit-workspace.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/inertia/inline-edit-workspace.md -->

# Recipe: Inline-Edit Workspace (Inertia)

The flagship of pattern **§6.8 — autosave cells**, adapted for
**Laravel + Inertia**: the same Linear-grade sprint backlog where **every
cell persists itself and the page has no Save button anywhere** — but the
list arrives as a page prop (a standard Laravel paginator), filters and tab
live in the URL through [`useQueryObject`](../../guides/inertia-helpers.md),
selection and paging come from the keyed
[`useTableContext`](../../guides/inertia-helpers.md), and every save is a
promise-wrapped partial `router.visit`. Anatomy, components, the cells, the
overlay, copy and data are identical to the Vue recipe; only the
data/URL/mutation layer changes.

Sibling recipes: [Vue](../vue/inline-edit-workspace.md) ·
[Nuxt](../nuxt/inline-edit-workspace.md).

Domain: **Sprint 24** of a product team — fourteen issues (`BB-227` …
`BB-241`), four statuses, three priorities, a six-member team (Sofia Reyes,
Jonah Weiss, Priya Natarajan, Tom Okafor, Elif Demir, Marco Bianchi).
Deliberately distinct from the invoices/members/expenses of the sibling
recipes.

## Prerequisites

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell`, `usePageShellContext` and `FloatingBottomPanel` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
  Components: [BbTable](../../BbTable.md) ·
  [BbSelectPopover](../../BbSelectPopover.md) (§ One popover per table row is
  load-bearing here) · [BbBadge](../../BbBadge.md) (the `loading` /
  `append:icon` interplay).

Guides: [Inline Edit Playbook](../../guides/inline-edit-playbook.md) (who owns
the edit — this page is the autosave answer) ·
[Inertia Helpers](../../guides/inertia-helpers.md) (the app-side toolkit this
recipe assumes) ·
[Design language](../../guides/design-language.md) (§ Using color, § Badges
label state) · [Page Shell](../../guides/page-shell.md) ·
[Floating Bottom Panel](../../guides/floating-bottom-panel.md).

From the [Inertia Helpers](../../guides/inertia-helpers.md) toolkit:
`useTableContext`, `useQueryObject`, `useQuery`, `useProp`,
`useResourceContext`. `<BbConfirm />` and `<BbToast />` mounted once in the
`createInertiaApp` render root — never in a page.

Controller: `Inertia::render('Sprints/Backlog', ['issues' => …, 'tabCounts'
=> …, 'team' => …])` — `issues` is a standard Laravel paginator
(`PaginatedResponse<Issue>`), already filtered/paged server-side from the
query string; `tabCounts` a plain `{ backlog, current, done }` map; `team`
the six members (small enough to always send). Mutation routes are plain
Laravel routes that redirect back — `PATCH /issues/:id` (any single editable
field), `POST /issues/:id/duplicate`, `POST /issues/:id/next-sprint`,
`DELETE /issues/:id`, and the bulk `PATCH|POST /issues/bulk/*` trio — plus
one small JSON GET endpoint (`GET /issues/:id/peek`) backing the sidebar
peek so opening it is never a page visit.

## Key ideas

- **No Save button anywhere.** Every cell commits itself through one context
  action, `persistField(issue, key, value)` — optimistic write, single-field
  PATCH visit + partial reload; failure rolls back just that field and
  toasts. Nothing on the page is ever
  "changed but unsaved", so there is no dirty ring and no dirty-gated
  button — the only transient state is _saving_, and the spinner carries it.
- **The optimistic overlay is page state, not cell state.** `pending` maps
  `issue.id → { field: value }` on **rung 3** of the state ladder: the grid
  cells, the peek workbench _and the retirement watcher_ all read it. This is
  the deliberate contrast with the one-shot §6.1 status cell (see
  `records-workspace`), whose `saving` flag is a rung-1 local ref — in an
  autosave grid the code that ingests fresh rows must also know what is in
  flight, so the flag cannot live inside a cell.
- **The overlay is retired where the fresh prop lands, never when a save
  resolves** — and only for fields the fresh rows actually confirm. In
  Inertia there is no fetch you own: rows arrive as the `issues` page prop
  (from your PATCH's reload, a tab visit, a filter visit, a poll), so
  retirement is one watcher on the ingested rows, covering every arrival
  path. Retiring on save-resolve instead makes a _second_ in-flight field of
  the same row flash new → old → new, because the save's response does not
  carry that field's value yet.
- **The overlay itself is deliberately platform-agnostic.** `pending`,
  `failed`, `valueOf`, `isSaving` and `persistField`'s rollback are the Vue
  recipe's code unchanged; only where a save goes and where fresh rows
  arrive are Inertia's.
- **Typed inputs commit on `@change` (blur/Enter), never `v-model`.** A
  `v-model` autosave is one request per keystroke. Pickers commit on pick —
  the click already _is_ the commit.
- **One coopting page context.** `provideBacklogWorkspace()` joins the
  page-shell stack and the keyed `useTableContext('issues')` once, owns
  filters/tab/overlay, and exposes complete actions. Eleven components share
  everything through one `useBacklogWorkspace()` call — zero prop drilling.
- **The table has no client-side fetch at all.** `issues` arrives as a page
  prop; `useTableContext('issues')` turns it into `items` +
  `totalItems`/`page`/`perPage` (URL-backed) + `selected`/`unselected`/`all`
  (select-all-across-pages), and `BbTable` binds directly to that handle.
- **Filters mirror into the URL with `useQueryObject`; tabs are real
  visits.** Typing in a pill filter performs a partial Inertia visit
  (`only: ['issues', 'tabCounts']`); `BbTabs` items carry `href` +
  `server: true` with the same `only` list. The server is the single source
  of filtered, paginated truth.
- **Options resolve once, at page level.** Status and priority are static
  module-level catalogs (fifty rows, zero requests); the assignee picker
  shares **one** query provider across every row — filtering the `team` page
  prop client-side — so unopened rows cost nothing and no picker ever makes
  a request.
- **Status is color, per the soft palette.** The registered `soft-*` badge
  variants label the closed status/priority sets; the internal trailing
  chevron says "clickable", and the badge's `loading` swaps the spinner into
  the chevron's place while that one field saves.
- **Buttons are `md` by default**; `sm` appears only in row actions, the
  filter pills, the peek footer and the bulk bar.

## Page anatomy

```
BacklogWorkspace/
	Index.vue               ← assembly: PageShell slots, table, tabs, pagination
	context.ts              ← coopts shell + keyed table ctx; owns filters + the pending overlay + persistField
	FilterRail.vue          ← status / priority / assignee filter pills + clear-all
	EditableTitleCell.vue   ← commit-on-blur text (@change, never v-model)
	EstimateCell.vue        ← commit-on-change number cell
	StatusCell.vue          ← editable soft badge (chevron at rest, spinner in flight)
	PriorityCell.vue        ← same grammar, its own leaf (§6.3: never one EditableCell with a type prop)
	AssigneeCell.vue        ← provider-backed people picker badge (ONE shared query fn)
	RowActions.vue          ← … dropdown: duplicate, move to next sprint, delete (confirm)
	SelectionBar.vue        ← bulk status / bulk assign / bulk move (floating bottom panel)
	IssuePeek.vue           ← peek workbench reusing the SAME Status/Priority/Assignee cells
```

Chrome assumed from the guides: `AppLayout` (left nav + fat footer),
`PageShell`, `FloatingBottomPanel`. Note what is _missing_ compared to the
records workspace: there is no dialog component and the shell's `#dialogs`
slot stays empty — on an autosave page the grid _is_ the form, so nothing
needs a modal to edit.

## Action inventory

| #   | Action                   | Trigger                            | Mechanism                                               |
| --- | ------------------------ | ---------------------------------- | ------------------------------------------------------- |
| 1   | New issue                | topbar, the page's one `primary`   | navigation (`/issues/new`)                              |
| 2   | Page search              | topbar right                       | `filters.search` → `useQueryObject` partial visit       |
| 3   | Switch sprint tab        | href tabs with live counts         | `BbTabs` `href` + `server: true` partial visit          |
| 4   | Filter by status         | rail pill                          | `BbSelectPopover` multiple over the static catalog      |
| 5   | Filter by priority       | rail pill                          | `BbSelectPopover` multiple over the static catalog      |
| 6   | Filter by assignee       | rail pill                          | the shared people provider, single select               |
| 7   | Clear filters            | rail right (only when active)      | context `clearFilters()`                                |
| 8   | Rename issue             | title cell (grid)                  | commit-on-blur `@change` → `persistField('title')`      |
| 9   | Re-estimate              | estimate cell (grid)               | commit-on-change number → `persistField('estimate')`    |
| 10  | Change status            | status badge (grid **and** peek)   | pick = commit; spinner in the chevron (§6.8)            |
| 11  | Change priority          | priority badge (grid **and** peek) | same grammar, its own leaf                              |
| 12  | Reassign                 | assignee badge (grid **and** peek) | people search over the `team` prop; one shared provider |
| 13  | Peek issue               | issue ref cell                     | `peekIssue(id)` → shell stack, JSON fetch               |
| 14  | Duplicate                | row `…` dropdown                   | promise-wrapped visit + toast                           |
| 15  | Move to next sprint      | row `…` **and** bulk bar           | `moveToNextSprint` / `bulkMoveToNextSprint` visits      |
| 16  | Delete                   | row `…`, peek footer               | destructive behind `useConfirm`, then a visit           |
| 17  | Bulk set status          | bottom panel picker                | `bulkStatus` on the selection context (across pages)    |
| 18  | Bulk assign              | bottom panel picker                | `bulkAssign` on the selection context (across pages)    |
| 19  | Select rows / select all | table checkboxes                   | `useTableContext` selection (across pages)              |
| 20  | Open full issue          | peek footer                        | navigation (`/issues/:id`)                              |
| 21  | Close peek               | shell chrome                       | shell stack close                                       |

Rows 8–12 are the recipe's reason to exist: five editable fields of three
different control kinds, each persisting itself, two of them able to be in
flight **on the same row at the same time**.

## The code

### Project setup — the soft status palette

Status and priority are small closed sets — the textbook case for the soft
semantic accents. The names are registered in the build plugin (that makes
them type-check as `BbBadge` variants); the CSS is the project's own,
kept in a stylesheet separate from the library defaults:

```ts
// vite.config.ts — the names; the library ships no CSS for them.
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import laravel from 'laravel-vite-plugin';
import { bitbossUi } from 'bitboss-ui/vite';

export default defineConfig({
	plugins: [
		laravel({ input: 'resources/js/app.ts', refresh: true }),
		vue(),
		bitbossUi({
			iconDir: './resources/js/assets/icons',
			badgeVariants: [
				'soft-gray',
				'soft-blue',
				'soft-green',
				'soft-amber',
				'soft-red',
			],
		}),
	],
});
```

```css
/* resources/css/badge-variants.css — trimmed. Canonical palette + the full
   recipe (why the selectors are doubled, why the hue lives in a local
   --accent): design-language.md § Using color. */
.bb-badge.bb-badge--soft-gray {
	--accent: #64748b;
}
.bb-badge.bb-badge--soft-blue {
	--accent: #2563eb;
}
.bb-badge.bb-badge--soft-green {
	--accent: #16a34a;
}
.bb-badge.bb-badge--soft-amber {
	--accent: #d97706;
}
.bb-badge.bb-badge--soft-red {
	--accent: #dc2626;
}

.bb-badge.bb-badge--soft-gray,
.bb-badge.bb-badge--soft-blue,
.bb-badge.bb-badge--soft-green,
.bb-badge.bb-badge--soft-amber,
.bb-badge.bb-badge--soft-red {
	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
	--border-width: 1px;
	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
}
```

### context.ts

```ts
// BacklogWorkspace/context.ts
import {
	computed,
	inject,
	provide,
	reactive,
	ref,
	watch,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import { router, usePage } from '@inertiajs/vue3';
import type { RequestPayload } from '@inertiajs/core';
import { useConfirm, useToast, type BadgeVariantType } from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import {
	useTableContext,
	type TableContext,
} from '@/composables/useTableContext';
import { useQueryObject } from '@/composables/useQueryObject';
import { useQuery } from '@/composables/useQuery';
import { useProp } from '@/composables/useProp';
import type { Issue, IssuePriority, IssueStatus, Member } from '@/types';

/** What the peek sidebar can show. Clicking an issue ref pushes one of these. */
export type PeekItem = { type: 'issue'; id: string };

export type SprintTab = 'backlog' | 'current' | 'done';

/**
 * Exactly what a save can carry: the subset of Issue the user edits inline.
 * Five fields of three control kinds on purpose — the pattern only proves
 * itself once a row can be PARTIALLY in flight (title saving while the same
 * row's status saves), once a field is backed by a search (assignee), and
 * once a field changes on every keystroke (title, estimate).
 */
export type IssuePatch = Partial<
	Pick<Issue, 'title' | 'estimate' | 'status' | 'priority' | 'assignee'>
>;
export type EditableKey = keyof IssuePatch;

export interface BacklogFilters {
	search: string;
	status: IssueStatus[];
	priority: IssuePriority[];
	/** The whole member, not an id — the pill labels itself with zero fetches. */
	assignee: Member | null;
}

/** The props every reload of this page depends on. */
const RELOAD_PROPS = ['issues', 'tabCounts'] as const;

// -- Option catalogs: resolved once, at module level, for the whole page. ----
// Static arrays cost fifty rows zero requests; a per-row provider would cost
// one request per opened row (BbSelectPopover § One popover per table row).
export const STATUS_OPTIONS: { value: IssueStatus; label: string }[] = [
	{ value: 'open', label: 'Open' },
	{ value: 'in-progress', label: 'In progress' },
	{ value: 'blocked', label: 'Blocked' },
	{ value: 'done', label: 'Done' },
];
export const PRIORITY_OPTIONS: { value: IssuePriority; label: string }[] = [
	{ value: 'high', label: 'High' },
	{ value: 'normal', label: 'Normal' },
	{ value: 'low', label: 'Low' },
];

// Status/priority are small closed sets — the textbook case for the soft
// accents (design-language.md § Using color). Registered in vite.config.ts.
export const STATUS_VARIANT: Record<IssueStatus, BadgeVariantType> = {
	open: 'soft-gray',
	'in-progress': 'soft-blue',
	blocked: 'soft-red',
	done: 'soft-green',
};
export const PRIORITY_VARIANT: Record<IssuePriority, BadgeVariantType> = {
	high: 'soft-amber',
	normal: 'secondary',
	low: 'outline',
};

/**
 * `id: null` is the real "Unassigned" option, not an absence. The assignee is
 * stored on the row as the whole member, so a row's badge always labels
 * itself from its own data — no client-side directory cache, and the trigger
 * never depends on the picker having loaded.
 */
export const UNASSIGNED: Member = { id: null, name: 'Unassigned' };

/**
 * ONE query provider shared by every assignee picker on the page — each
 * row's cell, the peek's cell, the rail pill and the bulk-assign picker.
 * Providers are lazy, so a row nobody opens costs nothing — and this one is
 * cheaper still: the controller already shares the six-member `team` as a
 * page prop, so the search filters it client-side, zero requests. Contract
 * (fetch-items-playbook): component-initiated calls (`prefill === true`)
 * and an empty query return the whole team, so the current selection always
 * stays resolvable; typed queries search.
 */
export const searchMembers = async (
	query: string,
	prefill: boolean
): Promise<Member[]> => {
	const team = usePage<{ team: Member[] }>().props.team;
	const q = query.trim().toLowerCase();
	const members =
		prefill || !q
			? team
			: team.filter((member) => member.name.toLowerCase().includes(q));
	return [UNASSIGNED, ...members];
};

export interface BacklogWorkspaceContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	table: TableContext<Issue, string>;
	// -- Page-owned state ------------------------------------------------------
	filters: BacklogFilters;
	hasActiveFilters: ComputedRef<boolean>;
	tab: Ref<SprintTab>;
	tabCounts: ComputedRef<Record<SprintTab, number>>;
	/** Bumped after every mutation — the peek watches it to re-fetch its JSON detail. */
	refreshKey: Ref<number>;
	// -- The autosave overlay (§6.8) --------------------------------------------
	/**
	 * Optimistic values per row PER FIELD, held until the server's own data
	 * carries them. Reactive. Rung 3 on purpose: the cells, the peek and the
	 * retirement watcher all read it. Cells never touch it directly — they go
	 * through `valueOf` / `isSaving`.
	 */
	pending: Record<string, IssuePatch>;
	/** Fields whose last save failed, keyed `${id}:${field}`. */
	failed: Readonly<Ref<Set<string>>>;
	/** Read-through: the overlay wins, the row is the fallback. */
	valueOf: <K extends EditableKey>(issue: Issue, key: K) => Issue[K];
	/** Whether THIS field of THIS row has a save in flight. */
	isSaving: (issue: Issue, key: EditableKey) => boolean;
	/** The one write path every cell commits through. */
	persistField: <K extends EditableKey>(
		issue: Issue,
		key: K,
		value: Issue[K]
	) => Promise<void>;
	// -- Peek ------------------------------------------------------------------
	peekIssue: (id: string) => void;
	// -- Actions (complete: visit + refresh + toast) ------------------------------
	clearFilters: () => void;
	duplicateIssue: (issue: Issue) => Promise<void>;
	moveToNextSprint: (issue: Issue) => Promise<void>;
	deleteIssue: (issue: Issue) => Promise<void>;
	bulkStatus: (status: IssueStatus) => Promise<void>;
	bulkAssign: (assignee: Member) => Promise<void>;
	bulkMoveToNextSprint: () => Promise<void>;
}

const key: InjectionKey<BacklogWorkspaceContext> = Symbol('backlog-workspace');

/** Comma-joined query value → string[] (or null when absent). */
const toArray = (value: unknown): string[] | null => {
	if (value == null || value === '') return null;
	return Array.isArray(value) ? value.map(String) : String(value).split(',');
};

/**
 * Inertia's callback-based visit, wrapped as a promise — so every context
 * action stays `async`, exactly like the Vue/Nuxt versions. Always a
 * partial reload; field saves pass just `['issues']`, everything else
 * refreshes the tab counts too.
 */
const visit = (
	method: 'post' | 'patch' | 'delete',
	url: string,
	// Inertia's own payload type — strings/numbers/booleans/arrays/files.
	// (`Record<string, unknown>` does not satisfy it.)
	data: RequestPayload = {},
	only: readonly string[] = RELOAD_PROPS
): Promise<void> =>
	new Promise((resolve, reject) => {
		router.visit(url, {
			method,
			data,
			only: [...only],
			preserveScroll: true,
			preserveState: true,
			onSuccess: () => resolve(),
			onError: (errors) => reject(errors),
		});
	});

export function provideBacklogWorkspace(): BacklogWorkspaceContext {
	const { toast } = useToast();
	const { confirm } = useConfirm();

	// -- Coopt the specific contexts: once, here, for the whole page. ----------
	const shell = usePageShellContext<PeekItem>();
	// `Issue, string`: BbTable's `item-value="id"` resolves selection to issue
	// ids, matching the Vue/Nuxt `table.selected: string[]` shape.
	const table = useTableContext<Issue, string>('issues');

	// -- Filters: seeded from the current URL, mirrored back by useQueryObject. -
	const query = useQuery();
	const team = useProp<Member[]>('team');
	const filters = reactive<BacklogFilters>({
		search: (query.search as string) ?? '',
		status: (toArray(query.status) ?? []) as IssueStatus[],
		priority: (toArray(query.priority) ?? []) as IssuePriority[],
		// The URL carries an id; the `team` prop turns it back into the whole
		// member, so the pill still labels itself with zero fetches. 'none' is
		// UNASSIGNED's serialized form (`id: null`) — a real filter value.
		assignee:
			query.assignee === 'none'
				? UNASSIGNED
				: (team.value.find((m) => String(m.id) === query.assignee) ?? null),
	});
	// The watcher mirrors a URL-shaped projection of the filters: the
	// whole-member assignee flattens to its id on the way out.
	useQueryObject(
		() => ({
			search: filters.search,
			status: filters.status,
			priority: filters.priority,
			assignee:
				filters.assignee === null
					? null
					: String(filters.assignee.id ?? 'none'),
		}),
		{ only: [...RELOAD_PROPS] }
	);

	const hasActiveFilters = computed(
		() =>
			filters.search !== '' ||
			filters.status.length > 0 ||
			filters.priority.length > 0 ||
			filters.assignee !== null
	);
	const clearFilters = () => {
		filters.search = '';
		filters.status = [];
		filters.priority = [];
		filters.assignee = null;
	};

	// Tab: seeded from the URL; BbTabs' own `href` + `server` visit updates
	// the URL, and its `v-model` write keeps this ref in sync with the click.
	const tab = ref<SprintTab>((query.tab as SprintTab) ?? 'current');
	const tabCounts = useProp<Record<SprintTab, number>>('tabCounts');

	const refreshKey = ref(0);

	// -- The autosave overlay -----------------------------------------------------
	const pending = reactive<Record<string, IssuePatch>>({});
	const failed = ref(new Set<string>());

	const valueOf = <K extends EditableKey>(issue: Issue, key: K): Issue[K] => {
		const patch = pending[issue.id];
		// `key in patch`, not `patch[key] ?? issue[key]`: null is a legitimate
		// committed value here (a cleared estimate), and `??` would drop that
		// overlay and show the stale row value while the save runs.
		return patch && key in patch ? (patch[key] as Issue[K]) : issue[key];
	};

	const isSaving = (issue: Issue, key: EditableKey): boolean => {
		const patch = pending[issue.id];
		return patch !== undefined && key in patch;
	};

	/** Human labels for the editable fields — used in the autosave/undo toasts. */
	const FIELD_LABELS: Record<EditableKey, string> = {
		title: 'title',
		estimate: 'estimate',
		status: 'status',
		priority: 'priority',
		assignee: 'assignee',
	};

	/**
	 * The complete autosave action, one per commit, for every control kind:
	 * no-op guard → snapshot-for-undo → optimistic set → single-field PATCH
	 * visit, whose own partial reload brings the fresh rows back. On failure it
	 * deletes JUST this field from the overlay (the cell snaps back — a second
	 * field of the same row still in flight is untouched) and toasts destructive.
	 *
	 * On SUCCESS it fires a soft "Undo" toast: every inline edit is one click from
	 * reverting, the old value PATCHed back (and re-doable, since Undo is itself a
	 * persistField call). The Undo action must RE-RESOLVE the row by id — the
	 * `issue` captured in the closure goes stale after the visit re-renders
	 * `issues`, and the no-op guard would then compare the revert against the
	 * stale value and swallow it.
	 */
	const persistField = async <K extends EditableKey>(
		issue: Issue,
		key: K,
		value: Issue[K]
	): Promise<void> => {
		// Snapshot what the user SEES right now — the value Undo restores.
		const previous = valueOf(issue, key);
		// No-op-commit guard: a blur without a change, or re-picking the on-screen
		// value, must not fire a request.
		if (JSON.stringify(value) === JSON.stringify(previous)) return;

		const flag = `${issue.id}:${key}`;
		(pending[issue.id] ??= {})[key] = value; // optimistic: the UI moves NOW
		failed.value.delete(flag);
		try {
			// One visit is both the PATCH and the reload — the redirect back
			// re-renders `issues`. Do NOT retire the overlay here: the watcher
			// below drops it once the server's own data carries the value.
			await visit('patch', `/issues/${issue.id}`, { [key]: value }, ['issues']);
			refreshKey.value++; // the peek re-fetches its JSON detail
			// Auto-undo: soft confirmation the edit can reverse in one click.
			toast({
				title: `${issue.ref}: ${FIELD_LABELS[key]} updated`,
				variant: 'success',
				actions: [
					{
						text: 'Undo',
						'prepend:icon': 'lucide:undo-2',
						onClick: () => {
							const current =
								table.items.value.find((r) => r.id === issue.id) ?? issue;
							return persistField(current, key, previous);
						},
					},
				],
			});
		} catch {
			// Rollback: drop just this field.
			const patch = pending[issue.id];
			if (patch) {
				delete patch[key];
				if (!Object.keys(patch).length) delete pending[issue.id];
			}
			failed.value.add(flag);
			toast({
				title: `Couldn't save the ${key} of ${issue.ref} — reverted.`,
				variant: 'destructive',
			});
		}
	};

	// -- Overlay retirement ---------------------------------------------------------
	// The Vue recipe retires the overlay inside its own fetchIssues; here
	// there is no fetch you own — fresh rows land as the `issues` page prop,
	// and the keyed table context re-syncs `items` after every successful
	// visit. So retirement runs HERE, where the prop lands, not when a save
	// resolves — and only for the fields the fresh rows actually CONFIRM. A
	// PATCH's response confirms its own field, but a SECOND field of the same
	// row still in flight is not in it yet; clearing the whole row's overlay
	// on save-resolve snaps that field back to the stale value until its own
	// visit lands — visibly, new → old → new. Rows also arrive through visits
	// this code never initiates (tab, filter, poll); one watcher covers every
	// arrival path. A field still in flight is left alone.
	watch(table.items, (rows) => {
		for (const issue of rows) {
			const patch = pending[issue.id];
			if (!patch) continue;
			for (const field of Object.keys(patch) as EditableKey[]) {
				if (JSON.stringify(patch[field]) === JSON.stringify(issue[field])) {
					delete patch[field]; // the server's own data carries it now
				}
			}
			if (!Object.keys(patch).length) delete pending[issue.id];
		}
	});

	// -- Peek ------------------------------------------------------------------------
	// One record type on this page, so the grammar is one verb: fresh stack.
	const peekIssue = (id: string) => shell.push({ type: 'issue', id }, true);

	// -- Discrete actions (row `…`, bulk bar) -------------------------------------
	// These are ordinary complete actions, records-workspace style: they
	// mutate whole rows, not single fields, so they bypass the overlay — the
	// visit's own partial reload replaces the rows — and being discrete (not
	// a blur), they DO toast success.
	const refresh = () => {
		refreshKey.value++;
	};

	const duplicateIssue = async (issue: Issue) => {
		await visit('post', `/issues/${issue.id}/duplicate`);
		refresh();
		toast({ title: `${issue.ref} duplicated.`, variant: 'success' });
	};

	const moveToNextSprint = async (issue: Issue) => {
		await visit('post', `/issues/${issue.id}/next-sprint`);
		refresh();
		toast({ title: `${issue.ref} moved to Sprint 25.`, variant: 'success' });
	};

	const deleteIssue = async (issue: Issue) => {
		const ok = await confirm({
			variant: 'destructive',
			title: 'Delete issue',
			text: `Delete ${issue.ref} — “${issue.title}”? This cannot be undone.`,
			yes: 'Delete',
			no: 'Cancel',
		});
		if (!ok) return;
		await visit('delete', `/issues/${issue.id}`);
		refresh();
		toast({ title: `${issue.ref} deleted.`, variant: 'success' });
	};

	// Bulk actions carry the full select-all-across-pages payload — the
	// server combines `all` + `unselected` the same way BbTable does.
	const bulkPayload = () => ({
		ids: table.selected.value,
		all: table.all.value,
		unselected: table.unselected.value,
	});
	const bulkCount = () =>
		table.all.value
			? table.totalItems.value - table.unselected.value.length
			: table.selected.value.length;

	const bulkStatus = async (status: IssueStatus) => {
		const count = bulkCount();
		await visit('patch', '/issues/bulk/status', { ...bulkPayload(), status });
		table.resetSelection();
		refresh();
		const label = STATUS_OPTIONS.find((o) => o.value === status)?.label;
		toast({
			title: `${count} issues moved to ${label}.`,
			variant: 'success',
		});
	};

	const bulkAssign = async (assignee: Member) => {
		const count = bulkCount();
		await visit('patch', '/issues/bulk/assign', {
			...bulkPayload(),
			assignee: assignee.id,
		});
		table.resetSelection();
		refresh();
		toast({
			title: `${count} issues assigned to ${assignee.name}.`,
			variant: 'success',
		});
	};

	const bulkMoveToNextSprint = async () => {
		const count = bulkCount();
		await visit('post', '/issues/bulk/next-sprint', bulkPayload());
		table.resetSelection();
		refresh();
		toast({
			title: `${count} issues moved to Sprint 25.`,
			variant: 'success',
		});
	};

	const ctx: BacklogWorkspaceContext = {
		shell,
		table,
		filters,
		hasActiveFilters,
		tab,
		tabCounts,
		refreshKey,
		pending,
		failed,
		valueOf,
		isSaving,
		persistField,
		peekIssue,
		clearFilters,
		duplicateIssue,
		moveToNextSprint,
		deleteIssue,
		bulkStatus,
		bulkAssign,
		bulkMoveToNextSprint,
	};
	provide(key, ctx);
	return ctx;
}

export function useBacklogWorkspace(): BacklogWorkspaceContext {
	const ctx = inject(key);
	if (!ctx)
		throw new Error('useBacklogWorkspace() called outside BacklogWorkspace');
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- BacklogWorkspace/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left, page search + primary action right. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs
					class="min-w-0 flex-auto"
					:items="[
						{ key: 'product', text: 'Product', href: '/product' },
						{ key: 'sprints', text: 'Sprints', href: '/sprints' },
						{ key: 'sprint-24', text: 'Sprint 24' },
					]"
				/>
				<div class="flex shrink-0 items-center gap-2">
					<!-- `label` is required across the input family; `hide-label`
					     keeps the accessible name while hiding it visually. -->
					<BbTextInput
						v-model="ctx.filters.search"
						autocomplete="off"
						clearable
						compact
						hide-label
						label="Search issues"
						placeholder="Search ref or title…"
						prepend:icon="lucide:search"
					/>
					<BbButton
						href="/issues/new"
						prepend:icon="lucide:plus"
						variant="primary"
					>
						New issue
					</BbButton>
				</div>
			</div>
		</template>

		<div class="flex flex-col gap-3 p-4">
			<FilterRail />

			<!-- Tabs are real visits: href + server (component-level `navigation`
			     is required alongside per-item `server`), each carrying the same
			     partial-reload prop list as the filter watcher. Counts come back
			     from the server on every reload. Each href is built from
			     `tabHref()`, NOT a bare `?tab=` literal: `preserve-state` keeps
			     `ctx.filters` alive across the visit, so if the href dropped the
			     filter query keys the server would render an unfiltered page
			     while the (unchanged) filter chips kept claiming the old
			     filters still applied. -->
			<BbTabs
				v-model="ctx.tab.value"
				compact
				navigation
				preserve-scroll
				preserve-state
				replace
				:items="[
					{
						key: 'backlog',
						label: `Backlog · ${ctx.tabCounts.value.backlog}`,
						href: tabHref('backlog'),
						server: true,
						only: ['issues', 'tabCounts'],
					},
					{
						key: 'current',
						label: `Current sprint · ${ctx.tabCounts.value.current}`,
						href: tabHref('current'),
						server: true,
						only: ['issues', 'tabCounts'],
					},
					{
						key: 'done',
						label: `Done · ${ctx.tabCounts.value.done}`,
						href: tabHref('done'),
						server: true,
						only: ['issues', 'tabCounts'],
					},
				]"
			/>

			<!-- No dependencies/items-fn: `issues` is a page prop, and selection
			     (across pages) binds straight onto the keyed table context. -->
			<BbTable
				v-model="ctx.table.selected.value"
				v-model:highlighted="highlightedIssue"
				v-model:select-all="ctx.table.all.value"
				v-model:unselected-items="ctx.table.unselected.value"
				actions
				caption="Sprint 24 backlog"
				:columns="columns"
				compact
				item-value="id"
				:items="ctx.table.items.value"
				legend="Sprint 24 backlog issues"
				interactive-while-loading
				loading-text="Loading issues…"
				:row-class="rowClass"
				selectable
			>
				<!-- The ref is the peek handle — the title can't be, it's an input.
				     `.plain-link` is the project-owned inline-link helper
				     (design-language.md § Guide helper), not a BbButton variant. -->
				<template #ref="{ item, content }">
					<BbBaseButton
						class="plain-link font-semibold"
						@click="() => ctx.peekIssue(item.id)"
					>
						{{ content }}
					</BbBaseButton>
				</template>

				<!-- Five self-persisting cells, three control kinds, one leaf each. -->
				<template #title="{ item }">
					<EditableTitleCell :issue="item" />
				</template>

				<template #estimate="{ item }">
					<EstimateCell :issue="item" />
				</template>

				<template #status="{ item }">
					<StatusCell :issue="item" />
				</template>

				<template #priority="{ item }">
					<PriorityCell :issue="item" />
				</template>

				<template #assignee="{ item }">
					<AssigneeCell :issue="item" />
				</template>

				<template #actions="{ item }">
					<RowActions :issue="item" />
				</template>

				<template #no-data>
					<div class="flex flex-col items-center gap-2 p-6 text-center">
						<p class="text-sm text-[color:var(--bb-text-muted)]">
							No issues match
							{{
								ctx.hasActiveFilters.value ? 'the current filters' : 'this tab'
							}}.
						</p>
						<BbButton
							v-if="ctx.hasActiveFilters.value"
							variant="ghost"
							@click="ctx.clearFilters"
						>
							Clear filters
						</BbButton>
					</div>
				</template>
			</BbTable>

			<!-- No table-id: the keyed table context is the page count here. -->
			<BbPagination
				v-model="ctx.table.page.value"
				label="Backlog pagination"
				:total-pages="ctx.table.totalPages.value"
			/>
		</div>

		<SelectionBar />

		<!-- Peek sidebar: the shell owns close; we render by type. -->
		<template #sidebar>
			<IssuePeek
				v-if="ctx.shell.current.value?.type === 'issue'"
				:issue-id="ctx.shell.current.value.id"
			/>
		</template>

		<!-- Deliberately no #dialogs content: every mutation on this page is
		     inline. The grid is the form. -->
	</PageShell>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import {
	BbBaseButton,
	BbBreadcrumbs,
	BbButton,
	BbPagination,
	BbTable,
	BbTabs,
	BbTextInput,
} from 'bitboss-ui';
import qs from 'query-string';
import PageShell from '@/components/layout/PageShell.vue';
import { useQuery } from '@/composables/useQuery';
import { provideBacklogWorkspace, type SprintTab } from './context';
import AssigneeCell from './AssigneeCell.vue';
import EditableTitleCell from './EditableTitleCell.vue';
import EstimateCell from './EstimateCell.vue';
import FilterRail from './FilterRail.vue';
import IssuePeek from './IssuePeek.vue';
import PriorityCell from './PriorityCell.vue';
import RowActions from './RowActions.vue';
import SelectionBar from './SelectionBar.vue';
import StatusCell from './StatusCell.vue';
import type { Issue } from '@/types';

const ctx = provideBacklogWorkspace();

// Merge `tab` into the *current* query instead of replacing it: `useQuery()`
// reads the live URL, which already carries every filter `useQueryObject`
// mirrored there, so switching tabs keeps `search`/`status`/`priority`/
// `assignee` intact instead of silently resetting the results to unfiltered.
const tabHref = (tab: SprintTab): string =>
	`/sprints/24?${qs.stringify({ ...useQuery(), tab }, { arrayFormat: 'comma' })}`;

// Row highlight tracks the open peek — the peeked row stays marked, and
// highlighting a row opens its peek; clearing the highlight closes it.
const highlightedIssue = computed<string | null>({
	get: () =>
		ctx.shell.current.value?.type === 'issue'
			? ctx.shell.current.value.id
			: null,
	set: (id) => {
		if (id == null) ctx.shell.close();
		else ctx.peekIssue(id);
	},
});

const columns = [
	{ key: 'ref', label: 'Ref', width: 90 },
	{ key: 'title', label: 'Title' },
	{ key: 'estimate', label: 'Est.', width: 90 },
	{ key: 'status', label: 'Status', width: 170 },
	{ key: 'priority', label: 'Priority', width: 140 },
	{ key: 'assignee', label: 'Assignee', width: 200 },
];

// Blocked rows get a tinted background — public row-class API, no internals.
// Even the tint reads THROUGH the overlay: unblock an issue and the row
// clears the moment the pick commits, not when the reload lands.
const rowClass = (item: Issue) =>
	ctx.valueOf(item, 'status') === 'blocked'
		? 'bg-red-50 dark:bg-red-950/20'
		: undefined;
</script>
```

### FilterRail.vue

```vue
<!-- BacklogWorkspace/FilterRail.vue -->
<template>
	<div class="flex flex-wrap items-center gap-2">
		<!-- Status: multi-select pill over the same static catalog the cells use.
		     `disable-writing` means there's no search field to host an in-popover
		     clear, so these tiny fixed-list filters clear from a rail-level chip
		     (×) instead — the searchable filter below clears from inside the
		     popover. -->
		<div class="inline-flex items-center gap-1">
			<BbSelectPopover
				v-model="ctx.filters.status"
				disable-writing
				item-text="label"
				item-value="value"
				:items="STATUS_OPTIONS"
				multiple
			>
				<template #activator="{ props }">
					<BbButton
						v-bind="props"
						aria-label="Filter by status"
						append:icon="lucide:chevron-down"
						size="sm"
						variant="outline"
					>
						Status{{
							ctx.filters.status.length ? ` · ${ctx.filters.status.length}` : ''
						}}
					</BbButton>
				</template>
			</BbSelectPopover>
			<BbButton
				v-if="ctx.filters.status.length"
				aria-label="Clear status filter"
				prepend:icon="lucide:x"
				size="sm"
				variant="ghost"
				@click="ctx.filters.status = []"
			/>
		</div>

		<!-- Priority: same shape, three options. -->
		<div class="inline-flex items-center gap-1">
			<BbSelectPopover
				v-model="ctx.filters.priority"
				disable-writing
				item-text="label"
				item-value="value"
				:items="PRIORITY_OPTIONS"
				multiple
			>
				<template #activator="{ props }">
					<BbButton
						v-bind="props"
						aria-label="Filter by priority"
						append:icon="lucide:chevron-down"
						size="sm"
						variant="outline"
					>
						Priority{{
							ctx.filters.priority.length
								? ` · ${ctx.filters.priority.length}`
								: ''
						}}
					</BbButton>
				</template>
			</BbSelectPopover>
			<BbButton
				v-if="ctx.filters.priority.length"
				aria-label="Clear priority filter"
				prepend:icon="lucide:x"
				size="sm"
				variant="ghost"
				@click="ctx.filters.priority = []"
			/>
		</div>

		<!-- Assignee: the SAME shared provider as every assignee cell. The whole
		     member is the value, so the pill labels itself from page state with
		     zero fetches — no watchEffect-to-resolve-a-name here. Query-aware
		     (searchable), so the filter clears from inside the popover search. -->
		<BbSelectPopover
			v-model="ctx.filters.assignee"
			clearable
			item-text="name"
			:items="searchMembers"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filter by assignee"
					append:icon="lucide:chevron-down"
					size="sm"
					variant="outline"
				>
					{{ ctx.filters.assignee?.name ?? 'Assignee' }}
				</BbButton>
			</template>
		</BbSelectPopover>

		<!-- Clear-all renders only while something is active. -->
		<BbButton
			v-if="ctx.hasActiveFilters.value"
			class="ml-auto"
			prepend:icon="lucide:x"
			size="sm"
			variant="ghost"
			@click="ctx.clearFilters"
		>
			Clear filters
		</BbButton>
	</div>
</template>

<script setup lang="ts">
import { BbButton, BbSelectPopover } from 'bitboss-ui';
import {
	PRIORITY_OPTIONS,
	STATUS_OPTIONS,
	searchMembers,
	useBacklogWorkspace,
} from './context';

const ctx = useBacklogWorkspace();
</script>
```

### EditableTitleCell.vue

```vue
<!-- BacklogWorkspace/EditableTitleCell.vue -->
<template>
	<!-- Commit on @change (blur/Enter), NEVER v-model: a v-model autosave is
	one request per keystroke. `:model-value` binds the read-through value
	down; the user's in-progress typing lives in the DOM until blur commits
	it. A failed save marks the field until the next commit attempt. -->
	<BbTextInput
		compact
		:has-errors="ctx.failed.value.has(`${issue.id}:title`)"
		hide-label
		label="Issue title"
		:loading="ctx.isSaving(issue, 'title')"
		:model-value="ctx.valueOf(issue, 'title')"
		@change="commit"
	/>
</template>

<script setup lang="ts">
import { BbTextInput } from 'bitboss-ui';
import { useBacklogWorkspace } from './context';
import type { Issue } from '@/types';

const props = defineProps<{ issue: Issue }>();

const ctx = useBacklogWorkspace();

// `@change` is the native event; the committed text is on the target.
const commit = (event: Event) =>
	ctx.persistField(
		props.issue,
		'title',
		(event.target as HTMLInputElement).value
	);
</script>
```

### EstimateCell.vue

```vue
<!-- BacklogWorkspace/EstimateCell.vue -->
<template>
	<BbNumberInput
		compact
		:has-errors="ctx.failed.value.has(`${issue.id}:estimate`)"
		hide-label
		label="Estimate"
		:loading="ctx.isSaving(issue, 'estimate')"
		:min="0"
		:model-value="ctx.valueOf(issue, 'estimate')"
		placeholder="—"
		@change="commit"
	/>
</template>

<script setup lang="ts">
import { BbNumberInput } from 'bitboss-ui';
import { useBacklogWorkspace } from './context';
import type { Issue } from '@/types';

const props = defineProps<{ issue: Issue }>();

const ctx = useBacklogWorkspace();

// A number input's `change` carries the RAW STRING; '' means cleared. A
// cleared estimate is a real commit (estimate: null), not a no-op — which is
// exactly why the context's valueOf checks `key in patch` instead of `??`.
const commit = (event: Event) => {
	const raw = (event.target as HTMLInputElement).value;
	ctx.persistField(props.issue, 'estimate', raw === '' ? null : Number(raw));
};
</script>
```

### StatusCell.vue

```vue
<!-- BacklogWorkspace/StatusCell.vue -->
<template>
	<BbSelectPopover
		compact
		disable-writing
		item-text="label"
		item-value="value"
		:items="STATUS_OPTIONS"
		:model-value="status"
		width="180px"
		@update:model-value="
			(next) => ctx.persistField(issue, 'status', next as IssueStatus)
		"
	>
		<template #activator="{ props: activatorProps, shown }">
			<!-- The badge IS the trigger: BbBadgeButton turns the badge's own
			body into the button, so the pill is the hit target and draws its own
			focus ring — no wrapper element, no chrome class. The internal
			trailing chevron says "this can change" and sits inside the button
			with the label; while THIS field's save runs the badge's `loading`
			swaps the spinner into the chevron's place — same size, nothing
			shifts. Unlike the one-shot §6.1 cell there is no local `saving` ref:
			the flag comes from the context overlay, because in an autosave grid
			the code ingesting fresh rows must also know what's in flight. -->
			<BbBadge
				append:icon="lucide:chevron-down"
				:class="{ 'status-cell--open': shown }"
				:loading="ctx.isSaving(issue, 'status')"
				:variant="STATUS_VARIANT[status]"
			>
				<BbBadgeButton
					:aria-label="`Change status for ${issue.ref}`"
					v-bind="activatorProps"
					>{{ label }}</BbBadgeButton
				>
			</BbBadge>
		</template>
	</BbSelectPopover>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
import { STATUS_OPTIONS, STATUS_VARIANT, useBacklogWorkspace } from './context';
import type { Issue, IssueStatus } from '@/types';

const props = defineProps<{ issue: Issue }>();

const ctx = useBacklogWorkspace();

// Read through the overlay, so the badge moves the instant a pick commits —
// color and label both.
const status = computed(() => ctx.valueOf(props.issue, 'status'));
const label = computed(
	() =>
		STATUS_OPTIONS.find((option) => option.value === status.value)?.label ??
		status.value
);
</script>

<style scoped>
/* Open = the badge's own hue, deepened, plus its variant ring — derived from
   the badge's --color/--ring tokens so every status keeps its identity
   instead of washing out to a neutral. */
.status-cell--open {
	--bg: color-mix(in oklab, var(--color) 24%, var(--bb-panel));
	--border-color: color-mix(in oklab, var(--color) 45%, var(--bb-panel));
	box-shadow: 0 0 0 var(--bb-ring-size) var(--ring);
}
</style>
```

### PriorityCell.vue

```vue
<!-- BacklogWorkspace/PriorityCell.vue -->
<template>
	<!-- Same grammar as StatusCell, its OWN leaf (§6.3): one `EditableCell`
	with a `type` prop growing a renderer switch is the API-monster seed. The
	sixty percent that repeats is cheaper than the prop that accumulates. -->
	<BbSelectPopover
		compact
		disable-writing
		item-text="label"
		item-value="value"
		:items="PRIORITY_OPTIONS"
		:model-value="priority"
		width="160px"
		@update:model-value="
			(next) => ctx.persistField(issue, 'priority', next as IssuePriority)
		"
	>
		<template #activator="{ props: activatorProps, shown }">
			<BbBadge
				append:icon="lucide:chevron-down"
				:class="{ 'priority-cell--open': shown }"
				:loading="ctx.isSaving(issue, 'priority')"
				:variant="PRIORITY_VARIANT[priority]"
			>
				<BbBadgeButton
					:aria-label="`Change priority for ${issue.ref}`"
					v-bind="activatorProps"
					>{{ label }}</BbBadgeButton
				>
			</BbBadge>
		</template>
	</BbSelectPopover>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
import {
	PRIORITY_OPTIONS,
	PRIORITY_VARIANT,
	useBacklogWorkspace,
} from './context';
import type { Issue, IssuePriority } from '@/types';

const props = defineProps<{ issue: Issue }>();

const ctx = useBacklogWorkspace();

const priority = computed(() => ctx.valueOf(props.issue, 'priority'));
const label = computed(
	() =>
		PRIORITY_OPTIONS.find((option) => option.value === priority.value)?.label ??
		priority.value
);
</script>

<style scoped>
/* Open = the badge's own hue, deepened, plus its variant ring (see
   StatusCell). */
.priority-cell--open {
	--bg: color-mix(in oklab, var(--color) 24%, var(--bb-panel));
	--border-color: color-mix(in oklab, var(--color) 45%, var(--bb-panel));
	box-shadow: 0 0 0 var(--bb-ring-size) var(--ring);
}
</style>
```

### AssigneeCell.vue

```vue
<!-- BacklogWorkspace/AssigneeCell.vue -->
<template>
	<!-- Provider-backed people picker. The provider is the ONE shared
	`searchMembers` — lazy per instance, so a row nobody opens never resolves.
	The whole member is the value (no item-value), matching how the row
	stores it. -->
	<BbSelectPopover
		compact
		item-text="name"
		:items="searchMembers"
		:model-value="assignee"
		width="220px"
		@update:model-value="
			(next) => ctx.persistField(issue, 'assignee', next as Member)
		"
	>
		<template #activator="{ props: activatorProps, shown }">
			<!-- Labelled from the ROW (through the overlay), never from the
			popover's `text`: a lazy provider has no items until first open, so
			`text` is empty — and the rows nobody opens must still read right on
			first paint. An assignee is a person, not a semantic status, so the
			badge stays neutral (`secondary`), no soft accent. -->
			<BbBadge
				append:icon="lucide:chevron-down"
				:class="{ 'assignee-cell--open': shown }"
				:loading="ctx.isSaving(issue, 'assignee')"
				variant="secondary"
			>
				<BbBadgeButton
					:aria-label="`Change assignee for ${issue.ref}`"
					v-bind="activatorProps"
					>{{ assignee.name }}</BbBadgeButton
				>
			</BbBadge>
		</template>
	</BbSelectPopover>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
import { searchMembers, useBacklogWorkspace } from './context';
import type { Issue, Member } from '@/types';

const props = defineProps<{ issue: Issue }>();

const ctx = useBacklogWorkspace();

const assignee = computed(() => ctx.valueOf(props.issue, 'assignee'));
</script>

<style scoped>
/* Open = the badge's own hue, deepened, plus its variant ring (see
   StatusCell). */
.assignee-cell--open {
	--bg: color-mix(in oklab, var(--color) 24%, var(--bb-panel));
	--border-color: color-mix(in oklab, var(--color) 45%, var(--bb-panel));
	box-shadow: 0 0 0 var(--bb-ring-size) var(--ring);
}
</style>
```

### RowActions.vue

```vue
<!-- BacklogWorkspace/RowActions.vue -->
<template>
	<BbDropdown
		:items="[
			{
				key: 'duplicate',
				text: 'Duplicate',
				'prepend:icon': 'lucide:copy',
				onClick: () => ctx.duplicateIssue(issue),
			},
			{
				key: 'next-sprint',
				text: 'Move to next sprint',
				'prepend:icon': 'lucide:arrow-right',
				onClick: () => ctx.moveToNextSprint(issue),
			},
			{
				key: 'delete',
				text: 'Delete',
				'prepend:icon': 'lucide:trash-2',
				variant: 'destructive',
				onClick: () => ctx.deleteIssue(issue),
			},
		]"
	>
		<template #activator="{ props }">
			<BbButton v-bind="props" icon="lucide:ellipsis" size="sm" variant="ghost">
				Issue actions
			</BbButton>
		</template>
	</BbDropdown>
</template>

<script setup lang="ts">
import { BbButton, BbDropdown } from 'bitboss-ui';
import { useBacklogWorkspace } from './context';
import type { Issue } from '@/types';

defineProps<{ issue: Issue }>();

const ctx = useBacklogWorkspace();
</script>
```

### SelectionBar.vue

```vue
<!-- BacklogWorkspace/SelectionBar.vue -->
<template>
	<FloatingBottomPanel :open="selectedCount > 0">
		<span class="px-2 text-sm">{{ selectedCount }} selected</span>

		<!-- Bulk pickers are DISPATCHERS, not fields: model stays null, every
		pick fires the bulk action and the popover closes. The bar holds no
		state of its own. `placement="top"` because the bar hugs the viewport
		bottom — open upward instead of flipping — with an 8px `offset` so the
		menu clears the bar. -->
		<BbSelectPopover
			disable-writing
			item-text="label"
			item-value="value"
			:items="STATUS_OPTIONS"
			:model-value="null"
			:offset="8"
			placement="top"
			width="180px"
			@update:model-value="(next) => ctx.bulkStatus(next as IssueStatus)"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Set status for selected issues"
					append:icon="lucide:chevron-up"
					size="sm"
					variant="ghost"
				>
					Set status
				</BbButton>
			</template>
		</BbSelectPopover>

		<BbSelectPopover
			item-text="name"
			:items="searchMembers"
			:model-value="null"
			:offset="8"
			placement="top"
			width="220px"
			@update:model-value="(next) => ctx.bulkAssign(next as Member)"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Assign selected issues"
					append:icon="lucide:chevron-up"
					size="sm"
					variant="ghost"
				>
					Assign
				</BbButton>
			</template>
		</BbSelectPopover>

		<BbButton
			prepend:icon="lucide:arrow-right"
			size="sm"
			variant="ghost"
			@click="ctx.bulkMoveToNextSprint"
		>
			Next sprint
		</BbButton>

		<div class="floating-bottom-panel__right flex items-center gap-1">
			<BbButton
				aria-label="Clear selection"
				icon="lucide:x"
				size="sm"
				variant="ghost"
				@click="ctx.table.resetSelection"
			/>
		</div>
	</FloatingBottomPanel>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbSelectPopover } from 'bitboss-ui';
import FloatingBottomPanel from '@/components/layout/FloatingBottomPanel.vue';
import { STATUS_OPTIONS, searchMembers, useBacklogWorkspace } from './context';
import type { IssueStatus, Member } from '@/types';

const ctx = useBacklogWorkspace();

// `all` (select-all-across-pages) does not enumerate rows, so the visible
// count is the total minus whatever the user manually deselected.
const selectedCount = computed(() =>
	ctx.table.all.value
		? ctx.table.totalItems.value - ctx.table.unselected.value.length
		: ctx.table.selected.value.length
);
</script>
```

### IssuePeek.vue

```vue
<!-- BacklogWorkspace/IssuePeek.vue -->
<template>
	<div v-if="issue" class="flex flex-col gap-4 text-sm">
		<!-- Identity header. -->
		<header class="flex flex-col gap-1">
			<p class="text-xs font-medium text-[color:var(--bb-text-muted)]">
				{{ issue.ref }}
			</p>
			<h2 class="text-base font-semibold">{{ issue.title }}</h2>
		</header>

		<!-- Properties: the SAME editable cells as the grid — one leaf, two
		call sites. Change the status here and the grid's badge (and even the
		blocked-row tint) moves in the same tick, because both surfaces read
		the same overlay; the spinner shows in both places at once. -->
		<dl class="grid grid-cols-[auto_1fr] items-center gap-x-4 gap-y-2">
			<dt class="text-[color:var(--bb-text-muted)]">Status</dt>
			<dd><StatusCell :issue="issue" /></dd>
			<dt class="text-[color:var(--bb-text-muted)]">Priority</dt>
			<dd><PriorityCell :issue="issue" /></dd>
			<dt class="text-[color:var(--bb-text-muted)]">Assignee</dt>
			<dd><AssigneeCell :issue="issue" /></dd>
			<dt class="text-[color:var(--bb-text-muted)]">Estimate</dt>
			<dd>
				{{
					ctx.valueOf(issue, 'estimate') === null
						? 'Unestimated'
						: `${ctx.valueOf(issue, 'estimate')} points`
				}}
			</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Sprint</dt>
			<dd>{{ issue.sprint }}</dd>
		</dl>

		<!-- Description. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Description
			</h3>
			<p class="whitespace-pre-line text-[color:var(--bb-text-muted)]">
				{{ issue.description }}
			</p>
		</section>

		<!-- Activity feed. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Activity
			</h3>
			<ul class="flex flex-col gap-2">
				<li v-for="entry in issue.activity" :key="entry.id" class="flex gap-2">
					<BbIcon
						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
						:icon="entry.icon"
						size="14"
					/>
					<div class="flex flex-col">
						<span>{{ entry.text }}</span>
						<span class="text-xs text-[color:var(--bb-text-muted)]"
							>{{ entry.actor }} · {{ longDate(entry.at) }}</span
						>
					</div>
				</li>
			</ul>
		</section>

		<!-- Peek is a workbench: act here, or leave for the full page. -->
		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				prepend:icon="lucide:arrow-right"
				size="sm"
				variant="secondary"
				@click="() => ctx.moveToNextSprint(issue!)"
			>
				Next sprint
			</BbButton>
			<BbButton
				size="sm"
				variant="destructive"
				@click="() => ctx.deleteIssue(issue!)"
			>
				Delete
			</BbButton>
			<BbButton
				append:icon="lucide:arrow-up-right"
				:href="`/issues/${issue.id}`"
				size="sm"
				variant="ghost"
			>
				Open full page
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { watch } from 'vue';
import { BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
import { useResourceContext } from '@/composables/useResourceContext';
import AssigneeCell from './AssigneeCell.vue';
import PriorityCell from './PriorityCell.vue';
import StatusCell from './StatusCell.vue';
import { useBacklogWorkspace } from './context';
import type { IssueDetail } from '@/types';

const props = defineProps<{ issueId: string }>();

const ctx = useBacklogWorkspace();

// A small JSON endpoint, not a page visit — opening the peek never
// re-renders the list underneath it. Re-fetches whenever the stack shows a
// different issue; `refreshKey` makes every commit (from the grid OR this
// panel) reflect here immediately. The cells inside don't flash across that
// reload either — they read the overlay, which only retires once fresh data
// confirms it.
const { data: issue, refresh } = useResourceContext<IssueDetail, string>(
	() => props.issueId,
	(id) => fetch(`/issues/${id}/peek`).then((res) => res.json())
);
watch(() => ctx.refreshKey.value, refresh);

const longDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
		year: 'numeric',
	});
</script>
```

## Why it is built this way

- **`pending` sits on rung 3, and the recipe's whole shape follows from
  that.** Three consumers force it up the ladder: the cells read it to render
  optimistically, the peek reads it so the second call site of every cell
  agrees with the first, and the retirement watcher reads it to drop
  confirmed fields when fresh rows land. Contrast the records workspace's
  §6.1 status cell, where `saving` is a rung-1 local `ref` around one awaited
  action — correct **there** because nothing but that one cell ever cares.
  Here the code that ingests fresh rows must know what's in flight, so a
  local flag physically cannot work; that is why the picker cells bind
  `:loading="ctx.isSaving(issue, 'status')"` instead of owning a `saving`
  ref.
- **`persistField` is one complete action for every control kind.** Text,
  number, and three pickers all commit through the same guard → optimistic
  set → PATCH visit pipeline (the visit's own partial reload is the refetch),
  so the failure story (drop one field, destructive toast) and the no-op
  story (blur without change costs nothing) are written once. The guard
  compares against `valueOf`, not the raw row — what the user _sees_ is the
  value they are re-committing.
- **Retirement lives where the prop lands because that is when the truth
  changes.** A resolved PATCH visit proves the server accepted the value —
  its response even carries fresh `issues` — but the overlay must still
  retire per-field, only for values the fresh rows confirm: a slow title
  save must survive a fast status save's reload untouched, and rows also
  arrive through visits this page never initiates. One watcher on the
  ingested rows is the choke point for every arrival path. The comment above
  it ships with the recipe on purpose: this is the §6.8 bug everyone writes
  once.
- **The `visit()` helper is the promise-wrapped router-visit pattern** from
  the records workspace: it turns Inertia's `onSuccess`/`onError` callbacks
  into a promise so `persistField` and every discrete action stay `async`
  functions — identical call sites to the Vue/Nuxt recipes. Field saves
  reload only `['issues']` (the hottest path on the page); discrete and bulk
  actions reload `tabCounts` too, because they move issues between tabs.
- **One watcher for filters, one visit mechanism for tabs.**
  `useQueryObject(..., { only: ['issues', 'tabCounts'] })` over a URL-shaped
  projection of `filters` is the entire filter-to-URL wiring; `BbTabs`'
  `href` + `server: true` items (with the required component-level
  `navigation`) make tab switches real partial visits with the same `only`
  list — one source of server truth, reached two ways. Each `href` is built
  by `tabHref()`, which merges `tab` into the current query rather than
  replacing it — `href: '/sprints/24?tab=backlog'` alone would drop every
  active filter, and because `preserve-state` keeps this page instance (and
  `ctx.filters`) alive across the visit, the chips would keep showing the
  old filters as active over an unfiltered result set.
- **Bulk actions carry the full select-all-across-pages payload**
  (`ids`/`all`/`unselected`) — never just an enumerated id list that
  silently drops rows outside the current page.
- **`valueOf` checks `key in patch`, not `??`.** A cleared estimate commits
  `null`, and `null ?? row.estimate` would silently un-render the overlay
  while the save runs. The one-line comment in the context is load-bearing.
- **No dirty ring anywhere, no success toasts for cell commits.** Autosave
  has no "changed but unsaved" state, so the ring (the draft-map pattern's
  grammar) would lie; and a page where every blur saves would toast
  constantly. The spinner in the chevron's place is the feedback; failure is
  the exception worth announcing (destructive toast + `has-errors` on the
  text/number cells via the `failed` set; badge cells announce by visibly
  snapping back). Discrete actions — duplicate, move, delete, bulk — _do_
  toast success: they are events, not keystrokes.
- **Five cells, five leaves.** `EditableTitleCell`, `EstimateCell`,
  `StatusCell`, `PriorityCell`, `AssigneeCell` — never one `EditableCell`
  with a `type` prop growing a renderer switch (§6.3/§4). Each takes exactly
  one data prop (`issue`) and gets its behavior from the context.
- **Typed inputs commit on `@change`; pickers commit on pick.** The text and
  number cells bind `:model-value` down and read the committed value from the
  native event (`event.target`); the number cell's change carries the raw
  string where `''` means cleared. No debounce machinery — blur/Enter and
  pick are natural commit points, so the request count equals the commit
  count.
- **Options resolve once.** Status and priority are module-level catalogs
  shared by the cells, the rail pills and the bulk picker — zero requests.
  The assignee is genuinely query-driven, so it gets the one exception: a
  **single** shared provider (`searchMembers`), lazy per instance, keeping
  unopened rows free — filtering the `team` page prop client-side, so it
  never even makes a request; prefill calls return the whole six-person team
  so the current selection always resolves. Rows store the whole member, so every badge and the
  filter pill label themselves from data they already hold — no
  `watchEffect`-to-resolve-a-name anywhere on this page.
- **The ref cell is the peek handle** because the title — the "name" of an
  issue — is an input here, and a click that sometimes edits and sometimes
  navigates is a broken affordance. One record type also collapses the stack
  grammar to a single verb (`peekIssue`, fresh stack).
- **The peek reuses the grid's cells verbatim** — one leaf, two call sites.
  Both read the same overlay, so a status change made in the panel updates
  the grid row (badge, tint, spinner) in the same tick, and vice versa. Its
  detail is a JSON fetch via `useResourceContext`, not a visit, so opening
  it never re-renders the list underneath.
- **Sizing:** topbar follows `md`-first (`compact` inputs at 28px flush
  beside the default buttons); `sm` appears exactly where the doctrine
  allows — rail pills, row actions, the bulk bar, the peek footer. Cell
  inputs are `compact`.
- **One `variant="primary"`** (New issue). The only irreversible action
  (delete — row menu and peek footer) rides `useConfirm`; moving between
  sprints is reversible, so it deliberately does not.

## Variations

- **Keyboard triage**: add `keyboard-navigation` to the table —
  `v-model:highlighted` already drives the peek — the approvals-inbox recipe
  is the full treatment; the overlay needs no changes, since it never cared
  how a commit was triggered.
- **Review-before-save domains**: if the product wants a batch the user
  confirms (accounting lines, permissions), swap the overlay for the
  draft-map pattern — dirty ring, dirty-gated Save — per the
  [Inline Edit Playbook](../../guides/inline-edit-playbook.md); the
  record-form recipe's line-item editor assembles it, with `usePromiseForm`
  as the batch's engine on this platform. Never mix both grammars on one
  table.
- **Undo instead of confirm**: for softer destructive-ish moves (Done →
  reopened), a success toast with an Undo action that visits the old value
  back through `persistField` is more Linear than a confirm dialog.
- **Live board**: because fresh rows retire the overlay per confirmed field,
  a polling `router.reload({ only: ['issues', 'tabCounts'] })` (or a
  websocket-triggered one) is safe — a poll landing mid-save cannot destroy
  an in-flight edit, which is exactly the property the write-back
  anti-pattern lacks.
- **Big directory**: if the team is hundreds of people, stop sending `team`
  eagerly — share it as `Inertia::optional()` and adapt it with
  `useLazyPropGetter`, or point `searchMembers` at a small JSON search
  endpoint like the records-workspace customer filter. Only the provider's
  body changes.

---

<!-- dist/ai/recipes/inertia/layout-scaffold.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/inertia/layout-scaffold.md -->

<!--
	GENERATED FILE — do not edit by hand.
	Source: fixtures/inertia/app/components/layout/usePageShellContext.ts, fixtures/inertia/app/components/layout/PageShell.vue, fixtures/inertia/app/components/layout/FloatingBottomPanel.vue
	Regenerate: npm run docs:scaffold
-->

# Recipe: Layout Scaffold (Inertia)

**Build this first.** Every page recipe imports `PageShell`,
`usePageShellContext` and `FloatingBottomPanel` from your own app — they are
_not_ package exports, by design: page chrome is yours to own and restyle. The
recipes assume the files below already exist. Create them verbatim, then the
rest of the recipes compile as written.

Sibling scaffolds: [Vue](../vue/layout-scaffold.md) · [Nuxt](../nuxt/layout-scaffold.md).

## Prerequisites

- `@vueuse/core` — `usePageShellContext.ts` imports `injectLocal`/`provideLocal`
  from it. `npm i @vueuse/core`. This library also depends on it, so it may
  already be resolvable via hoisting — don't rely on that: a package your own
  code imports belongs in your own `package.json`, or a strict installer
  (pnpm, Yarn PnP) will fail to resolve it.

## Why these are not package exports

A shell is the one part of an app that every product wants to own. Exporting it
would force our page grammar on your product and make every future change to it
a breaking change for you. Copying it costs you three files once and leaves the
chrome yours.

What you must **not** do is invent your own. These files encode behaviour the
page recipes depend on: the peek renders from a _stack_ (so a peek can open a
peek, and the back arrow works), `close()` empties that stack rather than
hiding a panel, and the closed sidebar is removed from flow with
`overflow-x: clip` on the body instead of an animated `padding-right` that
thrashes layout on every open.

## The files

### `resources/js/components/layout/usePageShellContext.ts`

The peek **stack**, not a boolean. `push(item)` opens a peek on top of the current one (so a peek can open a peek and the back arrow works), `push(item, true)` resets to a single top-level peek, and `close()` empties the stack. Provide/inject is idempotent — the page context and `PageShell` call it and share one instance, so neither has to pass it to the other.

```ts
import { injectLocal, provideLocal } from '@vueuse/core';
import { computed, ref, type ComputedRef, type Ref } from 'vue';

export type PageShellContext<T> = {
	/** The peek stack; the last entry is what the sidebar shows. */
	stack: Ref<T[]>;
	/** The top of the stack, or null when the sidebar is closed. */
	current: ComputedRef<T | null>;
	/** Stack depth — the shell shows a back arrow when > 1. */
	depth: ComputedRef<number>;
	/** Push a peek. `reset` opens a fresh stack (a top-level peek). */
	push: (item: T, reset?: boolean) => void;
	/**
	 * Open `item` as a fresh top-level peek — what a row click does. Reads as
	 * the intent rather than as `push(item, true)`, whose boolean says nothing
	 * at the call site.
	 */
	peek: (item: T) => void;
	/**
	 * Drill from the open peek into a related record, keeping the back arrow.
	 * The other half of the same intent pair.
	 */
	stackItem: (item: T) => void;
	/** Pop one level (the back arrow). */
	pop: () => void;
	/** Close the sidebar entirely. */
	close: () => void;
};

const KEY = 'page-shell';

export function usePageShellContext<T>(): PageShellContext<T> {
	const existing = injectLocal<PageShellContext<T> | null>(KEY, null);
	if (existing != null) return existing;

	const stack = ref<T[]>([]) as Ref<T[]>;
	const current = computed<T | null>(() => stack.value.at(-1) ?? null);
	const depth = computed(() => stack.value.length);

	const push = (item: T, reset = false) => {
		stack.value = reset ? [item] : [...stack.value, item];
	};
	// Named intents over the same primitive: `push(item, true)` at a call site
	// reads as "push, and something about true", which is how pilots end up
	// resetting a stack they meant to drill into.
	const peek = (item: T) => push(item, true);
	const stackItem = (item: T) => push(item);
	const pop = () => {
		stack.value = stack.value.slice(0, -1);
	};
	const close = () => {
		stack.value = [];
	};

	const context: PageShellContext<T> = {
		stack,
		current,
		depth,
		push,
		peek,
		stackItem,
		pop,
		close,
	};
	provideLocal(KEY, context);
	return context;
}
```

### `resources/js/components/layout/PageShell.vue`

The page frame: sticky topbar, body, and the peek sidebar with its own back/close chrome. The closed sidebar is taken out of flow by `overflow-x: clip` on the body — **not** by animating `padding-right` on the content, which thrashes layout on every open and leaves a phantom column behind.

```vue
<template>
	<div class="page-shell">
		<div v-if="$slots.topbar" class="page-shell__topbar">
			<slot name="topbar" />
		</div>

		<div class="page-shell__body">
			<!-- A `<div>`, not `<main>`: the app-side layout (AppLayout /
			     AppShell) already owns the page's one `<main>` landmark. A
			     second `<main>` here would nest two landmarks. -->
			<div class="page-shell__content">
				<slot />
			</div>

			<transition name="page-shell-sidebar">
				<aside
					v-if="shell.current.value"
					ref="panel"
					:aria-label="$slots['sidebar-title'] ? undefined : 'Details'"
					:aria-labelledby="$slots['sidebar-title'] ? titleId : undefined"
					class="page-shell__sidebar"
					data-test="page-shell-sidebar"
					tabindex="-1"
					@keydown.esc="onEscape"
				>
					<header class="page-shell__sidebar-chrome">
						<BbButton
							v-if="shell.depth.value > 1"
							aria-label="Back"
							data-test="peek-back"
							icon="lucide:arrow-left"
							size="sm"
							variant="ghost"
							@click="shell.pop"
						>
							Back
						</BbButton>
						<h2
							v-if="$slots['sidebar-title']"
							:id="titleId"
							class="page-shell__sidebar-title"
							data-test="peek-title"
						>
							<slot name="sidebar-title" />
						</h2>
						<span v-else class="page-shell__sidebar-spacer" />
						<BbButton
							aria-label="Close"
							data-test="peek-close"
							icon="lucide:x"
							size="sm"
							variant="ghost"
							@click="shell.close"
						>
							Close
						</BbButton>
					</header>
					<div class="page-shell__sidebar-body">
						<slot name="sidebar" />
					</div>
				</aside>
			</transition>
		</div>

		<slot name="dialogs" />
	</div>
</template>

<script setup lang="ts" generic="T">
import { nextTick, ref, useId, watch } from 'vue';
import { BbButton, useMobile, useSafeArea } from 'bitboss-ui';
import { usePageShellContext } from '@/components/layout/usePageShellContext';

const shell = usePageShellContext<T>();

/**
 * The peek sidebar is docked in the page, not floating over it, so nothing in
 * the library can tell it is there — and a toast would land on top of it. This
 * claims the right edge while it is open, and the toast stack slides clear.
 * Only on desktop: below the mobile breakpoint the sidebar covers the page
 * instead of sitting beside it (the `@media` block at the end of the styles),
 * so there is no edge to claim.
 *
 * SIDEBAR_W must stay in step with `.page-shell__sidebar { width }` below — it
 * is the same fact stated twice. (Pass `element: <the aside>` instead if you
 * make the panel resizable; the claim is then measured, not declared.)
 */
const SIDEBAR_W = 352; // 22rem
const { isMobile } = useMobile();
useSafeArea({
	side: 'right',
	// A declared size can't tell whether the panel is on screen — say so here
	// (`null` = nothing docked), or the edge stays claimed with no sidebar up.
	size: () => (shell.current.value ? SIDEBAR_W : null),
	active: () => !isMobile.value,
});

/**
 * Keyboard and screen-reader baseline for the peek. Deliberately NOT a focus
 * trap: on desktop this is a docked, non-modal panel and the page beside it
 * stays live and clickable, so trapping Tab would strand the keyboard in a
 * region the user can see past. What a non-modal panel does owe is a name,
 * focus that lands in it when it opens, focus that goes back where it came
 * from when it closes, and Escape. (The mobile sheet form below covers the
 * page, and that IS the shape where containment starts to matter — see the
 * Page Shell guide before adding a trap for it.)
 */
const panel = ref<HTMLElement | null>(null);
const titleId = useId();

/** The page-side control that opened the peek, to hand focus back to. */
let opener: HTMLElement | null = null;

watch(shell.current, async (item) => {
	if (item) {
		// Runs on flush 'pre', so the DOM is still the pre-change one: whatever
		// is focused now is the control that caused this. Only page-side ones
		// are worth remembering — a drill-down link lives inside the panel and
		// is destroyed by the very record it opens.
		const active = document.activeElement;
		if (active instanceof HTMLElement && !panel.value?.contains(active)) {
			opener = active;
		}

		// Focus the panel on every change, not just on open: a drill-down or a
		// Back destroys the control that was focused, and focus would otherwise
		// fall to <body> mid-consult. Landing on the panel also re-announces
		// its title, which is the record that just changed.
		await nextTick();
		panel.value?.focus();
		return;
	}

	const trigger = opener;
	opener = null;
	// The row may have been filtered away or re-rendered while the peek was
	// open; focusing a detached node quietly drops focus on <body> instead.
	if (trigger?.isConnected) trigger.focus();
});

const onEscape = (event: KeyboardEvent) => {
	// Library overlays (dropdown, popover, dialog) take Escape at the document
	// in the capture phase and stop it there, so this only ever sees the key
	// when the peek itself is the top-most open surface. `defaultPrevented`
	// covers anything app-side that handles Escape without stopping it.
	if (event.defaultPrevented) return;
	shell.close();
};
</script>

<style scoped>
.page-shell {
	display: flex;
	flex: 1;
	flex-direction: column;
	min-height: 0;
}

.page-shell__topbar {
	background: var(--bb-panel);
	position: sticky;
	/* Flush with the viewport by default. If your app layout puts a
	   sticky bar above the page (a brand/app bar), set --app-bar-h on an
	   ancestor and this topbar sits under it instead of overlapping it.

	   Two bars stacking is INTENTIONAL, not a layout bug to collapse: an
	   app/brand bar belongs to the SHELL, a topbar belongs to the PAGE. Keep
	   the two variables apart — --app-bar-h is the shell bar's height used
	   here as a sticky OFFSET, while that bar's own row height (if it needs a
	   name) is --app-bar-row-h. Conflating them is what makes a page topbar
	   sit exactly one bar too low. (Ruled PG-018, 2026-08-07.) */
	top: var(--app-bar-h, 0);
	z-index: 5;
}

.page-shell__body {
	display: flex;
	flex: 1;
	min-height: 0;
	overflow-x: clip;
}

.page-shell__content {
	flex: 1;
	min-width: 0;
}

/* Overlay sheet pinned on the parcel — same hairline as every other divider,
   no lead pin: the sidebar's edge stays uniform with the page grid. */
.page-shell__sidebar {
	background: color-mix(in oklab, var(--bb-panel) 92%, transparent);
	border-inline-start: 1px solid var(--bb-border);
	display: flex;
	flex-direction: column;
	flex-shrink: 0;
	/* Keep in step with SIDEBAR_W in the script — the safe-area claim that
	   keeps toasts off this panel is declared from that number. */
	width: 22rem;
}

.page-shell__sidebar-chrome {
	align-items: center;
	border-block-end: 1px solid var(--bb-border);
	display: flex;
	gap: 0.5rem;
	padding: 0.5rem 1rem;
}

.page-shell__sidebar-spacer {
	flex: 1;
}

.page-shell__sidebar-title {
	flex: 1;
	font-size: 15px;
	font-weight: 600;
	letter-spacing: -0.01em;
	min-width: 0;
	overflow: hidden;
	text-overflow: ellipsis;
	white-space: nowrap;
}

.page-shell__sidebar-body {
	overflow-y: auto;
	padding: 1rem;
}

.page-shell-sidebar-enter-active,
.page-shell-sidebar-leave-active {
	transition:
		transform var(--bb-transition-fast) var(--bb-ease),
		opacity var(--bb-transition-fast) var(--bb-ease);
}

.page-shell-sidebar-enter-from,
.page-shell-sidebar-leave-to {
	opacity: 0;
	transform: translateX(0.75rem);
}

/* Below the mobile breakpoint there is no room for a 22rem column beside the
   content, so the peek stops being a column and becomes a sheet over the whole
   page — chrome included, since its own header carries Back and Close.

   767.98px is `config.mobileMaxWidth` (768) minus a hair: the exact query
   `useMobile()` runs. The two must agree, or there is a band of widths where
   the safe-area claim above still thinks a panel is docked at the right edge
   while this rule has it covering the page. */
@media (max-width: 767.98px) {
	.page-shell__sidebar {
		/* Opaque here — the docked form is translucent over the page grid, but
		   a sheet that covers content must not let it show through. */
		background: var(--bb-panel);
		border-inline-start: 0;
		inset: 0;
		position: fixed;
		width: auto;
		/* Above the page topbar (5) and the floating bottom panel (30): while
		   the sheet is up, it is the page. */
		z-index: 40;
	}

	.page-shell__sidebar-body {
		/* The sheet runs to the bottom edge, so its own padding is what keeps
		   the last row clear of the home indicator. */
		padding-block-end: calc(1rem + env(safe-area-inset-bottom));
	}
}
</style>
```

### `resources/js/components/layout/FloatingBottomPanel.vue`

The selection dock. It hugs its content (`width: max-content` + `margin-inline: auto`) rather than stretching edge to edge — a full-bleed bar reads as broken viewport chrome instead of a response to your selection.

```vue
<template>
	<transition name="floating-bottom-panel">
		<div
			v-if="open"
			aria-label="Selection actions"
			class="floating-bottom-panel"
			data-test="selection-bar"
			role="region"
		>
			<slot />
		</div>
	</transition>
</template>

<script setup lang="ts">
defineProps<{ open?: boolean }>();
</script>

<style scoped>
.floating-bottom-panel {
	align-items: center;
	background: var(--bb-panel);
	border: 1px solid var(--bb-border);
	border-radius: var(--bb-radius-surface);
	box-shadow: var(--bb-shadow);
	display: flex;
	gap: 0.5rem;
	inset-block-end: 1.25rem;
	inset-inline: 0;
	margin-inline: auto;
	max-width: calc(100% - 2rem);
	padding: 0.375rem 0.5rem;
	position: fixed;
	width: max-content;
	z-index: 30;
}

.floating-bottom-panel :deep(.floating-bottom-panel__right) {
	border-inline-start: 1px solid var(--bb-border);
	margin-inline-start: 0.75rem;
	padding-inline-start: 0.75rem;
}

.floating-bottom-panel-enter-active,
.floating-bottom-panel-leave-active {
	transition:
		transform var(--bb-transition-fast) var(--bb-ease),
		opacity var(--bb-transition-fast) var(--bb-ease);
}

.floating-bottom-panel-enter-from,
.floating-bottom-panel-leave-to {
	opacity: 0;
	transform: translateY(0.75rem);
}
</style>
```

## Wiring a page

**One topbar per page (GROK-BTG-013).** The `#topbar` slot is the page's single
top command bar — breadcrumbs/title on the left, page commands (search, the
primary action) on the right. `PageShell` renders it as its own sticky bar; do
**not** stack a second brand/utility bar above it. Primary navigation lives in
the [App Layout](../../guides/app-layout.md) sidebar, and app-wide utilities
(global search, a user menu) go **into** this same topbar — never a second
stacked row.

The topbar row is `justify-between`: the breadcrumb trail and the trailing
controls both shrink by default, so the trail collapses to its own overflow
menu while free space sits unused in the middle. Give the trail
`class="min-w-0 flex-auto"` so it consumes that slack on a stable basis, and
`shrink-0` to its siblings so they stay content-sized — the same contract
the `BbBreadcrumbs` guide documents for exactly this row.

```vue
<template>
	<PageShell>
		<template #topbar>
			<div class="flex items-center justify-between gap-4 px-4">
				<!-- `flex-auto min-w-0` lets the trail consume the row's slack (and
             shrink/overflow) instead of being sized by its content. -->
				<BbBreadcrumbs class="min-w-0 flex-auto" :items="breadcrumbs" />
				<!-- `shrink-0` keeps search/actions/the account menu content-sized so
             they never lose the tug-of-war with the trail above. -->
				<div class="flex shrink-0 items-center gap-2">
					<!-- page search, primary action, AccountMenu (see below) -->
				</div>
			</div>
		</template>

		<!-- default slot: the page body -->
		<!-- The shipped `--highlighted` tint already marks the current row;
         `row-class` is how this page says WHY it is current (the open peek)
         and how you override the look. See the BbTable guide's Row highlight
         section. -->
		<BbTable
			v-model:highlighted="highlighted"
			:columns="columns"
			:items="items"
			:row-class="rowClass"
		/>

		<template #sidebar>
			<RecordPeek v-if="shell.current.value" :id="shell.current.value" />
		</template>

		<template #dialogs>
			<!-- dialogs mount here so they escape the body's overflow clip -->
		</template>
	</PageShell>

	<FloatingBottomPanel :open="selectedCount > 0">
		<span>{{ selectedCount }} selected</span>
	</FloatingBottomPanel>
</template>
```

## Topbar value pickers (account menu, theme, warehouse)

App-chrome value pickers — theme, an active warehouse/location, anything the
user picks occasionally rather than filters by — do not belong on a bordered
form `BbSelect` in the topbar; that is a field control, and the topbar has
no form. Reach for a ghost `BbButton` opening a `BbSelectPopover`, or (when
it lives next to other account actions) an account `BbDropdown` with nested
selectable submenus, exactly like the `NestedMenu` and `SelectableMenu`
patterns in the `BbDropdown` guide, combined: each category is a submenu
opener whose own `items` holds one selectable group, so picking a value
closes the whole menu back to the top level.

```vue
<template>
	<BbDropdown :items="accountMenuItems" placement="bottom-end" :width="240">
		<template #activator="{ props }">
			<BbButton
				v-bind="props"
				aria-label="Account menu"
				class="gap-1.5"
				size="sm"
				variant="ghost"
			>
				<BbAvatar size="xs">SE</BbAvatar>
			</BbButton>
		</template>
		<!-- Companions bind to a group by `id`; the group itself stays declared
         in `items` below. -->
		<BbDropdownGroup id="theme-opts" v-model="theme" />
		<BbDropdownGroup id="warehouse-opts" v-model="warehouseId" />
	</BbDropdown>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbAvatar, BbButton, BbDropdown, BbDropdownGroup } from 'bitboss-ui';
import type { BbDropdownItem } from 'bitboss-ui';

const theme = ref<'system' | 'light' | 'dark'>('system');
const warehouseId = ref('denver');

const accountMenuItems: BbDropdownItem[] = [
	{
		key: 'theme',
		text: 'Theme',
		'prepend:icon': 'lucide:sun-moon',
		// A submenu opener (`items`) whose own `items` is one selectable
		// group — `selectable: true` gives single-choice radio semantics and a
		// check on the picked row, with no bordered field anywhere.
		items: [
			{
				key: 'theme-opts',
				selectable: true,
				items: [
					{ key: 'system', text: 'System' },
					{ key: 'light', text: 'Light' },
					{ key: 'dark', text: 'Dark' },
				],
			},
		],
	},
	{
		key: 'warehouse',
		text: 'Warehouse',
		'prepend:icon': 'lucide:warehouse',
		items: [
			{
				key: 'warehouse-opts',
				selectable: true,
				items: [
					{ key: 'denver', text: 'Denver DC' },
					{ key: 'reno', text: 'Reno DC' },
					{ key: 'columbus', text: 'Columbus DC' },
				],
			},
		],
	},
	// A trailing separator section (a nested array) for plain navigation rows.
	[
		{
			key: 'settings',
			text: 'Settings',
			'prepend:icon': 'lucide:settings',
			href: '/settings',
		},
		{
			key: 'signout',
			text: 'Sign out',
			'prepend:icon': 'lucide:log-out',
			href: '/logout',
			method: 'post',
		},
	],
];
</script>
```

Watch `theme`/`warehouseId` and act on the change (flip `html.dark`, refetch
scoped to the new warehouse) the same way any other v-model-driven picker
would — the dropdown only owns the menu, never the side effect.

## The peek must stay in sync with the table highlight

`BbTable`'s `v-model:highlighted` and the shell stack are two pieces of state
pointing at one idea ("which row is open"). Wire **both** directions or the
second click on a row does nothing: the user closes the peek, the highlight is
still set, and a re-click leaves it unchanged so no watcher fires.

```ts
watch(highlighted, (id) => {
	if (id == null) {
		if (shell.current.value != null) shell.close();
		return;
	}
	shell.peek(id);
});

// The other direction: closing the peek clears the highlight, so the same row
// can open it again.
watch(shell.current, (current) => {
	if (current == null && highlighted.value != null) highlighted.value = null;
});
```

If a page has no peek, omit `v-model:highlighted` entirely. A highlight that
paints a selected row but opens nothing is a dead affordance.

## `workspace-surfaces.css` — the helpers every page re-invents

`.plain-link`, `.table-flush` and the row tints are project CSS by design (the
library ships no such classes), but they are the _same_ project CSS on every
workspace page. (`.table-flush`'s edge-inset rules address the table through
its grid containers — `> .bb-table__table > .bb-table__body > [role='row'] >
:first-child` — never through `table`/`tbody`/`tr`/`td`, which the table no
longer renders; the canonical block is in the BbTable guide § Styling hooks.)
Author them **once**, next to the layout, and import that file
from the app entry — not per page, and never copy-pasted into a page's
`<style scoped>`, which is how three pages end up with three underline colours.

```css
/* src/components/layout/workspace-surfaces.css */
.plain-link {
	color: inherit;
	text-decoration: underline;
	text-underline-offset: 2px;
	text-decoration-color: color-mix(in oklab, var(--bb-text) 25%, transparent);
	transition: text-decoration-color var(--bb-transition-fast) var(--bb-ease);
}
.plain-link:hover,
.plain-link:focus-visible {
	text-decoration-color: currentColor;
	outline: none;
}

.row-danger {
	background: color-mix(in oklab, var(--bb-danger) 6%, var(--bb-panel));
}
.row-danger:hover {
	background: color-mix(in oklab, var(--bb-danger) 10%, var(--bb-panel));
}
.row-warn {
	background: color-mix(in oklab, var(--bb-warn) 6%, var(--bb-panel));
}
.row-warn:hover {
	background: color-mix(in oklab, var(--bb-warn) 10%, var(--bb-panel));
}
```

Every rule here is built from `--bb-*` tokens, so the whole sheet follows the
theme and dark mode without a second dark block. See
[design-language](../../guides/design-language.md) § Row tint and § the
`.plain-link` helper for the reasoning behind each.

## Shortcuts live in the topbar, not in the page

A keyboard-driven screen needs its shortcuts discoverable, and the reflex is an
inline hint bar above the table. That bar is permanent chrome for information
read once. Default to a **topbar affordance**: a keyboard icon in
`#topbar-actions` opening a `BbPopover` that lists the bindings.

```vue
<BbPopover>
	<template #activator="{ props }">
		<BbButton v-bind="props" aria-label="Keyboard shortcuts" icon="lucide:keyboard" size="sm" variant="ghost" />
	</template>
	<dl class="shortcuts">…</dl>
</BbPopover>
```

An **inline** shortcut bar is a triage exception — a queue whose entire purpose
is rapid keyboard disposition (see the approvals-inbox recipe), where the
bindings are the primary UI rather than a reference. Everywhere else, the
topbar popover keeps the body for the records.

## The height chain — `flex: 1` only works if its parent fills the viewport

`PageShell` sets `flex: 1` on itself and `min-height: 0` on its body, but that
is a claim on space its **parent** has to actually own. If the main column is a
plain block, the shell is as tall as its content: a short page leaves the peek
sidebar floating mid-screen, and a long one scrolls the whole document instead
of the content area.

Every link in the chain has to hold, top to bottom:

| Level        | Rule                                                      |
| ------------ | --------------------------------------------------------- |
| layout root  | `min-height: 100dvh` (grid or flex — it just has to fill) |
| main column  | `display: flex; flex-direction: column; min-height: 0`    |
| content slot | `flex: 1; min-height: 0`                                  |
| `PageShell`  | `flex: 1` (already in the component)                      |

`min-height: 0` on every flex child is the part people drop. Without it a flex
item refuses to shrink below its content, so the _inner_ scroll container never
scrolls and the page grows instead — the classic "why is my sticky topbar
scrolling away" symptom.

## Do not nest a drawer inside the peek

The `#sidebar` slot **is** the drawer. Putting a `BbOffCanvas` inside it gives
you two stacked drawers with two close buttons. Pick one: the PageShell stack
for in-page detail, or a standalone `BbOffCanvas` for chrome that is not about
the current page (mobile nav, global filters).

---

<!-- dist/ai/recipes/inertia/onboarding.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/inertia/onboarding.md -->

# Recipe: Workspace Onboarding (Inertia)

The onboarding checklist adapted for **Laravel + Inertia**: the same live
progress header, single-open accordion whose steps carry the real actions
inline, and "see what you'll get" preview peeks — but the checklist state
arrives as a page prop, every mutation is a promise-wrapped `router.visit`
with `only: ['onboarding']` so statuses re-arrive in the same round trip,
the invite and project steps submit through
[`usePromiseForm`](../../guides/inertia-helpers.md) with 422 errors mapped
onto their fields, and the CSV import binds the file into a native `useForm`
that serializes multipart automatically. Anatomy, components, the context
shape, copy and data are identical to the Vue recipe; only the
data/mutation layer changes.

Sibling recipes: [Vue](../vue/onboarding.md) · [Nuxt](../nuxt/onboarding.md).

## Prerequisites

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell` and `usePageShellContext` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
- `<BbConfirm />` and `<BbToast />` mounted once in the `createInertiaApp` render root — never in a page.
- From the [Inertia Helpers](../../guides/inertia-helpers.md) toolkit:
  `useProp`, `usePromiseForm`.
- Controller: `Inertia::render('Onboarding/Index', ['onboarding' => [
'steps' => [...], 'connectedIntegrations' => [...], 'workspace' => ...,
'invites' => [...], 'firstProject' => ..., 'importedCustomers' => ...,
'reminders' => ['enabled' => ..., 'cadence' => ...]]])` — one compound
  prop is the whole checklist's server truth, re-sent on every partial
  reload the page triggers (`only: ['onboarding']`). Mutation routes are
  plain Laravel routes that redirect back (`PATCH /onboarding/steps/:id`,
  `POST /onboarding/integrations/:id/connect`, `POST /onboarding/invites`,
  `POST /onboarding/project`, `POST /onboarding/customers/import`,
  `PATCH /onboarding/reminders`, `POST /onboarding/dismiss`); the mutation
  that changes a step's real state (connecting an integration, sending
  invites, importing customers, enabling reminders) also flips that step's
  status server-side, so the client never computes completion itself.

## Key ideas

- **One coopting page context.** `provideOnboardingWorkspace()` joins the
  page-shell stack once, owns the step statuses, the integration and invite
  state, and every action. Every leaf calls `useOnboardingWorkspace()` and
  nothing else — zero prop drilling anywhere on the page.
- **`onboarding` is a page prop, not a client fetch.** `useProp<...>('onboarding')`
  gives a reactive read of the server's current checklist state; a single
  `watch` re-seeds `steps`, `integrations`, `invites`, `firstProject` and
  `reminders` from it every time a visit lands a fresh copy — there is no
  separate load call and no `persistStatus` writer, because the server
  already recomputes step statuses as part of each mutation response.
- **Mutations are promise-wrapped `router.visit` calls.** A tiny local
  `visit()` helper turns Inertia's callback-based API into a promise, so
  most context actions stay `async function`s exactly like the Vue/Nuxt
  versions — `await ctx.toggleIntegration(...)` reads the same everywhere.
- **Invites and the project form use `usePromiseForm`, with 422 on the
  fields.** These two steps carry real user input, so their context actions
  wrap `usePromiseForm` instead of the generic `visit()` helper; a failed
  submit rejects with Laravel's field-keyed error bag, and the step's own
  `inviteError`/`nameError` display catches and maps it — the same local
  error slot the client-side checks already use.
- **The CSV import binds the file into a `useForm`.** Inertia serializes a
  bound `File` as multipart automatically and exposes real upload bytes via
  `onProgress`, so the import step needs no manual `FormData` or XHR
  wiring — unlike the Nuxt adaptation, which has to reach for a raw
  `XMLHttpRequest` because `ofetch` has no progress hook.
- **Single-open accordion, modeled — not wrapped.** `BbAccordion` is one
  panel per boolean; there is no group component by design. One
  `activeStep` key in the context derives every panel's `model-value`, and
  finishing a step advances the key to the next unfinished one.
- **Previews ride the shell stack.** "See what you'll get" pushes a
  `step-preview` peek (replace semantics — previews never stack); the peek
  is a workbench: identity header, benefit list, a stat, and a "Set it up
  now" action that jumps back to the step.
- **Checklist archetype, so rows 4/5/7/8 of the standard anatomy don't
  apply**: no filter rail, no tabs, no pagination, no selection/bulk bar —
  and no page search, since the page has no filterable collection. Page
  Shell, breadcrumbs topbar and the stacked peek sidebar stay.
- **Buttons are `md` by default**; one `variant="primary"` on the page
  ("Go to dashboard" in the topbar); step submits are `secondary`,
  done/skip/preview are `ghost`; "Dismiss onboarding" rides `useConfirm`.

## Page anatomy

```
OnboardingChecklist/
	Index.vue                ← assembly: PageShell slots, accordion loop, thin
	context.ts               ← coopting page context (shell + onboarding prop + actions)
	ProgressHeader.vue       ← title, dismiss, BbProgress + "4 of 7 complete"
	StepHeader.vue           ← status icon, title, minutes, chevron (in the header button)
	StepActions.vue          ← per-step done / skip / preview footer row
	ProfileStep.vue          ← step 1 body: completed-at-signup summary + edit link
	IntegrationsStep.vue     ← step 2 body: BbSwitch rows (Stripe, QuickBooks, Slack, Drive)
	InviteStep.vue           ← step 3 body: BbTag emails + role BbSelect + send
	FirstProjectStep.vue     ← step 4 body: mini create-project form
	ImportCustomersStep.vue  ← step 5 body: BbDropzone CSV + BbProgress upload
	FirstInvoiceStep.vue     ← step 6 body: link-out to the invoice composer
	RemindersStep.vue        ← step 7 body: reminders switch + cadence select
	StepPreviewPeek.vue      ← sidebar "what you'll get" workbench per step
```

Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
(left nav + fat footer) and [Page Shell](../../guides/page-shell.md). The
dismiss confirmation renders through the app-wide `useConfirm` host, so this
page needs no `#dialogs` content of its own.

## Action inventory

| #   | Action                           | Trigger                             | Mechanism                                                               |
| --- | -------------------------------- | ----------------------------------- | ----------------------------------------------------------------------- |
| 1   | Go to dashboard                  | topbar, the page's one `primary`    | navigation (`href="/dashboard"`)                                        |
| 2   | Dismiss onboarding               | progress header, ghost              | `useConfirm` (destructive) → `router.post` + toast, server redirects    |
| 3   | Expand / collapse a step         | accordion header (single-open)      | `activeStep` key derives each panel's `model-value`                     |
| 4   | See what you'll get              | every step footer                   | `previewStep(id)` → shell peek (replace)                                |
| 5   | Mark step done / skip step       | step footer ghosts                  | `completeStep` / `skipStep` → promise-wrapped visit                     |
| 6   | Connect / disconnect integration | switch rows in _Connect your tools_ | optimistic toggle, `readonly` in flight, revert + toast on failure      |
| 7   | Compose the invite list          | `BbTag` (Enter/comma, max 10)       | local ref; `duplicate`/`max` surfaced via `errors`                      |
| 8   | Choose the invite role           | `BbSelect` beside the tags          | local ref                                                               |
| 9   | Send invitations                 | secondary button in step body       | `sendInvites` → `usePromiseForm`, 422 → `inviteError`                   |
| 10  | Create the first project         | mini form submit                    | `createProject` → `usePromiseForm`, 422 → `nameError`                   |
| 11  | Import customers CSV             | `BbDropzone` + Import button        | `importCustomers` → `useForm` multipart; `BbProgress` from `onProgress` |
| 12  | Open the invoice composer        | outline button in step 6            | navigation (`href="/invoices/create"`)                                  |
| 13  | Turn reminders on / pick cadence | switch + select in step 7           | `setReminders` / `setReminderCadence` + toast                           |
| 14  | Jump to a step from its preview  | peek footer                         | `jumpToStep(id)` → open step + close peek                               |
| 15  | Edit the workspace profile       | link in the completed profile step  | navigation (`href="/settings/general"`)                                 |
| 16  | Close the peek                   | shell chrome                        | shell stack close                                                       |

## The code

### context.ts

```ts
// OnboardingChecklist/context.ts
import {
	computed,
	inject,
	provide,
	reactive,
	ref,
	watch,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import { router, useForm } from '@inertiajs/vue3';
import type { RequestPayload } from '@inertiajs/core';
import { useConfirm, useToast } from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import { useProp } from '@/composables/useProp';
import { usePromiseForm } from '@/composables/usePromiseForm';
import type {
	InviteRole,
	PendingInvite,
	Project,
	ProjectDraft,
	ReminderCadence,
	WorkspaceProfile,
} from '@/types';

export type StepId =
	| 'profile'
	| 'integrations'
	| 'invites'
	| 'first-project'
	| 'import-customers'
	| 'first-invoice'
	| 'reminders';

export type StepStatus = 'todo' | 'complete' | 'skipped';

export interface OnboardingStep {
	id: StepId;
	title: string;
	description: string;
	/** Rough time estimate shown in the header while the step is open. */
	minutes: number;
	status: StepStatus;
}

export interface WorkspaceIntegration {
	id: string;
	name: string;
	description: string;
	/** Full static literal — the production icon scanner only bundles names it can see. */
	icon: string;
	connected: boolean;
	/** True while a connect/disconnect request is in flight (drives `readonly`). */
	busy: boolean;
}

/** What the stacked sidebar can show: the per-step "what you'll get" preview. */
export type PeekItem = { type: 'step-preview'; stepId: StepId };

/** The whole `onboarding` page prop — the server's checklist truth. */
type OnboardingProp = {
	steps: Record<StepId, StepStatus>;
	connectedIntegrations: string[];
	workspace: WorkspaceProfile;
	invites: PendingInvite[];
	firstProject: Project | null;
	importedCustomers: number | null;
	reminders: { enabled: boolean; cadence: ReminderCadence };
};

const RELOAD_PROPS = ['onboarding'] as const;

/** Inertia's callback-based visit, wrapped as a promise — so every simple
 * context action stays `async`, exactly like the Vue/Nuxt versions. Always a
 * partial reload of `onboarding`, the only prop this page depends on. */
const visit = (
	method: 'post' | 'patch' | 'delete',
	url: string,
	// Inertia's own payload type — strings/numbers/booleans/arrays/files.
	// (`Record<string, unknown>` does not satisfy it.)
	data: RequestPayload = {}
): Promise<void> =>
	new Promise((resolve, reject) => {
		router.visit(url, {
			method,
			data,
			only: [...RELOAD_PROPS],
			preserveScroll: true,
			preserveState: true,
			onSuccess: () => resolve(),
			onError: (errors) => reject(errors),
		});
	});

const STEP_DEFS: Record<StepId, Omit<OnboardingStep, 'status'>> = {
	profile: {
		id: 'profile',
		title: 'Set up your company profile',
		description: 'Legal name, billing address and tax details.',
		minutes: 2,
	},
	integrations: {
		id: 'integrations',
		title: 'Connect your tools',
		description:
			'Stripe for payments, QuickBooks for the books, Slack for alerts.',
		minutes: 3,
	},
	invites: {
		id: 'invites',
		title: 'Invite your teammates',
		description:
			'Billing works better when the whole team sees the same numbers.',
		minutes: 2,
	},
	'first-project': {
		id: 'first-project',
		title: 'Create your first project',
		description:
			'Projects group invoices, budgets and time entries per client.',
		minutes: 1,
	},
	'import-customers': {
		id: 'import-customers',
		title: 'Import your customers',
		description: 'Bring your existing customer list over as a CSV.',
		minutes: 5,
	},
	'first-invoice': {
		id: 'first-invoice',
		title: 'Send your first invoice',
		description: 'Compose, preview and send — payment link included.',
		minutes: 4,
	},
	reminders: {
		id: 'reminders',
		title: 'Turn on payment reminders',
		description: 'Stop chasing overdue invoices by hand.',
		minutes: 1,
	},
};
const STEP_ORDER: StepId[] = [
	'profile',
	'integrations',
	'invites',
	'first-project',
	'import-customers',
	'first-invoice',
	'reminders',
];

export interface OnboardingWorkspaceContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	// -- Page-owned state (seeded + re-seeded from the `onboarding` prop) ------
	steps: OnboardingStep[];
	/** The one open panel; `null` collapses everything (single-open accordion). */
	activeStep: Ref<StepId | null>;
	/** Steps no longer todo (complete or skipped) — drives the progress bar. */
	doneCount: ComputedRef<number>;
	allDone: ComputedRef<boolean>;
	workspace: Ref<WorkspaceProfile | null>;
	integrations: WorkspaceIntegration[];
	invites: Ref<PendingInvite[]>;
	firstProject: Ref<Project | null>;
	importState: {
		uploading: boolean;
		sentBytes: number;
		totalBytes: number;
		importedCount: number | null;
	};
	reminders: { enabled: boolean; cadence: ReminderCadence };
	// -- Step grammar ----------------------------------------------------------
	openStep: (id: StepId | null) => void;
	previewStep: (id: StepId) => void;
	jumpToStep: (id: StepId) => void;
	// -- Actions (complete: visit + toast; the server recomputes statuses) -----
	completeStep: (id: StepId) => Promise<void>;
	skipStep: (id: StepId) => Promise<void>;
	toggleIntegration: (
		integration: WorkspaceIntegration,
		next: boolean
	) => Promise<void>;
	/** Rejects with Laravel's field-keyed error bag on 422 — steps map it locally. */
	sendInvites: (emails: string[], role: InviteRole) => Promise<void>;
	createProject: (draft: ProjectDraft) => Promise<void>;
	importCustomers: (file: File) => Promise<void>;
	setReminders: (enabled: boolean) => Promise<void>;
	setReminderCadence: (cadence: ReminderCadence) => Promise<void>;
	dismissOnboarding: () => Promise<void>;
}

const key: InjectionKey<OnboardingWorkspaceContext> = Symbol(
	'onboarding-workspace'
);

export function provideOnboardingWorkspace(): OnboardingWorkspaceContext {
	const { toast } = useToast();
	const { confirm } = useConfirm();

	// -- Coopt the specific contexts: once, here, for the whole page. ----------
	const shell = usePageShellContext<PeekItem>();

	// -- Reactive read of the server's checklist truth. -------------------------
	const onboarding = useProp<OnboardingProp>('onboarding');

	// -- The checklist definition lives client-side; the server owns statuses. -
	const steps = reactive<OnboardingStep[]>(
		STEP_ORDER.map((id) => ({ ...STEP_DEFS[id], status: 'todo' }))
	);

	// Icon names are full static literals: the production icon scanner bundles
	// only literals it can see, and brand SVGs live in the app's iconDir.
	const integrations = reactive<WorkspaceIntegration[]>([
		{
			id: 'stripe',
			name: 'Stripe',
			description: 'Accept card payments; payouts reconcile against invoices.',
			icon: 'local:stripe',
			connected: false,
			busy: false,
		},
		{
			id: 'quickbooks',
			name: 'QuickBooks Online',
			description: 'Push paid invoices straight into your accounting.',
			icon: 'local:quickbooks',
			connected: false,
			busy: false,
		},
		{
			id: 'slack',
			name: 'Slack',
			description: 'A message in #finance when an invoice is paid or overdue.',
			icon: 'local:slack',
			connected: false,
			busy: false,
		},
		{
			id: 'google-drive',
			name: 'Google Drive',
			description: 'Attach contracts and receipts from your shared drives.',
			icon: 'local:google-drive',
			connected: false,
			busy: false,
		},
	]);

	const activeStep = ref<StepId | null>(null);
	const workspace = ref<WorkspaceProfile | null>(null);
	const invites = ref<PendingInvite[]>([]);
	const firstProject = ref<Project | null>(null);
	const importState = reactive({
		uploading: false,
		sentBytes: 0,
		totalBytes: 0,
		importedCount: null as number | null,
	});
	const reminders = reactive({
		enabled: false,
		cadence: '3-7-14' as ReminderCadence,
	});

	// Re-seed every local field whenever a visit lands a fresh `onboarding`
	// prop — the only place server truth flows into page state.
	const applyState = (state: OnboardingProp) => {
		for (const item of steps) item.status = state.steps[item.id];
		const connected = new Set(state.connectedIntegrations);
		for (const integration of integrations)
			integration.connected = connected.has(integration.id);
		workspace.value = state.workspace;
		invites.value = state.invites;
		firstProject.value = state.firstProject;
		importState.importedCount = state.importedCustomers;
		reminders.enabled = state.reminders.enabled;
		reminders.cadence = state.reminders.cadence;
	};
	applyState(onboarding.value);
	watch(onboarding, applyState);

	// Open the first unfinished step, right after the initial page load —
	// Inertia props are already hydrated before this runs, so no separate
	// loading state is needed the way the Nuxt adaptation needs one.
	activeStep.value =
		steps.find((candidate) => candidate.status === 'todo')?.id ?? null;

	// Skipped counts as done: the bar rewards moving on, like Linear's checklist.
	const doneCount = computed(
		() => steps.filter((step) => step.status !== 'todo').length
	);
	const allDone = computed(() => doneCount.value === steps.length);

	const step = (id: StepId): OnboardingStep =>
		steps.find((candidate) => candidate.id === id)!;

	// -- Step grammar ----------------------------------------------------------------
	const openStep = (id: StepId | null) => {
		activeStep.value = id;
	};
	// Previews replace: a checklist preview never stacks on another preview.
	const previewStep = (id: StepId) =>
		shell.push({ type: 'step-preview', stepId: id }, true);
	// From the peek back into the page: open the step and drop the sidebar.
	const jumpToStep = (id: StepId) => {
		activeStep.value = id;
		shell.close();
	};
	const openNextTodo = (after: StepId) => {
		const index = steps.findIndex((candidate) => candidate.id === after);
		const next = [...steps.slice(index + 1), ...steps.slice(0, index)].find(
			(candidate) => candidate.status === 'todo'
		);
		activeStep.value = next?.id ?? null;
	};

	// -- Actions --------------------------------------------------------------------
	// Manual done/skip: the same status endpoint the domain mutations below
	// hit implicitly server-side. The response's `onboarding` prop already
	// carries the new status by the time this promise resolves.
	const completeStep = async (id: StepId) => {
		const title = step(id).title;
		await visit('patch', `/onboarding/steps/${id}`, { status: 'complete' });
		toast({ title: `"${title}" checked off.`, variant: 'success' });
		openNextTodo(id);
	};

	// Skipping is quiet: it is a dismissal, not an achievement.
	const skipStep = async (id: StepId) => {
		await visit('patch', `/onboarding/steps/${id}`, { status: 'skipped' });
		openNextTodo(id);
	};

	// Optimistic, per the BbSwitch doctrine: flip now, revert + toast on failure.
	// `busy` drives `readonly` so conflicting toggles cannot queue. The server
	// flips the 'integrations' step to complete on a successful connect; the
	// partial reload brings that back with everything else.
	const toggleIntegration = async (
		integration: WorkspaceIntegration,
		next: boolean
	) => {
		integration.busy = true;
		integration.connected = next;
		try {
			await visit(
				'post',
				`/onboarding/integrations/${integration.id}/${next ? 'connect' : 'disconnect'}`
			);
			toast({
				title: `${integration.name} ${next ? 'connected' : 'disconnected'}.`,
				variant: 'success',
			});
		} catch {
			integration.connected = !next;
			toast({
				title: `Could not ${next ? 'connect' : 'disconnect'} ${integration.name}.`,
				variant: 'destructive',
			});
		} finally {
			integration.busy = false;
		}
	};

	// Carries real user input, so it rides usePromiseForm instead of the
	// generic visit() helper: a 422 rejects with Laravel's field-keyed error
	// bag, which InviteStep maps onto its own `inviteError` display.
	const invitesForm = usePromiseForm<{ emails: string[]; role: InviteRole }>({
		emails: [],
		role: 'member',
	});
	const sendInvites = async (emails: string[], role: InviteRole) => {
		invitesForm.form.emails = emails;
		invitesForm.form.role = role;
		await invitesForm.post('/onboarding/invites', {
			only: [...RELOAD_PROPS],
		});
		toast({
			title: `${emails.length} invitation${emails.length === 1 ? '' : 's'} sent.`,
			variant: 'success',
		});
	};

	const projectForm = usePromiseForm<{ name: string; client: string }>({
		name: '',
		client: '',
	});
	const createProject = async (draft: ProjectDraft) => {
		projectForm.form.name = draft.name;
		projectForm.form.client = draft.client;
		await projectForm.post('/onboarding/project', {
			only: [...RELOAD_PROPS],
		});
		toast({ title: `${draft.name} created.`, variant: 'success' });
	};

	// The bound File serializes as multipart automatically; onProgress gives
	// real upload bytes natively — no manual FormData/XHR wiring needed.
	const importForm = useForm<{ file: File | null }>({ file: null });
	const importCustomers = (file: File): Promise<void> => {
		importState.uploading = true;
		importState.totalBytes = file.size;
		importState.sentBytes = 0;
		importForm.file = file;
		return new Promise((resolve, reject) => {
			importForm.post('/onboarding/customers/import', {
				only: [...RELOAD_PROPS],
				forceFormData: true,
				onProgress: (event) => {
					if (event?.total) {
						importState.sentBytes = event.loaded ?? 0;
						importState.totalBytes = event.total;
					}
				},
				onSuccess: () => {
					importState.uploading = false;
					toast({
						title: `${onboarding.value.importedCustomers ?? 0} customers imported.`,
						variant: 'success',
					});
					resolve();
				},
				onError: (errors) => {
					importState.uploading = false;
					reject(errors);
				},
			});
		});
	};

	const setReminders = async (enabled: boolean) => {
		reminders.enabled = enabled;
		try {
			await visit('patch', '/onboarding/reminders', {
				enabled,
				cadence: reminders.cadence,
			});
			toast({
				title: enabled
					? 'Payment reminders are on.'
					: 'Payment reminders turned off.',
				variant: 'success',
			});
		} catch {
			reminders.enabled = !enabled;
			toast({ title: 'Could not update reminders.', variant: 'destructive' });
		}
	};

	const setReminderCadence = async (cadence: ReminderCadence) => {
		reminders.cadence = cadence;
		await visit('patch', '/onboarding/reminders', {
			enabled: reminders.enabled,
			cadence,
		});
		toast({ title: 'Reminder schedule updated.', variant: 'success' });
	};

	const dismissOnboarding = async () => {
		const ok = await confirm({
			variant: 'destructive',
			title: 'Dismiss onboarding',
			text: 'Hide the setup checklist for everyone in this workspace? Unfinished steps stay available under Settings → Setup.',
			yes: 'Dismiss',
			no: 'Keep it',
		});
		if (!ok) return;
		// A full visit, not a partial reload: the server redirects to the
		// dashboard, so there is no `onboarding` prop left to re-seed from.
		router.visit('/onboarding/dismiss', { method: 'post' });
		toast({
			title: 'Onboarding dismissed. Find it again under Settings → Setup.',
			variant: 'success',
		});
	};

	const ctx: OnboardingWorkspaceContext = {
		shell,
		steps,
		activeStep,
		doneCount,
		allDone,
		workspace,
		integrations,
		invites,
		firstProject,
		importState,
		reminders,
		openStep,
		previewStep,
		jumpToStep,
		completeStep,
		skipStep,
		toggleIntegration,
		sendInvites,
		createProject,
		importCustomers,
		setReminders,
		setReminderCadence,
		dismissOnboarding,
	};
	provide(key, ctx);
	return ctx;
}

export function useOnboardingWorkspace(): OnboardingWorkspaceContext {
	const ctx = inject(key);
	if (!ctx)
		throw new Error(
			'useOnboardingWorkspace() called outside OnboardingChecklist'
		);
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- OnboardingChecklist/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left, the page's one primary action right. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs
					class="min-w-0 flex-auto"
					:items="[
						{ key: 'dashboard', text: 'Dashboard', href: '/dashboard' },
						{ key: 'getting-started', text: 'Getting started' },
					]"
				/>
				<BbButton
					append:icon="lucide:arrow-right"
					class="shrink-0"
					href="/dashboard"
					variant="primary"
				>
					Go to dashboard
				</BbButton>
			</div>
		</template>

		<div class="mx-auto flex w-full max-w-3xl flex-col gap-6 p-4">
			<ProgressHeader />

			<!-- Single-open checklist: one active key in the context derives every
			     panel's model-value; opening one closes the rest, and clicking the
			     open header collapses everything (payload is false → key null). -->
			<div class="flex flex-col divide-y rounded-[var(--bb-radius)] border">
				<BbAccordion
					v-for="item in ctx.steps"
					:key="item.id"
					:model-value="ctx.activeStep.value === item.id"
					@update:model-value="(open) => ctx.openStep(open ? item.id : null)"
				>
					<template #header="{ value }">
						<StepHeader :open="value" :step="item" />
					</template>
					<div class="flex flex-col gap-4 px-11 pb-4">
						<component :is="stepBodies[item.id]" />
						<StepActions :step="item" />
					</div>
				</BbAccordion>
			</div>

			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Stuck on a step?
				<BbButton href="/docs/setup" size="sm" variant="link"
					>Read the setup guide</BbButton
				>
				— it covers every integration and the CSV format.
			</p>
		</div>

		<!-- The peek sidebar: the shell owns back/close; we render by type. -->
		<template #sidebar>
			<StepPreviewPeek
				v-if="ctx.shell.current.value?.type === 'step-preview'"
				:step-id="ctx.shell.current.value.stepId"
			/>
		</template>
	</PageShell>
</template>

<script setup lang="ts">
import type { Component } from 'vue';
import { BbAccordion, BbBreadcrumbs, BbButton } from 'bitboss-ui';
import PageShell from '@/components/layout/PageShell.vue';
import { provideOnboardingWorkspace, type StepId } from './context';
import FirstInvoiceStep from './FirstInvoiceStep.vue';
import FirstProjectStep from './FirstProjectStep.vue';
import ImportCustomersStep from './ImportCustomersStep.vue';
import IntegrationsStep from './IntegrationsStep.vue';
import InviteStep from './InviteStep.vue';
import ProfileStep from './ProfileStep.vue';
import ProgressHeader from './ProgressHeader.vue';
import RemindersStep from './RemindersStep.vue';
import StepActions from './StepActions.vue';
import StepHeader from './StepHeader.vue';
import StepPreviewPeek from './StepPreviewPeek.vue';

const ctx = provideOnboardingWorkspace();

// Each step body is its own component — a lookup, not a `type` prop.
const stepBodies: Record<StepId, Component> = {
	profile: ProfileStep,
	integrations: IntegrationsStep,
	invites: InviteStep,
	'first-project': FirstProjectStep,
	'import-customers': ImportCustomersStep,
	'first-invoice': FirstInvoiceStep,
	reminders: RemindersStep,
};
</script>
```

### ProgressHeader.vue

```vue
<!-- OnboardingChecklist/ProgressHeader.vue -->
<template>
	<header class="flex flex-col gap-3">
		<div class="flex items-start justify-between gap-4">
			<div class="flex flex-col gap-1">
				<h1 class="text-xl font-semibold">Set up Acme</h1>
				<p class="text-sm text-[color:var(--bb-text-muted)]">
					A few steps to get your billing workspace ready for the whole team.
				</p>
			</div>
			<BbButton variant="ghost" @click="ctx.dismissOnboarding">
				Dismiss onboarding
			</BbButton>
		</div>

		<div class="flex flex-col gap-1.5">
			<div class="flex items-center justify-between gap-4 text-sm">
				<span class="font-medium">
					{{
						ctx.allDone.value
							? 'All set — your workspace is ready.'
							: 'Your setup checklist'
					}}
				</span>
				<span class="text-[color:var(--bb-text-muted)]">
					{{ ctx.doneCount.value }} of {{ ctx.steps.length }} complete
				</span>
			</div>
			<!-- Real units in, no pre-computed percentage: max = number of steps. -->
			<BbProgress
				aria-label="Setup progress"
				:aria-valuetext="`${ctx.doneCount.value} of ${ctx.steps.length} steps complete`"
				:max="ctx.steps.length"
				:model-value="ctx.doneCount.value"
			/>
		</div>
	</header>
</template>

<script setup lang="ts">
import { BbButton, BbProgress } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';

const ctx = useOnboardingWorkspace();
</script>
```

### StepHeader.vue

```vue
<!-- OnboardingChecklist/StepHeader.vue -->
<template>
	<!-- Rendered INSIDE the accordion's header button: everything here is
	     non-interactive and click-transparent by design — the whole row toggles. -->
	<span class="flex w-full items-center gap-3 px-3 py-3 text-left">
		<BbIcon
			class="shrink-0"
			:class="
				step.status === 'complete'
					? 'text-green-600'
					: 'text-[color:var(--bb-text-muted)]'
			"
			:icon="statusIcon"
			size="20"
		/>
		<span class="flex min-w-0 flex-1 flex-col">
			<span
				class="text-sm font-medium"
				:class="
					step.status === 'todo' ? '' : 'text-[color:var(--bb-text-muted)]'
				"
			>
				{{ step.title }}
			</span>
			<span class="truncate text-xs text-[color:var(--bb-text-muted)]">{{
				step.description
			}}</span>
		</span>
		<span
			v-if="step.status === 'skipped'"
			class="shrink-0 text-xs uppercase tracking-wide text-[color:var(--bb-text-muted)]"
		>
			Skipped
		</span>
		<span
			v-else-if="step.status === 'todo'"
			class="shrink-0 text-xs text-[color:var(--bb-text-muted)]"
		>
			~{{ step.minutes }} min
		</span>
		<BbIcon
			class="shrink-0 text-[color:var(--bb-text-muted)] transition-transform"
			:class="open ? 'rotate-180' : ''"
			icon="lucide:chevron-down"
			size="16"
		/>
	</span>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbIcon } from 'bitboss-ui';
import type { OnboardingStep } from './context';

const props = defineProps<{ open: boolean; step: OnboardingStep }>();

// Full literals — the production icon scanner needs complete names.
const icons = {
	todo: 'lucide:circle-dashed',
	complete: 'lucide:circle-check',
	skipped: 'lucide:circle-check',
} as const;
const statusIcon = computed(() => icons[props.step.status]);
</script>
```

### StepActions.vue

```vue
<!-- OnboardingChecklist/StepActions.vue -->
<template>
	<footer class="flex flex-wrap items-center gap-2 border-t pt-3">
		<template v-if="step.status === 'todo'">
			<BbButton
				prepend:icon="lucide:check"
				variant="ghost"
				@click="() => ctx.completeStep(step.id)"
			>
				Mark as done
			</BbButton>
			<BbButton variant="ghost" @click="() => ctx.skipStep(step.id)">
				Skip for now
			</BbButton>
		</template>
		<span v-else class="text-xs text-[color:var(--bb-text-muted)]">
			{{ step.status === 'complete' ? 'Completed' : 'Skipped' }} — revisit any
			time from Settings → Setup.
		</span>
		<BbButton
			append:icon="lucide:chevron-right"
			class="ml-auto"
			variant="ghost"
			@click="() => ctx.previewStep(step.id)"
		>
			See what you'll get
		</BbButton>
	</footer>
</template>

<script setup lang="ts">
import { BbButton } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';
import type { OnboardingStep } from './context';

defineProps<{ step: OnboardingStep }>();

const ctx = useOnboardingWorkspace();
</script>
```

### ProfileStep.vue

```vue
<!-- OnboardingChecklist/ProfileStep.vue -->
<template>
	<div v-if="ctx.workspace.value" class="flex flex-col gap-3 text-sm">
		<p class="text-[color:var(--bb-text-muted)]">
			Done at signup — these details appear on every invoice you send.
		</p>
		<dl class="grid grid-cols-[auto_1fr] gap-x-6 gap-y-1.5">
			<dt class="text-[color:var(--bb-text-muted)]">Company</dt>
			<dd>{{ ctx.workspace.value.company }}</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Billing address</dt>
			<dd>{{ ctx.workspace.value.address }}</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Tax ID</dt>
			<dd>{{ ctx.workspace.value.taxId }}</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Currency</dt>
			<dd>{{ ctx.workspace.value.currency }}</dd>
		</dl>
		<div>
			<BbButton
				href="/settings/general"
				prepend:icon="lucide:pencil"
				size="sm"
				variant="link"
			>
				Edit workspace profile
			</BbButton>
		</div>
	</div>
</template>

<script setup lang="ts">
import { BbButton } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';

const ctx = useOnboardingWorkspace();
</script>
```

### IntegrationsStep.vue

```vue
<!-- OnboardingChecklist/IntegrationsStep.vue -->
<template>
	<div class="flex flex-col text-sm">
		<p class="pb-1 text-[color:var(--bb-text-muted)]">
			Flip a switch to connect — you'll be sent through the provider's consent
			screen the first time.
		</p>
		<div
			v-for="integration in ctx.integrations"
			:key="integration.id"
			class="flex items-center gap-3 border-b py-2.5 last:border-b-0"
		>
			<BbIcon class="shrink-0" :icon="integration.icon" size="20" />
			<div class="flex min-w-0 flex-1 flex-col">
				<span class="font-medium">{{ integration.name }}</span>
				<span class="truncate text-xs text-[color:var(--bb-text-muted)]">
					{{ integration.description }}
				</span>
			</div>
			<!-- Instant-effect toggle: the context flips optimistically, holds the
			     switch readonly while in flight, and reverts + toasts on failure. -->
			<BbSwitch
				hide-label
				:label="`Connect ${integration.name}`"
				:model-value="integration.connected"
				:name="`integration-${integration.id}`"
				:readonly="integration.busy"
				@update:model-value="(next) => ctx.toggleIntegration(integration, next)"
			/>
		</div>
	</div>
</template>

<script setup lang="ts">
import { BbIcon, BbSwitch } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';

const ctx = useOnboardingWorkspace();
</script>
```

### InviteStep.vue

```vue
<!-- OnboardingChecklist/InviteStep.vue -->
<template>
	<div class="flex flex-col gap-3 text-sm">
		<p class="text-[color:var(--bb-text-muted)]">
			Paste addresses or type them — Enter or a comma adds each one.
		</p>

		<div class="flex flex-wrap items-end gap-2">
			<BbTag
				v-model="emails"
				class="min-w-64 flex-1"
				compact
				:divider="['Enter', ',']"
				:errors="inviteError"
				label="Email addresses"
				:max="10"
				placeholder="ada.rossi@acme.com"
				prepend:icon="lucide:mail"
				@duplicate="
					(email) => (inviteError = `${email} is already in the list.`)
				"
				@max="() => (inviteError = 'You can invite up to 10 people at once.')"
			/>
			<BbSelect
				v-model="role"
				class="w-44"
				compact
				item-text="label"
				item-value="value"
				:items="roles"
				label="Role"
				label-mode="outside"
			/>
			<BbButton prepend:icon="lucide:send" variant="secondary" @click="send">
				Send invitations
			</BbButton>
		</div>

		<ul v-if="ctx.invites.value.length" class="flex flex-col gap-1">
			<li
				v-for="invite in ctx.invites.value"
				:key="invite.email"
				class="flex items-center justify-between gap-2 text-xs"
			>
				<span>{{ invite.email }}</span>
				<span class="text-[color:var(--bb-text-muted)]"
					>{{ invite.role }} · invited {{ invite.sentAt }}</span
				>
			</li>
		</ul>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbSelect, BbTag } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';
import type { InviteRole } from '@/types';

const ctx = useOnboardingWorkspace();

// Draft state only this leaf touches: local refs, not context fields.
const emails = ref<string[]>([]);
const role = ref<InviteRole>('member');
const inviteError = ref('');

const roles: { value: InviteRole; label: string }[] = [
	{ value: 'admin', label: 'Admin' },
	{ value: 'member', label: 'Member' },
	{ value: 'accountant', label: 'Accountant' },
];

// Returning the promise lets the button's automatic loading track the send.
const send = async () => {
	inviteError.value = '';
	if (emails.value.length === 0) {
		inviteError.value = 'Add at least one email address.';
		return;
	}
	const invalid = emails.value.filter((email) => !email.includes('@'));
	if (invalid.length > 0) {
		inviteError.value = `${invalid.join(', ')} ${invalid.length === 1 ? 'is' : 'are'} not a valid address.`;
		return;
	}
	try {
		await ctx.sendInvites(emails.value, role.value);
		emails.value = [];
	} catch (errors) {
		// Server-side (422) validation lands here as Laravel's field-keyed
		// error bag — usePromiseForm rejects with it unchanged.
		const bag = errors as Record<string, string | string[]>;
		const message = bag.emails ?? bag.role;
		inviteError.value = Array.isArray(message)
			? message[0]
			: (message ?? 'Could not send invitations.');
	}
};
</script>
```

### FirstProjectStep.vue

```vue
<!-- OnboardingChecklist/FirstProjectStep.vue -->
<template>
	<!-- Already created (by this session or a teammate): show it, not the form. -->
	<div v-if="ctx.firstProject.value" class="flex items-center gap-2 text-sm">
		<BbIcon class="text-green-600" icon="lucide:circle-check" size="16" />
		<span>
			<span class="font-medium">{{ ctx.firstProject.value.name }}</span>
			is ready for its first invoice.
		</span>
		<BbButton
			append:icon="lucide:arrow-up-right"
			:href="`/projects/${ctx.firstProject.value.id}`"
			size="sm"
			variant="link"
		>
			Open project
		</BbButton>
	</div>

	<form
		v-else
		class="flex flex-col gap-3 text-sm"
		novalidate
		@submit.prevent="submit"
	>
		<p class="text-[color:var(--bb-text-muted)]">
			A project keeps one client's invoices, budget and time entries together.
		</p>
		<div class="flex flex-wrap items-end gap-2">
			<BbTextInput
				v-model="draft.name"
				class="min-w-56 flex-1"
				compact
				:errors="nameError"
				label="Project name"
				label-mode="outside"
				placeholder="Website redesign"
			/>
			<BbTextInput
				v-model="draft.client"
				class="min-w-56 flex-1"
				compact
				label="Client"
				label-mode="outside"
				placeholder="Globex Corporation"
			/>
			<BbButton prepend:icon="lucide:plus" type="submit" variant="secondary">
				Create project
			</BbButton>
		</div>
	</form>
</template>

<script setup lang="ts">
import { reactive, ref } from 'vue';
import { BbButton, BbIcon, BbTextInput } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';

const ctx = useOnboardingWorkspace();

const draft = reactive({ name: '', client: '' });
const nameError = ref('');

// Returning the promise lets the submit button track the async work.
const submit = async () => {
	nameError.value = '';
	if (!draft.name.trim()) {
		nameError.value = 'Give the project a name.';
		return;
	}
	try {
		await ctx.createProject({ ...draft });
	} catch (errors) {
		// Server-side (422) validation lands here as Laravel's field-keyed
		// error bag — usePromiseForm rejects with it unchanged.
		const bag = errors as Record<string, string | string[]>;
		const message = bag.name ?? bag.client;
		nameError.value = Array.isArray(message)
			? message[0]
			: (message ?? 'Could not create the project.');
	}
};
</script>
```

### ImportCustomersStep.vue

```vue
<!-- OnboardingChecklist/ImportCustomersStep.vue -->
<template>
	<div class="flex flex-col gap-3 text-sm">
		<!-- Already imported: report it instead of showing an empty dropzone. -->
		<div
			v-if="ctx.importState.importedCount !== null"
			class="flex items-center gap-2"
		>
			<BbIcon class="text-green-600" icon="lucide:circle-check" size="16" />
			<span>
				<span class="font-medium">{{ ctx.importState.importedCount }}</span>
				customers imported.
			</span>
			<BbButton
				append:icon="lucide:arrow-up-right"
				href="/customers"
				size="sm"
				variant="link"
			>
				View customers
			</BbButton>
		</div>

		<template v-else>
			<!-- MIME + extension pairing: Excel exports often carry a non-CSV MIME
			     type (or none at all on drag-drop) — '.csv' is what admits them. -->
			<BbDropzone
				v-model="file"
				:accept="['text/csv', '.csv']"
				:disabled="ctx.importState.uploading"
				:errors="fileError"
				:max-size="10 * 1024 * 1024"
				@error="onReject"
			>
				<template #default="{ dragging, focused, open }">
					<div
						class="flex flex-col items-center gap-2 rounded-[var(--bb-radius)] border-2 border-dashed p-6 text-center transition-colors"
						:class="[
							dragging
								? 'border-[color:var(--bb-primary)] bg-[color:var(--bb-panel)]'
								: '',
							focused ? 'ring-2 ring-[color:var(--bb-ring)]' : '',
						]"
					>
						<BbIcon
							class="text-[color:var(--bb-text-muted)]"
							icon="lucide:file-spreadsheet"
							size="24"
						/>
						<p class="font-medium">
							{{
								dragging ? 'Drop your CSV here' : 'Drag your customers CSV here'
							}}
						</p>
						<p class="text-xs text-[color:var(--bb-text-muted)]">
							We map name, email, VAT number and address columns. Up to 10 MB.
						</p>
						<BbButton size="sm" variant="ghost" @click="open"
							>or browse files</BbButton
						>
					</div>
				</template>
			</BbDropzone>

			<!-- Captured, not yet imported: confirm before touching the workspace. -->
			<div v-if="file" class="flex items-center gap-2">
				<BbIcon
					class="shrink-0 text-[color:var(--bb-text-muted)]"
					icon="lucide:file-text"
					size="16"
				/>
				<span class="min-w-0 flex-1 truncate">
					{{ file.name }}
					<span class="text-xs text-[color:var(--bb-text-muted)]"
						>· {{ formatSize(file.size) }}</span
					>
				</span>
				<BbButton
					aria-label="Remove selected file"
					:disabled="ctx.importState.uploading"
					icon="lucide:x"
					size="sm"
					variant="ghost"
					@click="() => (file = null)"
				/>
				<BbButton
					:disabled="ctx.importState.uploading"
					prepend:icon="lucide:upload"
					variant="secondary"
					@click="startImport"
				>
					Import customers
				</BbButton>
			</div>

			<!-- The dropzone captures; the context uploads and drives the bar. -->
			<div v-if="ctx.importState.uploading" class="flex flex-col gap-1">
				<BbProgress
					aria-label="Upload progress"
					:max="ctx.importState.totalBytes"
					:model-value="ctx.importState.sentBytes"
				/>
				<span class="text-xs text-[color:var(--bb-text-muted)]">
					Uploading… {{ formatSize(ctx.importState.sentBytes) }} of
					{{ formatSize(ctx.importState.totalBytes) }}
				</span>
			</div>
		</template>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbDropzone, BbIcon, BbProgress } from 'bitboss-ui';
import type { DropZoneError } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';

const ctx = useOnboardingWorkspace();

// The captured-but-not-imported file is this leaf's own state.
const file = ref<File | null>(null);
const fileError = ref('');

// Rejects never reach the model — map the typed error to a message and feed
// it back through `errors` (the display is a round-trip, not automatic).
const onReject = (error: DropZoneError) => {
	fileError.value =
		error.type === 'maxSize'
			? `${error.filename} is ${error.formattedSize} — the limit is ${error.formattedMaxSize}.`
			: error.type === 'accept'
				? `${error.filename} is not a CSV file.`
				: `${error.filename} was rejected.`;
};

const startImport = async () => {
	if (!file.value) return;
	fileError.value = '';
	await ctx.importCustomers(file.value);
	file.value = null;
};

const formatSize = (bytes: number) =>
	bytes >= 1024 * 1024
		? `${(bytes / 1024 / 1024).toFixed(1)} MB`
		: `${Math.max(1, Math.round(bytes / 1024))} KB`;
</script>
```

### FirstInvoiceStep.vue

```vue
<!-- OnboardingChecklist/FirstInvoiceStep.vue -->
<template>
	<div class="flex flex-col gap-3 text-sm">
		<p class="text-[color:var(--bb-text-muted)]">
			The composer walks you through line items, taxes and payment terms. Every
			invoice goes out with a payment link — customers pay by card or bank
			transfer without creating an account. This step checks itself off when
			your first invoice is sent.
		</p>
		<div>
			<BbButton
				append:icon="lucide:arrow-up-right"
				href="/invoices/create"
				prepend:icon="lucide:receipt"
				variant="outline"
			>
				Open the invoice composer
			</BbButton>
		</div>
	</div>
</template>

<script setup lang="ts">
import { BbButton } from 'bitboss-ui';
</script>
```

### RemindersStep.vue

```vue
<!-- OnboardingChecklist/RemindersStep.vue -->
<template>
	<div class="flex flex-col gap-3 text-sm">
		<!-- Instant-effect switch: the context applies optimistically and reverts
		     with a toast if the server rejects the change. -->
		<BbSwitch
			description="Email customers automatically when an invoice goes overdue. Replies land in your inbox."
			label="Automatic payment reminders"
			:model-value="ctx.reminders.enabled"
			name="payment-reminders"
			@update:model-value="(next) => ctx.setReminders(next)"
		/>
		<BbSelect
			v-if="ctx.reminders.enabled"
			class="max-w-72"
			compact
			item-text="label"
			item-value="value"
			:items="cadences"
			label="Reminder schedule"
			label-mode="outside"
			:model-value="ctx.reminders.cadence"
			@update:model-value="(cadence) => ctx.setReminderCadence(cadence)"
		/>
	</div>
</template>

<script setup lang="ts">
import { BbSelect, BbSwitch } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';
import type { ReminderCadence } from '@/types';

const ctx = useOnboardingWorkspace();

const cadences: { value: ReminderCadence; label: string }[] = [
	{ value: '3-7-14', label: '3, 7 and 14 days overdue' },
	{ value: '7', label: '7 days overdue' },
	{ value: '7-30', label: '7 and 30 days overdue' },
];
</script>
```

### StepPreviewPeek.vue

```vue
<!-- OnboardingChecklist/StepPreviewPeek.vue -->
<template>
	<div class="flex flex-col gap-4 text-sm">
		<!-- Identity header. -->
		<header class="flex items-center gap-3">
			<span
				class="flex h-9 w-9 shrink-0 items-center justify-center rounded-[var(--bb-radius)] border"
			>
				<BbIcon :icon="preview.icon" size="18" />
			</span>
			<div class="flex min-w-0 flex-col">
				<h2 class="text-base font-semibold">{{ preview.title }}</h2>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					{{ preview.tagline }}
				</p>
			</div>
		</header>

		<p
			v-if="step.status !== 'todo'"
			class="flex items-center gap-1.5 text-xs text-[color:var(--bb-text-muted)]"
		>
			<!-- Green is earned: skipped reads as reached-but-unmeasured, not done. -->
			<BbIcon
				:class="
					step.status === 'complete'
						? 'text-green-600'
						: 'text-[color:var(--bb-text-muted)]'
				"
				icon="lucide:circle-check"
				size="14"
			/>
			{{
				step.status === 'complete'
					? 'Already done in this workspace.'
					: 'Skipped — you can still set it up.'
			}}
		</p>

		<!-- What you'll get. -->
		<section class="flex flex-col gap-2.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				What you'll get
			</h3>
			<ul class="flex flex-col gap-2.5">
				<li
					v-for="bullet in preview.bullets"
					:key="bullet.title"
					class="flex gap-2"
				>
					<BbIcon
						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
						:icon="bullet.icon"
						size="14"
					/>
					<div class="flex flex-col">
						<span class="font-medium">{{ bullet.title }}</span>
						<span class="text-xs text-[color:var(--bb-text-muted)]">{{
							bullet.text
						}}</span>
					</div>
				</li>
			</ul>
		</section>

		<!-- One concrete number beats three adjectives. -->
		<div class="rounded-[var(--bb-radius)] border p-3">
			<p class="text-lg font-semibold">{{ preview.stat.value }}</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				{{ preview.stat.label }}
			</p>
		</div>

		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				v-if="step.status === 'todo'"
				prepend:icon="lucide:check"
				variant="secondary"
				@click="() => ctx.jumpToStep(stepId)"
			>
				Set it up now
			</BbButton>
			<BbButton v-else variant="ghost" @click="() => ctx.jumpToStep(stepId)">
				Review this step
			</BbButton>
		</footer>
	</div>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbIcon } from 'bitboss-ui';
import { useOnboardingWorkspace, type StepId } from './context';

const props = defineProps<{ stepId: StepId }>();

const ctx = useOnboardingWorkspace();

const step = computed(
	() => ctx.steps.find((candidate) => candidate.id === props.stepId)!
);
const preview = computed(() => previews[props.stepId]);

interface StepPreview {
	icon: string;
	title: string;
	tagline: string;
	bullets: { icon: string; title: string; text: string }[];
	stat: { value: string; label: string };
}

// Presentation content with a single consumer: it lives in the leaf, not the
// context. Icon names are full static literals for the production scanner.
const previews: Record<StepId, StepPreview> = {
	profile: {
		icon: 'lucide:building-2',
		title: 'A complete company profile',
		tagline: 'Set once, printed on every document.',
		bullets: [
			{
				icon: 'lucide:file-text',
				title: 'Compliant invoices',
				text: 'Legal name, address and tax ID appear on every PDF automatically.',
			},
			{
				icon: 'lucide:euro',
				title: 'One currency for the books',
				text: 'Amounts, totals and reports all use your workspace currency.',
			},
		],
		stat: {
			value: '2 min',
			label: 'to update it later under Settings → General',
		},
	},
	integrations: {
		icon: 'lucide:link',
		title: 'Your tools, wired together',
		tagline:
			'Payments, accounting and alerts stop being three separate chores.',
		bullets: [
			{
				icon: 'lucide:credit-card',
				title: 'Payments reconcile themselves',
				text: 'Stripe payouts are matched against open invoices automatically.',
			},
			{
				icon: 'lucide:receipt',
				title: 'Books stay current',
				text: 'Paid invoices flow into QuickBooks the moment they settle.',
			},
			{
				icon: 'lucide:bell',
				title: 'The team finds out in Slack',
				text: '#finance gets a message on every paid and overdue invoice.',
			},
		],
		stat: {
			value: '9 days',
			label: 'faster average payment for teams with Stripe connected',
		},
	},
	invites: {
		icon: 'lucide:users',
		title: 'Everyone on the same numbers',
		tagline: 'Roles keep access right-sized from day one.',
		bullets: [
			{
				icon: 'lucide:user-plus',
				title: 'Sign-in with work email',
				text: 'Invitees join with their address — no shared passwords.',
			},
			{
				icon: 'lucide:key-round',
				title: 'Permissions per role',
				text: 'Accountants see reports; members see their own projects.',
			},
			{
				icon: 'lucide:clock',
				title: 'Invitations expire safely',
				text: 'Unaccepted invites lapse after 7 days and can be re-sent.',
			},
		],
		stat: { value: '10', label: 'invitations per batch' },
	},
	'first-project': {
		icon: 'lucide:folder',
		title: 'A home for each client',
		tagline: 'Projects keep invoices, budgets and time in one place.',
		bullets: [
			{
				icon: 'lucide:folder-open',
				title: 'Everything grouped',
				text: 'Invoices, budgets and time entries organized per client.',
			},
			{
				icon: 'lucide:chart-line',
				title: 'Profitability from day one',
				text: 'A per-project margin view as soon as the first invoice is paid.',
			},
		],
		stat: {
			value: '3',
			label: 'projects created by the average team in week one',
		},
	},
	'import-customers': {
		icon: 'lucide:file-spreadsheet',
		title: 'Your customer list, moved over',
		tagline: 'The CSV you already have is enough.',
		bullets: [
			{
				icon: 'lucide:upload',
				title: 'Columns mapped for you',
				text: 'Name, email, VAT number and address are detected automatically.',
			},
			{
				icon: 'lucide:check',
				title: 'No double imports',
				text: 'Rows are merged by email — re-running an import never duplicates.',
			},
		],
		stat: { value: '5,000', label: 'rows per import' },
	},
	'first-invoice': {
		icon: 'lucide:receipt',
		title: 'Your first invoice, out the door',
		tagline: 'Composed, sent and tracked in one flow.',
		bullets: [
			{
				icon: 'lucide:send',
				title: 'Sent from your domain',
				text: 'Invoices arrive from billing@your-company, not a noreply void.',
			},
			{
				icon: 'lucide:banknote',
				title: 'Payment link included',
				text: 'Customers pay by card or bank transfer without an account.',
			},
			{
				icon: 'lucide:clock',
				title: 'Overdue tracking starts itself',
				text: 'Due dates and aging are tracked from the moment you hit send.',
			},
		],
		stat: {
			value: '2×',
			label: 'faster payment on invoices with a payment link',
		},
	},
	reminders: {
		icon: 'lucide:bell',
		title: 'Overdue chasing, automated',
		tagline: 'Polite nudges on a schedule you choose.',
		bullets: [
			{
				icon: 'lucide:clock',
				title: 'A schedule, not a scramble',
				text: 'Reminders at 3, 7 and 14 days overdue — or the cadence you pick.',
			},
			{
				icon: 'lucide:mail',
				title: 'Replies reach a human',
				text: 'Customers answer straight into your inbox thread.',
			},
		],
		stat: {
			value: '38%',
			label: 'fewer invoices reach 30 days overdue with reminders on',
		},
	},
};
</script>
```

## Why it is built this way

- **The context coopts the shell, leaves consume.** The only specific
  context on a checklist page is the peek stack; `provideOnboardingWorkspace()`
  joins it once and thirteen components share step state, integration
  state and every action through one `useOnboardingWorkspace()` call. No
  component receives a callback prop; the only data props are the `step` /
  `stepId` an item renders (`StepHeader`, `StepActions`, `StepPreviewPeek`)
  — everything else is injection.
- **The server recomputes step statuses, so the client never has to.**
  Every mutation route — connect an integration, send invites, create the
  project, import customers, enable reminders — flips the relevant step's
  status server-side as part of the same request; the partial reload
  (`only: ['onboarding']`) brings that back in one round trip. There is no
  `persistStatus` writer like the Vue/Nuxt versions: the local `steps`
  array is purely a mirror of `applyState`, re-run by a `watch` every time
  the prop changes.
- **`sendInvites`/`createProject` ride `usePromiseForm`, not the generic
  `visit()` helper.** They carry real user input with server-side
  validation, so a 422 needs to reach specific fields. `usePromiseForm`
  rejects with Laravel's field-keyed error bag on failure; `InviteStep` and
  `FirstProjectStep` are the only two leaves with a `try`/`catch` around
  their context call, mapping the bag onto the same `inviteError`/
  `nameError` display the client-side checks already populate — one error
  surface per field, whether the rejection came from the browser or the
  server.
- **The CSV import binds the file into a `useForm`, not `FormData`.**
  Inertia detects the bound `File` and switches the request to multipart
  automatically, and `onProgress` reports real `loaded`/`total` bytes
  natively — no manual `FormData` assembly and no `XMLHttpRequest`, unlike
  the Nuxt adaptation (`ofetch` has no upload-progress hook, so that one
  forces a raw XHR).
- **Single-open is one key, per the BbAccordion doctrine.** `BbAccordion`
  is deliberately one panel per boolean with no group wrapper; the
  `activeStep` key derives each `model-value`, the `update:modelValue`
  payload (`false` on closing the open header) resets it to `null`, and
  `openNextTodo` gives the Linear feel of the checklist walking itself
  forward. No watchers force-closing siblings.
- **Headers stay passive, actions live in the body.** The accordion header
  is already a `<button>`; the status icon, minutes estimate and chevron in
  `StepHeader` are click-transparent metadata. Everything interactive —
  done, skip, preview, the step's real controls — is body content, so the
  markup stays valid and the click target stays whole.
- **Every rung of the state ladder is deliberate.** Draft state one leaf
  touches is a local ref (invite emails and role, the project draft, the
  captured CSV file, the reject message); everything two components read
  sits on the context (statuses, `importState` driving `BbProgress`,
  reminders); nothing on this page outlives it, so no store is involved.
- **The switch promise is kept.** Integration and reminder toggles apply
  optimistically, hold the control `readonly` while the request flies, and
  revert with a `destructive` toast on failure — the async-save pattern
  from the BbSwitch guide, owned by context actions so no leaf ever issues
  a visit or toasts on its own.
- **Previews are peeks, not dialogs.** "See what you'll get" is the
  checklist's version of clicking a record's name: `previewStep` pushes
  onto the coopted shell stack with `replace` (previews never stack), and
  `jumpToStep` owns the way back — leaves never touch the stack grammar
  directly.
- **Dismissal is a real redirect, not a partial reload.** `router.post`
  with no `only` list lets the server's redirect land on the dashboard;
  there is no `onboarding` prop left to re-seed from after it, so the
  action doesn't await one.
- **Sizing and variants:** `md`-first throughout the bodies (28px buttons
  flush beside `compact` inputs in the invite and project rows); `sm` only
  for genuinely dense spots (inline links, the file-row remove); exactly
  one `variant="primary"` (Go to dashboard); step submits are `secondary`;
  dismissal is a ghost gated by a `destructive` `useConfirm`.

## Variations

- **Personal onboarding**: scope statuses per user instead of per
  workspace (`Inertia::render('Onboarding/Index', ['onboarding' =>
OnboardingState::for($request->user())])`) and drop the workspace-wide
  dismiss confirm copy; the page shape is unchanged.
- **Sequential (gated) steps**: lock each accordion until the previous
  step is done by rendering the body's controls `disabled` with an
  explanatory line; for hard gates with per-step validation, the
  wizard-form recipe is the full treatment.
- **Preview follows the open step**: call `previewStep(id)` from
  `openStep` so the sidebar always previews the active step; keep the
  explicit footer button for touch users.
- **All-done celebration**: when `allDone` flips, swap `ProgressHeader`'s
  copy block for a success panel with the dashboard CTA and a "book an
  onboarding call" link.
- **Lazy integration catalog**: if the integrations list grows large or
  varies per plan, share it as `Inertia::lazy()` and read it with
  `useLazyProp` instead of hardcoding the four entries in `context.ts`.

---

<!-- dist/ai/recipes/inertia/ownership-atlas.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/inertia/ownership-atlas.md -->

# Recipe: Ownership Atlas (Inertia)

A resource-ownership admin page for **Laravel + Inertia** — the "who owns
what" screen every internal console grows (Okta's people → assigned
resources, a cloud console's cost-by-owner rollup): a dense, server-paged
table of owners where **expanding a row reveals a nested `BbTable` of the
holdings that owner is responsible for, column-aligned under the parent's
own tracks**. Around that signature move sits the full standard anatomy:
breadcrumbs + page search, a holding-type filter pill, region tabs with live
counts, expand/collapse-all controls, selection with a floating bulk
**Transfer holdings** action, and an owner peek sidebar opened by row
highlight. The list is a page prop, filters mirror into the URL through
[`useQueryObject`](../../guides/inertia-helpers.md), selection and paging
come from the keyed [`useTableContext`](../../guides/inertia-helpers.md),
and the one mutation is a promise-wrapped `router.visit`. Anatomy,
components, the context shape, copy and data are identical to the Vue
recipe; only the data/URL/mutation layer changes.

Inertia-only recipe — there is no Vue or Nuxt sibling. The nested-table
mechanics here are platform-neutral, so the table markup ports directly; only
the data/URL/mutation layer is Inertia-specific.

## Prerequisites

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell`, `usePageShellContext` and `FloatingBottomPanel` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
- `<BbToast />` mounted once in the `createInertiaApp` render root — never in a page.
- From the [Inertia Helpers](../../guides/inertia-helpers.md) toolkit:
  `useTableContext`, `useQueryObject`, `useResourceContext` (plus the
  `useProp` / `useQuery` prop-and-URL helpers).
- Controller: `Inertia::render('OwnershipAtlas', ['owners' =>
OwnerPaginator::make(...), 'tabCounts' => [...], 'ownerOptions' => [...]])` —
  `owners` is a standard Laravel paginator (`PaginatedResponse<Owner>`) whose
  rows **embed their holdings** (the expand row renders instantly, no
  per-expand fetch), `tabCounts` a plain `{ all, americas, emea, apac }` map,
  and `ownerOptions` the flat `{ id, name, team }` catalog the transfer
  picker offers. All three are re-sent on the partial reloads the page
  triggers. The `kinds` filter is applied to the holdings server-side: owners
  with no matching holding drop out, and each surviving owner's
  `holdingsCount` / `monthlyTotal` are recomputed over the filtered set.
  Search matches owner name, email, team **and** holding names.
- Mutation route: `PATCH /ownership/owners/bulk/transfer` (accepts the
  select-all-across-pages payload `{ ids, all, unselected, toOwnerId }`,
  redirects back). A small JSON endpoint
  (`GET /ownership/owners/:id/peek`) backs the sidebar peek so opening it is
  not a full-page visit.

## Key ideas

- **One coopting page context.** `provideOwnershipAtlas()` joins the
  page-shell stack **and** the keyed `useTableContext('owners')` once, owns
  filters/tab/expansion, and exposes complete actions. Every leaf calls
  `useOwnershipAtlas()` and nothing else — zero prop drilling anywhere on
  the page.
- **The expand row is a real nested `BbTable` that inherits the parent's
  column tracks.** `inherit-column-widths` snaps the holdings table onto the
  owners table's grid; because the parent is `selectable`, every child
  column carries an explicit `snap` starting at `1` (`snap: 1…4`), so
  Resource sits exactly under Owner and the right-aligned $/mo columns share
  one edge. This is the recipe's signature move — the full defense is in
  "Why it is built this way" and in the
  [BbTable guide](../../BbTable.md) ("Nested tables that align with the
  parent").
- **Page-level cell-padding overrides are scoped with direct-child
  combinators.** The full-bleed treatment (`.table-flush`) pads the outer
  table's first/last cells via
  `:deep(> .bb-table__table > .bb-table__head > [role='row'] > :first-child)`
  — the table is a CSS grid of roled `div`s, not a `<table>`, so the chain
  runs through its container classes, and a bare descendant selector would
  also hit the nested table (inside `.bb-table-expand__cell`) and clobber the
  structural offset padding it computes to stay flush with the parent grid.
- **Expansion is page state, not table-internal state.** `expanded` (owner
  ids) lives in the context and binds through `v-model:expanded-items`, so
  the toolbar (expand-all/collapse-all), the bulk bar (expand selected) and
  the peek footer (expand in table) all write the same array the table
  reads.
- **Row highlight IS the peek.** A two-way computed maps
  `v-model:highlighted` onto the shell stack: clicking a row opens the owner
  peek, clicking it again (or closing the sidebar) clears the highlight —
  highlight and selection stay independent axes.
- **The table has no client-side fetch at all.** `owners` arrives as a page
  prop; `useTableContext('owners')` turns it into `items` +
  `totalItems`/`page`/`perPage` (URL-backed) + `selected`/`unselected`/`all`
  (select-all-across-pages), and `BbTable` binds directly to that handle.
  Filters mirror into the URL with `useQueryObject`; tabs are real visits
  (`href` + `server: true` with component-level `navigation`).
- **The one mutation is a promise-wrapped `router.visit`.** A tiny local
  `visit()` helper turns Inertia's callback API into a promise so
  `bulkTransfer` stays an `async function` — identical call site to the
  Vue/Nuxt versions.
- **Buttons are `md` by default**; `sm`/`xs` only in the toolbar, the table
  rows, the peek footer and the bottom bar — the dense surfaces the
  doctrine allows.

## Page anatomy

```
OwnershipAtlas/
	Index.vue          ← assembly: PageShell slots, toolbar, owners table, pagination
	context.ts         ← coopting page context (shell + useTableContext + filters + expansion + actions)
	FilterRail.vue     ← holding-type pill + clear-all
	HoldingsTable.vue  ← the nested BbTable, snapped onto the parent's tracks
	SelectionBar.vue   ← expand-selected + bulk transfer in the floating bottom panel
	OwnerPeek.vue      ← sidebar workbench for the highlighted owner
```

Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
(left nav + fat footer), [Page Shell](../../guides/page-shell.md),
[Floating Bottom Panel](../../guides/floating-bottom-panel.md).

## Action inventory

| #   | Action                      | Trigger                              | Mechanism                                                 |
| --- | --------------------------- | ------------------------------------ | --------------------------------------------------------- |
| 1   | Page search                 | topbar right                         | `filters.search` → `useQueryObject` partial visit         |
| 2   | Filter holding type         | filter rail pill                     | `BbSelectPopover` multiple over the kind catalog          |
| 3   | Clear filters               | rail (only when active), empty state | context `clearFilters()`                                  |
| 4   | Switch region tab           | server-visit tabs with counts        | `BbTabs` `href` + `server: true` visit                    |
| 5   | Expand / collapse one owner | holdings-count control, actions col  | `expandProps` toggle → `v-model:expanded-items`           |
| 6/7 | Expand ⇄ collapse all       | **one** toggle in `#topbar-actions`  | `toggleExpandAll()` — flips on `allExpandedOnPage`        |
| 8   | Peek owner                  | click anywhere on a row              | `v-model:highlighted` ↔ shell stack, JSON fetch           |
| 9   | Expand in table             | peek footer                          | adds the peeked owner to `expanded`                       |
| 10  | Select rows / select all    | table checkboxes                     | `useTableContext` selection (across pages)                |
| 11  | Expand selected             | floating bottom panel                | `expandSelected()` resolves the selection payload         |
| 12  | Bulk transfer holdings      | bottom panel one-shot popover        | `bulkTransfer(toOwnerId)` → promise-wrapped visit + toast |
| 13  | Clear selection / paginate  | bottom panel ×, `BbPagination`       | `table.resetSelection()` / `table.page` v-model           |

## One expand toggle, in the topbar

Two adjacent icon buttons ("expand all" / "collapse all") burn chrome and
duplicate one affordance: at any moment exactly one of them does something.
Ship a **single** control whose meaning follows the page —

```ts
const allExpandedOnPage = computed(
	() =>
		pageRows.value.length > 0 &&
		pageRows.value.every((row) => expanded.value.includes(row.id))
);
const toggleExpandAll = () =>
	allExpandedOnPage.value ? collapseAll() : expandAllOnPage();
```

— and render it in the shell's `#topbar-actions`, beside search and the primary
action, not in a content toolbar of its own:

```vue
<BbButton
	:aria-label="allExpandedOnPage ? 'Collapse all' : 'Expand all'"
	:icon="
		allExpandedOnPage ? 'lucide:chevrons-down-up' : 'lucide:chevrons-up-down'
	"
	size="sm"
	variant="ghost"
	@click="toggleExpandAll"
/>
```

The icon flipping is the affordance; a page-level control belongs with the
page's other commands.

## Nest indent — one knob, never per-page spacers

Once the expand toggle lives in the identity cell (see
[BbTable](../../BbTable.md) § Putting the toggle in the identity cell), the
child rows have two defensible resting places, and agents otherwise invent a
one-off pixel inset per page:

```css
.atlas-nest {
	/* Default: flush. The child's tracks already snap to the parent's, so a
	   nested row lines up with the column it belongs to — which is the whole
	   point of inherit-column-widths. */
	--table-nest-indent: 0;
}

/* Opt-in: tuck the nest under the parent's TEXT, for hierarchies whose
   children have no toggle of their own to align with. */
.atlas-nest--under-text {
	--table-nest-indent: var(--table-identity-lead);
}
```

`--table-identity-lead` is the width of the identity cell's toggle track, so
the two can never drift. Set the knob on the nest container — never pad the
child's body (`.bb-table__body`) alone, which reintroduces the edge mismatch
the snap removed.

## The code

### context.ts

```ts
// OwnershipAtlas/context.ts
import {
	computed,
	inject,
	provide,
	reactive,
	ref,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import { router } from '@inertiajs/vue3';
import type { RequestPayload } from '@inertiajs/core';
import { useToast, type BadgeVariantType } from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import {
	useTableContext,
	type TableContext,
} from '@/composables/useTableContext';
import { useQueryObject } from '@/composables/useQueryObject';
import { useProp } from '@/composables/useProp';
import { useQuery } from '@/composables/useQuery';
import type {
	HoldingKind,
	HoldingStatus,
	Owner,
	OwnerDetail,
	OwnerOption,
	OwnerRegion,
} from '@/types';

export type OwnershipTab = 'all' | OwnerRegion;

/** What the sidebar can show. Row highlight pushes one of these. */
export type PeekItem = { type: 'owner'; id: string };

export interface OwnershipFilters {
	search: string;
	kinds: HoldingKind[];
}

// Shared label/variant catalogs: defined once beside the context, imported
// by every leaf that renders a kind, status or region.
export const KIND_LABEL: Record<HoldingKind, string> = {
	workspace: 'Workspace',
	project: 'Project',
	domain: 'Domain',
	database: 'Database',
	vault: 'Vault',
	device: 'Device',
	'seat-pool': 'Seat pool',
	bucket: 'Bucket',
};

export const STATUS_LABEL: Record<HoldingStatus, string> = {
	active: 'Active',
	paused: 'Paused',
	provisioning: 'Provisioning',
	retired: 'Retired',
};

export const STATUS_VARIANT: Record<HoldingStatus, BadgeVariantType> = {
	active: 'soft-green',
	paused: 'soft-amber',
	provisioning: 'soft-blue',
	retired: 'soft-gray',
};

export const REGION_LABEL: Record<OwnerRegion, string> = {
	americas: 'Americas',
	emea: 'EMEA',
	apac: 'APAC',
};

const RELOAD_PROPS = ['owners', 'tabCounts', 'ownerOptions'] as const;

/** Comma-joined query value → typed array (or [] when absent). */
const toArray = <T = string>(value: unknown): T[] => {
	if (Array.isArray(value)) return value as T[];
	if (typeof value === 'string' && value.length) return value.split(',') as T[];
	return [];
};

export interface OwnershipAtlasContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	table: TableContext<Owner, string>;
	// -- Page-owned state ------------------------------------------------------
	filters: OwnershipFilters;
	hasActiveFilters: ComputedRef<boolean>;
	tab: Ref<OwnershipTab>;
	tabCounts: ComputedRef<Record<OwnershipTab, number>>;
	/** Transfer-target catalog — every owner, not just the current page. */
	ownerOptions: ComputedRef<OwnerOption[]>;
	/** Owner ids currently expanded — drives the nested holdings tables. */
	expanded: Ref<string[]>;
	/** Bumped after every mutation — the peek watches it to re-fetch. */
	refreshKey: Ref<number>;
	// -- Data ------------------------------------------------------------------
	fetchOwner: (id: string) => Promise<OwnerDetail>;
	// -- Actions ---------------------------------------------------------------
	clearFilters: () => void;
	expandAllOnPage: () => void;
	collapseAll: () => void;
	expandSelected: () => void;
	peekOwner: (id: string) => void;
	bulkTransfer: (toOwnerId: string) => Promise<void>;
}

const key: InjectionKey<OwnershipAtlasContext> = Symbol('ownership-atlas');

/** Inertia's callback-based visit, wrapped as a promise — so the context
 * action stays `async`, exactly like the Vue/Nuxt versions. Always a
 * partial reload of the props this page depends on. */
const visit = (
	method: 'post' | 'put' | 'patch' | 'delete',
	url: string,
	// Inertia's own payload type — strings/numbers/booleans/arrays/files.
	data: RequestPayload = {}
): Promise<void> =>
	new Promise((resolve, reject) => {
		router.visit(url, {
			method,
			data,
			only: [...RELOAD_PROPS],
			preserveScroll: true,
			preserveState: true,
			onSuccess: () => resolve(),
			onError: (errors) => reject(errors),
		});
	});

export function provideOwnershipAtlas(): OwnershipAtlasContext {
	const { toast } = useToast();

	// -- Coopt the specific contexts: once, here, for the whole page. ----------
	const shell = usePageShellContext<PeekItem>();
	// `Owner, string`: BbTable's `item-value="id"` resolves selection to owner
	// ids ('own_…'), matching the Vue/Nuxt `table.selected: string[]` shape.
	const table = useTableContext<Owner, string>('owners');

	// -- Filters: seeded from the current URL, mirrored back by useQueryObject. -
	const query = useQuery();
	const filters = reactive<OwnershipFilters>({
		search: (query.search as string) ?? '',
		kinds: toArray<HoldingKind>(query.kinds),
	});
	useQueryObject(filters, { only: [...RELOAD_PROPS] });

	const hasActiveFilters = computed(
		() => filters.search.trim().length > 0 || filters.kinds.length > 0
	);
	const clearFilters = () => {
		filters.search = '';
		filters.kinds = [];
	};

	// Tab: seeded from the URL; BbTabs' own `href` + `server` visit updates
	// the URL, and its `v-model` write keeps this ref in sync with the click.
	const tab = ref<OwnershipTab>((query.tab as OwnershipTab) ?? 'all');
	const tabCounts = useProp<Record<OwnershipTab, number>>('tabCounts');
	const ownerOptions = useProp<OwnerOption[]>('ownerOptions');

	// -- Expansion: page state, one array, many writers. -----------------------
	// The toolbar, the bulk bar and the peek all mutate this; the table binds
	// it via `v-model:expanded-items`. Deliberately NOT in the URL: which rows
	// are unfolded is working posture, not a shareable view.
	const expanded = ref<string[]>([]);

	const expandAllOnPage = () => {
		expanded.value = table.items.value.map((owner) => owner.id);
	};

	const collapseAll = () => {
		expanded.value = [];
	};

	// Bulk expand honors select-all-across-pages semantics, but can only unfold
	// rows that are actually rendered — so it resolves against the current page.
	const expandSelected = () => {
		const ids = table.all.value
			? table.items.value
					.map((owner) => owner.id)
					.filter((id) => !table.unselected.value.includes(id))
			: [...table.selected.value];
		expanded.value = [...new Set([...expanded.value, ...ids])];
	};

	const peekOwner = (id: string) => shell.push({ type: 'owner', id }, true);

	const refreshKey = ref(0);

	// Bulk payload carries the full select-all-across-pages triple — the
	// server combines `all` + `unselected` the same way BbTable does.
	const bulkPayload = () => ({
		ids: table.selected.value,
		all: table.all.value,
		unselected: table.unselected.value,
	});

	const bulkTransfer = async (toOwnerId: string) => {
		const target = ownerOptions.value.find((owner) => owner.id === toOwnerId);
		await visit('patch', '/ownership/owners/bulk/transfer', {
			...bulkPayload(),
			toOwnerId,
		});
		refreshKey.value++;
		table.resetSelection();
		toast({
			title: `Holdings transferred to ${target?.name ?? 'the selected owner'}.`,
			variant: 'success',
		});
	};

	// A small JSON endpoint, not a page visit — opening the peek never
	// re-renders the list underneath it.
	const fetchOwner = (id: string): Promise<OwnerDetail> =>
		fetch(`/ownership/owners/${id}/peek`).then((res) => res.json());

	const ctx: OwnershipAtlasContext = {
		shell,
		table,
		filters,
		hasActiveFilters,
		tab,
		tabCounts,
		ownerOptions,
		expanded,
		refreshKey,
		fetchOwner,
		clearFilters,
		expandAllOnPage,
		collapseAll,
		expandSelected,
		peekOwner,
		bulkTransfer,
	};
	provide(key, ctx);
	return ctx;
}

export function useOwnershipAtlas(): OwnershipAtlasContext {
	const ctx = inject(key);
	if (!ctx)
		throw new Error('useOwnershipAtlas() called outside OwnershipAtlas');
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- OwnershipAtlas/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left, page search right. No creation action on
		     this page, so no primary button anywhere. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs
					class="min-w-0 flex-auto"
					:items="[
						{ key: 'admin', text: 'Admin', href: '/admin' },
						{ key: 'access', text: 'Access', href: '/access' },
						{ key: 'ownership', text: 'Ownership' },
					]"
				/>
				<BbTextInput
					v-model="ctx.filters.search"
					autocomplete="off"
					class="shrink-0"
					clearable
					compact
					hide-label
					label="Search owners or holdings"
					placeholder="Search owner, team, or resource…"
					prepend:icon="lucide:search"
				/>
			</div>
		</template>

		<div class="flex flex-col gap-3 p-4">
			<FilterRail />

			<!-- Toolbar row: region tabs share the line with the expansion
			     controls — expansion is page furniture, not a row concern. -->
			<div class="flex items-center gap-2">
				<div class="min-w-0 flex-1 overflow-clip">
					<!-- Tabs are real visits: href + server (component-level
					     `navigation` is required alongside per-item `server`). The
					     transfer catalog can't change with the tab, so `ownerOptions`
					     stays out of the tab reload list. Each href is built from
					     `tabHref()`, NOT a bare `?tab=` literal: `preserve-state`
					     keeps `ctx.filters` alive across the visit, so if the href
					     dropped the filter query keys the server would render an
					     unfiltered page while the (unchanged) filter chips kept
					     claiming the old filters still applied. -->
					<BbTabs
						v-model="ctx.tab.value"
						compact
						:items="[
							{
								key: 'all',
								label: `All · ${ctx.tabCounts.value.all}`,
								href: tabHref('all'),
								server: true,
								only: ['owners', 'tabCounts'],
							},
							{
								key: 'americas',
								label: `Americas · ${ctx.tabCounts.value.americas}`,
								href: tabHref('americas'),
								server: true,
								only: ['owners', 'tabCounts'],
							},
							{
								key: 'emea',
								label: `EMEA · ${ctx.tabCounts.value.emea}`,
								href: tabHref('emea'),
								server: true,
								only: ['owners', 'tabCounts'],
							},
							{
								key: 'apac',
								label: `APAC · ${ctx.tabCounts.value.apac}`,
								href: tabHref('apac'),
								server: true,
								only: ['owners', 'tabCounts'],
							},
						]"
						navigation
						preserve-scroll
						preserve-state
						replace
					/>
				</div>
				<div class="flex shrink-0 items-center gap-0.5">
					<BbButton
						v-bb-tooltip="{ text: 'Expand all on this page', delay: 400 }"
						aria-label="Expand all on this page"
						icon="lucide:chevrons-down"
						size="sm"
						variant="ghost"
						@click="ctx.expandAllOnPage"
					/>
					<BbButton
						v-bb-tooltip="{ text: 'Collapse all', delay: 400 }"
						aria-label="Collapse all"
						icon="lucide:chevrons-up"
						size="sm"
						variant="ghost"
						@click="ctx.collapseAll"
					/>
				</div>
			</div>

			<!-- No dependencies/items-fn: `owners` is a page prop, and selection
			     (across pages) binds straight onto the keyed table context.
			     `fixed` gives the parent equal-width tracks — a predictable grid
			     for the nested table to snap onto. -->
			<BbTable
				v-model="ctx.table.selected.value"
				v-model:expanded-items="ctx.expanded.value"
				v-model:highlighted="highlightedOwner"
				v-model:select-all="ctx.table.all.value"
				v-model:unselected-items="ctx.table.unselected.value"
				actions
				actions-text="Holdings"
				caption="Resource owners"
				class="table-flush"
				:columns="columns"
				compact
				fixed
				item-value="id"
				:items="ctx.table.items.value"
				legend="Select owners"
				loading-text="Loading owners…"
				:row-class="rowClass"
				selectable
			>
				<template #name="{ item, content }">
					<div class="flex min-w-0 flex-col leading-tight">
						<span class="font-semibold">{{ content }}</span>
						<span class="truncate text-xs text-[color:var(--bb-text-muted)]">{{
							item.email
						}}</span>
					</div>
				</template>

				<template #team="{ item, content }">
					<div class="flex min-w-0 flex-col leading-tight">
						<span>{{ content }}</span>
						<span class="truncate text-xs text-[color:var(--bb-text-muted)]">{{
							item.title
						}}</span>
					</div>
				</template>

				<template #region="{ item }">
					<span class="text-xs text-[color:var(--bb-text-muted)]">{{
						REGION_LABEL[item.region]
					}}</span>
				</template>

				<template #monthlytotal="{ content }">
					<span class="tabular-nums">{{ money(content) }}</span>
				</template>

				<!-- The actions column IS the expand control: the holdings count
				     doubles as the toggle, `expandProps` wires aria + keyboard. -->
				<template #actions="{ item, expanded: isOpen, expandProps }">
					<BbButton
						v-bind="expandProps"
						:append:icon="isOpen ? 'lucide:chevron-up' : 'lucide:chevron-down'"
						:aria-label="
							isOpen
								? `Collapse ${item.holdingsCount} holdings`
								: `Expand ${item.holdingsCount} holdings`
						"
						size="xs"
						variant="ghost"
					>
						<span class="tabular-nums">{{ item.holdingsCount }}</span>
					</BbButton>
				</template>

				<!-- The signature move: a nested BbTable that inherits this
				     table's column tracks. -->
				<template #expand="{ item }">
					<HoldingsTable :owner="item" />
				</template>

				<template #no-data>
					<div
						class="mx-auto flex max-w-sm flex-col items-center gap-3 px-6 py-12 text-center"
					>
						<BbIcon
							class="text-[color:var(--bb-text-muted)]"
							:icon="
								ctx.hasActiveFilters.value ? 'lucide:search-x' : 'lucide:layers'
							"
							size="2xl"
						/>
						<p class="text-sm font-semibold">
							{{
								ctx.hasActiveFilters.value
									? 'No matching owners'
									: 'No owners in this region'
							}}
						</p>
						<p class="text-xs text-[color:var(--bb-text-muted)]">
							{{
								ctx.hasActiveFilters.value
									? 'Clear the holding-type filter, or widen search.'
									: 'Switch tabs to another region.'
							}}
						</p>
						<BbButton
							v-if="ctx.hasActiveFilters.value"
							prepend:icon="lucide:x"
							size="sm"
							variant="outline"
							@click="ctx.clearFilters"
						>
							Clear filters
						</BbButton>
					</div>
				</template>
			</BbTable>

			<!-- No table-id: the keyed table context is the page count here. -->
			<BbPagination
				v-model="ctx.table.page.value"
				label="Owners pagination"
				:total-pages="ctx.table.totalPages.value"
			/>
		</div>

		<SelectionBar />

		<!-- The peek: rendered by type; row highlight drives the stack. -->
		<template #sidebar>
			<OwnerPeek
				v-if="ctx.shell.current.value?.type === 'owner'"
				:owner-id="ctx.shell.current.value.id"
			/>
		</template>
	</PageShell>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import {
	BbBreadcrumbs,
	BbButton,
	BbIcon,
	BbPagination,
	BbTable,
	BbTabs,
	BbTextInput,
	vBbTooltip,
	type BbTableColumn,
} from 'bitboss-ui';
import qs from 'query-string';
import PageShell from '@/components/layout/PageShell.vue';
import { useQuery } from '@/composables/useQuery';
import {
	provideOwnershipAtlas,
	REGION_LABEL,
	type OwnershipTab,
} from './context';
import FilterRail from './FilterRail.vue';
import HoldingsTable from './HoldingsTable.vue';
import OwnerPeek from './OwnerPeek.vue';
import SelectionBar from './SelectionBar.vue';
import type { Owner } from '@/types';

const ctx = provideOwnershipAtlas();

// Merge `tab` into the *current* query instead of replacing it: `useQuery()`
// reads the live URL, which already carries every filter `useQueryObject`
// mirrored there, so switching tabs keeps `search`/`kinds` intact instead of
// silently resetting the results to unfiltered.
const tabHref = (tab: OwnershipTab): string =>
	`/ownership?${qs.stringify({ ...useQuery(), tab }, { arrayFormat: 'comma' })}`;

/** Row highlight IS the peek: clicking a row opens owner detail in the
 * sidebar; clicking it again (BbTable clears the highlight) closes it. */
const highlightedOwner = computed<string | null>({
	get: () =>
		ctx.shell.current.value?.type === 'owner'
			? ctx.shell.current.value.id
			: null,
	set: (id) => {
		if (id == null) ctx.shell.close();
		else ctx.peekOwner(id);
	},
});

/** Four data columns — the nested holdings table snaps onto them 1:1. The
 * owner's title rides under Team; the holdings count lives on the expand
 * control in the actions column. */
const columns: Array<BbTableColumn<Owner>> = [
	{ key: 'name', label: 'Owner' },
	{ key: 'team', label: 'Team' },
	{ key: 'region', label: 'Region' },
	{ key: 'monthlyTotal', label: '$ / mo', align: 'right' },
];

const money = (value: number) =>
	new Intl.NumberFormat('en-US', {
		style: 'currency',
		currency: 'USD',
		maximumFractionDigits: 0,
	}).format(value);

// Public row-class API paints every row state: the base class carries the
// pointer cursor (rows are click targets — highlight opens the peek), the
// conditional classes carry the expanded / peek-open washes.
const rowClass = (item: Owner) => {
	const classes = ['owner-row'];
	if (ctx.expanded.value.includes(item.id)) classes.push('row-expanded');
	if (highlightedOwner.value === item.id) classes.push('row-peeked');
	return classes.join(' ');
};
</script>

<style scoped>
/* Full-bleed table: mirror the content wrapper's `p-4` so row washes and the
   nested table run edge to edge, while the outermost cells keep the optical
   margin — content stays lined up with the filter rail and tabs above. */
.table-flush {
	--page-inset: 1rem;
	margin-inline: calc(var(--page-inset) * -1);
	width: calc(100% + var(--page-inset) * 2);
}

/* Direct-child combinators keep these overrides on the OWNER table's own
   cells. The table is a CSS grid of roled divs (no <table>/<tr>/<td>), so the
   chain runs through its container classes. A bare
   `:deep([role='cell']:first-child)` would also match the nested holdings
   table and clobber the structural offset padding it computes to stay flush
   with the parent grid — the one selector mistake that silently breaks
   nested-table alignment. */
.table-flush
	:deep(> .bb-table__table > .bb-table__head > [role='row'] > :first-child),
.table-flush
	:deep(
		> .bb-table__table
			> .bb-table__body
			> [role='row']
			> :first-child:not(.bb-table-expand__cell)
	) {
	padding-inline-start: var(--page-inset);
}

.table-flush
	:deep(> .bb-table__table > .bb-table__head > [role='row'] > :last-child),
.table-flush
	:deep(
		> .bb-table__table
			> .bb-table__body
			> [role='row']
			> :last-child:not(.bb-table-expand__cell)
	) {
	padding-inline-end: var(--page-inset);
}

/* Expand rows stay edge-to-edge so the nested table can inherit the parent
   tracks without an extra inset shifting everything sideways. */
.table-flush
	:deep(
		> .bb-table__table > .bb-table__body > [role='row'] > .bb-table-expand__cell
	) {
	padding-inline: 0;
}

/* Row states, painted through the public row-class API. */
:deep(.owner-row) {
	cursor: pointer;
}

/* Expanded = hierarchy only: a quiet ink wash, no accent. */
:deep(.row-expanded) {
	background-color: color-mix(in oklab, var(--bb-text) 2.5%, transparent);
}

/* Peek-open = accent wash + a 1px lead pin on the row's start edge. */
:deep(.row-peeked) {
	background-color: color-mix(in oklab, var(--bb-primary) 6%, transparent);
	box-shadow: inset 1px 0 0 0 var(--bb-primary);
}
</style>
```

### HoldingsTable.vue — the nested table

```vue
<!-- OwnershipAtlas/HoldingsTable.vue — nested BbTable snapped under the owner. -->
<template>
	<div class="holdings-nest">
		<BbTable
			:caption="`Holdings owned by ${owner.name}`"
			class="w-full"
			:columns="columns"
			compact
			inherit-column-widths
			item-value="id"
			:items="owner.holdings"
		>
			<template #name="{ item, content }">
				<div class="flex min-w-0 flex-col leading-tight">
					<span class="font-semibold">{{ content }}</span>
					<span class="text-xs text-[color:var(--bb-text-muted)]">
						Since {{ monthLabel(item.since) }} · {{ item.region }}
					</span>
				</div>
			</template>

			<template #kind="{ item }">
				<span class="text-xs text-[color:var(--bb-text-muted)]">{{
					KIND_LABEL[item.kind]
				}}</span>
			</template>

			<template #status="{ item }">
				<BbBadge size="sm" :variant="STATUS_VARIANT[item.status]">
					{{ STATUS_LABEL[item.status] }}
				</BbBadge>
			</template>

			<template #monthlycost="{ content }">
				<span class="tabular-nums">{{ money(content) }}</span>
			</template>
		</BbTable>
	</div>
</template>

<script setup lang="ts">
import { BbBadge, BbTable, type BbTableColumn } from 'bitboss-ui';
import { KIND_LABEL, STATUS_LABEL, STATUS_VARIANT } from './context';
import type { Holding, Owner } from '@/types';

defineProps<{ owner: Owner }>();

/**
 * Explicit snaps onto the parent grid. The parent is `selectable`, so its
 * select column occupies tracks [0, 1] and the data columns sit at 1…4 —
 * `snap` base is 1 (it would be 0 under a non-selectable parent). Every
 * column defines a snap so none becomes the auto fill track: a width-free
 * last column would absorb the parent's actions region, and right-aligned
 * $/mo would land under the expand control instead of under the parent's
 * $/mo. With all four snapped, the parent's select and actions tracks fold
 * into the child's first/last cells as padding — the child starts flush with
 * the parent's first data column, and that inset is what reads as hierarchy.
 */
const columns: Array<BbTableColumn<Holding>> = [
	{ key: 'name', label: 'Resource', snap: 1 },
	{ key: 'kind', label: 'Type', snap: 2 },
	{ key: 'status', label: 'Status', snap: 3 },
	{ key: 'monthlyCost', label: '$ / mo', align: 'right', snap: 4 },
];

const money = (value: number) =>
	value === 0
		? '—'
		: new Intl.NumberFormat('en-US', {
				style: 'currency',
				currency: 'USD',
				maximumFractionDigits: 0,
			}).format(value);

const monthLabel = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		year: 'numeric',
	});
</script>

<style scoped>
/* Full-bleed inside the expand cell — the inherited snaps keep Resource
   under Owner. Hierarchy is the hairline + faint wash, NOT a padding inset:
   an inset would shift the child's cells off the parent's tracks and make
   the alignment lie. */
.holdings-nest {
	background: color-mix(in oklab, var(--bb-text) 1.5%, transparent);
	border-block-start: 1px solid var(--bb-border);
	width: 100%;
}
</style>
```

### FilterRail.vue

```vue
<!-- OwnershipAtlas/FilterRail.vue -->
<template>
	<div class="flex flex-wrap items-center gap-2">
		<!-- Holding type: multi-select pill over the kind catalog. Filtering by
		     kind reshapes the owners themselves (server-side): owners with no
		     matching holding drop out, counts and totals recompute. -->
		<BbSelectPopover
			v-model="ctx.filters.kinds"
			clearable
			item-text="label"
			item-value="value"
			:items="kindOptions"
			multiple
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filter by holding type"
					append:icon="lucide:chevron-down"
					prepend:icon="lucide:layers"
					size="sm"
					variant="outline"
				>
					Holding type{{
						ctx.filters.kinds.length ? ` · ${ctx.filters.kinds.length}` : ''
					}}
				</BbButton>
			</template>
		</BbSelectPopover>

		<!-- Clear-all renders only while something is active. -->
		<BbButton
			v-if="ctx.hasActiveFilters.value"
			prepend:icon="lucide:x"
			size="sm"
			variant="ghost"
			@click="ctx.clearFilters"
		>
			Clear
		</BbButton>
	</div>
</template>

<script setup lang="ts">
import { BbButton, BbSelectPopover } from 'bitboss-ui';
import { KIND_LABEL, useOwnershipAtlas } from './context';
import type { HoldingKind } from '@/types';

const ctx = useOwnershipAtlas();

// The pill's options come straight from the shared label catalog.
const kindOptions = (
	Object.entries(KIND_LABEL) as Array<[HoldingKind, string]>
).map(([value, label]) => ({ value, label }));
</script>
```

### SelectionBar.vue

```vue
<!-- OwnershipAtlas/SelectionBar.vue -->
<template>
	<FloatingBottomPanel :open="selectedCount > 0">
		<span class="px-2 text-sm text-[color:var(--bb-text-muted)]">
			<span class="font-semibold tabular-nums">{{ selectedCount }}</span>
			selected
		</span>

		<BbButton
			prepend:icon="lucide:chevrons-down"
			size="sm"
			variant="ghost"
			@click="ctx.expandSelected"
		>
			Expand
		</BbButton>

		<!-- Bulk transfer: a one-shot popover (model stays null) whose pick IS
		     the action. Targets exclude every selected owner — you cannot
		     transfer holdings onto an owner you are emptying. -->
		<BbSelectPopover
			item-text="name"
			item-value="id"
			:items="transferTargets"
			:model-value="null"
			:offset="10"
			placement="top"
			width="240px"
			@update:model-value="onTransfer"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Transfer holdings for selected owners"
					append:icon="lucide:chevron-up"
					prepend:icon="lucide:arrow-right-left"
					size="sm"
					variant="ghost"
				>
					Transfer holdings
				</BbButton>
			</template>
		</BbSelectPopover>

		<div class="floating-bottom-panel__right flex items-center gap-1">
			<BbButton
				aria-label="Clear selection"
				icon="lucide:x"
				size="sm"
				variant="ghost"
				@click="ctx.table.resetSelection"
			/>
		</div>
	</FloatingBottomPanel>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbSelectPopover } from 'bitboss-ui';
import FloatingBottomPanel from '@/components/layout/FloatingBottomPanel.vue';
import { useOwnershipAtlas } from './context';

const ctx = useOwnershipAtlas();

// `all` (select-all-across-pages) does not enumerate rows, so the visible
// count is the total minus whatever the user manually deselected.
const selectedCount = computed(() =>
	ctx.table.all.value
		? ctx.table.totalItems.value - ctx.table.unselected.value.length
		: ctx.table.selected.value.length
);

/** Don't offer transferring onto an owner who is already in the selection. */
const transferTargets = computed(() => {
	const selected = new Set(
		ctx.table.all.value
			? ctx.ownerOptions.value
					.map((owner) => owner.id)
					.filter((id) => !ctx.table.unselected.value.includes(id))
			: ctx.table.selected.value
	);
	return ctx.ownerOptions.value.filter((owner) => !selected.has(owner.id));
});

const onTransfer = (value: unknown) => {
	if (typeof value !== 'string' || !value) return;
	void ctx.bulkTransfer(value);
};
</script>
```

### OwnerPeek.vue

```vue
<!-- OwnershipAtlas/OwnerPeek.vue — sidebar workbench for the highlighted owner. -->
<template>
	<div v-if="owner" class="flex flex-col gap-4 text-sm">
		<!-- Identity header. -->
		<header class="flex flex-col gap-1">
			<h2 class="text-base font-semibold tracking-tight">{{ owner.name }}</h2>
			<p class="text-xs text-[color:var(--bb-text-muted)]">{{ owner.email }}</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				{{ owner.title }} · {{ owner.team }} ·
				{{ REGION_LABEL[owner.region] }}
			</p>
		</header>

		<!-- Properties. -->
		<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
			<dt class="text-[color:var(--bb-text-muted)]">Holdings</dt>
			<dd class="text-right tabular-nums">{{ owner.holdingsCount }}</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Monthly</dt>
			<dd class="text-right font-medium tabular-nums">
				{{ money(owner.monthlyTotal) }}
			</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Joined</dt>
			<dd class="text-right">{{ longDate(owner.joinedAt) }}</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Manager</dt>
			<dd class="text-right">{{ owner.manager ?? '—' }}</dd>
		</dl>

		<section v-if="owner.notes" class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Notes
			</h3>
			<p>{{ owner.notes }}</p>
		</section>

		<!-- Rollup by holding type. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				By type
			</h3>
			<ul class="flex flex-col gap-1.5">
				<li
					v-for="row in owner.kindBreakdown"
					:key="row.kind"
					class="grid grid-cols-[1fr_auto_auto] items-baseline gap-3"
				>
					<span class="min-w-0">{{ KIND_LABEL[row.kind] }}</span>
					<span
						class="text-xs tabular-nums text-[color:var(--bb-text-muted)]"
						>{{ row.count }}</span
					>
					<span
						class="text-xs tabular-nums text-[color:var(--bb-text-muted)]"
						>{{ money(row.monthlyCost) }}</span
					>
				</li>
			</ul>
		</section>

		<!-- The holdings themselves — a real list, not a summary sentence. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Holdings
			</h3>
			<ul class="flex flex-col gap-2">
				<li
					v-for="holding in owner.holdings"
					:key="holding.id"
					class="flex items-start justify-between gap-3"
				>
					<div class="flex min-w-0 flex-1 flex-col gap-0.5">
						<span class="font-medium">{{ holding.name }}</span>
						<span class="text-xs text-[color:var(--bb-text-muted)]"
							>{{ KIND_LABEL[holding.kind] }} · {{ holding.region }}</span
						>
					</div>
					<div class="flex flex-col items-end gap-1">
						<BbBadge size="sm" :variant="STATUS_VARIANT[holding.status]">
							{{ STATUS_LABEL[holding.status] }}
						</BbBadge>
						<span
							class="text-xs tabular-nums text-[color:var(--bb-text-muted)]"
							>{{ money(holding.monthlyCost) }}</span
						>
					</div>
				</li>
			</ul>
		</section>

		<!-- Workbench footer: act from the peek back into the table. -->
		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				prepend:icon="lucide:chevrons-down"
				size="sm"
				variant="secondary"
				@click="onExpandInTable"
			>
				Expand in table
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { watch } from 'vue';
import { BbBadge, BbButton, BbSpinner } from 'bitboss-ui';
import { useResourceContext } from '@/composables/useResourceContext';
import {
	KIND_LABEL,
	REGION_LABEL,
	STATUS_LABEL,
	STATUS_VARIANT,
	useOwnershipAtlas,
} from './context';
import type { OwnerDetail } from '@/types';

const props = defineProps<{ ownerId: string }>();

const ctx = useOwnershipAtlas();

// A small JSON endpoint, not a page visit — opening the peek never
// re-renders the list underneath it. Re-fetches whenever the highlight moves
// to a different owner; `refreshKey` makes bulk transfers reflect here
// immediately.
const { data: owner, refresh } = useResourceContext<OwnerDetail, string>(
	() => props.ownerId,
	ctx.fetchOwner
);
watch(() => ctx.refreshKey.value, refresh);

const money = (value: number) =>
	value === 0
		? '—'
		: new Intl.NumberFormat('en-US', {
				style: 'currency',
				currency: 'USD',
				maximumFractionDigits: 0,
			}).format(value);

const longDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
		year: 'numeric',
	});

// The peek writes the same expansion array the table reads — one rung-3
// state, three writers (toolbar, bulk bar, peek).
const onExpandInTable = () => {
	if (!owner.value) return;
	if (!ctx.expanded.value.includes(owner.value.id)) {
		ctx.expanded.value = [...ctx.expanded.value, owner.value.id];
	}
};
</script>
```

### The domain types (`@/types`)

```ts
export type HoldingKind =
	| 'workspace'
	| 'project'
	| 'domain'
	| 'database'
	| 'vault'
	| 'device'
	| 'seat-pool'
	| 'bucket';

export type HoldingStatus = 'active' | 'paused' | 'provisioning' | 'retired';

export type OwnerRegion = 'americas' | 'emea' | 'apac';

/** A resource an owner is responsible for — one nested-table row. */
export interface Holding {
	id: string;
	name: string;
	kind: HoldingKind;
	status: HoldingStatus;
	/** `YYYY-MM-DD` — when ownership began. */
	since: string;
	monthlyCost: number;
	region: string;
}

/** Parent row: a person with the holdings they own embedded. */
export interface Owner {
	id: string;
	name: string;
	email: string;
	team: string;
	title: string;
	region: OwnerRegion;
	holdingsCount: number;
	monthlyTotal: number;
	holdings: Holding[];
}

/** Transfer-picker option. */
export type OwnerOption = { id: string; name: string; team: string };

/** Rich owner detail for the sidebar peek. */
export interface OwnerDetail extends Owner {
	joinedAt: string;
	manager: string | null;
	notes: string;
	kindBreakdown: Array<{
		kind: HoldingKind;
		count: number;
		monthlyCost: number;
	}>;
}
```

## Why it is built this way

- **The nested table inherits the parent's tracks — never eyeballed
  widths.** `inherit-column-widths` is the whole alignment mechanism: the
  holdings table reads the owners table's measured tracks, so Resource sits
  under Owner and both $/mo columns share one right edge at every viewport
  width. Two hand-maintained width lists (or two tables that merely look
  similar) drift apart the first time a label changes; the inheritance
  cannot.
- **Every child column snaps, and the base is 1.** The parent is
  `selectable`, so its select column occupies the region before the first
  data track — child snaps start at `1` (`0` would put Resource under the
  checkboxes). And no child column may be left width-free: the width-free
  column becomes the fill track and absorbs the parent's **actions** region,
  which visually parks right-aligned $/mo under the expand control. With
  all four columns snapped, the select and actions tracks fold into the
  child's first/last cells as padding, and the child starts flush with the
  parent's first data column — that structural inset, plus a hairline and a
  faint wash, is the entire hierarchy treatment. No extra padding inset:
  an inset would make the alignment lie.
- **Cell-padding overrides use direct-child combinators.** `.table-flush`
  bleeds the owner table past the page padding and re-adds the inset on the
  outermost cells — but only via
  `:deep(> .bb-table__table > .bb-table__body > [role='row'] > :first-child)`
  (the table is a CSS grid of roled `div`s; `table`/`tbody`/`tr`/`td`
  selectors match nothing). A bare descendant selector would also hit the
  nested table's cells and clobber the offset padding it computes to stay on
  the parent grid. The expand cell itself is excluded from the inset and
  zero-padded, so the nested table gets the full row width to snap within.
- **Expansion is rung-3 page state.** `expanded` lives in the context
  because four surfaces touch it: the per-row control, the toolbar's
  expand-all/collapse-all, the bulk bar's Expand, and the peek's "Expand in
  table". Binding it through `v-model:expanded-items` (tracked by
  `item-value`) means expansion survives the partial reloads that replace
  the row objects. It stays out of the URL deliberately — unfolded rows are
  working posture, not a shareable view.
- **The actions column is the expand control.** This page's per-row action
  _is_ "show me the holdings", so the holdings count doubles as the toggle
  (`expandProps` wires `aria-expanded` and keyboard handling onto a real
  button). No `…` dropdown padding out the inventory.
- **Row highlight is the peek, via one two-way computed.** `get` derives the
  highlighted id from the shell stack; `set` pushes or closes. Highlight and
  selection remain independent axes — you can peek one owner while twelve
  are selected for transfer.
- **The context coopts, leaves consume.** `shell` and the keyed
  `useTableContext('owners')` are joined once in `provideOwnershipAtlas()`;
  five components share filters, selection, expansion, the peek and the
  transfer action through one `useOwnershipAtlas()` call. Leaves receive
  only the data they render (`owner`, `owner-id`).
- **`owners` is a page prop, not a client fetch.** The server owns
  filtering, search, tab scoping and pagination; `useQueryObject` (filters)
  and `href` + `server: true` tabs are two doors into the same partial
  reload. The `kinds` filter reshapes the owners themselves server-side —
  the client never re-derives counts or totals. Each tab `href` is built by
  `tabHref()`, which merges `tab` into the current query rather than
  replacing it — `href: '/ownership?tab=all'` alone would drop the `search`
  and `kinds` filters, and because `preserve-state` keeps this page instance
  (and `ctx.filters`) alive across the visit, the chips would keep showing
  the old filters as active over an unfiltered result set.
- **Bulk transfer carries the full select-all-across-pages payload**
  (`ids`/`all`/`unselected` + `toOwnerId`), and the target list excludes the
  current selection — the UI cannot express "transfer onto an owner being
  emptied". The action is complete: visit, refresh bump, selection reset,
  toast naming the target.
- **Sizing:** the topbar search is `compact` (28px) per `md`-first; `sm`
  appears only in the toolbar, rail pills, peek footer and bottom bar, and
  the in-row expand control is `xs` — the densest surface on the page. This
  page creates nothing, so no `variant="primary"` appears anywhere, and its
  one mutation is not destructive, so there is no `useConfirm` — holdings
  move, they are not lost.

## Variations

- **Per-holding actions**: give the nested table its own `actions` column
  (a `…` dropdown with "Transfer this holding") calling the same context
  action with a single id. Snap indices are unaffected — structural columns
  are accounted for automatically.
- **Divergent child columns**: if the holdings table needs columns that
  should _not_ align (say, an audit-log expansion), drop
  `inherit-column-widths` and let it lay out independently — inheritance is
  for continuation, not for every nested table.
- **Confirmed transfers**: if a transfer is heavyweight in your domain
  (billing moves with it), wrap `bulkTransfer` in `useConfirm` with the
  count and target in the message.
- **Deep-linkable expansion**: mirror `expanded` into the URL alongside the
  filters if support wants to share "look at this owner's holdings" links.
- **Keyboard triage**: add `keyboard-navigation` to the owners table —
  highlight already opens the peek, so arrows + Enter make the page
  reviewable hands-on-keyboard; the approvals-inbox recipe is the full
  treatment.

---

<!-- dist/ai/recipes/inertia/record-form.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/inertia/record-form.md -->

# Recipe: Record Form (Inertia)

The form archetype at full standard anatomy adapted for **Laravel +
Inertia**: the same Stripe-grade invoice create/edit page — sectioned
fields with tied selects, an inline-editing line-items table, a
dirty-guarded sticky action row, and a customer peek workbench — but the
draft **is** [`usePromiseForm`](../../guides/inertia-helpers.md) state, so
422 mapping is free on `form.errors`, dirty tracking is native
`form.isDirty`, saves are promise-wrapped `form.post`/`form.put` visits, and
the leave guard is the toolkit's
[`useConfirmOnRouteLeave`](../../guides/inertia-helpers.md). Anatomy,
components, the context shape, copy and data are identical to the Vue
recipe; only the data/URL/mutation layer changes.

Sibling recipes: [Vue](../vue/record-form.md) ·
[Nuxt](../nuxt/record-form.md). The listing this page belongs with is
[Records Workspace (Inertia)](./records-workspace.md).

## Prerequisites

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell` and `usePageShellContext` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
- `<BbConfirm />` and `<BbToast />` mounted once in the `createInertiaApp` render root — never in a page.
- From the [Inertia Helpers](../../guides/inertia-helpers.md) toolkit:
  `usePromiseForm`, `useConfirmOnRouteLeave`, `useProp`.
- Controller: `Inertia::render('Invoices/Edit', ['invoice' => $invoice])`
  — `invoice` is `null` on the create route and the full record (including
  `lineItems`) on the edit route. Standard Laravel validation; on failure
  Inertia puts messages on `form.errors`. Mutation routes are plain Laravel
  routes (`POST /invoices`, `PUT /invoices/:id`, `DELETE /invoices/:id`)
  that redirect back; small JSON GET endpoints (`GET /customers/search`,
  `GET /customers/:id/projects`, `GET /customers/:id/peek`) back the
  customer/project selects and the sidebar peek.

## Key ideas

- **One coopting page context.** `provideInvoiceForm()` joins the
  page-shell stack once, owns the draft, the server errors, the dirty
  state and every action (including the route-leave guard). Every leaf
  calls `useInvoiceForm()` and nothing else — cells, sections, the sticky
  bar and the peek share state with zero prop drilling.
- **The draft _is_ the Inertia form.** `ctx.draft` is `usePromiseForm`'s own
  reactive fields, so inline cell edits, the peek's "apply billing
  defaults", and add/duplicate/remove line all mutate `ctx.draft` exactly
  like the Vue/Nuxt recipes — but there is no separate submission payload
  to assemble by hand: `form.transform()` shapes the request just before
  `post`/`put`.
- **422 errors reach every input — including table rows — through
  Inertia's own `form.errors`.** Laravel-style keys (`customerId`,
  `lineItems.2.unitPrice`) arrive pre-mapped; scalar fields bind
  `ctx.errors.value.<key>` and the editable cells resolve their row key
  through `ctx.lineItemError(line, field)`, unchanged from the other
  platforms.
- **Tied selects are declarative.** Project depends on customer via
  `dependencies` + `enforce-coherence`; switching customers refetches the
  projects and clears a now-invalid pick automatically. No watchers.
- **Line items are an inline-editing table (§6.3).** One leaf per cell
  type — description, quantity, unit price — each swapping to an input on
  click, committing on blur/Enter and reverting on Esc. The amount column
  is virtual, computed from the row.
- **Dirty state is native.** `form.isDirty` compares the live draft
  against the baseline `form.defaults()` set on load and re-taken after
  every successful save — no JSON snapshot to maintain. The route-leave
  guard is the toolkit's `useConfirmOnRouteLeave({ disabled: () =>
!form.isDirty, whitelist: [submitUrl] })`, whitelisting the form's own
  submit URL so a save can't confirm-block itself.
- **Clicking the customer's name peeks the customer** — a workbench, not a
  preview: billing profile, stats, recent invoices, and an action that
  writes the customer's defaults back into the draft.
- **Buttons are `md` by default;** `sm` only in the line-items table and
  the peek. One `variant="primary"`: the save. No filter rail, no tabs, no
  bulk bar — the form archetype has no list to filter and no selection.

## Page anatomy

```
InvoiceForm/
	Index.vue                   ← assembly: PageShell slots, header, <form>, sections
	context.ts                  ← coopting page context (shell + usePromiseForm draft + actions + leave guard)
	DetailsSection.vue          ← tied selects, dates, terms, PO, tax rate
	LineItemsSection.vue        ← editable BbTable + add line + live totals
	EditableDescriptionCell.vue ← inline text edit (commit on blur/Enter, Esc reverts)
	EditableQuantityCell.vue    ← inline quantity edit, same grammar
	EditableRateCell.vue        ← inline unit-price edit, currency-formatted display
	NotesSection.vue            ← BbCollapsible disclosure over notes + terms
	FormActions.vue             ← sticky action row: delete / cancel / save draft / save
	CustomerPeek.vue            ← sidebar workbench for the picked customer
```

Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
(left nav + fat footer) and [Page Shell](../../guides/page-shell.md)
(topbar / content / stacked sidebar). The floating bottom panel is
deliberately absent — it is selection chrome, and a form has no selection.

## Action inventory

| #   | Action                          | Trigger                               | Mechanism                                                              |
| --- | ------------------------------- | ------------------------------------- | ---------------------------------------------------------------------- |
| 1   | Save invoice                    | sticky bar, the page's one `primary`  | `type="submit"` → `persist()` (`form.transform` + `post`/`put`)        |
| 2   | Save as draft                   | sticky bar outline (create mode)      | `persist('draft')`; controller redirect lands on the edit route        |
| 3   | Delete invoice                  | sticky bar destructive (edit mode)    | `useConfirm` → `remove()` (promise-wrapped `form.delete`) → toast      |
| 4   | Cancel                          | sticky bar ghost                      | navigation (`href`, an Inertia visit); leave guard intercepts if dirty |
| 5   | Pick customer                   | details section select                | query-aware `items` provider (small JSON endpoint)                     |
| 6   | Pick project                    | details section select                | `dependencies` + `enforce-coherence` (§ tied selects)                  |
| 7   | Peek customer                   | "View customer" link under the select | `ctx.peekCustomer()` → shell stack                                     |
| 8   | Apply billing defaults          | peek workbench button                 | writes terms + tax rate into the draft, toast                          |
| 9   | Edit description inline         | line-item cell                        | §6.3: commit on blur/Enter, Esc reverts                                |
| 10  | Edit quantity / rate inline     | line-item cells                       | §6.3 with `BbNumberInput` (min/precision enforced)                     |
| 11  | Add line item                   | section header + empty state          | `ctx.addLineItem()` pushes a blank draft row                           |
| 12  | Duplicate line                  | row actions                           | `ctx.duplicateLineItem(line)` inserts a copy below                     |
| 13  | Remove line                     | row actions                           | `ctx.removeLineItem(line)`                                             |
| 14  | Search line items               | topbar page search                    | `lineItemSearch` → `visibleLineItems` filter                           |
| 15  | Toggle notes & terms            | section disclosure button             | `BbCollapsible` + `aria-expanded`/`aria-controls`                      |
| 16  | Open customer / recent invoices | peek links                            | real `href` navigation (an Inertia visit; leave guard applies)         |

## The code

### The shapes

What the page props contribute — the record every block below is grounded
in:

```ts
// @/types (excerpt)
export type InvoiceStatus = 'draft' | 'pending' | 'paid' | 'overdue';

export interface LineItemDraft {
	/** Server id; unsaved rows carry a negative local id. */
	id: number;
	description: string;
	quantity: number;
	unitPrice: number;
}

export interface InvoiceDraft {
	customerId: number | null;
	projectId: number | null;
	/** `YYYY-MM-DD` (the date inputs run with `floating`). */
	issuedAt: string | null;
	dueDate: string | null;
	paymentTerms: string | null;
	poNumber: string | null;
	taxRate: number | null;
	lineItems: LineItemDraft[];
	notes: string | null;
	terms: string | null;
}

export interface Invoice extends InvoiceDraft {
	id: number;
	number: string;
	status: InvoiceStatus;
}
```

```ts
// Inertia::render('Invoices/Edit', ['invoice' => ...]) page prop
const pageProps = {
	invoice: {
		id: 2107,
		number: 'INV-2107',
		status: 'draft',
		customerId: 18, // Northwind Traders
		projectId: 112, // Website relaunch
		issuedAt: '2026-07-01',
		dueDate: '2026-07-31',
		paymentTerms: 'Net 30',
		poNumber: 'PO-2026-0641',
		taxRate: 8.875,
		lineItems: [
			{
				id: 9001,
				description: 'Design sprint — homepage & navigation',
				quantity: 3,
				unitPrice: 1850,
			},
			{
				id: 9002,
				description: 'Frontend build — catalogue & product views',
				quantity: 5,
				unitPrice: 1200,
			},
			{
				id: 9003,
				description: 'CMS integration & content migration',
				quantity: 2,
				unitPrice: 1400,
			},
			{
				id: 9004,
				description: 'QA & cross-browser pass',
				quantity: 1,
				unitPrice: 950,
			},
			{
				id: 9005,
				description: 'Staging infrastructure (June)',
				quantity: 1,
				unitPrice: 240,
			},
		],
		notes:
			'Second milestone of the relaunch engagement. Hosting billed at cost.',
		terms:
			'Payment due within 30 days. 1.5% monthly interest on overdue balances.',
	}, // null on the create route
};
```

### context.ts

```ts
// InvoiceForm/context.ts
import {
	computed,
	inject,
	provide,
	ref,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import { useConfirm, useToast } from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import { usePromiseForm } from '@/composables/usePromiseForm';
import { useConfirmOnRouteLeave } from '@/composables/useConfirmOnRouteLeave';
import { useProp } from '@/composables/useProp';
import type {
	Customer,
	CustomerDetail,
	Invoice,
	InvoiceDraft,
	InvoiceStatus,
	LineItemDraft,
	Project,
} from '@/types';

/** What the stacked sidebar can show. Clicking the customer's name pushes one. */
export type PeekItem = { type: 'customer'; id: number };

type LineItemField = 'description' | 'quantity' | 'unitPrice';

export interface InvoiceFormContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	// -- Page-owned state ------------------------------------------------------
	mode: 'create' | 'edit';
	/** Inertia delivers `invoice` as a page prop — nothing to await; this stays
	 *  a trivial computed only so Index.vue's `v-if` reads the same on every
	 *  platform. */
	loaded: ComputedRef<true>;
	invoiceNumber: ComputedRef<string | null>;
	status: ComputedRef<InvoiceStatus>;
	/** The Inertia form's own reactive fields — the draft IS `form`. */
	draft: InvoiceDraft;
	/** Inertia's own error bag: one message per field (not an array). */
	errors: ComputedRef<Record<string, string>>;
	saving: ComputedRef<boolean>;
	isDirty: ComputedRef<boolean>;
	lineItemSearch: Ref<string>;
	visibleLineItems: ComputedRef<LineItemDraft[]>;
	subtotal: ComputedRef<number>;
	taxAmount: ComputedRef<number>;
	total: ComputedRef<number>;
	// -- Item providers (handed straight to the selects) ------------------------
	fetchCustomers: (query: string, prefill: boolean) => Promise<Customer[]>;
	fetchProjects: () => Promise<Project[]>;
	// -- Row-level error lookup --------------------------------------------------
	lineItemError: (
		line: LineItemDraft,
		field: LineItemField
	) => string | undefined;
	// -- Draft mutations (the cells and the peek write through these) -----------
	updateLineItem: (
		line: LineItemDraft,
		patch: Partial<Omit<LineItemDraft, 'id'>>
	) => void;
	addLineItem: () => void;
	duplicateLineItem: (line: LineItemDraft) => void;
	removeLineItem: (line: LineItemDraft) => void;
	applyCustomerDefaults: (customer: CustomerDetail) => void;
	// -- Peek grammar ------------------------------------------------------------
	peekCustomer: () => void;
	// -- Actions (complete: visit + toast) ----------------------------------------
	saveInvoice: () => Promise<void>;
	saveAsDraft: () => Promise<void>;
	deleteInvoice: () => Promise<void>;
}

const key: InjectionKey<InvoiceFormContext> = Symbol('invoice-form');

export function provideInvoiceForm(): InvoiceFormContext {
	const { toast } = useToast();
	const { confirm } = useConfirm();

	// -- Coopt the shell: once, here, for the whole page. ------------------------
	const shell = usePageShellContext<PeekItem>();

	// `invoice` is null on the create route, the full record on the edit route.
	const invoice = useProp<Invoice | null>('invoice');
	const mode: 'create' | 'edit' = invoice.value !== null ? 'edit' : 'create';
	const invoiceId = invoice.value?.id ?? null;
	const loaded = computed(() => true as const);

	const invoiceNumber = computed(() => invoice.value?.number ?? null);
	const status = computed<InvoiceStatus>(
		() => invoice.value?.status ?? 'draft'
	);

	// -- The draft IS the Inertia form -------------------------------------------
	// Unsaved rows get negative local ids so `item-value` stays stable and the
	// payload can tell the server which lines are new (negative → null).
	let nextLocalId = -1;
	const blankLineItem = (): LineItemDraft => ({
		id: nextLocalId--,
		description: '',
		quantity: 1,
		unitPrice: 0,
	});

	const { form, post, put, remove, isSubmitting } =
		usePromiseForm<InvoiceDraft>({
			customerId: invoice.value?.customerId ?? null,
			projectId: invoice.value?.projectId ?? null,
			issuedAt: invoice.value?.issuedAt ?? null,
			dueDate: invoice.value?.dueDate ?? null,
			paymentTerms: invoice.value?.paymentTerms ?? null,
			poNumber: invoice.value?.poNumber ?? null,
			taxRate: invoice.value?.taxRate ?? null,
			lineItems: invoice.value
				? invoice.value.lineItems.map((line) => ({ ...line }))
				: [blankLineItem()],
			notes: invoice.value?.notes ?? null,
			terms: invoice.value?.terms ?? null,
		});
	const draft = form;
	const errors = computed(() => form.errors as Record<string, string>);
	const saving = isSubmitting;
	const isDirty = computed(() => form.isDirty);

	// -- Item providers -----------------------------------------------------------
	// Small JSON endpoints, not page visits: searching a select must not
	// re-render the page. Component-initiated calls (`prefill === true`) must
	// keep the current selection resolvable, or the chip loses its text.
	const fetchCustomers = async (
		query: string,
		prefill: boolean
	): Promise<Customer[]> => {
		if (prefill && draft.customerId !== null) {
			return fetch(`/customers/search?ids[]=${draft.customerId}`).then((res) =>
				res.json()
			);
		}
		return fetch(`/customers/search?q=${encodeURIComponent(query)}`).then(
			(res) => res.json()
		);
	};

	// Re-run by the project select's `dependencies: [draft.customerId]`; the
	// response always contains the customer's full project list, so an existing
	// `projectId` stays resolvable and `enforce-coherence` never wipes a valid pick.
	const fetchProjects = (): Promise<Project[]> =>
		draft.customerId === null
			? Promise.resolve([])
			: fetch(`/customers/${draft.customerId}/projects`).then((res) =>
					res.json()
				);

	// -- Line items -----------------------------------------------------------------
	const lineItemSearch = ref('');
	const visibleLineItems = computed(() => {
		const query = lineItemSearch.value.trim().toLowerCase();
		if (!query) return draft.lineItems;
		return draft.lineItems.filter((line) =>
			line.description.toLowerCase().includes(query)
		);
	});

	const subtotal = computed(() =>
		draft.lineItems.reduce(
			(sum, line) => sum + line.quantity * line.unitPrice,
			0
		)
	);
	const taxAmount = computed(
		() => subtotal.value * ((draft.taxRate ?? 0) / 100)
	);
	const total = computed(() => subtotal.value + taxAmount.value);

	// Server error keys index lines by payload position, which is draft order —
	// resolve a row's key through its id so the lookup survives filtering.
	const lineItemError = (
		line: LineItemDraft,
		field: LineItemField
	): string | undefined => {
		const index = draft.lineItems.findIndex(
			(candidate) => candidate.id === line.id
		);
		return errors.value[`lineItems.${index}.${field}`];
	};

	const updateLineItem = (
		line: LineItemDraft,
		patch: Partial<Omit<LineItemDraft, 'id'>>
	) => {
		const target = draft.lineItems.find(
			(candidate) => candidate.id === line.id
		);
		if (target) Object.assign(target, patch);
	};
	const addLineItem = () => {
		draft.lineItems.push(blankLineItem());
	};
	const duplicateLineItem = (line: LineItemDraft) => {
		const index = draft.lineItems.findIndex(
			(candidate) => candidate.id === line.id
		);
		draft.lineItems.splice(index + 1, 0, { ...line, id: nextLocalId-- });
	};
	const removeLineItem = (line: LineItemDraft) => {
		draft.lineItems = draft.lineItems.filter(
			(candidate) => candidate.id !== line.id
		);
	};

	// The peek writes back into the draft: the sidebar is a workbench.
	const applyCustomerDefaults = (customer: CustomerDetail) => {
		draft.paymentTerms = customer.defaultPaymentTerms;
		draft.taxRate = customer.defaultTaxRate;
		toast({
			title: `Applied ${customer.name}'s billing defaults.`,
			variant: 'success',
		});
	};

	// -- Peek grammar ----------------------------------------------------------------
	const peekCustomer = () => {
		if (draft.customerId === null) return;
		shell.push({ type: 'customer', id: draft.customerId }, true);
	};

	// -- Persistence -----------------------------------------------------------------
	// The submit target doubles as the whitelist entry below: PUT/DELETE and the
	// create POST land on the same two paths.
	const submitUrl =
		mode === 'edit' && invoiceId !== null
			? `/invoices/${invoiceId}`
			: '/invoices';

	const persist = async (nextStatus: InvoiceStatus): Promise<boolean> => {
		// New lines travel with `id: null`; the server assigns real ids on save.
		// `transform` shapes the request without mutating the draft's own fields.
		form.transform((data) => ({
			...data,
			status: nextStatus,
			lineItems: (data.lineItems as LineItemDraft[]).map((line) => ({
				...line,
				id: line.id > 0 ? line.id : null,
			})),
		}));
		try {
			await (mode === 'edit' ? put(submitUrl) : post(submitUrl));
			// Re-baseline: the just-saved values become the new "clean" state,
			// same purpose as the Vue/Nuxt recipes' JSON snapshot re-take.
			form.defaults();
			return true;
		} catch {
			// form.errors is already populated by usePromiseForm's reject path.
			toast({
				title: form.hasErrors
					? 'Some fields need attention.'
					: 'Something went wrong. Try again.',
				variant: 'destructive',
			});
			return false;
		}
	};

	const saveInvoice = async () => {
		// Creating finalizes the invoice; editing keeps whatever status it has.
		const ok = await persist(mode === 'edit' ? status.value : 'pending');
		if (!ok) return;
		// The controller's redirect is followed inside this same visit — no
		// client-side navigation call needed.
		toast({
			title:
				mode === 'edit'
					? `Invoice ${invoiceNumber.value} saved.`
					: 'Invoice created.',
			variant: 'success',
		});
	};

	const saveAsDraft = async () => {
		const ok = await persist('draft');
		if (!ok) return;
		toast({
			title:
				mode === 'edit'
					? `Draft ${invoiceNumber.value} saved.`
					: 'Draft saved.',
			variant: 'success',
		});
	};

	const deleteInvoice = async () => {
		if (mode !== 'edit' || invoiceId === null) return;
		const ok = await confirm({
			variant: 'destructive',
			title: 'Delete invoice',
			text: `Delete ${invoiceNumber.value}? This cannot be undone.`,
			yes: 'Delete',
			no: 'Cancel',
		});
		if (!ok) return;
		await remove(submitUrl);
		toast({ title: `${invoiceNumber.value} deleted.`, variant: 'success' });
	};

	// -- Route-leave guard ---------------------------------------------------------
	// `form.isDirty` needs no snapshot bookkeeping; the submit URL is whitelisted
	// so saving (which IS a visit) can't confirm-block itself.
	useConfirmOnRouteLeave({
		disabled: () => !form.isDirty,
		whitelist: [submitUrl],
		title: 'Unsaved changes',
		text: 'You have unsaved changes on this invoice. Leave without saving?',
	});

	const ctx: InvoiceFormContext = {
		shell,
		mode,
		loaded,
		invoiceNumber,
		status,
		draft,
		errors,
		saving,
		isDirty,
		lineItemSearch,
		visibleLineItems,
		subtotal,
		taxAmount,
		total,
		fetchCustomers,
		fetchProjects,
		lineItemError,
		updateLineItem,
		addLineItem,
		duplicateLineItem,
		removeLineItem,
		applyCustomerDefaults,
		peekCustomer,
		saveInvoice,
		saveAsDraft,
		deleteInvoice,
	};
	provide(key, ctx);
	return ctx;
}

export function useInvoiceForm(): InvoiceFormContext {
	const ctx = inject(key);
	if (!ctx) throw new Error('useInvoiceForm() called outside InvoiceForm');
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- InvoiceForm/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left, page search right. The search scopes the
		     work surface — here, the line-items table. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs class="min-w-0 flex-auto" :items="trail" />
				<BbTextInput
					v-model="ctx.lineItemSearch.value"
					autocomplete="off"
					class="shrink-0"
					clearable
					compact
					hide-label
					label="Search line items"
					placeholder="Search line items…"
					prepend:icon="lucide:search"
				/>
			</div>
		</template>

		<div
			v-if="ctx.loaded.value"
			class="mx-auto flex w-full max-w-4xl flex-col gap-6 p-4"
		>
			<header class="flex items-center gap-3">
				<h1 class="text-lg font-semibold">
					{{
						ctx.mode === 'edit'
							? `Edit ${ctx.invoiceNumber.value}`
							: 'New invoice'
					}}
				</h1>
				<BbBadge v-if="ctx.mode === 'edit'" variant="outline">{{
					ctx.status.value
				}}</BbBadge>
			</header>

			<!-- One form, one submit. `novalidate` keeps error UX on the inputs'
			     `errors` surface instead of browser bubbles. -->
			<form
				class="flex flex-col gap-6"
				novalidate
				@submit.prevent="ctx.saveInvoice"
			>
				<DetailsSection />
				<LineItemsSection />
				<NotesSection />
				<FormActions />
			</form>
		</div>

		<div v-else class="flex justify-center p-12">
			<BbSpinner label="Loading invoice…" />
		</div>

		<!-- Stacked peek sidebar: the shell owns back/close; we render by type. -->
		<template #sidebar>
			<CustomerPeek
				v-if="ctx.shell.current.value?.type === 'customer'"
				:customer-id="ctx.shell.current.value.id"
			/>
		</template>
	</PageShell>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbBadge, BbBreadcrumbs, BbSpinner, BbTextInput } from 'bitboss-ui';
import PageShell from '@/components/layout/PageShell.vue';
import { provideInvoiceForm } from './context';
import CustomerPeek from './CustomerPeek.vue';
import DetailsSection from './DetailsSection.vue';
import FormActions from './FormActions.vue';
import LineItemsSection from './LineItemsSection.vue';
import NotesSection from './NotesSection.vue';

const ctx = provideInvoiceForm();

// A real trail, ≥ 2 linked levels; the current page carries no target.
const trail = computed(() => [
	{ key: 'dashboard', text: 'Dashboard', href: '/dashboard' },
	{ key: 'billing', text: 'Billing', href: '/billing' },
	{ key: 'invoices', text: 'Invoices', href: '/invoices' },
	{
		key: 'invoice',
		text:
			ctx.mode === 'edit'
				? (ctx.invoiceNumber.value ?? 'Invoice')
				: 'New invoice',
	},
]);
</script>
```

### DetailsSection.vue

```vue
<!-- InvoiceForm/DetailsSection.vue -->
<template>
	<section class="flex flex-col gap-3">
		<h2
			class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
		>
			Details
		</h2>

		<div class="grid gap-4 sm:grid-cols-2">
			<!-- Tied selects: project depends on customer. `dependencies` re-runs
			     the project provider; `enforce-coherence` clears a project that is
			     no longer among the new options. No watchers. -->
			<div class="flex flex-col gap-1">
				<BbSelect
					v-model="ctx.draft.customerId"
					:errors="ctx.errors.value.customerId"
					item-text="name"
					item-value="id"
					:items="ctx.fetchCustomers"
					label="Customer"
					placeholder="Search customers…"
				/>
				<!-- Clicking the NAME of a thing peeks it. -->
				<BbButton
					v-if="ctx.draft.customerId !== null"
					append:icon="lucide:panel-right-open"
					class="self-start"
					size="sm"
					variant="link"
					@click="ctx.peekCustomer"
				>
					View customer
				</BbButton>
			</div>

			<BbSelect
				v-model="ctx.draft.projectId"
				:dependencies="[ctx.draft.customerId]"
				:disabled="ctx.draft.customerId === null"
				enforce-coherence
				:errors="ctx.errors.value.projectId"
				item-text="name"
				item-value="id"
				:items="ctx.fetchProjects"
				label="Project"
				placeholder="Pick the customer first"
			/>

			<!-- `floating` keeps the model a plain YYYY-MM-DD string, so the due
			     date's `min` can be fed straight from the issue date. -->
			<BbDatePickerInput
				v-model="ctx.draft.issuedAt"
				:errors="ctx.errors.value.issuedAt"
				floating
				label="Issue date"
				prepend:icon="lucide:calendar"
			/>
			<BbDatePickerInput
				v-model="ctx.draft.dueDate"
				:errors="ctx.errors.value.dueDate"
				floating
				label="Due date"
				:min="ctx.draft.issuedAt ?? undefined"
				prepend:icon="lucide:calendar"
			/>

			<BbSelect
				v-model="ctx.draft.paymentTerms"
				:errors="ctx.errors.value.paymentTerms"
				:items="['Due on receipt', 'Net 15', 'Net 30', 'Net 60']"
				label="Payment terms"
				placeholder="Choose terms"
			/>

			<BbTextInput
				v-model="ctx.draft.poNumber"
				:errors="ctx.errors.value.poNumber"
				label="PO / reference"
				placeholder="PO-2026-0641"
			/>

			<BbNumberInput
				v-model="ctx.draft.taxRate"
				:errors="ctx.errors.value.taxRate"
				hint="Applied to the subtotal below."
				label="Tax rate"
				:max="100"
				:max-precision="3"
				:min="0"
			>
				<template #suffix>%</template>
			</BbNumberInput>
		</div>
	</section>
</template>

<script setup lang="ts">
import {
	BbButton,
	BbDatePickerInput,
	BbNumberInput,
	BbSelect,
	BbTextInput,
} from 'bitboss-ui';
import { useInvoiceForm } from './context';

const ctx = useInvoiceForm();
</script>
```

### LineItemsSection.vue

```vue
<!-- InvoiceForm/LineItemsSection.vue -->
<template>
	<section class="flex flex-col gap-3">
		<div class="flex items-center justify-between">
			<h2
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Line items
			</h2>
			<BbButton
				prepend:icon="lucide:plus"
				variant="outline"
				@click="ctx.addLineItem"
			>
				Add line item
			</BbButton>
		</div>

		<!-- Inline-editing table (§6.3): every editable cell type is its own
		     leaf. The amount column is virtual — computed from the row. -->
		<BbTable
			actions
			caption="Invoice line items"
			:columns="columns"
			compact
			item-value="id"
			:items="ctx.visibleLineItems.value"
		>
			<template #description="{ item }">
				<EditableDescriptionCell :line="item" />
			</template>

			<template #quantity="{ item }">
				<EditableQuantityCell :line="item" />
			</template>

			<template #unit_price="{ item }">
				<EditableRateCell :line="item" />
			</template>

			<template #actions="{ item }">
				<div class="flex items-center justify-end gap-1">
					<BbButton
						icon="lucide:copy"
						size="sm"
						variant="ghost"
						@click="() => ctx.duplicateLineItem(item)"
					>
						Duplicate line
					</BbButton>
					<BbButton
						icon="lucide:trash-2"
						size="sm"
						variant="ghost"
						@click="() => ctx.removeLineItem(item)"
					>
						Remove line
					</BbButton>
				</div>
			</template>

			<template #no-data>
				<div class="flex flex-col items-center gap-2 p-6 text-center">
					<p class="text-sm text-[color:var(--bb-text-muted)]">
						{{
							ctx.lineItemSearch.value
								? 'No line items match your search.'
								: 'No line items yet.'
						}}
					</p>
					<BbButton
						v-if="!ctx.lineItemSearch.value"
						variant="outline"
						@click="ctx.addLineItem"
					>
						Add the first line
					</BbButton>
				</div>
			</template>
		</BbTable>

		<!-- Totals: live computed from the draft — they move as cells commit. -->
		<dl class="ml-auto grid w-60 grid-cols-[1fr_auto] gap-y-1 text-sm">
			<dt class="text-[color:var(--bb-text-muted)]">Subtotal</dt>
			<dd class="text-right tabular-nums">
				{{ currency.format(ctx.subtotal.value) }}
			</dd>
			<dt class="text-[color:var(--bb-text-muted)]">
				Tax ({{ ctx.draft.taxRate ?? 0 }}%)
			</dt>
			<dd class="text-right tabular-nums">
				{{ currency.format(ctx.taxAmount.value) }}
			</dd>
			<dt class="font-semibold">Total</dt>
			<dd class="text-right font-semibold tabular-nums">
				{{ currency.format(ctx.total.value) }}
			</dd>
		</dl>
	</section>
</template>

<script setup lang="ts">
import { BbButton, BbTable } from 'bitboss-ui';
import EditableDescriptionCell from './EditableDescriptionCell.vue';
import EditableQuantityCell from './EditableQuantityCell.vue';
import EditableRateCell from './EditableRateCell.vue';
import { useInvoiceForm } from './context';
import type { LineItemDraft } from '@/types';

const ctx = useInvoiceForm();

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});

// `unit_price` and `amount` match no item field on purpose: the first is
// fully slotted (snake_case key so the slot name reads naturally), the
// second is a virtual column deriving its content in the formatter.
const columns = [
	{ key: 'description', label: 'Description' },
	{ key: 'quantity', label: 'Qty', align: 'right' as const, width: 96 },
	{
		key: 'unit_price',
		label: 'Unit price',
		align: 'right' as const,
		width: 140,
	},
	{
		key: 'amount',
		label: 'Amount',
		align: 'right' as const,
		width: 130,
		formatter: (_: unknown, __: string, item: LineItemDraft) =>
			currency.format(item.quantity * item.unitPrice),
	},
];
</script>
```

### EditableDescriptionCell.vue

```vue
<!-- InvoiceForm/EditableDescriptionCell.vue -->
<template>
	<BbTextInput
		v-if="editing"
		v-model="value"
		autofocus
		compact
		:errors="ctx.lineItemError(line, 'description')"
		hide-label
		label="Line description"
		placeholder="What was delivered?"
		@blur="commit"
		@keydown.enter.prevent="commit"
		@keydown.esc="revert"
	/>
	<button
		v-else
		class="w-full rounded-[var(--bb-radius)] px-1 py-0.5 text-left hover:bg-[color:var(--bb-hover)]"
		:class="{
			'text-[color:var(--bb-text-muted)]': !line.description,
			'text-red-600 dark:text-red-400': hasError,
		}"
		type="button"
		@click="start"
	>
		{{ line.description || 'Add a description…' }}
	</button>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbTextInput } from 'bitboss-ui';
import { useInvoiceForm } from './context';
import type { LineItemDraft } from '@/types';

const props = defineProps<{ line: LineItemDraft }>();

const ctx = useInvoiceForm();

// Rung 1 of the ladder: only this cell reads or writes its editing state.
const editing = ref(false);
const value = ref<string | null>(null);

const hasError = computed(() => !!ctx.lineItemError(props.line, 'description'));

const start = () => {
	value.value = props.line.description;
	editing.value = true;
};

// Commit on blur/Enter, revert on Esc (§6.3). Enter is prevented so it
// edits the cell instead of submitting the enclosing invoice form; the
// `editing` guard keeps the blur that follows an Esc from re-committing.
const commit = () => {
	if (!editing.value) return;
	editing.value = false;
	ctx.updateLineItem(props.line, { description: value.value ?? '' });
};

const revert = () => {
	editing.value = false;
};
</script>
```

### EditableQuantityCell.vue

```vue
<!-- InvoiceForm/EditableQuantityCell.vue -->
<template>
	<BbNumberInput
		v-if="editing"
		v-model="value"
		autofocus
		compact
		:errors="ctx.lineItemError(line, 'quantity')"
		hide-label
		label="Quantity"
		:max-precision="2"
		:min="0"
		@blur="commit"
		@keydown.enter.prevent="commit"
		@keydown.esc="revert"
	/>
	<button
		v-else
		class="w-full rounded-[var(--bb-radius)] px-1 py-0.5 text-right tabular-nums hover:bg-[color:var(--bb-hover)]"
		:class="{ 'text-red-600 dark:text-red-400': hasError }"
		type="button"
		@click="start"
	>
		{{ line.quantity }}
	</button>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbNumberInput } from 'bitboss-ui';
import { useInvoiceForm } from './context';
import type { LineItemDraft } from '@/types';

const props = defineProps<{ line: LineItemDraft }>();

const ctx = useInvoiceForm();

const editing = ref(false);
const value = ref<number | null>(null);

const hasError = computed(() => !!ctx.lineItemError(props.line, 'quantity'));

const start = () => {
	value.value = props.line.quantity;
	editing.value = true;
};

const commit = () => {
	if (!editing.value) return;
	editing.value = false;
	// An emptied field emits null — treat it as a revert, not a zero.
	if (value.value === null) return;
	ctx.updateLineItem(props.line, { quantity: value.value });
};

const revert = () => {
	editing.value = false;
};
</script>
```

### EditableRateCell.vue

```vue
<!-- InvoiceForm/EditableRateCell.vue -->
<template>
	<BbNumberInput
		v-if="editing"
		v-model="value"
		autofocus
		compact
		:errors="ctx.lineItemError(line, 'unitPrice')"
		hide-label
		label="Unit price"
		:max-precision="2"
		:min="0"
		@blur="commit"
		@keydown.enter.prevent="commit"
		@keydown.esc="revert"
	>
		<template #prefix>$</template>
	</BbNumberInput>
	<button
		v-else
		class="w-full rounded-[var(--bb-radius)] px-1 py-0.5 text-right tabular-nums hover:bg-[color:var(--bb-hover)]"
		:class="{ 'text-red-600 dark:text-red-400': hasError }"
		type="button"
		@click="start"
	>
		{{ currency.format(line.unitPrice) }}
	</button>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbNumberInput } from 'bitboss-ui';
import { useInvoiceForm } from './context';
import type { LineItemDraft } from '@/types';

const props = defineProps<{ line: LineItemDraft }>();

const ctx = useInvoiceForm();

const editing = ref(false);
const value = ref<number | null>(null);

const hasError = computed(() => !!ctx.lineItemError(props.line, 'unitPrice'));

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});

const start = () => {
	value.value = props.line.unitPrice;
	editing.value = true;
};

const commit = () => {
	if (!editing.value) return;
	editing.value = false;
	if (value.value === null) return;
	ctx.updateLineItem(props.line, { unitPrice: value.value });
};

const revert = () => {
	editing.value = false;
};
</script>
```

### NotesSection.vue

```vue
<!-- InvoiceForm/NotesSection.vue -->
<template>
	<section class="flex flex-col gap-2">
		<!-- BbCollapsible ships no trigger: this button owns the disclosure
		     ARIA (`aria-expanded` + `aria-controls`). -->
		<BbButton
			append:icon="lucide:chevron-down"
			aria-controls="invoice-notes"
			:aria-expanded="open"
			class="self-start"
			variant="ghost"
			@click="open = !open"
		>
			Notes &amp; terms
		</BbButton>

		<!-- `eager` mounts the fields up front so their 422 errors render even
		     if the user never opened the section. Spacing lives on the inner
		     content — the collapsible zeroes its own box when closed. -->
		<BbCollapsible id="invoice-notes" v-model="open" eager>
			<div class="flex flex-col gap-4 pt-1">
				<BbTextarea
					v-model="ctx.draft.notes"
					auto-grow
					description="Shown on the invoice, under the line items."
					:errors="ctx.errors.value.notes"
					label="Notes to the customer"
					placeholder="Second milestone of the relaunch engagement…"
					:rows="2"
				/>
				<BbTextarea
					v-model="ctx.draft.terms"
					auto-grow
					description="Payment terms printed in the invoice footer."
					:errors="ctx.errors.value.terms"
					label="Terms"
					placeholder="Payment due within 30 days…"
					:rows="2"
				/>
			</div>
		</BbCollapsible>
	</section>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbCollapsible, BbTextarea } from 'bitboss-ui';
import { useInvoiceForm } from './context';

const ctx = useInvoiceForm();

// Rung 1: only this section cares whether it is open. Inertia delivers the
// invoice synchronously as a page prop, so seeding from the draft here
// starts an annotated invoice open and a blank one closed, same as Vue/Nuxt.
const open = ref(ctx.draft.notes !== null || ctx.draft.terms !== null);
</script>
```

### FormActions.vue

```vue
<!-- InvoiceForm/FormActions.vue -->
<template>
	<!-- Sticky action row: the commit affordance never scrolls away. Not the
	     floating bottom panel — that is selection chrome, and a form has no
	     selection. -->
	<div
		class="sticky bottom-0 z-10 -mx-4 flex items-center gap-3 border-t bg-[color:var(--bb-panel)] px-4 py-3"
	>
		<BbButton
			v-if="ctx.mode === 'edit'"
			prepend:icon="lucide:trash-2"
			variant="destructive"
			@click="ctx.deleteInvoice"
		>
			Delete
		</BbButton>
		<p
			v-if="ctx.isDirty.value"
			class="text-xs text-[color:var(--bb-text-muted)]"
		>
			Unsaved changes
		</p>

		<div class="ml-auto flex items-center gap-2">
			<!-- Cancel is navigation: the route-leave guard asks about a dirty
			     draft, so no bespoke confirm here. -->
			<BbButton :disabled="ctx.saving.value" href="/invoices" variant="ghost">
				Cancel
			</BbButton>
			<BbButton
				v-if="ctx.mode === 'create'"
				:disabled="ctx.saving.value"
				variant="outline"
				@click="ctx.saveAsDraft"
			>
				Save as draft
			</BbButton>
			<BbButton :loading="ctx.saving.value" type="submit" variant="primary">
				{{ ctx.mode === 'edit' ? 'Save changes' : 'Create invoice' }}
			</BbButton>
		</div>
	</div>
</template>

<script setup lang="ts">
import { BbButton } from 'bitboss-ui';
import { useInvoiceForm } from './context';

const ctx = useInvoiceForm();
</script>
```

### CustomerPeek.vue

```vue
<!-- InvoiceForm/CustomerPeek.vue -->
<template>
	<div v-if="customer" class="flex flex-col gap-4 text-sm">
		<header class="flex items-center gap-3">
			<BbAvatar :alt="customer.name" :src="customer.avatarUrl" />
			<div class="flex flex-col">
				<h2 class="text-base font-semibold">{{ customer.name }}</h2>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					{{ customer.email }} · {{ customer.country }}
				</p>
			</div>
		</header>

		<!-- Stat strip. -->
		<div class="grid grid-cols-3 gap-2">
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Total billed</p>
				<p class="font-semibold">{{ currency.format(customer.totalBilled) }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Outstanding</p>
				<p class="font-semibold">{{ currency.format(customer.outstanding) }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Invoices</p>
				<p class="font-semibold">{{ customer.invoiceCount }}</p>
			</div>
		</div>

		<!-- Billing profile: exactly the fields this form negotiates. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Billing profile
			</h3>
			<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
				<dt class="text-[color:var(--bb-text-muted)]">Default terms</dt>
				<dd>{{ customer.defaultPaymentTerms }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Default tax rate</dt>
				<dd>{{ customer.defaultTaxRate }}%</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Tax ID</dt>
				<dd>{{ customer.taxId }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Billing email</dt>
				<dd>{{ customer.billingEmail }}</dd>
			</dl>
			<!-- The peek acts on the form: this writes into the draft. -->
			<BbButton
				class="mt-1 self-start"
				prepend:icon="lucide:sparkles"
				size="sm"
				variant="secondary"
				@click="() => ctx.applyCustomerDefaults(customer!)"
			>
				Apply billing defaults
			</BbButton>
		</section>

		<!-- Recent invoices: real links — leaving a dirty draft still goes
		     through the route-leave guard. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Recent invoices
			</h3>
			<ul class="flex flex-col">
				<li
					v-for="recent in customer.recentInvoices"
					:key="recent.id"
					class="flex items-center justify-between gap-2 border-b py-1.5 last:border-b-0"
				>
					<BbBaseButton class="plain-link" :href="`/invoices/${recent.id}`">
						{{ recent.number }}
					</BbBaseButton>
					<BbBadge variant="outline">{{ recent.status }}</BbBadge>
					<span class="text-xs tabular-nums text-[color:var(--bb-text-muted)]">
						{{ currency.format(recent.amount) }}
					</span>
				</li>
			</ul>
		</section>

		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				append:icon="lucide:arrow-up-right"
				:href="`/customers/${customer.id}`"
				size="sm"
				variant="ghost"
			>
				Open customer
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { BbAvatar, BbBadge, BbButton, BbSpinner } from 'bitboss-ui';
import { useResourceContext } from '@/composables/useResourceContext';
import { useInvoiceForm } from './context';
import type { CustomerDetail } from '@/types';

const props = defineProps<{ customerId: number }>();

const ctx = useInvoiceForm();

// A small JSON endpoint, not a page visit — opening the peek never
// re-renders the form underneath it.
const { data: customer } = useResourceContext<CustomerDetail, number>(
	() => props.customerId,
	(id) => fetch(`/customers/${id}/peek`).then((res) => res.json())
);

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
</script>
```

## Why it is built this way

- **The context coopts, leaves consume.** The shell is joined once in
  `provideInvoiceForm()`; ten components share the draft, the errors, the
  peek stack and every action through one `useInvoiceForm()` call. The only
  props on the page are data-identity props: the cells' `line` and the
  peek's `customer-id`. Notably there is **no table context** here — the
  line-items table has no selection, no paging and no fetch; its entire
  state _is_ the draft, so there is nothing for a `useBbTableContext`
  handle to carry.
- **The draft is `usePromiseForm`'s own reactive fields.** Cell commits,
  line add/duplicate/remove and "apply billing defaults" mutate
  `ctx.draft` exactly like the Vue/Nuxt recipes (still context actions —
  leaves never reach around it); the only extra step is `form.transform()`
  inside `persist()`, which shapes the outgoing request (adds `status`,
  nulls out negative local ids) without mutating the draft the inputs are
  bound to.
- **422 keys are the server's shape, not reshaped.** `form.errors` arrives
  keyed exactly like Laravel's validation bag (`customerId`,
  `lineItems.2.unitPrice`) — no manual mapping. Scalar inputs bind
  `ctx.errors.value.<field>` directly; row errors keep their dotted keys
  and the cells resolve them through `lineItemError`, which derives the
  index from the row's id — so the lookup survives the page-search filter
  reordering what is visible.
- **Tied selects trust the machinery.** `dependencies: [draft.customerId]`
  re-runs the project provider, `enforce-coherence` prunes a stale pick,
  and both providers honor the prefill contract (return the selected
  record on component-initiated calls) so a valid selection is never
  wiped — the exact failure mode the BbSelect guide warns about. The
  providers themselves are small JSON endpoints (not lazy props), because
  the customer search is user-typed and the project list is parameterized
  by the chosen customer.
- **The inline-edit grammar is three tiny leaves, not one configurable
  cell.** Each editable cell owns rung-1 state (`editing`, the in-flight
  value), commits on blur/Enter and reverts on Esc. Enter is
  `.prevent`-ed so it commits the cell instead of submitting the enclosing
  form, and the `editing` guard keeps the unmount blur after an Esc from
  re-committing the reverted value.
- **Dirty tracking is native, so there is no snapshot to maintain.**
  `form.isDirty` already compares the live draft against its baseline;
  `form.defaults()` re-takes that baseline after every successful save,
  the same purpose the Vue/Nuxt JSON snapshot re-take serves. The
  route-leave guard is `useConfirmOnRouteLeave({ disabled: () =>
!form.isDirty, whitelist: [submitUrl] })` — the whitelist is required
  because submitting the form _is_ a visit, and without it the guard would
  confirm-block the form's own save.
- **No client-side redirects after save.** Unlike the Vue/Nuxt recipes'
  explicit `router.push`/`navigateTo`, the Laravel controller's redirect is
  followed inside the same Inertia visit that `post`/`put` performs —
  `saveInvoice`, `saveAsDraft` and `deleteInvoice` only toast.
- **A sticky action row, not the floating bottom panel.** The panel from
  the guides is selection-driven chrome that comes and goes; a form's
  commit affordance must be permanently visible, so it is a sticky row on
  the page surface (`--bb-panel` background, top border) hosting the one
  `variant="primary"` of the page.
- **Sizing:** the form fields are full-height — a form is not a dense
  surface. `compact` appears where density is real: the topbar search, the
  line-items table and its cell inputs. `sm` buttons appear only in the
  table's row actions, the "View customer" link and the peek; everything
  in the sticky row is default `md`.
- **Destructive actions ride `useConfirm`** — delete and the leave guard
  both — and the peek is a workbench: it acts on the draft and links out
  with real `href`s (Inertia visits), never `@click` + `router.visit`.

## Variations

- **Inside a `BbDialog`** (quick create from the invoices workspace): drop
  `useConfirmOnRouteLeave` and breadcrumbs, keep `form.isDirty`, confirm on
  the dialog's close instead, and move the action row into the dialog
  `#footer` — the context and sections carry over unchanged.
- **Autosave drafts**: debounce a watcher on `draft` that calls
  `persist('draft')` silently and re-takes `form.defaults()` per save; the
  "Save as draft" button disappears and the sticky row shows "Saved 12s
  ago".
- **Client-side pre-validation**: validate required fields on submit
  before calling `post`/`put` and merge the messages into `form.errors`
  via `form.setError(...)` — the inputs cannot tell the difference, which
  is the point.
- **Per-line tax**: add an `EditableTaxCell` per row (its own leaf, per
  the no-API-monster rule) and group the totals block by rate.
- **Send flow**: the primary becomes "Save and send" and opens a
  `BbDialog` preview (recipient, subject, PDF) whose open-state lives on
  the context, before persisting with `status: 'pending'`.
- **Static option catalogs**: if the customer list is small and identical
  for every render, swap `fetchCustomers`' JSON endpoint for a lazy prop —
  `const { getter: fetchCustomers } = useLazyPropGetter('customers')` — see
  `useLazyPropGetter` in the [Inertia Helpers](../../guides/inertia-helpers.md)
  guide.
- **Per-field persistence**: this page deliberately has no per-cell save
  feedback because no per-cell save exists — the draft is the mutation
  boundary and Save is the one commit. When the domain wants every field
  to persist itself (no Save button), that is the autosave pattern: see
  the [Inline Edit Playbook](../../guides/inline-edit-playbook.md) and
  the inline-edit-workspace recipe.

## Related

- [Records Workspace (Inertia)](./records-workspace.md) — the listing page
  this form is reached from.
- [Inertia Helpers](../../guides/inertia-helpers.md) — `usePromiseForm`,
  `useConfirmOnRouteLeave`, `useResourceContext` in full.
- [Page Shell](../../guides/page-shell.md) — the app-side layout the
  customer peek renders inside.
- [BbTable](../../BbTable.md), [BbSelect](../../BbSelect.md),
  [BbCollapsible](../../BbCollapsible.md) — the components this page
  leans on hardest.

---

<!-- dist/ai/recipes/inertia/records-workspace.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/inertia/records-workspace.md -->

# Recipe: Records Workspace (Inertia)

The flagship advanced-page recipe adapted for **Laravel + Inertia**: the
same Stripe-invoices × Linear list workspace — app chrome, breadcrumbs +
page search, chip filter rail, tabs with live counts, a dense server-paged
table, a floating bulk-action bar, and a stacked peek sidebar — but the list
is a page prop, filters mirror into the URL through
[`useQueryObject`](../../guides/inertia-helpers.md), selection and paging
come from the keyed [`useTableContext`](../../guides/inertia-helpers.md),
and every mutation is a promise-wrapped `router.visit`. Anatomy, components,
the context shape, copy and data are identical to the Vue recipe; only the
data/URL/mutation layer changes.

Sibling recipes: [Vue](../vue/records-workspace.md) ·
[Nuxt](../nuxt/records-workspace.md).

## Prerequisites

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell`, `usePageShellContext` and `FloatingBottomPanel` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
- `<BbConfirm />` and `<BbToast />` mounted once in the `createInertiaApp` render root — never in a page.
- From the [Inertia Helpers](../../guides/inertia-helpers.md) toolkit:
  `useTableContext`, `useQueryObject`, `useResourceContext`.
- Controller: `Inertia::render('Invoices/Index', ['invoices' =>
InvoicePaginator::make(...), 'tabCounts' => [...]])` — `invoices` is a
  standard Laravel paginator (`PaginatedResponse<Invoice>`) and `tabCounts`
  a plain `{ all, outstanding, paid, archived }` map. Both are re-sent on
  every partial reload the page triggers (`only: ['invoices', 'tabCounts']`).
  Mutation routes are plain Laravel routes (`PATCH /invoices/:id`,
  `POST /invoices/:id/duplicate`, …) that redirect back; small JSON GET
  endpoints (`GET /invoices/:id/peek`, `GET /customers/:id/peek`,
  `GET /customers/search`) back the sidebar peeks and the customer filter
  facet so neither is a full-page visit.

## Key ideas

- **One coopting page context.** `provideInvoicesWorkspace()` joins the
  page-shell stack **and** the keyed `useTableContext('invoices')` once,
  owns filters/tab/dialogs, and exposes complete actions. Every leaf calls
  `useInvoicesWorkspace()` and nothing else — zero prop drilling anywhere
  on the page.
- **The table has no client-side fetch at all.** `invoices` arrives as a
  page prop; `useTableContext('invoices')` turns it into `items` +
  `totalItems`/`page`/`perPage` (URL-backed) + `selected`/`unselected`/`all`
  (select-all-across-pages), and `BbTable` binds directly to that handle —
  no `dependencies`, no items function.
- **Filters mirror into the URL with `useQueryObject`.** Changing a filter
  performs a partial Inertia visit
  (`only: ['invoices', 'tabCounts']`); the server is the single source of
  filtered, paginated truth.
- **One Filters menu, one chip per applied facet.** The rail is a single
  `BbDropdown` (`BbDropdown.md` § Nested submenus + § Selectable groups) of
  nested category → selectable/searchable groups (Status, Customer) plus one
  chip per APPLIED facet — never one per value. Each chip is itself a small
  `BbDropdown` scoped to that one group (an external `activator` ref onto a
  `BbBadgeButton`, not the `#activator` slot — nesting a component between
  `BbBadge` and its button breaks the badge's direct-child detection), reading
  its label from `useBbDropdownContext` so it never re-fetches what the menu
  already resolved. Clearing happens chip by chip via the badge's clear
  button (no bulk clear-all). **Never** `BbSelectPopover` + an imperative
  `ref.open()` here: it exposes nothing to call, and its floating mode closes
  an `sr-only`/off-screen activator the instant it opens. Due date is a
  free-form range, not a discrete facet, so it stays its own compact
  `BbDatePickerInput` pill outside the menu.
- **Tabs are real visits.** `BbTabs` items carry `href` + `server: true`
  (component-level `navigation` is required alongside it) so switching tabs
  is a genuine, partial-reloaded Inertia visit — not a client-only URL
  change.
- **Mutations are promise-wrapped `router.visit` calls.** A tiny local
  `visit()` helper turns Inertia's callback-based API into a promise, so
  context actions stay `async function`s exactly like the Vue/Nuxt
  versions — `await ctx.updateStatus(...)` reads the same everywhere.
- **Clicking a row peeks it.** `v-model:highlighted` is bound to the shell
  stack, so the highlighted row and the open peek are the same fact; the
  invoice number cell links to the full detail page instead. Peeks fetch
  from a small JSON endpoint via `useResourceContext` — not a full-page
  visit, so opening the sidebar never replaces the list underneath it.
- **Buttons are `md` by default** (28px, flush beside `compact` inputs);
  `sm` only in the table rows, the peeks' headers and the bottom bar.

## Page anatomy

```
InvoicesWorkspace/
	Index.vue               ← assembly: PageShell slots, table, tabs, pagination
	context.ts               ← coopting page context (shell + useTableContext + filters + actions)
	facets.ts                ← the facet contract (shape only — deliberately no shared builder)
	dueRange.ts              ← due-date preset keys + range math
	FilterRail.vue           ← one Filters menu + one chip per applied facet
	FilterChip.vue           ← applied-facet chip — itself a dropdown onto the same filter
	StatusCell.vue           ← one-click status change (soft badge → BbSelectPopover)
	DueDateCell.vue          ← inline due-date reschedule (v-bb-date directive on the cell button)
	RowActions.vue           ← per-row "…" dropdown
	SelectionBar.vue         ← bulk actions in the floating bottom panel
	InvoicePeek.vue          ← sidebar workbench, stack level 1
	CustomerPeek.vue         ← stacked peek, back arrow via the shell
	RecordPaymentDialog.vue  ← page-level dialog, driven by the context
```

Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
(left nav + fat footer), [Page Shell](../../guides/page-shell.md),
[Floating Bottom Panel](../../guides/floating-bottom-panel.md).

## Action inventory

| #   | Action                     | Trigger                          | Mechanism                                                                                      |
| --- | -------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------- |
| 1   | New invoice                | topbar, the page's one `primary` | navigation (`href="/invoices/create"`)                                                         |
| 2   | Page search                | topbar right                     | `filters.search` → `useQueryObject` partial visit                                              |
| 3   | Filter status / customer   | Filters menu + filter chips      | `BbDropdown` nested facets; chip = small scoped `BbDropdown` on the same group                 |
| 3b  | Filter due date            | date-range pill                  | `BbDatePickerInput` range — not a Filters-menu facet                                           |
| 4   | Clear a filter             | chip clear button / date pill    | badge `@click:clear` (status/customer) or input `clearable` (due) — one at a time, no bulk CTA |
| 5   | Switch tab                 | server-visit tabs with counts    | `BbTabs` `href` + `server: true` visit                                                         |
| 6   | Peek invoice               | row click / peek lists           | `v-model:highlighted` → `peekInvoice(id)`, JSON fetch                                          |
| 7   | Peek customer              | customer cell (fresh) / in peeks | `peekCustomer(id)` / `stackCustomer(id)` → back arrow                                          |
| 8   | Change status inline       | status badge in row & peek       | one-click `BbSelectPopover` → undoable visit                                                   |
| 9   | Reschedule due date inline | due-date cell                    | `v-bb-date` directive on the cell button → undoable visit                                      |
| 10  | Record payment             | row `…`, peek button             | `BbDialog` via `ctx.dialogs` → promise-wrapped visit                                           |
| 11  | Edit / duplicate           | row `…` dropdown                 | navigation (`href`) / context action                                                           |
| 12  | Archive / delete           | row `…`, bulk bar                | destructive behind `useConfirm`                                                                |
| 13  | Bulk mark paid / remind    | floating bottom panel            | context actions on `table.selected`/`all`/`unselected`                                         |
| 14  | Select rows / select all   | table checkboxes                 | `useTableContext` selection (across pages)                                                     |
| 15  | Open full invoice          | invoice number cell, peek footer | navigation (`href="/invoices/:id"`)                                                            |
| 16  | Back / close peek          | shell chrome                     | shell stack pop / close                                                                        |

## The code

### context.ts

```ts
// InvoicesWorkspace/context.ts
import {
	computed,
	inject,
	provide,
	reactive,
	ref,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import { router } from '@inertiajs/vue3';
import type { RequestPayload } from '@inertiajs/core';
import { useConfirm, useToast } from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import {
	useTableContext,
	type TableContext,
} from '@/composables/useTableContext';
import { useQueryObject } from '@/composables/useQueryObject';
import { useProp } from '@/composables/useProp';
import { useQuery } from '@/composables/useQuery';
import type { Invoice, InvoiceStatus, PaymentDraft } from '@/types';

/**
 * What the stacked sidebar can show — a discriminated union of EVERY related
 * type the rows and the peeks expose, so one shell serves the whole consult.
 * `label` rides along because `#sidebar-title` has to name the top of the
 * stack before that record's own fetch has resolved.
 */
export type PeekItem =
	| { type: 'invoice'; id: number; label: string }
	| { type: 'customer'; id: number; label: string };

export type WorkspaceTab = 'all' | 'outstanding' | 'paid' | 'archived';

export interface InvoiceFilters {
	search: string;
	status: InvoiceStatus[];
	customerId: number | null;
	/**
	 * `[start, end]` ISO strings, or `[]` when unset. Range mode requires an
	 * array modelValue -- binding `null` throws, so the empty filter is `[]`.
	 */
	dueBetween: string[];
}

const RELOAD_PROPS = ['invoices', 'tabCounts'] as const;

export interface InvoicesWorkspaceContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	table: TableContext<Invoice, number>;
	// -- Page-owned state ------------------------------------------------------
	filters: InvoiceFilters;
	hasActiveFilters: ComputedRef<boolean>;
	tab: Ref<WorkspaceTab>;
	tabCounts: ComputedRef<Record<WorkspaceTab, number>>;
	dialogs: { recordPayment: Ref<Invoice | null> };
	/** Bumped after every mutation — peeks watch it to re-fetch their JSON detail. */
	refreshKey: Ref<number>;
	// -- Peek grammar ----------------------------------------------------------
	peekInvoice: (id: number) => void;
	stackInvoice: (id: number) => void;
	stackCustomer: (id: number) => void;
	// -- Actions (complete: visit + refresh + toast) -----------------------------
	clearFilters: () => void;
	updateStatus: (invoice: Invoice, status: InvoiceStatus) => Promise<void>;
	duplicateInvoice: (invoice: Invoice) => Promise<void>;
	recordPayment: (invoice: Invoice, draft: PaymentDraft) => Promise<void>;
	archiveInvoice: (invoice: Invoice) => Promise<void>;
	deleteInvoice: (invoice: Invoice) => Promise<void>;
	bulkMarkPaid: () => Promise<void>;
	bulkRemind: () => Promise<void>;
	bulkArchive: () => Promise<void>;
}

const key: InjectionKey<InvoicesWorkspaceContext> =
	Symbol('invoices-workspace');

/** Comma-joined query value → string[] (or null when absent). */
const toArray = (value: unknown): string[] | null => {
	if (value == null || value === '') return null;
	return Array.isArray(value) ? value.map(String) : String(value).split(',');
};

/** Inertia's callback-based visit, wrapped as a promise — so every context
 * action stays `async`, exactly like the Vue/Nuxt versions. Always a
 * partial reload of the props this page depends on. */
const visit = (
	method: 'post' | 'put' | 'patch' | 'delete',
	url: string,
	// Inertia's own payload type — strings/numbers/booleans/arrays/files.
	// (`Record<string, unknown>` does not satisfy it.)
	data: RequestPayload = {}
): Promise<void> =>
	new Promise((resolve, reject) => {
		router.visit(url, {
			method,
			data,
			only: [...RELOAD_PROPS],
			preserveScroll: true,
			preserveState: true,
			onSuccess: () => resolve(),
			onError: (errors) => reject(errors),
		});
	});

export function provideInvoicesWorkspace(): InvoicesWorkspaceContext {
	const { toast } = useToast();
	const { confirm } = useConfirm();

	// -- Coopt the specific contexts: once, here, for the whole page. ----------
	const shell = usePageShellContext<PeekItem>();
	// `Invoice, number`: BbTable's `item-value="id"` resolves selection to
	// invoice ids, matching the Vue/Nuxt `table.selected: number[]` shape.
	const table = useTableContext<Invoice, number>('invoices');

	// -- Filters: seeded from the current URL, mirrored back by useQueryObject. -
	const query = useQuery();
	const filters = reactive<InvoiceFilters>({
		search: (query.search as string) ?? '',
		status: (toArray(query.status) ?? []) as InvoiceStatus[],
		customerId: query.customerId ? Number(query.customerId) : null,
		dueBetween: toArray(query.dueBetween) ?? [],
	});
	useQueryObject(filters, { only: [...RELOAD_PROPS] });

	const hasActiveFilters = computed(
		() =>
			filters.search !== '' ||
			filters.status.length > 0 ||
			filters.customerId !== null ||
			filters.dueBetween.length > 0
	);
	const clearFilters = () => {
		filters.search = '';
		filters.status = [];
		filters.customerId = null;
		filters.dueBetween = [];
	};

	// Tab: seeded from the URL; BbTabs' own `href` + `server` visit updates
	// the URL, and its `v-model` write keeps this ref in sync with the click.
	const tab = ref<WorkspaceTab>((query.tab as WorkspaceTab) ?? 'all');
	const tabCounts = useProp<Record<WorkspaceTab, number>>('tabCounts');

	const refreshKey = ref(0);
	const dialogs = { recordPayment: ref<Invoice | null>(null) };

	// -- Peek grammar ----------------------------------------------------------------
	// peekX opens a fresh stack (from the list); stackX drills down (from a peek).
	// `peek` opens a fresh top-level peek (a row click); `stackItem` drills from
	// the open one, keeping the back arrow. Named intents beat `push(item, true)`,
	// whose boolean silently resets a stack you meant to drill into.
	const peekInvoice = (id: number, label: string) =>
		shell.peek({ type: 'invoice', id, label });
	const stackInvoice = (id: number, label: string) =>
		shell.stackItem({ type: 'invoice', id, label });
	const stackCustomer = (id: number, label: string) =>
		shell.stackItem({ type: 'customer', id, label });

	// -- Actions --------------------------------------------------------------------
	const refresh = () => {
		refreshKey.value++;
	};

	const updateStatus = async (invoice: Invoice, status: InvoiceStatus) => {
		await visit('patch', `/invoices/${invoice.id}`, { status });
		refresh();
		toast({
			title: `${invoice.number} moved to ${status}.`,
			variant: 'success',
		});
	};

	const duplicateInvoice = async (invoice: Invoice) => {
		await visit('post', `/invoices/${invoice.id}/duplicate`);
		refresh();
		toast({ title: `${invoice.number} duplicated.`, variant: 'success' });
	};

	const recordPayment = async (invoice: Invoice, draft: PaymentDraft) => {
		await visit('post', `/invoices/${invoice.id}/payments`, { ...draft });
		dialogs.recordPayment.value = null;
		refresh();
		toast({
			title: `Payment recorded on ${invoice.number}.`,
			variant: 'success',
		});
	};

	const archiveInvoice = async (invoice: Invoice) => {
		await visit('patch', `/invoices/${invoice.id}/archive`);
		refresh();
		toast({ title: `${invoice.number} archived.`, variant: 'success' });
	};

	const deleteInvoice = async (invoice: Invoice) => {
		const ok = await confirm({
			variant: 'destructive',
			title: 'Delete invoice',
			text: `Delete ${invoice.number}? This cannot be undone.`,
			yes: 'Delete',
			no: 'Cancel',
		});
		if (!ok) return;
		await visit('delete', `/invoices/${invoice.id}`);
		refresh();
		toast({ title: `${invoice.number} deleted.`, variant: 'success' });
	};

	// Bulk actions carry the full select-all-across-pages payload — the
	// server combines `all` + `unselected` the same way BbTable does.
	const bulkPayload = () => ({
		ids: table.selected.value,
		all: table.all.value,
		unselected: table.unselected.value,
	});
	const bulkCount = () =>
		table.all.value
			? table.totalItems.value - table.unselected.value.length
			: table.selected.value.length;

	const bulkMarkPaid = async () => {
		const count = bulkCount();
		await visit('patch', '/invoices/bulk/mark-paid', bulkPayload());
		table.resetSelection();
		toast({ title: `${count} invoices marked as paid.`, variant: 'success' });
	};

	const bulkRemind = async () => {
		const count = bulkCount();
		await visit('post', '/invoices/bulk/remind', bulkPayload());
		table.resetSelection();
		toast({
			title: `Reminder sent for ${count} invoices.`,
			variant: 'success',
		});
	};

	const bulkArchive = async () => {
		const count = bulkCount();
		const ok = await confirm({
			variant: 'destructive',
			title: 'Archive invoices',
			text: `Archive ${count} invoices? They move out of every tab except Archived.`,
			yes: 'Archive',
			no: 'Cancel',
		});
		if (!ok) return;
		await visit('patch', '/invoices/bulk/archive', bulkPayload());
		table.resetSelection();
		toast({ title: `${count} invoices archived.`, variant: 'success' });
	};

	const ctx: InvoicesWorkspaceContext = {
		shell,
		table,
		filters,
		hasActiveFilters,
		tab,
		tabCounts,
		dialogs,
		refreshKey,
		peekInvoice,
		stackInvoice,
		stackCustomer,
		clearFilters,
		updateStatus,
		duplicateInvoice,
		recordPayment,
		archiveInvoice,
		deleteInvoice,
		bulkMarkPaid,
		bulkRemind,
		bulkArchive,
	};
	provide(key, ctx);
	return ctx;
}

export function useInvoicesWorkspace(): InvoicesWorkspaceContext {
	const ctx = inject(key);
	if (!ctx)
		throw new Error('useInvoicesWorkspace() called outside InvoicesWorkspace');
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- InvoicesWorkspace/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left, page search + primary action right. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs
					class="min-w-0 flex-auto"
					:items="[
						{ key: 'dashboard', text: 'Dashboard', href: '/dashboard' },
						{ key: 'billing', text: 'Billing', href: '/billing' },
						{ key: 'invoices', text: 'Invoices' },
					]"
				/>
				<div class="flex shrink-0 items-center gap-2">
					<BbTextInput
						v-model="ctx.filters.search"
						autocomplete="off"
						hide-label
						label="Search invoices"
						clearable
						compact
						placeholder="Search number or customer…"
						prepend:icon="lucide:search"
					/>
					<BbButton
						href="/invoices/create"
						prepend:icon="lucide:plus"
						variant="primary"
					>
						New invoice
					</BbButton>
				</div>
			</div>
		</template>

		<div class="flex flex-col gap-3 p-4">
			<FilterRail />

			<!-- Tabs are real visits: href + server (component-level `navigation`
			     is required alongside per-item `server`), each carrying the same
			     partial-reload prop list as the filter watcher. `preserve-state`
			     keeps this page (and the tabs instance) alive across the visit so
			     the sliding pill animates to the new tab instead of the page
			     remounting and the pill snapping — matching the filter watcher,
			     which already visits with preserveState. Each href is built from
			     `tabHref()`, NOT a bare `?tab=` literal: `preserve-state` keeps
			     `ctx.filters` alive across the visit, so if the href dropped the
			     filter query keys the server would render an unfiltered page while
			     the (unchanged) filter chips kept claiming the old filters still
			     applied. -->
			<BbTabs
				v-model="ctx.tab.value"
				compact
				navigation
				preserve-scroll
				preserve-state
				replace
				:items="[
					{
						key: 'all',
						label: `All · ${ctx.tabCounts.value.all}`,
						href: tabHref('all'),
						server: true,
						only: ['invoices', 'tabCounts'],
					},
					{
						key: 'outstanding',
						label: `Outstanding · ${ctx.tabCounts.value.outstanding}`,
						href: tabHref('outstanding'),
						server: true,
						only: ['invoices', 'tabCounts'],
					},
					{
						key: 'paid',
						label: `Paid · ${ctx.tabCounts.value.paid}`,
						href: tabHref('paid'),
						server: true,
						only: ['invoices', 'tabCounts'],
					},
					{
						key: 'archived',
						label: `Archived · ${ctx.tabCounts.value.archived}`,
						href: tabHref('archived'),
						server: true,
						only: ['invoices', 'tabCounts'],
					},
				]"
			/>

			<!-- No dependencies/items-fn: `invoices` is a page prop, and selection
			     (across pages) binds straight onto the keyed table context. -->
			<BbTable
				v-model="ctx.table.selected.value"
				v-model:select-all="ctx.table.all.value"
				v-model:unselected-items="ctx.table.unselected.value"
				actions
				caption="Invoices"
				:columns="columns"
				compact
				item-value="id"
				:items="ctx.table.items.value"
				legend="Select invoices"
				loading-text="Loading invoices…"
				:row-class="rowClass"
				selectable
			>
				<!-- Clicking the NAME of a thing peeks it. `.plain-link`
				     (design-language.md § Guide helper) is the project-owned
				     inline-link class, not a BbButton variant: `link` keeps
				     button chrome and never flows/truncates like inline text
				     at cell width. -->
				<template #number="{ item, content }">
					<BbBaseButton
						class="plain-link"
						@click="() => ctx.peekInvoice(item.id, item.number)"
					>
						{{ content }}
					</BbBaseButton>
				</template>

				<template #customer_name="{ item, content }">
					<!-- A related name is an inline link, not a button: `BbButton`
					     (any variant) is padded and breaks the row's line-height. -->
					<BbBaseButton
						class="plain-link"
						@click="
							() => ctx.stackCustomer(item.customer.id, item.customer.name)
						"
					>
						{{ content }}
					</BbBaseButton>
				</template>

				<template #status="{ item }">
					<StatusCell :invoice="item" />
				</template>

				<template #actions="{ item }">
					<RowActions :invoice="item" />
				</template>

				<template #no-data>
					<div class="flex flex-col items-center gap-2 p-6 text-center">
						<p class="text-sm text-[color:var(--bb-text-muted)]">
							No invoices match
							{{
								ctx.hasActiveFilters.value ? 'the current filters' : 'this tab'
							}}.
						</p>
						<BbButton
							v-if="ctx.hasActiveFilters.value"
							variant="ghost"
							@click="ctx.clearFilters"
						>
							Clear filters
						</BbButton>
					</div>
				</template>
			</BbTable>

			<!-- No table-id: the keyed table context is the page count here. -->
			<BbPagination
				v-model="ctx.table.page.value"
				label="Invoices pagination"
				:total-pages="ctx.table.totalPages.value"
			/>
		</div>

		<SelectionBar />

		<!-- The peek names itself: without `#sidebar-title` the shell opens with
		     back/close flanking empty space, and the entity name ends up as a
		     second title inside the body. It follows the TOP of the stack, so a
		     drill-down renames the chrome. -->
		<template #sidebar-title>{{ ctx.shell.current.value?.label }}</template>

		<!-- Stacked peek sidebar: the shell owns back/close; we render by type. -->
		<template #sidebar>
			<InvoicePeek
				v-if="ctx.shell.current.value?.type === 'invoice'"
				:invoice-id="ctx.shell.current.value.id"
			/>
			<CustomerPeek
				v-else-if="ctx.shell.current.value?.type === 'customer'"
				:customer-id="ctx.shell.current.value.id"
			/>
		</template>

		<template #dialogs>
			<RecordPaymentDialog />
		</template>
	</PageShell>
</template>

<script setup lang="ts">
import {
	BbBaseButton,
	BbBreadcrumbs,
	BbButton,
	BbPagination,
	BbTable,
	BbTabs,
	BbTextInput,
} from 'bitboss-ui';
import qs from 'query-string';
import PageShell from '@/components/layout/PageShell.vue';
import { useQuery } from '@/composables/useQuery';
import { provideInvoicesWorkspace, type WorkspaceTab } from './context';
import CustomerPeek from './CustomerPeek.vue';
import FilterRail from './FilterRail.vue';
import InvoicePeek from './InvoicePeek.vue';
import RecordPaymentDialog from './RecordPaymentDialog.vue';
import RowActions from './RowActions.vue';
import SelectionBar from './SelectionBar.vue';
import StatusCell from './StatusCell.vue';
import type { Invoice } from '@/types';

const ctx = provideInvoicesWorkspace();

// Merge `tab` into the *current* query instead of replacing it: `useQuery()`
// reads the live URL, which already carries every filter `useQueryObject`
// mirrored there, so switching tabs keeps `search`/`status`/`customerId`/
// `dueBetween` intact instead of silently resetting the results to unfiltered.
const tabHref = (tab: WorkspaceTab): string =>
	`/invoices?${qs.stringify({ ...useQuery(), tab }, { arrayFormat: 'comma' })}`;

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
const shortDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
	});

const columns = [
	{ key: 'number', label: 'Invoice' },
	{ key: 'customer.name', label: 'Customer' },
	{
		key: 'amount',
		label: 'Amount',
		formatter: (value: number) => currency.format(value),
	},
	{ key: 'status', label: 'Status' },
	{ key: 'dueDate', label: 'Due', formatter: shortDate },
	{ key: 'issuedAt', label: 'Issued', formatter: shortDate },
];

// Overdue rows get a tinted background — public row-class API, no internals.
const rowClass = (item: Invoice) =>
	item.status === 'overdue' ? 'bg-red-50 dark:bg-red-950/20' : undefined;
</script>
```

### FilterRail.vue

```vue
<!-- InvoicesWorkspace/FilterRail.vue -->
<template>
	<div class="flex flex-wrap items-center gap-2">
		<!-- One Filters menu: nested category → selectable/searchable group.
		     Never one BbSelectPopover pill per facet — that component has no
		     `defineExpose`, so a chip can't `ref.open()` it, and its floating
		     mode auto-closes an off-screen/`sr-only` activator on open. -->
		<BbDropdown id="invoice-filters" :items="menu" :width="220">
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filters"
					prepend:icon="lucide:list-filter"
					size="sm"
					variant="outline"
				>
					Filters
				</BbButton>
			</template>
			<BbDropdownGroup id="status" v-model="ctx.filters.status" />
			<BbDropdownGroup id="customer" v-model="ctx.filters.customerId" />
		</BbDropdown>

		<!-- One chip per APPLIED facet — never one per value. See
		     FilterChip.vue: each chip is itself a small dropdown scoped to the
		     same group, reusing the exact descriptor declared below. -->
		<FilterChip
			v-if="ctx.filters.status.length"
			:group="statusGroup"
			group-key="status"
			label="Status"
			:model-value="ctx.filters.status"
			@update:model-value="
				(value) => (ctx.filters.status = value as InvoiceStatus[])
			"
		/>
		<FilterChip
			v-if="ctx.filters.customerId != null"
			:group="customerGroup"
			group-key="customer"
			label="Customer"
			:model-value="ctx.filters.customerId"
			@update:model-value="
				(value) => (ctx.filters.customerId = value as number | null)
			"
		/>

		<!-- Due date is a free-form range, not a discrete facet — its own
		     compact pill outside the Filters menu, no chip. A compact input
		     is 28px — flush with the sm Filters button's row. -->
		<BbDatePickerInput
			v-model="ctx.filters.dueBetween"
			hide-label
			label="Due date range"
			clearable
			compact
			placeholder="Due between…"
			range
		/>

		<!-- Clear-all is the LAST CHIP, not a ghost button floated to the far
		     end by `ml-auto`: it acts on the chips, so it belongs in their row
		     and at their scale. Keep the ghost "Clear filters" for the empty
		     state (`#no-data`), where there are no chips to sit beside. -->
		<BbBadge
			v-if="ctx.hasActiveFilters.value"
			clearable
			:clearable-label="`Clear all filters`"
			size="xl"
			variant="outline"
			@click:clear="ctx.clearFilters"
		>
			Clear all
		</BbBadge>
	</div>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import {
	BbBadge,
	BbButton,
	BbDatePickerInput,
	BbDropdown,
	BbDropdownGroup,
} from 'bitboss-ui';
import type { BbDropdownItem } from 'bitboss-ui';
import { useInvoicesWorkspace } from './context';
import FilterChip from './FilterChip.vue';
import type { Customer, InvoiceStatus } from '@/types';

const ctx = useInvoicesWorkspace();

// Query-aware pipeline getter: called with the typed query because the group
// below sets `searchable: true` (same `(query, prefill, modelValue)` shape a
// BbSelect provider uses). A small JSON endpoint, not an Inertia visit —
// searching a filter facet must not re-render the page.
const searchCustomers = (query: string): Promise<Customer[]> =>
	fetch(`/customers/search?q=${encodeURIComponent(query)}`).then((res) =>
		res.json()
	);

// Static enum facet: item text resolves synchronously, so its chip reads
// `useBbDropdownContext` (in FilterChip.vue) with zero extra fetch.
const statusGroup: BbDropdownItem = {
	key: 'status',
	label: 'Status',
	hideLabel: true,
	selectable: true,
	multiple: true,
	items: [
		{ key: 'draft', text: 'Draft' },
		{ key: 'pending', text: 'Pending' },
		{ key: 'paid', text: 'Paid' },
		{ key: 'overdue', text: 'Overdue' },
	],
};

// Pipeline facet: `prefill: true` resolves a picked customer's name eagerly,
// so a chip never sits on a bare id while this group's own submenu (inside
// the Filters menu) has never been opened. The eager flag belongs HERE, on
// the menu's copy only — the chip derives its own copy with
// `prefill: 'interaction'` (see FilterChip.vue), because a second dropdown
// redeclaring `prefill: true` would fetch every seeded facet twice on page
// load for nothing.
const customerGroup: BbDropdownItem = {
	key: 'customer',
	label: 'Customer',
	hideLabel: true,
	selectable: true,
	searchable: true,
	prefill: true,
	itemText: 'name',
	itemValue: 'id',
	items: searchCustomers,
};

// Top-level items are submenu openers; each nests exactly one selectable
// group ("nested category › searchable options" — BbDropdown.md § Nested
// submenus). `hideLabel` on the group skips a redundant inner heading since
// the category row already names the facet.
const menu = computed<BbDropdownItem[]>(() => [
	{
		key: 'status-category',
		text: 'Status',
		'prepend:icon': 'lucide:circle-dot',
		items: [statusGroup],
	},
	{
		key: 'customer-category',
		text: 'Customer',
		'prepend:icon': 'lucide:building-2',
		items: [customerGroup],
	},
]);
</script>
```

### FilterChip.vue

```vue
<!-- InvoicesWorkspace/FilterChip.vue -->
<template>
	<BbBadge
		clearable
		:clearable-label="`Remove ${label} filter`"
		size="xl"
		variant="secondary"
		@click:clear="onClear"
	>
		<BbBadgeButton ref="chipRef">{{ chipText }}</BbBadgeButton>
	</BbBadge>
	<!-- External `activator` (a template ref) — NEVER the `#activator` slot: a
	     component sitting between `BbBadge` and `BbBadgeButton` breaks the
	     badge's direct-child vnode scan (the companion must be a literal
	     child). This IS "the chip is itself a dropdown onto the same filter
	     group": `chipGroup` is derived from the exact descriptor FilterRail
	     declared (spread, one override — never redeclared), so this scoped
	     picker and the Filters menu's own submenu can never drift apart. -->
	<BbDropdown :activator="chipRef" :items="[chipGroup]" :width="220">
		<BbDropdownGroup
			:id="groupKey"
			:model-value="modelValue"
			@update:model-value="emit('update:modelValue', $event)"
		/>
	</BbDropdown>
</template>

<script setup lang="ts">
import { computed, useTemplateRef } from 'vue';
import {
	BbBadge,
	BbBadgeButton,
	BbDropdown,
	BbDropdownGroup,
	useBbDropdownContext,
} from 'bitboss-ui';
import type { BbDropdownItem } from 'bitboss-ui';

const props = defineProps<{
	/** Matches the group's `key` in the Filters menu, and its key in
	 * `useBbDropdownContext('invoice-filters').groups`. */
	groupKey: string;
	/** Static fallback/prefix text — the group itself sets `hideLabel`. */
	label: string;
	/** The SAME group descriptor passed to the Filters menu — not redeclared. */
	group: BbDropdownItem;
	modelValue: unknown;
}>();
const emit = defineEmits<{ 'update:modelValue': [value: unknown] }>();

const chipRef = useTemplateRef('chipRef');

// The chip's own copy of the shared descriptor, one override: `prefill:
// 'interaction'`. BbDropdown mounts a pipeline resolver for every group it
// declares at its own root, independent of the panel ever opening — so if
// this second dropdown repeated the menu's `prefill: true` verbatim, each
// seeded pipeline facet would be fetched TWICE on page load, and the chip's
// copy of the result would feed nothing (the label below comes from the
// menu's resolution via context). `'interaction'` defers this copy's fetch
// to the moment the chip's dropdown is actually opened. For static array
// facets the override is inert — arrays resolve synchronously either way.
const chipGroup = computed<BbDropdownItem>(() => ({
	...props.group,
	prefill: 'interaction',
}));

// Reads the Filters menu's already-resolved selection — no twin fetch. A
// pipeline group needs `prefill: true` (set on the MENU's copy of `group` by
// FilterRail) so this never sits on a bare id/value while the menu's own
// submenu is unopened.
const dropdownFilters = useBbDropdownContext('invoice-filters');
const chipText = computed(() => {
	const options =
		dropdownFilters.groups.value[props.groupKey]?.selectedOptions ?? [];
	if (!options.length) return props.label;
	return `${props.label}: ${options
		.map((option) => option.text ?? String(option.value))
		.join(', ')}`;
});

const onClear = () =>
	emit('update:modelValue', Array.isArray(props.modelValue) ? [] : null);
</script>
```

### StatusCell.vue

```vue
<!-- InvoicesWorkspace/StatusCell.vue -->
<template>
	<BbSelectPopover
		:items="['draft', 'pending', 'paid', 'overdue']"
		:model-value="invoice.status"
		width="180"
		@update:model-value="(status) => pick(status as InvoiceStatus)"
	>
		<template #activator="{ props: activatorProps }">
			<!-- The badge IS the trigger: BbBadgeButton turns the badge's own
			body into the button, so the pill is the hit target and draws its
			own focus ring — no wrapper element, no chrome class. The internal
			trailing chevron says "clickable"; while the save runs the badge's
			`loading` swaps the spinner into the chevron's place (§6.1
			niceties). -->
			<BbBadge
				append:icon="lucide:chevron-down"
				:loading="saving"
				variant="outline"
			>
				<BbBadgeButton
					:aria-label="`Change status for invoice ${invoice.number}`"
					v-bind="activatorProps"
					>{{ invoice.status }}</BbBadgeButton
				>
			</BbBadge>
		</template>
	</BbSelectPopover>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
import { useInvoicesWorkspace } from './context';
import type { Invoice, InvoiceStatus } from '@/types';

const props = defineProps<{ invoice: Invoice }>();

const ctx = useInvoicesWorkspace();

// In-flight flag for the save feedback — rung-1 local state, not context.
const saving = ref(false);
const pick = async (status: InvoiceStatus) => {
	saving.value = true;
	try {
		await ctx.updateStatus(props.invoice, status);
	} finally {
		saving.value = false;
	}
};
</script>
```

### RowActions.vue

```vue
<!-- InvoicesWorkspace/RowActions.vue -->
<template>
	<BbDropdown
		:items="[
			{
				key: 'edit',
				text: 'Edit',
				'prepend:icon': 'lucide:pencil',
				href: `/invoices/${invoice.id}/edit`,
			},
			{
				key: 'duplicate',
				text: 'Duplicate',
				'prepend:icon': 'lucide:copy',
				onClick: () => ctx.duplicateInvoice(invoice),
			},
			{
				key: 'payment',
				text: 'Record payment',
				'prepend:icon': 'lucide:banknote',
				onClick: () => (ctx.dialogs.recordPayment.value = invoice),
			},
			{
				key: 'archive',
				text: 'Archive',
				'prepend:icon': 'lucide:archive',
				onClick: () => ctx.archiveInvoice(invoice),
			},
			{
				key: 'delete',
				text: 'Delete',
				'prepend:icon': 'lucide:trash-2',
				variant: 'destructive',
				onClick: () => ctx.deleteInvoice(invoice),
			},
		]"
	>
		<template #activator="{ props }">
			<BbButton v-bind="props" icon="lucide:ellipsis" size="sm" variant="ghost">
				Invoice actions
			</BbButton>
		</template>
	</BbDropdown>
</template>

<script setup lang="ts">
import { BbButton, BbDropdown } from 'bitboss-ui';
import { useInvoicesWorkspace } from './context';
import type { Invoice } from '@/types';

defineProps<{ invoice: Invoice }>();

const ctx = useInvoicesWorkspace();
</script>
```

### SelectionBar.vue

```vue
<!-- InvoicesWorkspace/SelectionBar.vue -->
<template>
	<FloatingBottomPanel :open="selectedCount > 0">
		<span class="px-2 text-sm">{{ selectedCount }} selected</span>
		<BbButton
			prepend:icon="lucide:check"
			size="sm"
			variant="ghost"
			@click="ctx.bulkMarkPaid"
		>
			Mark as paid
		</BbButton>
		<BbButton
			prepend:icon="lucide:send"
			size="sm"
			variant="ghost"
			@click="ctx.bulkRemind"
		>
			Send reminder
		</BbButton>
		<div class="floating-bottom-panel__right flex items-center gap-1">
			<BbButton size="sm" variant="destructive" @click="ctx.bulkArchive"
				>Archive</BbButton
			>
			<BbButton
				aria-label="Clear selection"
				icon="lucide:x"
				size="sm"
				variant="ghost"
				@click="ctx.table.resetSelection"
			/>
		</div>
	</FloatingBottomPanel>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton } from 'bitboss-ui';
import { useInvoicesWorkspace } from './context';
import FloatingBottomPanel from '@/components/layout/FloatingBottomPanel.vue';

const ctx = useInvoicesWorkspace();

// `all` (select-all-across-pages) does not enumerate rows, so the visible
// count is the total minus whatever the user manually deselected.
const selectedCount = computed(() =>
	ctx.table.all.value
		? ctx.table.totalItems.value - ctx.table.unselected.value.length
		: ctx.table.selected.value.length
);
</script>
```

### InvoicePeek.vue

```vue
<!-- InvoicesWorkspace/InvoicePeek.vue -->
<template>
	<div v-if="invoice" class="flex flex-col gap-4 text-sm">
		<!-- Header: identity + one-click status + amount. -->
		<header class="flex flex-col gap-1.5">
			<div class="flex items-center justify-between gap-2">
				<h2 class="text-base font-semibold">{{ invoice.number }}</h2>
				<StatusCell :invoice="invoice" />
			</div>
			<p class="text-xl font-semibold">{{ currency.format(invoice.amount) }}</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Issued {{ longDate(invoice.issuedAt) }} · due
				{{ longDate(invoice.dueDate) }}
			</p>
		</header>

		<!-- Properties: customer name drills DOWN — stacked peek, back arrow.
		     `.plain-link` (design-language.md § Guide helper), not a BbButton
		     variant — a property-grid value is inline text, not a button. -->
		<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
			<dt class="text-[color:var(--bb-text-muted)]">Customer</dt>
			<dd>
				<BbBaseButton
					class="plain-link"
					@click="
						() =>
							ctx.stackCustomer(invoice!.customer.id, invoice!.customer.name)
					"
				>
					{{ invoice.customer.name }}
				</BbBaseButton>
			</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Project</dt>
			<dd>{{ invoice.project.name }}</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Payment terms</dt>
			<dd>{{ invoice.paymentTerms }}</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Reference</dt>
			<dd>{{ invoice.reference }}</dd>
		</dl>

		<!-- Line items: a real mini-table, not a summary sentence. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Line items
			</h3>
			<BbTable
				caption="Invoice line items"
				:columns="[
					{ key: 'description', label: 'Description' },
					{ key: 'quantity', label: 'Qty' },
					{
						key: 'total',
						label: 'Total',
						formatter: (value: number) => currency.format(value),
					},
				]"
				compact
				item-value="id"
				:items="invoice.lineItems"
			/>
		</section>

		<!-- Payments so far. -->
		<section v-if="invoice.payments.length" class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Payments
			</h3>
			<ul class="flex flex-col gap-1">
				<li
					v-for="payment in invoice.payments"
					:key="payment.id"
					class="flex items-center justify-between gap-2"
				>
					<span
						>{{ currency.format(payment.amount) }} · {{ payment.method }}</span
					>
					<span class="text-xs text-[color:var(--bb-text-muted)]">{{
						longDate(payment.paidAt)
					}}</span>
				</li>
			</ul>
		</section>

		<!-- Activity feed. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Activity
			</h3>
			<ul class="flex flex-col gap-2">
				<li
					v-for="entry in invoice.activity"
					:key="entry.id"
					class="flex gap-2"
				>
					<BbIcon
						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
						:icon="entry.icon"
						size="14"
					/>
					<div class="flex flex-col">
						<span>{{ entry.text }}</span>
						<span class="text-xs text-[color:var(--bb-text-muted)]"
							>{{ entry.actor }} · {{ longDate(entry.at) }}</span
						>
					</div>
				</li>
			</ul>
		</section>

		<!-- Peek is a workbench: act here, or leave for the full page. -->
		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				prepend:icon="lucide:banknote"
				size="sm"
				variant="secondary"
				@click="() => (ctx.dialogs.recordPayment.value = invoice)"
			>
				Record payment
			</BbButton>
			<BbButton
				append:icon="lucide:arrow-up-right"
				:href="`/invoices/${invoice.id}`"
				size="sm"
				variant="ghost"
			>
				Open full page
			</BbButton>
		</footer>
	</div>

	<!-- `data === null` means EITHER "not loaded yet" OR "failed" — a peek
	     needs a third state, or a 403/404 renders this spinner forever. -->
	<div
		v-else-if="loadFailed"
		class="flex flex-col items-center gap-2 p-8 text-center"
	>
		<p class="text-sm text-[color:var(--bb-text-muted)]">
			Couldn't load this invoice.
		</p>
		<BbButton size="sm" variant="ghost" @click="refresh">Retry</BbButton>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue';
import { BbBaseButton, BbButton, BbIcon, BbSpinner, BbTable } from 'bitboss-ui';
import { useResourceContext } from '@/composables/useResourceContext';
import StatusCell from './StatusCell.vue';
import { useInvoicesWorkspace } from './context';
import type { InvoiceDetail } from '@/types';

const props = defineProps<{ invoiceId: number }>();

const ctx = useInvoicesWorkspace();

// A small JSON endpoint, not a page visit — opening the peek never
// re-renders the list underneath it. Re-fetches whenever the stack shows a
// different invoice; `refreshKey` makes mutations (status, payment) reflect
// here immediately.
const loadFailed = ref(false);
const { data: invoice, refresh } = useResourceContext<InvoiceDetail, number>(
	() => props.invoiceId,
	async (id) => {
		// `fetch` never rejects on a 403/404 — check `res.ok` and throw, or a
		// failed peek is indistinguishable from one still loading.
		const res = await fetch(`/invoices/${id}/peek`);
		if (!res.ok) throw new Error(`Failed to load invoice ${id}: ${res.status}`);
		return res.json();
	},
	{
		onSuccess: () => {
			loadFailed.value = false;
		},
		onError: () => {
			loadFailed.value = true;
		},
	}
);
watch(() => ctx.refreshKey.value, refresh);

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
const longDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
		year: 'numeric',
	});
</script>
```

### CustomerPeek.vue

```vue
<!-- InvoicesWorkspace/CustomerPeek.vue -->
<template>
	<div v-if="customer" class="flex flex-col gap-4 text-sm">
		<header class="flex items-center gap-3">
			<BbAvatar :alt="customer.name" :src="customer.avatarUrl" />
			<div class="flex flex-col">
				<h2 class="text-base font-semibold">{{ customer.name }}</h2>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					{{ customer.email }} · {{ customer.country }}
				</p>
			</div>
		</header>

		<!-- Stat strip. -->
		<div class="grid grid-cols-3 gap-2">
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Total billed</p>
				<p class="font-semibold">{{ currency.format(customer.totalBilled) }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Outstanding</p>
				<p class="font-semibold">{{ currency.format(customer.outstanding) }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Invoices</p>
				<p class="font-semibold">{{ customer.invoiceCount }}</p>
			</div>
		</div>

		<!-- Recent invoices: names drill down again — the stack keeps growing.
		     `.plain-link` (design-language.md § Guide helper), not a BbButton
		     variant — same identity-cell rule as the invoices table. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Recent invoices
			</h3>
			<ul class="flex flex-col">
				<li
					v-for="recent in customer.recentInvoices"
					:key="recent.id"
					class="flex items-center justify-between gap-2 border-b py-1.5 last:border-b-0"
				>
					<BbBaseButton
						class="plain-link"
						@click="() => ctx.stackInvoice(recent.id, recent.number)"
					>
						{{ recent.number }}
					</BbBaseButton>
					<BbBadge variant="outline">{{ recent.status }}</BbBadge>
					<span class="text-xs text-[color:var(--bb-text-muted)]">{{
						currency.format(recent.amount)
					}}</span>
				</li>
			</ul>
		</section>

		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				append:icon="lucide:arrow-up-right"
				:href="`/customers/${customer.id}`"
				size="sm"
				variant="ghost"
			>
				Open customer
			</BbButton>
		</footer>
	</div>

	<!-- Same third state as InvoicePeek: `data === null` alone can't tell
	     "loading" from "failed". -->
	<div
		v-else-if="loadFailed"
		class="flex flex-col items-center gap-2 p-8 text-center"
	>
		<p class="text-sm text-[color:var(--bb-text-muted)]">
			Couldn't load this customer.
		</p>
		<BbButton size="sm" variant="ghost" @click="refresh">Retry</BbButton>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import {
	BbAvatar,
	BbBadge,
	BbBaseButton,
	BbButton,
	BbSpinner,
} from 'bitboss-ui';
import { useResourceContext } from '@/composables/useResourceContext';
import { useInvoicesWorkspace } from './context';
import type { CustomerDetail } from '@/types';

const props = defineProps<{ customerId: number }>();

const ctx = useInvoicesWorkspace();

const loadFailed = ref(false);
const { data: customer, refresh } = useResourceContext<CustomerDetail, number>(
	() => props.customerId,
	async (id) => {
		const res = await fetch(`/customers/${id}/peek`);
		if (!res.ok)
			throw new Error(`Failed to load customer ${id}: ${res.status}`);
		return res.json();
	},
	{
		onSuccess: () => {
			loadFailed.value = false;
		},
		onError: () => {
			loadFailed.value = true;
		},
	}
);

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
</script>
```

### RecordPaymentDialog.vue

```vue
<!-- InvoicesWorkspace/RecordPaymentDialog.vue -->
<template>
	<BbDialog
		:model-value="invoice !== null"
		size="sm"
		:title="invoice ? `Record payment — ${invoice.number}` : ''"
		@update:model-value="close"
	>
		<form
			v-if="invoice"
			class="flex flex-col gap-3"
			novalidate
			@submit.prevent="submit"
		>
			<BbNumberInput
				v-model="draft.amount"
				label="Amount"
				label-mode="outside"
				:max-precision="2"
				:min="0"
			>
				<template #prefix>$</template>
			</BbNumberInput>
			<BbDatePickerInput
				v-model="draft.paidAt"
				label="Paid on"
				label-mode="outside"
			/>
			<BbSelect
				v-model="draft.method"
				:items="['bank transfer', 'card', 'check', 'cash']"
				label="Method"
				label-mode="outside"
			/>
			<div class="mt-1 flex justify-end gap-2">
				<BbButton type="button" variant="ghost" @click="close">Cancel</BbButton>
				<BbButton type="submit" variant="secondary">Record payment</BbButton>
			</div>
		</form>
	</BbDialog>
</template>

<script setup lang="ts">
import { computed, reactive, watch } from 'vue';
import {
	BbButton,
	BbDatePickerInput,
	BbDialog,
	BbNumberInput,
	BbSelect,
} from 'bitboss-ui';
import { useInvoicesWorkspace } from './context';
import type { PaymentDraft } from '@/types';

const ctx = useInvoicesWorkspace();

// The dialog's subject lives in the page context — any component on the
// page (row actions, the peek) can open it by assigning the invoice.
const invoice = computed(() => ctx.dialogs.recordPayment.value);
const close = () => {
	ctx.dialogs.recordPayment.value = null;
};

const draft = reactive<PaymentDraft>({
	amount: null,
	paidAt: null,
	method: null,
});
watch(invoice, (next) => {
	// Re-seed per invoice: default to paying the remaining balance today.
	draft.amount = next?.amountDue ?? null;
	draft.paidAt = next ? new Date().toISOString() : null;
	draft.method = null;
});

// Returning the promise lets the submit button track the async work.
const submit = () =>
	invoice.value ? ctx.recordPayment(invoice.value, { ...draft }) : undefined;
</script>
```

## Why it is built this way

- **The context coopts, leaves consume.** `shell` and the keyed
  `useTableContext('invoices')` are joined once in
  `provideInvoicesWorkspace()`; nine components share filters, selection,
  the peek stack and every action through one `useInvoicesWorkspace()`
  call. No component on this page receives a callback prop, and only
  peeks/cells receive data props (the item or id they render).
- **`invoices` is a page prop, not a client fetch.** `useTableContext`
  turns the Laravel paginator into `items`/`totalItems`/`page`/`perPage`
  (URL-backed) plus `selected`/`unselected`/`all`; `BbTable` binds directly
  to that handle with `v-model`/`v-model:select-all`/`v-model:unselected-items`
  — there is no items function and no `dependencies` array, because the
  server already did the filtering, sorting and paging before the props
  arrived.
- **One watcher for filters, one visit mechanism for tabs.**
  `useQueryObject(filters, { only: ['invoices', 'tabCounts'] })` is the
  entire filter-to-URL wiring; `BbTabs`' `href` + `server: true` items (with
  the required component-level `navigation`) make tab switches real,
  partial-reloaded visits with the same `only` list — one source of
  server truth, reached two ways. Each `href` is built by `tabHref()`, which
  merges `tab` into the current query rather than replacing it — `href:
'/invoices?tab=all'` alone would drop every active filter, and because
  `preserve-state` keeps this page instance (and `ctx.filters`) alive across
  the visit, the chips would keep showing the old filters as active over an
  unfiltered result set.
- **The `visit()` helper is the promise-wrapped router-visit pattern** the
  base's adaptation notes call for: it turns Inertia's
  `onSuccess`/`onError` callbacks into a promise so every context action
  (`updateStatus`, `duplicateInvoice`, the bulk actions, …) stays an
  `async function` — identical call sites to the Vue/Nuxt recipes,
  `await ctx.updateStatus(...)`.
- **Bulk actions carry the full select-all-across-pages payload**
  (`ids`/`all`/`unselected`) so "select all, deselect three, archive" sends
  the same semantics the table itself models — never just an enumerated id
  list that silently drops rows outside the current page.
- **Peeks are JSON fetches, not visits.** `useResourceContext` re-fetches
  on id change and exposes a `refresh()` the peek re-runs whenever
  `ctx.refreshKey` bumps (every mutation bumps it) — opening or updating a
  peek never re-renders the list page underneath it.
- **`peekX` vs `stackX` is the whole stack grammar.** Fresh peeks replace,
  drill-downs push; the shell renders the back arrow when depth > 1. The
  grammar lives in the context — a leaf cannot accidentally nuke the
  stack.
- **Dialogs hang off the context** (`ctx.dialogs.recordPayment` holds the
  subject invoice, not a boolean) so row actions and the peek open the
  same dialog with zero coordination.
- **Sizing:** topbar and rail follow `md`-first (`compact` inputs at 28px
  flush beside the default buttons); `sm` appears exactly where the
  doctrine allows — row actions, pills, peek footers, the bulk bar.
- **One `variant="primary"`** (New invoice). Destructive actions —
  single, bulk, in-peek — all ride `useConfirm`.
- **The status badge tells you it saves.** `StatusCell` carries the §6.1
  niceties: an internal trailing chevron (a clickable status must say so)
  and `:loading` around the awaited context action, so the spinner takes
  the chevron's place while the save runs. The flag is a local `ref` —
  rung 1, not context state. The ownership grammar behind inline edits is
  the [Inline Edit Playbook](../../guides/inline-edit-playbook.md).

## Variations

- **Keyboard triage**: add `keyboard-navigation` to the table and open the
  peek from `v-model:highlighted` — the approvals-inbox recipe is the
  full treatment.
- **Saved views**: persist `filters` + `tab` per user in a store
  (`useSavedViewsStore`) and render a view switcher before the tabs.
- **Inline amount editing**: swap the amount cell for an
  `EditableAmountCell` per the inline-editing pattern. Choosing between
  explicit-commit cells and a fully autosaving grid is the
  [Inline Edit Playbook](../../guides/inline-edit-playbook.md); the
  autosave treatment is the inline-edit-workspace recipe.
- **Lazy tab counts**: if `tabCounts` is expensive to compute, share it as
  `Inertia::lazy()` and read it with `useLazyProp` instead of a plain
  prop — the tab labels resolve once it lands instead of blocking the
  first render.

### Tabs are lifecycle; chips are facets

The rail and the tab strip answer two different questions, and twinning them is
the fastest way to make a workspace feel arbitrary:

- **Tabs = one lifecycle segment.** Where the record _is_ in its own flow —
  All / Outstanding / Paid / Archived. Mutually exclusive, always visible,
  carrying the counts.
- **Chips = cross-cutting facets.** Anything that can apply to a record in any
  segment — customer, owner, due date, tag. Additive, and only rendered while
  applied.

Never expose the same dimension both ways: a `status` facet inside the Filters
menu next to a status tab strip lets the user set two conflicting answers to one
question, and neither control shows the other's state. If a dimension deserves
both roles (a lifecycle you also want to combine), pick one and give the other
distinct chrome — never the same values with different affordances.

**Rail anatomy** — one row, one scale:

| Slot                    | What                                                    |
| ----------------------- | ------------------------------------------------------- |
| `.filter-rail`          | the row itself: Filters trigger, chips, free-form pills |
| Filters trigger         | one `BbDropdown` of the _unapplied_ facets              |
| `.filter-rail__applied` | one chip per **applied facet** — never one per value    |
| free-form controls      | ranges (dates, amounts) that are not discrete facets    |
| clear-all               | the last chip in the row, same scale as the others      |

Sizes come from the pairing table in [BbBadge](../../BbBadge.md): the trigger
here is a `sm` button, so every chip in the row is `xl`.

## Conformance — a listing is done when

Peek, highlight and title are one feature; shipping two of the three leaves a
dead affordance behind. Before calling a records screen finished:

- [ ] **`v-model:highlighted` is wired both ways** — closing the peek clears
      the highlight, or the same row cannot reopen it (see the Layout
      Scaffold's sync section).
- [ ] **`#sidebar-title` is filled**, or the peek opens with back/close
      flanking empty space.
- [ ] **`#sidebar` renders every `PeekItem` branch** the union declares.
- [ ] **Related names stack** — `BbBaseButton` + `.plain-link` calling
      `stackItem`, never a padded `BbButton`, and never dead text.
- [ ] **The row highlight follows the root of the stack**, so drilling
      invoice → customer does not un-highlight the row the consult began on.

If a page genuinely has no peek, delete the shell wiring rather than leaving
`v-model:highlighted` painting rows that open nothing.

---

<!-- dist/ai/recipes/inertia/upload-center.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/inertia/upload-center.md -->

# Recipe: Upload Center (Inertia)

The Expensify-grade expense receipts submission page adapted for **Laravel +
Inertia**: the same multi-file dropzone feeding an inline-editable table,
per-file upload progress with inline retry, one-click category cells, bulk
actions in the floating bottom panel, and a stacked receipt/merchant peek
sidebar — but the drafts page is a page prop, filters mirror into the URL
through [`useQueryObject`](../../guides/inertia-helpers.md), selection and
paging come from the keyed [`useTableContext`](../../guides/inertia-helpers.md),
and field edits/submit/bulk actions are promise-wrapped `router.visit`
calls. The raw file transfer itself stays outside Inertia entirely — visits
cannot stream per-file progress for a background queue — so uploads keep a
direct `fetch`/XHR path (not axios — a modern Inertia install doesn't ship
it; use it only if your app already has it as a dependency) and finish with
a partial reload. **Because the transfer leaves Inertia's request pipeline,
it also leaves Inertia's automatic CSRF handling behind:** read the
`XSRF-TOKEN` cookie yourself and echo it back as the `X-XSRF-TOKEN` request
header, or every upload 419s. Anatomy, components, the context shape, copy
and data are identical to the Vue recipe; only the data/URL/mutation layer
changes.

Sibling recipes: [Vue](../vue/upload-center.md) ·
[Nuxt](../nuxt/upload-center.md).

## Prerequisites

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell`, `usePageShellContext` and `FloatingBottomPanel` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
- `<BbConfirm />` and `<BbToast />` mounted once in the `createInertiaApp` render root — never in a page.
- From the [Inertia Helpers](../../guides/inertia-helpers.md) toolkit:
  `useTableContext`, `useQueryObject`, `useResourceContext`.
- A `useCategoriesStore()` Pinia store exposing the shared expense-category
  catalog (Travel, Meals & entertainment, Lodging, Rideshare & transit,
  Software & subscriptions, Office supplies, Fuel, Client entertainment).
- The registered `soft-*` badge variants (`soft-gray` / `soft-amber` /
  `soft-green`) from the [Inline Edit Workspace](./inline-edit-workspace.md)
  recipe — the receipt-status maps in `context.ts` use them
  (design-language § Using color).
- Controller: `Inertia::render('Receipts/Index', ['receipts' =>
ReceiptPaginator::make(...), 'tabCounts' => [...], 'readyCount' => ...])` —
  `receipts` is a standard Laravel paginator (`PaginatedResponse<Receipt>`),
  `tabCounts` a plain `{ drafts, submitted, reimbursed }` map, `readyCount`
  the number of drafts complete enough to submit. All three are re-sent on
  every partial reload the page triggers
  (`only: ['receipts', 'tabCounts', 'readyCount']`). Mutation routes are
  plain Laravel routes (`PATCH /receipts/:id`, `POST /receipts/:id/submit`,
  …) that redirect back; small JSON GET endpoints (`GET /receipts/:id/peek`,
  `GET /merchants/:name/peek`, `GET /merchants/search`) back the sidebar
  peeks and the merchant filter so opening one is not a full-page visit.
  `POST /receipts/upload` accepts a single `multipart/form-data` file and is
  hit directly (not through Inertia) so the client can read upload progress.
  Because that request bypasses Inertia, it also bypasses Inertia's automatic
  CSRF handling: `api.receipts.upload()` (your own `@/api`, not part of this
  toolkit) must read the `XSRF-TOKEN` cookie Laravel sets and send it back as
  the `X-XSRF-TOKEN` request header itself, or every upload comes back 419.

## Key ideas

- **One coopting page context.** `provideUploadCenter()` joins the
  page-shell stack **and** the keyed `useTableContext('receipts')` once,
  coopts the shared category catalog from `useCategoriesStore()`, owns the
  URL-mirrored filters/tab and the **upload queue**, and exposes complete
  actions. Every leaf calls `useUploadCenter()` and nothing else.
- **The server page has no client-side fetch at all.** `receipts` arrives
  as a page prop; `useTableContext('receipts')` turns it into `items` +
  `totalItems`/`page`/`perPage` (URL-backed) + `selected`/`unselected`/`all`
  (select-all-across-pages); the context merges the live upload queue ahead
  of those items in a computed (`rows`) that `BbTable` binds to directly.
- **Filters mirror into the URL with `useQueryObject`.** Typing in a pill
  filter performs a partial Inertia visit
  (`only: ['receipts', 'tabCounts', 'readyCount']`); the server is the
  single source of filtered, paginated truth for the drafts/submitted/
  reimbursed rows.
- **Tabs are real visits.** `BbTabs` items carry `href` + `server: true`
  (component-level `navigation` is required alongside it) so switching tabs
  is a genuine, partial-reloaded Inertia visit — not a client-only URL
  change.
- **Capture and transfer are two layers, and transfer never touches
  Inertia.** `BbDropzone` only validates and hands over `File[]`; the
  context drains the dropzone's model into `ctx.enqueueFiles()` and runs
  the uploads itself. Inertia visits have no upload-progress events for a
  background queue, so each transfer is a direct `fetch`/XHR call (an
  `AbortController` + progress callback per file, same call shape as the
  other platforms) that finishes with a plain `router.reload({ only: […] })`
  instead of a data-carrying visit. Because it leaves Inertia's pipeline,
  it must also echo the `XSRF-TOKEN` cookie back as `X-XSRF-TOKEN` itself —
  Inertia's visits do this for you; a direct call doesn't get it for free.
- **Mutations are promise-wrapped `router.visit` calls.** A tiny local
  `visit()` helper turns Inertia's callback-based API into a promise, so
  context actions stay `async function`s exactly like the Vue/Nuxt
  versions — `await ctx.updateReceipt(...)` reads the same everywhere.
- **Clicking the name of a thing peeks it**, fetched from a small JSON
  endpoint via `useResourceContext` — not a full-page visit, so opening the
  sidebar never replaces the drafts table underneath it.
- **Buttons are `md` by default** (28px, flush beside `compact` inputs);
  `sm`/`xs` only in the table rows, the peeks' headers and the bottom bar.
  Real file downloads (`Download original`) set `target="_blank"` so
  `BbButton` renders a plain anchor instead of letting Inertia intercept a
  same-origin `href` as a visit — a raw file response would otherwise be
  swallowed by the Inertia request/response cycle.

## Page anatomy

```
UploadCenter/
	Index.vue              ← assembly: PageShell slots, dropzone, tabs, table, pagination
	context.ts              ← coopting page context (shell + useTableContext + categories + URL filters + upload queue + actions)
	ReceiptDropzone.vue    ← multi-file capture, constraint errors mapped to messages
	FilterRail.vue          ← pill filters + clear-all
	ReceiptFileCell.vue     ← file icon + name (peek link) + size, both row kinds
	UploadProgressCell.vue ← per-file BbProgress / failed state with inline retry
	MerchantCell.vue        ← inline text edit, commit on blur/Enter (§6.3)
	CategoryCell.vue        ← one-click badge → BbSelectPopover (§6.1)
	AmountCell.vue           ← inline number edit with $ prefix
	DateCell.vue             ← date picker cell, commit on pick
	RowActions.vue           ← remove-from-queue / per-receipt "…" dropdown
	SelectionBar.vue         ← bulk categorize + bulk remove in the floating bottom panel
	ReceiptPeek.vue          ← sidebar workbench, stack level 1
	MerchantPeek.vue         ← stacked peek, back arrow via the shell
```

Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
(left nav + fat footer), [Page Shell](../../guides/page-shell.md),
[Floating Bottom Panel](../../guides/floating-bottom-panel.md).

## Action inventory

| #   | Action                            | Trigger                            | Mechanism                                                        |
| --- | --------------------------------- | ---------------------------------- | ---------------------------------------------------------------- |
| 1   | Upload receipts                   | dropzone (drag, click, Browse)     | `enqueueFiles()` → direct fetch/XHR upload + partial reload      |
| 2   | Retry a failed upload             | inline in the progress cell        | `retryUpload(id)` re-issues the same direct request              |
| 3   | Remove an in-flight upload        | row actions (x)                    | `removeUpload(id)` aborts + drops the row                        |
| 4   | Page search                       | topbar right                       | `filters.search` → `useQueryObject` partial visit                |
| 5   | Filter category / merchant / date | filter rail pills                  | `BbSelectPopover` multiple / query-aware / date range            |
| 6   | Clear filters                     | rail right (only when active)      | context `clearFilters()`                                         |
| 7   | Switch tab                        | server-visit tabs with counts      | `BbTabs` `href` + `server: true` visit                           |
| 8   | Edit merchant inline              | merchant cell                      | commit on blur/Enter → promise-wrapped visit, Esc reverts (§6.3) |
| 9   | Change category one-click         | category badge in row & peek       | `BbSelectPopover` on the badge (§6.1) → promise-wrapped visit    |
| 10  | Edit amount inline                | amount cell ($ prefix)             | commit on blur/Enter → promise-wrapped visit, Esc reverts        |
| 11  | Edit expense date inline          | date cell                          | commit on pick → promise-wrapped visit                           |
| 12  | Submit one receipt                | row `…`, peek footer               | `submitReceipt()` (visit + refresh + toast)                      |
| 13  | Submit all with count             | topbar, the page's one `primary`   | `submitAll()` — count from every fetch                           |
| 14  | Remove a draft                    | row `…`, peek footer               | destructive behind `useConfirm`                                  |
| 15  | Bulk categorize                   | floating bottom panel popover      | `bulkCategorize()` on `table.selected`/`all`/`unselected`        |
| 16  | Bulk remove                       | floating bottom panel              | destructive behind `useConfirm`, count in message                |
| 17  | Select rows / select all          | table checkboxes (drafts only)     | `useTableContext` selection (across pages)                       |
| 18  | Peek receipt                      | filename cell / merchant peek list | `peekReceipt(id)` → shell stack, JSON fetch                      |
| 19  | Peek merchant (stacked)           | merchant name inside the peek      | `stackMerchant(name)` → back arrow, JSON fetch                   |
| 20  | Download original                 | row `…`, peek footer               | navigation (`target="_blank"`, real file endpoint)               |

## The code

### context.ts

```ts
// UploadCenter/context.ts
import {
	computed,
	inject,
	provide,
	reactive,
	ref,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import { router } from '@inertiajs/vue3';
import type { RequestPayload } from '@inertiajs/core';
import { useConfirm, useToast, type BadgeVariantType } from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import {
	useTableContext,
	type TableContext,
} from '@/composables/useTableContext';
import { useQueryObject } from '@/composables/useQueryObject';
import { useProp } from '@/composables/useProp';
import { useQuery } from '@/composables/useQuery';
import { useCategoriesStore } from '@/stores/categories';
import { api } from '@/api';
import type { Category, Receipt, ReceiptStatus } from '@/types';

/** What the stacked sidebar can show. Clicking a name pushes one of these. */
export type PeekItem =
	| { type: 'receipt'; id: string }
	| { type: 'merchant'; name: string };

export type UploadCenterTab = 'drafts' | 'submitted' | 'reimbursed';

export interface ReceiptFilters {
	search: string;
	categoryIds: string[];
	merchant: string | null;
	/**
	 * `[start, end]` as `YYYY-MM-DD`, or `[]` when unset. Range mode requires an
	 * array modelValue -- binding `null` throws, so the empty filter is `[]`.
	 */
	spentBetween: string[];
}

/** A dropped file whose transfer is still in flight (or failed). Local-only. */
export type UploadRow = {
	/** Local id (`upload-…`) — never collides with server receipt ids. */
	id: string;
	kind: 'upload';
	filename: string;
	size: number;
	/** 0–100. Mutated in place per progress tick — reactive, no refetch. */
	progress: number;
	failed: boolean;
};

/** A server receipt as the table renders it. */
export type ReceiptRow = Receipt & { kind: 'receipt' };

/** What the table actually lists on the Drafts tab: uploads first. */
export type UploadCenterRow = UploadRow | ReceiptRow;

/** The only fields the inline cells may change. */
export type ReceiptPatch = Partial<
	Pick<Receipt, 'merchant' | 'categoryId' | 'amount' | 'date'>
>;

const RELOAD_PROPS = ['receipts', 'tabCounts', 'readyCount'] as const;

// -- Receipt-status badge maps: one closed set, mapped once for the whole page.
// The receipt lifecycle (table rows, the receipt peek header, the merchant
// peek's recent list) is a small closed set — the textbook case for the soft
// accents (design-language.md § Using color), registered via badge-variants.d.ts.
// draft = idle/neutral, submitted = pending approval, reimbursed = done.
export const STATUS_LABEL: Record<ReceiptStatus, string> = {
	draft: 'Draft',
	submitted: 'Submitted',
	reimbursed: 'Reimbursed',
};
export const STATUS_VARIANT: Record<ReceiptStatus, BadgeVariantType> = {
	draft: 'soft-gray',
	submitted: 'soft-amber',
	reimbursed: 'soft-green',
};

export interface UploadCenterContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	table: TableContext<Receipt, string>;
	/** Shared expense-category catalog, coopted from the store. */
	categories: ComputedRef<Category[]>;
	// -- Page-owned state ------------------------------------------------------
	filters: ReceiptFilters;
	hasActiveFilters: ComputedRef<boolean>;
	tab: Ref<UploadCenterTab>;
	tabCounts: ComputedRef<Record<UploadCenterTab, number>>;
	/** Drafts that are complete (merchant + category + amount + date). */
	readyCount: ComputedRef<number>;
	/** The live upload queue — in-flight and failed transfers. */
	uploads: Ref<UploadRow[]>;
	/** Bumped after every mutation — peeks watch it to re-fetch their JSON detail. */
	refreshKey: Ref<number>;
	// -- Data --------------------------------------------------------------------
	/** Drafts tab: queue rows first, then the fetched server page. */
	rows: ComputedRef<UploadCenterRow[]>;
	searchMerchants: (query: string) => Promise<string[]>;
	// -- Peek grammar ----------------------------------------------------------
	peekReceipt: (id: string) => void;
	stackReceipt: (id: string) => void;
	stackMerchant: (name: string) => void;
	// -- Actions (complete: visit/reload + refresh + toast) ----------------------
	clearFilters: () => void;
	enqueueFiles: (files: File[]) => void;
	retryUpload: (id: string) => void;
	removeUpload: (id: string) => void;
	updateReceipt: (receipt: Receipt, patch: ReceiptPatch) => Promise<void>;
	submitReceipt: (receipt: Receipt) => Promise<void>;
	submitAll: () => Promise<void>;
	/** Resolves `true` when the receipt was actually deleted (confirm accepted). */
	deleteReceipt: (receipt: Receipt) => Promise<boolean>;
	bulkCategorize: (categoryId: string) => Promise<void>;
	bulkRemove: () => Promise<void>;
}

const key: InjectionKey<UploadCenterContext> = Symbol('upload-center');

/** Comma-joined query value → string[] (or null when absent). */
const toArray = (value: unknown): string[] | null => {
	if (value == null || value === '') return null;
	return Array.isArray(value) ? value.map(String) : String(value).split(',');
};

/** Inertia's callback-based visit, wrapped as a promise — so every context
 * action stays `async`, exactly like the Vue/Nuxt versions. Always a
 * partial reload of the props this page depends on. */
const visit = (
	method: 'post' | 'put' | 'patch' | 'delete',
	url: string,
	// Inertia's own payload type — strings/numbers/booleans/arrays/files.
	// (`Record<string, unknown>` does not satisfy it.)
	data: RequestPayload = {}
): Promise<void> =>
	new Promise((resolve, reject) => {
		router.visit(url, {
			method,
			data,
			only: [...RELOAD_PROPS],
			preserveScroll: true,
			preserveState: true,
			onSuccess: () => resolve(),
			onError: (errors) => reject(errors),
		});
	});

export function provideUploadCenter(): UploadCenterContext {
	const { toast } = useToast();
	const { confirm } = useConfirm();

	// -- Coopt the specific contexts: once, here, for the whole page. ----------
	const shell = usePageShellContext<PeekItem>();
	// `Receipt, string`: BbTable's `item-value="id"` resolves selection to
	// receipt ids ('rcp_…'), matching the Vue/Nuxt `table.selected: string[]` shape.
	const table = useTableContext<Receipt, string>('receipts');
	const categoriesStore = useCategoriesStore();
	const categories = computed(() => categoriesStore.categories);

	// -- Filters: seeded from the current URL, mirrored back by useQueryObject. -
	const query = useQuery();
	const filters = reactive<ReceiptFilters>({
		search: (query.search as string) ?? '',
		categoryIds: toArray(query.categoryIds) ?? [],
		merchant: (query.merchant as string) ?? null,
		spentBetween: toArray(query.spentBetween) ?? [],
	});
	useQueryObject(filters, { only: [...RELOAD_PROPS] });

	const hasActiveFilters = computed(
		() =>
			filters.search !== '' ||
			filters.categoryIds.length > 0 ||
			filters.merchant !== null ||
			filters.spentBetween.length > 0
	);
	const clearFilters = () => {
		filters.search = '';
		filters.categoryIds = [];
		filters.merchant = null;
		filters.spentBetween = [];
	};

	// Tab: seeded from the URL; BbTabs' own `href` + `server` visit updates
	// the URL, and its `v-model` write keeps this ref in sync with the click.
	const tab = ref<UploadCenterTab>((query.tab as UploadCenterTab) ?? 'drafts');
	const tabCounts = useProp<Record<UploadCenterTab, number>>('tabCounts');
	const readyCount = useProp<number>('readyCount');

	const refreshKey = ref(0);
	const refresh = () => {
		refreshKey.value++;
	};

	// -- Data ---------------------------------------------------------------------
	// The live upload queue is client-only reactive state — it is NOT part of
	// the `receipts` prop. `rows` merges it above the fetched page for the
	// Drafts tab; `BbTable` binds to `rows` directly (no items function).
	const uploads = ref<UploadRow[]>([]);
	const rows = computed<UploadCenterRow[]>(() => {
		const serverRows = table.items.value.map(
			(receipt): ReceiptRow => ({ ...receipt, kind: 'receipt' })
		);
		return tab.value === 'drafts'
			? [...uploads.value, ...serverRows]
			: serverRows;
	});

	const searchMerchants = (search: string): Promise<string[]> =>
		fetch(`/merchants/search?q=${encodeURIComponent(search)}`).then((res) =>
			res.json()
		);

	// -- Upload machinery ----------------------------------------------------------
	// Inertia visits cannot stream per-file progress for a background queue, so
	// each transfer is a direct fetch/XHR call (not router.visit) — the same
	// call shape as the other platforms. It leaves Inertia's pipeline, so it
	// must echo the XSRF-TOKEN cookie back as X-XSRF-TOKEN itself (Inertia's
	// own visits do this for free; a direct call doesn't get it). It finishes
	// with a plain partial reload instead of a data-carrying visit. The queue
	// rows themselves are reactive: progress ticks mutate them in place and
	// `rows` above re-derives
	// on every push/filter, no reload needed for that. Files and abort
	// controllers live in closure maps, not render state.
	const uploadFiles = new Map<string, File>();
	const controllers = new Map<string, AbortController>();

	const startUpload = async (id: string) => {
		const file = uploadFiles.get(id);
		const row = uploads.value.find((upload) => upload.id === id);
		if (!file || !row) return;
		row.failed = false;
		row.progress = 0;
		const controller = new AbortController();
		controllers.set(id, controller);
		try {
			await api.receipts.upload(file, {
				signal: controller.signal,
				onProgress: (percent) => {
					row.progress = percent;
				},
			});
			// Success: the file re-enters as a server draft with OCR-extracted
			// merchant/amount/date prefilled — the partial reload swaps the rows.
			uploads.value = uploads.value.filter((upload) => upload.id !== id);
			uploadFiles.delete(id);
			router.reload({ only: [...RELOAD_PROPS] });
		} catch {
			// Keep the row: the progress cell renders the inline Retry.
			row.failed = true;
		} finally {
			controllers.delete(id);
		}
	};

	const enqueueFiles = (files: File[]) => {
		for (const file of files) {
			const id = `upload-${crypto.randomUUID()}`;
			uploadFiles.set(id, file);
			uploads.value.push({
				id,
				kind: 'upload',
				filename: file.name,
				size: file.size,
				progress: 0,
				failed: false,
			});
			void startUpload(id);
		}
	};

	const retryUpload = (id: string) => {
		void startUpload(id);
	};

	const removeUpload = (id: string) => {
		controllers.get(id)?.abort();
		controllers.delete(id);
		uploadFiles.delete(id);
		uploads.value = uploads.value.filter((upload) => upload.id !== id);
	};

	// -- Peek grammar ----------------------------------------------------------------
	// peekX opens a fresh stack (from the list); stackX drills down (from a peek).
	const peekReceipt = (id: string) => shell.push({ type: 'receipt', id }, true);
	const stackReceipt = (id: string) => shell.push({ type: 'receipt', id });
	const stackMerchant = (name: string) =>
		shell.push({ type: 'merchant', name });

	// -- Actions --------------------------------------------------------------------
	const updateReceipt = async (receipt: Receipt, patch: ReceiptPatch) => {
		try {
			await visit('patch', `/receipts/${receipt.id}`, { ...patch });
			refresh(); // silent on success — the cell already shows the new value
		} catch {
			refresh(); // the reload reverts the cell to the server value
			toast({
				title: `Could not save ${receipt.filename}. Changes were reverted.`,
				variant: 'destructive',
			});
		}
	};

	const submitReceipt = async (receipt: Receipt) => {
		await visit('post', `/receipts/${receipt.id}/submit`);
		refresh();
		toast({
			title: `${receipt.merchant ?? receipt.filename} submitted for approval.`,
			variant: 'success',
		});
	};

	const submitAll = async () => {
		await visit('post', '/receipts/submit-drafts');
		refresh();
		toast({
			title: `${readyCount.value} receipts submitted for approval.`,
			variant: 'success',
		});
	};

	const deleteReceipt = async (receipt: Receipt): Promise<boolean> => {
		const ok = await confirm({
			variant: 'destructive',
			title: 'Remove receipt',
			text: `Remove ${receipt.filename}? The file is deleted and cannot be recovered.`,
			yes: 'Remove',
			no: 'Cancel',
		});
		if (!ok) return false;
		await visit('delete', `/receipts/${receipt.id}`);
		refresh();
		toast({ title: `${receipt.filename} removed.`, variant: 'success' });
		return true;
	};

	// Bulk actions carry the full select-all-across-pages payload — the
	// server combines `all` + `unselected` the same way BbTable does.
	const bulkPayload = () => ({
		ids: table.selected.value,
		all: table.all.value,
		unselected: table.unselected.value,
	});
	const bulkCount = () =>
		table.all.value
			? table.totalItems.value - table.unselected.value.length
			: table.selected.value.length;

	const bulkCategorize = async (categoryId: string) => {
		const count = bulkCount();
		await visit('patch', '/receipts/bulk/categorize', {
			...bulkPayload(),
			categoryId,
		});
		const category = categories.value.find((entry) => entry.id === categoryId);
		table.resetSelection();
		refresh();
		toast({
			title: `${count} receipts filed under ${category?.name ?? 'the selected category'}.`,
			variant: 'success',
		});
	};

	const bulkRemove = async () => {
		const count = bulkCount();
		const ok = await confirm({
			variant: 'destructive',
			title: 'Remove receipts',
			text: `Remove ${count} receipts? Their files are deleted and cannot be recovered.`,
			yes: 'Remove',
			no: 'Cancel',
		});
		if (!ok) return;
		await visit('post', '/receipts/bulk/delete', bulkPayload());
		table.resetSelection();
		refresh();
		toast({ title: `${count} receipts removed.`, variant: 'success' });
	};

	const ctx: UploadCenterContext = {
		shell,
		table,
		categories,
		filters,
		hasActiveFilters,
		tab,
		tabCounts,
		readyCount,
		uploads,
		refreshKey,
		rows,
		searchMerchants,
		peekReceipt,
		stackReceipt,
		stackMerchant,
		clearFilters,
		enqueueFiles,
		retryUpload,
		removeUpload,
		updateReceipt,
		submitReceipt,
		submitAll,
		deleteReceipt,
		bulkCategorize,
		bulkRemove,
	};
	provide(key, ctx);
	return ctx;
}

export function useUploadCenter(): UploadCenterContext {
	const ctx = inject(key);
	if (!ctx) throw new Error('useUploadCenter() called outside UploadCenter');
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- UploadCenter/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left, page search + submit-all right. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs
					class="min-w-0 flex-auto"
					:items="[
						{ key: 'dashboard', text: 'Dashboard', href: '/dashboard' },
						{ key: 'expenses', text: 'Expenses', href: '/expenses' },
						{ key: 'receipts', text: 'Receipts' },
					]"
				/>
				<div class="flex shrink-0 items-center gap-2">
					<BbTextInput
						v-model="ctx.filters.search"
						autocomplete="off"
						clearable
						compact
						hide-label
						label="Search receipts"
						placeholder="Search merchant or filename…"
						prepend:icon="lucide:search"
					/>
					<!-- The page's single primary: submit-all with a live count.
					     BbButton tracks the async handler, so it shows its own
					     loading state while the batch submits. -->
					<BbButton
						:disabled="ctx.readyCount.value === 0"
						prepend:icon="lucide:send"
						variant="primary"
						@click="ctx.submitAll"
					>
						{{ submitLabel }}
					</BbButton>
				</div>
			</div>
		</template>

		<div class="flex flex-col gap-3 p-4">
			<!-- Capture surface: drafts tab only. -->
			<ReceiptDropzone v-if="ctx.tab.value === 'drafts'" />

			<FilterRail />

			<!-- Tabs are real visits: href + server (component-level `navigation`
			     is required alongside per-item `server`), each carrying the same
			     partial-reload prop list as the filter watcher. Each href is
			     built from `tabHref()`, NOT a bare `?tab=` literal:
			     `preserve-state` keeps `ctx.filters` alive across the visit, so
			     if the href dropped the filter query keys the server would
			     render an unfiltered page while the (unchanged) filter chips
			     kept claiming the old filters still applied. -->
			<BbTabs
				v-model="ctx.tab.value"
				compact
				navigation
				preserve-scroll
				preserve-state
				replace
				:items="[
					{
						key: 'drafts',
						label: `Drafts · ${ctx.tabCounts.value.drafts}`,
						href: tabHref('drafts'),
						server: true,
						only: ['receipts', 'tabCounts', 'readyCount'],
					},
					{
						key: 'submitted',
						label: `Submitted · ${ctx.tabCounts.value.submitted}`,
						href: tabHref('submitted'),
						server: true,
						only: ['receipts', 'tabCounts', 'readyCount'],
					},
					{
						key: 'reimbursed',
						label: `Reimbursed · ${ctx.tabCounts.value.reimbursed}`,
						href: tabHref('reimbursed'),
						server: true,
						only: ['receipts', 'tabCounts', 'readyCount'],
					},
				]"
			/>

			<!-- No dependencies/items-fn: `receipts` is a page prop, `rows` merges
			     the live upload queue above it, and selection (across pages) binds
			     straight onto the keyed table context. -->
			<BbTable
				v-model="ctx.table.selected.value"
				v-model:select-all="ctx.table.all.value"
				v-model:unselected-items="ctx.table.unselected.value"
				actions
				caption="Expense receipts"
				:columns="columns"
				compact
				item-value="id"
				:items="ctx.rows.value"
				legend="Select receipts"
				loading-text="Loading receipts…"
				:row-class="rowClass"
				:selectable="isDraft"
			>
				<!-- Clicking the NAME of a thing peeks it. -->
				<template #filename="{ item }">
					<ReceiptFileCell :row="item" />
				</template>

				<!-- Editable cells on draft rows; plain text everywhere else. -->
				<template #merchant="{ item }">
					<MerchantCell v-if="isDraft(item)" :receipt="item" />
					<span
						v-else-if="item.kind === 'upload'"
						class="text-[color:var(--bb-text-muted)]"
						>—</span
					>
					<span v-else>{{ item.merchant ?? '—' }}</span>
				</template>

				<!-- Slot names are normalized: `categoryId` → `#categoryid`. -->
				<template #categoryid="{ item }">
					<CategoryCell v-if="isDraft(item)" :receipt="item" />
					<span
						v-else-if="item.kind === 'upload'"
						class="text-[color:var(--bb-text-muted)]"
						>—</span
					>
					<span v-else>{{ categoryName(item.categoryId) }}</span>
				</template>

				<template #amount="{ item }">
					<AmountCell v-if="isDraft(item)" :receipt="item" />
					<span
						v-else-if="item.kind === 'upload'"
						class="text-[color:var(--bb-text-muted)]"
						>—</span
					>
					<span v-else>{{
						item.amount === null ? '—' : currency.format(item.amount)
					}}</span>
				</template>

				<template #date="{ item }">
					<DateCell v-if="isDraft(item)" :receipt="item" />
					<span
						v-else-if="item.kind === 'upload'"
						class="text-[color:var(--bb-text-muted)]"
						>—</span
					>
					<span v-else>{{ item.date ? shortDate(item.date) : '—' }}</span>
				</template>

				<!-- Status column doubles as the transfer surface for queue rows. -->
				<template #status="{ item }">
					<UploadProgressCell v-if="item.kind === 'upload'" :upload="item" />
					<BbBadge v-else :variant="STATUS_VARIANT[item.status]">{{
						STATUS_LABEL[item.status]
					}}</BbBadge>
				</template>

				<template #actions="{ item }">
					<RowActions :row="item" />
				</template>

				<template #no-data>
					<div class="flex flex-col items-center gap-2 p-8 text-center">
						<BbIcon
							aria-hidden="true"
							class="text-[color:var(--bb-text-muted)]"
							:icon="
								ctx.hasActiveFilters.value
									? 'lucide:search-x'
									: 'lucide:receipt'
							"
							size="2xl"
						/>
						<p class="text-sm font-semibold">
							{{
								ctx.hasActiveFilters.value
									? 'No matching receipts'
									: ctx.tab.value === 'drafts'
										? 'No drafts yet'
										: 'Nothing in this tab yet'
							}}
						</p>
						<p class="text-xs text-[color:var(--bb-text-muted)]">
							{{
								ctx.hasActiveFilters.value
									? 'Loosen a filter above, or switch tabs to widen the view.'
									: ctx.tab.value === 'drafts'
										? 'Drop receipts above to get started.'
										: 'Submitted and reimbursed receipts land in their own tabs.'
							}}
						</p>
						<BbButton
							v-if="ctx.hasActiveFilters.value"
							prepend:icon="lucide:x"
							variant="ghost"
							@click="ctx.clearFilters"
						>
							Clear filters
						</BbButton>
					</div>
				</template>
			</BbTable>

			<!-- No table-id: the keyed table context is the page count here. -->
			<BbPagination
				v-model="ctx.table.page.value"
				label="Receipts pagination"
				:total-pages="ctx.table.totalPages.value"
			/>
		</div>

		<SelectionBar />

		<!-- Stacked peek sidebar: the shell owns back/close; we render by type. -->
		<template #sidebar>
			<ReceiptPeek
				v-if="ctx.shell.current.value?.type === 'receipt'"
				:receipt-id="ctx.shell.current.value.id"
			/>
			<MerchantPeek
				v-else-if="ctx.shell.current.value?.type === 'merchant'"
				:merchant-name="ctx.shell.current.value.name"
			/>
		</template>
	</PageShell>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import {
	BbBadge,
	BbBreadcrumbs,
	BbButton,
	BbIcon,
	BbPagination,
	BbTable,
	BbTabs,
	BbTextInput,
} from 'bitboss-ui';
import qs from 'query-string';
import PageShell from '@/components/layout/PageShell.vue';
import { useQuery } from '@/composables/useQuery';
import {
	provideUploadCenter,
	STATUS_LABEL,
	STATUS_VARIANT,
	type ReceiptRow,
	type UploadCenterRow,
	type UploadCenterTab,
} from './context';
import AmountCell from './AmountCell.vue';
import CategoryCell from './CategoryCell.vue';
import DateCell from './DateCell.vue';
import FilterRail from './FilterRail.vue';
import MerchantCell from './MerchantCell.vue';
import MerchantPeek from './MerchantPeek.vue';
import ReceiptDropzone from './ReceiptDropzone.vue';
import ReceiptFileCell from './ReceiptFileCell.vue';
import ReceiptPeek from './ReceiptPeek.vue';
import RowActions from './RowActions.vue';
import SelectionBar from './SelectionBar.vue';
import UploadProgressCell from './UploadProgressCell.vue';

const ctx = provideUploadCenter();

// Merge `tab` into the *current* query instead of replacing it: `useQuery()`
// reads the live URL, which already carries every filter `useQueryObject`
// mirrored there, so switching tabs keeps `search`/`categoryIds`/`merchant`/
// `spentBetween` intact instead of silently resetting the results to
// unfiltered.
const tabHref = (tab: UploadCenterTab): string =>
	`/receipts?${qs.stringify({ ...useQuery(), tab }, { arrayFormat: 'comma' })}`;

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
const shortDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
	});

// Every cell renders through a slot, so columns stay label-only definitions.
const columns = [
	{ key: 'filename', label: 'Receipt' },
	{ key: 'merchant', label: 'Merchant' },
	{ key: 'categoryId', label: 'Category' },
	{ key: 'amount', label: 'Amount', align: 'right' as const },
	{ key: 'date', label: 'Date' },
	{ key: 'status', label: 'Status' },
];

// Only server-side drafts are editable and selectable; queue rows and
// submitted/reimbursed receipts are not. The narrow predicate keeps the
// `v-else` (non-draft receipt) branch a real `ReceiptRow`, not `never`.
const isDraft = (
	item: UploadCenterRow
): item is ReceiptRow & { status: 'draft' } =>
	item.kind === 'receipt' && item.status === 'draft';

// Failed transfers get a tinted row — public row-class API, no internals.
const rowClass = (item: UploadCenterRow) =>
	item.kind === 'upload' && item.failed
		? 'bg-red-50 dark:bg-red-950/20'
		: undefined;

const categoryName = (categoryId: string | null) =>
	ctx.categories.value.find((category) => category.id === categoryId)?.name ??
	'—';

const submitLabel = computed(() =>
	ctx.readyCount.value === 0
		? 'Submit receipts'
		: `Submit ${ctx.readyCount.value} ${ctx.readyCount.value === 1 ? 'receipt' : 'receipts'}`
);
</script>
```

### ReceiptDropzone.vue

```vue
<!-- UploadCenter/ReceiptDropzone.vue -->
<template>
	<BbDropzone
		v-model="pending"
		:accept="ACCEPT"
		:errors="dropError"
		:max-files="20"
		:max-size="MAX_SIZE"
		multiple
		@error="onError"
	>
		<template #default="{ dragging, focused, open }">
			<div
				class="flex flex-col items-center gap-2 rounded-[var(--bb-radius)] border-2 border-dashed p-6 text-center transition-colors"
				:class="[
					dragging ? 'border-[var(--bb-primary)]' : 'border-[var(--bb-border)]',
					focused ? 'ring-2 ring-[var(--bb-primary)] ring-offset-2' : '',
				]"
			>
				<BbIcon
					class="text-[color:var(--bb-text-muted)]"
					icon="lucide:receipt"
					size="lg"
				/>
				<p class="text-sm font-medium">
					{{ dragging ? 'Drop to add receipts' : 'Drop receipts here' }}
				</p>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					JPG, PNG, HEIC or PDF · up to 10 MB each · 20 files per drop
				</p>
				<BbButton
					prepend:icon="lucide:folder-open"
					variant="ghost"
					@click="open"
				>
					Browse files
				</BbButton>
			</div>
		</template>
	</BbDropzone>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue';
import { BbButton, BbDropzone, BbIcon, type DropZoneError } from 'bitboss-ui';
import { useUploadCenter } from './context';

// Pair every extension with its MIME type: the MIME rule matches by content
// type, the .ext rule catches drag-drops where the OS leaves file.type empty.
const ACCEPT = [
	'image/jpeg',
	'.jpg',
	'.jpeg',
	'image/png',
	'.png',
	'image/heic',
	'.heic',
	'application/pdf',
	'.pdf',
];
const MAX_SIZE = 10 * 1024 * 1024; // 10 MB per receipt

const ctx = useUploadCenter();

// BbDropzone captures and validates; the context uploads through a direct
// fetch/XHR path (Inertia visits can't stream progress). The model is a
// hand-off buffer: drain every validated batch into the queue, then clear
// it (which also resets the duplicate check for future corrections).
const pending = ref<File[]>([]);
watch(pending, (files) => {
	if (files.length === 0) return;
	dropError.value = undefined;
	ctx.enqueueFiles(files);
	pending.value = [];
});

// The errors display is a round-trip: map each typed reject to a sentence
// and feed it back through the `errors` prop (rendered in the built-in
// aria-live region and referenced from the input's aria-describedby). Batch drops emit one error per file; showing the last
// message keeps the surface calm.
const dropError = ref<string | undefined>();
const onError = (error: DropZoneError) => {
	if (error.type === 'maxSize') {
		dropError.value = `${error.filename} is ${error.formattedSize} — receipts are capped at ${error.formattedMaxSize}.`;
	} else if (error.type === 'accept') {
		dropError.value = `${error.filename} is not a JPG, PNG, HEIC or PDF.`;
	} else if (error.type === 'uniqueness') {
		dropError.value = `${error.filename} is already in this drop.`;
	} else {
		dropError.value = `That drop had ${error.totalFiles} files — add at most 20 at a time.`;
	}
};
</script>
```

### FilterRail.vue

```vue
<!-- UploadCenter/FilterRail.vue -->
<template>
	<div class="flex flex-wrap items-center gap-2">
		<!-- Category: multi-select pill over the coopted catalog. Searchable, so
		     the filter clears from inside the popover search. -->
		<BbSelectPopover
			v-model="ctx.filters.categoryIds"
			clearable
			item-text="name"
			item-value="id"
			:items="ctx.categories.value"
			multiple
			width="240px"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filter by category"
					append:icon="lucide:chevron-down"
					size="sm"
					variant="outline"
				>
					Category{{
						ctx.filters.categoryIds.length
							? ` · ${ctx.filters.categoryIds.length}`
							: ''
					}}
				</BbButton>
			</template>
		</BbSelectPopover>

		<!-- Merchant: query-aware search against a small JSON endpoint, not an
		     Inertia visit — searching a filter pill must not re-render the page.
		     Merchant names are their own values, so the pill labels itself
		     straight from the filter state; searchable, so it clears
		     in-popover. -->
		<BbSelectPopover
			v-model="ctx.filters.merchant"
			clearable
			:items="ctx.searchMerchants"
			width="240px"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filter by merchant"
					append:icon="lucide:chevron-down"
					size="sm"
					variant="outline"
				>
					{{ ctx.filters.merchant ?? 'Merchant' }}
				</BbButton>
			</template>
		</BbSelectPopover>

		<!-- Spent-between range: a compact input is 28px — flush with the pills. -->
		<BbDatePickerInput
			v-model="ctx.filters.spentBetween"
			clearable
			compact
			floating
			hide-label
			label="Spent between"
			placeholder="Spent between…"
			range
		/>

		<!-- Clear-all renders only while something is active. -->
		<BbButton
			v-if="ctx.hasActiveFilters.value"
			class="ml-auto"
			prepend:icon="lucide:x"
			size="sm"
			variant="ghost"
			@click="ctx.clearFilters"
		>
			Clear filters
		</BbButton>
	</div>
</template>

<script setup lang="ts">
import { BbButton, BbDatePickerInput, BbSelectPopover } from 'bitboss-ui';
import { useUploadCenter } from './context';

const ctx = useUploadCenter();
</script>
```

### ReceiptFileCell.vue

```vue
<!-- UploadCenter/ReceiptFileCell.vue -->
<template>
	<div class="flex items-center gap-2">
		<BbIcon
			class="shrink-0 text-[color:var(--bb-text-muted)]"
			:icon="fileIcon"
			size="16"
		/>
		<div class="flex min-w-0 flex-col">
			<!-- Server receipts peek on click; queue rows are not peekable yet. -->
			<BbButton
				v-if="row.kind === 'receipt'"
				class="justify-start"
				size="sm"
				variant="link"
				@click="() => ctx.peekReceipt(row.id)"
			>
				{{ row.filename }}
			</BbButton>
			<span v-else class="truncate text-sm">{{ row.filename }}</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">{{
				formattedSize
			}}</span>
		</div>
	</div>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbIcon } from 'bitboss-ui';
import { useUploadCenter, type UploadCenterRow } from './context';

const props = defineProps<{ row: UploadCenterRow }>();

const ctx = useUploadCenter();

const fileIcon = computed(() =>
	props.row.filename.toLowerCase().endsWith('.pdf')
		? 'lucide:file-text'
		: 'lucide:image'
);

const formattedSize = computed(() => {
	const bytes =
		props.row.kind === 'upload' ? props.row.size : props.row.fileSize;
	return bytes >= 1024 * 1024
		? `${(bytes / (1024 * 1024)).toFixed(1)} MB`
		: `${Math.max(1, Math.round(bytes / 1024))} KB`;
});
</script>
```

### UploadProgressCell.vue

```vue
<!-- UploadCenter/UploadProgressCell.vue -->
<template>
	<!-- In flight: a live bar. `upload.progress` is a reactive field mutated
	     by the context's progress callback — no refetch per tick. -->
	<div v-if="!upload.failed" class="flex min-w-32 items-center gap-2">
		<BbProgress
			:aria-label="`Uploading ${upload.filename}`"
			class="flex-1"
			:model-value="upload.progress"
		/>
		<span class="text-xs tabular-nums text-[color:var(--bb-text-muted)]"
			>{{ upload.progress }}%</span
		>
	</div>

	<!-- Failed: say so and retry inline. `xs` is fine here — this is the
	     densest surface on the page. -->
	<div v-else class="flex items-center gap-2">
		<span class="text-xs font-medium text-red-600 dark:text-red-400"
			>Upload failed</span
		>
		<BbButton
			prepend:icon="lucide:rotate-cw"
			size="xs"
			variant="outline"
			@click="() => ctx.retryUpload(upload.id)"
		>
			Retry
		</BbButton>
	</div>
</template>

<script setup lang="ts">
import { BbButton, BbProgress } from 'bitboss-ui';
import { useUploadCenter, type UploadRow } from './context';

defineProps<{ upload: UploadRow }>();

const ctx = useUploadCenter();
</script>
```

### MerchantCell.vue

```vue
<!-- UploadCenter/MerchantCell.vue -->
<template>
	<BbTextInput
		v-model="draft"
		compact
		hide-label
		label="Merchant"
		placeholder="Add merchant"
		@change="commit"
		@keydown.esc="revert"
	/>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue';
import { BbTextInput } from 'bitboss-ui';
import { useUploadCenter } from './context';
import type { Receipt } from '@/types';

const props = defineProps<{ receipt: Receipt }>();

const ctx = useUploadCenter();

// Inline-edit doctrine (§6.3): a local draft, commit on @change — which
// fires once for the whole blur/Enter sequence, unlike binding @blur AND
// @keydown.enter separately (that double-fires: Enter commits, then the
// field still blurs right after). Revert on Esc. The server value re-seeds
// the draft whenever a reload updates the row — which is also how a
// failed save reverts.
const draft = ref<string | null>(props.receipt.merchant);
watch(
	() => props.receipt.merchant,
	(value) => {
		draft.value = value;
	}
);

const commit = () => {
	const merchant = draft.value?.trim() || null;
	if (merchant === props.receipt.merchant) return;
	void ctx.updateReceipt(props.receipt, { merchant });
};
const revert = () => {
	draft.value = props.receipt.merchant;
};
</script>
```

### CategoryCell.vue

```vue
<!-- UploadCenter/CategoryCell.vue -->
<template>
	<BbSelectPopover
		compact
		disable-writing
		item-text="name"
		item-value="id"
		:items="ctx.categories.value"
		:model-value="receipt.categoryId"
		width="220px"
		@update:model-value="(categoryId) => pick(categoryId as string)"
	>
		<template #activator="{ props: activatorProps, shown }">
			<!-- One-click pattern (§6.1): the badge is the focusable trigger —
			     BbBadgeButton takes over the badge body, the trailing chevron says
			     "this can change", and while the save runs `loading` swaps the
			     spinner into the chevron's place. A category is a label, not a
			     semantic status, so a set category reads neutral (`secondary`);
			     only the unset state stays `outline` so empty cells read as
			     quieter to-dos, not values. -->
			<BbBadge
				append:icon="lucide:chevron-down"
				:class="{ 'category-cell--open': shown }"
				:loading="saving"
				:variant="receipt.categoryId ? 'secondary' : 'outline'"
			>
				<BbBadgeButton
					:aria-label="`Change category for ${receipt.filename}`"
					v-bind="activatorProps"
					>{{ categoryName }}</BbBadgeButton
				>
			</BbBadge>
		</template>
	</BbSelectPopover>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
import { useUploadCenter } from './context';
import type { Receipt } from '@/types';

const props = defineProps<{ receipt: Receipt }>();

const ctx = useUploadCenter();

// In-flight flag for the save feedback — rung-1 local state, not context.
const saving = ref(false);
const pick = async (categoryId: string) => {
	saving.value = true;
	try {
		await ctx.updateReceipt(props.receipt, { categoryId });
	} finally {
		saving.value = false;
	}
};

// The trigger labels itself from the coopted catalog, never from the
// popover's lazy `text` slot prop.
const categoryName = computed(
	() =>
		ctx.categories.value.find(
			(category) => category.id === props.receipt.categoryId
		)?.name ?? 'Set category'
);
</script>

<style scoped>
/* Open = the badge's own hue, deepened, plus its variant ring — the same
   grammar as every badge-activator cell. */
.category-cell--open {
	--bg: color-mix(in oklab, var(--color) 24%, var(--bb-panel));
	--border-color: color-mix(in oklab, var(--color) 45%, var(--bb-panel));
	box-shadow: 0 0 0 var(--bb-ring-size) var(--ring);
}
</style>
```

### AmountCell.vue

```vue
<!-- UploadCenter/AmountCell.vue -->
<template>
	<BbNumberInput
		v-model="draft"
		compact
		hide-label
		label="Amount"
		:max-precision="2"
		:min="0"
		placeholder="0.00"
		@change="commit"
		@keydown.esc="revert"
	>
		<template #prefix>$</template>
	</BbNumberInput>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue';
import { BbNumberInput } from 'bitboss-ui';
import { useUploadCenter } from './context';
import type { Receipt } from '@/types';

const props = defineProps<{ receipt: Receipt }>();

const ctx = useUploadCenter();

/** Money cells always show two decimals so the column optically aligns. */
const formatMoney = (value: number | null): string | null =>
	value === null || Number.isNaN(value) ? null : value.toFixed(2);

// Same commit/revert contract as the merchant cell, on the number model —
// commit on @change, not @blur + @keydown.enter (see MerchantCell.vue).
const draft = ref<number | string | null>(formatMoney(props.receipt.amount));
watch(
	() => props.receipt.amount,
	(value) => {
		draft.value = formatMoney(value);
	}
);

const commit = () => {
	const amount =
		draft.value === null || draft.value === '' ? null : Number(draft.value);
	if (amount === props.receipt.amount) {
		draft.value = formatMoney(props.receipt.amount);
		return;
	}
	void ctx.updateReceipt(props.receipt, { amount });
	draft.value = formatMoney(amount);
};
const revert = () => {
	draft.value = formatMoney(props.receipt.amount);
};
</script>
```

### DateCell.vue

```vue
<!-- UploadCenter/DateCell.vue -->
<template>
	<!-- Picking a date IS the commit — no blur dance for calendar input.
	     `floating` keeps the model a plain YYYY-MM-DD string. -->
	<BbDatePickerInput
		compact
		floating
		hide-label
		label="Expense date"
		:model-value="receipt.date"
		placeholder="YYYY-MM-DD"
		@update:model-value="commit"
	/>
</template>

<script setup lang="ts">
import { BbDatePickerInput } from 'bitboss-ui';
import { useUploadCenter } from './context';
import type { Receipt } from '@/types';

const props = defineProps<{ receipt: Receipt }>();

const ctx = useUploadCenter();

const commit = (value: string | string[] | null) => {
	const date = Array.isArray(value) ? (value[0] ?? null) : value;
	if (date === props.receipt.date) return;
	void ctx.updateReceipt(props.receipt, { date });
};
</script>
```

### RowActions.vue

```vue
<!-- UploadCenter/RowActions.vue -->
<template>
	<!-- Queue rows: one explicit remove (aborts the transfer). -->
	<BbButton
		v-if="row.kind === 'upload'"
		:aria-label="`Remove ${row.filename} from the queue`"
		icon="lucide:x"
		size="sm"
		variant="ghost"
		@click="() => ctx.removeUpload(row.id)"
	/>

	<!-- Server receipts: contextual dropdown, entries vary by status. -->
	<BbDropdown v-else :items="items">
		<template #activator="{ props }">
			<BbButton v-bind="props" icon="lucide:ellipsis" size="sm" variant="ghost">
				Receipt actions
			</BbButton>
		</template>
	</BbDropdown>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbDropdown } from 'bitboss-ui';
import { useUploadCenter, type UploadCenterRow } from './context';

const props = defineProps<{ row: UploadCenterRow }>();

const ctx = useUploadCenter();

const items = computed(() => {
	if (props.row.kind !== 'receipt') return [];
	const receipt = props.row;
	const isDraft = receipt.status === 'draft';
	return [
		...(isDraft
			? [
					{
						key: 'submit',
						text: 'Submit for approval',
						'prepend:icon': 'lucide:send',
						onClick: () => ctx.submitReceipt(receipt),
					},
				]
			: []),
		{
			// A real file download, not an Inertia page — `target` forces
			// BbButton to render a plain anchor instead of letting Inertia
			// intercept this same-origin `href` as a visit (see BbBaseButton's
			// routing rules).
			key: 'download',
			text: 'Download original',
			'prepend:icon': 'lucide:download',
			href: `/receipts/${receipt.id}/file`,
			target: '_blank',
		},
		...(isDraft
			? [
					{
						key: 'remove',
						text: 'Remove',
						'prepend:icon': 'lucide:trash-2',
						variant: 'destructive' as const,
						onClick: () => ctx.deleteReceipt(receipt),
					},
				]
			: []),
	];
});
</script>
```

### SelectionBar.vue

```vue
<!-- UploadCenter/SelectionBar.vue -->
<template>
	<FloatingBottomPanel :open="selectedCount > 0">
		<span class="px-2 text-sm text-[color:var(--bb-text-muted)]">
			<span class="font-semibold tabular-nums">{{ selectedCount }}</span>
			selected
		</span>

		<!-- Bulk categorize: the picker lives right in the bar — a one-shot
		     popover (model stays null) whose selection IS the action. -->
		<BbSelectPopover
			item-text="name"
			item-value="id"
			:items="ctx.categories.value"
			:model-value="null"
			:offset="10"
			placement="top"
			width="220px"
			@update:model-value="
				(categoryId) => categoryId && ctx.bulkCategorize(categoryId)
			"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Set category for selected receipts"
					prepend:icon="lucide:tag"
					size="sm"
					variant="ghost"
				>
					Set category
				</BbButton>
			</template>
		</BbSelectPopover>

		<div class="floating-bottom-panel__right flex items-center gap-1">
			<BbButton size="sm" variant="destructive" @click="ctx.bulkRemove"
				>Remove</BbButton
			>
			<BbButton
				v-bb-tooltip="{ text: 'Clear selection', delay: 400 }"
				aria-label="Clear selection"
				icon="lucide:x"
				size="sm"
				variant="ghost"
				@click="ctx.table.resetSelection"
			/>
		</div>
	</FloatingBottomPanel>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbSelectPopover, vBbTooltip } from 'bitboss-ui';
import { useUploadCenter } from './context';
import FloatingBottomPanel from '@/components/layout/FloatingBottomPanel.vue';

const ctx = useUploadCenter();

// `all` (select-all-across-pages) does not enumerate rows, so the visible
// count is the total minus whatever the user manually deselected.
const selectedCount = computed(() =>
	ctx.table.all.value
		? ctx.table.totalItems.value - ctx.table.unselected.value.length
		: ctx.table.selected.value.length
);
</script>
```

### ReceiptPeek.vue

```vue
<!-- UploadCenter/ReceiptPeek.vue -->
<template>
	<div v-if="receipt" class="flex flex-col gap-4 text-sm">
		<!-- Header: merchant identity + amount + status. The merchant name
		     drills DOWN — stacked peek, back arrow via the shell. -->
		<header class="flex flex-col gap-1.5">
			<div class="flex items-center justify-between gap-2">
				<BbButton
					v-if="receipt.merchant"
					size="sm"
					variant="link"
					@click="() => ctx.stackMerchant(receipt!.merchant!)"
				>
					{{ receipt.merchant }}
				</BbButton>
				<span v-else class="text-[color:var(--bb-text-muted)]"
					>No merchant yet</span
				>
				<BbBadge :variant="STATUS_VARIANT[receipt.status]">{{
					STATUS_LABEL[receipt.status]
				}}</BbBadge>
			</div>
			<p class="text-xl font-semibold">
				{{
					receipt.amount === null
						? 'Amount missing'
						: currency.format(receipt.amount)
				}}
			</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				{{ receipt.filename }} · spent
				{{ receipt.date ? longDate(receipt.date) : '—' }}
			</p>
		</header>

		<!-- Preview placeholder: the real app renders the scanned image here. -->
		<div
			class="flex h-44 flex-col items-center justify-center gap-1 rounded-[var(--bb-radius)] border bg-[var(--bb-panel)] text-[color:var(--bb-text-muted)]"
		>
			<BbIcon icon="lucide:receipt" size="lg" />
			<span class="text-xs">Receipt preview</span>
		</div>

		<!-- Extracted fields: what OCR read off the scan, with confidence. -->
		<section class="flex flex-col gap-1.5">
			<div class="flex items-center justify-between">
				<h3
					class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
				>
					Extracted fields
				</h3>
				<BbBadge size="xs" variant="outline">{{
					`OCR · ${receipt.extracted.confidence}%`
				}}</BbBadge>
			</div>
			<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
				<dt class="text-[color:var(--bb-text-muted)]">Merchant</dt>
				<dd>{{ receipt.extracted.merchant ?? '—' }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Total</dt>
				<dd>
					{{
						receipt.extracted.total === null
							? '—'
							: currency.format(receipt.extracted.total)
					}}
				</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Tax</dt>
				<dd>
					{{
						receipt.extracted.tax === null
							? '—'
							: currency.format(receipt.extracted.tax)
					}}
				</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Date</dt>
				<dd>
					{{ receipt.extracted.date ? longDate(receipt.extracted.date) : '—' }}
				</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Paid with</dt>
				<dd>{{ receipt.extracted.paymentMethod ?? '—' }}</dd>
			</dl>
		</section>

		<!-- Properties: the peek is a workbench — the category is the same
		     one-click cell as in the table. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Details
			</h3>
			<dl class="grid grid-cols-[auto_1fr] items-center gap-x-4 gap-y-1.5">
				<dt class="text-[color:var(--bb-text-muted)]">Category</dt>
				<dd><CategoryCell :receipt="receipt" /></dd>
				<dt class="text-[color:var(--bb-text-muted)]">Uploaded</dt>
				<dd>{{ longDate(receipt.uploadedAt) }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Report</dt>
				<dd>{{ receipt.reportName ?? 'Not on a report yet' }}</dd>
			</dl>
		</section>

		<!-- Activity feed. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Activity
			</h3>
			<ul class="flex flex-col gap-2">
				<li
					v-for="entry in receipt.activity"
					:key="entry.id"
					class="flex gap-2"
				>
					<BbIcon
						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
						:icon="entry.icon"
						size="14"
					/>
					<div class="flex flex-col">
						<span>{{ entry.text }}</span>
						<span class="text-xs text-[color:var(--bb-text-muted)]"
							>{{ entry.actor }} · {{ longDate(entry.at) }}</span
						>
					</div>
				</li>
			</ul>
		</section>

		<!-- Act here, or leave for the original file. -->
		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				v-if="receipt.status === 'draft'"
				prepend:icon="lucide:send"
				size="sm"
				variant="secondary"
				@click="() => ctx.submitReceipt(receipt!)"
			>
				Submit
			</BbButton>
			<!-- A real file download, not an Inertia page — `target` forces a
			     plain anchor instead of an Inertia visit. -->
			<BbButton
				append:icon="lucide:arrow-up-right"
				:href="`/receipts/${receipt.id}/file`"
				size="sm"
				target="_blank"
				variant="ghost"
			>
				Download original
			</BbButton>
			<BbButton
				v-if="receipt.status === 'draft'"
				class="ml-auto"
				prepend:icon="lucide:trash-2"
				size="sm"
				variant="destructive"
				@click="removeAndClose"
			>
				Remove
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { watch } from 'vue';
import { BbBadge, BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
import { useResourceContext } from '@/composables/useResourceContext';
import CategoryCell from './CategoryCell.vue';
import { STATUS_LABEL, STATUS_VARIANT, useUploadCenter } from './context';
import type { ReceiptDetail } from '@/types';

const props = defineProps<{ receiptId: string }>();

const ctx = useUploadCenter();

// A small JSON endpoint, not a page visit — opening the peek never
// re-renders the drafts table underneath it. Re-fetches whenever the stack
// shows a different receipt; `refreshKey` makes mutations (category,
// submit) and completed uploads reflect here immediately.
const { data: receipt, refresh } = useResourceContext<ReceiptDetail, string>(
	() => props.receiptId,
	(id) => fetch(`/receipts/${id}/peek`).then((res) => res.json())
);
watch(() => ctx.refreshKey.value, refresh);

// deleteReceipt resolves true only when the confirm was accepted — don't
// close the peek on a cancelled dialog.
const removeAndClose = async () => {
	if (!receipt.value) return;
	if (await ctx.deleteReceipt(receipt.value)) ctx.shell.close();
};

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
const longDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
		year: 'numeric',
	});
</script>
```

### MerchantPeek.vue

```vue
<!-- UploadCenter/MerchantPeek.vue -->
<template>
	<div v-if="merchant" class="flex flex-col gap-4 text-sm">
		<header class="flex items-center gap-3">
			<div
				class="grid h-9 w-9 shrink-0 place-items-center rounded-[var(--bb-radius)] border"
			>
				<BbIcon
					class="text-[color:var(--bb-text-muted)]"
					icon="lucide:store"
					size="18"
				/>
			</div>
			<div class="flex flex-col">
				<h2 class="text-base font-semibold">{{ merchant.name }}</h2>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					{{ merchant.defaultCategoryName }} · this year
				</p>
			</div>
		</header>

		<!-- Stat strip. -->
		<div class="grid grid-cols-3 gap-2">
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Total spent</p>
				<p class="font-semibold">{{ currency.format(merchant.totalSpent) }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Receipts</p>
				<p class="font-semibold">{{ merchant.receiptCount }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Average</p>
				<p class="font-semibold">
					{{ currency.format(merchant.averageAmount) }}
				</p>
			</div>
		</div>

		<!-- Recent receipts: names drill down again — the stack keeps growing. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Recent receipts
			</h3>
			<ul class="flex flex-col">
				<li
					v-for="recent in merchant.recentReceipts"
					:key="recent.id"
					class="flex items-center justify-between gap-2 border-b py-1.5 last:border-b-0"
				>
					<BbButton
						size="sm"
						variant="link"
						@click="() => ctx.stackReceipt(recent.id)"
					>
						{{ recent.filename }}
					</BbButton>
					<BbBadge :variant="STATUS_VARIANT[recent.status]">{{
						STATUS_LABEL[recent.status]
					}}</BbBadge>
					<span class="text-xs tabular-nums text-[color:var(--bb-text-muted)]">
						{{ currency.format(recent.amount) }}
					</span>
				</li>
			</ul>
		</section>

		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<!-- An internal listing page — same-origin `href` auto-upgrades to an
			     Inertia visit (§3a); no `target` needed here. -->
			<BbButton
				append:icon="lucide:arrow-up-right"
				:href="`/expenses/receipts?merchant=${encodeURIComponent(merchant.name)}`"
				size="sm"
				variant="ghost"
			>
				All receipts from {{ merchant.name }}
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { BbBadge, BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
import { useResourceContext } from '@/composables/useResourceContext';
import { STATUS_LABEL, STATUS_VARIANT, useUploadCenter } from './context';
import type { MerchantSummary } from '@/types';

const props = defineProps<{ merchantName: string }>();

const ctx = useUploadCenter();

const { data: merchant } = useResourceContext<MerchantSummary, string>(
	() => props.merchantName,
	(name) =>
		fetch(`/merchants/${encodeURIComponent(name)}/peek`).then((res) =>
			res.json()
		)
);

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
</script>
```

## Why it is built this way

- **The context coopts, leaves consume.** `shell` and the keyed
  `useTableContext('receipts')` are joined once in `provideUploadCenter()`;
  thirteen components share the filters, the queue, selection, the peek
  stack and every action through one `useUploadCenter()` call. No leaf
  imports `@/api`, `fetch` or a store directly — even the query-aware
  merchant pill gets its provider (`ctx.searchMerchants`) from the context.
- **`receipts` is a page prop, not a client fetch.** `useTableContext`
  turns the Laravel paginator into `items`/`totalItems`/`page`/`perPage`
  (URL-backed) plus `selected`/`unselected`/`all`; `BbTable` binds directly
  to `rows` (the queue merged ahead of `table.items`) with
  `v-model`/`v-model:select-all`/`v-model:unselected-items` — there is no
  items function and no `dependencies` array, because the server already
  did the filtering, sorting and paging before the props arrived.
- **The upload queue crosses the data-layer swap untouched.** It was
  always client-only reactive state, so it needed no adaptation beyond
  where it merges: `uploads` stays a plain `ref`, progress ticks still
  mutate the row objects in place, and `rows` (a computed combining
  `uploads` with `table.items`) is what `BbTable` binds to — Vue's own
  reactivity re-renders the one cell reading a progress tick, no reload
  involved.
- **Inertia visits can't stream upload progress, so the transfer itself
  doesn't use one.** `api.receipts.upload()` posts `FormData` through a
  direct fetch/XHR call (not axios — a modern Inertia install doesn't ship
  it) — an `AbortController` + progress callback per file, same shape as the
  other platforms — and finishes with a plain
  `router.reload({ only: [...RELOAD_PROPS] })` instead of a data-carrying
  visit, since a completed upload only needs the fresh paginator, not a
  navigation. Leaving Inertia's pipeline means leaving its automatic CSRF
  handling too: `api.receipts.upload()` must read the `XSRF-TOKEN` cookie and
  send it back as the `X-XSRF-TOKEN` header, or the request 419s.
- **One watcher for filters, one visit mechanism for tabs.**
  `useQueryObject(filters, { only: ['receipts', 'tabCounts', 'readyCount'] })`
  is the entire filter-to-URL wiring; `BbTabs`' `href` + `server: true`
  items (with the required component-level `navigation`) make tab switches
  real, partial-reloaded visits with the same `only` list — one source of
  server truth, reached two ways. Each `href` is built by `tabHref()`, which
  merges `tab` into the current query rather than replacing it — `href:
'/receipts?tab=drafts'` alone would drop every active filter, and because
  `preserve-state` keeps this page instance (and `ctx.filters`) alive across
  the visit, the chips would keep showing the old filters as active over an
  unfiltered result set.
- **The `visit()` helper is the promise-wrapped router-visit pattern** the
  base's adaptation notes call for: it turns Inertia's
  `onSuccess`/`onError` callbacks into a promise so every context action
  (`updateReceipt`, `submitReceipt`, the bulk actions, …) stays an `async
function` — identical call sites to the Vue/Nuxt recipes,
  `await ctx.updateReceipt(...)`.
- **Bulk actions carry the full select-all-across-pages payload**
  (`ids`/`all`/`unselected`) so "select all, deselect three, categorize"
  sends the same semantics the table itself models — never just an
  enumerated id list that silently drops rows outside the current page.
- **Peeks are JSON fetches, not visits.** `useResourceContext` re-fetches
  on id change and exposes a `refresh()` the peek re-runs whenever
  `ctx.refreshKey` bumps (every mutation and every completed upload bumps
  it) — opening or updating a peek never re-renders the drafts page
  underneath it.
- **`peekX` vs `stackX` is the whole stack grammar.** Fresh peeks replace,
  drill-downs push; the shell renders the back arrow when depth > 1. The
  grammar lives in the context — a leaf cannot accidentally nuke the
  stack.
- **Real file downloads set `target`, internal pages don't.** Inertia
  auto-upgrades any same-origin `href` without a `target` into a visit
  (§3a) — correct for the merchant peek's "All receipts from…" link, but
  wrong for "Download original": a raw file response fed through the
  Inertia request cycle would never reach the browser as a download.
  Setting `target="_blank"` makes `BbBaseButton` fall back to a plain
  anchor for exactly those two links (the row `…` dropdown and the peek
  footer).
- **Sizing:** topbar and rail follow `md`-first (`compact` search at 28px
  flush beside the default-size primary); `sm` appears exactly where the
  doctrine allows — row actions, pills, peek footers, the bulk bar — and
  the one `xs` (inline Retry) sits inside a table cell, the densest
  surface on the page. **One `variant="primary"`** (Submit all, with its
  live count and auto-tracked loading). Destructive actions — single,
  bulk, in-peek — all ride `useConfirm` with the filename or count in the
  message.

## Variations

- **Expense reports**: group receipts into named reports (a `reportId`
  column + a "Add to report" bulk action feeding a `BbSelectPopover` of
  open reports); the Submit-all primary becomes "Submit report".
- **Policy checks**: server flags out-of-policy drafts
  (`receipt.policyWarning`); tint the row, badge the amount cell, and
  render a `BbAlert` above the table summarizing the count.
- **Camera-first mobile**: keep `accept` image-heavy and rely on the
  native picker offering the camera; the dropzone slot collapses to a
  single "Snap a receipt" affordance under the mobile breakpoint.
- **Auto-submit on high confidence**: when `extracted.confidence` ≥ 95 and
  all four fields resolved, submit server-side on upload and toast an
  undo — the Drafts tab then only holds receipts needing review.
- **Lazy tab counts**: if `tabCounts`/`readyCount` are expensive to
  compute, share them as `Inertia::lazy()` and read them with
  `useLazyProp` instead of a plain prop — the tab labels and the submit-all
  button resolve once the data lands instead of blocking the first render.

---

<!-- dist/ai/recipes/inertia/wizard-form.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/inertia/wizard-form.md -->

# Recipe: Wizard Form (Inertia)

The same Mailchimp-grade "Create campaign" wizard adapted for **Laravel +
Inertia**: four steps (Audience → Content → Schedule → Review) behind a
custom stepper header, per-step validation gating forward progress, the
active step mirrored into the URL, save-draft everywhere, and a dirty-state
leave guard. Anatomy, components, the context shape, copy and data are
identical to the Vue recipe; only the data/URL/mutation layer changes — the
draft is a [`usePromiseForm`](../../guides/inertia-helpers.md) whose
`form.errors` merge straight into the per-step validation, the step mirrors
into the URL without an Inertia visit (it's pure display state), and
[`useConfirmOnRouteLeave`](../../guides/inertia-helpers.md) replaces
`onBeforeRouteLeave`.

Sibling recipes: [Vue](../vue/wizard-form.md) ·
[Nuxt](../nuxt/wizard-form.md).

## Prerequisites

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell` and `usePageShellContext` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
- `<BbConfirm />` and `<BbToast />` mounted once in the `createInertiaApp` render root — never in a page.
- From the [Inertia Helpers](../../guides/inertia-helpers.md) toolkit:
  `usePromiseForm`, `useConfirmOnRouteLeave`, `useProp`, `useQuery`,
  `useResourceContext`.
- [App Layout](../../guides/app-layout.md) and
  [Page Shell](../../guides/page-shell.md) copied into
  `src/components/layout/` per their guides — the page renders inside this
  chrome.
- Controller: `Inertia::render('Campaigns/Edit', ['campaign' => $campaign,
'draft' => $draft])` — `campaign` is the record, `draft` the saved field
  values (matching `CampaignDraft` verbatim, camelCase — the `FormRequest`
  behind the mutation routes below is assumed to key its `422` validation
  messages the same way). Mutation routes: `PUT /campaigns/:id` (save
  draft), `POST /campaigns/:id/send-test`, `POST /campaigns/:id/send`,
  `DELETE /campaigns/:id`; small JSON endpoints back the segment lookups:
  `GET /segments/search?q=`, `GET /segments/:id`,
  `GET /segments/:id/estimate`, `GET /segments/:id/detail`.

## Key ideas

- **One coopting page context.** `provideCampaignWizard()` joins the
  page-shell stack once and owns the draft, the current step, the live
  validation, and every action. All seven leaves call
  `useCampaignWizard()` and nothing else — the only prop on the page is
  the id the segment peek renders.
- **The stepper is derived state, not navigation chrome.** A step is
  reachable exactly when every step before it validates — the same
  predicate `goNext()` uses — so jumping from the header can never outrun
  the validation gate. Steps already passed show `done` (checkmarked),
  reachable future steps stay numbered (`upcoming`), and `locked` steps
  render as disabled `BbBaseButton`s.
- **Validation merges `form.errors` live — no manual bookkeeping.**
  `issues` recomputes from the client-side checks _and_
  `usePromiseForm`'s already-reactive `form.errors`, folded onto the step
  that owns each field, so a failed save surfaces exactly like a blocked
  Next. The `BbAlert` summary and inline field errors still appear only
  after a blocked Next (`attempted`), and shrink live as each problem
  clears.
- **The draft and campaign arrive as page props — there is no loading
  state.** `usePromiseForm` seeds itself from the `draft` prop once;
  `ctx.loading` stays permanently `false`. The requested `?step` is
  clamped to the first incomplete step **at setup**, synchronously — no
  deferred fetch to wait on.
- **The step mirrors into the URL without an Inertia visit.** The step is
  pure client display state, not server data, so changing it updates
  `history.replaceState` directly instead of round-tripping through
  `router.visit` — unlike a tabs-as-filters page, no prop on this page
  depends on which step is showing.
- **One `BbSmoothHeight` wraps the alert + step outlet together**, so the
  step swap _and_ the validation summary appearing both glide instead of
  snapping. Conditional regions inside a step (the scheduled-date fields)
  need no wrapper of their own — the same resize observer catches them.
- **Back and Save draft are always free; validation only guards forward.**
  The page's one `variant="primary"` is the final Send/Schedule submit,
  with `:loading` riding `ctx.submitting` (`usePromiseForm`'s
  `isSubmitting`).
- **Leaving is guarded by `form.isDirty` — no snapshots.**
  `useConfirmOnRouteLeave` reads `draft.isDirty` and whitelists the
  campaign's own save/send/send-test URLs so submitting can't block
  itself; `draft.defaults()` re-baselines after a successful save/send so
  the follow-up navigate-away never re-prompts, and discarding sets a
  local flag before its own delete + navigate for the same reason.

## Page anatomy

```
CampaignWizard/
	Index.vue          ← assembly: PageShell slots, stepper, BbSmoothHeight outlet, footer
	context.ts         ← coopting page context (shell + usePromiseForm draft + step + validation + actions)
	StepperHeader.vue  ← BbBaseButton steps with done/current/upcoming/locked states
	AudienceStep.vue   ← segment select, audience filters, live recipient estimate
	ContentStep.vue    ← subject/preheader, body, template picker, send-test
	ScheduleStep.vue   ← send-now vs scheduled, date + timezone
	ReviewStep.vue     ← read-only summary with per-section Edit links
	WizardFooter.vue   ← Back · Save draft · Next / Send with :loading
	SegmentPeek.vue    ← sidebar workbench for the selected segment
```

Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
(left nav + fat footer) and [Page Shell](../../guides/page-shell.md).
Wizard archetype: no filter rail, no tabs, no table, no pagination, no bulk
bar — the work surface is the step outlet.

## Action inventory

| #   | Action                      | Trigger                          | Mechanism                                                                   |
| --- | --------------------------- | -------------------------------- | --------------------------------------------------------------------------- |
| 1   | Advance a step (validated)  | footer **Next** (secondary)      | `goNext()` — blocks and raises the `BbAlert` summary on issues              |
| 2   | Go back                     | footer **Back** (ghost)          | `goBack()` — never validated                                                |
| 3   | Jump to an unlocked step    | stepper header                   | `goToStep()`; locked steps are disabled `BbBaseButton`s                     |
| 4   | Edit a section from Review  | per-section **Edit** links       | `goToStep()` back to that step                                              |
| 5   | Save draft                  | footer ghost, on every step      | `saveDraft()` → `usePromiseForm.put` (whitelisted) + toast                  |
| 6   | Send a test email           | Content step ghost               | `sendTest()` → `post` to `/campaigns/:id/send-test`                         |
| 7   | Send / schedule campaign    | Review, the page's one `primary` | `submit()` with `:loading`, whole-wizard validation, `put` then `post`      |
| 8   | Discard draft               | topbar, destructive              | `useConfirm` → `remove` (DELETE) + `router.visit('/campaigns')`             |
| 9   | Peek the segment            | segment name (Audience & Review) | `peekSegment()` → shell stack                                               |
| 10  | Leave with unsaved changes  | any Inertia visit                | `useConfirmOnRouteLeave` guard → `useConfirm`                               |
| 11  | Restore position on refresh | URL `?step=N`                    | read via `useQuery()`, clamped at setup; changes via `history.replaceState` |

## The code

### context.ts

```ts
// CampaignWizard/context.ts
import {
	computed,
	inject,
	provide,
	reactive,
	ref,
	watch,
	watchEffect,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import { router } from '@inertiajs/vue3';
import { useConfirm, useToast } from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import { useConfirmOnRouteLeave } from '@/composables/useConfirmOnRouteLeave';
import { usePromiseForm } from '@/composables/usePromiseForm';
import { useProp } from '@/composables/useProp';
import { useQuery } from '@/composables/useQuery';
import type { Campaign, Segment } from '@/types';

/** What the sidebar can show: the audience segment behind the campaign. */
export type PeekItem = { type: 'segment'; id: number };

export type StepKey = 'audience' | 'content' | 'schedule' | 'review';
export type StepStatus = 'done' | 'current' | 'upcoming' | 'locked';
export type SendMode = 'now' | 'scheduled';

export const STEPS: { key: StepKey; label: string }[] = [
	{ key: 'audience', label: 'Audience' },
	{ key: 'content', label: 'Content' },
	{ key: 'schedule', label: 'Schedule' },
	{ key: 'review', label: 'Review' },
];

export interface CampaignTemplate {
	id: string;
	name: string;
	description: string;
}

export const TEMPLATES: CampaignTemplate[] = [
	{
		id: 'product-update',
		name: 'Product update',
		description: 'Hero image, feature blocks, one CTA.',
	},
	{
		id: 'newsletter',
		name: 'Newsletter',
		description: 'Multi-story digest with section dividers.',
	},
	{
		id: 'plain-text',
		name: 'Plain text',
		description: 'No chrome — reads like a personal email.',
	},
];

export const TIMEZONES = [
	{ label: 'Rome (CET)', value: 'Europe/Rome' },
	{ label: 'London (GMT)', value: 'Europe/London' },
	{ label: 'New York (ET)', value: 'America/New_York' },
	{ label: 'Chicago (CT)', value: 'America/Chicago' },
	{ label: 'Los Angeles (PT)', value: 'America/Los_Angeles' },
	{ label: 'Tokyo (JST)', value: 'Asia/Tokyo' },
	{ label: 'Sydney (AEST)', value: 'Australia/Sydney' },
];

export const COUNTRIES = [
	{ label: 'Italy', value: 'IT' },
	{ label: 'France', value: 'FR' },
	{ label: 'Germany', value: 'DE' },
	{ label: 'United Kingdom', value: 'GB' },
	{ label: 'United States', value: 'US' },
	{ label: 'Canada', value: 'CA' },
];

/** Everything the four steps edit. Persisted verbatim by saveDraft/submit.
 *
 * `type`, not `interface`: only a type alias satisfies `usePromiseForm`'s
 * `Record<string, FormValue>` constraint (implicit index signature). */
export type CampaignDraft = {
	// Audience
	segmentId: number | null;
	/** Empty array = every country in the segment. */
	countries: string[];
	/** Skip contacts already emailed in the last 7 days. */
	excludeRecent: boolean;
	// Content
	subject: string;
	preheader: string;
	body: string;
	templateId: string | null;
	// Schedule
	sendMode: SendMode;
	/** ISO string from BbDatePickerInput; only meaningful when scheduled. */
	sendAt: string | null;
	timezone: string;
};

export interface StepIssue {
	/** Draft field the issue belongs to — leaves match on it for inline errors. */
	field: string;
	message: string;
}

export interface CampaignWizardContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	// -- Wizard state ----------------------------------------------------------
	loading: Ref<boolean>;
	campaign: Ref<Campaign | null>;
	draft: CampaignDraft;
	step: Ref<StepKey>;
	dirty: ComputedRef<boolean>;
	lastSavedAt: Ref<string | null>;
	submitting: Ref<boolean>;
	// -- Validation ------------------------------------------------------------
	issues: ComputedRef<Record<StepKey, StepIssue[]>>;
	/** Steps whose Next was blocked at least once — only they show errors. */
	attempted: Record<StepKey, boolean>;
	stepStatus: (key: StepKey) => StepStatus;
	fieldErrors: (step: StepKey, field: string) => string[];
	// -- Audience intel --------------------------------------------------------
	selectedSegment: Ref<Segment | null>;
	estimatedRecipients: Ref<number | null>;
	// -- Peek grammar ----------------------------------------------------------
	peekSegment: () => void;
	// -- Actions (complete: API + state + toast) --------------------------------
	goToStep: (key: StepKey) => void;
	goBack: () => void;
	goNext: () => void;
	saveDraft: () => Promise<void>;
	sendTest: () => Promise<void>;
	submit: () => Promise<void>;
	discardDraft: () => Promise<void>;
}

const key: InjectionKey<CampaignWizardContext> = Symbol('campaign-wizard');

/** Which step owns each server-validated field — used to route a failed
 * save's `form.errors` onto the right step, merged into `issues` below. */
const FIELDS_BY_STEP: Record<StepKey, (keyof CampaignDraft)[]> = {
	audience: ['segmentId'],
	content: ['subject', 'body', 'templateId'],
	schedule: ['sendAt', 'timezone'],
	review: [],
};
const stepForField = (field: string): StepKey | undefined =>
	(Object.keys(FIELDS_BY_STEP) as StepKey[]).find((stepKey) =>
		(FIELDS_BY_STEP[stepKey] as string[]).includes(field)
	);

export function provideCampaignWizard(): CampaignWizardContext {
	const { toast } = useToast();
	const { confirm } = useConfirm();

	// -- Coopt the specific contexts: once, here, for the whole page. ----------
	const shell = usePageShellContext<PeekItem>();

	// -- Wizard state -----------------------------------------------------------
	// The record and the saved draft arrive as page props — no fetch, no
	// loading state. `usePromiseForm` seeds itself once from `draft`; every
	// further edit is local until saveDraft/submit visits the server.
	const campaign = useProp<Campaign>('campaign');
	const campaignId = campaign.value.id;
	const loading = ref(false);

	const initialDraft = useProp<CampaignDraft>('draft').value;
	const {
		form: draft,
		put,
		post,
		remove,
		isSubmitting,
	} = usePromiseForm<CampaignDraft>({ ...initialDraft });

	// -- Validation ---------------------------------------------------------------
	// Live on every keystroke; SURFACED only per `attempted` (set when a Next,
	// submit or save is blocked), so untouched steps never open covered in red.
	const issues = computed<Record<StepKey, StepIssue[]>>(() => {
		const audience: StepIssue[] = [];
		if (draft.segmentId === null)
			audience.push({
				field: 'segmentId',
				message: 'Choose the segment this campaign goes to.',
			});

		const content: StepIssue[] = [];
		if (!draft.subject.trim())
			content.push({ field: 'subject', message: 'Write a subject line.' });
		else if (draft.subject.length > 150)
			content.push({
				field: 'subject',
				message: 'Keep the subject under 150 characters.',
			});
		if (!draft.body.trim())
			content.push({
				field: 'body',
				message: 'The email body cannot be empty.',
			});
		if (draft.templateId === null)
			content.push({ field: 'templateId', message: 'Pick a template.' });

		const schedule: StepIssue[] = [];
		if (draft.sendMode === 'scheduled') {
			if (!draft.sendAt)
				schedule.push({ field: 'sendAt', message: 'Pick a send date.' });
			if (!draft.timezone)
				schedule.push({ field: 'timezone', message: 'Pick a timezone.' });
		}

		// Merge server (422) errors onto the step that owns each field —
		// `form.errors` is already reactive, so no separate bookkeeping is
		// needed, unlike a manual snapshot/errors ref.
		const withServerErrors = (
			stepKey: StepKey,
			list: StepIssue[]
		): StepIssue[] => [
			...list,
			...FIELDS_BY_STEP[stepKey]
				.filter((field) => draft.errors[field])
				.map((field) => ({ field, message: draft.errors[field] as string })),
		];

		return {
			audience: withServerErrors('audience', audience),
			content: withServerErrors('content', content),
			schedule: withServerErrors('schedule', schedule),
			review: [],
		};
	});

	const attempted = reactive<Record<StepKey, boolean>>({
		audience: false,
		content: false,
		schedule: false,
		review: false,
	});

	const fieldErrors = (stepKey: StepKey, field: string): string[] =>
		attempted[stepKey]
			? issues.value[stepKey]
					.filter((issue) => issue.field === field)
					.map((issue) => issue.message)
			: [];

	// -- Step machine ---------------------------------------------------------------
	const step = ref<StepKey>('audience');

	const indexOf = (stepKey: StepKey) =>
		STEPS.findIndex((item) => item.key === stepKey);

	// The single gating predicate: a step is reachable when every step
	// before it validates. Next, the stepper, and submit all derive from it.
	const unlocked = (stepKey: StepKey) =>
		STEPS.slice(0, indexOf(stepKey)).every(
			(item) => issues.value[item.key].length === 0
		);

	const stepStatus = (stepKey: StepKey): StepStatus => {
		if (stepKey === step.value) return 'current';
		// Only steps already passed count as done — unlocked future steps stay
		// numbered (upcoming), not checkmarked.
		if (indexOf(stepKey) < indexOf(step.value)) return 'done';
		return unlocked(stepKey) ? 'upcoming' : 'locked';
	};

	const firstIncompleteStep = (): StepKey =>
		STEPS.find((item) => issues.value[item.key].length > 0)?.key ?? 'review';

	const goToStep = (stepKey: StepKey) => {
		if (stepKey !== step.value && stepStatus(stepKey) === 'locked') return;
		step.value = stepKey;
	};

	const goBack = () => {
		const previous = STEPS[indexOf(step.value) - 1];
		if (previous) step.value = previous.key;
	};

	const goNext = () => {
		const current = step.value;
		if (issues.value[current].length > 0) {
			attempted[current] = true; // raises the alert + inline errors
			return;
		}
		attempted[current] = false;
		const next = STEPS[indexOf(current) + 1];
		if (next) step.value = next.key;
	};

	// The draft is already loaded (a page prop), so the requested step is
	// clamped synchronously here — no deferred fetch to wait on.
	const query = useQuery();
	const requestedStep = STEPS[Number(query.step) - 1]?.key ?? 'audience';
	step.value =
		stepStatus(requestedStep) === 'locked'
			? firstIncompleteStep()
			: requestedStep;

	// Mirror the step into the URL. This is pure client display state (no
	// page prop depends on it), so it updates history directly instead of
	// round-tripping through an Inertia visit.
	watch(step, (next) => {
		const url = new URL(window.location.href);
		url.searchParams.set('step', String(indexOf(next) + 1));
		window.history.replaceState(history.state, '', url);
	});

	// -- Audience intel ---------------------------------------------------------------
	// Small JSON endpoints, not Inertia visits — resolving the segment must
	// not re-render the page. Same resolve-by-id pattern as the flagship's
	// customer pill.
	const selectedSegment = ref<Segment | null>(null);
	watchEffect(async () => {
		selectedSegment.value =
			draft.segmentId === null
				? null
				: await fetch(`/segments/${draft.segmentId}`).then((res) => res.json());
	});

	const estimatedRecipients = ref<number | null>(null);
	watchEffect(async () => {
		if (draft.segmentId === null) {
			estimatedRecipients.value = null;
			return;
		}
		const params = new URLSearchParams();
		draft.countries.forEach((code) => params.append('countries[]', code));
		params.set('excludeRecent', String(draft.excludeRecent));
		estimatedRecipients.value = await fetch(
			`/segments/${draft.segmentId}/estimate?${params.toString()}`
		).then((res) => res.json());
	});

	// -- Peek grammar ----------------------------------------------------------------
	const peekSegment = () => {
		if (draft.segmentId !== null)
			shell.push({ type: 'segment', id: draft.segmentId }, true);
	};

	// -- Persistence + dirty guard ------------------------------------------------------
	const lastSavedAt = ref<string | null>(null);
	const dirty = computed(() => draft.isDirty);

	// Set right before a deliberate delete, so the guard below never
	// double-prompts on the navigate-away that follows it.
	const discarded = ref(false);

	const campaignUrl = `/campaigns/${campaignId}`;
	useConfirmOnRouteLeave({
		disabled: () => discarded.value || !dirty.value,
		whitelist: [campaignUrl, `${campaignUrl}/send`, `${campaignUrl}/send-test`],
		title: 'Leave campaign setup?',
		text: 'You have unsaved changes. Leave and lose them, or stay and save the draft.',
	});

	// -- Actions --------------------------------------------------------------------
	// After a failed save/send, form.errors is already populated by Inertia;
	// jump to whichever step owns the first offending field, same surfacing
	// as a blocked Next.
	const surfaceServerErrors = () => {
		const brokenStep = Object.keys(draft.errors)
			.map(stepForField)
			.find((found): found is StepKey => Boolean(found));
		if (brokenStep) {
			attempted[brokenStep] = true;
			step.value = brokenStep;
		}
	};

	const saveDraft = async () => {
		try {
			await put(campaignUrl);
			draft.defaults(); // re-baseline: this save is the new "clean" state
			lastSavedAt.value = new Date().toISOString();
			toast({ title: 'Draft saved.', variant: 'success' });
		} catch {
			surfaceServerErrors();
		}
	};

	const sendTest = async () => {
		if (issues.value.content.length > 0) {
			attempted.content = true; // same surfacing as a blocked Next
			return;
		}
		await post(`${campaignUrl}/send-test`);
		toast({ title: 'Test email sent to your address.', variant: 'success' });
	};

	const submit = async () => {
		// Whole-wizard validation: land the user on the first broken step.
		const incomplete = STEPS.find((item) => issues.value[item.key].length > 0);
		if (incomplete) {
			attempted[incomplete.key] = true;
			step.value = incomplete.key;
			return;
		}
		try {
			await put(campaignUrl);
			await post(`${campaignUrl}/send`);
			draft.defaults(); // the guard has nothing left to protect
			toast({
				title:
					draft.sendMode === 'now'
						? 'Campaign is on its way.'
						: 'Campaign scheduled.',
				variant: 'success',
			});
			router.visit(campaignUrl);
		} catch {
			surfaceServerErrors();
		}
	};

	const discardDraft = async () => {
		const ok = await confirm({
			variant: 'destructive',
			title: 'Discard draft',
			text: `Delete "${campaign.value?.name ?? 'this campaign'}" and everything entered so far? This cannot be undone.`,
			yes: 'Discard',
			no: 'Keep draft',
		});
		if (!ok) return;
		discarded.value = true; // don't double-prompt via the leave guard
		await remove(campaignUrl);
		toast({ title: 'Draft discarded.', variant: 'success' });
		router.visit('/campaigns');
	};

	const ctx: CampaignWizardContext = {
		shell,
		loading,
		campaign,
		draft,
		step,
		dirty,
		lastSavedAt,
		submitting: isSubmitting,
		issues,
		attempted,
		stepStatus,
		fieldErrors,
		selectedSegment,
		estimatedRecipients,
		peekSegment,
		goToStep,
		goBack,
		goNext,
		saveDraft,
		sendTest,
		submit,
		discardDraft,
	};
	provide(key, ctx);
	return ctx;
}

export function useCampaignWizard(): CampaignWizardContext {
	const ctx = inject(key);
	if (!ctx)
		throw new Error('useCampaignWizard() called outside CampaignWizard');
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- CampaignWizard/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left; save state + the destructive escape right.
		     Wizard archetype: no page search, no filter rail, no tabs. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs class="min-w-0 flex-auto" :items="crumbs" />
				<div class="flex shrink-0 items-center gap-3">
					<span
						v-if="savedLabel"
						class="text-xs text-[color:var(--bb-text-muted)]"
						>{{ savedLabel }}</span
					>
					<BbButton
						prepend:icon="lucide:trash-2"
						variant="destructive"
						@click="ctx.discardDraft"
					>
						Discard draft
					</BbButton>
				</div>
			</div>
		</template>

		<div class="mx-auto flex w-full max-w-3xl flex-col gap-5 p-4">
			<header class="flex flex-col gap-0.5">
				<h1 class="text-lg font-semibold">
					{{ ctx.campaign.value?.name ?? 'New campaign' }}
				</h1>
				<p class="text-sm text-[color:var(--bb-text-muted)]">
					Set up the audience, content and schedule, then review and send.
				</p>
			</header>

			<StepperHeader />

			<!-- One wrapper around the alert AND the step outlet: the step swap
			     and the validation summary appearing/shrinking both glide. -->
			<!-- Enable height motion only after mount so first paint does not
			     animate in; later step swaps still glide. -->
			<BbSmoothHeight :disabled="!stepHeightReady">
				<div class="flex flex-col gap-4">
					<BbAlert
						v-if="summaryIssues.length"
						hide-close
						icon="lucide:circle-x"
						:title="`Fix ${summaryIssues.length} ${summaryIssues.length === 1 ? 'issue' : 'issues'} to continue`"
						variant="destructive"
					>
						<template #text>
							<ul class="list-disc pl-4">
								<li v-for="issue in summaryIssues" :key="issue.field">
									{{ issue.message }}
								</li>
							</ul>
						</template>
					</BbAlert>

					<div v-if="ctx.loading.value" class="flex justify-center p-10">
						<BbSpinner />
					</div>
					<AudienceStep v-else-if="ctx.step.value === 'audience'" />
					<ContentStep v-else-if="ctx.step.value === 'content'" />
					<ScheduleStep v-else-if="ctx.step.value === 'schedule'" />
					<ReviewStep v-else />
				</div>
			</BbSmoothHeight>

			<WizardFooter />
		</div>

		<!-- Clicking the segment's NAME peeks it — Audience step and Review. -->
		<template #sidebar>
			<SegmentPeek
				v-if="ctx.shell.current.value?.type === 'segment'"
				:segment-id="ctx.shell.current.value.id"
			/>
		</template>
	</PageShell>
</template>

<script setup lang="ts">
import { computed, onMounted, ref } from 'vue';
import {
	BbAlert,
	BbBreadcrumbs,
	BbButton,
	BbSmoothHeight,
	BbSpinner,
} from 'bitboss-ui';
import PageShell from '@/components/layout/PageShell.vue';
import { provideCampaignWizard } from './context';
import AudienceStep from './AudienceStep.vue';
import ContentStep from './ContentStep.vue';
import ReviewStep from './ReviewStep.vue';
import ScheduleStep from './ScheduleStep.vue';
import SegmentPeek from './SegmentPeek.vue';
import StepperHeader from './StepperHeader.vue';
import WizardFooter from './WizardFooter.vue';

const ctx = provideCampaignWizard();

/** Keep SmoothHeight off while the first paint settles; enable after 300ms
 * for step-to-step glides. */
const stepHeightReady = ref(false);
onMounted(() => {
	setTimeout(() => {
		stepHeightReady.value = true;
	}, 300);
});

const crumbs = computed(() => [
	{ key: 'dashboard', text: 'Dashboard', href: '/dashboard' },
	{ key: 'campaigns', text: 'Campaigns', href: '/campaigns' },
	{ key: 'setup', text: ctx.campaign.value?.name ?? 'New campaign' },
]);

// The summary shows only the CURRENT step's issues, and only once the user
// tried to leave it — it shrinks live as each problem is fixed.
const summaryIssues = computed(() =>
	ctx.attempted[ctx.step.value] ? ctx.issues.value[ctx.step.value] : []
);

const savedLabel = computed(() => {
	if (ctx.dirty.value) return 'Unsaved changes';
	if (!ctx.lastSavedAt.value) return null;
	const time = new Date(ctx.lastSavedAt.value).toLocaleTimeString('en-US', {
		hour: 'numeric',
		minute: '2-digit',
	});
	return `Draft saved at ${time}`;
});
</script>
```

### StepperHeader.vue

```vue
<!-- CampaignWizard/StepperHeader.vue -->
<template>
	<nav aria-label="Campaign setup steps" class="flex items-center gap-1">
		<template v-for="(stepMeta, index) in STEPS" :key="stepMeta.key">
			<!-- Connector line between steps. -->
			<div
				v-if="index > 0"
				aria-hidden="true"
				class="h-px min-w-3 flex-1 bg-[var(--bb-border)]"
			/>

			<!-- The primitive gives element semantics + disabled handling; the
			     look is entirely ours. Done and upcoming steps jump, locked
			     steps are inert. -->
			<BbBaseButton
				:aria-current="status(stepMeta.key) === 'current' ? 'step' : undefined"
				class="flex items-center gap-2 rounded-[var(--bb-radius)] px-2 py-1.5 text-sm focus-visible:ring-2 focus-visible:ring-[var(--bb-primary)]"
				:class="{
					'bg-[var(--bb-hover)] font-medium':
						status(stepMeta.key) === 'current',
					'hover:bg-[var(--bb-hover)]': ['done', 'upcoming'].includes(
						status(stepMeta.key)
					),
					'text-[color:var(--bb-text-muted)]':
						status(stepMeta.key) === 'locked',
				}"
				:disabled="status(stepMeta.key) === 'locked'"
				@click="() => ctx.goToStep(stepMeta.key)"
			>
				<span
					class="flex size-5 shrink-0 items-center justify-center rounded-full border text-xs"
					:class="{
						'border-transparent bg-[var(--bb-primary)] text-[var(--bb-primary-fg)]':
							status(stepMeta.key) === 'done',
						'border-[var(--bb-primary)] text-[color:var(--bb-primary)]':
							status(stepMeta.key) === 'current',
						'border-[var(--bb-border)]': status(stepMeta.key) === 'locked',
					}"
				>
					<BbIcon
						v-if="status(stepMeta.key) === 'done'"
						icon="lucide:check"
						size="12"
					/>
					<template v-else>{{ index + 1 }}</template>
				</span>
				{{ stepMeta.label }}
			</BbBaseButton>
		</template>
	</nav>
</template>

<script setup lang="ts">
import { BbBaseButton, BbIcon } from 'bitboss-ui';
import { STEPS, useCampaignWizard, type StepKey } from './context';

const ctx = useCampaignWizard();

const status = (key: StepKey) => ctx.stepStatus(key);
</script>
```

### AudienceStep.vue

```vue
<!-- CampaignWizard/AudienceStep.vue -->
<template>
	<section class="flex flex-col gap-4">
		<div class="flex flex-col gap-0.5">
			<h2 class="text-base font-semibold">Who gets this email?</h2>
			<p class="text-sm text-[color:var(--bb-text-muted)]">
				Pick a segment, then narrow it with delivery filters.
			</p>
		</div>

		<!-- Query-aware items function: the select searches the API as you type. -->
		<BbSelect
			v-model="ctx.draft.segmentId"
			:errors="segmentErrors"
			item-text="name"
			item-value="id"
			:items="searchSegments"
			label="Segment"
			label-mode="outside"
			placeholder="Search segments…"
			required
		/>

		<!-- Resolved segment + live estimate: the context owns both fetches. -->
		<div
			v-if="ctx.selectedSegment.value"
			class="flex flex-col gap-1 rounded-[var(--bb-radius)] border p-3 text-sm"
		>
			<div class="flex items-center justify-between gap-2">
				<BbButton size="sm" variant="link" @click="ctx.peekSegment">
					{{ ctx.selectedSegment.value.name }}
				</BbButton>
				<span class="text-xs text-[color:var(--bb-text-muted)]">
					Last synced {{ shortDate(ctx.selectedSegment.value.lastSyncedAt) }}
				</span>
			</div>
			<p class="text-[color:var(--bb-text-muted)]">
				{{ number.format(ctx.selectedSegment.value.contactCount) }} contacts in
				the segment ·
				<strong class="text-[var(--bb-text)]">
					{{
						ctx.estimatedRecipients.value === null
							? '…'
							: number.format(ctx.estimatedRecipients.value)
					}}
				</strong>
				estimated recipients after filters
			</p>
		</div>

		<BbSelect
			v-model="ctx.draft.countries"
			:items="COUNTRIES"
			item-text="label"
			item-value="value"
			label="Limit to countries"
			label-mode="outside"
			multiple
			placeholder="All countries"
		/>

		<BbSwitch
			v-model="ctx.draft.excludeRecent"
			description="Avoids fatigue: anyone who already received a campaign this week is skipped."
			label="Skip contacts emailed in the last 7 days"
		/>
	</section>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbSelect, BbSwitch } from 'bitboss-ui';
import { COUNTRIES, useCampaignWizard } from './context';
import type { Segment } from '@/types';

const ctx = useCampaignWizard();

// A small JSON endpoint, not an Inertia visit — searching the segment
// picker must not re-render the page.
const searchSegments = (query: string): Promise<Segment[]> =>
	fetch(`/segments/search?q=${encodeURIComponent(query)}`).then((res) =>
		res.json()
	);

// Inline errors appear only after a blocked Next (attempted), per the context.
const segmentErrors = computed(() => ctx.fieldErrors('audience', 'segmentId'));

const number = new Intl.NumberFormat('en-US');
const shortDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
	});
</script>
```

### ContentStep.vue

```vue
<!-- CampaignWizard/ContentStep.vue -->
<template>
	<section class="flex flex-col gap-4">
		<div class="flex flex-col gap-0.5">
			<h2 class="text-base font-semibold">What does it say?</h2>
			<p class="text-sm text-[color:var(--bb-text-muted)]">
				Subject and preheader are what people see in the inbox list.
			</p>
		</div>

		<BbTextInput
			v-model="ctx.draft.subject"
			:description="`${ctx.draft.subject.length}/150 characters`"
			:errors="errorsFor('subject')"
			label="Subject line"
			label-mode="outside"
			placeholder="The July roast drop is here — 20% off subscriptions"
			required
		/>

		<BbTextInput
			v-model="ctx.draft.preheader"
			description="Optional. Shows after the subject in most inboxes — keep it under 90 characters."
			label="Preheader"
			label-mode="outside"
			placeholder="Three new single origins, roasted this week."
		/>

		<!-- Fixed rows on purpose: an auto-growing textarea inside BbSmoothHeight
		     would re-animate the outlet on every line break while typing. -->
		<BbTextarea
			v-model="ctx.draft.body"
			:errors="errorsFor('body')"
			label="Body"
			label-mode="outside"
			placeholder="Write the email…"
			required
			:rows="10"
		/>

		<BbRadioGroup
			v-model="ctx.draft.templateId"
			:errors="errorsFor('templateId')"
			item-text="name"
			item-value="id"
			:items="TEMPLATES"
			legend="Template"
			name="template"
			required
		>
			<!-- Name + one-line description per option, from the same items. -->
			<template #label="{ item, text }">
				<span class="flex flex-col">
					<span>{{ text }}</span>
					<span class="text-xs text-[color:var(--bb-text-muted)]">{{
						item.description
					}}</span>
				</span>
			</template>
		</BbRadioGroup>

		<!-- Auto-loading: the button tracks the async handler by itself. -->
		<div>
			<BbButton
				prepend:icon="lucide:send"
				variant="ghost"
				@click="ctx.sendTest"
			>
				Send test email
			</BbButton>
		</div>
	</section>
</template>

<script setup lang="ts">
import { BbButton, BbRadioGroup, BbTextarea, BbTextInput } from 'bitboss-ui';
import { TEMPLATES, useCampaignWizard } from './context';

const ctx = useCampaignWizard();

const errorsFor = (field: string) => ctx.fieldErrors('content', field);
</script>
```

### ScheduleStep.vue

```vue
<!-- CampaignWizard/ScheduleStep.vue -->
<template>
	<section class="flex flex-col gap-4">
		<div class="flex flex-col gap-0.5">
			<h2 class="text-base font-semibold">When does it go out?</h2>
			<p class="text-sm text-[color:var(--bb-text-muted)]">
				Send it as soon as you confirm, or pick a date.
			</p>
		</div>

		<BbRadioGroup
			v-model="ctx.draft.sendMode"
			item-text="label"
			item-value="value"
			:items="[
				{
					label: 'Send now — goes out as soon as you confirm on Review',
					value: 'now',
				},
				{ label: 'Schedule for later', value: 'scheduled' },
			]"
			legend="When to send"
			name="send-mode"
		/>

		<!-- No inner BbSmoothHeight: the page-level wrapper's resize observer
		     already animates this region appearing and disappearing. -->
		<div
			v-if="ctx.draft.sendMode === 'scheduled'"
			class="grid gap-4 sm:grid-cols-2"
		>
			<BbDatePickerInput
				v-model="ctx.draft.sendAt"
				description="Campaigns go out at 9:00 AM local to the timezone you pick."
				:errors="errorsFor('sendAt')"
				label="Send date"
				label-mode="outside"
				:min="today"
				required
			/>
			<BbSelect
				v-model="ctx.draft.timezone"
				:errors="errorsFor('timezone')"
				item-text="label"
				item-value="value"
				:items="TIMEZONES"
				label="Timezone"
				label-mode="outside"
				required
			/>
		</div>
	</section>
</template>

<script setup lang="ts">
import { BbDatePickerInput, BbRadioGroup, BbSelect } from 'bitboss-ui';
import { TIMEZONES, useCampaignWizard } from './context';

const ctx = useCampaignWizard();

const errorsFor = (field: string) => ctx.fieldErrors('schedule', field);

// BbDatePickerInput's min takes YYYY-MM-DD.
const today = new Date().toISOString().slice(0, 10);
</script>
```

### ReviewStep.vue

```vue
<!-- CampaignWizard/ReviewStep.vue -->
<template>
	<section class="flex flex-col gap-5">
		<div class="flex flex-col gap-0.5">
			<h2 class="text-base font-semibold">Review and send</h2>
			<p class="text-sm text-[color:var(--bb-text-muted)]">
				Everything below is what goes out. Edit any section — your progress is
				kept.
			</p>
		</div>

		<!-- Audience -->
		<section
			class="flex flex-col gap-2 rounded-[var(--bb-radius)] border p-3 text-sm"
		>
			<div class="flex items-center justify-between gap-2">
				<h3
					class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
				>
					Audience
				</h3>
				<BbButton
					prepend:icon="lucide:pencil"
					size="sm"
					variant="ghost"
					@click="() => ctx.goToStep('audience')"
				>
					Edit
				</BbButton>
			</div>
			<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
				<dt class="text-[color:var(--bb-text-muted)]">Segment</dt>
				<dd>
					<BbButton size="sm" variant="link" @click="ctx.peekSegment">
						{{ ctx.selectedSegment.value?.name ?? '—' }}
					</BbButton>
				</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Countries</dt>
				<dd>{{ countryNames || 'All countries' }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Fatigue filter</dt>
				<dd>
					{{
						ctx.draft.excludeRecent
							? 'Skipping contacts emailed in the last 7 days'
							: 'Off'
					}}
				</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Estimated recipients</dt>
				<dd class="font-medium">
					{{
						ctx.estimatedRecipients.value === null
							? '—'
							: number.format(ctx.estimatedRecipients.value)
					}}
				</dd>
			</dl>
		</section>

		<!-- Content -->
		<section
			class="flex flex-col gap-2 rounded-[var(--bb-radius)] border p-3 text-sm"
		>
			<div class="flex items-center justify-between gap-2">
				<h3
					class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
				>
					Content
				</h3>
				<BbButton
					prepend:icon="lucide:pencil"
					size="sm"
					variant="ghost"
					@click="() => ctx.goToStep('content')"
				>
					Edit
				</BbButton>
			</div>
			<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
				<dt class="text-[color:var(--bb-text-muted)]">Subject</dt>
				<dd class="font-medium">{{ ctx.draft.subject }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Preheader</dt>
				<dd>{{ ctx.draft.preheader || '—' }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Template</dt>
				<dd>{{ templateName }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Body</dt>
				<dd class="text-[color:var(--bb-text-muted)]">{{ bodyExcerpt }}</dd>
			</dl>
		</section>

		<!-- Schedule -->
		<section
			class="flex flex-col gap-2 rounded-[var(--bb-radius)] border p-3 text-sm"
		>
			<div class="flex items-center justify-between gap-2">
				<h3
					class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
				>
					Schedule
				</h3>
				<BbButton
					prepend:icon="lucide:pencil"
					size="sm"
					variant="ghost"
					@click="() => ctx.goToStep('schedule')"
				>
					Edit
				</BbButton>
			</div>
			<p>{{ scheduleSummary }}</p>
		</section>
	</section>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton } from 'bitboss-ui';
import { COUNTRIES, TEMPLATES, TIMEZONES, useCampaignWizard } from './context';

const ctx = useCampaignWizard();

const number = new Intl.NumberFormat('en-US');

const countryNames = computed(() =>
	ctx.draft.countries
		.map(
			(code) =>
				COUNTRIES.find((country) => country.value === code)?.label ?? code
		)
		.join(', ')
);

const templateName = computed(
	() =>
		TEMPLATES.find((template) => template.id === ctx.draft.templateId)?.name ??
		'—'
);

const bodyExcerpt = computed(() =>
	ctx.draft.body.length > 140
		? `${ctx.draft.body.slice(0, 140)}…`
		: ctx.draft.body
);

const scheduleSummary = computed(() => {
	if (ctx.draft.sendMode === 'now')
		return 'Sends immediately after you confirm.';
	if (!ctx.draft.sendAt) return '—';
	const date = new Date(ctx.draft.sendAt).toLocaleDateString('en-US', {
		weekday: 'short',
		month: 'short',
		day: 'numeric',
		year: 'numeric',
	});
	const zone =
		TIMEZONES.find((timezone) => timezone.value === ctx.draft.timezone)
			?.label ?? ctx.draft.timezone;
	return `Scheduled for ${date} · 9:00 AM · ${zone}`;
});
</script>
```

### WizardFooter.vue

```vue
<!-- CampaignWizard/WizardFooter.vue -->
<template>
	<footer class="flex items-center justify-between gap-2 border-t pt-4">
		<!-- Back is always free — never validated, only bounded. -->
		<BbButton
			:disabled="isFirst"
			prepend:icon="lucide:chevron-left"
			variant="ghost"
			@click="ctx.goBack"
		>
			Back
		</BbButton>

		<div class="flex items-center gap-2">
			<!-- On every step, whatever the validation state. -->
			<BbButton
				prepend:icon="lucide:save"
				variant="ghost"
				@click="ctx.saveDraft"
			>
				Save draft
			</BbButton>

			<BbButton
				v-if="!isReview"
				append:icon="lucide:chevron-right"
				variant="secondary"
				@click="ctx.goNext"
			>
				Next
			</BbButton>

			<!-- The page's single primary. -->
			<BbButton
				v-else
				:loading="ctx.submitting.value"
				prepend:icon="lucide:send"
				variant="primary"
				@click="ctx.submit"
			>
				{{
					ctx.draft.sendMode === 'now' ? 'Send campaign' : 'Schedule campaign'
				}}
			</BbButton>
		</div>
	</footer>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton } from 'bitboss-ui';
import { STEPS, useCampaignWizard } from './context';

const ctx = useCampaignWizard();

const isFirst = computed(() => ctx.step.value === STEPS[0].key);
const isReview = computed(() => ctx.step.value === 'review');
</script>
```

### SegmentPeek.vue

```vue
<!-- CampaignWizard/SegmentPeek.vue -->
<template>
	<div v-if="segment" class="flex flex-col gap-4 text-sm">
		<header class="flex flex-col gap-0.5">
			<h2 class="text-base font-semibold">{{ segment.name }}</h2>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				{{ number.format(segment.contactCount) }} contacts · last synced
				{{ longDate(segment.lastSyncedAt) }}
			</p>
		</header>

		<!-- Stat strip. -->
		<div class="grid grid-cols-3 gap-2">
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Avg. open rate</p>
				<p class="font-semibold">{{ percent(segment.openRate) }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Avg. click rate</p>
				<p class="font-semibold">{{ percent(segment.clickRate) }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					Unsubscribes / mo
				</p>
				<p class="font-semibold">
					{{ number.format(segment.monthlyUnsubscribes) }}
				</p>
			</div>
		</div>

		<!-- The segment's definition, so "who is in here" is answerable in place. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Conditions
			</h3>
			<ul class="flex flex-col gap-1">
				<li v-for="rule in segment.rules" :key="rule" class="flex gap-2">
					<BbIcon
						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
						icon="lucide:filter"
						size="14"
					/>
					<span>{{ rule }}</span>
				</li>
			</ul>
		</section>

		<!-- Recent campaigns to this segment: fatigue check before sending. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Recent campaigns
			</h3>
			<ul class="flex flex-col">
				<li
					v-for="recent in segment.recentCampaigns"
					:key="recent.id"
					class="flex items-center justify-between gap-2 border-b py-1.5 last:border-b-0"
				>
					<span>{{ recent.name }}</span>
					<span class="text-xs text-[color:var(--bb-text-muted)]">{{
						longDate(recent.sentAt)
					}}</span>
				</li>
			</ul>
		</section>

		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				append:icon="lucide:arrow-up-right"
				:href="`/segments/${segment.id}`"
				size="sm"
				variant="ghost"
			>
				Open segment
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
import { useResourceContext } from '@/composables/useResourceContext';
import type { SegmentDetail } from '@/types';

const props = defineProps<{ segmentId: number }>();

// A small JSON endpoint, not a page visit — opening the peek never
// re-renders the wizard underneath it. Re-fetches whenever the stack shows
// a different segment.
const { data: segment } = useResourceContext<SegmentDetail, number>(
	() => props.segmentId,
	(id) => fetch(`/segments/${id}/detail`).then((res) => res.json())
);

const number = new Intl.NumberFormat('en-US');
const percent = (value: number) => `${(value * 100).toFixed(1)}%`;
const longDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
		year: 'numeric',
	});
</script>
```

## Why it is built this way

- **The context coopts, leaves consume.** `shell` is joined once in
  `provideCampaignWizard()`; seven components share the draft, the step
  machine, validation and every action through one `useCampaignWizard()`
  call. The only data prop on the page is `SegmentPeek`'s `segment-id`;
  no component receives a callback.
- **One gating predicate rules everything.** `unlocked(step)` — every
  step before it validates — drives the stepper's `upcoming`/`locked`
  states, `goToStep`'s guard, and (via `issues[current]`) `goNext`. A
  stepper jump is therefore exactly as safe as pressing Next the right
  number of times; the header can never smuggle the user past validation.
  Only steps already passed count as `done` — a defaulted step (Schedule
  starts valid on "send now") stays numbered (`upcoming`), not
  checkmarked, until the user actually moves past it, though it is
  jumpable straight away: there is genuinely nothing left to do there.
- **`form.errors` is the error contract for saves, with zero extra
  bookkeeping.** It is already reactive, so `issues` simply folds it onto
  the step that owns each field (`FIELDS_BY_STEP`) — no manual
  `serverErrors` ref to clear and repopulate. A failed save renders in the
  exact same `BbAlert` summary and inline errors as a client-side block,
  and `surfaceServerErrors()` jumps the user to the first broken step.
  Field names stay camelCase (`segmentId`, not `segment_id`) to keep the
  context's shape identical across all three platforms — the `FormRequest`
  behind the mutation routes is assumed to key its messages the same way.
- **No loading state, because there is nothing to load.** `campaign` and
  `draft` arrive as page props; `usePromiseForm` seeds itself from `draft`
  once and `ctx.loading` stays `false` for the whole page's life. The
  requested `?step` is clamped **synchronously at setup** — unlike the
  Vue/Nuxt recipes, there is no fetch to wait on before it's safe to do so.
- **The step mirrors via `history.replaceState`, not a visit.** Unlike a
  tab switch on a listing page, no page prop depends on which wizard step
  is showing, so round-tripping through `router.visit` would only add
  latency and risk resetting local form edits for no benefit — a direct
  history update keeps the URL shareable at zero cost.
- **Steps are four components, not one with a `type` prop.** Each step
  owns its inputs, its formatting helpers, and nothing else; the assembly
  is a `v-if` chain inside the `BbSmoothHeight` outlet. A single
  `WizardStep` with a renderer switch is the API-monster seed.
- **`BbBaseButton` is the right stepper primitive.** The steps are
  clickable surfaces whose look is entirely bespoke — token-styled pills
  with a number/check bullet — and the primitive contributes what CSS
  can't: a real `<button>`, native `disabled` for locked steps, and a
  focus scaffold (the visible ring is ours, per its guide). `aria-current="step"`
  is set manually — the prop-based `ariaCurrentValue` only applies to
  exact-active _links_.
- **One `BbSmoothHeight`, wrapping alert + outlet.** Both height changes
  on this page — the step swap and the summary toggling — animate through
  the same wrapper, so they compose into one glide when Next is blocked.
  Regions that appear _inside_ a step (the scheduled-date grid) are caught
  by the same resize observer; and the body textarea keeps fixed `rows`
  because an auto-growing textarea inside the wrapper would re-animate the
  outlet on every line break. Height motion is enabled only after mount
  (`:disabled` until a 300ms `onMounted` flag flips), so the first paint
  never animates in.
- **The guard drives off `form.isDirty`, whitelisted against its own
  saves.** `useConfirmOnRouteLeave` reads `dirty` (an alias for
  `draft.isDirty`) and whitelists `campaignUrl` and its `/send` and
  `/send-test` children, so `saveDraft`/`sendTest`/`submit` can never
  block themselves. `draft.defaults()` re-baselines the dirty tracking
  right after a successful save/send, so the follow-up `router.visit`
  away from the page never re-prompts; `discardDraft` sets a local
  `discarded` flag before its own delete + navigate for the same reason —
  the same "nothing left to protect" guarantee the Vue/Nuxt snapshot reset
  gives, expressed with Inertia's own dirty tracking instead.
- **Sizing:** everything follows `md`-first — footer, topbar and step
  forms use default-size buttons and regular inputs; `sm` appears only on
  the dense inline surfaces (Review's Edit/segment links, the peek
  footer). One `variant="primary"` (Send/Schedule); Next is `secondary`;
  Save draft, Back and Send test are ghosts; the two destructive actions
  (discard, leave-with-changes) both ride `useConfirm`.

## Variations

- **Branching steps**: make `STEPS` a computed — e.g. an A/B test
  campaign inserts a "Variants" step after Content. The status predicate,
  URL mapping and footer already work off the array, so nothing else
  changes.
- **Autosave**: debounce a watcher on `draft` that calls a silent
  `saveDraft` (no toast); the footer button and the topbar save-state stay
  as the manual escape, and the leave guard almost never fires.
- **Vertical checklist stepper** (Mailchimp's actual layout): swap
  `StepperHeader` for a left rail where each step row also shows its
  one-line summary and the step bodies expand in place — the context and
  its predicate are unchanged.
- **Send time**: add an hour `BbSelect` beside the timezone and fold it
  into `sendAt` on save, replacing the fixed 9:00 AM policy.

---

<!-- dist/ai/recipes/nuxt/approvals-inbox.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/nuxt/approvals-inbox.md -->

# Recipe: Approvals Inbox (Nuxt)

The densest advanced-page recipe in the folder, adapted for **Nuxt**: the
same Linear-triage × Expensify-approvals expense inbox —
`keyboard-navigation` with the highlight driving the peek, one-click
approve, reject-with-reason and snooze dialogs, a floating bulk-action bar,
and an `A`/`R`/`S` shortcut bar — but filters and the active tab live in the
URL and the list loads through `useAsyncData` watching `route.query`.
Anatomy, components, the context shape, copy and data are identical to the
Vue recipe; only the data/URL/mutation layer changes.

Sibling recipes: [Vue](../vue/approvals-inbox.md) ·
[Inertia](../inertia/approvals-inbox.md).

## Prerequisites

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell`, `usePageShellContext` and `FloatingBottomPanel` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
- `<BbConfirm />` and `<BbToast />` mounted once in `app.vue` — never in a page.
- [App Layout](../../guides/app-layout.md), [Page Shell](../../guides/page-shell.md)
  and [Floating Bottom Panel](../../guides/floating-bottom-panel.md) copied
  into `src/components/layout/` per their guides — every recipe page assumes
  this chrome exists and renders inside it.
- Server routes: `GET /api/expenses` (accepts `search`, `submitterId`,
  `categories[]`, `amountOver`, `tab`, `page`, `perPage`, returns
  `{ data, total, tabCounts }`), plus the mutation routes referenced below
  (`PATCH /api/expenses/:id/approve`, `POST /api/expenses/:id/reject`,
  `PATCH /api/expenses/:id/snooze`, `PATCH /api/expenses/bulk/approve`,
  `POST /api/expenses/bulk/reject`) and small `GET /api/expenses/:id`,
  `GET /api/submitters`, `GET /api/submitters/:id` endpoints backing the
  peeks and the submitter filter pill.

## Key ideas

- **Highlight drives the peek, not a click handler.** The table gets
  `keyboard-navigation`; `ctx.table.highlighted` (the coopted **library**
  table context — unchanged from the Vue recipe, since it tracks the table
  widget, not the URL) is watched in `context.ts`, and every highlight
  change replaces the sidebar's stack with that expense — arrowing through
  rows previews each one with zero markup in `Index.vue`. Selection stays a
  fully independent axis, free for the bulk bar.
- **Filters and tab live in the URL, not in local refs.** They are seeded
  from `route.query` at setup and every change writes back through
  `navigateTo` — the page is bookmarkable and survives reload.
- **`useAsyncData` watches `route.query`.** That single watch source is the
  whole refetch trigger — filters, tab and page changes all funnel through
  the URL first, so there is exactly one fetch path.
- **One coopting page context.** `provideApprovalsInbox()` joins the
  page-shell stack and the table context once, owns filters/tab/dialogs,
  and exposes complete actions. Every leaf calls `useApprovalsInbox()` and
  nothing else.
- **Three dispatch surfaces, one set of actions.** Approve / reject /
  snooze are reachable from the row, from inside the peek, and from the
  `A`/`R`/`S` keyboard shortcuts — all three call the exact same context
  functions (`approve`, `openReject`, `openSnooze`), so there is exactly
  one place each action's fetch call, refresh and toast live.
- **Reason and date are dialogs, not confirms.** Reject needs a typed
  reason and snooze needs a date, so both open a small `BbDialog` (the
  dialog itself is the confirmation gate) — a plain `useConfirm` is
  reserved for actions that need no input.
- **The shortcut bar mirrors `useDeleteCmd`'s guard.** A small keydown
  handler in the context checks `isInteractiveElementFocused()` before
  firing — typing "reason" in the reject textarea never triggers `R`.
  Platform-neutral: identical code to the Vue and Inertia recipes.
- **Clicking a submitter's name always stacks**, from a row or from inside
  the expense peek — the back arrow appears once the stack is two deep,
  exactly the "peek vs stack" grammar of the flagship.
- **Tabs are URL filters with live counts** (`Needs approval` / `Approved`
  / `Rejected` / `All`), same shape as every other workspace in the folder.
- **Buttons are `md` by default**; `sm`/`xs` apply only where the doctrine
  allows it — table rows, the peek footers, the bulk bar, the shortcut bar.

## Page anatomy

```
ApprovalsInbox/
	Index.vue            ← assembly: PageShell slots, table, tabs, pagination
	context.ts            ← coopting page context (shell + table + URL filters + shortcuts + actions)
	FilterRail.vue         ← pill filters + clear-all
	ShortcutsHint.vue       ← A / R / S icon buttons, tooltip-labelled, act on the highlighted row
	ReceiptThumbnail.vue   ← receipt image/placeholder cell
	RowActions.vue         ← per-row approve / reject / snooze icon buttons
	SelectionBar.vue       ← bulk approve / reject in the floating bottom panel
	RejectDialog.vue       ← single-row reject, required reason
	BulkRejectDialog.vue   ← bulk reject, required reason
	SnoozeDialog.vue       ← single-row snooze, date picker
	ExpensePeek.vue         ← sidebar workbench, stack level 1 (opens from highlight)
	SubmitterPeek.vue       ← stacked peek, back arrow via the shell
```

Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
(left nav + fat footer), [Page Shell](../../guides/page-shell.md),
[Floating Bottom Panel](../../guides/floating-bottom-panel.md).

## Action inventory

| #   | Action                           | Trigger                                                | Mechanism                                                 |
| --- | -------------------------------- | ------------------------------------------------------ | --------------------------------------------------------- |
| 1   | Page search (merchant/submitter) | topbar right                                           | `filters.search` → URL → `useAsyncData` refetch           |
| 2   | Filter by submitter              | filter rail pill                                       | `BbSelectPopover` single, query-aware (`$fetch`)          |
| 3   | Filter by category               | filter rail pill                                       | `BbSelectPopover` multiple                                |
| 4   | Quick filter: amount over        | filter rail pill                                       | `BbSelectPopover` single, preset thresholds               |
| 5   | Clear filters                    | rail right (only when active)                          | context `clearFilters()`                                  |
| 6   | Switch tab                       | href tabs with counts                                  | URL + `useAsyncData` refetch                              |
| 7   | Arrow through rows               | `keyboard-navigation` roving tabindex                  | table's own Arrow/Home/End                                |
| 8   | Preview an expense               | highlight a row (click, Enter/Space, arrow-then-Enter) | `ctx.table.highlighted` watcher → `peekExpense` (replace) |
| 9   | Approve (one click)              | row icon button, peek footer, key `A`                  | `approve(expense)` — `$fetch` + `refresh()` + toast       |
| 10  | Reject with reason               | row icon button, peek footer, key `R`                  | `openReject` → `RejectDialog` (required `BbTextarea`)     |
| 11  | Snooze                           | row icon button, peek footer, key `S`                  | `openSnooze` → `SnoozeDialog` (`BbDatePickerInput`)       |
| 12  | Select rows / select all         | table checkboxes                                       | table context                                             |
| 13  | Bulk approve                     | floating bottom panel                                  | `bulkApprove()` on `table.selected`                       |
| 14  | Bulk reject with reason          | floating bottom panel                                  | `BulkRejectDialog`, destructive                           |
| 15  | Stack a submitter                | submitter cell / peek property                         | `stackSubmitter(id)` → shell stack, back arrow            |
| 16  | Stack an expense from a profile  | recent-expense row inside `SubmitterPeek`              | `stackExpense(id)` → shell stack                          |
| 17  | View full-size receipt           | peek "View receipt" link                               | navigation (`href`, new tab)                              |
| 18  | Open full expense                | peek footer                                            | navigation (`to="/expenses/:id"`)                         |
| 19  | Back / close peek                | shell chrome                                           | shell stack pop / close                                   |

Nineteen distinct actions, spanning inline one-click mutation (9),
input-gated mutation via dialog (10, 11, 14), bulk mutation (13, 14),
keyboard dispatch (7, 9, 10, 11), navigation (17, 18, 19) and contextual
drill-down (15, 16) — well past the ≥ 12 bar.

## The code

### context.ts

```ts
// ApprovalsInbox/context.ts
import {
	computed,
	inject,
	provide,
	reactive,
	ref,
	watch,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import { useMagicKeys, watchDebounced, whenever } from '@vueuse/core';
import {
	useBbTableContext,
	useConfirm,
	useToast,
	type BbTableContext,
} from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import type { Expense, ExpenseCategory } from '@/types';

/** What the stacked sidebar can show. Clicking a name pushes one of these. */
export type PeekItem =
	| { type: 'expense'; id: number }
	| { type: 'submitter'; id: number };

export type ApprovalsTab = 'needsApproval' | 'approved' | 'rejected' | 'all';

export interface ApprovalsFilters {
	search: string;
	submitterId: number | null;
	categories: ExpenseCategory[];
	/** Preset threshold from the quick filter (`50`, `100`, `250`…), or `null`. */
	amountOver: number | null;
}

type ExpenseListResponse = {
	data: Expense[];
	total: number;
	tabCounts: Record<ApprovalsTab, number>;
};

export interface ApprovalsInboxContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	table: BbTableContext;
	// -- Page-owned state --------------------------------------------------------
	filters: ApprovalsFilters;
	hasActiveFilters: ComputedRef<boolean>;
	tab: Ref<ApprovalsTab>;
	tabCounts: ComputedRef<Record<ApprovalsTab, number>>;
	dialogs: {
		reject: Ref<Expense | null>;
		bulkReject: Ref<boolean>;
		snooze: Ref<Expense | null>;
	};
	// -- Data (server-rendered, URL-driven) ---------------------------------------
	expenses: ComputedRef<Expense[]>;
	expensesPending: Ref<boolean>;
	/** The expense under the roving tabindex, resolved from the last fetch. */
	highlightedExpense: ComputedRef<Expense | null>;
	// -- Peek grammar ----------------------------------------------------------
	// (peekExpense — the highlight-driven replace — is internal to the watcher
	// below, not part of the public surface: leaves never open the peek
	// directly, only highlight drives it.)
	stackExpense: (id: number) => void;
	stackSubmitter: (id: number) => void;
	// -- Actions (complete: fetch + refresh + toast) -----------------------------
	clearFilters: () => void;
	approve: (expense: Expense) => Promise<void>;
	openReject: (expense: Expense) => void;
	reject: (expense: Expense, reason: string) => Promise<void>;
	openSnooze: (expense: Expense) => void;
	snooze: (expense: Expense, until: string) => Promise<void>;
	bulkApprove: () => Promise<void>;
	openBulkReject: () => void;
	bulkReject: (reason: string) => Promise<void>;
	// -- Keyboard-shortcut dispatch (mirrors the row/peek buttons) --------------
	approveHighlighted: () => void;
	rejectHighlighted: () => void;
	snoozeHighlighted: () => void;
}

const key: InjectionKey<ApprovalsInboxContext> = Symbol('approvals-inbox');

/** Mirrors `useDeleteCmd`'s guard: skip shortcuts while the user is typing. */
const isInteractiveElementFocused = (): boolean => {
	const active = document.activeElement;
	if (!active) return false;
	const tag = active.tagName.toLowerCase();
	if (tag === 'input' || tag === 'textarea' || tag === 'select') return true;
	return active.getAttribute('contenteditable') === 'true';
};

/** Comma-joined query value → typed array (or `[]` when absent). */
const toArray = <T = string>(value: unknown): T[] => {
	if (value == null || value === '') return [];
	const raw = Array.isArray(value) ? value : String(value).split(',');
	return raw as T[];
};

export function provideApprovalsInbox(): ApprovalsInboxContext {
	const { toast } = useToast();
	const { confirm } = useConfirm();
	const route = useRoute();

	// -- Coopt the specific contexts: once, here, for the whole page. ----------
	const shell = usePageShellContext<PeekItem>();
	const table = useBbTableContext('approvals-table', { perPage: 25 });

	// -- Filters + tab: seeded from the URL, the single source of truth. -------
	const filters = reactive<ApprovalsFilters>({
		search: (route.query.search as string) ?? '',
		submitterId: route.query.submitterId
			? Number(route.query.submitterId)
			: null,
		categories: toArray<ExpenseCategory>(route.query.categories),
		amountOver: route.query.amountOver ? Number(route.query.amountOver) : null,
	});
	const tab = ref<ApprovalsTab>(
		(route.query.tab as ApprovalsTab) ?? 'needsApproval'
	);

	const hasActiveFilters = computed(
		() =>
			filters.search !== '' ||
			filters.submitterId !== null ||
			filters.categories.length > 0 ||
			filters.amountOver !== null
	);
	const clearFilters = () => {
		filters.search = '';
		filters.submitterId = null;
		filters.categories = [];
		filters.amountOver = null;
	};

	// Every filter/tab change mirrors into the query string; `useAsyncData`
	// below watches `route.query`, so this is the whole refetch trigger.
	const syncQuery = () =>
		navigateTo({
			query: {
				search: filters.search || undefined,
				submitterId: filters.submitterId ?? undefined,
				categories: filters.categories.length
					? filters.categories.join(',')
					: undefined,
				amountOver: filters.amountOver ?? undefined,
				tab: tab.value,
			},
		});
	watchDebounced(filters, syncQuery, { deep: true, debounce: 300 });
	watch(tab, () => {
		table.page.value = 1;
		syncQuery();
	});

	// -- Data ---------------------------------------------------------------------
	const { data, pending, refresh } = useAsyncData<ExpenseListResponse>(
		'expenses',
		() =>
			$fetch<ExpenseListResponse>('/api/expenses', {
				query: {
					search: filters.search || undefined,
					submitterId: filters.submitterId ?? undefined,
					categories: filters.categories,
					amountOver: filters.amountOver ?? undefined,
					tab: tab.value,
					page: table.page.value,
					perPage: table.perPage.value,
				},
			}),
		{ watch: [() => route.query, table.page] }
	);
	const expenses = computed(() => data.value?.data ?? []);
	const expensesPending = pending;
	const tabCounts = computed(
		() =>
			data.value?.tabCounts ?? {
				needsApproval: 0,
				approved: 0,
				rejected: 0,
				all: 0,
			}
	);
	watch(
		data,
		(response) => {
			if (response) table.totalItems.value = response.total;
		},
		{ immediate: true }
	);

	const dialogs = {
		reject: ref<Expense | null>(null),
		bulkReject: ref(false),
		snooze: ref<Expense | null>(null),
	};

	// -- Peek grammar -----------------------------------------------------------------
	// peekX replaces the stack (from the list / highlight); stackX drills down.
	const peekExpense = (id: number) => shell.push({ type: 'expense', id }, true);
	const stackExpense = (id: number) => shell.push({ type: 'expense', id });
	const stackSubmitter = (id: number) => shell.push({ type: 'submitter', id });

	// Highlighting IS the peek trigger: arrowing (or clicking) a row opens it,
	// clearing the highlight closes it. `item-value="id"` on the table means
	// `table.highlighted` already holds the plain id. This reads the table
	// context, not the URL, so it is unchanged from the Vue recipe.
	watch(table.highlighted, (id) => {
		if (id == null) {
			shell.close();
		} else {
			peekExpense(id as number);
		}
	});

	const highlightedExpense = computed<Expense | null>(
		() =>
			expenses.value.find(
				(expense) => expense.id === table.highlighted.value
			) ?? null
	);

	// -- Actions ----------------------------------------------------------------------
	const clearSelection = () => {
		table.selected.value = [];
	};

	const approve = async (expense: Expense) => {
		await $fetch(`/api/expenses/${expense.id}/approve`, { method: 'PATCH' });
		await refresh();
		toast({
			title: `Approved ${expense.merchant} — $${expense.amount.toFixed(2)}.`,
			variant: 'success',
		});
	};

	const openReject = (expense: Expense) => {
		dialogs.reject.value = expense;
	};
	const reject = async (expense: Expense, reason: string) => {
		await $fetch(`/api/expenses/${expense.id}/reject`, {
			method: 'POST',
			body: { reason },
		});
		dialogs.reject.value = null;
		await refresh();
		toast({ title: `Rejected ${expense.merchant}.`, variant: 'success' });
	};

	const openSnooze = (expense: Expense) => {
		dialogs.snooze.value = expense;
	};
	const snooze = async (expense: Expense, until: string) => {
		await $fetch(`/api/expenses/${expense.id}/snooze`, {
			method: 'PATCH',
			body: { until },
		});
		dialogs.snooze.value = null;
		await refresh();
		toast({ title: `${expense.merchant} snoozed.`, variant: 'success' });
	};

	const bulkApprove = async () => {
		const ids = table.selected.value as number[];
		await $fetch('/api/expenses/bulk/approve', {
			method: 'PATCH',
			body: { ids },
		});
		clearSelection();
		await refresh();
		toast({ title: `${ids.length} expenses approved.`, variant: 'success' });
	};

	const openBulkReject = () => {
		dialogs.bulkReject.value = true;
	};
	const bulkReject = async (reason: string) => {
		const ids = table.selected.value as number[];
		const ok = await confirm({
			variant: 'destructive',
			title: 'Reject expenses',
			text: `Reject ${ids.length} expenses? The submitters are notified.`,
			yes: 'Reject',
			no: 'Cancel',
		});
		if (!ok) return;
		await $fetch('/api/expenses/bulk/reject', {
			method: 'POST',
			body: { ids, reason },
		});
		dialogs.bulkReject.value = false;
		clearSelection();
		await refresh();
		toast({ title: `${ids.length} expenses rejected.`, variant: 'success' });
	};

	// -- Keyboard-shortcut dispatch: same actions, resolved against the row
	// under the roving tabindex. Guarded exactly like `useDeleteCmd`.
	const keys = useMagicKeys();
	const withHighlighted = (run: (expense: Expense) => void) => {
		if (isInteractiveElementFocused()) return;
		if (
			dialogs.reject.value ||
			dialogs.bulkReject.value ||
			dialogs.snooze.value
		)
			return;
		const expense = highlightedExpense.value;
		if (expense) run(expense);
	};
	const approveHighlighted = () =>
		withHighlighted((expense) => void approve(expense));
	const rejectHighlighted = () => withHighlighted(openReject);
	const snoozeHighlighted = () => withHighlighted(openSnooze);

	whenever(keys['a'], approveHighlighted);
	whenever(keys['r'], rejectHighlighted);
	whenever(keys['s'], snoozeHighlighted);

	const ctx: ApprovalsInboxContext = {
		shell,
		table,
		filters,
		hasActiveFilters,
		tab,
		tabCounts,
		dialogs,
		expenses,
		expensesPending,
		highlightedExpense,
		stackExpense,
		stackSubmitter,
		clearFilters,
		approve,
		openReject,
		reject,
		openSnooze,
		snooze,
		bulkApprove,
		openBulkReject,
		bulkReject,
		approveHighlighted,
		rejectHighlighted,
		snoozeHighlighted,
	};
	provide(key, ctx);
	return ctx;
}

export function useApprovalsInbox(): ApprovalsInboxContext {
	const ctx = inject(key);
	if (!ctx)
		throw new Error('useApprovalsInbox() called outside ApprovalsInbox');
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- ApprovalsInbox/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left, page search right. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs
					class="min-w-0 flex-auto"
					:items="[
						{ key: 'dashboard', text: 'Dashboard', to: '/dashboard' },
						{ key: 'finance', text: 'Finance', to: '/finance' },
						{ key: 'approvals', text: 'Approvals' },
					]"
				/>
				<BbTextInput
					v-model="ctx.filters.search"
					autocomplete="off"
					class="shrink-0"
					clearable
					compact
					hide-label
					label="Search expenses"
					placeholder="Search merchant or submitter…"
					prepend:icon="lucide:search"
				/>
			</div>
		</template>

		<div class="flex flex-col gap-3 p-4">
			<FilterRail />

			<div class="flex items-center justify-between gap-2">
				<!-- Tabs as URL filters: counts come from the server on every fetch. -->
				<BbTabs
					v-model="ctx.tab.value"
					compact
					:items="[
						{
							key: 'needsApproval',
							label: `Needs approval · ${ctx.tabCounts.value.needsApproval}`,
							href: '?tab=needsApproval',
						},
						{
							key: 'approved',
							label: `Approved · ${ctx.tabCounts.value.approved}`,
							href: '?tab=approved',
						},
						{
							key: 'rejected',
							label: `Rejected · ${ctx.tabCounts.value.rejected}`,
							href: '?tab=rejected',
						},
						{
							key: 'all',
							label: `All · ${ctx.tabCounts.value.all}`,
							href: '?tab=all',
						},
					]"
				/>
				<ShortcutsHint />
			</div>

			<BbTable
				id="approvals-table"
				actions
				caption="Expense approvals"
				:columns="columns"
				compact
				item-value="id"
				:items="ctx.expenses.value"
				keyboard-navigation
				legend="Select expenses"
				:loading="ctx.expensesPending.value"
				loading-text="Loading expenses…"
				:row-class="rowClass"
				selectable
			>
				<template #receipt="{ item }">
					<ReceiptThumbnail :expense="item" />
				</template>

				<template #merchant="{ content }">
					<span class="font-medium">{{ content }}</span>
				</template>

				<template #submitter_name="{ item }">
					<BbButton
						size="sm"
						variant="ghost"
						@click="() => ctx.stackSubmitter(item.submitter.id)"
					>
						{{ item.submitter.name }}
					</BbButton>
				</template>

				<template #category="{ item }">
					<BbBadge variant="outline">{{ item.category }}</BbBadge>
				</template>

				<template #status="{ item }">
					<BbBadge variant="outline">{{ statusLabel(item.status) }}</BbBadge>
				</template>

				<template #actions="{ item }">
					<RowActions :expense="item" />
				</template>

				<template #no-data>
					<div class="flex flex-col items-center gap-2 p-6 text-center">
						<p class="text-sm text-[color:var(--bb-text-muted)]">
							No expenses match
							{{
								ctx.hasActiveFilters.value ? 'the current filters' : 'this tab'
							}}.
						</p>
						<BbButton
							v-if="ctx.hasActiveFilters.value"
							variant="ghost"
							@click="ctx.clearFilters"
						>
							Clear filters
						</BbButton>
					</div>
				</template>
			</BbTable>

			<BbPagination table-id="approvals-table" />
		</div>

		<SelectionBar />

		<!-- Stacked peek sidebar: highlight opens the expense; names drill down. -->
		<template #sidebar>
			<ExpensePeek
				v-if="ctx.shell.current.value?.type === 'expense'"
				:expense-id="ctx.shell.current.value.id"
			/>
			<SubmitterPeek
				v-else-if="ctx.shell.current.value?.type === 'submitter'"
				:submitter-id="ctx.shell.current.value.id"
			/>
		</template>

		<template #dialogs>
			<RejectDialog />
			<BulkRejectDialog />
			<SnoozeDialog />
		</template>
	</PageShell>
</template>

<script setup lang="ts">
import {
	BbBadge,
	BbBreadcrumbs,
	BbButton,
	BbPagination,
	BbTable,
	BbTabs,
	BbTextInput,
} from 'bitboss-ui';
import PageShell from '@/components/layout/PageShell.vue';
import { provideApprovalsInbox } from './context';
import BulkRejectDialog from './BulkRejectDialog.vue';
import ExpensePeek from './ExpensePeek.vue';
import FilterRail from './FilterRail.vue';
import ReceiptThumbnail from './ReceiptThumbnail.vue';
import RejectDialog from './RejectDialog.vue';
import RowActions from './RowActions.vue';
import SelectionBar from './SelectionBar.vue';
import ShortcutsHint from './ShortcutsHint.vue';
import SnoozeDialog from './SnoozeDialog.vue';
import SubmitterPeek from './SubmitterPeek.vue';
import type { Expense, ExpenseStatus } from '@/types';

const ctx = provideApprovalsInbox();

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
const shortDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
	});
const statusLabel = (status: ExpenseStatus) =>
	({
		needsApproval: 'Needs approval',
		approved: 'Approved',
		rejected: 'Rejected',
		snoozed: 'Snoozed',
	})[status];

const columns = [
	{ key: 'receipt', label: 'Receipt', width: 48 },
	{ key: 'merchant', label: 'Merchant' },
	{ key: 'submitter.name', label: 'Submitter' },
	{ key: 'category', label: 'Category' },
	{
		key: 'amount',
		label: 'Amount',
		align: 'right' as const,
		formatter: (value: number) => currency.format(value),
	},
	{ key: 'submittedAt', label: 'Submitted', formatter: shortDate },
	{ key: 'status', label: 'Status' },
];

// A default highlight tint ships out of the box; row-class customizes it.
const rowClass = (item: Expense) =>
	ctx.table.highlighted.value === item.id
		? 'bg-indigo-50 dark:bg-indigo-950/20'
		: undefined;
</script>
```

### FilterRail.vue

```vue
<!-- ApprovalsInbox/FilterRail.vue -->
<template>
	<div class="flex flex-wrap items-center gap-2">
		<!-- Submitter: single, query-aware search against the API. -->
		<BbSelectPopover
			v-model="ctx.filters.submitterId"
			item-text="name"
			item-value="id"
			:items="searchSubmitters"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filter by submitter"
					append:icon="lucide:chevron-down"
					size="sm"
					variant="outline"
				>
					{{ submitterLabel }}
				</BbButton>
			</template>
		</BbSelectPopover>

		<!-- Category: multi-select pill. -->
		<BbSelectPopover
			v-model="ctx.filters.categories"
			:items="['travel', 'meals', 'software', 'office', 'client', 'other']"
			multiple
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filter by category"
					append:icon="lucide:chevron-down"
					size="sm"
					variant="outline"
				>
					Category{{
						ctx.filters.categories.length
							? ` · ${ctx.filters.categories.length}`
							: ''
					}}
				</BbButton>
			</template>
		</BbSelectPopover>

		<!-- Amount over: a quick-filter pill from preset thresholds. -->
		<BbSelectPopover
			v-model="ctx.filters.amountOver"
			disable-writing
			:items="[50, 100, 250, 500, 1000]"
			width="160px"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filter by amount"
					append:icon="lucide:chevron-down"
					size="sm"
					variant="outline"
				>
					{{
						ctx.filters.amountOver
							? `Over $${ctx.filters.amountOver}`
							: 'Amount'
					}}
				</BbButton>
			</template>
		</BbSelectPopover>

		<!-- Clear-all renders only while something is active. -->
		<BbButton
			v-if="ctx.hasActiveFilters.value"
			class="ml-auto"
			prepend:icon="lucide:x"
			size="sm"
			variant="ghost"
			@click="ctx.clearFilters"
		>
			Clear filters
		</BbButton>
	</div>
</template>

<script setup lang="ts">
import { computed, ref, watchEffect } from 'vue';
import { BbButton, BbSelectPopover } from 'bitboss-ui';
import { useApprovalsInbox } from './context';
import type { Submitter } from '@/types';

const ctx = useApprovalsInbox();

// Query-aware items function: BbSelectPopover calls it with the search text.
const searchSubmitters = (query: string): Promise<Submitter[]> =>
	$fetch<Submitter[]>('/api/submitters', { query: { search: query } });

// The trigger labels itself from page state (a standalone popover with a
// seeded model stays lazy and has no resolvable `text` before first open).
const selectedSubmitter = ref<Submitter | null>(null);
watchEffect(async () => {
	selectedSubmitter.value =
		ctx.filters.submitterId == null
			? null
			: await $fetch<Submitter>(`/api/submitters/${ctx.filters.submitterId}`);
});
const submitterLabel = computed(
	() => selectedSubmitter.value?.name ?? 'Submitter'
);
</script>
```

### ShortcutsHint.vue

```vue
<!-- ApprovalsInbox/ShortcutsHint.vue -->
<template>
	<div class="flex items-center gap-1">
		<span class="mr-1 text-xs text-[color:var(--bb-text-muted)]"
			>Shortcuts</span
		>
		<BbTooltip>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Approve highlighted expense"
					:disabled="!ctx.highlightedExpense.value"
					icon="lucide:check"
					size="xs"
					variant="ghost"
					@click="ctx.approveHighlighted"
				/>
			</template>
			<span class="flex items-center gap-1.5">
				Approve
				<kbd
					class="rounded border border-current px-1 font-mono text-[10px] leading-4 opacity-75"
					>A</kbd
				>
			</span>
		</BbTooltip>
		<BbTooltip>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Reject highlighted expense"
					:disabled="!ctx.highlightedExpense.value"
					icon="lucide:x"
					size="xs"
					variant="ghost"
					@click="ctx.rejectHighlighted"
				/>
			</template>
			<span class="flex items-center gap-1.5">
				Reject
				<kbd
					class="rounded border border-current px-1 font-mono text-[10px] leading-4 opacity-75"
					>R</kbd
				>
			</span>
		</BbTooltip>
		<BbTooltip>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Snooze highlighted expense"
					:disabled="!ctx.highlightedExpense.value"
					icon="lucide:clock"
					size="xs"
					variant="ghost"
					@click="ctx.snoozeHighlighted"
				/>
			</template>
			<span class="flex items-center gap-1.5">
				Snooze
				<kbd
					class="rounded border border-current px-1 font-mono text-[10px] leading-4 opacity-75"
					>S</kbd
				>
			</span>
		</BbTooltip>
	</div>
</template>

<script setup lang="ts">
import { BbButton, BbTooltip } from 'bitboss-ui';
import { useApprovalsInbox } from './context';

const ctx = useApprovalsInbox();
</script>
```

### ReceiptThumbnail.vue

```vue
<!-- ApprovalsInbox/ReceiptThumbnail.vue -->
<template>
	<img
		v-if="expense.receiptUrl"
		:alt="`Receipt from ${expense.merchant}`"
		class="h-8 w-8 rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] object-cover"
		:src="expense.receiptUrl"
	/>
	<div
		v-else
		aria-hidden="true"
		class="flex h-8 w-8 items-center justify-center rounded-[var(--bb-radius)] border border-dashed border-[color:var(--bb-border)] text-[color:var(--bb-text-muted)]"
	>
		<BbIcon icon="lucide:receipt" size="14" />
	</div>
</template>

<script setup lang="ts">
import { BbIcon } from 'bitboss-ui';
import type { Expense } from '@/types';

defineProps<{ expense: Expense }>();
</script>
```

### RowActions.vue

```vue
<!-- ApprovalsInbox/RowActions.vue -->
<template>
	<div class="flex items-center gap-1">
		<BbTooltip text="Approve">
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Approve"
					:disabled="resolved"
					icon="lucide:check"
					size="xs"
					variant="ghost"
					@click="() => ctx.approve(expense)"
				/>
			</template>
		</BbTooltip>
		<BbTooltip text="Reject">
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Reject"
					:disabled="resolved"
					icon="lucide:x"
					size="xs"
					variant="ghost"
					@click="() => ctx.openReject(expense)"
				/>
			</template>
		</BbTooltip>
		<BbTooltip text="Snooze">
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Snooze"
					:disabled="resolved"
					icon="lucide:clock"
					size="xs"
					variant="ghost"
					@click="() => ctx.openSnooze(expense)"
				/>
			</template>
		</BbTooltip>
	</div>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbTooltip } from 'bitboss-ui';
import { useApprovalsInbox } from './context';
import type { Expense } from '@/types';

const props = defineProps<{ expense: Expense }>();

const ctx = useApprovalsInbox();

const resolved = computed(
	() =>
		props.expense.status === 'approved' || props.expense.status === 'rejected'
);
</script>
```

### RejectDialog.vue

```vue
<!-- ApprovalsInbox/RejectDialog.vue -->
<template>
	<BbDialog
		:model-value="expense !== null"
		size="sm"
		:title="expense ? `Reject — ${expense.merchant}` : ''"
		@show="reason = ''"
		@update:model-value="close"
	>
		<form
			v-if="expense"
			class="flex flex-col gap-3"
			novalidate
			@submit.prevent="submit"
		>
			<BbTextarea
				v-model="reason"
				label="Reason"
				label-mode="outside"
				placeholder="Why is this expense being rejected?"
				rows="3"
			/>
			<div class="mt-1 flex justify-end gap-2">
				<BbButton type="button" variant="ghost" @click="close">Cancel</BbButton>
				<BbButton
					:disabled="reason.trim().length < 3"
					type="submit"
					variant="destructive"
				>
					Reject expense
				</BbButton>
			</div>
		</form>
	</BbDialog>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbButton, BbDialog, BbTextarea } from 'bitboss-ui';
import { useApprovalsInbox } from './context';

const ctx = useApprovalsInbox();

// The dialog's subject lives in the page context — the row action and the
// peek's reject button both just assign it.
const expense = computed(() => ctx.dialogs.reject.value);
const close = () => {
	ctx.dialogs.reject.value = null;
};

const reason = ref('');
const submit = () =>
	expense.value ? ctx.reject(expense.value, reason.value.trim()) : undefined;
</script>
```

### BulkRejectDialog.vue

```vue
<!-- ApprovalsInbox/BulkRejectDialog.vue -->
<template>
	<BbDialog
		:model-value="ctx.dialogs.bulkReject.value"
		size="sm"
		:title="`Reject ${count} expenses`"
		@show="reason = ''"
		@update:model-value="close"
	>
		<form class="flex flex-col gap-3" novalidate @submit.prevent="submit">
			<BbTextarea
				v-model="reason"
				label="Reason"
				label-mode="outside"
				placeholder="Applied to every selected expense."
				rows="3"
			/>
			<div class="mt-1 flex justify-end gap-2">
				<BbButton type="button" variant="ghost" @click="close">Cancel</BbButton>
				<BbButton
					:disabled="reason.trim().length < 3"
					type="submit"
					variant="destructive"
				>
					Reject {{ count }} expenses
				</BbButton>
			</div>
		</form>
	</BbDialog>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbButton, BbDialog, BbTextarea } from 'bitboss-ui';
import { useApprovalsInbox } from './context';

const ctx = useApprovalsInbox();

const count = computed(() => (ctx.table.selected.value as number[]).length);
const close = () => {
	ctx.dialogs.bulkReject.value = false;
};

const reason = ref('');
const submit = () => ctx.bulkReject(reason.value.trim());
</script>
```

### SnoozeDialog.vue

```vue
<!-- ApprovalsInbox/SnoozeDialog.vue -->
<template>
	<BbDialog
		:model-value="expense !== null"
		size="xs"
		:title="expense ? `Snooze — ${expense.merchant}` : ''"
		@show="until = tomorrow"
		@update:model-value="close"
	>
		<form
			v-if="expense"
			class="flex flex-col gap-3"
			novalidate
			@submit.prevent="submit"
		>
			<BbDatePickerInput
				v-model="until"
				floating
				label="Snooze until"
				label-mode="outside"
				:min="tomorrow"
			/>
			<div class="mt-1 flex justify-end gap-2">
				<BbButton type="button" variant="ghost" @click="close">Cancel</BbButton>
				<BbButton type="submit" variant="secondary">Snooze</BbButton>
			</div>
		</form>
	</BbDialog>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbButton, BbDatePickerInput, BbDialog } from 'bitboss-ui';
import { useApprovalsInbox } from './context';

const ctx = useApprovalsInbox();

const expense = computed(() => ctx.dialogs.snooze.value);
const close = () => {
	ctx.dialogs.snooze.value = null;
};

const tomorrow = new Date(Date.now() + 86_400_000).toISOString().slice(0, 10);
const until = ref(tomorrow);
const submit = () =>
	expense.value ? ctx.snooze(expense.value, until.value) : undefined;
</script>
```

### SelectionBar.vue

```vue
<!-- ApprovalsInbox/SelectionBar.vue -->
<template>
	<FloatingBottomPanel :open="selectedCount > 0">
		<span class="px-2 text-sm">{{ selectedCount }} selected</span>
		<BbButton
			prepend:icon="lucide:check"
			size="sm"
			variant="ghost"
			@click="ctx.bulkApprove"
		>
			Approve
		</BbButton>
		<div class="floating-bottom-panel__right flex items-center gap-1">
			<BbButton size="sm" variant="destructive" @click="ctx.openBulkReject">
				Reject
			</BbButton>
			<BbButton
				aria-label="Clear selection"
				icon="lucide:x"
				size="sm"
				variant="ghost"
				@click="clearSelection"
			/>
		</div>
	</FloatingBottomPanel>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton } from 'bitboss-ui';
import FloatingBottomPanel from '@/components/layout/FloatingBottomPanel.vue';
import { useApprovalsInbox } from './context';

const ctx = useApprovalsInbox();

const selectedCount = computed(() => ctx.table.selected.value?.length ?? 0);
const clearSelection = () => {
	ctx.table.selected.value = [];
};
</script>
```

### ExpensePeek.vue

```vue
<!-- ApprovalsInbox/ExpensePeek.vue -->
<template>
	<div v-if="expense" class="flex flex-col gap-4 text-sm">
		<!-- Header: identity + amount + status. -->
		<header class="flex flex-col gap-1.5">
			<div class="flex items-center justify-between gap-2">
				<h2 class="text-base font-semibold">{{ expense.merchant }}</h2>
				<BbBadge variant="outline">{{ statusLabel(expense.status) }}</BbBadge>
			</div>
			<p class="text-xl font-semibold">{{ currency.format(expense.amount) }}</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Submitted {{ longDate(expense.submittedAt) }}
			</p>
		</header>

		<!-- Receipt: bigger than the row thumbnail, with a full-size link out. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Receipt
			</h3>
			<img
				v-if="expense.receiptUrl"
				:alt="`Receipt from ${expense.merchant}`"
				class="h-40 w-full rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] object-cover"
				:src="expense.receiptUrl"
			/>
			<p v-else class="text-xs text-[color:var(--bb-text-muted)]">
				No receipt attached.
			</p>
			<BbButton
				v-if="expense.receiptUrl"
				append:icon="lucide:arrow-up-right"
				:href="expense.receiptUrl"
				size="sm"
				target="_blank"
				variant="ghost"
			>
				View full-size receipt
			</BbButton>
		</section>

		<!-- Properties: submitter name drills DOWN — stacked peek, back arrow. -->
		<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
			<dt class="text-[color:var(--bb-text-muted)]">Submitter</dt>
			<dd>
				<!-- A person's NAME is an identity cell: an inline link, never a
				     padded button (BTG-015 / agent-contract § Inline Links). -->
				<BbBaseButton
					class="plain-link"
					@click="() => ctx.stackSubmitter(expense!.submitter.id)"
				>
					{{ expense.submitter.name }}
				</BbBaseButton>
			</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Category</dt>
			<dd class="capitalize">{{ expense.category }}</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Memo</dt>
			<dd>{{ expense.memo ?? '—' }}</dd>
		</dl>

		<!-- Activity feed. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Activity
			</h3>
			<ul class="flex flex-col gap-2">
				<li
					v-for="entry in expense.activity"
					:key="entry.id"
					class="flex gap-2"
				>
					<BbIcon
						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
						:icon="entry.icon"
						size="14"
					/>
					<div class="flex flex-col">
						<span>{{ entry.text }}</span>
						<span class="text-xs text-[color:var(--bb-text-muted)]"
							>{{ entry.actor }} · {{ longDate(entry.at) }}</span
						>
					</div>
				</li>
			</ul>
		</section>

		<!-- Peek is a workbench: the same three actions as the row, plus the real page. -->
		<footer class="mt-2 flex flex-wrap items-center gap-2 border-t pt-3">
			<BbButton
				:disabled="resolved"
				prepend:icon="lucide:check"
				size="sm"
				variant="secondary"
				@click="() => ctx.approve(expense!)"
			>
				Approve
			</BbButton>
			<BbButton
				:disabled="resolved"
				prepend:icon="lucide:x"
				size="sm"
				variant="destructive"
				@click="() => ctx.openReject(expense!)"
			>
				Reject
			</BbButton>
			<BbButton
				:disabled="resolved"
				prepend:icon="lucide:clock"
				size="sm"
				variant="outline"
				@click="() => ctx.openSnooze(expense!)"
			>
				Snooze
			</BbButton>
			<BbButton
				append:icon="lucide:arrow-up-right"
				class="ml-auto"
				size="sm"
				:to="`/expenses/${expense.id}`"
				variant="ghost"
			>
				Open full expense
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { computed, ref, watchEffect } from 'vue';
import { BbBadge, BbBaseButton, BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
import { useApprovalsInbox } from './context';
import type { ExpenseDetail, ExpenseStatus } from '@/types';

const props = defineProps<{ expenseId: number }>();

const ctx = useApprovalsInbox();

// Re-fetches whenever the stack shows a different expense; re-runs whenever
// the list refreshes too — `approve`/`reject`/`snooze` all call `refresh()`,
// which updates `ctx.expenses` and re-triggers this watcher.
const expense = ref<ExpenseDetail | null>(null);
watchEffect(async () => {
	void ctx.expenses.value;
	expense.value = await $fetch<ExpenseDetail>(
		`/api/expenses/${props.expenseId}`
	);
});

const resolved = computed(
	() =>
		expense.value?.status === 'approved' || expense.value?.status === 'rejected'
);

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
const longDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
		year: 'numeric',
	});
const statusLabel = (status: ExpenseStatus) =>
	({
		needsApproval: 'Needs approval',
		approved: 'Approved',
		rejected: 'Rejected',
		snoozed: 'Snoozed',
	})[status];
</script>
```

### SubmitterPeek.vue

```vue
<!-- ApprovalsInbox/SubmitterPeek.vue -->
<template>
	<div v-if="submitter" class="flex flex-col gap-4 text-sm">
		<header class="flex items-center gap-3">
			<BbAvatar :alt="submitter.name" :src="submitter.avatarUrl" />
			<div class="flex flex-col">
				<h2 class="text-base font-semibold">{{ submitter.name }}</h2>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					{{ submitter.email }} · {{ submitter.team }}
				</p>
			</div>
		</header>

		<!-- Stat strip. -->
		<div class="grid grid-cols-3 gap-2">
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Submitted (YTD)</p>
				<p class="font-semibold">
					{{ currency.format(submitter.totalSubmitted) }}
				</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Pending</p>
				<p class="font-semibold">{{ submitter.pendingCount }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Approval rate</p>
				<p class="font-semibold">{{ submitter.approvalRate }}%</p>
			</div>
		</div>

		<!-- Recent expenses: names drill down again — the stack keeps growing. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Recent expenses
			</h3>
			<ul class="flex flex-col">
				<li
					v-for="recent in submitter.recentExpenses"
					:key="recent.id"
					class="flex items-center justify-between gap-2 border-b py-1.5 last:border-b-0"
				>
					<BbBaseButton
						class="plain-link"
						@click="() => ctx.stackExpense(recent.id)"
					>
						{{ recent.merchant }}
					</BbBaseButton>
					<BbBadge variant="outline">{{ recent.status }}</BbBadge>
					<span class="text-xs text-[color:var(--bb-text-muted)]">{{
						currency.format(recent.amount)
					}}</span>
				</li>
			</ul>
		</section>

		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				append:icon="lucide:arrow-up-right"
				size="sm"
				:to="`/people/${submitter.id}`"
				variant="ghost"
			>
				Open profile
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { ref, watchEffect } from 'vue';
import {
	BbAvatar,
	BbBadge,
	BbBaseButton,
	BbButton,
	BbSpinner,
} from 'bitboss-ui';
import { useApprovalsInbox } from './context';
import type { SubmitterDetail } from '@/types';

const props = defineProps<{ submitterId: number }>();

const ctx = useApprovalsInbox();

const submitter = ref<SubmitterDetail | null>(null);
watchEffect(async () => {
	submitter.value = await $fetch<SubmitterDetail>(
		`/api/submitters/${props.submitterId}`
	);
});

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
</script>
```

## Why it is built this way

- **The context coopts, leaves consume.** `shell` and `table` are joined
  once in `provideApprovalsInbox()`; twelve components share filters,
  selection, highlight, the peek stack, the keyboard shortcuts and every
  action through one `useApprovalsInbox()` call.
- **Highlight is the trigger, not a bespoke click handler.** Per the
  `BbTable` guide, `highlighted` is "a parallel, UI-intent state…
  independent of selection" that ships unstyled — this recipe is exactly
  the case the guide's Row Highlight section describes: a `watch` on
  `table.highlighted` is the entire wiring between "arrow to a row" and
  "the peek is open", and `keyboard-navigation`'s Enter/Space "activate…
  through the same path as a mouse click" means the mouse and the keyboard
  share one code path for free. This is unchanged from the Vue recipe
  because it reads the **library** table context (the widget's own state),
  which has nothing to do with the URL.
- **The URL is the filter store, `useAsyncData` is the fetch.** Filters and
  tab are seeded from `route.query` once at setup, mirrored back with
  `navigateTo` on every change (debounced for free text), and
  `useAsyncData('expenses', …, { watch: [() => route.query, table.page] })`
  is the single refetch trigger — there is exactly one place data loads.
- **The table context still owns paging, selection and highlight.**
  `useBbTableContext` is unchanged from the Vue recipe: it seeds `perPage`,
  `BbPagination` joins by `table-id`, `SelectionBar` reads `table.selected`,
  and the highlight watcher reads `table.highlighted` — only the _items_
  move from an items-function to a resolved `:items` array written by the
  page's own fetch.
- **`item-value="id"`** is what lets `table.highlighted` (and
  `table.selected`) hold plain ids instead of whole objects — the keyboard
  handler and the peek both resolve the full `Expense` from `ctx.expenses`
  (the current page's fetched list), never from the table's internal row
  wrapper.
- **One dispatch path per action, three entry points.** `approve`,
  `openReject` and `openSnooze` are called identically from `RowActions`,
  `ExpensePeek`'s footer, and the `A`/`R`/`S` keyboard handlers
  (`approveHighlighted` etc. are the same functions, resolved against
  `highlightedExpense` instead of a row prop) — there is exactly one place
  each action's fetch call, `refresh()` and toast live.
- **Reason and date are dialogs, not confirms.** Per the pattern catalog,
  "anything needing input opens a `BbDialog`" — reject needs a typed
  reason, snooze needs a date, so both get a small dialog whose open-state
  is the subject itself (`ctx.dialogs.reject` holds the `Expense`, not a
  boolean). Bulk reject is destructive **and** needs input, so it layers a
  `useConfirm` on top of the dialog's own submit.
- **The shortcut guard mirrors `useDeleteCmd`.** `isInteractiveElementFocused()`
  is copied verbatim from the Inertia Helpers guide's `useDeleteCmd` (which
  the guide notes "works on any platform") so typing a rejection reason
  never fires `R`; the handler also bails while any dialog is open.
- **`peekX` vs `stackX` is the whole stack grammar**, unchanged from the
  Vue recipe: highlighting always **replaces** (`peekExpense`, `true`),
  clicking a submitter's name always **pushes** (`stackSubmitter`), and the
  shell renders the back arrow once depth > 1 — from a row, from inside
  the expense peek, or drilling back from the submitter peek's own recent
  expenses.
- **Peeks re-fetch off the list, not a manual counter.** `ExpensePeek`
  watches `ctx.expenses.value` (bumped by every `refresh()` call) instead
  of a separate `refreshKey` ref — one fewer piece of state, since the
  list's own reactivity already carries the "something changed" signal.
- **Sizing:** topbar and rail follow `md`-first; `sm`/`xs` appear exactly
  where the doctrine allows — table rows (`xs`, the densest surface), the
  shortcut bar (`xs`), the peek footers and the bulk bar (`sm`).
- **No `variant="primary"` on this page.** Triage has no "create" action —
  the one-primary-action rule is satisfied vacuously; every action here is
  either a one-click mutation, a gated mutation via dialog, or navigation.

## Variations

- **No snooze**: drop `SnoozeDialog.vue`, the `S` shortcut, and the
  `snoozed` tab state — the remaining approve/reject pair still clears the
  ≥ 12 action bar on its own via the bulk/keyboard/peek spread.
- **Auto-advance after action**: after `approve`/`reject` resolves, call
  `table.highlighted.value = nextExpenseId` (the id following the acted-on
  row in `ctx.expenses.value`) so triage keeps moving without a
  re-highlight — the classic "Superhuman" flow.
- **Per-category routing**: seed `filters.categories` from a saved view
  per approver role (a store-backed default) instead of starting empty.
- **SSR-populated peeks**: swap the peeks' `$fetch` calls for
  `useAsyncData` keyed by id if the peek content should be part of the
  server-rendered payload rather than a client-side follow-up fetch.

---

<!-- dist/ai/recipes/nuxt/command-palette.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/nuxt/command-palette.md -->

# Recipe: Command Palette (Nuxt)

`BbCommand` does not exist — the [component picker](../../guides/component-picker.md)
says to compose `BbDialog` + `BbSelectPopover`, and this recipe is that
composition, worked end to end: a `⌘K`/`Ctrl+K` shortcut (plus an optional
visible topbar trigger) opens a dialog; inside it, `BbSelectPopover`'s
search-and-pick engine — debouncing, race protection, grouping — drives a
single query against your backend and returns **grouped** results (Pages,
Records, Actions, or whatever taxonomy fits your app). Picking a result
navigates and closes the palette. No new component ships anywhere in this
recipe — it is `BbDialog` and `BbSelectPopover`'s existing engine, wired.

Sibling recipes: [Vue](../vue/command-palette.md) ·
[Inertia](../inertia/command-palette.md).

## Prerequisites

- `<BbConfirm />` and `<BbToast />` mounted once in `app.vue` — never in a
  page. `CommandPalette.vue` (below) mounts the same way, once, in the same
  root — the shortcut must work from every page, not just ones that
  remember to render it.
- A backend search endpoint that returns **grouped** results — this recipe
  assumes `GET /api/search?q=…` responding
  `{ pages: Result[], records: Result[], actions: Result[] }` where each
  `Result` is `{ id, title, subtitle?, href, icon }`. Shape it to your own
  taxonomy; only the "grouped array of navigable rows" contract matters below.

## Key ideas

- **`BbSelectPopover` is the documented tool for this.** Its own guide says
  outright: "It is the right tool for command-palette and inline-edit
  patterns." This recipe does not fight that — it gives the popover a real,
  on-screen activator inside a dialog, not a hidden one.
- **The activator must be real and visible, never `sr-only`.** `BbSelectPopover`
  closes itself when its activator's intersection ratio drops below 1 (it
  assumes an off-screen/invisible trigger means "the anchor scrolled away, so
  close"). A hidden activator forced open programmatically opens and then
  immediately auto-closes — a broken pattern worth naming so nobody reaches
  for it. This recipe's activator is a normal, painted search button sitting
  inside the open dialog, so its intersection ratio is always 1.
- **`BbSelectPopover` has no imperative `ref.open()`** (its `defineExpose` is
  empty) — the only way to open it from outside its own activator slot is a
  real DOM interaction on that activator. So the dialog's `@shown` handler
  (fires after the native `showModal()` call and initial focus — later than
  `@show`, so the trigger is guaranteed painted) calls `.click()` on our own
  template ref to the trigger button. This is not a workaround; it is how the
  popover is designed to be opened.
- **A fresh popover instance every open.** `BbSelectPopover` keeps its typed
  query and open state internally with no external reset hook. Keying the
  popover on an integer that increments on `@show` remounts it cleanly each
  time the palette opens, so a stale query from the last search never
  reappears.
- **`prefill: false`** makes the provider **search-first**: nothing loads on
  open, and the panel shows a "type to search" hint until the first
  keystroke — exactly right for a palette where browsing the full result set
  makes no sense. Debouncing (default 500ms), race protection and loading
  state are the popover's built-in guarantees; this recipe does not
  re-implement any of them.
- **Options here have no `href`/`to`.** Unlike `BbDropdown` (or `BbButton`),
  `BbSelectPopover`'s options are picked, not linked — there is no
  navigation prop to reach for. Picking updates `v-model` with the chosen
  `href`, and the `update:model-value` handler is where navigation actually
  happens — the one place in this recipe a click handler drives routing
  instead of a `to`/`href` prop, and it is the only place that could.
- **A shared `open` ref, not a prop.** `useCommandPalette()` is a tiny
  module-level singleton so both the `⌘K` shortcut and an optional visible
  topbar "Search" button flip the same state — see
  [Layout Scaffold](./layout-scaffold.md#topbar-value-pickers-account-menu-theme-warehouse)
  for the account-menu neighbourhood this typically sits in.
- **Client-only, by design.** A modal dialog is client-side UI — SSR renders
  it closed and empty, and content appears on first open, so there is
  nothing server-specific to wire here beyond the `$fetch` call itself.

## The code

### `app/composables/useCommandPalette.ts`

```ts
// app/composables/useCommandPalette.ts
import { ref } from 'vue';

// Module-level singleton: one palette per app. The `⌘K` shortcut and any
// visible "Search" trigger (topbar button, empty-state CTA, …) all flip this
// same ref instead of each owning their own boolean.
const open = ref(false);

export function useCommandPalette() {
	return { open };
}
```

### `app/components/CommandPalette.vue`

```vue
<!-- CommandPalette.vue — mount once in app.vue, alongside BbConfirm/BbToast -->
<template>
	<BbDialog v-model="open" size="lg" title="Search" @shown="onShown">
		<BbSelectPopover
			:key="instance"
			:adaptive="false"
			group-by="group"
			item-text="title"
			item-value="href"
			:items="search"
			:model-value="null"
			no-data-text="No results."
			placement="bottom-start"
			:prefill="false"
			width="100%"
			@update:model-value="onPick"
		>
			<template #activator="{ props }">
				<!-- The real, painted activator — see "Key ideas" for why it must
				     be visible, not `sr-only`. -->
				<button
					ref="triggerRef"
					v-bind="props"
					class="command-palette__trigger"
					type="button"
				>
					<BbIcon icon="lucide:search" />
					<span>Type to search…</span>
				</button>
			</template>

			<template #option="{ item }">
				<div class="command-palette__option">
					<BbIcon :icon="item.icon" />
					<div class="flex min-w-0 flex-col">
						<span class="truncate">{{ item.title }}</span>
						<span
							v-if="item.subtitle"
							class="truncate text-xs text-[color:var(--bb-text-muted)]"
						>
							{{ item.subtitle }}
						</span>
					</div>
				</div>
			</template>

			<template #no-data="{ query }">
				<p class="p-3 text-sm text-[color:var(--bb-text-muted)]">
					{{ query ? `No results for "${query}".` : 'Type to search.' }}
				</p>
			</template>
		</BbSelectPopover>
	</BbDialog>
</template>

<script setup lang="ts">
import { nextTick, ref } from 'vue';
import { useMagicKeys, whenever } from '@vueuse/core';
import { BbDialog, BbIcon, BbSelectPopover } from 'bitboss-ui';
import { useCommandPalette } from '@/composables/useCommandPalette';

interface Result {
	id: string;
	title: string;
	subtitle?: string;
	href: string;
	icon: string;
	group: 'Pages' | 'Records' | 'Actions';
}

const { open } = useCommandPalette();

// `⌘K` on Mac, `Ctrl+K` elsewhere; `preventDefault` stops the browser's own
// address-bar shortcut (Firefox/Edge) from firing alongside ours.
const keys = useMagicKeys({
	passive: false,
	onEventFired(event) {
		if (event.key === 'k' && (event.metaKey || event.ctrlKey)) {
			event.preventDefault();
		}
	},
});
whenever(keys['cmd+k'], () => (open.value = true));
whenever(keys['ctrl+k'], () => (open.value = true));

// Remounting the popover on every open (see "Key ideas") clears its typed
// query and closed state without hand-rolling a reset API it doesn't expose.
const instance = ref(0);
const triggerRef = ref<HTMLButtonElement>();
const onShown = () => {
	instance.value++;
	void nextTick(() => triggerRef.value?.click());
};

const search = async (query: string): Promise<Result[]> => {
	if (query.trim() === '') return [];
	const data = await $fetch<{
		pages: Result[];
		records: Result[];
		actions: Result[];
	}>('/api/search', { query: { q: query } });
	return [
		...data.pages.map((r) => ({ ...r, group: 'Pages' as const })),
		...data.records.map((r) => ({ ...r, group: 'Records' as const })),
		...data.actions.map((r) => ({ ...r, group: 'Actions' as const })),
	];
};

// The one place this recipe navigates from a handler instead of `to`/`href`
// — see "Key ideas": select options carry no navigation prop.
const onPick = (href: string | null) => {
	if (href == null) return;
	open.value = false;
	void navigateTo(href);
};
</script>

<style scoped>
.command-palette__trigger {
	align-items: center;
	background: var(--bb-panel);
	border: 1px solid var(--bb-border);
	border-radius: var(--bb-radius);
	color: var(--bb-text-muted);
	display: flex;
	gap: 0.5rem;
	padding: 0.5rem 0.75rem;
	width: 100%;
}

.command-palette__option {
	align-items: center;
	display: flex;
	gap: 0.5rem;
	min-width: 0;
}
</style>
```

### An optional visible trigger, anywhere

Any button can open the same palette without touching the shortcut logic —
this is the button that replaces "a top-bar link to `/search`":

```vue
<script setup lang="ts">
import { BbButton } from 'bitboss-ui';
import { useCommandPalette } from '@/composables/useCommandPalette';

const { open } = useCommandPalette();
</script>

<template>
	<BbButton
		aria-label="Search (⌘K)"
		icon="lucide:search"
		size="sm"
		variant="ghost"
		@click="open = true"
	/>
</template>
```

## Why it is built this way

- **The popover's own guide already names this use case** — reaching for
  `BbSelectPopover` here is not a stretch of its design, it is the
  documented one.
- **Visibility, not exposed imperative methods, is what opens the panel.**
  `BbSelectPopover` deliberately exposes nothing on its component ref; the
  only supported way in is a real interaction on the activator you rendered.
  Clicking a real, on-screen `triggerRef` from `@shown` **is** that
  interaction, not a bypass of it.
- **`@shown`, not `@show`.** `@show` fires the instant the model flips to
  `true`, before the dialog's native `showModal()` call and before the
  trigger is guaranteed painted; `@shown` fires after both, so the
  programmatic click always lands on a real, visible element.
- **Grouping is server-shaped, not client-invented.** `group-by="group"`
  buckets the flattened response exactly the way `BbSelect`'s "Group
  options" playbook describes — no bespoke section-rendering markup.

## Gotchas

- **Escape inside the search field closes the popover, not the dialog.**
  The search input's own `keydown.esc` handler stops propagation, so the
  first `Escape` clears/closes the panel and a second one closes the dialog.
  This mirrors most native command palettes (clear query, then dismiss) —
  do not "fix" it by removing the popover's own Escape handling.
- **`$fetch('/api/search', …)` is a placeholder route.** Swap it for your
  app's real search endpoint (a Nitro server route works well here); keep
  the grouped-array response shape or adjust
  `group-by`/`item-text`/`item-value` to match your own.
- **Do not read `text`/`selectedOptions` for the trigger label.** This
  recipe's trigger is static ("Type to search…") on purpose — a command
  palette's activator never needs to reflect a "current selection" the way a
  filter pill does.
- **`BbSelectPopover` has no `placeholder` prop.** The search field only
  carries an accessible name (from `config.locale`) — there is no visible
  placeholder text to set. The trigger's own "Type to search…" label is
  what carries that instruction, not a prop on the popover.
  </content>

---

<!-- dist/ai/recipes/nuxt/inline-edit-workspace.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/nuxt/inline-edit-workspace.md -->

# Recipe: Inline-Edit Workspace (Nuxt)

The flagship of pattern **§6.8 — autosave cells**, adapted for **Nuxt**: a
Linear-grade sprint backlog where **every cell persists itself and the page
has no Save button anywhere**. Change a status, retype a title, clear an
estimate — it is already saved, or it has already rolled back and told you.
Filters and the active tab live in the URL, the list loads through
`useAsyncData` watching `route.query`, and the optimistic overlay retires in
that fetch's `transform`; every mutation ends in `refresh()`. Anatomy,
components, the context shape, copy and data are identical to the Vue
recipe; only the data/URL/mutation layer changes.

Domain: **Sprint 24** of a product team — fourteen issues (`BB-227` …
`BB-241`), four statuses, three priorities, a six-member team (Sofia Reyes,
Jonah Weiss, Priya Natarajan, Tom Okafor, Elif Demir, Marco Bianchi).
Deliberately distinct from the invoices/members/expenses of the sibling
recipes.

## Prerequisites

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell`, `usePageShellContext` and `FloatingBottomPanel` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
  Components: [BbTable](../../BbTable.md) ·
  [BbSelectPopover](../../BbSelectPopover.md) (§ One popover per table row is
  load-bearing here) · [BbBadge](../../BbBadge.md) (the `loading` /
  `append:icon` interplay).

Guides: [Inline Edit Playbook](../../guides/inline-edit-playbook.md) (who owns
the edit — this page is the autosave answer) ·
[Design language](../../guides/design-language.md) (§ Using color, § Badges
label state) · [Page Shell](../../guides/page-shell.md) ·
[Floating Bottom Panel](../../guides/floating-bottom-panel.md).

Siblings: [vue](../vue/inline-edit-workspace.md) ·
[inertia](../inertia/inline-edit-workspace.md).

Platform assumptions: `<BbConfirm />` and `<BbToast />` mounted once in
`app.vue` — never in a page; the layout chrome from the guides copied into
`src/components/layout/`. Server routes: `GET /api/issues` (accepts
`search`, `status[]`, `priority[]`, `assignee`, `tab`, `page`, `perPage`;
returns `{ data, total, tabCounts }`); `GET /api/members` (`search`; the
team directory) and `GET /api/members/:id`; plus the mutation routes
referenced below (`PATCH /api/issues/:id`, `POST /api/issues/:id/duplicate`,
`POST /api/issues/move-to-next-sprint`, `PATCH /api/issues/bulk`,
`DELETE /api/issues/:id`).

## Key ideas

- **No Save button anywhere.** Every cell commits itself through one context
  action, `persistField(issue, key, value)` — optimistic write, single-field
  PATCH, refetch; failure rolls back just that field and toasts. Nothing on
  the page is ever "changed but unsaved", so there is no dirty ring and no
  dirty-gated button — the only transient state is _saving_, and the spinner
  carries it.
- **The optimistic overlay is page state, not cell state.** `pending` maps
  `issue.id → { field: value }` on **rung 3** of the state ladder: the grid
  cells, the peek workbench _and the fetch itself_ all read it. This is the
  deliberate contrast with the one-shot §6.1 status cell (see
  `records-workspace`), whose `saving` flag is a rung-1 local ref — in an
  autosave grid the fetch must also know what is in flight, so the flag
  cannot live inside a cell.
- **The overlay is retired in the fetch's `transform`, never when a save
  resolves** — and only for fields the response actually confirms. Retiring
  on save-resolve makes the cell flash new → old → new for the whole reload,
  because the table still holds the stale row until the refetch lands.
- **Typed inputs commit on `@change` (blur/Enter), never `v-model`.** A
  `v-model` autosave is one request per keystroke. Pickers commit on pick —
  the click already _is_ the commit.
- **One coopting page context.** `provideBacklogWorkspace()` joins the
  page-shell stack and the table context once, owns filters/tab/overlay, and
  exposes complete actions. Eleven components share everything through one
  `useBacklogWorkspace()` call — zero prop drilling.
- **Filters and tab live in the URL, not in local-only refs.** They are
  seeded from `route.query` at setup and every change mirrors back through
  `navigateTo` (debounced for free text); `useAsyncData('issues', …)`
  watching `route.query` is the single refetch trigger, and its own
  `refresh()` is the one imperative reload every mutation calls. The page is
  bookmarkable mid-triage and survives reload.
- **Options resolve once, at page level.** Status and priority are static
  module-level catalogs (fifty rows, zero requests); the assignee picker
  shares **one** query provider across every row, so unopened rows cost
  nothing.
- **Status is color, per the soft palette.** The registered `soft-*` badge
  variants label the closed status/priority sets; the internal trailing
  chevron says "clickable", and the badge's `loading` swaps the spinner into
  the chevron's place while that one field saves.
- **Buttons are `md` by default**; `sm` appears only in row actions, the
  filter pills, the peek footer and the bulk bar. Internal navigation
  (`New issue`, the peek's `Open full page`) uses `to`, Nuxt's Vue Router
  prop, instead of a raw `href`.

## Page anatomy

```
BacklogWorkspace/
	Index.vue               ← assembly: PageShell slots, table, tabs, pagination
	context.ts              ← coopts shell + table ctx; owns URL-synced filters + the pending overlay + persistField
	FilterRail.vue          ← status / priority / assignee filter pills + clear-all
	EditableTitleCell.vue   ← commit-on-blur text (@change, never v-model)
	EstimateCell.vue        ← commit-on-change number cell
	StatusCell.vue          ← editable soft badge (chevron at rest, spinner in flight)
	PriorityCell.vue        ← same grammar, its own leaf (§6.3: never one EditableCell with a type prop)
	AssigneeCell.vue        ← provider-backed people picker badge (ONE shared query fn)
	RowActions.vue          ← … dropdown: duplicate, move to next sprint, delete (confirm)
	SelectionBar.vue        ← bulk status / bulk assign / bulk move (floating bottom panel)
	IssuePeek.vue           ← peek workbench reusing the SAME Status/Priority/Assignee cells
```

Chrome assumed from the guides: `AppLayout` (left nav + fat footer),
`PageShell`, `FloatingBottomPanel`. Note what is _missing_ compared to the
records workspace: there is no dialog component and the shell's `#dialogs`
slot stays empty — on an autosave page the grid _is_ the form, so nothing
needs a modal to edit.

## Action inventory

| #   | Action                   | Trigger                            | Mechanism                                            |
| --- | ------------------------ | ---------------------------------- | ---------------------------------------------------- |
| 1   | New issue                | topbar, the page's one `primary`   | navigation (`to="/issues/new"`)                      |
| 2   | Page search              | topbar right                       | `filters.search` → URL → `useAsyncData` refetch      |
| 3   | Switch sprint tab        | href tabs with live counts         | URL + `useAsyncData` refetch                         |
| 4   | Filter by status         | rail pill                          | `BbSelectPopover` multiple over the static catalog   |
| 5   | Filter by priority       | rail pill                          | `BbSelectPopover` multiple over the static catalog   |
| 6   | Filter by assignee       | rail pill                          | the shared people provider, single select            |
| 7   | Clear filters            | rail right (only when active)      | context `clearFilters()`                             |
| 8   | Rename issue             | title cell (grid)                  | commit-on-blur `@change` → `persistField('title')`   |
| 9   | Re-estimate              | estimate cell (grid)               | commit-on-change number → `persistField('estimate')` |
| 10  | Change status            | status badge (grid **and** peek)   | pick = commit; spinner in the chevron (§6.8)         |
| 11  | Change priority          | priority badge (grid **and** peek) | same grammar, its own leaf                           |
| 12  | Reassign                 | assignee badge (grid **and** peek) | async people search; one shared provider             |
| 13  | Peek issue               | issue ref cell                     | `peekIssue(id)` → shell stack                        |
| 14  | Duplicate                | row `…` dropdown                   | context action + toast                               |
| 15  | Move to next sprint      | row `…` **and** bulk bar           | `moveToNextSprint` / `bulkMoveToNextSprint`          |
| 16  | Delete                   | row `…`, peek footer               | destructive behind `useConfirm`                      |
| 17  | Bulk set status          | bottom panel picker                | `bulkStatus` on `table.selected`                     |
| 18  | Bulk assign              | bottom panel picker                | `bulkAssign` on `table.selected`                     |
| 19  | Select rows / select all | table checkboxes                   | table context                                        |
| 20  | Open full issue          | peek footer                        | navigation (`to="/issues/:id"`)                      |
| 21  | Close peek               | shell chrome                       | shell stack close                                    |

Rows 8–12 are the recipe's reason to exist: five editable fields of three
different control kinds, each persisting itself, two of them able to be in
flight **on the same row at the same time**.

## The code

### Project setup — the soft status palette

Status and priority are small closed sets — the textbook case for the soft
semantic accents. The names are registered in the Nuxt module (that makes
them type-check as `BbBadge` variants); the CSS is the project's own,
kept in a stylesheet separate from the library defaults:

```ts
// nuxt.config.ts — the names; the library ships no CSS for them.
export default defineNuxtConfig({
	modules: ['bitboss-ui/nuxt'],
	css: ['~/assets/css/badge-variants.css'],
	bitboss: {
		iconDir: './assets/icons',
		badgeVariants: [
			'soft-gray',
			'soft-blue',
			'soft-green',
			'soft-amber',
			'soft-red',
		],
	},
});
```

```css
/* assets/css/badge-variants.css — trimmed. Canonical palette + the full
   recipe (why the selectors are doubled, why the hue lives in a local
   --accent): design-language.md § Using color. */
.bb-badge.bb-badge--soft-gray {
	--accent: #64748b;
}
.bb-badge.bb-badge--soft-blue {
	--accent: #2563eb;
}
.bb-badge.bb-badge--soft-green {
	--accent: #16a34a;
}
.bb-badge.bb-badge--soft-amber {
	--accent: #d97706;
}
.bb-badge.bb-badge--soft-red {
	--accent: #dc2626;
}

.bb-badge.bb-badge--soft-gray,
.bb-badge.bb-badge--soft-blue,
.bb-badge.bb-badge--soft-green,
.bb-badge.bb-badge--soft-amber,
.bb-badge.bb-badge--soft-red {
	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
	--border-width: 1px;
	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
}
```

### context.ts

```ts
// BacklogWorkspace/context.ts
import {
	computed,
	inject,
	provide,
	reactive,
	ref,
	watch,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import {
	useBbTableContext,
	useConfirm,
	useToast,
	type BadgeVariantType,
	type BbTableContext,
} from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import { watchDebounced } from '@vueuse/core';
import type { Issue, IssuePriority, IssueStatus, Member } from '@/types';

/** What the peek sidebar can show. Clicking an issue ref pushes one of these. */
export type PeekItem = { type: 'issue'; id: string };

export type SprintTab = 'backlog' | 'current' | 'done';

/**
 * Exactly what a save can carry: the subset of Issue the user edits inline.
 * Five fields of three control kinds on purpose — the pattern only proves
 * itself once a row can be PARTIALLY in flight (title saving while the same
 * row's status saves), once a field is backed by a search (assignee), and
 * once a field changes on every keystroke (title, estimate).
 */
export type IssuePatch = Partial<
	Pick<Issue, 'title' | 'estimate' | 'status' | 'priority' | 'assignee'>
>;
export type EditableKey = keyof IssuePatch;

export interface BacklogFilters {
	search: string;
	status: IssueStatus[];
	priority: IssuePriority[];
	/** The whole member, not an id — the pill labels itself with zero fetches. */
	assignee: Member | null;
}

type IssueListResponse = {
	data: Issue[];
	total: number;
	tabCounts: Record<SprintTab, number>;
};

// -- Option catalogs: resolved once, at module level, for the whole page. ----
// Static arrays cost fifty rows zero requests; a per-row provider would cost
// one request per opened row (BbSelectPopover § One popover per table row).
export const STATUS_OPTIONS: { value: IssueStatus; label: string }[] = [
	{ value: 'open', label: 'Open' },
	{ value: 'in-progress', label: 'In progress' },
	{ value: 'blocked', label: 'Blocked' },
	{ value: 'done', label: 'Done' },
];
export const PRIORITY_OPTIONS: { value: IssuePriority; label: string }[] = [
	{ value: 'high', label: 'High' },
	{ value: 'normal', label: 'Normal' },
	{ value: 'low', label: 'Low' },
];

// Status/priority are small closed sets — the textbook case for the soft
// accents (design-language.md § Using color). Registered in nuxt.config.ts.
export const STATUS_VARIANT: Record<IssueStatus, BadgeVariantType> = {
	open: 'soft-gray',
	'in-progress': 'soft-blue',
	blocked: 'soft-red',
	done: 'soft-green',
};
export const PRIORITY_VARIANT: Record<IssuePriority, BadgeVariantType> = {
	high: 'soft-amber',
	normal: 'secondary',
	low: 'outline',
};

/**
 * `id: null` is the real "Unassigned" option, not an absence. The assignee is
 * stored on the row as the whole member, so a row's badge always labels
 * itself from its own data — no client-side directory cache, and the trigger
 * never depends on the picker having loaded.
 */
export const UNASSIGNED: Member = { id: null, name: 'Unassigned' };

/**
 * ONE query provider shared by every assignee picker on the page — each
 * row's cell, the peek's cell, the rail pill and the bulk-assign picker.
 * Providers are lazy, so a row nobody opens costs nothing. Contract
 * (fetch-items-playbook): component-initiated calls (`prefill === true`) and
 * an empty query return the whole team — six people, one cheap request — so
 * the current selection always stays resolvable; typed queries search.
 */
export const searchMembers = async (
	query: string,
	prefill: boolean
): Promise<Member[]> => {
	const q = query.trim();
	const members = await $fetch<Member[]>('/api/members', {
		query: prefill || !q ? {} : { search: q },
	});
	return [UNASSIGNED, ...members];
};

export interface BacklogWorkspaceContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	table: BbTableContext;
	// -- Page-owned state (URL-synced) -------------------------------------------
	filters: BacklogFilters;
	hasActiveFilters: ComputedRef<boolean>;
	tab: Ref<SprintTab>;
	tabCounts: ComputedRef<Record<SprintTab, number>>;
	// -- The autosave overlay (§6.8) --------------------------------------------
	/**
	 * Optimistic values per row PER FIELD, held until the server's own data
	 * carries them. Reactive. Rung 3 on purpose: the cells, the peek and
	 * the fetch's transform all read it. Cells never touch it directly —
	 * they go through `valueOf` / `isSaving`.
	 */
	pending: Record<string, IssuePatch>;
	/** Fields whose last save failed, keyed `${id}:${field}`. */
	failed: Readonly<Ref<Set<string>>>;
	/** Read-through: the overlay wins, the row is the fallback. */
	valueOf: <K extends EditableKey>(issue: Issue, key: K) => Issue[K];
	/** Whether THIS field of THIS row has a save in flight. */
	isSaving: (issue: Issue, key: EditableKey) => boolean;
	/** The one write path every cell commits through. */
	persistField: <K extends EditableKey>(
		issue: Issue,
		key: K,
		value: Issue[K]
	) => Promise<void>;
	// -- Data (URL-driven; the fetch's transform retires the overlay) ------------
	issues: ComputedRef<Issue[]>;
	issuesPending: Ref<boolean>;
	// -- Peek ------------------------------------------------------------------
	peekIssue: (id: string) => void;
	// -- Actions (complete: API + refresh + toast) ------------------------------
	clearFilters: () => void;
	duplicateIssue: (issue: Issue) => Promise<void>;
	moveToNextSprint: (issue: Issue) => Promise<void>;
	deleteIssue: (issue: Issue) => Promise<void>;
	bulkStatus: (status: IssueStatus) => Promise<void>;
	bulkAssign: (assignee: Member) => Promise<void>;
	bulkMoveToNextSprint: () => Promise<void>;
}

const key: InjectionKey<BacklogWorkspaceContext> = Symbol('backlog-workspace');

/** Comma-joined query value → string[] (or null when absent). */
const toArray = (value: unknown): string[] | null => {
	if (value == null || value === '') return null;
	return Array.isArray(value) ? value.map(String) : String(value).split(',');
};

export function provideBacklogWorkspace(): BacklogWorkspaceContext {
	const { toast } = useToast();
	const { confirm } = useConfirm();
	const route = useRoute();

	// -- Coopt the specific contexts: once, here, for the whole page. ----------
	const shell = usePageShellContext<PeekItem>();
	const table = useBbTableContext('backlog-table', { perPage: 25 });

	// -- Filters + tab: seeded from the URL, the single source of truth. -------
	const filters = reactive<BacklogFilters>({
		search: (route.query.search as string) ?? '',
		status: (toArray(route.query.status) ?? []) as IssueStatus[],
		priority: (toArray(route.query.priority) ?? []) as IssuePriority[],
		assignee: null, // resolved from the URL just below
	});
	const tab = ref<SprintTab>((route.query.tab as SprintTab) ?? 'current');

	// The URL carries the assignee as an id (`none` = the real Unassigned
	// option, whose id is null). Rows store the whole member, so this one-time
	// resolution exists only so a deep link into a filtered view can label the
	// pill — nothing else on the page ever resolves an id to a name.
	if (route.query.assignee === 'none') {
		filters.assignee = UNASSIGNED;
	} else if (route.query.assignee) {
		$fetch<Member>(`/api/members/${route.query.assignee}`).then((member) => {
			filters.assignee = member;
		});
	}

	const hasActiveFilters = computed(
		() =>
			filters.search !== '' ||
			filters.status.length > 0 ||
			filters.priority.length > 0 ||
			filters.assignee !== null
	);

	const clearFilters = () => {
		filters.search = '';
		filters.status = [];
		filters.priority = [];
		filters.assignee = null;
	};

	// Every filter/tab change mirrors into the query string; `useAsyncData`
	// below watches `route.query`, so this is the whole refetch trigger.
	const syncQuery = () =>
		navigateTo({
			query: {
				search: filters.search || undefined,
				status: filters.status.length ? filters.status.join(',') : undefined,
				priority: filters.priority.length
					? filters.priority.join(',')
					: undefined,
				assignee:
					filters.assignee === null
						? undefined
						: (filters.assignee.id ?? 'none'),
				tab: tab.value,
			},
		});
	watchDebounced(filters, syncQuery, { deep: true, debounce: 300 });
	watch(tab, () => {
		table.page.value = 1;
		syncQuery();
	});

	// -- The autosave overlay -----------------------------------------------------
	const pending = reactive<Record<string, IssuePatch>>({});
	const failed = ref(new Set<string>());

	const valueOf = <K extends EditableKey>(issue: Issue, key: K): Issue[K] => {
		const patch = pending[issue.id];
		// `key in patch`, not `patch[key] ?? issue[key]`: null is a legitimate
		// committed value here (a cleared estimate), and `??` would drop that
		// overlay and show the stale row value while the save runs.
		return patch && key in patch ? (patch[key] as Issue[K]) : issue[key];
	};

	const isSaving = (issue: Issue, key: EditableKey): boolean => {
		const patch = pending[issue.id];
		return patch !== undefined && key in patch;
	};

	// -- Data ---------------------------------------------------------------------
	// The one place the list loads. `route.query` is the single watch source —
	// filters, tab and page changes all funnel through the URL first. The
	// overlay owns the name `pending` on this page, so the fetch's own flag
	// lands as `issuesPending`.
	const {
		data,
		pending: issuesPending,
		refresh,
	} = useAsyncData<IssueListResponse>(
		'issues',
		() =>
			$fetch<IssueListResponse>('/api/issues', {
				query: {
					search: filters.search || undefined,
					status: filters.status,
					priority: filters.priority,
					assignee:
						filters.assignee === null
							? undefined
							: (filters.assignee.id ?? 'none'),
					tab: tab.value,
					page: table.page.value,
					perPage: table.perPage.value,
				},
			}),
		{
			watch: [() => route.query, table.page],
			// Retire the overlay HERE — in the transform, where the fresh rows
			// materialize — not when a save resolves, and only the fields this
			// response actually CONFIRMS. Between a save landing and this
			// reload arriving, the table still holds the OLD row; clearing the
			// overlay early makes the cell revert to the stale value for the
			// whole reload — visibly, new → old → new. A field still in flight
			// (the response doesn't carry its value yet) is left alone.
			transform: (response: IssueListResponse) => {
				for (const issue of response.data) {
					const patch = pending[issue.id];
					if (!patch) continue;
					for (const field of Object.keys(patch) as EditableKey[]) {
						if (JSON.stringify(patch[field]) === JSON.stringify(issue[field])) {
							delete patch[field]; // the server's own data carries it now
						}
					}
					if (!Object.keys(patch).length) delete pending[issue.id];
				}
				return response;
			},
		}
	);
	const issues = computed(() => data.value?.data ?? []);
	const tabCounts = computed(
		() => data.value?.tabCounts ?? { backlog: 0, current: 0, done: 0 }
	);
	// Paging totals come back on every fetch and land in the table context.
	watch(
		data,
		(response) => {
			if (response) table.totalItems.value = response.total;
		},
		{ immediate: true }
	);

	/** Human labels for the editable fields — used in the autosave/undo toasts. */
	const FIELD_LABELS: Record<EditableKey, string> = {
		title: 'title',
		estimate: 'estimate',
		status: 'status',
		priority: 'priority',
		assignee: 'assignee',
	};

	/**
	 * The complete autosave action, one per commit, for every control kind:
	 * no-op guard → snapshot-for-undo → optimistic set → single-field PATCH →
	 * refetch. On failure it deletes JUST this field from the overlay (the cell
	 * snaps back — a second field of the same row still in flight is untouched)
	 * and toasts destructive.
	 *
	 * On SUCCESS it fires a soft "Undo" toast: every inline edit is one click from
	 * reverting, the old value PATCHed back (and re-doable, since Undo is itself a
	 * persistField call). The Undo action must RE-RESOLVE the row by id — the
	 * `issue` captured in the closure goes stale after the refetch, and the no-op
	 * guard would then compare the revert against the stale value and swallow it.
	 */
	const persistField = async <K extends EditableKey>(
		issue: Issue,
		key: K,
		value: Issue[K]
	): Promise<void> => {
		// Snapshot what the user SEES right now — the value Undo restores.
		const previous = valueOf(issue, key);
		// No-op-commit guard: a blur without a change, or re-picking the on-screen
		// value, must not fire a request.
		if (JSON.stringify(value) === JSON.stringify(previous)) return;

		const flag = `${issue.id}:${key}`;
		(pending[issue.id] ??= {})[key] = value; // optimistic: the UI moves NOW
		failed.value.delete(flag);
		try {
			await $fetch(`/api/issues/${issue.id}`, {
				method: 'PATCH',
				body: { [key]: value } as IssuePatch,
			});
			// Reload — but do NOT retire the overlay here. The useAsyncData
			// transform drops it once the server's own data carries the value
			// (see above).
			await refresh();
			// Auto-undo: soft confirmation the edit can reverse in one click.
			toast({
				title: `${issue.ref}: ${FIELD_LABELS[key]} updated`,
				variant: 'success',
				actions: [
					{
						text: 'Undo',
						'prepend:icon': 'lucide:undo-2',
						onClick: () => {
							const current =
								issues.value.find((r) => r.id === issue.id) ?? issue;
							return persistField(current, key, previous);
						},
					},
				],
			});
		} catch {
			// Rollback: drop just this field.
			const patch = pending[issue.id];
			if (patch) {
				delete patch[key];
				if (!Object.keys(patch).length) delete pending[issue.id];
			}
			failed.value.add(flag);
			toast({
				title: `Couldn't save the ${key} of ${issue.ref} — reverted.`,
				variant: 'destructive',
			});
		}
	};

	// -- Peek ------------------------------------------------------------------------
	// One record type on this page, so the grammar is one verb: fresh stack.
	const peekIssue = (id: string) => shell.push({ type: 'issue', id }, true);

	// -- Discrete actions (row `…`, bulk bar) -------------------------------------
	// These are ordinary complete actions, records-workspace style: they
	// mutate whole rows, not single fields, so they bypass the overlay and
	// simply `refresh()` — and being discrete (not a blur), they DO toast
	// success.
	const duplicateIssue = async (issue: Issue) => {
		const copy = await $fetch<Issue>(`/api/issues/${issue.id}/duplicate`, {
			method: 'POST',
		});
		await refresh();
		toast({ title: `Duplicated as ${copy.ref}.`, variant: 'success' });
	};

	const moveToNextSprint = async (issue: Issue) => {
		await $fetch('/api/issues/move-to-next-sprint', {
			method: 'POST',
			body: { ids: [issue.id] },
		});
		await refresh();
		toast({ title: `${issue.ref} moved to Sprint 25.`, variant: 'success' });
	};

	const deleteIssue = async (issue: Issue) => {
		const ok = await confirm({
			variant: 'destructive',
			title: 'Delete issue',
			text: `Delete ${issue.ref} — “${issue.title}”? This cannot be undone.`,
			yes: 'Delete',
			no: 'Cancel',
		});
		if (!ok) return;
		await $fetch(`/api/issues/${issue.id}`, { method: 'DELETE' });
		await refresh();
		toast({ title: `${issue.ref} deleted.`, variant: 'success' });
	};

	// Bulk actions read and clear the coopted table context themselves.
	const bulkIds = (): string[] => table.selected.value;
	const clearSelection = () => {
		table.selected.value = [];
	};

	const bulkStatus = async (status: IssueStatus) => {
		const ids = bulkIds();
		await $fetch('/api/issues/bulk', {
			method: 'PATCH',
			body: { ids, patch: { status } },
		});
		clearSelection();
		await refresh();
		const label = STATUS_OPTIONS.find((o) => o.value === status)?.label;
		toast({
			title: `${ids.length} issues moved to ${label}.`,
			variant: 'success',
		});
	};

	const bulkAssign = async (assignee: Member) => {
		const ids = bulkIds();
		await $fetch('/api/issues/bulk', {
			method: 'PATCH',
			body: { ids, patch: { assignee } },
		});
		clearSelection();
		await refresh();
		toast({
			title: `${ids.length} issues assigned to ${assignee.name}.`,
			variant: 'success',
		});
	};

	const bulkMoveToNextSprint = async () => {
		const ids = bulkIds();
		await $fetch('/api/issues/move-to-next-sprint', {
			method: 'POST',
			body: { ids },
		});
		clearSelection();
		await refresh();
		toast({
			title: `${ids.length} issues moved to Sprint 25.`,
			variant: 'success',
		});
	};

	const ctx: BacklogWorkspaceContext = {
		shell,
		table,
		filters,
		hasActiveFilters,
		tab,
		tabCounts,
		pending,
		failed,
		valueOf,
		isSaving,
		persistField,
		issues,
		issuesPending,
		peekIssue,
		clearFilters,
		duplicateIssue,
		moveToNextSprint,
		deleteIssue,
		bulkStatus,
		bulkAssign,
		bulkMoveToNextSprint,
	};
	provide(key, ctx);
	return ctx;
}

export function useBacklogWorkspace(): BacklogWorkspaceContext {
	const ctx = inject(key);
	if (!ctx)
		throw new Error('useBacklogWorkspace() called outside BacklogWorkspace');
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- BacklogWorkspace/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left, page search + primary action right. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs
					class="min-w-0 flex-auto"
					:items="[
						{ key: 'product', text: 'Product', to: '/product' },
						{ key: 'sprints', text: 'Sprints', to: '/sprints' },
						{ key: 'sprint-24', text: 'Sprint 24' },
					]"
				/>
				<div class="flex shrink-0 items-center gap-2">
					<!-- `label` is required across the input family; `hide-label`
					     keeps the accessible name while hiding it visually. -->
					<BbTextInput
						v-model="ctx.filters.search"
						autocomplete="off"
						clearable
						compact
						hide-label
						label="Search issues"
						placeholder="Search ref or title…"
						prepend:icon="lucide:search"
					/>
					<BbButton
						prepend:icon="lucide:plus"
						to="/issues/new"
						variant="primary"
					>
						New issue
					</BbButton>
				</div>
			</div>
		</template>

		<div class="flex flex-col gap-3 p-4">
			<FilterRail />

			<!-- Tabs as URL filters: href updates the query, the key feeds the
			     fetch. Counts come back from the server on every fetch. -->
			<BbTabs
				v-model="ctx.tab.value"
				compact
				:items="[
					{
						key: 'backlog',
						label: `Backlog · ${ctx.tabCounts.value.backlog}`,
						href: '?tab=backlog',
					},
					{
						key: 'current',
						label: `Current sprint · ${ctx.tabCounts.value.current}`,
						href: '?tab=current',
					},
					{
						key: 'done',
						label: `Done · ${ctx.tabCounts.value.done}`,
						href: '?tab=done',
					},
				]"
			/>

			<!-- `interactive-while-loading`: autosave bumps `refreshKey` after every
			     commit, and loading rows are `inert` by default — without it,
			     saving one cell freezes the editor you already opened two rows
			     down (BbTable guide § Loading and empty states). -->
			<BbTable
				id="backlog-table"
				v-model:highlighted="highlightedIssue"
				actions
				caption="Sprint 24 backlog"
				:columns="columns"
				compact
				item-value="id"
				:items="ctx.issues.value"
				legend="Sprint 24 backlog issues"
				:loading="ctx.issuesPending.value"
				interactive-while-loading
				loading-text="Loading issues…"
				:row-class="rowClass"
				selectable
			>
				<!-- The ref is the peek handle — the title can't be, it's an input.
				     `.plain-link` is the project-owned inline-link helper
				     (design-language.md § Guide helper), not a BbButton variant. -->
				<template #ref="{ item, content }">
					<BbBaseButton
						class="plain-link font-semibold"
						@click="() => ctx.peekIssue(item.id)"
					>
						{{ content }}
					</BbBaseButton>
				</template>

				<!-- Five self-persisting cells, three control kinds, one leaf each. -->
				<template #title="{ item }">
					<EditableTitleCell :issue="item" />
				</template>

				<template #estimate="{ item }">
					<EstimateCell :issue="item" />
				</template>

				<template #status="{ item }">
					<StatusCell :issue="item" />
				</template>

				<template #priority="{ item }">
					<PriorityCell :issue="item" />
				</template>

				<template #assignee="{ item }">
					<AssigneeCell :issue="item" />
				</template>

				<template #actions="{ item }">
					<RowActions :issue="item" />
				</template>

				<template #no-data>
					<div class="flex flex-col items-center gap-2 p-6 text-center">
						<p class="text-sm text-[color:var(--bb-text-muted)]">
							No issues match
							{{
								ctx.hasActiveFilters.value ? 'the current filters' : 'this tab'
							}}.
						</p>
						<BbButton
							v-if="ctx.hasActiveFilters.value"
							variant="ghost"
							@click="ctx.clearFilters"
						>
							Clear filters
						</BbButton>
					</div>
				</template>
			</BbTable>

			<!-- Joins the table context by id: no page/totalPages wiring at all. -->
			<BbPagination table-id="backlog-table" />
		</div>

		<SelectionBar />

		<!-- Peek sidebar: the shell owns close; we render by type. -->
		<template #sidebar>
			<IssuePeek
				v-if="ctx.shell.current.value?.type === 'issue'"
				:issue-id="ctx.shell.current.value.id"
			/>
		</template>

		<!-- Deliberately no #dialogs content: every mutation on this page is
		     inline. The grid is the form. -->
	</PageShell>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import {
	BbBaseButton,
	BbBreadcrumbs,
	BbButton,
	BbPagination,
	BbTable,
	BbTabs,
	BbTextInput,
} from 'bitboss-ui';
import PageShell from '@/components/layout/PageShell.vue';
import { provideBacklogWorkspace } from './context';
import AssigneeCell from './AssigneeCell.vue';
import EditableTitleCell from './EditableTitleCell.vue';
import EstimateCell from './EstimateCell.vue';
import FilterRail from './FilterRail.vue';
import IssuePeek from './IssuePeek.vue';
import PriorityCell from './PriorityCell.vue';
import RowActions from './RowActions.vue';
import SelectionBar from './SelectionBar.vue';
import StatusCell from './StatusCell.vue';
import type { Issue } from '@/types';

const ctx = provideBacklogWorkspace();

// Row highlight tracks the open peek — the peeked row stays marked, and
// highlighting a row opens its peek; clearing the highlight closes it.
const highlightedIssue = computed<string | null>({
	get: () =>
		ctx.shell.current.value?.type === 'issue'
			? ctx.shell.current.value.id
			: null,
	set: (id) => {
		if (id == null) ctx.shell.close();
		else ctx.peekIssue(id);
	},
});

const columns = [
	{ key: 'ref', label: 'Ref', width: 90 },
	{ key: 'title', label: 'Title' },
	{ key: 'estimate', label: 'Est.', width: 90 },
	{ key: 'status', label: 'Status', width: 170 },
	{ key: 'priority', label: 'Priority', width: 140 },
	{ key: 'assignee', label: 'Assignee', width: 200 },
];

// Blocked rows get a tinted background — public row-class API, no internals.
// Even the tint reads THROUGH the overlay: unblock an issue and the row
// clears the moment the pick commits, not when the refetch lands.
const rowClass = (item: Issue) =>
	ctx.valueOf(item, 'status') === 'blocked'
		? 'bg-red-50 dark:bg-red-950/20'
		: undefined;
</script>
```

### FilterRail.vue

```vue
<!-- BacklogWorkspace/FilterRail.vue -->
<template>
	<div class="flex flex-wrap items-center gap-2">
		<!-- Status: multi-select pill over the same static catalog the cells use.
		     `disable-writing` means there's no search field to host an in-popover
		     clear, so these tiny fixed-list filters clear from a rail-level chip
		     (×) instead — the searchable filter below clears from inside the
		     popover. -->
		<div class="inline-flex items-center gap-1">
			<BbSelectPopover
				v-model="ctx.filters.status"
				disable-writing
				item-text="label"
				item-value="value"
				:items="STATUS_OPTIONS"
				multiple
			>
				<template #activator="{ props }">
					<BbButton
						v-bind="props"
						aria-label="Filter by status"
						append:icon="lucide:chevron-down"
						size="sm"
						variant="outline"
					>
						Status{{
							ctx.filters.status.length ? ` · ${ctx.filters.status.length}` : ''
						}}
					</BbButton>
				</template>
			</BbSelectPopover>
			<BbButton
				v-if="ctx.filters.status.length"
				aria-label="Clear status filter"
				prepend:icon="lucide:x"
				size="sm"
				variant="ghost"
				@click="ctx.filters.status = []"
			/>
		</div>

		<!-- Priority: same shape, three options. -->
		<div class="inline-flex items-center gap-1">
			<BbSelectPopover
				v-model="ctx.filters.priority"
				disable-writing
				item-text="label"
				item-value="value"
				:items="PRIORITY_OPTIONS"
				multiple
			>
				<template #activator="{ props }">
					<BbButton
						v-bind="props"
						aria-label="Filter by priority"
						append:icon="lucide:chevron-down"
						size="sm"
						variant="outline"
					>
						Priority{{
							ctx.filters.priority.length
								? ` · ${ctx.filters.priority.length}`
								: ''
						}}
					</BbButton>
				</template>
			</BbSelectPopover>
			<BbButton
				v-if="ctx.filters.priority.length"
				aria-label="Clear priority filter"
				prepend:icon="lucide:x"
				size="sm"
				variant="ghost"
				@click="ctx.filters.priority = []"
			/>
		</div>

		<!-- Assignee: the SAME shared provider as every assignee cell. The whole
		     member is the value, so the pill labels itself from page state with
		     zero fetches — no watchEffect-to-resolve-a-name here. Query-aware
		     (searchable), so the filter clears from inside the popover search. -->
		<BbSelectPopover
			v-model="ctx.filters.assignee"
			clearable
			item-text="name"
			:items="searchMembers"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filter by assignee"
					append:icon="lucide:chevron-down"
					size="sm"
					variant="outline"
				>
					{{ ctx.filters.assignee?.name ?? 'Assignee' }}
				</BbButton>
			</template>
		</BbSelectPopover>

		<!-- Clear-all renders only while something is active. -->
		<BbButton
			v-if="ctx.hasActiveFilters.value"
			class="ml-auto"
			prepend:icon="lucide:x"
			size="sm"
			variant="ghost"
			@click="ctx.clearFilters"
		>
			Clear filters
		</BbButton>
	</div>
</template>

<script setup lang="ts">
import { BbButton, BbSelectPopover } from 'bitboss-ui';
import {
	PRIORITY_OPTIONS,
	STATUS_OPTIONS,
	searchMembers,
	useBacklogWorkspace,
} from './context';

const ctx = useBacklogWorkspace();
</script>
```

### EditableTitleCell.vue

```vue
<!-- BacklogWorkspace/EditableTitleCell.vue -->
<template>
	<!-- Commit on @change (blur/Enter), NEVER v-model: a v-model autosave is
	one request per keystroke. `:model-value` binds the read-through value
	down; the user's in-progress typing lives in the DOM until blur commits
	it. A failed save marks the field until the next commit attempt. -->
	<BbTextInput
		compact
		:has-errors="ctx.failed.value.has(`${issue.id}:title`)"
		hide-label
		label="Issue title"
		:loading="ctx.isSaving(issue, 'title')"
		:model-value="ctx.valueOf(issue, 'title')"
		@change="commit"
	/>
</template>

<script setup lang="ts">
import { BbTextInput } from 'bitboss-ui';
import { useBacklogWorkspace } from './context';
import type { Issue } from '@/types';

const props = defineProps<{ issue: Issue }>();

const ctx = useBacklogWorkspace();

// `@change` is the native event; the committed text is on the target.
const commit = (event: Event) =>
	ctx.persistField(
		props.issue,
		'title',
		(event.target as HTMLInputElement).value
	);
</script>
```

### EstimateCell.vue

```vue
<!-- BacklogWorkspace/EstimateCell.vue -->
<template>
	<BbNumberInput
		compact
		:has-errors="ctx.failed.value.has(`${issue.id}:estimate`)"
		hide-label
		label="Estimate"
		:loading="ctx.isSaving(issue, 'estimate')"
		:min="0"
		:model-value="ctx.valueOf(issue, 'estimate')"
		placeholder="—"
		@change="commit"
	/>
</template>

<script setup lang="ts">
import { BbNumberInput } from 'bitboss-ui';
import { useBacklogWorkspace } from './context';
import type { Issue } from '@/types';

const props = defineProps<{ issue: Issue }>();

const ctx = useBacklogWorkspace();

// A number input's `change` carries the RAW STRING; '' means cleared. A
// cleared estimate is a real commit (estimate: null), not a no-op — which is
// exactly why the context's valueOf checks `key in patch` instead of `??`.
const commit = (event: Event) => {
	const raw = (event.target as HTMLInputElement).value;
	ctx.persistField(props.issue, 'estimate', raw === '' ? null : Number(raw));
};
</script>
```

### StatusCell.vue

```vue
<!-- BacklogWorkspace/StatusCell.vue -->
<template>
	<BbSelectPopover
		compact
		disable-writing
		item-text="label"
		item-value="value"
		:items="STATUS_OPTIONS"
		:model-value="status"
		width="180px"
		@update:model-value="
			(next) => ctx.persistField(issue, 'status', next as IssueStatus)
		"
	>
		<template #activator="{ props: activatorProps, shown }">
			<!-- The badge IS the trigger: BbBadgeButton turns the badge's own
			body into the button, so the pill is the hit target and draws its own
			focus ring — no wrapper element, no chrome class. The internal
			trailing chevron says "this can change" and sits inside the button
			with the label; while THIS field's save runs the badge's `loading`
			swaps the spinner into the chevron's place — same size, nothing
			shifts. Unlike the one-shot §6.1 cell there is no local `saving` ref:
			the flag comes from the context overlay, because in an autosave grid
			the fetch must also know what's in flight. -->
			<BbBadge
				append:icon="lucide:chevron-down"
				:class="{ 'status-cell--open': shown }"
				:loading="ctx.isSaving(issue, 'status')"
				:variant="STATUS_VARIANT[status]"
			>
				<BbBadgeButton
					:aria-label="`Change status for ${issue.ref}`"
					v-bind="activatorProps"
					>{{ label }}</BbBadgeButton
				>
			</BbBadge>
		</template>
	</BbSelectPopover>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
import { STATUS_OPTIONS, STATUS_VARIANT, useBacklogWorkspace } from './context';
import type { Issue, IssueStatus } from '@/types';

const props = defineProps<{ issue: Issue }>();

const ctx = useBacklogWorkspace();

// Read through the overlay, so the badge moves the instant a pick commits —
// color and label both.
const status = computed(() => ctx.valueOf(props.issue, 'status'));
const label = computed(
	() =>
		STATUS_OPTIONS.find((option) => option.value === status.value)?.label ??
		status.value
);
</script>

<style scoped>
/* Open = the badge's own hue, deepened, plus its variant ring — derived from
   the badge's --color/--ring tokens so every status keeps its identity
   instead of washing out to a neutral. */
.status-cell--open {
	--bg: color-mix(in oklab, var(--color) 24%, var(--bb-panel));
	--border-color: color-mix(in oklab, var(--color) 45%, var(--bb-panel));
	box-shadow: 0 0 0 var(--bb-ring-size) var(--ring);
}
</style>
```

### PriorityCell.vue

```vue
<!-- BacklogWorkspace/PriorityCell.vue -->
<template>
	<!-- Same grammar as StatusCell, its OWN leaf (§6.3): one `EditableCell`
	with a `type` prop growing a renderer switch is the API-monster seed. The
	sixty percent that repeats is cheaper than the prop that accumulates. -->
	<BbSelectPopover
		compact
		disable-writing
		item-text="label"
		item-value="value"
		:items="PRIORITY_OPTIONS"
		:model-value="priority"
		width="160px"
		@update:model-value="
			(next) => ctx.persistField(issue, 'priority', next as IssuePriority)
		"
	>
		<template #activator="{ props: activatorProps, shown }">
			<BbBadge
				append:icon="lucide:chevron-down"
				:class="{ 'priority-cell--open': shown }"
				:loading="ctx.isSaving(issue, 'priority')"
				:variant="PRIORITY_VARIANT[priority]"
			>
				<BbBadgeButton
					:aria-label="`Change priority for ${issue.ref}`"
					v-bind="activatorProps"
					>{{ label }}</BbBadgeButton
				>
			</BbBadge>
		</template>
	</BbSelectPopover>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
import {
	PRIORITY_OPTIONS,
	PRIORITY_VARIANT,
	useBacklogWorkspace,
} from './context';
import type { Issue, IssuePriority } from '@/types';

const props = defineProps<{ issue: Issue }>();

const ctx = useBacklogWorkspace();

const priority = computed(() => ctx.valueOf(props.issue, 'priority'));
const label = computed(
	() =>
		PRIORITY_OPTIONS.find((option) => option.value === priority.value)?.label ??
		priority.value
);
</script>

<style scoped>
/* Open = the badge's own hue, deepened, plus its variant ring (see
   StatusCell). */
.priority-cell--open {
	--bg: color-mix(in oklab, var(--color) 24%, var(--bb-panel));
	--border-color: color-mix(in oklab, var(--color) 45%, var(--bb-panel));
	box-shadow: 0 0 0 var(--bb-ring-size) var(--ring);
}
</style>
```

### AssigneeCell.vue

```vue
<!-- BacklogWorkspace/AssigneeCell.vue -->
<template>
	<!-- Provider-backed people picker. The provider is the ONE shared
	`searchMembers` — lazy per instance, so a row nobody opens never fetches.
	The whole member is the value (no item-value), matching how the row
	stores it. -->
	<BbSelectPopover
		compact
		item-text="name"
		:items="searchMembers"
		:model-value="assignee"
		width="220px"
		@update:model-value="
			(next) => ctx.persistField(issue, 'assignee', next as Member)
		"
	>
		<template #activator="{ props: activatorProps, shown }">
			<!-- Labelled from the ROW (through the overlay), never from the
			popover's `text`: a lazy provider has no items until first open, so
			`text` is empty — and the rows nobody opens must still read right on
			first paint. An assignee is a person, not a semantic status, so the
			badge stays neutral (`secondary`), no soft accent. -->
			<BbBadge
				append:icon="lucide:chevron-down"
				:class="{ 'assignee-cell--open': shown }"
				:loading="ctx.isSaving(issue, 'assignee')"
				variant="secondary"
			>
				<BbBadgeButton
					:aria-label="`Change assignee for ${issue.ref}`"
					v-bind="activatorProps"
					>{{ assignee.name }}</BbBadgeButton
				>
			</BbBadge>
		</template>
	</BbSelectPopover>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
import { searchMembers, useBacklogWorkspace } from './context';
import type { Issue, Member } from '@/types';

const props = defineProps<{ issue: Issue }>();

const ctx = useBacklogWorkspace();

const assignee = computed(() => ctx.valueOf(props.issue, 'assignee'));
</script>

<style scoped>
/* Open = the badge's own hue, deepened, plus its variant ring (see
   StatusCell). */
.assignee-cell--open {
	--bg: color-mix(in oklab, var(--color) 24%, var(--bb-panel));
	--border-color: color-mix(in oklab, var(--color) 45%, var(--bb-panel));
	box-shadow: 0 0 0 var(--bb-ring-size) var(--ring);
}
</style>
```

### RowActions.vue

```vue
<!-- BacklogWorkspace/RowActions.vue -->
<template>
	<BbDropdown
		:items="[
			{
				key: 'duplicate',
				text: 'Duplicate',
				'prepend:icon': 'lucide:copy',
				onClick: () => ctx.duplicateIssue(issue),
			},
			{
				key: 'next-sprint',
				text: 'Move to next sprint',
				'prepend:icon': 'lucide:arrow-right',
				onClick: () => ctx.moveToNextSprint(issue),
			},
			{
				key: 'delete',
				text: 'Delete',
				'prepend:icon': 'lucide:trash-2',
				variant: 'destructive',
				onClick: () => ctx.deleteIssue(issue),
			},
		]"
	>
		<template #activator="{ props }">
			<BbButton v-bind="props" icon="lucide:ellipsis" size="sm" variant="ghost">
				Issue actions
			</BbButton>
		</template>
	</BbDropdown>
</template>

<script setup lang="ts">
import { BbButton, BbDropdown } from 'bitboss-ui';
import { useBacklogWorkspace } from './context';
import type { Issue } from '@/types';

defineProps<{ issue: Issue }>();

const ctx = useBacklogWorkspace();
</script>
```

### SelectionBar.vue

```vue
<!-- BacklogWorkspace/SelectionBar.vue -->
<template>
	<FloatingBottomPanel :open="selectedCount > 0">
		<span class="px-2 text-sm">{{ selectedCount }} selected</span>

		<!-- Bulk pickers are DISPATCHERS, not fields: model stays null, every
		pick fires the bulk action and the popover closes. The bar holds no
		state of its own. `placement="top"` because the bar hugs the viewport
		bottom — open upward instead of flipping — with an 8px `offset` so the
		menu clears the bar. -->
		<BbSelectPopover
			disable-writing
			item-text="label"
			item-value="value"
			:items="STATUS_OPTIONS"
			:model-value="null"
			:offset="8"
			placement="top"
			width="180px"
			@update:model-value="(next) => ctx.bulkStatus(next as IssueStatus)"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Set status for selected issues"
					append:icon="lucide:chevron-up"
					size="sm"
					variant="ghost"
				>
					Set status
				</BbButton>
			</template>
		</BbSelectPopover>

		<BbSelectPopover
			item-text="name"
			:items="searchMembers"
			:model-value="null"
			:offset="8"
			placement="top"
			width="220px"
			@update:model-value="(next) => ctx.bulkAssign(next as Member)"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Assign selected issues"
					append:icon="lucide:chevron-up"
					size="sm"
					variant="ghost"
				>
					Assign
				</BbButton>
			</template>
		</BbSelectPopover>

		<BbButton
			prepend:icon="lucide:arrow-right"
			size="sm"
			variant="ghost"
			@click="ctx.bulkMoveToNextSprint"
		>
			Next sprint
		</BbButton>

		<div class="floating-bottom-panel__right flex items-center gap-1">
			<BbButton
				aria-label="Clear selection"
				icon="lucide:x"
				size="sm"
				variant="ghost"
				@click="clearSelection"
			/>
		</div>
	</FloatingBottomPanel>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbSelectPopover } from 'bitboss-ui';
import FloatingBottomPanel from '@/components/layout/FloatingBottomPanel.vue';
import { STATUS_OPTIONS, searchMembers, useBacklogWorkspace } from './context';
import type { IssueStatus, Member } from '@/types';

const ctx = useBacklogWorkspace();

const selectedCount = computed(() => ctx.table.selected.value?.length ?? 0);
const clearSelection = () => {
	ctx.table.selected.value = [];
};
</script>
```

### IssuePeek.vue

```vue
<!-- BacklogWorkspace/IssuePeek.vue -->
<template>
	<div v-if="issue" class="flex flex-col gap-4 text-sm">
		<!-- Identity header. -->
		<header class="flex flex-col gap-1">
			<p class="text-xs font-medium text-[color:var(--bb-text-muted)]">
				{{ issue.ref }}
			</p>
			<h2 class="text-base font-semibold">{{ issue.title }}</h2>
		</header>

		<!-- Properties: the SAME editable cells as the grid — one leaf, two
		call sites. Change the status here and the grid's badge (and even the
		blocked-row tint) moves in the same tick, because both surfaces read
		the same overlay; the spinner shows in both places at once. -->
		<dl class="grid grid-cols-[auto_1fr] items-center gap-x-4 gap-y-2">
			<dt class="text-[color:var(--bb-text-muted)]">Status</dt>
			<dd><StatusCell :issue="issue" /></dd>
			<dt class="text-[color:var(--bb-text-muted)]">Priority</dt>
			<dd><PriorityCell :issue="issue" /></dd>
			<dt class="text-[color:var(--bb-text-muted)]">Assignee</dt>
			<dd><AssigneeCell :issue="issue" /></dd>
			<dt class="text-[color:var(--bb-text-muted)]">Estimate</dt>
			<dd>
				{{
					ctx.valueOf(issue, 'estimate') === null
						? 'Unestimated'
						: `${ctx.valueOf(issue, 'estimate')} points`
				}}
			</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Sprint</dt>
			<dd>{{ issue.sprint }}</dd>
		</dl>

		<!-- Description. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Description
			</h3>
			<p class="whitespace-pre-line text-[color:var(--bb-text-muted)]">
				{{ issue.description }}
			</p>
		</section>

		<!-- Activity feed. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Activity
			</h3>
			<ul class="flex flex-col gap-2">
				<li v-for="entry in issue.activity" :key="entry.id" class="flex gap-2">
					<BbIcon
						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
						:icon="entry.icon"
						size="14"
					/>
					<div class="flex flex-col">
						<span>{{ entry.text }}</span>
						<span class="text-xs text-[color:var(--bb-text-muted)]"
							>{{ entry.actor }} · {{ longDate(entry.at) }}</span
						>
					</div>
				</li>
			</ul>
		</section>

		<!-- Peek is a workbench: act here, or leave for the full page. -->
		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				prepend:icon="lucide:arrow-right"
				size="sm"
				variant="secondary"
				@click="() => ctx.moveToNextSprint(issue!)"
			>
				Next sprint
			</BbButton>
			<BbButton
				size="sm"
				variant="destructive"
				@click="() => ctx.deleteIssue(issue!)"
			>
				Delete
			</BbButton>
			<BbButton
				append:icon="lucide:arrow-up-right"
				size="sm"
				:to="`/issues/${issue.id}`"
				variant="ghost"
			>
				Open full page
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { ref, watchEffect } from 'vue';
import { BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
import AssigneeCell from './AssigneeCell.vue';
import PriorityCell from './PriorityCell.vue';
import StatusCell from './StatusCell.vue';
import { useBacklogWorkspace } from './context';
import type { IssueDetail } from '@/types';

const props = defineProps<{ issueId: string }>();

const ctx = useBacklogWorkspace();

// Re-fetches whenever the stack shows a different issue; reading `ctx.issues`
// makes every commit (from the grid OR from this panel) — each of which ends
// in the list's `refresh()` — reflect here immediately. The cells inside
// don't flash across that reload either — they read the overlay, and the
// overlay only retires when the fresh data confirms it.
const issue = ref<IssueDetail | null>(null);
watchEffect(async () => {
	void ctx.issues.value;
	issue.value = await $fetch<IssueDetail>(`/api/issues/${props.issueId}`);
});

const longDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
		year: 'numeric',
	});
</script>
```

## Why it is built this way

- **`pending` sits on rung 3, and the recipe's whole shape follows from
  that.** Three consumers force it up the ladder: the cells read it to render
  optimistically, the peek reads it so the second call site of every cell
  agrees with the first, and the `useAsyncData` transform reads it to retire
  confirmed fields. Contrast the records workspace's §6.1 status cell, where
  `saving` is a rung-1 local `ref` around one awaited action — correct
  **there** because nothing but that one cell ever cares. Here the fetch must
  know what's in flight, so a local flag physically cannot work; that is why
  the picker cells bind `:loading="ctx.isSaving(issue, 'status')"` instead of
  owning a `saving` ref.
- **`persistField` is one complete action for every control kind.** Text,
  number, and three pickers all commit through the same guard → optimistic
  set → PATCH → refetch pipeline, so the failure story (drop one field,
  destructive toast) and the no-op story (blur without change costs nothing)
  are written once. The guard compares against `valueOf`, not the raw row —
  what the user _sees_ is the value they are re-committing.
- **Retirement lives in the fetch's `transform` because that is when the
  truth changes.** A resolved PATCH proves the server accepted the value, not
  that the table shows it — the rows in memory are still old until the
  refetch lands. Retiring per-field (only values the response confirms) means
  a slow title save survives a fast status save's reload untouched. The
  comment on the `transform` ships with the recipe on purpose: this is the
  §6.8 bug everyone writes once.
- **The URL is the filter store, `useAsyncData` is the fetch.** Filters and
  tab are seeded from `route.query` once at setup, mirrored back with
  `navigateTo` on every change (debounced for free text), and
  `useAsyncData('issues', …, { watch: [() => route.query, table.page] })` is
  the single refetch trigger — there is exactly one place data loads, which
  is also the only place the overlay retires. The assignee pill is the one
  URL nuance: rows store the whole member, but a deep link carries only an
  id, so the context resolves it to a member once at setup.
- **`valueOf` checks `key in patch`, not `??`.** A cleared estimate commits
  `null`, and `null ?? row.estimate` would silently un-render the overlay
  while the save runs. The one-line comment in the context is load-bearing.
- **No dirty ring anywhere, no success toasts for cell commits.** Autosave
  has no "changed but unsaved" state, so the ring (the draft-map pattern's
  grammar) would lie; and a page where every blur saves would toast
  constantly. The spinner in the chevron's place is the feedback; failure is
  the exception worth announcing (destructive toast + `has-errors` on the
  text/number cells via the `failed` set; badge cells announce by visibly
  snapping back). Discrete actions — duplicate, move, delete, bulk — _do_
  toast success: they are events, not keystrokes.
- **Five cells, five leaves.** `EditableTitleCell`, `EstimateCell`,
  `StatusCell`, `PriorityCell`, `AssigneeCell` — never one `EditableCell`
  with a `type` prop growing a renderer switch (§6.3/§4). Each takes exactly
  one data prop (`issue`) and gets its behavior from the context.
- **Typed inputs commit on `@change`; pickers commit on pick.** The text and
  number cells bind `:model-value` down and read the committed value from the
  native event (`event.target`); the number cell's change carries the raw
  string where `''` means cleared. No debounce machinery — blur/Enter and
  pick are natural commit points, so the request count equals the commit
  count.
- **Options resolve once.** Status and priority are module-level catalogs
  shared by the cells, the rail pills and the bulk picker — zero requests.
  The assignee is genuinely query-driven, so it gets the one exception: a
  **single** shared provider (`searchMembers`), lazy per instance, keeping
  unopened rows free; prefill calls return the whole six-person team so the
  current selection always resolves. Rows store the whole member, so every
  badge and the filter pill label themselves from data they already hold —
  no `watchEffect`-to-resolve-a-name anywhere on this page; the only
  directory lookup is the one-time deep-link resolution of `?assignee=` at
  setup.
- **Internal links use `to`, not `href`.** `to` renders a real Vue Router
  link (client-side navigation); a raw `href` would force a full page reload.
  The `New issue` primary and the peek's `Open full page` link use `to`; the
  tabs keep `href` (`?tab=…`) because their client-side pushState is what
  keeps `route.query.tab` in sync — the URL-filter grammar itself.
- **The ref cell is the peek handle** because the title — the "name" of an
  issue — is an input here, and a click that sometimes edits and sometimes
  navigates is a broken affordance. One record type also collapses the stack
  grammar to a single verb (`peekIssue`, fresh stack).
- **The peek reuses the grid's cells verbatim** — one leaf, two call sites.
  Both read the same overlay, so a status change made in the panel updates
  the grid row (badge, tint, spinner) in the same tick, and vice versa.
- **Sizing:** topbar follows `md`-first (`compact` inputs at 28px flush
  beside the default buttons); `sm` appears exactly where the doctrine
  allows — rail pills, row actions, the bulk bar, the peek footer. Cell
  inputs are `compact`.
- **One `variant="primary"`** (New issue). The only irreversible action
  (delete — row menu and peek footer) rides `useConfirm`; moving between
  sprints is reversible, so it deliberately does not.

## Variations

- **Keyboard triage**: add `keyboard-navigation` to the table —
  `v-model:highlighted` already drives the peek — the approvals-inbox recipe
  is the full treatment; the overlay needs no changes, since it never cared
  how a commit was triggered.
- **Review-before-save domains**: if the product wants a batch the user
  confirms (accounting lines, permissions), swap the overlay for the
  draft-map pattern — dirty ring, dirty-gated Save — per the
  [Inline Edit Playbook](../../guides/inline-edit-playbook.md); the
  record-form recipe's line-item editor assembles it. Never mix both
  grammars on one table.
- **Undo instead of confirm**: for softer destructive-ish moves (Done →
  reopened), a success toast with an Undo action that PATCHes the old value
  back is more Linear than a confirm dialog.
- **Live board**: because refetches retire the overlay per confirmed field,
  a polling `refresh()` call (or a websocket-triggered one) is safe — a
  poll landing mid-save cannot destroy an in-flight edit, which is exactly
  the property the write-back anti-pattern lacks.

---

<!-- dist/ai/recipes/nuxt/layout-scaffold.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/nuxt/layout-scaffold.md -->

<!--
	GENERATED FILE — do not edit by hand.
	Source: fixtures/nuxt/app/composables/usePageShellContext.ts, fixtures/nuxt/app/components/PageShell.vue, fixtures/nuxt/app/components/FloatingBottomPanel.vue
	Regenerate: npm run docs:scaffold
-->

# Recipe: Layout Scaffold (Nuxt)

**Build this first.** Every page recipe imports `PageShell`,
`usePageShellContext` and `FloatingBottomPanel` from your own app — they are
_not_ package exports, by design: page chrome is yours to own and restyle. The
recipes assume the files below already exist. Create them verbatim, then the
rest of the recipes compile as written.

Sibling scaffolds: [Vue](../vue/layout-scaffold.md) · [Inertia](../inertia/layout-scaffold.md).

## Prerequisites

- `@vueuse/core` — `usePageShellContext.ts` imports `injectLocal`/`provideLocal`
  from it. `npm i @vueuse/core`. This library also depends on it, so it may
  already be resolvable via hoisting — don't rely on that: a package your own
  code imports belongs in your own `package.json`, or a strict installer
  (pnpm, Yarn PnP) will fail to resolve it.

## Why these are not package exports

A shell is the one part of an app that every product wants to own. Exporting it
would force our page grammar on your product and make every future change to it
a breaking change for you. Copying it costs you three files once and leaves the
chrome yours.

What you must **not** do is invent your own. These files encode behaviour the
page recipes depend on: the peek renders from a _stack_ (so a peek can open a
peek, and the back arrow works), `close()` empties that stack rather than
hiding a panel, and the closed sidebar is removed from flow with
`overflow-x: clip` on the body instead of an animated `padding-right` that
thrashes layout on every open.

## The files

### `app/composables/usePageShellContext.ts`

The peek **stack**, not a boolean. `push(item)` opens a peek on top of the current one (so a peek can open a peek and the back arrow works), `push(item, true)` resets to a single top-level peek, and `close()` empties the stack. Provide/inject is idempotent — the page context and `PageShell` call it and share one instance, so neither has to pass it to the other.

```ts
import { injectLocal, provideLocal } from '@vueuse/core';
import { computed, ref, type ComputedRef, type Ref } from 'vue';

export type PageShellContext<T> = {
	/** The peek stack; the last entry is what the sidebar shows. */
	stack: Ref<T[]>;
	/** The top of the stack, or null when the sidebar is closed. */
	current: ComputedRef<T | null>;
	/** Stack depth — the shell shows a back arrow when > 1. */
	depth: ComputedRef<number>;
	/** Push a peek. `reset` opens a fresh stack (a top-level peek). */
	push: (item: T, reset?: boolean) => void;
	/**
	 * Open `item` as a fresh top-level peek — what a row click does. Reads as
	 * the intent rather than as `push(item, true)`, whose boolean says nothing
	 * at the call site.
	 */
	peek: (item: T) => void;
	/**
	 * Drill from the open peek into a related record, keeping the back arrow.
	 * The other half of the same intent pair.
	 */
	stackItem: (item: T) => void;
	/** Pop one level (the back arrow). */
	pop: () => void;
	/** Close the sidebar entirely. */
	close: () => void;
};

const KEY = 'page-shell';

export function usePageShellContext<T>(): PageShellContext<T> {
	const existing = injectLocal<PageShellContext<T> | null>(KEY, null);
	if (existing != null) return existing;

	const stack = ref<T[]>([]) as Ref<T[]>;
	const current = computed<T | null>(() => stack.value.at(-1) ?? null);
	const depth = computed(() => stack.value.length);

	const push = (item: T, reset = false) => {
		stack.value = reset ? [item] : [...stack.value, item];
	};
	// Named intents over the same primitive: `push(item, true)` at a call site
	// reads as "push, and something about true", which is how pilots end up
	// resetting a stack they meant to drill into.
	const peek = (item: T) => push(item, true);
	const stackItem = (item: T) => push(item);
	const pop = () => {
		stack.value = stack.value.slice(0, -1);
	};
	const close = () => {
		stack.value = [];
	};

	const context: PageShellContext<T> = {
		stack,
		current,
		depth,
		push,
		peek,
		stackItem,
		pop,
		close,
	};
	provideLocal(KEY, context);
	return context;
}
```

### `app/components/PageShell.vue`

The page frame: sticky topbar, body, and the peek sidebar with its own back/close chrome. The closed sidebar is taken out of flow by `overflow-x: clip` on the body — **not** by animating `padding-right` on the content, which thrashes layout on every open and leaves a phantom column behind.

```vue
<template>
	<div class="page-shell">
		<div v-if="$slots.topbar" class="page-shell__topbar">
			<slot name="topbar" />
		</div>

		<div class="page-shell__body">
			<!-- A `<div>`, not `<main>`: the app-side layout (AppLayout /
			     AppShell) already owns the page's one `<main>` landmark. A
			     second `<main>` here would nest two landmarks. -->
			<div class="page-shell__content">
				<slot />
			</div>

			<transition name="page-shell-sidebar">
				<aside
					v-if="shell.current.value"
					ref="panel"
					:aria-label="$slots['sidebar-title'] ? undefined : 'Details'"
					:aria-labelledby="$slots['sidebar-title'] ? titleId : undefined"
					class="page-shell__sidebar"
					data-test="page-shell-sidebar"
					tabindex="-1"
					@keydown.esc="onEscape"
				>
					<header class="page-shell__sidebar-chrome">
						<BbButton
							v-if="shell.depth.value > 1"
							aria-label="Back"
							data-test="peek-back"
							icon="lucide:arrow-left"
							size="sm"
							variant="ghost"
							@click="shell.pop"
						>
							Back
						</BbButton>
						<h2
							v-if="$slots['sidebar-title']"
							:id="titleId"
							class="page-shell__sidebar-title"
							data-test="peek-title"
						>
							<slot name="sidebar-title" />
						</h2>
						<span v-else class="page-shell__sidebar-spacer" />
						<BbButton
							aria-label="Close"
							data-test="peek-close"
							icon="lucide:x"
							size="sm"
							variant="ghost"
							@click="shell.close"
						>
							Close
						</BbButton>
					</header>
					<div class="page-shell__sidebar-body">
						<slot name="sidebar" />
					</div>
				</aside>
			</transition>
		</div>

		<slot name="dialogs" />
	</div>
</template>

<script setup lang="ts" generic="T">
import { nextTick, ref, useId, watch } from 'vue';
import { BbButton, useMobile, useSafeArea } from 'bitboss-ui';
import { usePageShellContext } from '~/composables/usePageShellContext';

const shell = usePageShellContext<T>();

/**
 * The peek sidebar is docked in the page, not floating over it, so nothing in
 * the library can tell it is there — and a toast would land on top of it. This
 * claims the right edge while it is open, and the toast stack slides clear.
 * Only on desktop: below the mobile breakpoint the sidebar covers the page
 * instead of sitting beside it (the `@media` block at the end of the styles),
 * so there is no edge to claim.
 *
 * SIDEBAR_W must stay in step with `.page-shell__sidebar { width }` below — it
 * is the same fact stated twice. (Pass `element: <the aside>` instead if you
 * make the panel resizable; the claim is then measured, not declared.)
 */
const SIDEBAR_W = 352; // 22rem
const { isMobile } = useMobile();
useSafeArea({
	side: 'right',
	// A declared size can't tell whether the panel is on screen — say so here
	// (`null` = nothing docked), or the edge stays claimed with no sidebar up.
	size: () => (shell.current.value ? SIDEBAR_W : null),
	active: () => !isMobile.value,
});

/**
 * Keyboard and screen-reader baseline for the peek. Deliberately NOT a focus
 * trap: on desktop this is a docked, non-modal panel and the page beside it
 * stays live and clickable, so trapping Tab would strand the keyboard in a
 * region the user can see past. What a non-modal panel does owe is a name,
 * focus that lands in it when it opens, focus that goes back where it came
 * from when it closes, and Escape. (The mobile sheet form below covers the
 * page, and that IS the shape where containment starts to matter — see the
 * Page Shell guide before adding a trap for it.)
 */
const panel = ref<HTMLElement | null>(null);
const titleId = useId();

/** The page-side control that opened the peek, to hand focus back to. */
let opener: HTMLElement | null = null;

watch(shell.current, async (item) => {
	if (item) {
		// Runs on flush 'pre', so the DOM is still the pre-change one: whatever
		// is focused now is the control that caused this. Only page-side ones
		// are worth remembering — a drill-down link lives inside the panel and
		// is destroyed by the very record it opens.
		const active = document.activeElement;
		if (active instanceof HTMLElement && !panel.value?.contains(active)) {
			opener = active;
		}

		// Focus the panel on every change, not just on open: a drill-down or a
		// Back destroys the control that was focused, and focus would otherwise
		// fall to <body> mid-consult. Landing on the panel also re-announces
		// its title, which is the record that just changed.
		await nextTick();
		panel.value?.focus();
		return;
	}

	const trigger = opener;
	opener = null;
	// The row may have been filtered away or re-rendered while the peek was
	// open; focusing a detached node quietly drops focus on <body> instead.
	if (trigger?.isConnected) trigger.focus();
});

const onEscape = (event: KeyboardEvent) => {
	// Library overlays (dropdown, popover, dialog) take Escape at the document
	// in the capture phase and stop it there, so this only ever sees the key
	// when the peek itself is the top-most open surface. `defaultPrevented`
	// covers anything app-side that handles Escape without stopping it.
	if (event.defaultPrevented) return;
	shell.close();
};
</script>

<style scoped>
.page-shell {
	display: flex;
	flex: 1;
	flex-direction: column;
	min-height: 0;
}

.page-shell__topbar {
	background: var(--bb-panel);
	position: sticky;
	/* Flush with the viewport by default. If your app layout puts a
	   sticky bar above the page (a brand/app bar), set --app-bar-h on an
	   ancestor and this topbar sits under it instead of overlapping it.

	   Two bars stacking is INTENTIONAL, not a layout bug to collapse: an
	   app/brand bar belongs to the SHELL, a topbar belongs to the PAGE. Keep
	   the two variables apart — --app-bar-h is the shell bar's height used
	   here as a sticky OFFSET, while that bar's own row height (if it needs a
	   name) is --app-bar-row-h. Conflating them is what makes a page topbar
	   sit exactly one bar too low. (Ruled PG-018, 2026-08-07.) */
	top: var(--app-bar-h, 0);
	z-index: 5;
}

.page-shell__body {
	display: flex;
	flex: 1;
	min-height: 0;
	overflow-x: clip;
}

.page-shell__content {
	flex: 1;
	min-width: 0;
}

/* Overlay sheet pinned on the parcel — same hairline as every other divider,
   no lead pin: the sidebar's edge stays uniform with the page grid. */
.page-shell__sidebar {
	background: color-mix(in oklab, var(--bb-panel) 92%, transparent);
	border-inline-start: 1px solid var(--bb-border);
	display: flex;
	flex-direction: column;
	flex-shrink: 0;
	/* Keep in step with SIDEBAR_W in the script — the safe-area claim that
	   keeps toasts off this panel is declared from that number. */
	width: 22rem;
}

.page-shell__sidebar-chrome {
	align-items: center;
	border-block-end: 1px solid var(--bb-border);
	display: flex;
	gap: 0.5rem;
	padding: 0.5rem 1rem;
}

.page-shell__sidebar-spacer {
	flex: 1;
}

.page-shell__sidebar-title {
	flex: 1;
	font-size: 15px;
	font-weight: 600;
	letter-spacing: -0.01em;
	min-width: 0;
	overflow: hidden;
	text-overflow: ellipsis;
	white-space: nowrap;
}

.page-shell__sidebar-body {
	overflow-y: auto;
	padding: 1rem;
}

.page-shell-sidebar-enter-active,
.page-shell-sidebar-leave-active {
	transition:
		transform var(--bb-transition-fast) var(--bb-ease),
		opacity var(--bb-transition-fast) var(--bb-ease);
}

.page-shell-sidebar-enter-from,
.page-shell-sidebar-leave-to {
	opacity: 0;
	transform: translateX(0.75rem);
}

/* Below the mobile breakpoint there is no room for a 22rem column beside the
   content, so the peek stops being a column and becomes a sheet over the whole
   page — chrome included, since its own header carries Back and Close.

   767.98px is `config.mobileMaxWidth` (768) minus a hair: the exact query
   `useMobile()` runs. The two must agree, or there is a band of widths where
   the safe-area claim above still thinks a panel is docked at the right edge
   while this rule has it covering the page. */
@media (max-width: 767.98px) {
	.page-shell__sidebar {
		/* Opaque here — the docked form is translucent over the page grid, but
		   a sheet that covers content must not let it show through. */
		background: var(--bb-panel);
		border-inline-start: 0;
		inset: 0;
		position: fixed;
		width: auto;
		/* Above the page topbar (5) and the floating bottom panel (30): while
		   the sheet is up, it is the page. */
		z-index: 40;
	}

	.page-shell__sidebar-body {
		/* The sheet runs to the bottom edge, so its own padding is what keeps
		   the last row clear of the home indicator. */
		padding-block-end: calc(1rem + env(safe-area-inset-bottom));
	}
}
</style>
```

### `app/components/FloatingBottomPanel.vue`

The selection dock. It hugs its content (`width: max-content` + `margin-inline: auto`) rather than stretching edge to edge — a full-bleed bar reads as broken viewport chrome instead of a response to your selection.

```vue
<template>
	<transition name="floating-bottom-panel">
		<div
			v-if="open"
			aria-label="Selection actions"
			class="floating-bottom-panel"
			data-test="selection-bar"
			role="region"
		>
			<slot />
		</div>
	</transition>
</template>

<script setup lang="ts">
defineProps<{ open?: boolean }>();
</script>

<style scoped>
.floating-bottom-panel {
	align-items: center;
	background: var(--bb-panel);
	border: 1px solid var(--bb-border);
	border-radius: var(--bb-radius-surface);
	box-shadow: var(--bb-shadow);
	display: flex;
	gap: 0.5rem;
	inset-block-end: 1.25rem;
	inset-inline: 0;
	margin-inline: auto;
	max-width: calc(100% - 2rem);
	padding: 0.375rem 0.5rem;
	position: fixed;
	width: max-content;
	z-index: 30;
}

.floating-bottom-panel :deep(.floating-bottom-panel__right) {
	border-inline-start: 1px solid var(--bb-border);
	margin-inline-start: 0.75rem;
	padding-inline-start: 0.75rem;
}

.floating-bottom-panel-enter-active,
.floating-bottom-panel-leave-active {
	transition:
		transform var(--bb-transition-fast) var(--bb-ease),
		opacity var(--bb-transition-fast) var(--bb-ease);
}

.floating-bottom-panel-enter-from,
.floating-bottom-panel-leave-to {
	opacity: 0;
	transform: translateY(0.75rem);
}
</style>
```

## Wiring a page

**One topbar per page (GROK-BTG-013).** The `#topbar` slot is the page's single
top command bar — breadcrumbs/title on the left, page commands (search, the
primary action) on the right. `PageShell` renders it as its own sticky bar; do
**not** stack a second brand/utility bar above it. Primary navigation lives in
the [App Layout](../../guides/app-layout.md) sidebar, and app-wide utilities
(global search, a user menu) go **into** this same topbar — never a second
stacked row.

The topbar row is `justify-between`: the breadcrumb trail and the trailing
controls both shrink by default, so the trail collapses to its own overflow
menu while free space sits unused in the middle. Give the trail
`class="min-w-0 flex-auto"` so it consumes that slack on a stable basis, and
`shrink-0` to its siblings so they stay content-sized — the same contract
the `BbBreadcrumbs` guide documents for exactly this row.

```vue
<template>
	<PageShell>
		<template #topbar>
			<div class="flex items-center justify-between gap-4 px-4">
				<!-- `flex-auto min-w-0` lets the trail consume the row's slack (and
             shrink/overflow) instead of being sized by its content. -->
				<BbBreadcrumbs class="min-w-0 flex-auto" :items="breadcrumbs" />
				<!-- `shrink-0` keeps search/actions/the account menu content-sized so
             they never lose the tug-of-war with the trail above. -->
				<div class="flex shrink-0 items-center gap-2">
					<!-- page search, primary action, AccountMenu (see below) -->
				</div>
			</div>
		</template>

		<!-- default slot: the page body -->
		<!-- The shipped `--highlighted` tint already marks the current row;
         `row-class` is how this page says WHY it is current (the open peek)
         and how you override the look. See the BbTable guide's Row highlight
         section. -->
		<BbTable
			v-model:highlighted="highlighted"
			:columns="columns"
			:items="items"
			:row-class="rowClass"
		/>

		<template #sidebar>
			<RecordPeek v-if="shell.current.value" :id="shell.current.value" />
		</template>

		<template #dialogs>
			<!-- dialogs mount here so they escape the body's overflow clip -->
		</template>
	</PageShell>

	<FloatingBottomPanel :open="selectedCount > 0">
		<span>{{ selectedCount }} selected</span>
	</FloatingBottomPanel>
</template>
```

## Topbar value pickers (account menu, theme, warehouse)

App-chrome value pickers — theme, an active warehouse/location, anything the
user picks occasionally rather than filters by — do not belong on a bordered
form `BbSelect` in the topbar; that is a field control, and the topbar has
no form. Reach for a ghost `BbButton` opening a `BbSelectPopover`, or (when
it lives next to other account actions) an account `BbDropdown` with nested
selectable submenus, exactly like the `NestedMenu` and `SelectableMenu`
patterns in the `BbDropdown` guide, combined: each category is a submenu
opener whose own `items` holds one selectable group, so picking a value
closes the whole menu back to the top level.

```vue
<template>
	<BbDropdown :items="accountMenuItems" placement="bottom-end" :width="240">
		<template #activator="{ props }">
			<BbButton
				v-bind="props"
				aria-label="Account menu"
				class="gap-1.5"
				size="sm"
				variant="ghost"
			>
				<BbAvatar size="xs">SE</BbAvatar>
			</BbButton>
		</template>
		<!-- Companions bind to a group by `id`; the group itself stays declared
         in `items` below. -->
		<BbDropdownGroup id="theme-opts" v-model="theme" />
		<BbDropdownGroup id="warehouse-opts" v-model="warehouseId" />
	</BbDropdown>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbAvatar, BbButton, BbDropdown, BbDropdownGroup } from 'bitboss-ui';
import type { BbDropdownItem } from 'bitboss-ui';

const theme = ref<'system' | 'light' | 'dark'>('system');
const warehouseId = ref('denver');

const accountMenuItems: BbDropdownItem[] = [
	{
		key: 'theme',
		text: 'Theme',
		'prepend:icon': 'lucide:sun-moon',
		// A submenu opener (`items`) whose own `items` is one selectable
		// group — `selectable: true` gives single-choice radio semantics and a
		// check on the picked row, with no bordered field anywhere.
		items: [
			{
				key: 'theme-opts',
				selectable: true,
				items: [
					{ key: 'system', text: 'System' },
					{ key: 'light', text: 'Light' },
					{ key: 'dark', text: 'Dark' },
				],
			},
		],
	},
	{
		key: 'warehouse',
		text: 'Warehouse',
		'prepend:icon': 'lucide:warehouse',
		items: [
			{
				key: 'warehouse-opts',
				selectable: true,
				items: [
					{ key: 'denver', text: 'Denver DC' },
					{ key: 'reno', text: 'Reno DC' },
					{ key: 'columbus', text: 'Columbus DC' },
				],
			},
		],
	},
	// A trailing separator section (a nested array) for plain navigation rows.
	[
		{
			key: 'settings',
			text: 'Settings',
			'prepend:icon': 'lucide:settings',
			href: '/settings',
		},
		{
			key: 'signout',
			text: 'Sign out',
			'prepend:icon': 'lucide:log-out',
			href: '/logout',
			method: 'post',
		},
	],
];
</script>
```

Watch `theme`/`warehouseId` and act on the change (flip `html.dark`, refetch
scoped to the new warehouse) the same way any other v-model-driven picker
would — the dropdown only owns the menu, never the side effect.

## The peek must stay in sync with the table highlight

`BbTable`'s `v-model:highlighted` and the shell stack are two pieces of state
pointing at one idea ("which row is open"). Wire **both** directions or the
second click on a row does nothing: the user closes the peek, the highlight is
still set, and a re-click leaves it unchanged so no watcher fires.

```ts
watch(highlighted, (id) => {
	if (id == null) {
		if (shell.current.value != null) shell.close();
		return;
	}
	shell.peek(id);
});

// The other direction: closing the peek clears the highlight, so the same row
// can open it again.
watch(shell.current, (current) => {
	if (current == null && highlighted.value != null) highlighted.value = null;
});
```

If a page has no peek, omit `v-model:highlighted` entirely. A highlight that
paints a selected row but opens nothing is a dead affordance.

## `workspace-surfaces.css` — the helpers every page re-invents

`.plain-link`, `.table-flush` and the row tints are project CSS by design (the
library ships no such classes), but they are the _same_ project CSS on every
workspace page. (`.table-flush`'s edge-inset rules address the table through
its grid containers — `> .bb-table__table > .bb-table__body > [role='row'] >
:first-child` — never through `table`/`tbody`/`tr`/`td`, which the table no
longer renders; the canonical block is in the BbTable guide § Styling hooks.)
Author them **once**, next to the layout, and import that file
from the app entry — not per page, and never copy-pasted into a page's
`<style scoped>`, which is how three pages end up with three underline colours.

```css
/* src/components/layout/workspace-surfaces.css */
.plain-link {
	color: inherit;
	text-decoration: underline;
	text-underline-offset: 2px;
	text-decoration-color: color-mix(in oklab, var(--bb-text) 25%, transparent);
	transition: text-decoration-color var(--bb-transition-fast) var(--bb-ease);
}
.plain-link:hover,
.plain-link:focus-visible {
	text-decoration-color: currentColor;
	outline: none;
}

.row-danger {
	background: color-mix(in oklab, var(--bb-danger) 6%, var(--bb-panel));
}
.row-danger:hover {
	background: color-mix(in oklab, var(--bb-danger) 10%, var(--bb-panel));
}
.row-warn {
	background: color-mix(in oklab, var(--bb-warn) 6%, var(--bb-panel));
}
.row-warn:hover {
	background: color-mix(in oklab, var(--bb-warn) 10%, var(--bb-panel));
}
```

Every rule here is built from `--bb-*` tokens, so the whole sheet follows the
theme and dark mode without a second dark block. See
[design-language](../../guides/design-language.md) § Row tint and § the
`.plain-link` helper for the reasoning behind each.

## Shortcuts live in the topbar, not in the page

A keyboard-driven screen needs its shortcuts discoverable, and the reflex is an
inline hint bar above the table. That bar is permanent chrome for information
read once. Default to a **topbar affordance**: a keyboard icon in
`#topbar-actions` opening a `BbPopover` that lists the bindings.

```vue
<BbPopover>
	<template #activator="{ props }">
		<BbButton v-bind="props" aria-label="Keyboard shortcuts" icon="lucide:keyboard" size="sm" variant="ghost" />
	</template>
	<dl class="shortcuts">…</dl>
</BbPopover>
```

An **inline** shortcut bar is a triage exception — a queue whose entire purpose
is rapid keyboard disposition (see the approvals-inbox recipe), where the
bindings are the primary UI rather than a reference. Everywhere else, the
topbar popover keeps the body for the records.

## The height chain — `flex: 1` only works if its parent fills the viewport

`PageShell` sets `flex: 1` on itself and `min-height: 0` on its body, but that
is a claim on space its **parent** has to actually own. If the main column is a
plain block, the shell is as tall as its content: a short page leaves the peek
sidebar floating mid-screen, and a long one scrolls the whole document instead
of the content area.

Every link in the chain has to hold, top to bottom:

| Level        | Rule                                                      |
| ------------ | --------------------------------------------------------- |
| layout root  | `min-height: 100dvh` (grid or flex — it just has to fill) |
| main column  | `display: flex; flex-direction: column; min-height: 0`    |
| content slot | `flex: 1; min-height: 0`                                  |
| `PageShell`  | `flex: 1` (already in the component)                      |

`min-height: 0` on every flex child is the part people drop. Without it a flex
item refuses to shrink below its content, so the _inner_ scroll container never
scrolls and the page grows instead — the classic "why is my sticky topbar
scrolling away" symptom.

## Do not nest a drawer inside the peek

The `#sidebar` slot **is** the drawer. Putting a `BbOffCanvas` inside it gives
you two stacked drawers with two close buttons. Pick one: the PageShell stack
for in-page detail, or a standalone `BbOffCanvas` for chrome that is not about
the current page (mobile nav, global filters).

---

<!-- dist/ai/recipes/nuxt/onboarding.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/nuxt/onboarding.md -->

# Recipe: Workspace Onboarding (Nuxt)

The onboarding checklist adapted for **Nuxt**: the same live progress header,
single-open accordion whose steps carry the real actions inline, and "see
what you'll get" preview peeks — but the checklist state loads through
`useAsyncData` and every mutation is a `$fetch` call followed by `refresh()`,
so the server stays the single source of truth for step statuses. Anatomy,
components, the context shape, copy and data are identical to the Vue
recipe; only the data/mutation layer changes.

Sibling recipes: [Vue](../vue/onboarding.md) ·
[Inertia](../inertia/onboarding.md).

## Prerequisites

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell` and `usePageShellContext` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
- `<BbConfirm />` and `<BbToast />` mounted once in `app.vue` — never in a page.
- [App Layout](../../guides/app-layout.md) and
  [Page Shell](../../guides/page-shell.md) copied into `src/components/layout/`
  per their guides — this page assumes the chrome exists and renders inside
  it.
- Server routes: `GET /api/onboarding` (returns `{ steps, connectedIntegrations,
workspace, invites, firstProject, importedCustomers, reminders }`), plus the
  mutation routes referenced below (`PATCH /api/onboarding/steps/:id`,
  `POST /api/onboarding/integrations/:id/connect`,
  `POST /api/onboarding/invites`, `POST /api/onboarding/project`,
  `POST /api/onboarding/customers/import`, `PATCH /api/onboarding/reminders`,
  `POST /api/onboarding/dismiss`).

## Key ideas

- **One coopting page context.** `provideOnboardingWorkspace()` joins the
  page-shell stack once, owns the step statuses, the integration and invite
  state, and every action. Every leaf calls `useOnboardingWorkspace()` and
  nothing else — zero prop drilling anywhere on the page.
- **`useAsyncData` loads the checklist once; every mutation ends in
  `refresh()`.** There is exactly one status writer path: `$fetch` the
  mutation, then `refresh()` re-pulls `/api/onboarding` and a single watcher
  re-seeds every local field (`steps`, `integrations`, `invites`,
  `firstProject`, `reminders`) from the fresh response — no mutation patches
  local state by hand except the optimistic switches.
- **Steps act inline; the checklist ticks itself.** Each step body _is_ the
  feature: switches connect integrations, a tag input sends invites, a mini
  form creates the project, a dropzone imports the CSV. Completing the real
  action persists the step status through one private `persistStatus` —
  the same verb the manual "Mark as done" / "Skip for now" ghosts use.
- **Single-open accordion, modeled — not wrapped.** `BbAccordion` is one
  panel per boolean; there is no group component by design. One
  `activeStep` key in the context derives every panel's `model-value`, and
  finishing a step advances the key to the next unfinished one.
- **CSV upload progress needs raw `XMLHttpRequest`.** `ofetch` (Nuxt's
  `$fetch`) has no upload-progress hook, so the one import mutation wraps
  `XMLHttpRequest` directly to drive real bytes into `BbProgress`; every
  other mutation on the page uses `$fetch`.
- **Previews ride the shell stack.** "See what you'll get" pushes a
  `step-preview` peek (replace semantics — previews never stack); the peek
  is a workbench: identity header, benefit list, a stat, and a "Set it up
  now" action that jumps back to the step.
- **Checklist archetype, so rows 4/5/7/8 of the standard anatomy don't
  apply**: no filter rail, no tabs, no pagination, no selection/bulk bar —
  and no page search, since the page has no filterable collection. Page
  Shell, breadcrumbs topbar and the stacked peek sidebar stay.
- **Buttons are `md` by default**; one `variant="primary"` on the page
  ("Go to dashboard" in the topbar); step submits are `secondary`,
  done/skip/preview are `ghost`; "Dismiss onboarding" rides `useConfirm`.

## Page anatomy

```
OnboardingChecklist/
	Index.vue                ← assembly: PageShell slots, accordion loop, thin
	context.ts               ← coopting page context (shell + useAsyncData + actions)
	ProgressHeader.vue       ← title, dismiss, BbProgress + "4 of 7 complete"
	StepHeader.vue           ← status icon, title, minutes, chevron (in the header button)
	StepActions.vue          ← per-step done / skip / preview footer row
	ProfileStep.vue          ← step 1 body: completed-at-signup summary + edit link
	IntegrationsStep.vue     ← step 2 body: BbSwitch rows (Stripe, QuickBooks, Slack, Drive)
	InviteStep.vue           ← step 3 body: BbTag emails + role BbSelect + send
	FirstProjectStep.vue     ← step 4 body: mini create-project form
	ImportCustomersStep.vue  ← step 5 body: BbDropzone CSV + BbProgress upload
	FirstInvoiceStep.vue     ← step 6 body: link-out to the invoice composer
	RemindersStep.vue        ← step 7 body: reminders switch + cadence select
	StepPreviewPeek.vue      ← sidebar "what you'll get" workbench per step
```

Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
(left nav + fat footer) and [Page Shell](../../guides/page-shell.md). The
dismiss confirmation renders through the app-wide `useConfirm` host, so this
page needs no `#dialogs` content of its own.

## Action inventory

| #   | Action                           | Trigger                             | Mechanism                                                          |
| --- | -------------------------------- | ----------------------------------- | ------------------------------------------------------------------ |
| 1   | Go to dashboard                  | topbar, the page's one `primary`    | navigation (`/dashboard`)                                          |
| 2   | Dismiss onboarding               | progress header, ghost              | `useConfirm` (destructive) → `$fetch` + `navigateTo` + toast       |
| 3   | Expand / collapse a step         | accordion header (single-open)      | `activeStep` key derives each panel's `model-value`                |
| 4   | See what you'll get              | every step footer                   | `previewStep(id)` → shell peek (replace)                           |
| 5   | Mark step done / skip step       | step footer ghosts                  | `completeStep` / `skipStep` → `$fetch` + `refresh()`               |
| 6   | Connect / disconnect integration | switch rows in _Connect your tools_ | optimistic toggle, `readonly` in flight, revert + toast on failure |
| 7   | Compose the invite list          | `BbTag` (Enter/comma, max 10)       | local ref; `duplicate`/`max` surfaced via `errors`                 |
| 8   | Choose the invite role           | `BbSelect` beside the tags          | local ref                                                          |
| 9   | Send invitations                 | secondary button in step body       | `sendInvites` → `$fetch` + auto-complete + toast                   |
| 10  | Create the first project         | mini form submit                    | `createProject` → `$fetch` + auto-complete + toast                 |
| 11  | Import customers CSV             | `BbDropzone` + Import button        | `importCustomers`; `BbProgress` driven by real XHR upload bytes    |
| 12  | Open the invoice composer        | outline button in step 6            | navigation (`/invoices/create`)                                    |
| 13  | Turn reminders on / pick cadence | switch + select in step 7           | `setReminders` / `setReminderCadence` + toast                      |
| 14  | Jump to a step from its preview  | peek footer                         | `jumpToStep(id)` → open step + close peek                          |
| 15  | Edit the workspace profile       | link in the completed profile step  | navigation (`/settings/general`)                                   |
| 16  | Close the peek                   | shell chrome                        | shell stack close                                                  |

## The code

### context.ts

```ts
// OnboardingChecklist/context.ts
import {
	computed,
	inject,
	provide,
	reactive,
	ref,
	watch,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import { useConfirm, useToast } from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import type {
	InviteRole,
	PendingInvite,
	Project,
	ProjectDraft,
	ReminderCadence,
	WorkspaceProfile,
} from '@/types';

export type StepId =
	| 'profile'
	| 'integrations'
	| 'invites'
	| 'first-project'
	| 'import-customers'
	| 'first-invoice'
	| 'reminders';

export type StepStatus = 'todo' | 'complete' | 'skipped';

export interface OnboardingStep {
	id: StepId;
	title: string;
	description: string;
	/** Rough time estimate shown in the header while the step is open. */
	minutes: number;
	status: StepStatus;
}

export interface WorkspaceIntegration {
	id: string;
	name: string;
	description: string;
	/** Full static literal — the production icon scanner only bundles names it can see. */
	icon: string;
	connected: boolean;
	/** True while a connect/disconnect request is in flight (drives `readonly`). */
	busy: boolean;
}

/** What the stacked sidebar can show: the per-step "what you'll get" preview. */
export type PeekItem = { type: 'step-preview'; stepId: StepId };

/** The whole `/api/onboarding` response — the single source of truth. */
type OnboardingState = {
	steps: Record<StepId, StepStatus>;
	connectedIntegrations: string[];
	workspace: WorkspaceProfile;
	invites: PendingInvite[];
	firstProject: Project | null;
	importedCustomers: number | null;
	reminders: { enabled: boolean; cadence: ReminderCadence };
};

export interface OnboardingWorkspaceContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	// -- Page-owned state ------------------------------------------------------
	steps: OnboardingStep[];
	/** The one open panel; `null` collapses everything (single-open accordion). */
	activeStep: Ref<StepId | null>;
	/** Steps no longer todo (complete or skipped) — drives the progress bar. */
	doneCount: ComputedRef<number>;
	allDone: ComputedRef<boolean>;
	workspace: Ref<WorkspaceProfile | null>;
	integrations: WorkspaceIntegration[];
	invites: Ref<PendingInvite[]>;
	firstProject: Ref<Project | null>;
	importState: {
		uploading: boolean;
		sentBytes: number;
		totalBytes: number;
		importedCount: number | null;
	};
	reminders: { enabled: boolean; cadence: ReminderCadence };
	// -- Step grammar ----------------------------------------------------------
	openStep: (id: StepId | null) => void;
	previewStep: (id: StepId) => void;
	jumpToStep: (id: StepId) => void;
	// -- Actions (complete: $fetch + refresh + toast) ----------------------------
	completeStep: (id: StepId) => Promise<void>;
	skipStep: (id: StepId) => Promise<void>;
	toggleIntegration: (
		integration: WorkspaceIntegration,
		next: boolean
	) => Promise<void>;
	sendInvites: (emails: string[], role: InviteRole) => Promise<void>;
	createProject: (draft: ProjectDraft) => Promise<void>;
	importCustomers: (file: File) => Promise<void>;
	setReminders: (enabled: boolean) => Promise<void>;
	setReminderCadence: (cadence: ReminderCadence) => Promise<void>;
	dismissOnboarding: () => Promise<void>;
}

const key: InjectionKey<OnboardingWorkspaceContext> = Symbol(
	'onboarding-workspace'
);

// ofetch has no upload-progress hook, so the one import mutation drives real
// bytes through a plain XMLHttpRequest instead — every other mutation below
// uses $fetch.
const uploadWithProgress = (
	url: string,
	body: FormData,
	onProgress: (sentBytes: number, totalBytes: number) => void
): Promise<{ imported: number }> =>
	new Promise((resolve, reject) => {
		const xhr = new XMLHttpRequest();
		xhr.open('POST', url);
		xhr.upload.addEventListener('progress', (event) => {
			if (event.lengthComputable) onProgress(event.loaded, event.total);
		});
		xhr.addEventListener('load', () => {
			if (xhr.status >= 200 && xhr.status < 300) {
				resolve(JSON.parse(xhr.responseText));
			} else {
				reject(new Error(`Import failed (${xhr.status}).`));
			}
		});
		xhr.addEventListener('error', () => reject(new Error('Import failed.')));
		xhr.send(body);
	});

export function provideOnboardingWorkspace(): OnboardingWorkspaceContext {
	const { toast } = useToast();
	const { confirm } = useConfirm();

	// -- Coopt the specific contexts: once, here, for the whole page. ----------
	const shell = usePageShellContext<PeekItem>();

	// -- The checklist definition lives client-side; the server owns statuses. -
	const steps = reactive<OnboardingStep[]>([
		{
			id: 'profile',
			title: 'Set up your company profile',
			description: 'Legal name, billing address and tax details.',
			minutes: 2,
			status: 'todo',
		},
		{
			id: 'integrations',
			title: 'Connect your tools',
			description:
				'Stripe for payments, QuickBooks for the books, Slack for alerts.',
			minutes: 3,
			status: 'todo',
		},
		{
			id: 'invites',
			title: 'Invite your teammates',
			description:
				'Billing works better when the whole team sees the same numbers.',
			minutes: 2,
			status: 'todo',
		},
		{
			id: 'first-project',
			title: 'Create your first project',
			description:
				'Projects group invoices, budgets and time entries per client.',
			minutes: 1,
			status: 'todo',
		},
		{
			id: 'import-customers',
			title: 'Import your customers',
			description: 'Bring your existing customer list over as a CSV.',
			minutes: 5,
			status: 'todo',
		},
		{
			id: 'first-invoice',
			title: 'Send your first invoice',
			description: 'Compose, preview and send — payment link included.',
			minutes: 4,
			status: 'todo',
		},
		{
			id: 'reminders',
			title: 'Turn on payment reminders',
			description: 'Stop chasing overdue invoices by hand.',
			minutes: 1,
			status: 'todo',
		},
	]);

	// Icon names are full static literals: the production icon scanner bundles
	// only literals it can see, and brand SVGs live in the app's iconDir.
	const integrations = reactive<WorkspaceIntegration[]>([
		{
			id: 'stripe',
			name: 'Stripe',
			description: 'Accept card payments; payouts reconcile against invoices.',
			icon: 'local:stripe',
			connected: false,
			busy: false,
		},
		{
			id: 'quickbooks',
			name: 'QuickBooks Online',
			description: 'Push paid invoices straight into your accounting.',
			icon: 'local:quickbooks',
			connected: false,
			busy: false,
		},
		{
			id: 'slack',
			name: 'Slack',
			description: 'A message in #finance when an invoice is paid or overdue.',
			icon: 'local:slack',
			connected: false,
			busy: false,
		},
		{
			id: 'google-drive',
			name: 'Google Drive',
			description: 'Attach contracts and receipts from your shared drives.',
			icon: 'local:google-drive',
			connected: false,
			busy: false,
		},
	]);

	const activeStep = ref<StepId | null>(null);
	const workspace = ref<WorkspaceProfile | null>(null);
	const invites = ref<PendingInvite[]>([]);
	const firstProject = ref<Project | null>(null);
	const importState = reactive({
		uploading: false,
		sentBytes: 0,
		totalBytes: 0,
		importedCount: null as number | null,
	});
	const reminders = reactive({
		enabled: false,
		cadence: '3-7-14' as ReminderCadence,
	});

	// Skipped counts as done: the bar rewards moving on, like Linear's checklist.
	const doneCount = computed(
		() => steps.filter((step) => step.status !== 'todo').length
	);
	const allDone = computed(() => doneCount.value === steps.length);

	const step = (id: StepId): OnboardingStep =>
		steps.find((candidate) => candidate.id === id)!;

	// -- Data: one useAsyncData load; every mutation ends in refresh(). --------
	const { data, refresh } = useAsyncData<OnboardingState>('onboarding', () =>
		$fetch<OnboardingState>('/api/onboarding')
	);

	let hasOpenedFirstStep = false;
	watch(
		data,
		(state) => {
			if (!state) return;
			for (const item of steps) item.status = state.steps[item.id];
			const connected = new Set(state.connectedIntegrations);
			for (const integration of integrations)
				integration.connected = connected.has(integration.id);
			workspace.value = state.workspace;
			invites.value = state.invites;
			firstProject.value = state.firstProject;
			importState.importedCount = state.importedCustomers;
			reminders.enabled = state.reminders.enabled;
			reminders.cadence = state.reminders.cadence;
			// Open the first unfinished step once, the first time data arrives.
			if (!hasOpenedFirstStep) {
				activeStep.value =
					steps.find((candidate) => candidate.status === 'todo')?.id ?? null;
				hasOpenedFirstStep = true;
			}
		},
		{ immediate: true }
	);

	// -- Step grammar ----------------------------------------------------------------
	const openStep = (id: StepId | null) => {
		activeStep.value = id;
	};
	// Previews replace: a checklist preview never stacks on another preview.
	const previewStep = (id: StepId) =>
		shell.push({ type: 'step-preview', stepId: id }, true);
	// From the peek back into the page: open the step and drop the sidebar.
	const jumpToStep = (id: StepId) => {
		activeStep.value = id;
		shell.close();
	};
	const openNextTodo = (after: StepId) => {
		const index = steps.findIndex((candidate) => candidate.id === after);
		const next = [...steps.slice(index + 1), ...steps.slice(0, index)].find(
			(candidate) => candidate.status === 'todo'
		);
		activeStep.value = next?.id ?? null;
	};

	// -- Actions --------------------------------------------------------------------
	// The one status writer: $fetch then refresh() re-seeds the whole page from
	// the server response. Domain actions (send invites, import…) auto-check
	// their step through it; the manual done/skip ghosts use the same verb.
	const persistStatus = async (id: StepId, status: StepStatus) => {
		if (step(id).status === status) return;
		await $fetch(`/api/onboarding/steps/${id}`, {
			method: 'PATCH',
			body: { status },
		});
		await refresh();
	};

	const completeStep = async (id: StepId) => {
		const title = step(id).title;
		await persistStatus(id, 'complete');
		toast({ title: `"${title}" checked off.`, variant: 'success' });
		openNextTodo(id);
	};

	// Skipping is quiet: it is a dismissal, not an achievement.
	const skipStep = async (id: StepId) => {
		await persistStatus(id, 'skipped');
		openNextTodo(id);
	};

	// Optimistic, per the BbSwitch doctrine: flip now, revert + toast on failure.
	// `busy` drives `readonly` so conflicting toggles cannot queue.
	const toggleIntegration = async (
		integration: WorkspaceIntegration,
		next: boolean
	) => {
		integration.busy = true;
		integration.connected = next;
		try {
			await $fetch(
				`/api/onboarding/integrations/${integration.id}/${next ? 'connect' : 'disconnect'}`,
				{ method: 'POST' }
			);
			toast({
				title: `${integration.name} ${next ? 'connected' : 'disconnected'}.`,
				variant: 'success',
			});
			if (next) await persistStatus('integrations', 'complete');
		} catch {
			integration.connected = !next;
			toast({
				title: `Could not ${next ? 'connect' : 'disconnect'} ${integration.name}.`,
				variant: 'destructive',
			});
		} finally {
			integration.busy = false;
		}
	};

	const sendInvites = async (emails: string[], role: InviteRole) => {
		await $fetch('/api/onboarding/invites', {
			method: 'POST',
			body: { emails, role },
		});
		await persistStatus('invites', 'complete');
		toast({
			title: `${emails.length} invitation${emails.length === 1 ? '' : 's'} sent.`,
			variant: 'success',
		});
	};

	const createProject = async (draft: ProjectDraft) => {
		await $fetch('/api/onboarding/project', { method: 'POST', body: draft });
		await persistStatus('first-project', 'complete');
		toast({ title: `${draft.name} created.`, variant: 'success' });
	};

	const importCustomers = async (file: File) => {
		importState.uploading = true;
		importState.totalBytes = file.size;
		importState.sentBytes = 0;
		try {
			const body = new FormData();
			body.append('file', file);
			const result = await uploadWithProgress(
				'/api/onboarding/customers/import',
				body,
				(sentBytes, totalBytes) => {
					importState.sentBytes = sentBytes;
					importState.totalBytes = totalBytes;
				}
			);
			importState.importedCount = result.imported;
			await persistStatus('import-customers', 'complete');
			toast({
				title: `${result.imported} customers imported.`,
				variant: 'success',
			});
		} finally {
			importState.uploading = false;
		}
	};

	const setReminders = async (enabled: boolean) => {
		reminders.enabled = enabled;
		try {
			await $fetch('/api/onboarding/reminders', {
				method: 'PATCH',
				body: { enabled, cadence: reminders.cadence },
			});
			if (enabled) await persistStatus('reminders', 'complete');
			toast({
				title: enabled
					? 'Payment reminders are on.'
					: 'Payment reminders turned off.',
				variant: 'success',
			});
		} catch {
			reminders.enabled = !enabled;
			toast({ title: 'Could not update reminders.', variant: 'destructive' });
		}
	};

	const setReminderCadence = async (cadence: ReminderCadence) => {
		reminders.cadence = cadence;
		await $fetch('/api/onboarding/reminders', {
			method: 'PATCH',
			body: { enabled: reminders.enabled, cadence },
		});
		toast({ title: 'Reminder schedule updated.', variant: 'success' });
	};

	const dismissOnboarding = async () => {
		const ok = await confirm({
			variant: 'destructive',
			title: 'Dismiss onboarding',
			text: 'Hide the setup checklist for everyone in this workspace? Unfinished steps stay available under Settings → Setup.',
			yes: 'Dismiss',
			no: 'Keep it',
		});
		if (!ok) return;
		await $fetch('/api/onboarding/dismiss', { method: 'POST' });
		toast({
			title: 'Onboarding dismissed. Find it again under Settings → Setup.',
			variant: 'success',
		});
		await navigateTo('/dashboard');
	};

	const ctx: OnboardingWorkspaceContext = {
		shell,
		steps,
		activeStep,
		doneCount,
		allDone,
		workspace,
		integrations,
		invites,
		firstProject,
		importState,
		reminders,
		openStep,
		previewStep,
		jumpToStep,
		completeStep,
		skipStep,
		toggleIntegration,
		sendInvites,
		createProject,
		importCustomers,
		setReminders,
		setReminderCadence,
		dismissOnboarding,
	};
	provide(key, ctx);
	return ctx;
}

export function useOnboardingWorkspace(): OnboardingWorkspaceContext {
	const ctx = inject(key);
	if (!ctx)
		throw new Error(
			'useOnboardingWorkspace() called outside OnboardingChecklist'
		);
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- OnboardingChecklist/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left, the page's one primary action right. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs
					class="min-w-0 flex-auto"
					:items="[
						{ key: 'dashboard', text: 'Dashboard', to: '/dashboard' },
						{ key: 'getting-started', text: 'Getting started' },
					]"
				/>
				<BbButton
					append:icon="lucide:arrow-right"
					class="shrink-0"
					to="/dashboard"
					variant="primary"
				>
					Go to dashboard
				</BbButton>
			</div>
		</template>

		<div class="mx-auto flex w-full max-w-3xl flex-col gap-6 p-4">
			<ProgressHeader />

			<!-- Single-open checklist: one active key in the context derives every
			     panel's model-value; opening one closes the rest, and clicking the
			     open header collapses everything (payload is false → key null). -->
			<div class="flex flex-col divide-y rounded-[var(--bb-radius)] border">
				<BbAccordion
					v-for="item in ctx.steps"
					:key="item.id"
					:model-value="ctx.activeStep.value === item.id"
					@update:model-value="(open) => ctx.openStep(open ? item.id : null)"
				>
					<template #header="{ value }">
						<StepHeader :open="value" :step="item" />
					</template>
					<div class="flex flex-col gap-4 px-11 pb-4">
						<component :is="stepBodies[item.id]" />
						<StepActions :step="item" />
					</div>
				</BbAccordion>
			</div>

			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Stuck on a step?
				<BbButton size="sm" to="/docs/setup" variant="link"
					>Read the setup guide</BbButton
				>
				— it covers every integration and the CSV format.
			</p>
		</div>

		<!-- The peek sidebar: the shell owns back/close; we render by type. -->
		<template #sidebar>
			<StepPreviewPeek
				v-if="ctx.shell.current.value?.type === 'step-preview'"
				:step-id="ctx.shell.current.value.stepId"
			/>
		</template>
	</PageShell>
</template>

<script setup lang="ts">
import type { Component } from 'vue';
import { BbAccordion, BbBreadcrumbs, BbButton } from 'bitboss-ui';
import PageShell from '@/components/layout/PageShell.vue';
import { provideOnboardingWorkspace, type StepId } from './context';
import FirstInvoiceStep from './FirstInvoiceStep.vue';
import FirstProjectStep from './FirstProjectStep.vue';
import ImportCustomersStep from './ImportCustomersStep.vue';
import IntegrationsStep from './IntegrationsStep.vue';
import InviteStep from './InviteStep.vue';
import ProfileStep from './ProfileStep.vue';
import ProgressHeader from './ProgressHeader.vue';
import RemindersStep from './RemindersStep.vue';
import StepActions from './StepActions.vue';
import StepHeader from './StepHeader.vue';
import StepPreviewPeek from './StepPreviewPeek.vue';

const ctx = provideOnboardingWorkspace();

// Each step body is its own component — a lookup, not a `type` prop.
const stepBodies: Record<StepId, Component> = {
	profile: ProfileStep,
	integrations: IntegrationsStep,
	invites: InviteStep,
	'first-project': FirstProjectStep,
	'import-customers': ImportCustomersStep,
	'first-invoice': FirstInvoiceStep,
	reminders: RemindersStep,
};
</script>
```

### ProgressHeader.vue

```vue
<!-- OnboardingChecklist/ProgressHeader.vue -->
<template>
	<header class="flex flex-col gap-3">
		<div class="flex items-start justify-between gap-4">
			<div class="flex flex-col gap-1">
				<h1 class="text-xl font-semibold">Set up Acme</h1>
				<p class="text-sm text-[color:var(--bb-text-muted)]">
					A few steps to get your billing workspace ready for the whole team.
				</p>
			</div>
			<BbButton variant="ghost" @click="ctx.dismissOnboarding">
				Dismiss onboarding
			</BbButton>
		</div>

		<div class="flex flex-col gap-1.5">
			<div class="flex items-center justify-between gap-4 text-sm">
				<span class="font-medium">
					{{
						ctx.allDone.value
							? 'All set — your workspace is ready.'
							: 'Your setup checklist'
					}}
				</span>
				<span class="text-[color:var(--bb-text-muted)]">
					{{ ctx.doneCount.value }} of {{ ctx.steps.length }} complete
				</span>
			</div>
			<!-- Real units in, no pre-computed percentage: max = number of steps. -->
			<BbProgress
				aria-label="Setup progress"
				:aria-valuetext="`${ctx.doneCount.value} of ${ctx.steps.length} steps complete`"
				:max="ctx.steps.length"
				:model-value="ctx.doneCount.value"
			/>
		</div>
	</header>
</template>

<script setup lang="ts">
import { BbButton, BbProgress } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';

const ctx = useOnboardingWorkspace();
</script>
```

### StepHeader.vue

```vue
<!-- OnboardingChecklist/StepHeader.vue -->
<template>
	<!-- Rendered INSIDE the accordion's header button: everything here is
	     non-interactive and click-transparent by design — the whole row toggles. -->
	<span class="flex w-full items-center gap-3 px-3 py-3 text-left">
		<BbIcon
			class="shrink-0"
			:class="
				step.status === 'complete'
					? 'text-green-600'
					: 'text-[color:var(--bb-text-muted)]'
			"
			:icon="statusIcon"
			size="20"
		/>
		<span class="flex min-w-0 flex-1 flex-col">
			<span
				class="text-sm font-medium"
				:class="
					step.status === 'todo' ? '' : 'text-[color:var(--bb-text-muted)]'
				"
			>
				{{ step.title }}
			</span>
			<span class="truncate text-xs text-[color:var(--bb-text-muted)]">{{
				step.description
			}}</span>
		</span>
		<span
			v-if="step.status === 'skipped'"
			class="shrink-0 text-xs uppercase tracking-wide text-[color:var(--bb-text-muted)]"
		>
			Skipped
		</span>
		<span
			v-else-if="step.status === 'todo'"
			class="shrink-0 text-xs text-[color:var(--bb-text-muted)]"
		>
			~{{ step.minutes }} min
		</span>
		<BbIcon
			class="shrink-0 text-[color:var(--bb-text-muted)] transition-transform"
			:class="open ? 'rotate-180' : ''"
			icon="lucide:chevron-down"
			size="16"
		/>
	</span>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbIcon } from 'bitboss-ui';
import type { OnboardingStep } from './context';

const props = defineProps<{ open: boolean; step: OnboardingStep }>();

// Full literals — the production icon scanner needs complete names.
const icons = {
	todo: 'lucide:circle-dashed',
	complete: 'lucide:circle-check',
	skipped: 'lucide:circle-check',
} as const;
const statusIcon = computed(() => icons[props.step.status]);
</script>
```

### StepActions.vue

```vue
<!-- OnboardingChecklist/StepActions.vue -->
<template>
	<footer class="flex flex-wrap items-center gap-2 border-t pt-3">
		<template v-if="step.status === 'todo'">
			<BbButton
				prepend:icon="lucide:check"
				variant="ghost"
				@click="() => ctx.completeStep(step.id)"
			>
				Mark as done
			</BbButton>
			<BbButton variant="ghost" @click="() => ctx.skipStep(step.id)">
				Skip for now
			</BbButton>
		</template>
		<span v-else class="text-xs text-[color:var(--bb-text-muted)]">
			{{ step.status === 'complete' ? 'Completed' : 'Skipped' }} — revisit any
			time from Settings → Setup.
		</span>
		<BbButton
			append:icon="lucide:chevron-right"
			class="ml-auto"
			variant="ghost"
			@click="() => ctx.previewStep(step.id)"
		>
			See what you'll get
		</BbButton>
	</footer>
</template>

<script setup lang="ts">
import { BbButton } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';
import type { OnboardingStep } from './context';

defineProps<{ step: OnboardingStep }>();

const ctx = useOnboardingWorkspace();
</script>
```

### ProfileStep.vue

```vue
<!-- OnboardingChecklist/ProfileStep.vue -->
<template>
	<div v-if="ctx.workspace.value" class="flex flex-col gap-3 text-sm">
		<p class="text-[color:var(--bb-text-muted)]">
			Done at signup — these details appear on every invoice you send.
		</p>
		<dl class="grid grid-cols-[auto_1fr] gap-x-6 gap-y-1.5">
			<dt class="text-[color:var(--bb-text-muted)]">Company</dt>
			<dd>{{ ctx.workspace.value.company }}</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Billing address</dt>
			<dd>{{ ctx.workspace.value.address }}</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Tax ID</dt>
			<dd>{{ ctx.workspace.value.taxId }}</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Currency</dt>
			<dd>{{ ctx.workspace.value.currency }}</dd>
		</dl>
		<div>
			<BbButton
				prepend:icon="lucide:pencil"
				size="sm"
				to="/settings/general"
				variant="link"
			>
				Edit workspace profile
			</BbButton>
		</div>
	</div>
</template>

<script setup lang="ts">
import { BbButton } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';

const ctx = useOnboardingWorkspace();
</script>
```

### IntegrationsStep.vue

```vue
<!-- OnboardingChecklist/IntegrationsStep.vue -->
<template>
	<div class="flex flex-col text-sm">
		<p class="pb-1 text-[color:var(--bb-text-muted)]">
			Flip a switch to connect — you'll be sent through the provider's consent
			screen the first time.
		</p>
		<div
			v-for="integration in ctx.integrations"
			:key="integration.id"
			class="flex items-center gap-3 border-b py-2.5 last:border-b-0"
		>
			<BbIcon class="shrink-0" :icon="integration.icon" size="20" />
			<div class="flex min-w-0 flex-1 flex-col">
				<span class="font-medium">{{ integration.name }}</span>
				<span class="truncate text-xs text-[color:var(--bb-text-muted)]">
					{{ integration.description }}
				</span>
			</div>
			<!-- Instant-effect toggle: the context flips optimistically, holds the
			     switch readonly while in flight, and reverts + toasts on failure. -->
			<BbSwitch
				hide-label
				:label="`Connect ${integration.name}`"
				:model-value="integration.connected"
				:name="`integration-${integration.id}`"
				:readonly="integration.busy"
				@update:model-value="(next) => ctx.toggleIntegration(integration, next)"
			/>
		</div>
	</div>
</template>

<script setup lang="ts">
import { BbIcon, BbSwitch } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';

const ctx = useOnboardingWorkspace();
</script>
```

### InviteStep.vue

```vue
<!-- OnboardingChecklist/InviteStep.vue -->
<template>
	<div class="flex flex-col gap-3 text-sm">
		<p class="text-[color:var(--bb-text-muted)]">
			Paste addresses or type them — Enter or a comma adds each one.
		</p>

		<div class="flex flex-wrap items-end gap-2">
			<BbTag
				v-model="emails"
				class="min-w-64 flex-1"
				compact
				:divider="['Enter', ',']"
				:errors="inviteError"
				label="Email addresses"
				:max="10"
				placeholder="ada.rossi@acme.com"
				prepend:icon="lucide:mail"
				@duplicate="
					(email) => (inviteError = `${email} is already in the list.`)
				"
				@max="() => (inviteError = 'You can invite up to 10 people at once.')"
			/>
			<BbSelect
				v-model="role"
				class="w-44"
				compact
				item-text="label"
				item-value="value"
				:items="roles"
				label="Role"
				label-mode="outside"
			/>
			<BbButton prepend:icon="lucide:send" variant="secondary" @click="send">
				Send invitations
			</BbButton>
		</div>

		<ul v-if="ctx.invites.value.length" class="flex flex-col gap-1">
			<li
				v-for="invite in ctx.invites.value"
				:key="invite.email"
				class="flex items-center justify-between gap-2 text-xs"
			>
				<span>{{ invite.email }}</span>
				<span class="text-[color:var(--bb-text-muted)]"
					>{{ invite.role }} · invited {{ invite.sentAt }}</span
				>
			</li>
		</ul>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbSelect, BbTag } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';
import type { InviteRole } from '@/types';

const ctx = useOnboardingWorkspace();

// Draft state only this leaf touches: local refs, not context fields.
const emails = ref<string[]>([]);
const role = ref<InviteRole>('member');
const inviteError = ref('');

const roles: { value: InviteRole; label: string }[] = [
	{ value: 'admin', label: 'Admin' },
	{ value: 'member', label: 'Member' },
	{ value: 'accountant', label: 'Accountant' },
];

// Returning the promise lets the button's automatic loading track the send.
const send = async () => {
	inviteError.value = '';
	if (emails.value.length === 0) {
		inviteError.value = 'Add at least one email address.';
		return;
	}
	const invalid = emails.value.filter((email) => !email.includes('@'));
	if (invalid.length > 0) {
		inviteError.value = `${invalid.join(', ')} ${invalid.length === 1 ? 'is' : 'are'} not a valid address.`;
		return;
	}
	await ctx.sendInvites(emails.value, role.value);
	emails.value = [];
};
</script>
```

### FirstProjectStep.vue

```vue
<!-- OnboardingChecklist/FirstProjectStep.vue -->
<template>
	<!-- Already created (by this session or a teammate): show it, not the form. -->
	<div v-if="ctx.firstProject.value" class="flex items-center gap-2 text-sm">
		<BbIcon class="text-green-600" icon="lucide:circle-check" size="16" />
		<span>
			<span class="font-medium">{{ ctx.firstProject.value.name }}</span>
			is ready for its first invoice.
		</span>
		<BbButton
			append:icon="lucide:arrow-up-right"
			size="sm"
			:to="`/projects/${ctx.firstProject.value.id}`"
			variant="link"
		>
			Open project
		</BbButton>
	</div>

	<form
		v-else
		class="flex flex-col gap-3 text-sm"
		novalidate
		@submit.prevent="submit"
	>
		<p class="text-[color:var(--bb-text-muted)]">
			A project keeps one client's invoices, budget and time entries together.
		</p>
		<div class="flex flex-wrap items-end gap-2">
			<BbTextInput
				v-model="draft.name"
				class="min-w-56 flex-1"
				compact
				:errors="nameError"
				label="Project name"
				label-mode="outside"
				placeholder="Website redesign"
			/>
			<BbTextInput
				v-model="draft.client"
				class="min-w-56 flex-1"
				compact
				label="Client"
				label-mode="outside"
				placeholder="Globex Corporation"
			/>
			<BbButton prepend:icon="lucide:plus" type="submit" variant="secondary">
				Create project
			</BbButton>
		</div>
	</form>
</template>

<script setup lang="ts">
import { reactive, ref } from 'vue';
import { BbButton, BbIcon, BbTextInput } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';

const ctx = useOnboardingWorkspace();

const draft = reactive({ name: '', client: '' });
const nameError = ref('');

// Returning the promise lets the submit button track the async work.
const submit = () => {
	nameError.value = '';
	if (!draft.name.trim()) {
		nameError.value = 'Give the project a name.';
		return;
	}
	return ctx.createProject({ ...draft });
};
</script>
```

### ImportCustomersStep.vue

```vue
<!-- OnboardingChecklist/ImportCustomersStep.vue -->
<template>
	<div class="flex flex-col gap-3 text-sm">
		<!-- Already imported: report it instead of showing an empty dropzone. -->
		<div
			v-if="ctx.importState.importedCount !== null"
			class="flex items-center gap-2"
		>
			<BbIcon class="text-green-600" icon="lucide:circle-check" size="16" />
			<span>
				<span class="font-medium">{{ ctx.importState.importedCount }}</span>
				customers imported.
			</span>
			<BbButton
				append:icon="lucide:arrow-up-right"
				size="sm"
				to="/customers"
				variant="link"
			>
				View customers
			</BbButton>
		</div>

		<template v-else>
			<!-- MIME + extension pairing: Excel exports often carry a non-CSV MIME
			     type (or none at all on drag-drop) — '.csv' is what admits them. -->
			<BbDropzone
				v-model="file"
				:accept="['text/csv', '.csv']"
				:disabled="ctx.importState.uploading"
				:errors="fileError"
				:max-size="10 * 1024 * 1024"
				@error="onReject"
			>
				<template #default="{ dragging, focused, open }">
					<div
						class="flex flex-col items-center gap-2 rounded-[var(--bb-radius)] border-2 border-dashed p-6 text-center transition-colors"
						:class="[
							dragging
								? 'border-[color:var(--bb-primary)] bg-[color:var(--bb-panel)]'
								: '',
							focused ? 'ring-2 ring-[color:var(--bb-ring)]' : '',
						]"
					>
						<BbIcon
							class="text-[color:var(--bb-text-muted)]"
							icon="lucide:file-spreadsheet"
							size="24"
						/>
						<p class="font-medium">
							{{
								dragging ? 'Drop your CSV here' : 'Drag your customers CSV here'
							}}
						</p>
						<p class="text-xs text-[color:var(--bb-text-muted)]">
							We map name, email, VAT number and address columns. Up to 10 MB.
						</p>
						<BbButton size="sm" variant="ghost" @click="open"
							>or browse files</BbButton
						>
					</div>
				</template>
			</BbDropzone>

			<!-- Captured, not yet imported: confirm before touching the workspace. -->
			<div v-if="file" class="flex items-center gap-2">
				<BbIcon
					class="shrink-0 text-[color:var(--bb-text-muted)]"
					icon="lucide:file-text"
					size="16"
				/>
				<span class="min-w-0 flex-1 truncate">
					{{ file.name }}
					<span class="text-xs text-[color:var(--bb-text-muted)]"
						>· {{ formatSize(file.size) }}</span
					>
				</span>
				<BbButton
					aria-label="Remove selected file"
					:disabled="ctx.importState.uploading"
					icon="lucide:x"
					size="sm"
					variant="ghost"
					@click="() => (file = null)"
				/>
				<BbButton
					:disabled="ctx.importState.uploading"
					prepend:icon="lucide:upload"
					variant="secondary"
					@click="startImport"
				>
					Import customers
				</BbButton>
			</div>

			<!-- The dropzone captures; the context uploads and drives the bar. -->
			<div v-if="ctx.importState.uploading" class="flex flex-col gap-1">
				<BbProgress
					aria-label="Upload progress"
					:max="ctx.importState.totalBytes"
					:model-value="ctx.importState.sentBytes"
				/>
				<span class="text-xs text-[color:var(--bb-text-muted)]">
					Uploading… {{ formatSize(ctx.importState.sentBytes) }} of
					{{ formatSize(ctx.importState.totalBytes) }}
				</span>
			</div>
		</template>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbDropzone, BbIcon, BbProgress } from 'bitboss-ui';
import type { DropZoneError } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';

const ctx = useOnboardingWorkspace();

// The captured-but-not-imported file is this leaf's own state.
const file = ref<File | null>(null);
const fileError = ref('');

// Rejects never reach the model — map the typed error to a message and feed
// it back through `errors` (the display is a round-trip, not automatic).
const onReject = (error: DropZoneError) => {
	fileError.value =
		error.type === 'maxSize'
			? `${error.filename} is ${error.formattedSize} — the limit is ${error.formattedMaxSize}.`
			: error.type === 'accept'
				? `${error.filename} is not a CSV file.`
				: `${error.filename} was rejected.`;
};

const startImport = async () => {
	if (!file.value) return;
	fileError.value = '';
	await ctx.importCustomers(file.value);
	file.value = null;
};

const formatSize = (bytes: number) =>
	bytes >= 1024 * 1024
		? `${(bytes / 1024 / 1024).toFixed(1)} MB`
		: `${Math.max(1, Math.round(bytes / 1024))} KB`;
</script>
```

### FirstInvoiceStep.vue

```vue
<!-- OnboardingChecklist/FirstInvoiceStep.vue -->
<template>
	<div class="flex flex-col gap-3 text-sm">
		<p class="text-[color:var(--bb-text-muted)]">
			The composer walks you through line items, taxes and payment terms. Every
			invoice goes out with a payment link — customers pay by card or bank
			transfer without creating an account. This step checks itself off when
			your first invoice is sent.
		</p>
		<div>
			<BbButton
				append:icon="lucide:arrow-up-right"
				prepend:icon="lucide:receipt"
				to="/invoices/create"
				variant="outline"
			>
				Open the invoice composer
			</BbButton>
		</div>
	</div>
</template>

<script setup lang="ts">
import { BbButton } from 'bitboss-ui';
</script>
```

### RemindersStep.vue

```vue
<!-- OnboardingChecklist/RemindersStep.vue -->
<template>
	<div class="flex flex-col gap-3 text-sm">
		<!-- Instant-effect switch: the context applies optimistically and reverts
		     with a toast if the server rejects the change. -->
		<BbSwitch
			description="Email customers automatically when an invoice goes overdue. Replies land in your inbox."
			label="Automatic payment reminders"
			:model-value="ctx.reminders.enabled"
			name="payment-reminders"
			@update:model-value="(next) => ctx.setReminders(next)"
		/>
		<BbSelect
			v-if="ctx.reminders.enabled"
			class="max-w-72"
			compact
			item-text="label"
			item-value="value"
			:items="cadences"
			label="Reminder schedule"
			label-mode="outside"
			:model-value="ctx.reminders.cadence"
			@update:model-value="(cadence) => ctx.setReminderCadence(cadence)"
		/>
	</div>
</template>

<script setup lang="ts">
import { BbSelect, BbSwitch } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';
import type { ReminderCadence } from '@/types';

const ctx = useOnboardingWorkspace();

const cadences: { value: ReminderCadence; label: string }[] = [
	{ value: '3-7-14', label: '3, 7 and 14 days overdue' },
	{ value: '7', label: '7 days overdue' },
	{ value: '7-30', label: '7 and 30 days overdue' },
];
</script>
```

### StepPreviewPeek.vue

```vue
<!-- OnboardingChecklist/StepPreviewPeek.vue -->
<template>
	<div class="flex flex-col gap-4 text-sm">
		<!-- Identity header. -->
		<header class="flex items-center gap-3">
			<span
				class="flex h-9 w-9 shrink-0 items-center justify-center rounded-[var(--bb-radius)] border"
			>
				<BbIcon :icon="preview.icon" size="18" />
			</span>
			<div class="flex min-w-0 flex-col">
				<h2 class="text-base font-semibold">{{ preview.title }}</h2>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					{{ preview.tagline }}
				</p>
			</div>
		</header>

		<p
			v-if="step.status !== 'todo'"
			class="flex items-center gap-1.5 text-xs text-[color:var(--bb-text-muted)]"
		>
			<!-- Green is earned: skipped reads as reached-but-unmeasured, not done. -->
			<BbIcon
				:class="
					step.status === 'complete'
						? 'text-green-600'
						: 'text-[color:var(--bb-text-muted)]'
				"
				icon="lucide:circle-check"
				size="14"
			/>
			{{
				step.status === 'complete'
					? 'Already done in this workspace.'
					: 'Skipped — you can still set it up.'
			}}
		</p>

		<!-- What you'll get. -->
		<section class="flex flex-col gap-2.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				What you'll get
			</h3>
			<ul class="flex flex-col gap-2.5">
				<li
					v-for="bullet in preview.bullets"
					:key="bullet.title"
					class="flex gap-2"
				>
					<BbIcon
						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
						:icon="bullet.icon"
						size="14"
					/>
					<div class="flex flex-col">
						<span class="font-medium">{{ bullet.title }}</span>
						<span class="text-xs text-[color:var(--bb-text-muted)]">{{
							bullet.text
						}}</span>
					</div>
				</li>
			</ul>
		</section>

		<!-- One concrete number beats three adjectives. -->
		<div class="rounded-[var(--bb-radius)] border p-3">
			<p class="text-lg font-semibold">{{ preview.stat.value }}</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				{{ preview.stat.label }}
			</p>
		</div>

		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				v-if="step.status === 'todo'"
				prepend:icon="lucide:check"
				variant="secondary"
				@click="() => ctx.jumpToStep(stepId)"
			>
				Set it up now
			</BbButton>
			<BbButton v-else variant="ghost" @click="() => ctx.jumpToStep(stepId)">
				Review this step
			</BbButton>
		</footer>
	</div>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbIcon } from 'bitboss-ui';
import { useOnboardingWorkspace, type StepId } from './context';

const props = defineProps<{ stepId: StepId }>();

const ctx = useOnboardingWorkspace();

const step = computed(
	() => ctx.steps.find((candidate) => candidate.id === props.stepId)!
);
const preview = computed(() => previews[props.stepId]);

interface StepPreview {
	icon: string;
	title: string;
	tagline: string;
	bullets: { icon: string; title: string; text: string }[];
	stat: { value: string; label: string };
}

// Presentation content with a single consumer: it lives in the leaf, not the
// context. Icon names are full static literals for the production scanner.
const previews: Record<StepId, StepPreview> = {
	profile: {
		icon: 'lucide:building-2',
		title: 'A complete company profile',
		tagline: 'Set once, printed on every document.',
		bullets: [
			{
				icon: 'lucide:file-text',
				title: 'Compliant invoices',
				text: 'Legal name, address and tax ID appear on every PDF automatically.',
			},
			{
				icon: 'lucide:euro',
				title: 'One currency for the books',
				text: 'Amounts, totals and reports all use your workspace currency.',
			},
		],
		stat: {
			value: '2 min',
			label: 'to update it later under Settings → General',
		},
	},
	integrations: {
		icon: 'lucide:link',
		title: 'Your tools, wired together',
		tagline:
			'Payments, accounting and alerts stop being three separate chores.',
		bullets: [
			{
				icon: 'lucide:credit-card',
				title: 'Payments reconcile themselves',
				text: 'Stripe payouts are matched against open invoices automatically.',
			},
			{
				icon: 'lucide:receipt',
				title: 'Books stay current',
				text: 'Paid invoices flow into QuickBooks the moment they settle.',
			},
			{
				icon: 'lucide:bell',
				title: 'The team finds out in Slack',
				text: '#finance gets a message on every paid and overdue invoice.',
			},
		],
		stat: {
			value: '9 days',
			label: 'faster average payment for teams with Stripe connected',
		},
	},
	invites: {
		icon: 'lucide:users',
		title: 'Everyone on the same numbers',
		tagline: 'Roles keep access right-sized from day one.',
		bullets: [
			{
				icon: 'lucide:user-plus',
				title: 'Sign-in with work email',
				text: 'Invitees join with their address — no shared passwords.',
			},
			{
				icon: 'lucide:key-round',
				title: 'Permissions per role',
				text: 'Accountants see reports; members see their own projects.',
			},
			{
				icon: 'lucide:clock',
				title: 'Invitations expire safely',
				text: 'Unaccepted invites lapse after 7 days and can be re-sent.',
			},
		],
		stat: { value: '10', label: 'invitations per batch' },
	},
	'first-project': {
		icon: 'lucide:folder',
		title: 'A home for each client',
		tagline: 'Projects keep invoices, budgets and time in one place.',
		bullets: [
			{
				icon: 'lucide:folder-open',
				title: 'Everything grouped',
				text: 'Invoices, budgets and time entries organized per client.',
			},
			{
				icon: 'lucide:chart-line',
				title: 'Profitability from day one',
				text: 'A per-project margin view as soon as the first invoice is paid.',
			},
		],
		stat: {
			value: '3',
			label: 'projects created by the average team in week one',
		},
	},
	'import-customers': {
		icon: 'lucide:file-spreadsheet',
		title: 'Your customer list, moved over',
		tagline: 'The CSV you already have is enough.',
		bullets: [
			{
				icon: 'lucide:upload',
				title: 'Columns mapped for you',
				text: 'Name, email, VAT number and address are detected automatically.',
			},
			{
				icon: 'lucide:check',
				title: 'No double imports',
				text: 'Rows are merged by email — re-running an import never duplicates.',
			},
		],
		stat: { value: '5,000', label: 'rows per import' },
	},
	'first-invoice': {
		icon: 'lucide:receipt',
		title: 'Your first invoice, out the door',
		tagline: 'Composed, sent and tracked in one flow.',
		bullets: [
			{
				icon: 'lucide:send',
				title: 'Sent from your domain',
				text: 'Invoices arrive from billing@your-company, not a noreply void.',
			},
			{
				icon: 'lucide:banknote',
				title: 'Payment link included',
				text: 'Customers pay by card or bank transfer without an account.',
			},
			{
				icon: 'lucide:clock',
				title: 'Overdue tracking starts itself',
				text: 'Due dates and aging are tracked from the moment you hit send.',
			},
		],
		stat: {
			value: '2×',
			label: 'faster payment on invoices with a payment link',
		},
	},
	reminders: {
		icon: 'lucide:bell',
		title: 'Overdue chasing, automated',
		tagline: 'Polite nudges on a schedule you choose.',
		bullets: [
			{
				icon: 'lucide:clock',
				title: 'A schedule, not a scramble',
				text: 'Reminders at 3, 7 and 14 days overdue — or the cadence you pick.',
			},
			{
				icon: 'lucide:mail',
				title: 'Replies reach a human',
				text: 'Customers answer straight into your inbox thread.',
			},
		],
		stat: {
			value: '38%',
			label: 'fewer invoices reach 30 days overdue with reminders on',
		},
	},
};
</script>
```

## Why it is built this way

- **The context coopts the shell, leaves consume.** The only specific
  context on a checklist page is the peek stack; `provideOnboardingWorkspace()`
  joins it once and thirteen components share step state, integration
  state and every action through one `useOnboardingWorkspace()` call. No
  component receives a callback prop; the only data props are the `step` /
  `stepId` an item renders (`StepHeader`, `StepActions`, `StepPreviewPeek`)
  — everything else is injection.
- **One fetch, one refresh path.** `useAsyncData('onboarding', …)` loads the
  whole checklist once; `persistStatus` is the single place that `$fetch`s a
  mutation and calls `refresh()` — a `watch(data, …, { immediate: true })`
  re-seeds every local field from the fresh response, so `steps`,
  `integrations`, `invites`, `firstProject` and `reminders` can never drift
  from what the server actually persisted.
- **Single-open is one key, per the BbAccordion doctrine.** `BbAccordion`
  is deliberately one panel per boolean with no group wrapper; the
  `activeStep` key derives each `model-value`, the `update:modelValue`
  payload (`false` on closing the open header) resets it to `null`, and
  `openNextTodo` gives the Linear feel of the checklist walking itself
  forward. No watchers force-closing siblings.
- **Headers stay passive, actions live in the body.** The accordion header
  is already a `<button>`; the status icon, minutes estimate and chevron in
  `StepHeader` are click-transparent metadata. Everything interactive —
  done, skip, preview, the step's real controls — is body content, so the
  markup stays valid and the click target stays whole.
- **`ofetch` has no upload-progress hook.** Every mutation on this page is a
  plain `$fetch` except the CSV import, which needs real bytes for
  `BbProgress` — that one call drops to a raw `XMLHttpRequest` wrapped in a
  promise. It is the only exception, called out explicitly so it doesn't
  read as an inconsistency.
- **Every rung of the state ladder is deliberate.** Draft state one leaf
  touches is a local ref (invite emails and role, the project draft, the
  captured CSV file, the reject message); everything two components read
  sits on the context (statuses, `importState` driving `BbProgress`,
  reminders); nothing on this page outlives it, so no store is involved.
- **The switch promise is kept.** Integration and reminder toggles apply
  optimistically, hold the control `readonly` while the request flies, and
  revert with a `destructive` toast on failure — the async-save pattern
  from the BbSwitch guide, owned by context actions so no leaf ever talks
  to `$fetch` or toasts on its own.
- **The dropzone captures; the context uploads.** `BbDropzone` has no
  request surface by design: the leaf holds the captured `File`, maps the
  typed `@error` union back through `errors` (the display round-trip), and
  `importCustomers` drives `BbProgress` from real bytes — `max` is the file
  size, never a pre-computed percentage.
- **Previews are peeks, not dialogs.** "See what you'll get" is the
  checklist's version of clicking a record's name: `previewStep` pushes
  onto the coopted shell stack with `replace` (previews never stack), and
  `jumpToStep` owns the way back — leaves never touch the stack grammar
  directly.
- **Sizing and variants:** `md`-first throughout the bodies (28px buttons
  flush beside `compact` inputs in the invite and project rows); `sm` only
  for genuinely dense spots (inline links, the file-row remove); exactly
  one `variant="primary"` (Go to dashboard); step submits are `secondary`;
  dismissal is a ghost gated by a `destructive` `useConfirm`.

## Variations

- **Personal onboarding**: scope statuses per user instead of per
  workspace (`$fetch('/api/onboarding', { query: { scope: 'user' } })`)
  and drop the workspace-wide dismiss confirm copy; the page shape is
  unchanged.
- **Sequential (gated) steps**: lock each accordion until the previous
  step is done by rendering the body's controls `disabled` with an
  explanatory line; for hard gates with per-step validation, the
  wizard-form recipe is the full treatment.
- **Preview follows the open step**: call `previewStep(id)` from
  `openStep` so the sidebar always previews the active step; keep the
  explicit footer button for touch users.
- **All-done celebration**: when `allDone` flips, swap `ProgressHeader`'s
  copy block for a success panel with the dashboard CTA and a "book an
  onboarding call" link.

---

<!-- dist/ai/recipes/nuxt/record-form.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/nuxt/record-form.md -->

# Recipe: Record Form (Nuxt)

The form archetype at full standard anatomy adapted for **Nuxt**: the same
Stripe-grade invoice create/edit page — sectioned fields with tied selects,
server-side 422 error mapping onto every input (including table rows), an
inline-editing line-items table, a dirty-snapshot route-leave guard, a
sticky action row, and a customer peek workbench — but the invoice loads
through `useAsyncData` keyed on the route param, saves go through `$fetch`
with `FetchError` 422 mapping, and redirects use `navigateTo`. Anatomy,
components, the context shape, copy and data are identical to the Vue
recipe; only the data/URL/mutation layer changes.

Sibling recipes: [Vue](../vue/record-form.md) ·
[Inertia](../inertia/record-form.md). The listing this page belongs with is
[Records Workspace (Nuxt)](./records-workspace.md).

## Prerequisites

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell` and `usePageShellContext` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
- `<BbConfirm />` and `<BbToast />` mounted once in `app.vue` — never in a page.
- Server routes: `GET /api/invoices/:id`, `POST /api/invoices`,
  `PUT /api/invoices/:id`, `DELETE /api/invoices/:id` (422 on validation
  failure with `{ errors: { field: ['message'] } }`), plus
  `GET /api/customers`, `GET /api/projects` and a
  `GET /api/customers/:id/detail` endpoint backing the peek.

## Key ideas

- **One coopting page context.** `provideInvoiceForm()` joins the
  page-shell stack once, owns the draft, the server errors, the dirty
  snapshot and every action (including the route-leave guard). Every leaf
  calls `useInvoiceForm()` and nothing else — cells, sections, the sticky
  bar and the peek share state with zero prop drilling.
- **The draft is the page's single mutable surface.** Inline cell edits,
  the peek's "apply billing defaults", add/duplicate/remove line — all of
  it mutates `ctx.draft`. The API boundary is exactly one call: `persist()`,
  whose `FetchError` 422 response (`error.data.errors`) maps back onto the
  same draft's fields.
- **422 errors reach every input — including table rows.** Laravel-style
  keys (`customerId`, `lineItems.2.unitPrice`) land in one `errors` map;
  scalar fields bind `ctx.errors.value.<key>` and the editable cells
  resolve their row key through `ctx.lineItemError(line, field)`.
- **Tied selects are declarative.** Project depends on customer via
  `dependencies` + `enforce-coherence`; switching customers refetches the
  projects and clears a now-invalid pick automatically. No watchers.
- **Line items are an inline-editing table (§6.3).** One leaf per cell
  type — description, quantity, unit price — each swapping to an input on
  click, committing on blur/Enter and reverting on Esc. The amount column
  is virtual, computed from the row.
- **The invoice loads through `useAsyncData`, keyed on the route param.**
  `loaded` derives from its `pending` state instead of a manual ref. Dirty
  state stays a JSON snapshot, re-baselined before every navigation the
  page itself causes (save redirect, delete redirect) — `navigateTo` in
  place of `router.push` — so the route-leave confirm only fires on
  genuinely abandoned edits.
- **Clicking the customer's name peeks the customer** — a workbench, not a
  preview: billing profile, stats, recent invoices, and an action that
  writes the customer's defaults back into the draft.
- **Buttons are `md` by default;** `sm` only in the line-items table and
  the peek. One `variant="primary"`: the save. No filter rail, no tabs, no
  bulk bar — the form archetype has no list to filter and no selection.

## Page anatomy

```
InvoiceForm/
	Index.vue                   ← assembly: PageShell slots, header, <form>, sections
	context.ts                  ← coopting page context (shell + draft + errors + actions + leave guard)
	DetailsSection.vue          ← tied selects, dates, terms, PO, tax rate
	LineItemsSection.vue        ← editable BbTable + add line + live totals
	EditableDescriptionCell.vue ← inline text edit (commit on blur/Enter, Esc reverts)
	EditableQuantityCell.vue    ← inline quantity edit, same grammar
	EditableRateCell.vue        ← inline unit-price edit, currency-formatted display
	NotesSection.vue            ← BbCollapsible disclosure over notes + terms
	FormActions.vue             ← sticky action row: delete / cancel / save draft / save
	CustomerPeek.vue            ← sidebar workbench for the picked customer
```

Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
(left nav + fat footer) and [Page Shell](../../guides/page-shell.md)
(topbar / content / stacked sidebar). The floating bottom panel is
deliberately absent — it is selection chrome, and a form has no selection.

## Action inventory

| #   | Action                          | Trigger                               | Mechanism                                                                  |
| --- | ------------------------------- | ------------------------------------- | -------------------------------------------------------------------------- |
| 1   | Save invoice                    | sticky bar, the page's one `primary`  | `type="submit"` → `persist()` (`$fetch` + `FetchError` 422) + `navigateTo` |
| 2   | Save as draft                   | sticky bar outline (create mode)      | `persist('draft')`, `navigateTo` swaps URL to edit in place                |
| 3   | Delete invoice                  | sticky bar destructive (edit mode)    | `useConfirm` → `$fetch` DELETE → toast → `navigateTo`                      |
| 4   | Cancel                          | sticky bar ghost                      | navigation (`to`); leave guard intercepts if dirty                         |
| 5   | Pick customer                   | details section select                | query-aware `items` provider                                               |
| 6   | Pick project                    | details section select                | `dependencies` + `enforce-coherence` (§ tied selects)                      |
| 7   | Peek customer                   | "View customer" link under the select | `ctx.peekCustomer()` → shell stack                                         |
| 8   | Apply billing defaults          | peek workbench button                 | writes terms + tax rate into the draft, toast                              |
| 9   | Edit description inline         | line-item cell                        | §6.3: commit on blur/Enter, Esc reverts                                    |
| 10  | Edit quantity / rate inline     | line-item cells                       | §6.3 with `BbNumberInput` (min/precision enforced)                         |
| 11  | Add line item                   | section header + empty state          | `ctx.addLineItem()` pushes a blank draft row                               |
| 12  | Duplicate line                  | row actions                           | `ctx.duplicateLineItem(line)` inserts a copy below                         |
| 13  | Remove line                     | row actions                           | `ctx.removeLineItem(line)`                                                 |
| 14  | Search line items               | topbar page search                    | `lineItemSearch` → `visibleLineItems` filter                               |
| 15  | Toggle notes & terms            | section disclosure button             | `BbCollapsible` + `aria-expanded`/`aria-controls`                          |
| 16  | Open customer / recent invoices | peek links                            | real `to` navigation (leave guard applies)                                 |

## The code

### The shapes

What `@/types` contributes and what `GET /api/invoices/2107` returns — the
record every block below is grounded in:

```ts
// @/types (excerpt)
export type InvoiceStatus = 'draft' | 'pending' | 'paid' | 'overdue';

export interface LineItemDraft {
	/** Server id; unsaved rows carry a negative local id. */
	id: number;
	description: string;
	quantity: number;
	unitPrice: number;
}

export interface InvoiceDraft {
	customerId: number | null;
	projectId: number | null;
	/** `YYYY-MM-DD` (the date inputs run with `floating`). */
	issuedAt: string | null;
	dueDate: string | null;
	paymentTerms: string | null;
	poNumber: string | null;
	taxRate: number | null;
	lineItems: LineItemDraft[];
	notes: string | null;
	terms: string | null;
}
```

```ts
// The invoice being edited (GET /api/invoices/2107)
const invoice = {
	id: 2107,
	number: 'INV-2107',
	status: 'draft',
	customerId: 18, // Northwind Traders
	projectId: 112, // Website relaunch
	issuedAt: '2026-07-01',
	dueDate: '2026-07-31',
	paymentTerms: 'Net 30',
	poNumber: 'PO-2026-0641',
	taxRate: 8.875,
	lineItems: [
		{
			id: 9001,
			description: 'Design sprint — homepage & navigation',
			quantity: 3,
			unitPrice: 1850,
		},
		{
			id: 9002,
			description: 'Frontend build — catalogue & product views',
			quantity: 5,
			unitPrice: 1200,
		},
		{
			id: 9003,
			description: 'CMS integration & content migration',
			quantity: 2,
			unitPrice: 1400,
		},
		{
			id: 9004,
			description: 'QA & cross-browser pass',
			quantity: 1,
			unitPrice: 950,
		},
		{
			id: 9005,
			description: 'Staging infrastructure (June)',
			quantity: 1,
			unitPrice: 240,
		},
	],
	notes: 'Second milestone of the relaunch engagement. Hosting billed at cost.',
	terms:
		'Payment due within 30 days. 1.5% monthly interest on overdue balances.',
};
```

### context.ts

```ts
// InvoiceForm/context.ts
import {
	computed,
	inject,
	provide,
	reactive,
	ref,
	watch,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import { onBeforeRouteLeave } from 'vue-router';
import { FetchError } from 'ofetch';
import { useConfirm, useToast } from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import type {
	Customer,
	CustomerDetail,
	Invoice,
	InvoiceDraft,
	InvoiceStatus,
	LineItemDraft,
	Project,
} from '@/types';

/** What the stacked sidebar can show. Clicking the customer's name pushes one. */
export type PeekItem = { type: 'customer'; id: number };

type LineItemField = 'description' | 'quantity' | 'unitPrice';

export interface InvoiceFormContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	// -- Page-owned state ------------------------------------------------------
	mode: 'create' | 'edit';
	loaded: ComputedRef<boolean>;
	invoiceNumber: Ref<string | null>;
	status: Ref<InvoiceStatus>;
	draft: InvoiceDraft;
	/** Server 422 errors, keyed Laravel-style (`customerId`, `lineItems.2.unitPrice`). */
	errors: Ref<Record<string, string[]>>;
	saving: Ref<boolean>;
	isDirty: ComputedRef<boolean>;
	lineItemSearch: Ref<string>;
	visibleLineItems: ComputedRef<LineItemDraft[]>;
	subtotal: ComputedRef<number>;
	taxAmount: ComputedRef<number>;
	total: ComputedRef<number>;
	// -- Item providers (handed straight to the selects) ------------------------
	fetchCustomers: (query: string, prefill: boolean) => Promise<Customer[]>;
	fetchProjects: () => Promise<Project[]>;
	// -- Row-level error lookup --------------------------------------------------
	lineItemError: (
		line: LineItemDraft,
		field: LineItemField
	) => string[] | undefined;
	// -- Draft mutations (the cells and the peek write through these) -----------
	updateLineItem: (
		line: LineItemDraft,
		patch: Partial<Omit<LineItemDraft, 'id'>>
	) => void;
	addLineItem: () => void;
	duplicateLineItem: (line: LineItemDraft) => void;
	removeLineItem: (line: LineItemDraft) => void;
	applyCustomerDefaults: (customer: CustomerDetail) => void;
	// -- Peek grammar ------------------------------------------------------------
	peekCustomer: () => void;
	// -- Actions (complete: API + 422 mapping + toast + redirect) ----------------
	saveInvoice: () => Promise<void>;
	saveAsDraft: () => Promise<void>;
	deleteInvoice: () => Promise<void>;
}

const key: InjectionKey<InvoiceFormContext> = Symbol('invoice-form');

export function provideInvoiceForm(): InvoiceFormContext {
	const { toast } = useToast();
	const { confirm } = useConfirm();

	// -- Coopt the shell: once, here, for the whole page. ------------------------
	const shell = usePageShellContext<PeekItem>();

	// /invoices/create has no id; /invoices/:id/edit does.
	const route = useRoute();
	// `const` is safe here: Nuxt file-based routing renders `/invoices/create`
	// and `/invoices/:id/edit` from SEPARATE page files, so the create→edit
	// `navigateTo(…, { replace: true })` in `saveAsDraft` REMOUNTS this component
	// — setup re-runs against the new route and `mode` re-derives to 'edit' on
	// its own. (Contrast the Vue recipe, where one component serves both routes,
	// so it is patched in place and must promote `mode` by hand.)
	const invoiceId = route.params.id ? Number(route.params.id) : null;
	const mode: 'create' | 'edit' = invoiceId === null ? 'create' : 'edit';

	// -- The draft ---------------------------------------------------------------
	// Unsaved rows get negative local ids so `item-value` stays stable and the
	// payload can tell the server which lines are new (negative → null).
	let nextLocalId = -1;
	const blankLineItem = (): LineItemDraft => ({
		id: nextLocalId--,
		description: '',
		quantity: 1,
		unitPrice: 0,
	});

	const draft = reactive<InvoiceDraft>({
		customerId: null,
		projectId: null,
		issuedAt: null,
		dueDate: null,
		paymentTerms: null,
		poNumber: null,
		taxRate: null,
		lineItems: [blankLineItem()],
		notes: null,
		terms: null,
	});

	const invoiceNumber = ref<string | null>(null);
	const status = ref<InvoiceStatus>('draft');
	const errors = ref<Record<string, string[]>>({});
	const saving = ref(false);
	const snapshot = ref(JSON.stringify(draft));

	// The invoice itself loads through useAsyncData, keyed on the route param;
	// `loaded` derives from its pending state instead of a manual ref (`true`
	// straight away in create mode, since there is nothing to fetch).
	const { data: loadedInvoice, pending } = useAsyncData<Invoice | null>(
		`invoice-form-${invoiceId ?? 'new'}`,
		() =>
			invoiceId === null
				? Promise.resolve(null)
				: $fetch<Invoice>(`/api/invoices/${invoiceId}`)
	);
	const loaded = computed(() => mode === 'create' || !pending.value);

	watch(
		loadedInvoice,
		(invoice) => {
			if (!invoice) return;
			invoiceNumber.value = invoice.number;
			status.value = invoice.status;
			draft.customerId = invoice.customerId;
			draft.projectId = invoice.projectId;
			draft.issuedAt = invoice.issuedAt;
			draft.dueDate = invoice.dueDate;
			draft.paymentTerms = invoice.paymentTerms;
			draft.poNumber = invoice.poNumber;
			draft.taxRate = invoice.taxRate;
			draft.lineItems = invoice.lineItems.map((line) => ({ ...line }));
			draft.notes = invoice.notes;
			draft.terms = invoice.terms;
			snapshot.value = JSON.stringify(draft);
		},
		{ immediate: true }
	);

	// Dirty = the draft's JSON diverged from the last committed snapshot.
	// Gated on `loaded` so the async seed of edit mode never reads as dirty.
	const isDirty = computed(
		() => loaded.value && JSON.stringify(draft) !== snapshot.value
	);

	// -- Item providers -----------------------------------------------------------
	// Component-initiated calls (`prefill === true`) must keep the current
	// selection resolvable, or the chip loses its text.
	const fetchCustomers = async (
		query: string,
		prefill: boolean
	): Promise<Customer[]> => {
		if (prefill && draft.customerId !== null) {
			return $fetch<Customer[]>('/api/customers', {
				query: { ids: [draft.customerId] },
			});
		}
		return $fetch<Customer[]>('/api/customers', { query: { search: query } });
	};

	// Re-run by the project select's `dependencies: [draft.customerId]`; the
	// response always contains the customer's full project list, so an existing
	// `projectId` stays resolvable and `enforce-coherence` never wipes a valid pick.
	const fetchProjects = (): Promise<Project[]> =>
		draft.customerId === null
			? Promise.resolve([])
			: $fetch<Project[]>('/api/projects', {
					query: { customer: draft.customerId },
				});

	// -- Line items -----------------------------------------------------------------
	const lineItemSearch = ref('');
	const visibleLineItems = computed(() => {
		// A `clearable` BbTextInput emits **null** when emptied, not `''` — coalesce
		// before calling a string method, or the first clear throws
		// `Cannot read properties of null (reading 'trim')`.
		const query = (lineItemSearch.value ?? '').trim().toLowerCase();
		if (!query) return draft.lineItems;
		return draft.lineItems.filter((line) =>
			line.description.toLowerCase().includes(query)
		);
	});

	const subtotal = computed(() =>
		draft.lineItems.reduce(
			(sum, line) => sum + line.quantity * line.unitPrice,
			0
		)
	);
	const taxAmount = computed(
		() => subtotal.value * ((draft.taxRate ?? 0) / 100)
	);
	const total = computed(() => subtotal.value + taxAmount.value);

	// Server 422 keys index lines by payload position, which is draft order —
	// resolve a row's key through its id so the lookup survives filtering.
	const lineItemError = (
		line: LineItemDraft,
		field: LineItemField
	): string[] | undefined => {
		const index = draft.lineItems.findIndex(
			(candidate) => candidate.id === line.id
		);
		return errors.value[`lineItems.${index}.${field}`];
	};

	const updateLineItem = (
		line: LineItemDraft,
		patch: Partial<Omit<LineItemDraft, 'id'>>
	) => {
		const target = draft.lineItems.find(
			(candidate) => candidate.id === line.id
		);
		if (target) Object.assign(target, patch);
	};
	const addLineItem = () => {
		draft.lineItems.push(blankLineItem());
	};
	const duplicateLineItem = (line: LineItemDraft) => {
		const index = draft.lineItems.findIndex(
			(candidate) => candidate.id === line.id
		);
		draft.lineItems.splice(index + 1, 0, { ...line, id: nextLocalId-- });
	};
	const removeLineItem = (line: LineItemDraft) => {
		draft.lineItems = draft.lineItems.filter(
			(candidate) => candidate.id !== line.id
		);
	};

	// The peek writes back into the draft: the sidebar is a workbench.
	const applyCustomerDefaults = (customer: CustomerDetail) => {
		draft.paymentTerms = customer.defaultPaymentTerms;
		draft.taxRate = customer.defaultTaxRate;
		toast({
			title: `Applied ${customer.name}'s billing defaults.`,
			variant: 'success',
		});
	};

	// -- Peek grammar ----------------------------------------------------------------
	const peekCustomer = () => {
		if (draft.customerId === null) return;
		shell.push({ type: 'customer', id: draft.customerId }, true);
	};

	// -- Persistence -----------------------------------------------------------------
	// New lines travel with `id: null`; the server assigns real ids on save.
	const payload = (nextStatus: InvoiceStatus) => ({
		...draft,
		status: nextStatus,
		lineItems: draft.lineItems.map((line) => ({
			...line,
			id: line.id > 0 ? line.id : null,
		})),
	});

	const persist = async (
		nextStatus: InvoiceStatus
	): Promise<Invoice | null> => {
		saving.value = true;
		errors.value = {};
		try {
			const saved =
				mode === 'edit' && invoiceId !== null
					? await $fetch<Invoice>(`/api/invoices/${invoiceId}`, {
							method: 'PUT',
							body: payload(nextStatus),
						})
					: await $fetch<Invoice>('/api/invoices', {
							method: 'POST',
							body: payload(nextStatus),
						});
			// Re-baseline BEFORE navigating so the leave guard lets the redirect through.
			snapshot.value = JSON.stringify(draft);
			status.value = saved.status;
			invoiceNumber.value = saved.number;
			return saved;
		} catch (error: unknown) {
			if (error instanceof FetchError && error.statusCode === 422) {
				// Laravel-style: { errors: { 'lineItems.2.unitPrice': ['Must be positive.'] } }
				errors.value = (error.data?.errors as Record<string, string[]>) ?? {};
				toast({ title: 'Some fields need attention.', variant: 'destructive' });
			} else {
				toast({
					title: 'Something went wrong. Try again.',
					variant: 'destructive',
				});
			}
			return null;
		} finally {
			saving.value = false;
		}
	};

	const saveInvoice = async () => {
		// Creating finalizes the invoice; editing keeps whatever status it has.
		const saved = await persist(mode === 'edit' ? status.value : 'pending');
		if (!saved) return;
		toast({ title: `Invoice ${saved.number} saved.`, variant: 'success' });
		await navigateTo(`/invoices/${saved.id}`);
	};

	const saveAsDraft = async () => {
		const saved = await persist('draft');
		if (!saved) return;
		toast({ title: `Draft ${saved.number} saved.`, variant: 'success' });
		// Swap the URL to the edit route. Nuxt remounts the component there, so it
		// comes back up in edit mode against the freshly-created invoice — no
		// manual promotion needed (and "Save as draft" is a create-only action,
		// so it isn't shown again).
		if (mode === 'create') {
			await navigateTo(`/invoices/${saved.id}/edit`, { replace: true });
		}
	};

	const deleteInvoice = async () => {
		if (mode !== 'edit' || invoiceId === null) return;
		const ok = await confirm({
			variant: 'destructive',
			title: 'Delete invoice',
			text: `Delete ${invoiceNumber.value}? This cannot be undone.`,
			yes: 'Delete',
			no: 'Cancel',
		});
		if (!ok) return;
		await $fetch(`/api/invoices/${invoiceId}`, { method: 'DELETE' });
		// Re-baseline so the guard doesn't ask about a record that no longer exists.
		snapshot.value = JSON.stringify(draft);
		toast({ title: `${invoiceNumber.value} deleted.`, variant: 'success' });
		await navigateTo('/invoices');
	};

	// -- Route-leave guard ---------------------------------------------------------
	// Lives with the state it protects. `onBeforeRouteLeave` works unchanged in
	// Nuxt pages because `provideInvoiceForm()` runs in the page's setup.
	onBeforeRouteLeave(async () => {
		if (!isDirty.value) return true;
		return await confirm({
			variant: 'destructive',
			title: 'Unsaved changes',
			text: 'You have unsaved changes on this invoice. Leave without saving?',
			yes: 'Discard changes',
			no: 'Keep editing',
		});
	});

	const ctx: InvoiceFormContext = {
		shell,
		mode,
		loaded,
		invoiceNumber,
		status,
		draft,
		errors,
		saving,
		isDirty,
		lineItemSearch,
		visibleLineItems,
		subtotal,
		taxAmount,
		total,
		fetchCustomers,
		fetchProjects,
		lineItemError,
		updateLineItem,
		addLineItem,
		duplicateLineItem,
		removeLineItem,
		applyCustomerDefaults,
		peekCustomer,
		saveInvoice,
		saveAsDraft,
		deleteInvoice,
	};
	provide(key, ctx);
	return ctx;
}

export function useInvoiceForm(): InvoiceFormContext {
	const ctx = inject(key);
	if (!ctx) throw new Error('useInvoiceForm() called outside InvoiceForm');
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- InvoiceForm/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left, page search right. The search scopes the
		     work surface — here, the line-items table. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs class="min-w-0 flex-auto" :items="trail" />
				<BbTextInput
					v-model="ctx.lineItemSearch.value"
					autocomplete="off"
					class="shrink-0"
					clearable
					compact
					hide-label
					label="Search line items"
					placeholder="Search line items…"
					prepend:icon="lucide:search"
				/>
			</div>
		</template>

		<div
			v-if="ctx.loaded.value"
			class="mx-auto flex w-full max-w-4xl flex-col gap-6 p-4"
		>
			<header class="flex items-center gap-3">
				<h1 class="text-lg font-semibold">
					{{
						ctx.mode === 'edit'
							? `Edit ${ctx.invoiceNumber.value}`
							: 'New invoice'
					}}
				</h1>
				<BbBadge v-if="ctx.mode === 'edit'" variant="outline">{{
					ctx.status.value
				}}</BbBadge>
			</header>

			<!-- One form, one submit. `novalidate` keeps error UX on the inputs'
			     `errors` surface instead of browser bubbles. -->
			<form
				class="flex flex-col gap-6"
				novalidate
				@submit.prevent="ctx.saveInvoice"
			>
				<DetailsSection />
				<LineItemsSection />
				<NotesSection />
				<FormActions />
			</form>
		</div>

		<div v-else class="flex justify-center p-12">
			<BbSpinner label="Loading invoice…" />
		</div>

		<!-- Stacked peek sidebar: the shell owns back/close; we render by type. -->
		<template #sidebar>
			<CustomerPeek
				v-if="ctx.shell.current.value?.type === 'customer'"
				:customer-id="ctx.shell.current.value.id"
			/>
		</template>
	</PageShell>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbBadge, BbBreadcrumbs, BbSpinner, BbTextInput } from 'bitboss-ui';
import PageShell from '@/components/layout/PageShell.vue';
import { provideInvoiceForm } from './context';
import CustomerPeek from './CustomerPeek.vue';
import DetailsSection from './DetailsSection.vue';
import FormActions from './FormActions.vue';
import LineItemsSection from './LineItemsSection.vue';
import NotesSection from './NotesSection.vue';

const ctx = provideInvoiceForm();

// A real trail, ≥ 2 linked levels; the current page carries no target.
const trail = computed(() => [
	{ key: 'dashboard', text: 'Dashboard', to: '/dashboard' },
	{ key: 'billing', text: 'Billing', to: '/billing' },
	{ key: 'invoices', text: 'Invoices', to: '/invoices' },
	{
		key: 'invoice',
		text:
			ctx.mode === 'edit'
				? (ctx.invoiceNumber.value ?? 'Invoice')
				: 'New invoice',
	},
]);
</script>
```

### DetailsSection.vue

```vue
<!-- InvoiceForm/DetailsSection.vue -->
<template>
	<section class="flex flex-col gap-3">
		<h2
			class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
		>
			Details
		</h2>

		<div class="grid gap-4 sm:grid-cols-2">
			<!-- Tied selects: project depends on customer. `dependencies` re-runs
			     the project provider; `enforce-coherence` clears a project that is
			     no longer among the new options. No watchers. -->
			<div class="flex flex-col gap-1">
				<BbSelect
					v-model="ctx.draft.customerId"
					:errors="ctx.errors.value.customerId"
					item-text="name"
					item-value="id"
					:items="ctx.fetchCustomers"
					label="Customer"
					placeholder="Search customers…"
				/>
				<!-- Clicking the NAME of a thing peeks it. -->
				<BbButton
					v-if="ctx.draft.customerId !== null"
					append:icon="lucide:panel-right-open"
					class="self-start"
					size="sm"
					variant="link"
					@click="ctx.peekCustomer"
				>
					View customer
				</BbButton>
			</div>

			<BbSelect
				v-model="ctx.draft.projectId"
				:dependencies="[ctx.draft.customerId]"
				:disabled="ctx.draft.customerId === null"
				enforce-coherence
				:errors="ctx.errors.value.projectId"
				item-text="name"
				item-value="id"
				:items="ctx.fetchProjects"
				label="Project"
				placeholder="Pick the customer first"
			/>

			<!-- `floating` keeps the model a plain YYYY-MM-DD string, so the due
			     date's `min` can be fed straight from the issue date. -->
			<BbDatePickerInput
				v-model="ctx.draft.issuedAt"
				:errors="ctx.errors.value.issuedAt"
				floating
				label="Issue date"
				prepend:icon="lucide:calendar"
			/>
			<BbDatePickerInput
				v-model="ctx.draft.dueDate"
				:errors="ctx.errors.value.dueDate"
				floating
				label="Due date"
				:min="ctx.draft.issuedAt ?? undefined"
				prepend:icon="lucide:calendar"
			/>

			<BbSelect
				v-model="ctx.draft.paymentTerms"
				:errors="ctx.errors.value.paymentTerms"
				:items="['Due on receipt', 'Net 15', 'Net 30', 'Net 60']"
				label="Payment terms"
				placeholder="Choose terms"
			/>

			<BbTextInput
				v-model="ctx.draft.poNumber"
				:errors="ctx.errors.value.poNumber"
				label="PO / reference"
				placeholder="PO-2026-0641"
			/>

			<BbNumberInput
				v-model="ctx.draft.taxRate"
				:errors="ctx.errors.value.taxRate"
				hint="Applied to the subtotal below."
				label="Tax rate"
				:max="100"
				:max-precision="3"
				:min="0"
			>
				<template #suffix>%</template>
			</BbNumberInput>
		</div>
	</section>
</template>

<script setup lang="ts">
import {
	BbButton,
	BbDatePickerInput,
	BbNumberInput,
	BbSelect,
	BbTextInput,
} from 'bitboss-ui';
import { useInvoiceForm } from './context';

const ctx = useInvoiceForm();
</script>
```

### LineItemsSection.vue

```vue
<!-- InvoiceForm/LineItemsSection.vue -->
<template>
	<section class="flex flex-col gap-3">
		<div class="flex items-center justify-between">
			<h2
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Line items
			</h2>
			<BbButton
				prepend:icon="lucide:plus"
				variant="outline"
				@click="ctx.addLineItem"
			>
				Add line item
			</BbButton>
		</div>

		<!-- Inline-editing table (§6.3): every editable cell type is its own
		     leaf. The amount column is virtual — computed from the row. -->
		<BbTable
			actions
			caption="Invoice line items"
			:columns="columns"
			compact
			item-value="id"
			:items="ctx.visibleLineItems.value"
		>
			<template #description="{ item }">
				<EditableDescriptionCell :line="item" />
			</template>

			<template #quantity="{ item }">
				<EditableQuantityCell :line="item" />
			</template>

			<template #unit_price="{ item }">
				<EditableRateCell :line="item" />
			</template>

			<template #actions="{ item }">
				<div class="flex items-center justify-end gap-1">
					<BbButton
						icon="lucide:copy"
						size="sm"
						variant="ghost"
						@click="() => ctx.duplicateLineItem(item)"
					>
						Duplicate line
					</BbButton>
					<BbButton
						icon="lucide:trash-2"
						size="sm"
						variant="ghost"
						@click="() => ctx.removeLineItem(item)"
					>
						Remove line
					</BbButton>
				</div>
			</template>

			<template #no-data>
				<div class="flex flex-col items-center gap-2 p-6 text-center">
					<p class="text-sm text-[color:var(--bb-text-muted)]">
						{{
							ctx.lineItemSearch.value
								? 'No line items match your search.'
								: 'No line items yet.'
						}}
					</p>
					<BbButton
						v-if="!ctx.lineItemSearch.value"
						variant="outline"
						@click="ctx.addLineItem"
					>
						Add the first line
					</BbButton>
				</div>
			</template>
		</BbTable>

		<!-- Totals: live computed from the draft — they move as cells commit. -->
		<dl class="ml-auto grid w-60 grid-cols-[1fr_auto] gap-y-1 text-sm">
			<dt class="text-[color:var(--bb-text-muted)]">Subtotal</dt>
			<dd class="text-right tabular-nums">
				{{ currency.format(ctx.subtotal.value) }}
			</dd>
			<dt class="text-[color:var(--bb-text-muted)]">
				Tax ({{ ctx.draft.taxRate ?? 0 }}%)
			</dt>
			<dd class="text-right tabular-nums">
				{{ currency.format(ctx.taxAmount.value) }}
			</dd>
			<dt class="font-semibold">Total</dt>
			<dd class="text-right font-semibold tabular-nums">
				{{ currency.format(ctx.total.value) }}
			</dd>
		</dl>
	</section>
</template>

<script setup lang="ts">
import { BbButton, BbTable } from 'bitboss-ui';
import EditableDescriptionCell from './EditableDescriptionCell.vue';
import EditableQuantityCell from './EditableQuantityCell.vue';
import EditableRateCell from './EditableRateCell.vue';
import { useInvoiceForm } from './context';
import type { LineItemDraft } from '@/types';

const ctx = useInvoiceForm();

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});

// `unit_price` and `amount` match no item field on purpose: the first is
// fully slotted (snake_case key so the slot name reads naturally), the
// second is a virtual column deriving its content in the formatter.
const columns = [
	{ key: 'description', label: 'Description' },
	{ key: 'quantity', label: 'Qty', align: 'right' as const, width: 96 },
	{
		key: 'unit_price',
		label: 'Unit price',
		align: 'right' as const,
		width: 140,
	},
	{
		key: 'amount',
		label: 'Amount',
		align: 'right' as const,
		width: 130,
		formatter: (_: unknown, __: string, item: LineItemDraft) =>
			currency.format(item.quantity * item.unitPrice),
	},
];
</script>
```

### EditableDescriptionCell.vue

```vue
<!-- InvoiceForm/EditableDescriptionCell.vue -->
<template>
	<BbTextInput
		v-if="editing"
		v-model="value"
		autofocus
		compact
		:errors="ctx.lineItemError(line, 'description')"
		hide-label
		label="Line description"
		placeholder="What was delivered?"
		@blur="commit"
		@keydown.enter.prevent="commit"
		@keydown.esc="revert"
	/>
	<button
		v-else
		class="w-full rounded-[var(--bb-radius)] px-1 py-0.5 text-left hover:bg-[color:var(--bb-hover)]"
		:class="{
			'text-[color:var(--bb-text-muted)]': !line.description,
			'text-red-600 dark:text-red-400': hasError,
		}"
		type="button"
		@click="start"
	>
		{{ line.description || 'Add a description…' }}
	</button>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbTextInput } from 'bitboss-ui';
import { useInvoiceForm } from './context';
import type { LineItemDraft } from '@/types';

const props = defineProps<{ line: LineItemDraft }>();

const ctx = useInvoiceForm();

// Rung 1 of the ladder: only this cell reads or writes its editing state.
const editing = ref(false);
const value = ref<string | null>(null);

const hasError = computed(() => !!ctx.lineItemError(props.line, 'description'));

const start = () => {
	value.value = props.line.description;
	editing.value = true;
};

// Commit on blur/Enter, revert on Esc (§6.3). Enter is prevented so it
// edits the cell instead of submitting the enclosing invoice form; the
// `editing` guard keeps the blur that follows an Esc from re-committing.
const commit = () => {
	if (!editing.value) return;
	editing.value = false;
	ctx.updateLineItem(props.line, { description: value.value ?? '' });
};

const revert = () => {
	editing.value = false;
};
</script>
```

### EditableQuantityCell.vue

```vue
<!-- InvoiceForm/EditableQuantityCell.vue -->
<template>
	<BbNumberInput
		v-if="editing"
		v-model="value"
		autofocus
		compact
		:errors="ctx.lineItemError(line, 'quantity')"
		hide-label
		label="Quantity"
		:max-precision="2"
		:min="0"
		@blur="commit"
		@keydown.enter.prevent="commit"
		@keydown.esc="revert"
	/>
	<button
		v-else
		class="w-full rounded-[var(--bb-radius)] px-1 py-0.5 text-right tabular-nums hover:bg-[color:var(--bb-hover)]"
		:class="{ 'text-red-600 dark:text-red-400': hasError }"
		type="button"
		@click="start"
	>
		{{ line.quantity }}
	</button>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbNumberInput } from 'bitboss-ui';
import { useInvoiceForm } from './context';
import type { LineItemDraft } from '@/types';

const props = defineProps<{ line: LineItemDraft }>();

const ctx = useInvoiceForm();

const editing = ref(false);
const value = ref<number | null>(null);

const hasError = computed(() => !!ctx.lineItemError(props.line, 'quantity'));

const start = () => {
	value.value = props.line.quantity;
	editing.value = true;
};

const commit = () => {
	if (!editing.value) return;
	editing.value = false;
	// An emptied field emits null — treat it as a revert, not a zero.
	if (value.value === null) return;
	ctx.updateLineItem(props.line, { quantity: value.value });
};

const revert = () => {
	editing.value = false;
};
</script>
```

### EditableRateCell.vue

```vue
<!-- InvoiceForm/EditableRateCell.vue -->
<template>
	<BbNumberInput
		v-if="editing"
		v-model="value"
		autofocus
		compact
		:errors="ctx.lineItemError(line, 'unitPrice')"
		hide-label
		label="Unit price"
		:max-precision="2"
		:min="0"
		@blur="commit"
		@keydown.enter.prevent="commit"
		@keydown.esc="revert"
	>
		<template #prefix>$</template>
	</BbNumberInput>
	<button
		v-else
		class="w-full rounded-[var(--bb-radius)] px-1 py-0.5 text-right tabular-nums hover:bg-[color:var(--bb-hover)]"
		:class="{ 'text-red-600 dark:text-red-400': hasError }"
		type="button"
		@click="start"
	>
		{{ currency.format(line.unitPrice) }}
	</button>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbNumberInput } from 'bitboss-ui';
import { useInvoiceForm } from './context';
import type { LineItemDraft } from '@/types';

const props = defineProps<{ line: LineItemDraft }>();

const ctx = useInvoiceForm();

const editing = ref(false);
const value = ref<number | null>(null);

const hasError = computed(() => !!ctx.lineItemError(props.line, 'unitPrice'));

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});

const start = () => {
	value.value = props.line.unitPrice;
	editing.value = true;
};

const commit = () => {
	if (!editing.value) return;
	editing.value = false;
	if (value.value === null) return;
	ctx.updateLineItem(props.line, { unitPrice: value.value });
};

const revert = () => {
	editing.value = false;
};
</script>
```

### NotesSection.vue

```vue
<!-- InvoiceForm/NotesSection.vue -->
<template>
	<section class="flex flex-col gap-2">
		<!-- BbCollapsible ships no trigger: this button owns the disclosure
		     ARIA (`aria-expanded` + `aria-controls`). -->
		<BbButton
			append:icon="lucide:chevron-down"
			aria-controls="invoice-notes"
			:aria-expanded="open"
			class="self-start"
			variant="ghost"
			@click="open = !open"
		>
			Notes &amp; terms
		</BbButton>

		<!-- `eager` mounts the fields up front so their 422 errors render even
		     if the user never opened the section. Spacing lives on the inner
		     content — the collapsible zeroes its own box when closed. -->
		<BbCollapsible id="invoice-notes" v-model="open" eager>
			<div class="flex flex-col gap-4 pt-1">
				<BbTextarea
					v-model="ctx.draft.notes"
					auto-grow
					description="Shown on the invoice, under the line items."
					:errors="ctx.errors.value.notes"
					label="Notes to the customer"
					placeholder="Second milestone of the relaunch engagement…"
					:rows="2"
				/>
				<BbTextarea
					v-model="ctx.draft.terms"
					auto-grow
					description="Payment terms printed in the invoice footer."
					:errors="ctx.errors.value.terms"
					label="Terms"
					placeholder="Payment due within 30 days…"
					:rows="2"
				/>
			</div>
		</BbCollapsible>
	</section>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbCollapsible, BbTextarea } from 'bitboss-ui';
import { useInvoiceForm } from './context';

const ctx = useInvoiceForm();

// Rung 1: only this section cares whether it is open. The section mounts
// after the invoice loaded (Index gates on ctx.loaded), so seeding from the
// draft starts an annotated invoice open and a blank one closed.
const open = ref(ctx.draft.notes !== null || ctx.draft.terms !== null);
</script>
```

### FormActions.vue

```vue
<!-- InvoiceForm/FormActions.vue -->
<template>
	<!-- Sticky action row: the commit affordance never scrolls away. Not the
	     floating bottom panel — that is selection chrome, and a form has no
	     selection. -->
	<div
		class="sticky bottom-0 z-10 -mx-4 flex items-center gap-3 border-t bg-[color:var(--bb-panel)] px-4 py-3"
	>
		<BbButton
			v-if="ctx.mode === 'edit'"
			prepend:icon="lucide:trash-2"
			variant="destructive"
			@click="ctx.deleteInvoice"
		>
			Delete
		</BbButton>
		<p
			v-if="ctx.isDirty.value"
			class="text-xs text-[color:var(--bb-text-muted)]"
		>
			Unsaved changes
		</p>

		<div class="ml-auto flex items-center gap-2">
			<!-- Cancel is navigation: the route-leave guard asks about a dirty
			     draft, so no bespoke confirm here. -->
			<BbButton :disabled="ctx.saving.value" to="/invoices" variant="ghost">
				Cancel
			</BbButton>
			<BbButton
				v-if="ctx.mode === 'create'"
				:disabled="ctx.saving.value"
				variant="outline"
				@click="ctx.saveAsDraft"
			>
				Save as draft
			</BbButton>
			<BbButton :loading="ctx.saving.value" type="submit" variant="primary">
				{{ ctx.mode === 'edit' ? 'Save changes' : 'Create invoice' }}
			</BbButton>
		</div>
	</div>
</template>

<script setup lang="ts">
import { BbButton } from 'bitboss-ui';
import { useInvoiceForm } from './context';

const ctx = useInvoiceForm();
</script>
```

### CustomerPeek.vue

```vue
<!-- InvoiceForm/CustomerPeek.vue -->
<template>
	<div v-if="customer" class="flex flex-col gap-4 text-sm">
		<header class="flex items-center gap-3">
			<BbAvatar :alt="customer.name" :src="customer.avatarUrl" />
			<div class="flex flex-col">
				<h2 class="text-base font-semibold">{{ customer.name }}</h2>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					{{ customer.email }} · {{ customer.country }}
				</p>
			</div>
		</header>

		<!-- Stat strip. -->
		<div class="grid grid-cols-3 gap-2">
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Total billed</p>
				<p class="font-semibold">{{ currency.format(customer.totalBilled) }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Outstanding</p>
				<p class="font-semibold">{{ currency.format(customer.outstanding) }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Invoices</p>
				<p class="font-semibold">{{ customer.invoiceCount }}</p>
			</div>
		</div>

		<!-- Billing profile: exactly the fields this form negotiates. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Billing profile
			</h3>
			<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
				<dt class="text-[color:var(--bb-text-muted)]">Default terms</dt>
				<dd>{{ customer.defaultPaymentTerms }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Default tax rate</dt>
				<dd>{{ customer.defaultTaxRate }}%</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Tax ID</dt>
				<dd>{{ customer.taxId }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Billing email</dt>
				<dd>{{ customer.billingEmail }}</dd>
			</dl>
			<!-- The peek acts on the form: this writes into the draft. -->
			<BbButton
				class="mt-1 self-start"
				prepend:icon="lucide:sparkles"
				size="sm"
				variant="secondary"
				@click="() => ctx.applyCustomerDefaults(customer!)"
			>
				Apply billing defaults
			</BbButton>
		</section>

		<!-- Recent invoices: real links — leaving a dirty draft still goes
		     through the route-leave guard. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Recent invoices
			</h3>
			<ul class="flex flex-col">
				<li
					v-for="recent in customer.recentInvoices"
					:key="recent.id"
					class="flex items-center justify-between gap-2 border-b py-1.5 last:border-b-0"
				>
					<BbBaseButton class="plain-link" :to="`/invoices/${recent.id}`">
						{{ recent.number }}
					</BbBaseButton>
					<BbBadge variant="outline">{{ recent.status }}</BbBadge>
					<span class="text-xs tabular-nums text-[color:var(--bb-text-muted)]">
						{{ currency.format(recent.amount) }}
					</span>
				</li>
			</ul>
		</section>

		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				append:icon="lucide:arrow-up-right"
				size="sm"
				:to="`/customers/${customer.id}`"
				variant="ghost"
			>
				Open customer
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { ref, watchEffect } from 'vue';
import { BbAvatar, BbBadge, BbButton, BbSpinner } from 'bitboss-ui';
import { useInvoiceForm } from './context';
import type { CustomerDetail } from '@/types';

const props = defineProps<{ customerId: number }>();

const ctx = useInvoiceForm();

const customer = ref<CustomerDetail | null>(null);
watchEffect(async () => {
	customer.value = await $fetch<CustomerDetail>(
		`/api/customers/${props.customerId}/detail`
	);
});

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
</script>
```

## Why it is built this way

- **The context coopts, leaves consume.** The shell is joined once in
  `provideInvoiceForm()`; ten components share the draft, the errors, the
  peek stack and every action through one `useInvoiceForm()` call. The only
  props on the page are data-identity props: the cells' `line` and the
  peek's `customer-id`. Notably there is **no table context** here — the
  line-items table has no selection, no paging and no fetch; its entire
  state _is_ the draft, so there is nothing for a `useBbTableContext`
  handle to carry.
- **The invoice loads through `useAsyncData`, `loaded` derives from
  `pending`.** Keying the fetch on the route param means Nuxt's payload
  caching and SSR hydration work for free; the watcher seeds the draft
  once the data lands, exactly the same seeding logic the Vue recipe runs
  inside a `.then()`.
- **The draft is the mutation boundary.** On a workspace page every action
  hits the API; on a form the unsaved state is the product. Cell commits,
  line add/duplicate/remove and "apply billing defaults" therefore mutate
  `ctx.draft` (still context actions — leaves never reach around it), and
  the single `persist()` call is where `$fetch`, the `FetchError` 422
  mapping, the toast and the snapshot re-baseline live.
- **422 keys are the server's shape, not reshaped.** Scalar inputs bind
  `ctx.errors.value.<field>` directly; row errors keep their
  `lineItems.<index>.<field>` keys and the cells resolve them through
  `lineItemError`, which derives the index from the row's id — so the
  lookup survives the page-search filter reordering what is visible.
- **Tied selects trust the machinery.** `dependencies: [draft.customerId]`
  re-runs the project provider, `enforce-coherence` prunes a stale pick,
  and both providers honor the prefill contract (return the selected
  record on component-initiated calls) so a valid selection is never
  wiped — the exact failure mode the BbSelect guide warns about.
- **The inline-edit grammar is three tiny leaves, not one configurable
  cell.** Each editable cell owns rung-1 state (`editing`, the in-flight
  value), commits on blur/Enter and reverts on Esc. Enter is
  `.prevent`-ed so it commits the cell instead of submitting the enclosing
  form, and the `editing` guard keeps the unmount blur after an Esc from
  re-committing the reverted value.
- **The dirty snapshot re-baselines before every self-inflicted
  navigation** — successful save, draft save, delete — using `navigateTo`
  in place of `router.push`/`router.replace`, so the `onBeforeRouteLeave`
  confirm fires only when the user genuinely walks away. Cancel is a plain
  `to` link for the same reason: the guard _is_ the confirm, so the button
  needs none of its own.
- **A sticky action row, not the floating bottom panel.** The panel from
  the guides is selection-driven chrome that comes and goes; a form's
  commit affordance must be permanently visible, so it is a sticky row on
  the page surface (`--bb-panel` background, top border) hosting the one
  `variant="primary"` of the page.
- **Sizing:** the form fields are full-height — a form is not a dense
  surface. `compact` appears where density is real: the topbar search, the
  line-items table and its cell inputs. `sm` buttons appear only in the
  table's row actions, the "View customer" link and the peek; everything
  in the sticky row is default `md`.
- **Destructive actions ride `useConfirm`** — delete and the leave guard
  both — and the peek is a workbench: it acts on the draft and links out
  with real `to` links, never `@click` + router.

## Variations

- **Inside a `BbDialog`** (quick create from the invoices workspace): drop
  the route guard and breadcrumbs, keep `isDirty`, confirm on the dialog's
  close instead, and move the action row into the dialog `#footer` — the
  context and sections carry over unchanged.
- **Autosave drafts**: debounce a watcher on `draft` that calls
  `persist('draft')` silently and re-baselines per save; the "Save as
  draft" button disappears and the sticky row shows "Saved 12s ago".
- **Client-side pre-validation**: validate required fields on submit
  before calling the API and merge the messages into the same `errors`
  map — the inputs cannot tell the difference, which is the point.
- **Per-line tax**: add an `EditableTaxCell` per row (its own leaf, per
  the no-API-monster rule) and group the totals block by rate.
- **Send flow**: the primary becomes "Save and send" and opens a
  `BbDialog` preview (recipient, subject, PDF) whose open-state lives on
  the context, before persisting with `status: 'pending'`.
- **Per-field persistence**: this page deliberately has no per-cell save
  feedback because no per-cell save exists — the draft is the mutation
  boundary and Save is the one commit. When the domain wants every field
  to persist itself (no Save button), that is the autosave pattern: see
  the [Inline Edit Playbook](../../guides/inline-edit-playbook.md) and
  the inline-edit-workspace recipe.

## Related

- [Records Workspace (Nuxt)](./records-workspace.md) — the listing page
  this form is reached from.
- [Page Shell](../../guides/page-shell.md) — the app-side layout the
  customer peek renders inside.
- [BbTable](../../BbTable.md), [BbSelect](../../BbSelect.md),
  [BbCollapsible](../../BbCollapsible.md) — the components this page
  leans on hardest.

---

<!-- dist/ai/recipes/nuxt/records-workspace.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/nuxt/records-workspace.md -->

# Recipe: Records Workspace (Nuxt)

The flagship advanced-page recipe adapted for **Nuxt**: the same Stripe-
invoices × Linear list workspace — app chrome, breadcrumbs + page search,
chip filter rail (one Filters menu + editable filter chips), href tabs with live counts, a dense server-paged table, a
floating bulk-action bar, and a stacked peek sidebar — but filters and the
active tab live in the URL and the list loads through `useAsyncData`
watching `route.query`. Anatomy, components, the context shape, copy and
data are identical to the Vue recipe; only the data/URL/mutation layer
changes.

Sibling recipes: [Vue](../vue/records-workspace.md) ·
[Inertia](../inertia/records-workspace.md).

## Prerequisites

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell`, `usePageShellContext` and `FloatingBottomPanel` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
- `<BbConfirm />` and `<BbToast />` mounted once in `app.vue` — never in a page.
- [App Layout](../../guides/app-layout.md), [Page Shell](../../guides/page-shell.md)
  and [Floating Bottom Panel](../../guides/floating-bottom-panel.md) copied
  into `src/components/layout/` per their guides — every recipe page assumes
  this chrome exists and renders inside it.
- Server routes: `GET /api/invoices` (accepts `search`, `status[]`,
  `customerId`, `dueBetween[]`, `tab`, `page`, `perPage`, returns
  `{ data, total, tabCounts }`), plus the mutation routes referenced below
  (`PATCH /api/invoices/:id`, `POST /api/invoices/:id/duplicate`, …).

## Key ideas

- **One coopting page context.** `provideInvoicesWorkspace()` joins the
  page-shell stack and the table context once, owns filters/tab/dialogs,
  and exposes complete actions. Every leaf calls `useInvoicesWorkspace()`
  and nothing else — zero prop drilling anywhere on the page.
- **Filters and tab live in the URL, not in local refs.** They are seeded
  from `route.query` at setup and every change writes back through
  `navigateTo` — the page is bookmarkable and survives reload.
- **`useAsyncData` watches `route.query`.** That single watch source is
  the whole refetch trigger — filters, tab and page changes all funnel
  through the URL first, so there is exactly one fetch path.
- **The table keeps its selection/paging context.** `useBbTableContext`
  still owns `page`/`perPage`/`selected`/`totalItems` by id — only the _items_
  become a resolved array (`:items` + `:loading`) instead of an items
  function, since the page now owns the fetch.
- **Clicking the name of a thing peeks it.** Invoice number → invoice peek
  (fresh stack); customer name — in a row or inside a peek — → customer
  peek **stacked** with a back arrow. Peeks are workbenches: status
  control, properties, line items, activity, payments.
- **One Filters menu, one chip per applied facet.** A single `BbDropdown`
  (`BbDropdown.md` § Nested submenus + § Selectable groups) nests category →
  selectable/searchable group (Status, Customer); one chip per APPLIED facet
  — never one per value — renders below it, each a small `BbDropdown` scoped
  to that same group via an external `activator` ref, reading its label from
  `useBbDropdownContext` so it never re-fetches what the menu already
  resolved. **Never** `BbSelectPopover` + an imperative `ref.open()`: it
  exposes nothing to call, and its floating mode closes an
  `sr-only`/off-screen activator the instant it opens. Due date is a
  free-form range, not a discrete facet, so it stays its own compact
  `BbDatePickerInput` pill with a clear-all that renders only while something
  is active.
- **Buttons are `md` by default** (28px, flush beside `compact` inputs);
  `sm` only in the table rows, the peeks' headers and the bottom bar.
  Internal navigation (`New invoice`, row `Edit`, peek `Open…` links) uses
  `to`, Nuxt's Vue Router prop, instead of a raw `href`.

## Page anatomy

```
InvoicesWorkspace/
	Index.vue               ← assembly: PageShell slots, table, tabs, pagination
	context.ts               ← coopting page context (shell + table + URL filters + actions)
	FilterRail.vue           ← one Filters menu + one chip per applied facet
	FilterChip.vue           ← applied-facet chip — itself a dropdown onto the same filter
	StatusCell.vue           ← one-click status change (badge → BbSelectPopover)
	RowActions.vue           ← per-row "…" dropdown
	SelectionBar.vue         ← bulk actions in the floating bottom panel
	InvoicePeek.vue          ← sidebar workbench, stack level 1
	CustomerPeek.vue         ← stacked peek, back arrow via the shell
	RecordPaymentDialog.vue  ← page-level dialog, driven by the context
```

Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
(left nav + fat footer), [Page Shell](../../guides/page-shell.md),
[Floating Bottom Panel](../../guides/floating-bottom-panel.md).

## Action inventory

| #   | Action                   | Trigger                          | Mechanism                                                                                      |
| --- | ------------------------ | -------------------------------- | ---------------------------------------------------------------------------------------------- |
| 1   | New invoice              | topbar, the page's one `primary` | navigation (`to="/invoices/create"`)                                                           |
| 2   | Page search              | topbar right                     | `filters.search` → URL → `useAsyncData` refetch                                                |
| 3   | Filter status / customer | Filters menu + filter chips      | `BbDropdown` nested facets; chip = small scoped `BbDropdown` on the same group                 |
| 3b  | Filter due date          | date-range pill                  | `BbDatePickerInput` range — not a Filters-menu facet                                           |
| 4   | Clear a filter           | chip clear button / date pill    | badge `@click:clear` (status/customer) or input `clearable` (due) — one at a time, no bulk CTA |
| 5   | Switch tab               | href tabs with counts            | URL + `useAsyncData` refetch                                                                   |
| 6   | Peek invoice             | invoice number cell / peek lists | `peekInvoice(id)` → shell stack                                                                |
| 7   | Peek customer (stacked)  | customer cell / inside peeks     | `stackCustomer(id)` → back arrow                                                               |
| 8   | Change status inline     | status badge in row & peek       | one-click `BbSelectPopover`                                                                    |
| 9   | Record payment           | row `…`, peek button             | `BbDialog` via `ctx.dialogs`                                                                   |
| 10  | Edit / duplicate         | row `…` dropdown                 | navigation (`to`) / context action                                                             |
| 11  | Archive / delete         | row `…`, bulk bar                | destructive behind `useConfirm`                                                                |
| 12  | Bulk mark paid / remind  | floating bottom panel            | context actions on `table.selected`                                                            |
| 13  | Select rows / select all | table checkboxes                 | table context                                                                                  |
| 14  | Open full invoice        | peek footer                      | navigation (`to="/invoices/:id"`)                                                              |
| 15  | Back / close peek        | shell chrome                     | shell stack pop / close                                                                        |

## The code

### context.ts

```ts
// InvoicesWorkspace/context.ts
import {
	computed,
	inject,
	provide,
	reactive,
	ref,
	watch,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import {
	useBbTableContext,
	useConfirm,
	useToast,
	type BbTableContext,
} from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import { watchDebounced } from '@vueuse/core';
import type { Invoice, InvoiceStatus, PaymentDraft } from '@/types';

/**
 * What the stacked sidebar can show — a discriminated union of EVERY related
 * type the rows and the peeks expose, so one shell serves the whole consult.
 * `label` rides along because `#sidebar-title` has to name the top of the
 * stack before that record's own fetch has resolved.
 */
export type PeekItem =
	| { type: 'invoice'; id: number; label: string }
	| { type: 'customer'; id: number; label: string };

export type WorkspaceTab = 'all' | 'outstanding' | 'paid' | 'archived';

export interface InvoiceFilters {
	search: string;
	status: InvoiceStatus[];
	customerId: number | null;
	/**
	 * `[start, end]` ISO strings, or `[]` when unset. Range mode requires an
	 * array modelValue -- binding `null` throws, so the empty filter is `[]`.
	 */
	dueBetween: string[];
}

type InvoiceListResponse = {
	data: Invoice[];
	total: number;
	tabCounts: Record<WorkspaceTab, number>;
};

export interface InvoicesWorkspaceContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	table: BbTableContext;
	// -- Page-owned state ------------------------------------------------------
	filters: InvoiceFilters;
	hasActiveFilters: ComputedRef<boolean>;
	tab: Ref<WorkspaceTab>;
	tabCounts: ComputedRef<Record<WorkspaceTab, number>>;
	dialogs: { recordPayment: Ref<Invoice | null> };
	// -- Data (server-rendered, URL-driven) -------------------------------------
	invoices: ComputedRef<Invoice[]>;
	invoicesPending: Ref<boolean>;
	// -- Peek grammar ----------------------------------------------------------
	peekInvoice: (id: number) => void;
	stackInvoice: (id: number) => void;
	stackCustomer: (id: number) => void;
	// -- Actions (complete: API + refresh + toast) ------------------------------
	clearFilters: () => void;
	updateStatus: (invoice: Invoice, status: InvoiceStatus) => Promise<void>;
	duplicateInvoice: (invoice: Invoice) => Promise<void>;
	recordPayment: (invoice: Invoice, draft: PaymentDraft) => Promise<void>;
	archiveInvoice: (invoice: Invoice) => Promise<void>;
	deleteInvoice: (invoice: Invoice) => Promise<void>;
	bulkMarkPaid: () => Promise<void>;
	bulkRemind: () => Promise<void>;
	bulkArchive: () => Promise<void>;
}

const key: InjectionKey<InvoicesWorkspaceContext> =
	Symbol('invoices-workspace');

/** Comma-joined query value → string[] (or null when absent). */
const toArray = (value: unknown): string[] | null => {
	if (value == null || value === '') return null;
	return Array.isArray(value) ? value.map(String) : String(value).split(',');
};

export function provideInvoicesWorkspace(): InvoicesWorkspaceContext {
	const { toast } = useToast();
	const { confirm } = useConfirm();
	const route = useRoute();

	// -- Coopt the specific contexts: once, here, for the whole page. ----------
	const shell = usePageShellContext<PeekItem>();
	const table = useBbTableContext('invoices-table', { perPage: 25 });

	// -- Filters + tab: seeded from the URL, the single source of truth. -------
	const filters = reactive<InvoiceFilters>({
		search: (route.query.search as string) ?? '',
		status: (toArray(route.query.status) ?? []) as InvoiceStatus[],
		customerId: route.query.customerId ? Number(route.query.customerId) : null,
		dueBetween: toArray(route.query.dueBetween) ?? [],
	});
	const tab = ref<WorkspaceTab>((route.query.tab as WorkspaceTab) ?? 'all');

	const hasActiveFilters = computed(
		() =>
			filters.search !== '' ||
			filters.status.length > 0 ||
			filters.customerId !== null ||
			filters.dueBetween.length > 0
	);

	const clearFilters = () => {
		filters.search = '';
		filters.status = [];
		filters.customerId = null;
		filters.dueBetween = [];
	};

	// Every filter/tab change mirrors into the query string; `useAsyncData`
	// below watches `route.query`, so this is the whole refetch trigger.
	const syncQuery = () =>
		navigateTo({
			query: {
				search: filters.search || undefined,
				status: filters.status.length ? filters.status.join(',') : undefined,
				customerId: filters.customerId ?? undefined,
				dueBetween: filters.dueBetween.length
					? filters.dueBetween.join(',')
					: undefined,
				tab: tab.value,
			},
		});
	watchDebounced(filters, syncQuery, { deep: true, debounce: 300 });
	watch(tab, () => {
		table.page.value = 1;
		syncQuery();
	});

	// -- Data ---------------------------------------------------------------------
	const { data, pending, refresh } = useAsyncData<InvoiceListResponse>(
		'invoices',
		() =>
			$fetch<InvoiceListResponse>('/api/invoices', {
				query: {
					search: filters.search || undefined,
					status: filters.status,
					customerId: filters.customerId ?? undefined,
					dueBetween: filters.dueBetween.length
						? filters.dueBetween
						: undefined,
					tab: tab.value,
					page: table.page.value,
					perPage: table.perPage.value,
				},
			}),
		{ watch: [() => route.query, table.page] }
	);
	const invoices = computed(() => data.value?.data ?? []);
	const invoicesPending = pending;
	const tabCounts = computed(
		() =>
			data.value?.tabCounts ?? {
				all: 0,
				outstanding: 0,
				paid: 0,
				archived: 0,
			}
	);
	watch(
		data,
		(response) => {
			if (response) table.totalItems.value = response.total;
		},
		{ immediate: true }
	);

	const dialogs = { recordPayment: ref<Invoice | null>(null) };

	// -- Peek grammar ----------------------------------------------------------------
	// peekX opens a fresh stack (from the list); stackX drills down (from a peek).
	// `peek` opens a fresh top-level peek (a row click); `stackItem` drills from
	// the open one, keeping the back arrow. Named intents beat `push(item, true)`,
	// whose boolean silently resets a stack you meant to drill into.
	const peekInvoice = (id: number, label: string) =>
		shell.peek({ type: 'invoice', id, label });
	const stackInvoice = (id: number, label: string) =>
		shell.stackItem({ type: 'invoice', id, label });
	const stackCustomer = (id: number, label: string) =>
		shell.stackItem({ type: 'customer', id, label });

	// -- Actions --------------------------------------------------------------------
	const updateStatus = async (invoice: Invoice, status: InvoiceStatus) => {
		await $fetch(`/api/invoices/${invoice.id}`, {
			method: 'PATCH',
			body: { status },
		});
		await refresh();
		toast({
			title: `${invoice.number} moved to ${status}.`,
			variant: 'success',
		});
	};

	const duplicateInvoice = async (invoice: Invoice) => {
		const copy = await $fetch<Invoice>(
			`/api/invoices/${invoice.id}/duplicate`,
			{
				method: 'POST',
			}
		);
		await refresh();
		toast({ title: `Duplicated as ${copy.number}.`, variant: 'success' });
	};

	const recordPayment = async (invoice: Invoice, draft: PaymentDraft) => {
		await $fetch(`/api/invoices/${invoice.id}/payments`, {
			method: 'POST',
			body: draft,
		});
		dialogs.recordPayment.value = null;
		await refresh();
		toast({
			title: `Payment recorded on ${invoice.number}.`,
			variant: 'success',
		});
	};

	const archiveInvoice = async (invoice: Invoice) => {
		await $fetch(`/api/invoices/${invoice.id}/archive`, { method: 'PATCH' });
		await refresh();
		toast({ title: `${invoice.number} archived.`, variant: 'success' });
	};

	const deleteInvoice = async (invoice: Invoice) => {
		const ok = await confirm({
			variant: 'destructive',
			title: 'Delete invoice',
			text: `Delete ${invoice.number}? This cannot be undone.`,
			yes: 'Delete',
			no: 'Cancel',
		});
		if (!ok) return;
		await $fetch(`/api/invoices/${invoice.id}`, { method: 'DELETE' });
		await refresh();
		toast({ title: `${invoice.number} deleted.`, variant: 'success' });
	};

	// Bulk actions read and clear the coopted table context themselves.
	const bulkIds = (): number[] => table.selected.value;
	const clearSelection = () => {
		table.selected.value = [];
	};

	const bulkMarkPaid = async () => {
		const ids = bulkIds();
		await $fetch('/api/invoices/bulk/mark-paid', {
			method: 'PATCH',
			body: { ids },
		});
		clearSelection();
		await refresh();
		toast({
			title: `${ids.length} invoices marked as paid.`,
			variant: 'success',
		});
	};

	const bulkRemind = async () => {
		const ids = bulkIds();
		await $fetch('/api/invoices/bulk/remind', {
			method: 'POST',
			body: { ids },
		});
		clearSelection();
		toast({
			title: `Reminder sent for ${ids.length} invoices.`,
			variant: 'success',
		});
	};

	const bulkArchive = async () => {
		const ids = bulkIds();
		const ok = await confirm({
			variant: 'destructive',
			title: 'Archive invoices',
			text: `Archive ${ids.length} invoices? They move out of every tab except Archived.`,
			yes: 'Archive',
			no: 'Cancel',
		});
		if (!ok) return;
		await $fetch('/api/invoices/bulk/archive', {
			method: 'PATCH',
			body: { ids },
		});
		clearSelection();
		await refresh();
		toast({ title: `${ids.length} invoices archived.`, variant: 'success' });
	};

	const ctx: InvoicesWorkspaceContext = {
		shell,
		table,
		filters,
		hasActiveFilters,
		tab,
		tabCounts,
		dialogs,
		invoices,
		invoicesPending,
		peekInvoice,
		stackInvoice,
		stackCustomer,
		clearFilters,
		updateStatus,
		duplicateInvoice,
		recordPayment,
		archiveInvoice,
		deleteInvoice,
		bulkMarkPaid,
		bulkRemind,
		bulkArchive,
	};
	provide(key, ctx);
	return ctx;
}

export function useInvoicesWorkspace(): InvoicesWorkspaceContext {
	const ctx = inject(key);
	if (!ctx)
		throw new Error('useInvoicesWorkspace() called outside InvoicesWorkspace');
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- InvoicesWorkspace/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left, page search + primary action right. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs
					class="min-w-0 flex-auto"
					:items="[
						{ key: 'dashboard', text: 'Dashboard', to: '/dashboard' },
						{ key: 'billing', text: 'Billing', to: '/billing' },
						{ key: 'invoices', text: 'Invoices' },
					]"
				/>
				<div class="flex shrink-0 items-center gap-2">
					<BbTextInput
						v-model="ctx.filters.search"
						autocomplete="off"
						hide-label
						label="Search invoices"
						clearable
						compact
						placeholder="Search number or customer…"
						prepend:icon="lucide:search"
					/>
					<BbButton
						prepend:icon="lucide:plus"
						to="/invoices/create"
						variant="primary"
					>
						New invoice
					</BbButton>
				</div>
			</div>
		</template>

		<div class="flex flex-col gap-3 p-4">
			<FilterRail />

			<!-- Tabs as URL filters: href updates the query, the key feeds the
			     fetch. Counts come from the server on every fetch. -->
			<BbTabs
				v-model="ctx.tab.value"
				compact
				:items="[
					{
						key: 'all',
						label: `All · ${ctx.tabCounts.value.all}`,
						href: '?tab=all',
					},
					{
						key: 'outstanding',
						label: `Outstanding · ${ctx.tabCounts.value.outstanding}`,
						href: '?tab=outstanding',
					},
					{
						key: 'paid',
						label: `Paid · ${ctx.tabCounts.value.paid}`,
						href: '?tab=paid',
					},
					{
						key: 'archived',
						label: `Archived · ${ctx.tabCounts.value.archived}`,
						href: '?tab=archived',
					},
				]"
			/>

			<BbTable
				id="invoices-table"
				actions
				caption="Invoices"
				:columns="columns"
				compact
				item-value="id"
				:items="ctx.invoices.value"
				legend="Select invoices"
				:loading="ctx.invoicesPending.value"
				loading-text="Loading invoices…"
				:row-class="rowClass"
				selectable
			>
				<!-- Clicking the NAME of a thing peeks it. `.plain-link`
				     (design-language.md § Guide helper) is the project-owned
				     inline-link class, not a BbButton variant: `link` keeps
				     button chrome and never flows/truncates like inline text
				     at cell width. -->
				<template #number="{ item, content }">
					<BbBaseButton
						class="plain-link"
						@click="() => ctx.peekInvoice(item.id, item.number)"
					>
						{{ content }}
					</BbBaseButton>
				</template>

				<template #customer_name="{ item, content }">
					<!-- A related name is an inline link, not a button: `BbButton`
					     (any variant) is padded and breaks the row's line-height. -->
					<BbBaseButton
						class="plain-link"
						@click="
							() => ctx.stackCustomer(item.customer.id, item.customer.name)
						"
					>
						{{ content }}
					</BbBaseButton>
				</template>

				<template #status="{ item }">
					<StatusCell :invoice="item" />
				</template>

				<template #actions="{ item }">
					<RowActions :invoice="item" />
				</template>

				<template #no-data>
					<div class="flex flex-col items-center gap-2 p-6 text-center">
						<p class="text-sm text-[color:var(--bb-text-muted)]">
							No invoices match
							{{
								ctx.hasActiveFilters.value ? 'the current filters' : 'this tab'
							}}.
						</p>
						<BbButton
							v-if="ctx.hasActiveFilters.value"
							variant="ghost"
							@click="ctx.clearFilters"
						>
							Clear filters
						</BbButton>
					</div>
				</template>
			</BbTable>

			<!-- Joins the table context by id: no page/totalPages wiring at all. -->
			<BbPagination table-id="invoices-table" />
		</div>

		<SelectionBar />

		<!-- The peek names itself: without `#sidebar-title` the shell opens with
		     back/close flanking empty space, and the entity name ends up as a
		     second title inside the body. It follows the TOP of the stack, so a
		     drill-down renames the chrome. -->
		<template #sidebar-title>{{ ctx.shell.current.value?.label }}</template>

		<!-- Stacked peek sidebar: the shell owns back/close; we render by type. -->
		<template #sidebar>
			<InvoicePeek
				v-if="ctx.shell.current.value?.type === 'invoice'"
				:invoice-id="ctx.shell.current.value.id"
			/>
			<CustomerPeek
				v-else-if="ctx.shell.current.value?.type === 'customer'"
				:customer-id="ctx.shell.current.value.id"
			/>
		</template>

		<template #dialogs>
			<RecordPaymentDialog />
		</template>
	</PageShell>
</template>

<script setup lang="ts">
import {
	BbBaseButton,
	BbBreadcrumbs,
	BbButton,
	BbPagination,
	BbTable,
	BbTabs,
	BbTextInput,
} from 'bitboss-ui';
import PageShell from '@/components/layout/PageShell.vue';
import { provideInvoicesWorkspace } from './context';
import CustomerPeek from './CustomerPeek.vue';
import FilterRail from './FilterRail.vue';
import InvoicePeek from './InvoicePeek.vue';
import RecordPaymentDialog from './RecordPaymentDialog.vue';
import RowActions from './RowActions.vue';
import SelectionBar from './SelectionBar.vue';
import StatusCell from './StatusCell.vue';
import type { Invoice } from '@/types';

const ctx = provideInvoicesWorkspace();

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
const shortDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
	});

const columns = [
	{ key: 'number', label: 'Invoice' },
	{ key: 'customer.name', label: 'Customer' },
	{
		key: 'amount',
		label: 'Amount',
		formatter: (value: number) => currency.format(value),
	},
	{ key: 'status', label: 'Status' },
	{ key: 'dueDate', label: 'Due', formatter: shortDate },
	{ key: 'issuedAt', label: 'Issued', formatter: shortDate },
];

// Overdue rows get a tinted background — public row-class API, no internals.
const rowClass = (item: Invoice) =>
	item.status === 'overdue' ? 'bg-red-50 dark:bg-red-950/20' : undefined;
</script>
```

### FilterRail.vue

```vue
<!-- InvoicesWorkspace/FilterRail.vue -->
<template>
	<div class="flex flex-wrap items-center gap-2">
		<!-- One Filters menu: nested category → selectable/searchable group.
		     Never one BbSelectPopover pill per facet — that component has no
		     `defineExpose`, so a chip can't `ref.open()` it, and its floating
		     mode auto-closes an off-screen/`sr-only` activator on open. -->
		<BbDropdown id="invoice-filters" :items="menu" :width="220">
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filters"
					prepend:icon="lucide:list-filter"
					size="sm"
					variant="outline"
				>
					Filters
				</BbButton>
			</template>
			<BbDropdownGroup id="status" v-model="ctx.filters.status" />
			<BbDropdownGroup id="customer" v-model="ctx.filters.customerId" />
		</BbDropdown>

		<!-- One chip per APPLIED facet — never one per value. See
		     FilterChip.vue: each chip is itself a small dropdown scoped to the
		     same group, reusing the exact descriptor declared below. -->
		<FilterChip
			v-if="ctx.filters.status.length"
			:group="statusGroup"
			group-key="status"
			label="Status"
			:model-value="ctx.filters.status"
			@update:model-value="
				(value) => (ctx.filters.status = value as InvoiceStatus[])
			"
		/>
		<FilterChip
			v-if="ctx.filters.customerId != null"
			:group="customerGroup"
			group-key="customer"
			label="Customer"
			:model-value="ctx.filters.customerId"
			@update:model-value="
				(value) => (ctx.filters.customerId = value as number | null)
			"
		/>

		<!-- Due date is a free-form range, not a discrete facet — its own
		     compact pill outside the Filters menu, no chip. A compact input
		     is 28px — flush with the sm Filters button's row. -->
		<BbDatePickerInput
			v-model="ctx.filters.dueBetween"
			hide-label
			label="Due date range"
			clearable
			compact
			placeholder="Due between…"
			range
		/>

		<!-- Clear-all is the LAST CHIP, not a ghost button floated to the far
		     end by `ml-auto`: it acts on the chips, so it belongs in their row
		     and at their scale. Keep the ghost "Clear filters" for the empty
		     state (`#no-data`), where there are no chips to sit beside. -->
		<BbBadge
			v-if="ctx.hasActiveFilters.value"
			clearable
			:clearable-label="`Clear all filters`"
			size="xl"
			variant="outline"
			@click:clear="ctx.clearFilters"
		>
			Clear all
		</BbBadge>
	</div>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import {
	BbBadge,
	BbButton,
	BbDatePickerInput,
	BbDropdown,
	BbDropdownGroup,
} from 'bitboss-ui';
import type { BbDropdownItem } from 'bitboss-ui';
import { useInvoicesWorkspace } from './context';
import FilterChip from './FilterChip.vue';
import type { Customer, InvoiceStatus } from '@/types';

const ctx = useInvoicesWorkspace();

// Query-aware pipeline getter: called with the typed query because the group
// below sets `searchable: true` (same `(query, prefill, modelValue)` shape a
// BbSelect provider uses).
const searchCustomers = (query: string): Promise<Customer[]> =>
	$fetch<Customer[]>('/api/customers', { query: { search: query } });

// Static enum facet: item text resolves synchronously, so its chip reads
// `useBbDropdownContext` (in FilterChip.vue) with zero extra fetch.
const statusGroup: BbDropdownItem = {
	key: 'status',
	label: 'Status',
	hideLabel: true,
	selectable: true,
	multiple: true,
	items: [
		{ key: 'draft', text: 'Draft' },
		{ key: 'pending', text: 'Pending' },
		{ key: 'paid', text: 'Paid' },
		{ key: 'overdue', text: 'Overdue' },
	],
};

// Pipeline facet: `prefill: true` resolves a picked customer's name eagerly,
// so a chip never sits on a bare id while this group's own submenu (inside
// the Filters menu) has never been opened. The eager flag belongs HERE, on
// the menu's copy only — the chip derives its own copy with
// `prefill: 'interaction'` (see FilterChip.vue), because a second dropdown
// redeclaring `prefill: true` would fetch every seeded facet twice on page
// load for nothing.
const customerGroup: BbDropdownItem = {
	key: 'customer',
	label: 'Customer',
	hideLabel: true,
	selectable: true,
	searchable: true,
	prefill: true,
	itemText: 'name',
	itemValue: 'id',
	items: searchCustomers,
};

// Top-level items are submenu openers; each nests exactly one selectable
// group ("nested category › searchable options" — BbDropdown.md § Nested
// submenus). `hideLabel` on the group skips a redundant inner heading since
// the category row already names the facet.
const menu = computed<BbDropdownItem[]>(() => [
	{
		key: 'status-category',
		text: 'Status',
		'prepend:icon': 'lucide:circle-dot',
		items: [statusGroup],
	},
	{
		key: 'customer-category',
		text: 'Customer',
		'prepend:icon': 'lucide:building-2',
		items: [customerGroup],
	},
]);
</script>
```

### FilterChip.vue

```vue
<!-- InvoicesWorkspace/FilterChip.vue -->
<template>
	<BbBadge
		clearable
		:clearable-label="`Remove ${label} filter`"
		size="xl"
		variant="secondary"
		@click:clear="onClear"
	>
		<BbBadgeButton ref="chipRef">{{ chipText }}</BbBadgeButton>
	</BbBadge>
	<!-- External `activator` (a template ref) — NEVER the `#activator` slot: a
	     component sitting between `BbBadge` and `BbBadgeButton` breaks the
	     badge's direct-child vnode scan (the companion must be a literal
	     child). This IS "the chip is itself a dropdown onto the same filter
	     group": `chipGroup` is derived from the exact descriptor FilterRail
	     declared (spread, one override — never redeclared), so this scoped
	     picker and the Filters menu's own submenu can never drift apart. -->
	<BbDropdown :activator="chipRef" :items="[chipGroup]" :width="220">
		<BbDropdownGroup
			:id="groupKey"
			:model-value="modelValue"
			@update:model-value="emit('update:modelValue', $event)"
		/>
	</BbDropdown>
</template>

<script setup lang="ts">
import { computed, useTemplateRef } from 'vue';
import {
	BbBadge,
	BbBadgeButton,
	BbDropdown,
	BbDropdownGroup,
	useBbDropdownContext,
} from 'bitboss-ui';
import type { BbDropdownItem } from 'bitboss-ui';

const props = defineProps<{
	/** Matches the group's `key` in the Filters menu, and its key in
	 * `useBbDropdownContext('invoice-filters').groups`. */
	groupKey: string;
	/** Static fallback/prefix text — the group itself sets `hideLabel`. */
	label: string;
	/** The SAME group descriptor passed to the Filters menu — not redeclared. */
	group: BbDropdownItem;
	modelValue: unknown;
}>();
const emit = defineEmits<{ 'update:modelValue': [value: unknown] }>();

const chipRef = useTemplateRef('chipRef');

// The chip's own copy of the shared descriptor, one override: `prefill:
// 'interaction'`. BbDropdown mounts a pipeline resolver for every group it
// declares at its own root, independent of the panel ever opening — so if
// this second dropdown repeated the menu's `prefill: true` verbatim, each
// seeded pipeline facet would be fetched TWICE on page load, and the chip's
// copy of the result would feed nothing (the label below comes from the
// menu's resolution via context). `'interaction'` defers this copy's fetch
// to the moment the chip's dropdown is actually opened. For static array
// facets the override is inert — arrays resolve synchronously either way.
const chipGroup = computed<BbDropdownItem>(() => ({
	...props.group,
	prefill: 'interaction',
}));

// Reads the Filters menu's already-resolved selection — no twin fetch. A
// pipeline group needs `prefill: true` (set on the MENU's copy of `group` by
// FilterRail) so this never sits on a bare id/value while the menu's own
// submenu is unopened.
const dropdownFilters = useBbDropdownContext('invoice-filters');
const chipText = computed(() => {
	const options =
		dropdownFilters.groups.value[props.groupKey]?.selectedOptions ?? [];
	if (!options.length) return props.label;
	return `${props.label}: ${options
		.map((option) => option.text ?? String(option.value))
		.join(', ')}`;
});

const onClear = () =>
	emit('update:modelValue', Array.isArray(props.modelValue) ? [] : null);
</script>
```

### StatusCell.vue

```vue
<!-- InvoicesWorkspace/StatusCell.vue -->
<template>
	<BbSelectPopover
		:items="['draft', 'pending', 'paid', 'overdue']"
		:model-value="invoice.status"
		width="180"
		@update:model-value="(status) => pick(status as InvoiceStatus)"
	>
		<template #activator="{ props: activatorProps }">
			<!-- The badge IS the trigger: BbBadgeButton turns the badge's own
			body into the button, so the pill is the hit target and draws its
			own focus ring — no wrapper element, no chrome class. The internal
			trailing chevron says "clickable"; while the save runs the badge's
			`loading` swaps the spinner into the chevron's place (§6.1
			niceties). -->
			<BbBadge
				append:icon="lucide:chevron-down"
				:loading="saving"
				variant="outline"
			>
				<BbBadgeButton
					:aria-label="`Change status for invoice ${invoice.number}`"
					v-bind="activatorProps"
					>{{ invoice.status }}</BbBadgeButton
				>
			</BbBadge>
		</template>
	</BbSelectPopover>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
import { useInvoicesWorkspace } from './context';
import type { Invoice, InvoiceStatus } from '@/types';

const props = defineProps<{ invoice: Invoice }>();

const ctx = useInvoicesWorkspace();

// In-flight flag for the save feedback — rung-1 local state, not context.
const saving = ref(false);
const pick = async (status: InvoiceStatus) => {
	saving.value = true;
	try {
		await ctx.updateStatus(props.invoice, status);
	} finally {
		saving.value = false;
	}
};
</script>
```

### RowActions.vue

```vue
<!-- InvoicesWorkspace/RowActions.vue -->
<template>
	<BbDropdown
		:items="[
			{
				key: 'edit',
				text: 'Edit',
				'prepend:icon': 'lucide:pencil',
				to: `/invoices/${invoice.id}/edit`,
			},
			{
				key: 'duplicate',
				text: 'Duplicate',
				'prepend:icon': 'lucide:copy',
				onClick: () => ctx.duplicateInvoice(invoice),
			},
			{
				key: 'payment',
				text: 'Record payment',
				'prepend:icon': 'lucide:banknote',
				onClick: () => (ctx.dialogs.recordPayment.value = invoice),
			},
			{
				key: 'archive',
				text: 'Archive',
				'prepend:icon': 'lucide:archive',
				onClick: () => ctx.archiveInvoice(invoice),
			},
			{
				key: 'delete',
				text: 'Delete',
				'prepend:icon': 'lucide:trash-2',
				variant: 'destructive',
				onClick: () => ctx.deleteInvoice(invoice),
			},
		]"
	>
		<template #activator="{ props }">
			<BbButton v-bind="props" icon="lucide:ellipsis" size="sm" variant="ghost">
				Invoice actions
			</BbButton>
		</template>
	</BbDropdown>
</template>

<script setup lang="ts">
import { BbButton, BbDropdown } from 'bitboss-ui';
import { useInvoicesWorkspace } from './context';
import type { Invoice } from '@/types';

defineProps<{ invoice: Invoice }>();

const ctx = useInvoicesWorkspace();
</script>
```

### SelectionBar.vue

```vue
<!-- InvoicesWorkspace/SelectionBar.vue -->
<template>
	<FloatingBottomPanel :open="selectedCount > 0">
		<span class="px-2 text-sm">{{ selectedCount }} selected</span>
		<BbButton
			prepend:icon="lucide:check"
			size="sm"
			variant="ghost"
			@click="ctx.bulkMarkPaid"
		>
			Mark as paid
		</BbButton>
		<BbButton
			prepend:icon="lucide:send"
			size="sm"
			variant="ghost"
			@click="ctx.bulkRemind"
		>
			Send reminder
		</BbButton>
		<div class="floating-bottom-panel__right flex items-center gap-1">
			<BbButton size="sm" variant="destructive" @click="ctx.bulkArchive"
				>Archive</BbButton
			>
			<BbButton
				aria-label="Clear selection"
				icon="lucide:x"
				size="sm"
				variant="ghost"
				@click="clearSelection"
			/>
		</div>
	</FloatingBottomPanel>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton } from 'bitboss-ui';
import FloatingBottomPanel from '@/components/layout/FloatingBottomPanel.vue';
import { useInvoicesWorkspace } from './context';

const ctx = useInvoicesWorkspace();

const selectedCount = computed(() => ctx.table.selected.value?.length ?? 0);
const clearSelection = () => {
	ctx.table.selected.value = [];
};
</script>
```

### InvoicePeek.vue

```vue
<!-- InvoicesWorkspace/InvoicePeek.vue -->
<template>
	<div v-if="invoice" class="flex flex-col gap-4 text-sm">
		<!-- Header: identity + one-click status + amount. -->
		<header class="flex flex-col gap-1.5">
			<div class="flex items-center justify-between gap-2">
				<h2 class="text-base font-semibold">{{ invoice.number }}</h2>
				<StatusCell :invoice="invoice" />
			</div>
			<p class="text-xl font-semibold">{{ currency.format(invoice.amount) }}</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Issued {{ longDate(invoice.issuedAt) }} · due
				{{ longDate(invoice.dueDate) }}
			</p>
		</header>

		<!-- Properties: customer name drills DOWN — stacked peek, back arrow.
		     `.plain-link` (design-language.md § Guide helper), not a BbButton
		     variant — a property-grid value is inline text, not a button. -->
		<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
			<dt class="text-[color:var(--bb-text-muted)]">Customer</dt>
			<dd>
				<BbBaseButton
					class="plain-link"
					@click="
						() =>
							ctx.stackCustomer(invoice!.customer.id, invoice!.customer.name)
					"
				>
					{{ invoice.customer.name }}
				</BbBaseButton>
			</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Project</dt>
			<dd>{{ invoice.project.name }}</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Payment terms</dt>
			<dd>{{ invoice.paymentTerms }}</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Reference</dt>
			<dd>{{ invoice.reference }}</dd>
		</dl>

		<!-- Line items: a real mini-table, not a summary sentence. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Line items
			</h3>
			<BbTable
				caption="Invoice line items"
				:columns="[
					{ key: 'description', label: 'Description' },
					{ key: 'quantity', label: 'Qty' },
					{
						key: 'total',
						label: 'Total',
						formatter: (value: number) => currency.format(value),
					},
				]"
				compact
				item-value="id"
				:items="invoice.lineItems"
			/>
		</section>

		<!-- Payments so far. -->
		<section v-if="invoice.payments.length" class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Payments
			</h3>
			<ul class="flex flex-col gap-1">
				<li
					v-for="payment in invoice.payments"
					:key="payment.id"
					class="flex items-center justify-between gap-2"
				>
					<span
						>{{ currency.format(payment.amount) }} · {{ payment.method }}</span
					>
					<span class="text-xs text-[color:var(--bb-text-muted)]">{{
						longDate(payment.paidAt)
					}}</span>
				</li>
			</ul>
		</section>

		<!-- Activity feed. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Activity
			</h3>
			<ul class="flex flex-col gap-2">
				<li
					v-for="entry in invoice.activity"
					:key="entry.id"
					class="flex gap-2"
				>
					<BbIcon
						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
						:icon="entry.icon"
						size="14"
					/>
					<div class="flex flex-col">
						<span>{{ entry.text }}</span>
						<span class="text-xs text-[color:var(--bb-text-muted)]"
							>{{ entry.actor }} · {{ longDate(entry.at) }}</span
						>
					</div>
				</li>
			</ul>
		</section>

		<!-- Peek is a workbench: act here, or leave for the full page. -->
		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				prepend:icon="lucide:banknote"
				size="sm"
				variant="secondary"
				@click="() => (ctx.dialogs.recordPayment.value = invoice)"
			>
				Record payment
			</BbButton>
			<BbButton
				append:icon="lucide:arrow-up-right"
				size="sm"
				:to="`/invoices/${invoice.id}`"
				variant="ghost"
			>
				Open full page
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { ref, watchEffect } from 'vue';
import { BbBaseButton, BbButton, BbIcon, BbSpinner, BbTable } from 'bitboss-ui';
import StatusCell from './StatusCell.vue';
import { useInvoicesWorkspace } from './context';
import type { InvoiceDetail } from '@/types';

const props = defineProps<{ invoiceId: number }>();

const ctx = useInvoicesWorkspace();

// Re-fetches whenever the stack shows a different invoice; the surrounding
// list's `refresh()` re-renders `ctx.invoices`, but this JSON fetch is its
// own concern so it re-runs whenever the invoice list refreshes too.
const invoice = ref<InvoiceDetail | null>(null);
watchEffect(async () => {
	void ctx.invoices.value;
	invoice.value = await $fetch<InvoiceDetail>(
		`/api/invoices/${props.invoiceId}`
	);
});

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
const longDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
		year: 'numeric',
	});
</script>
```

### CustomerPeek.vue

```vue
<!-- InvoicesWorkspace/CustomerPeek.vue -->
<template>
	<div v-if="customer" class="flex flex-col gap-4 text-sm">
		<header class="flex items-center gap-3">
			<BbAvatar :alt="customer.name" :src="customer.avatarUrl" />
			<div class="flex flex-col">
				<h2 class="text-base font-semibold">{{ customer.name }}</h2>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					{{ customer.email }} · {{ customer.country }}
				</p>
			</div>
		</header>

		<!-- Stat strip. -->
		<div class="grid grid-cols-3 gap-2">
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Total billed</p>
				<p class="font-semibold">{{ currency.format(customer.totalBilled) }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Outstanding</p>
				<p class="font-semibold">{{ currency.format(customer.outstanding) }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Invoices</p>
				<p class="font-semibold">{{ customer.invoiceCount }}</p>
			</div>
		</div>

		<!-- Recent invoices: names drill down again — the stack keeps growing.
		     `.plain-link` (design-language.md § Guide helper), not a BbButton
		     variant — same identity-cell rule as the invoices table. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Recent invoices
			</h3>
			<ul class="flex flex-col">
				<li
					v-for="recent in customer.recentInvoices"
					:key="recent.id"
					class="flex items-center justify-between gap-2 border-b py-1.5 last:border-b-0"
				>
					<BbBaseButton
						class="plain-link"
						@click="() => ctx.stackInvoice(recent.id, recent.number)"
					>
						{{ recent.number }}
					</BbBaseButton>
					<BbBadge variant="outline">{{ recent.status }}</BbBadge>
					<span class="text-xs text-[color:var(--bb-text-muted)]">{{
						currency.format(recent.amount)
					}}</span>
				</li>
			</ul>
		</section>

		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				append:icon="lucide:arrow-up-right"
				size="sm"
				:to="`/customers/${customer.id}`"
				variant="ghost"
			>
				Open customer
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { ref, watchEffect } from 'vue';
import {
	BbAvatar,
	BbBadge,
	BbBaseButton,
	BbButton,
	BbSpinner,
} from 'bitboss-ui';
import { useInvoicesWorkspace } from './context';
import type { CustomerDetail } from '@/types';

const props = defineProps<{ customerId: number }>();

const ctx = useInvoicesWorkspace();

const customer = ref<CustomerDetail | null>(null);
watchEffect(async () => {
	customer.value = await $fetch<CustomerDetail>(
		`/api/customers/${props.customerId}`
	);
});

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
</script>
```

### RecordPaymentDialog.vue

```vue
<!-- InvoicesWorkspace/RecordPaymentDialog.vue -->
<template>
	<BbDialog
		:model-value="invoice !== null"
		size="sm"
		:title="invoice ? `Record payment — ${invoice.number}` : ''"
		@update:model-value="close"
	>
		<form
			v-if="invoice"
			class="flex flex-col gap-3"
			novalidate
			@submit.prevent="submit"
		>
			<BbNumberInput
				v-model="draft.amount"
				label="Amount"
				label-mode="outside"
				:max-precision="2"
				:min="0"
			>
				<template #prefix>$</template>
			</BbNumberInput>
			<BbDatePickerInput
				v-model="draft.paidAt"
				label="Paid on"
				label-mode="outside"
			/>
			<BbSelect
				v-model="draft.method"
				:items="['bank transfer', 'card', 'check', 'cash']"
				label="Method"
				label-mode="outside"
			/>
			<div class="mt-1 flex justify-end gap-2">
				<BbButton type="button" variant="ghost" @click="close">Cancel</BbButton>
				<BbButton type="submit" variant="secondary">Record payment</BbButton>
			</div>
		</form>
	</BbDialog>
</template>

<script setup lang="ts">
import { computed, reactive, watch } from 'vue';
import {
	BbButton,
	BbDatePickerInput,
	BbDialog,
	BbNumberInput,
	BbSelect,
} from 'bitboss-ui';
import { useInvoicesWorkspace } from './context';
import type { PaymentDraft } from '@/types';

const ctx = useInvoicesWorkspace();

// The dialog's subject lives in the page context — any component on the
// page (row actions, the peek) can open it by assigning the invoice.
const invoice = computed(() => ctx.dialogs.recordPayment.value);
const close = () => {
	ctx.dialogs.recordPayment.value = null;
};

const draft = reactive<PaymentDraft>({
	amount: null,
	paidAt: null,
	method: null,
});
watch(invoice, (next) => {
	// Re-seed per invoice: default to paying the remaining balance today.
	draft.amount = next?.amountDue ?? null;
	draft.paidAt = next ? new Date().toISOString() : null;
	draft.method = null;
});

// Returning the promise lets the submit button track the async work.
const submit = () =>
	invoice.value ? ctx.recordPayment(invoice.value, { ...draft }) : undefined;
</script>
```

## Why it is built this way

- **The context coopts, leaves consume.** `shell` and `table` are joined
  once in `provideInvoicesWorkspace()`; nine components share filters,
  selection, the peek stack and every action through one
  `useInvoicesWorkspace()` call. No component on this page receives a
  callback prop, and only peeks/cells receive data props (the item or id
  they render).
- **The URL is the filter store, `useAsyncData` is the fetch.** Filters and
  tab are seeded from `route.query` once at setup, mirrored back with
  `navigateTo` on every change (debounced for free text), and
  `useAsyncData('invoices', …, { watch: [() => route.query, table.page] })`
  is the single refetch trigger — there is exactly one place data loads.
- **The table context still owns paging and selection.** `useBbTableContext`
  is unchanged from the Vue recipe: it seeds `perPage`, `BbPagination`
  joins by `table-id`, and `SelectionBar` reads `table.selected` — only the
  _items_ move from an items-function to a resolved `:items` array written
  by the page's own fetch.
- **`peekX` vs `stackX` is the whole stack grammar.** Fresh peeks replace,
  drill-downs push; the shell renders the back arrow when depth > 1. The
  grammar lives in the context — a leaf cannot accidentally nuke the
  stack.
- **Tabs carry `href` and live counts**, exactly as in the Vue recipe — the
  client-side pushState they perform keeps `route.query.tab` in sync, which
  is what seeds `tab` on load and what `useAsyncData`'s `route.query` watch
  reacts to.
- **Internal links use `to`, not `href`.** `to` renders a real Vue Router
  link (client-side navigation); a raw `href` would force a full page
  reload. Every same-app link in this recipe — the primary "New invoice"
  action, the row `Edit` item, both peek "Open…" links — uses `to`.
- **Dialogs hang off the context** (`ctx.dialogs.recordPayment` holds the
  subject invoice, not a boolean) so row actions and the peek open the
  same dialog with zero coordination.
- **Sizing:** topbar and rail follow `md`-first (`compact` inputs at 28px
  flush beside the default buttons); `sm` appears exactly where the
  doctrine allows — row actions, pills, peek footers, the bulk bar.
- **One `variant="primary"`** (New invoice). Destructive actions —
  single, bulk, in-peek — all ride `useConfirm`.
- **The status badge tells you it saves.** `StatusCell` carries the §6.1
  niceties: an internal trailing chevron (a clickable status must say so)
  and `:loading` around the awaited context action, so the spinner takes
  the chevron's place while the save runs. The flag is a local `ref` —
  rung 1, not context state. The ownership grammar behind inline edits is
  the [Inline Edit Playbook](../../guides/inline-edit-playbook.md).

## Variations

- **Keyboard triage**: add `keyboard-navigation` to the table and open the
  peek from `v-model:highlighted` — the approvals-inbox recipe is the
  full treatment.
- **Saved views**: persist `filters` + `tab` per user in a store
  (`useSavedViewsStore`) and render a view switcher before the tabs.
- **Inline amount editing**: swap the amount cell for an
  `EditableAmountCell` per the inline-editing pattern. Choosing between
  explicit-commit cells and a fully autosaving grid is the
  [Inline Edit Playbook](../../guides/inline-edit-playbook.md); the
  autosave treatment is the inline-edit-workspace recipe.
- **SSR-populated peeks**: swap the peeks' `$fetch` calls for
  `useAsyncData` keyed by id if the peek content should be part of the
  server-rendered payload rather than a client-side follow-up fetch.

### Tabs are lifecycle; chips are facets

The rail and the tab strip answer two different questions, and twinning them is
the fastest way to make a workspace feel arbitrary:

- **Tabs = one lifecycle segment.** Where the record _is_ in its own flow —
  All / Outstanding / Paid / Archived. Mutually exclusive, always visible,
  carrying the counts.
- **Chips = cross-cutting facets.** Anything that can apply to a record in any
  segment — customer, owner, due date, tag. Additive, and only rendered while
  applied.

Never expose the same dimension both ways: a `status` facet inside the Filters
menu next to a status tab strip lets the user set two conflicting answers to one
question, and neither control shows the other's state. If a dimension deserves
both roles (a lifecycle you also want to combine), pick one and give the other
distinct chrome — never the same values with different affordances.

**Rail anatomy** — one row, one scale:

| Slot                    | What                                                    |
| ----------------------- | ------------------------------------------------------- |
| `.filter-rail`          | the row itself: Filters trigger, chips, free-form pills |
| Filters trigger         | one `BbDropdown` of the _unapplied_ facets              |
| `.filter-rail__applied` | one chip per **applied facet** — never one per value    |
| free-form controls      | ranges (dates, amounts) that are not discrete facets    |
| clear-all               | the last chip in the row, same scale as the others      |

Sizes come from the pairing table in [BbBadge](../../BbBadge.md): the trigger
here is a `sm` button, so every chip in the row is `xl`.

## Conformance — a listing is done when

Peek, highlight and title are one feature; shipping two of the three leaves a
dead affordance behind. Before calling a records screen finished:

- [ ] **`v-model:highlighted` is wired both ways** — closing the peek clears
      the highlight, or the same row cannot reopen it (see the Layout
      Scaffold's sync section).
- [ ] **`#sidebar-title` is filled**, or the peek opens with back/close
      flanking empty space.
- [ ] **`#sidebar` renders every `PeekItem` branch** the union declares.
- [ ] **Related names stack** — `BbBaseButton` + `.plain-link` calling
      `stackItem`, never a padded `BbButton`, and never dead text.
- [ ] **The row highlight follows the root of the stack**, so drilling
      invoice → customer does not un-highlight the row the consult began on.

If a page genuinely has no peek, delete the shell wiring rather than leaving
`v-model:highlighted` painting rows that open nothing.

---

<!-- dist/ai/recipes/nuxt/upload-center.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/nuxt/upload-center.md -->

# Recipe: Upload Center (Nuxt)

The Expensify-grade expense receipts submission page adapted for **Nuxt**:
the same multi-file dropzone feeding an inline-editable table, per-file
upload progress with inline retry, one-click category cells, bulk actions
in the floating bottom panel, and a stacked receipt/merchant peek sidebar —
but filters and the active tab live in the URL, the drafts page loads
through `useAsyncData` watching `route.query`, and the live upload queue
stays exactly what it is: client-only reactive state merged above the
fetched rows. Anatomy, components, the context shape, copy and data are
identical to the Vue recipe; only the data/URL/mutation layer changes.

Sibling recipes: [Vue](../vue/upload-center.md) ·
[Inertia](../inertia/upload-center.md).

## Prerequisites

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell`, `usePageShellContext` and `FloatingBottomPanel` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
- `<BbConfirm />` and `<BbToast />` mounted once in `app.vue` — never in a page.
- [App Layout](../../guides/app-layout.md), [Page Shell](../../guides/page-shell.md)
  and [Floating Bottom Panel](../../guides/floating-bottom-panel.md) copied
  into `src/components/layout/` per their guides — every recipe page assumes
  this chrome exists and renders inside it.
- A `useCategoriesStore()` Pinia store exposing the shared expense-category
  catalog (Travel, Meals & entertainment, Lodging, Rideshare & transit,
  Software & subscriptions, Office supplies, Fuel, Client entertainment).
- Server routes: `GET /api/receipts` (accepts `search`, `categoryIds[]`,
  `merchant`, `spentBetween[]`, `tab`, `page`, `perPage`, returns
  `{ data, total, tabCounts, readyCount }`), `GET /api/merchants/search`,
  plus the mutation routes referenced below (`PATCH /api/receipts/:id`,
  `POST /api/receipts/:id/submit`, `POST /api/receipts/submit-drafts`,
  `DELETE /api/receipts/:id`, `PATCH /api/receipts/bulk/categorize`,
  `POST /api/receipts/bulk/delete`). A dedicated `POST /api/receipts/upload`
  endpoint backs `api.receipts.upload()` — see the upload note below.

## Key ideas

- **One coopting page context.** `provideUploadCenter()` joins the
  page-shell stack and the table context once, coopts the shared category
  catalog from `useCategoriesStore()`, owns the URL-backed filters/tab and
  the **upload queue**, and exposes complete actions. Every leaf calls
  `useUploadCenter()` and nothing else.
- **Filters and tab live in the URL, not in local refs.** They are seeded
  from `route.query` at setup and every change writes back through
  `navigateTo` — the page is bookmarkable and survives reload.
- **`useAsyncData` watches `route.query`.** That single watch source is
  the whole refetch trigger for the _server_ page — filters, tab and page
  changes all funnel through the URL first, so there is exactly one fetch
  path for drafts/submitted/reimbursed rows.
- **The upload queue is untouched by the data-layer swap.** It stays
  client-only reactive state (`uploads`), merged above the fetched server
  rows in a computed (`rows`) passed straight to `BbTable`'s `:items` —
  no `dependencies`, no `refreshKey`; progress ticks mutate the queue rows
  in place and Vue's own reactivity re-renders the one cell reading them.
- **Capture and transfer are two layers.** `BbDropzone` only validates and
  hands over `File[]`; the context runs the uploads (AbortController +
  progress callback per file) and the dropzone leaf immediately drains its
  model into `ctx.enqueueFiles()`. `$fetch` has no upload-progress events,
  so the transfer itself posts `FormData` through a small XHR wrapper in
  `@/api` — the call site (`api.receipts.upload(file, { signal, onProgress })`)
  stays identical to the other platforms.
- **Every draft cell edits in place**, exactly as in the Vue recipe:
  merchant (§6.3), category (§6.1), amount, date — each its own leaf with
  a single `receipt` prop, failed saves revert via `refresh()` and toast
  destructive.
- **Tabs are URL filters.** Drafts / Submitted / Reimbursed carry `href`
  (`?tab=drafts`) and live counts from every fetch; the same table is the
  pane, read-only outside Drafts.
- **Clicking the name of a thing peeks it.** Filename → receipt peek
  (fresh stack); merchant name inside the peek → merchant peek **stacked**
  with a back arrow. Peeks fetch their own JSON and re-run whenever
  `ctx.rows.value` changes (the same signal a server `refresh()` updates).
- **Buttons are `md` by default**; `sm`/`xs` only in the table rows, the
  filter pills, the peek footers and the bottom bar. One
  `variant="primary"`: **Submit all** with its live count. Internal SPA
  navigation (the merchant peek's "All receipts from…" link) uses `to`;
  the file-download links (`Download original`) stay a raw `href` — they
  serve a real file, not a Nuxt page, so they must not be intercepted by
  the router.

## Page anatomy

```
UploadCenter/
	Index.vue              ← assembly: PageShell slots, dropzone, tabs, table, pagination
	context.ts              ← coopting page context (shell + table + categories + URL filters + upload queue + actions)
	ReceiptDropzone.vue    ← multi-file capture, constraint errors mapped to messages
	FilterRail.vue          ← pill filters + clear-all
	ReceiptFileCell.vue     ← file icon + name (peek link) + size, both row kinds
	UploadProgressCell.vue ← per-file BbProgress / failed state with inline retry
	MerchantCell.vue        ← inline text edit, commit on blur/Enter (§6.3)
	CategoryCell.vue        ← one-click badge → BbSelectPopover (§6.1)
	AmountCell.vue           ← inline number edit with $ prefix
	DateCell.vue             ← date picker cell, commit on pick
	RowActions.vue           ← remove-from-queue / per-receipt "…" dropdown
	SelectionBar.vue         ← bulk categorize + bulk remove in the floating bottom panel
	ReceiptPeek.vue          ← sidebar workbench, stack level 1
	MerchantPeek.vue         ← stacked peek, back arrow via the shell
```

Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
(left nav + fat footer), [Page Shell](../../guides/page-shell.md),
[Floating Bottom Panel](../../guides/floating-bottom-panel.md).

## Action inventory

| #   | Action                            | Trigger                            | Mechanism                                             |
| --- | --------------------------------- | ---------------------------------- | ----------------------------------------------------- |
| 1   | Upload receipts                   | dropzone (drag, click, Browse)     | `enqueueFiles()` → per-file upload with progress      |
| 2   | Retry a failed upload             | inline in the progress cell        | `retryUpload(id)` re-issues the request               |
| 3   | Remove an in-flight upload        | row actions (x)                    | `removeUpload(id)` aborts + drops the row             |
| 4   | Page search                       | topbar right                       | `filters.search` → URL → `useAsyncData` refetch       |
| 5   | Filter category / merchant / date | filter rail pills                  | `BbSelectPopover` multiple / query-aware / date range |
| 6   | Clear filters                     | rail right (only when active)      | context `clearFilters()`                              |
| 7   | Switch tab                        | href tabs with counts              | URL + `useAsyncData` refetch                          |
| 8   | Edit merchant inline              | merchant cell                      | commit on blur/Enter, Esc reverts (§6.3)              |
| 9   | Change category one-click         | category badge in row & peek       | `BbSelectPopover` on the badge (§6.1)                 |
| 10  | Edit amount inline                | amount cell ($ prefix)             | commit on blur/Enter, Esc reverts                     |
| 11  | Edit expense date inline          | date cell                          | commit on pick                                        |
| 12  | Submit one receipt                | row `…`, peek footer               | `submitReceipt()` ($fetch + refresh + toast)          |
| 13  | Submit all with count             | topbar, the page's one `primary`   | `submitAll()` — count from every fetch                |
| 14  | Remove a draft                    | row `…`, peek footer               | destructive behind `useConfirm`                       |
| 15  | Bulk categorize                   | floating bottom panel popover      | `bulkCategorize()` on `table.selected`                |
| 16  | Bulk remove                       | floating bottom panel              | destructive behind `useConfirm`, count in message     |
| 17  | Select rows / select all          | table checkboxes (drafts only)     | table context, `selectable` predicate                 |
| 18  | Peek receipt                      | filename cell / merchant peek list | `peekReceipt(id)` → shell stack                       |
| 19  | Peek merchant (stacked)           | merchant name inside the peek      | `stackMerchant(name)` → back arrow                    |
| 20  | Download original                 | row `…`, peek footer               | navigation (raw `href`, real file endpoint)           |

## The code

### context.ts

```ts
// UploadCenter/context.ts
import {
	computed,
	inject,
	provide,
	reactive,
	ref,
	watch,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import {
	useBbTableContext,
	useConfirm,
	useToast,
	type BbTableContext,
} from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import { useCategoriesStore } from '@/stores/categories';
import { api } from '@/api';
import { watchDebounced } from '@vueuse/core';
import type { Category, Receipt } from '@/types';

/** What the stacked sidebar can show. Clicking a name pushes one of these. */
export type PeekItem =
	| { type: 'receipt'; id: string }
	| { type: 'merchant'; name: string };

export type UploadCenterTab = 'drafts' | 'submitted' | 'reimbursed';

export interface ReceiptFilters {
	search: string;
	categoryIds: string[];
	merchant: string | null;
	/**
	 * `[start, end]` as `YYYY-MM-DD`, or `[]` when unset. Range mode requires an
	 * array modelValue -- binding `null` throws, so the empty filter is `[]`.
	 */
	spentBetween: string[];
}

/** A dropped file whose transfer is still in flight (or failed). Local-only. */
export type UploadRow = {
	/** Local id (`upload-…`) — never collides with server receipt ids. */
	id: string;
	kind: 'upload';
	filename: string;
	size: number;
	/** 0–100. Mutated in place per progress tick — reactive, no refetch. */
	progress: number;
	failed: boolean;
};

/** A server receipt as the table renders it. */
export type ReceiptRow = Receipt & { kind: 'receipt' };

/** What the table actually lists on the Drafts tab: uploads first. */
export type UploadCenterRow = UploadRow | ReceiptRow;

/** The only fields the inline cells may change. */
export type ReceiptPatch = Partial<
	Pick<Receipt, 'merchant' | 'categoryId' | 'amount' | 'date'>
>;

type ReceiptListResponse = {
	data: Receipt[];
	total: number;
	tabCounts: Record<UploadCenterTab, number>;
	readyCount: number;
};

export interface UploadCenterContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	table: BbTableContext;
	/** Shared expense-category catalog, coopted from the store. */
	categories: ComputedRef<Category[]>;
	// -- Page-owned state ------------------------------------------------------
	filters: ReceiptFilters;
	hasActiveFilters: ComputedRef<boolean>;
	tab: Ref<UploadCenterTab>;
	tabCounts: ComputedRef<Record<UploadCenterTab, number>>;
	/** Drafts that are complete (merchant + category + amount + date). */
	readyCount: ComputedRef<number>;
	/** The live upload queue — in-flight and failed transfers. */
	uploads: Ref<UploadRow[]>;
	// -- Data (server-rendered, URL-driven) -------------------------------------
	/** Drafts tab: queue rows first, then the fetched server page. */
	rows: ComputedRef<UploadCenterRow[]>;
	rowsPending: Ref<boolean>;
	searchMerchants: (query: string) => Promise<string[]>;
	// -- Peek grammar ----------------------------------------------------------
	peekReceipt: (id: string) => void;
	stackReceipt: (id: string) => void;
	stackMerchant: (name: string) => void;
	// -- Actions (complete: API + refresh + toast) ------------------------------
	clearFilters: () => void;
	enqueueFiles: (files: File[]) => void;
	retryUpload: (id: string) => void;
	removeUpload: (id: string) => void;
	updateReceipt: (receipt: Receipt, patch: ReceiptPatch) => Promise<void>;
	submitReceipt: (receipt: Receipt) => Promise<void>;
	submitAll: () => Promise<void>;
	/** Resolves `true` when the receipt was actually deleted (confirm accepted). */
	deleteReceipt: (receipt: Receipt) => Promise<boolean>;
	bulkCategorize: (categoryId: string) => Promise<void>;
	bulkRemove: () => Promise<void>;
}

const key: InjectionKey<UploadCenterContext> = Symbol('upload-center');

/** Comma-joined query value → string[] (or null when absent). */
const toArray = (value: unknown): string[] | null => {
	if (value == null || value === '') return null;
	return Array.isArray(value) ? value.map(String) : String(value).split(',');
};

export function provideUploadCenter(): UploadCenterContext {
	const { toast } = useToast();
	const { confirm } = useConfirm();
	const route = useRoute();

	// -- Coopt the specific contexts: once, here, for the whole page. ----------
	const shell = usePageShellContext<PeekItem>();
	const table = useBbTableContext('receipts-table', { perPage: 25 });
	const categoriesStore = useCategoriesStore();
	const categories = computed(() => categoriesStore.categories);

	// -- Filters + tab: seeded from the URL, the single source of truth. -------
	const filters = reactive<ReceiptFilters>({
		search: (route.query.search as string) ?? '',
		categoryIds: toArray(route.query.categoryIds) ?? [],
		merchant: (route.query.merchant as string) ?? null,
		spentBetween: toArray(route.query.spentBetween) ?? [],
	});
	const tab = ref<UploadCenterTab>(
		(route.query.tab as UploadCenterTab) ?? 'drafts'
	);

	const hasActiveFilters = computed(
		() =>
			filters.search !== '' ||
			filters.categoryIds.length > 0 ||
			filters.merchant !== null ||
			filters.spentBetween.length > 0
	);

	const clearFilters = () => {
		filters.search = '';
		filters.categoryIds = [];
		filters.merchant = null;
		filters.spentBetween = [];
	};

	// Every filter/tab change mirrors into the query string; `useAsyncData`
	// below watches `route.query`, so this is the whole refetch trigger.
	const syncQuery = () =>
		navigateTo({
			query: {
				search: filters.search || undefined,
				categoryIds: filters.categoryIds.length
					? filters.categoryIds.join(',')
					: undefined,
				merchant: filters.merchant ?? undefined,
				spentBetween: filters.spentBetween.length
					? filters.spentBetween.join(',')
					: undefined,
				tab: tab.value,
			},
		});
	watchDebounced(filters, syncQuery, { deep: true, debounce: 300 });
	watch(tab, () => {
		table.page.value = 1;
		syncQuery();
	});

	// -- Data ---------------------------------------------------------------------
	// The one place the *server* page is fetched. A drafts page looks like:
	//   { id: 'rcp_3128', filename: 'uber-2026-07-08.pdf',   merchant: 'Uber',
	//     categoryId: 'cat-rideshare', amount: 42.8,  date: '2026-07-08', … }
	//   { id: 'rcp_3127', filename: 'IMG_4021.jpg',          merchant: 'Starbucks Reserve',
	//     categoryId: 'cat-meals',     amount: 11.4,  date: '2026-07-08', … }
	//   { id: 'rcp_3120', filename: 'delta-ticket-0472.pdf', merchant: 'Delta Air Lines',
	//     categoryId: 'cat-travel',    amount: 428.6, date: '2026-07-06', … }
	//   { id: 'rcp_3117', filename: 'marriott-folio.pdf',    merchant: 'Marriott Marquis SF',
	//     categoryId: 'cat-lodging',   amount: 612.33, date: '2026-07-05', … }
	// The live upload queue is NOT part of this response — it is client-only
	// reactive state merged in below, ahead of the fetched rows.
	const { data, pending, refresh } = useAsyncData<ReceiptListResponse>(
		'receipts',
		() =>
			$fetch<ReceiptListResponse>('/api/receipts', {
				query: {
					search: filters.search || undefined,
					categoryIds: filters.categoryIds,
					merchant: filters.merchant ?? undefined,
					spentBetween: filters.spentBetween.length
						? filters.spentBetween
						: undefined,
					tab: tab.value,
					page: table.page.value,
					perPage: table.perPage.value,
				},
			}),
		{ watch: [() => route.query, table.page] }
	);
	const serverRows = computed<ReceiptRow[]>(
		() =>
			data.value?.data.map(
				(receipt): ReceiptRow => ({ ...receipt, kind: 'receipt' })
			) ?? []
	);
	// Drafts tab: queue rows render above the fetched page; a completed upload
	// re-enters here once the next `refresh()` lands it as a server draft.
	const uploads = ref<UploadRow[]>([]);
	const rows = computed<UploadCenterRow[]>(() =>
		tab.value === 'drafts'
			? [...uploads.value, ...serverRows.value]
			: serverRows.value
	);
	const rowsPending = pending;
	const tabCounts = computed(
		() => data.value?.tabCounts ?? { drafts: 0, submitted: 0, reimbursed: 0 }
	);
	const readyCount = computed(() => data.value?.readyCount ?? 0);
	watch(
		data,
		(response) => {
			if (response) table.totalItems.value = response.total;
		},
		{ immediate: true }
	);

	const searchMerchants = (query: string): Promise<string[]> =>
		$fetch<string[]>('/api/merchants/search', { query: { q: query } });

	// -- Upload machinery ----------------------------------------------------------
	// Untouched by the URL/useAsyncData swap: the queue is client-only state,
	// mutated in place per progress tick — reactive, no refetch — and `rows`
	// above re-derives on every push/filter. Files and abort controllers live
	// in closure maps, not render state.
	const uploadFiles = new Map<string, File>();
	const controllers = new Map<string, AbortController>();

	const startUpload = async (id: string) => {
		const file = uploadFiles.get(id);
		const row = uploads.value.find((upload) => upload.id === id);
		if (!file || !row) return;
		row.failed = false;
		row.progress = 0;
		const controller = new AbortController();
		controllers.set(id, controller);
		try {
			// `$fetch` has no upload-progress events, so `api.receipts.upload`
			// posts FormData through a small XHR wrapper in `@/api` instead of
			// `$fetch` — the call shape here is identical to the other platforms.
			await api.receipts.upload(file, {
				signal: controller.signal,
				onProgress: (percent) => {
					row.progress = percent;
				},
			});
			// Success: the file re-enters as a server draft with OCR-extracted
			// merchant/amount/date prefilled — the refresh swaps the rows.
			uploads.value = uploads.value.filter((upload) => upload.id !== id);
			uploadFiles.delete(id);
			await refresh();
		} catch {
			// Keep the row: the progress cell renders the inline Retry.
			row.failed = true;
		} finally {
			controllers.delete(id);
		}
	};

	const enqueueFiles = (files: File[]) => {
		for (const file of files) {
			const id = `upload-${crypto.randomUUID()}`;
			uploadFiles.set(id, file);
			uploads.value.push({
				id,
				kind: 'upload',
				filename: file.name,
				size: file.size,
				progress: 0,
				failed: false,
			});
			void startUpload(id);
		}
	};

	const retryUpload = (id: string) => {
		void startUpload(id);
	};

	const removeUpload = (id: string) => {
		controllers.get(id)?.abort();
		controllers.delete(id);
		uploadFiles.delete(id);
		uploads.value = uploads.value.filter((upload) => upload.id !== id);
	};

	// -- Peek grammar ----------------------------------------------------------------
	// peekX opens a fresh stack (from the list); stackX drills down (from a peek).
	const peekReceipt = (id: string) => shell.push({ type: 'receipt', id }, true);
	const stackReceipt = (id: string) => shell.push({ type: 'receipt', id });
	const stackMerchant = (name: string) =>
		shell.push({ type: 'merchant', name });

	// -- Actions --------------------------------------------------------------------
	const updateReceipt = async (receipt: Receipt, patch: ReceiptPatch) => {
		try {
			await $fetch(`/api/receipts/${receipt.id}`, {
				method: 'PATCH',
				body: patch,
			});
			await refresh(); // silent on success — the cell already shows the new value
		} catch {
			await refresh(); // the refetch reverts the cell to the server value
			toast({
				title: `Could not save ${receipt.filename}. Changes were reverted.`,
				variant: 'destructive',
			});
		}
	};

	const submitReceipt = async (receipt: Receipt) => {
		await $fetch(`/api/receipts/${receipt.id}/submit`, { method: 'POST' });
		await refresh();
		toast({
			title: `${receipt.merchant ?? receipt.filename} submitted for approval.`,
			variant: 'success',
		});
	};

	const submitAll = async () => {
		const { submitted } = await $fetch<{ submitted: number }>(
			'/api/receipts/submit-drafts',
			{ method: 'POST' }
		);
		await refresh();
		toast({
			title: `${submitted} receipts submitted for approval.`,
			variant: 'success',
		});
	};

	const deleteReceipt = async (receipt: Receipt): Promise<boolean> => {
		const ok = await confirm({
			variant: 'destructive',
			title: 'Remove receipt',
			text: `Remove ${receipt.filename}? The file is deleted and cannot be recovered.`,
			yes: 'Remove',
			no: 'Cancel',
		});
		if (!ok) return false;
		await $fetch(`/api/receipts/${receipt.id}`, { method: 'DELETE' });
		await refresh();
		toast({ title: `${receipt.filename} removed.`, variant: 'success' });
		return true;
	};

	// Bulk actions read and clear the coopted table context themselves. Only
	// draft receipt rows are selectable, so `selected` holds receipt ids.
	const bulkIds = (): string[] => table.selected.value;
	const clearSelection = () => {
		table.selected.value = [];
	};

	const bulkCategorize = async (categoryId: string) => {
		const ids = bulkIds();
		await $fetch('/api/receipts/bulk/categorize', {
			method: 'PATCH',
			body: { ids, categoryId },
		});
		const category = categories.value.find((entry) => entry.id === categoryId);
		clearSelection();
		await refresh();
		toast({
			title: `${ids.length} receipts filed under ${category?.name ?? 'the selected category'}.`,
			variant: 'success',
		});
	};

	const bulkRemove = async () => {
		const ids = bulkIds();
		const ok = await confirm({
			variant: 'destructive',
			title: 'Remove receipts',
			text: `Remove ${ids.length} receipts? Their files are deleted and cannot be recovered.`,
			yes: 'Remove',
			no: 'Cancel',
		});
		if (!ok) return;
		await $fetch('/api/receipts/bulk/delete', {
			method: 'POST',
			body: { ids },
		});
		clearSelection();
		await refresh();
		toast({ title: `${ids.length} receipts removed.`, variant: 'success' });
	};

	const ctx: UploadCenterContext = {
		shell,
		table,
		categories,
		filters,
		hasActiveFilters,
		tab,
		tabCounts,
		readyCount,
		uploads,
		rows,
		rowsPending,
		searchMerchants,
		peekReceipt,
		stackReceipt,
		stackMerchant,
		clearFilters,
		enqueueFiles,
		retryUpload,
		removeUpload,
		updateReceipt,
		submitReceipt,
		submitAll,
		deleteReceipt,
		bulkCategorize,
		bulkRemove,
	};
	provide(key, ctx);
	return ctx;
}

export function useUploadCenter(): UploadCenterContext {
	const ctx = inject(key);
	if (!ctx) throw new Error('useUploadCenter() called outside UploadCenter');
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- UploadCenter/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left, page search + submit-all right. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs
					class="min-w-0 flex-auto"
					:items="[
						{ key: 'dashboard', text: 'Dashboard', to: '/dashboard' },
						{ key: 'expenses', text: 'Expenses', to: '/expenses' },
						{ key: 'receipts', text: 'Receipts' },
					]"
				/>
				<div class="flex shrink-0 items-center gap-2">
					<BbTextInput
						v-model="ctx.filters.search"
						autocomplete="off"
						clearable
						compact
						hide-label
						label="Search receipts"
						placeholder="Search merchant or filename…"
						prepend:icon="lucide:search"
					/>
					<!-- The page's single primary: submit-all with a live count.
					     BbButton tracks the async handler, so it shows its own
					     loading state while the batch submits. -->
					<BbButton
						:disabled="ctx.readyCount.value === 0"
						prepend:icon="lucide:send"
						variant="primary"
						@click="ctx.submitAll"
					>
						{{ submitLabel }}
					</BbButton>
				</div>
			</div>
		</template>

		<div class="flex flex-col gap-3 p-4">
			<!-- Capture surface: drafts tab only. -->
			<ReceiptDropzone v-if="ctx.tab.value === 'drafts'" />

			<FilterRail />

			<!-- Tabs as URL filters: href updates the query, the key feeds the
			     fetch. Counts come from the server on every fetch. -->
			<BbTabs
				v-model="ctx.tab.value"
				compact
				:items="[
					{
						key: 'drafts',
						label: `Drafts · ${ctx.tabCounts.value.drafts}`,
						href: '?tab=drafts',
					},
					{
						key: 'submitted',
						label: `Submitted · ${ctx.tabCounts.value.submitted}`,
						href: '?tab=submitted',
					},
					{
						key: 'reimbursed',
						label: `Reimbursed · ${ctx.tabCounts.value.reimbursed}`,
						href: '?tab=reimbursed',
					},
				]"
			/>

			<BbTable
				id="receipts-table"
				actions
				caption="Expense receipts"
				:columns="columns"
				compact
				item-value="id"
				:items="ctx.rows.value"
				legend="Select receipts"
				:loading="ctx.rowsPending.value"
				loading-text="Loading receipts…"
				:row-class="rowClass"
				:selectable="isDraft"
			>
				<!-- Clicking the NAME of a thing peeks it. -->
				<template #filename="{ item }">
					<ReceiptFileCell :row="item" />
				</template>

				<!-- Editable cells on draft rows; plain text everywhere else. -->
				<template #merchant="{ item }">
					<MerchantCell v-if="isDraft(item)" :receipt="item" />
					<span
						v-else-if="item.kind === 'upload'"
						class="text-[color:var(--bb-text-muted)]"
						>—</span
					>
					<span v-else>{{ item.merchant ?? '—' }}</span>
				</template>

				<template #categoryid="{ item }">
					<CategoryCell v-if="isDraft(item)" :receipt="item" />
					<span
						v-else-if="item.kind === 'upload'"
						class="text-[color:var(--bb-text-muted)]"
						>—</span
					>
					<span v-else>{{ categoryName(item.categoryId) }}</span>
				</template>

				<template #amount="{ item }">
					<AmountCell v-if="isDraft(item)" :receipt="item" />
					<span
						v-else-if="item.kind === 'upload'"
						class="text-[color:var(--bb-text-muted)]"
						>—</span
					>
					<span v-else>{{
						item.amount === null ? '—' : currency.format(item.amount)
					}}</span>
				</template>

				<template #date="{ item }">
					<DateCell v-if="isDraft(item)" :receipt="item" />
					<span
						v-else-if="item.kind === 'upload'"
						class="text-[color:var(--bb-text-muted)]"
						>—</span
					>
					<span v-else>{{ item.date ? shortDate(item.date) : '—' }}</span>
				</template>

				<!-- Status column doubles as the transfer surface for queue rows. -->
				<template #status="{ item }">
					<UploadProgressCell v-if="item.kind === 'upload'" :upload="item" />
					<BbBadge v-else variant="outline">{{ item.status }}</BbBadge>
				</template>

				<template #actions="{ item }">
					<RowActions :row="item" />
				</template>

				<template #no-data>
					<div class="flex flex-col items-center gap-2 p-6 text-center">
						<p class="text-sm text-[color:var(--bb-text-muted)]">
							{{
								ctx.hasActiveFilters.value
									? 'No receipts match the current filters.'
									: ctx.tab.value === 'drafts'
										? 'No drafts — drop receipts above to get started.'
										: 'Nothing here yet.'
							}}
						</p>
						<BbButton
							v-if="ctx.hasActiveFilters.value"
							variant="ghost"
							@click="ctx.clearFilters"
						>
							Clear filters
						</BbButton>
					</div>
				</template>
			</BbTable>

			<!-- Joins the table context by id: no page/totalPages wiring at all. -->
			<BbPagination table-id="receipts-table" />
		</div>

		<SelectionBar />

		<!-- Stacked peek sidebar: the shell owns back/close; we render by type. -->
		<template #sidebar>
			<ReceiptPeek
				v-if="ctx.shell.current.value?.type === 'receipt'"
				:receipt-id="ctx.shell.current.value.id"
			/>
			<MerchantPeek
				v-else-if="ctx.shell.current.value?.type === 'merchant'"
				:merchant-name="ctx.shell.current.value.name"
			/>
		</template>
	</PageShell>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import {
	BbBadge,
	BbBreadcrumbs,
	BbButton,
	BbPagination,
	BbTable,
	BbTabs,
	BbTextInput,
} from 'bitboss-ui';
import PageShell from '@/components/layout/PageShell.vue';
import {
	provideUploadCenter,
	type ReceiptRow,
	type UploadCenterRow,
} from './context';
import AmountCell from './AmountCell.vue';
import CategoryCell from './CategoryCell.vue';
import DateCell from './DateCell.vue';
import FilterRail from './FilterRail.vue';
import MerchantCell from './MerchantCell.vue';
import MerchantPeek from './MerchantPeek.vue';
import ReceiptDropzone from './ReceiptDropzone.vue';
import ReceiptFileCell from './ReceiptFileCell.vue';
import ReceiptPeek from './ReceiptPeek.vue';
import RowActions from './RowActions.vue';
import SelectionBar from './SelectionBar.vue';
import UploadProgressCell from './UploadProgressCell.vue';

const ctx = provideUploadCenter();

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
const shortDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
	});

// Every cell renders through a slot, so columns stay label-only definitions.
const columns = [
	{ key: 'filename', label: 'Receipt' },
	{ key: 'merchant', label: 'Merchant' },
	{ key: 'categoryId', label: 'Category' },
	{ key: 'amount', label: 'Amount', align: 'right' as const },
	{ key: 'date', label: 'Date' },
	{ key: 'status', label: 'Status' },
];

// Only server-side drafts are editable and selectable; queue rows and
// submitted/reimbursed receipts are not.
const isDraft = (item: UploadCenterRow): item is ReceiptRow =>
	item.kind === 'receipt' && item.status === 'draft';

// Failed transfers get a tinted row — public row-class API, no internals.
const rowClass = (item: UploadCenterRow) =>
	item.kind === 'upload' && item.failed
		? 'bg-red-50 dark:bg-red-950/20'
		: undefined;

const categoryName = (categoryId: string | null) =>
	ctx.categories.value.find((category) => category.id === categoryId)?.name ??
	'—';

const submitLabel = computed(() =>
	ctx.readyCount.value === 0
		? 'Submit receipts'
		: `Submit ${ctx.readyCount.value} ${ctx.readyCount.value === 1 ? 'receipt' : 'receipts'}`
);
</script>
```

### ReceiptDropzone.vue

```vue
<!-- UploadCenter/ReceiptDropzone.vue -->
<template>
	<BbDropzone
		v-model="pending"
		:accept="ACCEPT"
		:errors="dropError"
		:max-files="20"
		:max-size="MAX_SIZE"
		multiple
		@error="onError"
	>
		<template #default="{ dragging, focused, open }">
			<div
				class="flex flex-col items-center gap-2 rounded-[var(--bb-radius)] border-2 border-dashed p-6 text-center transition-colors"
				:class="[
					dragging ? 'border-[var(--bb-primary)]' : 'border-[var(--bb-border)]',
					focused ? 'ring-2 ring-[var(--bb-primary)] ring-offset-2' : '',
				]"
			>
				<BbIcon
					class="text-[color:var(--bb-text-muted)]"
					icon="lucide:receipt"
					size="lg"
				/>
				<p class="text-sm font-medium">
					{{ dragging ? 'Drop to add receipts' : 'Drop receipts here' }}
				</p>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					JPG, PNG, HEIC or PDF · up to 10 MB each · 20 files per drop
				</p>
				<BbButton
					prepend:icon="lucide:folder-open"
					variant="ghost"
					@click="open"
				>
					Browse files
				</BbButton>
			</div>
		</template>
	</BbDropzone>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue';
import { BbButton, BbDropzone, BbIcon, type DropZoneError } from 'bitboss-ui';
import { useUploadCenter } from './context';

// Pair every extension with its MIME type: the MIME rule matches by content
// type, the .ext rule catches drag-drops where the OS leaves file.type empty.
const ACCEPT = [
	'image/jpeg',
	'.jpg',
	'.jpeg',
	'image/png',
	'.png',
	'image/heic',
	'.heic',
	'application/pdf',
	'.pdf',
];
const MAX_SIZE = 10 * 1024 * 1024; // 10 MB per receipt

const ctx = useUploadCenter();

// BbDropzone captures and validates; the context uploads (posting FormData
// through an XHR wrapper — see context.ts). The model is a hand-off buffer:
// drain every validated batch into the queue, then clear it (which also
// resets the duplicate check for future corrections).
const pending = ref<File[]>([]);
watch(pending, (files) => {
	if (files.length === 0) return;
	dropError.value = undefined;
	ctx.enqueueFiles(files);
	pending.value = [];
});

// The errors display is a round-trip: map each typed reject to a sentence
// and feed it back through the `errors` prop (rendered in the built-in
// aria-live region and referenced from the input's aria-describedby). Batch drops emit one error per file; showing the last
// message keeps the surface calm.
const dropError = ref<string | undefined>();
const onError = (error: DropZoneError) => {
	if (error.type === 'maxSize') {
		dropError.value = `${error.filename} is ${error.formattedSize} — receipts are capped at ${error.formattedMaxSize}.`;
	} else if (error.type === 'accept') {
		dropError.value = `${error.filename} is not a JPG, PNG, HEIC or PDF.`;
	} else if (error.type === 'uniqueness') {
		dropError.value = `${error.filename} is already in this drop.`;
	} else {
		dropError.value = `That drop had ${error.totalFiles} files — add at most 20 at a time.`;
	}
};
</script>
```

### FilterRail.vue

```vue
<!-- UploadCenter/FilterRail.vue -->
<template>
	<div class="flex flex-wrap items-center gap-2">
		<!-- Category: multi-select pill over the coopted catalog. -->
		<BbSelectPopover
			v-model="ctx.filters.categoryIds"
			item-text="name"
			item-value="id"
			:items="ctx.categories.value"
			multiple
			width="240px"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filter by category"
					append:icon="lucide:chevron-down"
					size="sm"
					variant="outline"
				>
					Category{{
						ctx.filters.categoryIds.length
							? ` · ${ctx.filters.categoryIds.length}`
							: ''
					}}
				</BbButton>
			</template>
		</BbSelectPopover>

		<!-- Merchant: query-aware search. Merchant names are their own values,
		     so the pill labels itself straight from the filter state. -->
		<BbSelectPopover
			v-model="ctx.filters.merchant"
			:items="ctx.searchMerchants"
			width="240px"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filter by merchant"
					append:icon="lucide:chevron-down"
					size="sm"
					variant="outline"
				>
					{{ ctx.filters.merchant ?? 'Merchant' }}
				</BbButton>
			</template>
		</BbSelectPopover>

		<!-- Spent-between range: a compact input is 28px — flush with the pills. -->
		<BbDatePickerInput
			v-model="ctx.filters.spentBetween"
			clearable
			compact
			floating
			hide-label
			label="Spent between"
			placeholder="Spent between…"
			range
		/>

		<!-- Clear-all renders only while something is active. -->
		<BbButton
			v-if="ctx.hasActiveFilters.value"
			class="ml-auto"
			prepend:icon="lucide:x"
			size="sm"
			variant="ghost"
			@click="ctx.clearFilters"
		>
			Clear filters
		</BbButton>
	</div>
</template>

<script setup lang="ts">
import { BbButton, BbDatePickerInput, BbSelectPopover } from 'bitboss-ui';
import { useUploadCenter } from './context';

const ctx = useUploadCenter();
</script>
```

### ReceiptFileCell.vue

```vue
<!-- UploadCenter/ReceiptFileCell.vue -->
<template>
	<div class="flex items-center gap-2">
		<BbIcon
			class="shrink-0 text-[color:var(--bb-text-muted)]"
			:icon="fileIcon"
			size="16"
		/>
		<div class="flex min-w-0 flex-col">
			<!-- Server receipts peek on click; queue rows are not peekable yet. -->
			<BbButton
				v-if="row.kind === 'receipt'"
				class="justify-start"
				size="sm"
				variant="link"
				@click="() => ctx.peekReceipt(row.id)"
			>
				{{ row.filename }}
			</BbButton>
			<span v-else class="truncate text-sm">{{ row.filename }}</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">{{
				formattedSize
			}}</span>
		</div>
	</div>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbIcon } from 'bitboss-ui';
import { useUploadCenter, type UploadCenterRow } from './context';

const props = defineProps<{ row: UploadCenterRow }>();

const ctx = useUploadCenter();

const fileIcon = computed(() =>
	props.row.filename.toLowerCase().endsWith('.pdf')
		? 'lucide:file-text'
		: 'lucide:image'
);

const formattedSize = computed(() => {
	const bytes =
		props.row.kind === 'upload' ? props.row.size : props.row.fileSize;
	return bytes >= 1024 * 1024
		? `${(bytes / (1024 * 1024)).toFixed(1)} MB`
		: `${Math.max(1, Math.round(bytes / 1024))} KB`;
});
</script>
```

### UploadProgressCell.vue

```vue
<!-- UploadCenter/UploadProgressCell.vue -->
<template>
	<!-- In flight: a live bar. `upload.progress` is a reactive field mutated
	     by the context's progress callback — no refetch per tick. -->
	<div v-if="!upload.failed" class="flex min-w-32 items-center gap-2">
		<BbProgress
			:aria-label="`Uploading ${upload.filename}`"
			class="flex-1"
			:model-value="upload.progress"
		/>
		<span class="text-xs tabular-nums text-[color:var(--bb-text-muted)]"
			>{{ upload.progress }}%</span
		>
	</div>

	<!-- Failed: say so and retry inline. `xs` is fine here — this is the
	     densest surface on the page. -->
	<div v-else class="flex items-center gap-2">
		<span class="text-xs font-medium text-red-600 dark:text-red-400"
			>Upload failed</span
		>
		<BbButton
			prepend:icon="lucide:rotate-cw"
			size="xs"
			variant="outline"
			@click="() => ctx.retryUpload(upload.id)"
		>
			Retry
		</BbButton>
	</div>
</template>

<script setup lang="ts">
import { BbButton, BbProgress } from 'bitboss-ui';
import { useUploadCenter, type UploadRow } from './context';

defineProps<{ upload: UploadRow }>();

const ctx = useUploadCenter();
</script>
```

### MerchantCell.vue

```vue
<!-- UploadCenter/MerchantCell.vue -->
<template>
	<BbTextInput
		v-model="draft"
		compact
		hide-label
		label="Merchant"
		placeholder="Add merchant"
		@change="commit"
		@keydown.esc="revert"
	/>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue';
import { BbTextInput } from 'bitboss-ui';
import { useUploadCenter } from './context';
import type { Receipt } from '@/types';

const props = defineProps<{ receipt: Receipt }>();

const ctx = useUploadCenter();

// Inline-edit doctrine (§6.3): a local draft, commit on @change — which
// fires once for the whole blur/Enter sequence, unlike binding @blur AND
// @keydown.enter separately (that double-fires: Enter commits, then the
// field still blurs right after). Revert on Esc. The server value re-seeds
// the draft whenever a refetch updates the row — which is also how a
// failed save reverts.
const draft = ref<string | null>(props.receipt.merchant);
watch(
	() => props.receipt.merchant,
	(value) => {
		draft.value = value;
	}
);

const commit = () => {
	const merchant = draft.value?.trim() || null;
	if (merchant === props.receipt.merchant) return;
	void ctx.updateReceipt(props.receipt, { merchant });
};
const revert = () => {
	draft.value = props.receipt.merchant;
};
</script>
```

### CategoryCell.vue

```vue
<!-- UploadCenter/CategoryCell.vue -->
<template>
	<BbSelectPopover
		compact
		disable-writing
		item-text="name"
		item-value="id"
		:items="ctx.categories.value"
		:model-value="receipt.categoryId"
		width="220px"
		@update:model-value="(categoryId) => pick(categoryId as string)"
	>
		<template #activator="{ props: activatorProps, shown }">
			<!-- One-click pattern (§6.1): the badge is the focusable trigger —
			     BbBadgeButton takes over the badge body, the trailing chevron says
			     "this can change", and while the save runs `loading` swaps the
			     spinner into the chevron's place. A category is a label, not a
			     semantic status, so a set category reads neutral (`secondary`);
			     only the unset state stays `outline` so empty cells read as
			     quieter to-dos, not values. -->
			<BbBadge
				append:icon="lucide:chevron-down"
				:class="{ 'category-cell--open': shown }"
				:loading="saving"
				:variant="receipt.categoryId ? 'secondary' : 'outline'"
			>
				<BbBadgeButton
					:aria-label="`Change category for ${receipt.filename}`"
					v-bind="activatorProps"
					>{{ categoryName }}</BbBadgeButton
				>
			</BbBadge>
		</template>
	</BbSelectPopover>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
import { useUploadCenter } from './context';
import type { Receipt } from '@/types';

const props = defineProps<{ receipt: Receipt }>();

const ctx = useUploadCenter();

// In-flight flag for the save feedback — rung-1 local state, not context.
const saving = ref(false);
const pick = async (categoryId: string) => {
	saving.value = true;
	try {
		await ctx.updateReceipt(props.receipt, { categoryId });
	} finally {
		saving.value = false;
	}
};

// The trigger labels itself from the coopted catalog, never from the
// popover's lazy `text` slot prop.
const categoryName = computed(
	() =>
		ctx.categories.value.find(
			(category) => category.id === props.receipt.categoryId
		)?.name ?? 'Set category'
);
</script>

<style scoped>
/* Open = the badge's own hue, deepened, plus its variant ring — the same
   grammar as every badge-activator cell. */
.category-cell--open {
	--bg: color-mix(in oklab, var(--color) 24%, var(--bb-panel));
	--border-color: color-mix(in oklab, var(--color) 45%, var(--bb-panel));
	box-shadow: 0 0 0 var(--bb-ring-size) var(--ring);
}
</style>
```

### AmountCell.vue

```vue
<!-- UploadCenter/AmountCell.vue -->
<template>
	<BbNumberInput
		v-model="draft"
		compact
		hide-label
		label="Amount"
		:max-precision="2"
		:min="0"
		placeholder="0.00"
		@change="commit"
		@keydown.esc="revert"
	>
		<template #prefix>$</template>
	</BbNumberInput>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue';
import { BbNumberInput } from 'bitboss-ui';
import { useUploadCenter } from './context';
import type { Receipt } from '@/types';

const props = defineProps<{ receipt: Receipt }>();

const ctx = useUploadCenter();

// Same commit/revert contract as the merchant cell, on the number model —
// commit on @change, not @blur + @keydown.enter (see MerchantCell.vue).
const draft = ref<number | string | null>(props.receipt.amount);
watch(
	() => props.receipt.amount,
	(value) => {
		draft.value = value;
	}
);

const commit = () => {
	const amount =
		draft.value === null || draft.value === '' ? null : Number(draft.value);
	if (amount === props.receipt.amount) return;
	void ctx.updateReceipt(props.receipt, { amount });
};
const revert = () => {
	draft.value = props.receipt.amount;
};
</script>
```

### DateCell.vue

```vue
<!-- UploadCenter/DateCell.vue -->
<template>
	<!-- Picking a date IS the commit — no blur dance for calendar input.
	     `floating` keeps the model a plain YYYY-MM-DD string. -->
	<BbDatePickerInput
		compact
		floating
		hide-label
		label="Expense date"
		:model-value="receipt.date"
		placeholder="YYYY-MM-DD"
		@update:model-value="commit"
	/>
</template>

<script setup lang="ts">
import { BbDatePickerInput } from 'bitboss-ui';
import { useUploadCenter } from './context';
import type { Receipt } from '@/types';

const props = defineProps<{ receipt: Receipt }>();

const ctx = useUploadCenter();

const commit = (value: string | string[] | null) => {
	const date = Array.isArray(value) ? (value[0] ?? null) : value;
	if (date === props.receipt.date) return;
	void ctx.updateReceipt(props.receipt, { date });
};
</script>
```

### RowActions.vue

```vue
<!-- UploadCenter/RowActions.vue -->
<template>
	<!-- Queue rows: one explicit remove (aborts the transfer). -->
	<BbButton
		v-if="row.kind === 'upload'"
		:aria-label="`Remove ${row.filename} from the queue`"
		icon="lucide:x"
		size="sm"
		variant="ghost"
		@click="() => ctx.removeUpload(row.id)"
	/>

	<!-- Server receipts: contextual dropdown, entries vary by status. -->
	<BbDropdown v-else :items="items">
		<template #activator="{ props }">
			<BbButton v-bind="props" icon="lucide:ellipsis" size="sm" variant="ghost">
				Receipt actions
			</BbButton>
		</template>
	</BbDropdown>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbDropdown } from 'bitboss-ui';
import { useUploadCenter, type UploadCenterRow } from './context';

const props = defineProps<{ row: UploadCenterRow }>();

const ctx = useUploadCenter();

const items = computed(() => {
	if (props.row.kind !== 'receipt') return [];
	const receipt = props.row;
	const isDraft = receipt.status === 'draft';
	return [
		...(isDraft
			? [
					{
						key: 'submit',
						text: 'Submit for approval',
						'prepend:icon': 'lucide:send',
						onClick: () => ctx.submitReceipt(receipt),
					},
				]
			: []),
		{
			// A real file download, not a Nuxt page — a raw `href` triggers a
			// normal browser navigation instead of being intercepted by the
			// router, which is what a client-side `to` would otherwise do.
			key: 'download',
			text: 'Download original',
			'prepend:icon': 'lucide:download',
			href: `/receipts/${receipt.id}/file`,
		},
		...(isDraft
			? [
					{
						key: 'remove',
						text: 'Remove',
						'prepend:icon': 'lucide:trash-2',
						variant: 'destructive' as const,
						onClick: () => ctx.deleteReceipt(receipt),
					},
				]
			: []),
	];
});
</script>
```

### SelectionBar.vue

```vue
<!-- UploadCenter/SelectionBar.vue -->
<template>
	<FloatingBottomPanel :open="selectedCount > 0">
		<span class="px-2 text-sm">{{ selectedCount }} selected</span>

		<!-- Bulk categorize: the picker lives right in the bar — a one-shot
		     popover (model stays null) whose selection IS the action. -->
		<BbSelectPopover
			item-text="name"
			item-value="id"
			:items="ctx.categories.value"
			:model-value="null"
			placement="top"
			width="220px"
			@update:model-value="
				(categoryId) => categoryId && ctx.bulkCategorize(categoryId)
			"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Set category for selected receipts"
					prepend:icon="lucide:tag"
					size="sm"
					variant="ghost"
				>
					Set category
				</BbButton>
			</template>
		</BbSelectPopover>

		<div class="floating-bottom-panel__right flex items-center gap-1">
			<BbButton size="sm" variant="destructive" @click="ctx.bulkRemove"
				>Remove</BbButton
			>
			<BbButton
				aria-label="Clear selection"
				icon="lucide:x"
				size="sm"
				variant="ghost"
				@click="clearSelection"
			/>
		</div>
	</FloatingBottomPanel>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbSelectPopover } from 'bitboss-ui';
import FloatingBottomPanel from '@/components/layout/FloatingBottomPanel.vue';
import { useUploadCenter } from './context';

const ctx = useUploadCenter();

const selectedCount = computed(() => ctx.table.selected.value?.length ?? 0);
const clearSelection = () => {
	ctx.table.selected.value = [];
};
</script>
```

### ReceiptPeek.vue

```vue
<!-- UploadCenter/ReceiptPeek.vue -->
<template>
	<div v-if="receipt" class="flex flex-col gap-4 text-sm">
		<!-- Header: merchant identity + amount + status. The merchant name
		     drills DOWN — stacked peek, back arrow via the shell. -->
		<header class="flex flex-col gap-1.5">
			<div class="flex items-center justify-between gap-2">
				<BbButton
					v-if="receipt.merchant"
					size="sm"
					variant="link"
					@click="() => ctx.stackMerchant(receipt!.merchant!)"
				>
					{{ receipt.merchant }}
				</BbButton>
				<span v-else class="text-[color:var(--bb-text-muted)]"
					>No merchant yet</span
				>
				<BbBadge variant="outline">{{ receipt.status }}</BbBadge>
			</div>
			<p class="text-xl font-semibold">
				{{
					receipt.amount === null
						? 'Amount missing'
						: currency.format(receipt.amount)
				}}
			</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				{{ receipt.filename }} · spent
				{{ receipt.date ? longDate(receipt.date) : '—' }}
			</p>
		</header>

		<!-- Preview placeholder: the real app renders the scanned image here. -->
		<div
			class="flex h-44 flex-col items-center justify-center gap-1 rounded-[var(--bb-radius)] border bg-[var(--bb-panel)] text-[color:var(--bb-text-muted)]"
		>
			<BbIcon icon="lucide:receipt" size="lg" />
			<span class="text-xs">Receipt preview</span>
		</div>

		<!-- Extracted fields: what OCR read off the scan, with confidence. -->
		<section class="flex flex-col gap-1.5">
			<div class="flex items-center justify-between">
				<h3
					class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
				>
					Extracted fields
				</h3>
				<BbBadge size="xs" variant="outline">{{
					`OCR · ${receipt.extracted.confidence}%`
				}}</BbBadge>
			</div>
			<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
				<dt class="text-[color:var(--bb-text-muted)]">Merchant</dt>
				<dd>{{ receipt.extracted.merchant ?? '—' }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Total</dt>
				<dd>
					{{
						receipt.extracted.total === null
							? '—'
							: currency.format(receipt.extracted.total)
					}}
				</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Tax</dt>
				<dd>
					{{
						receipt.extracted.tax === null
							? '—'
							: currency.format(receipt.extracted.tax)
					}}
				</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Date</dt>
				<dd>
					{{ receipt.extracted.date ? longDate(receipt.extracted.date) : '—' }}
				</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Paid with</dt>
				<dd>{{ receipt.extracted.paymentMethod ?? '—' }}</dd>
			</dl>
		</section>

		<!-- Properties: the peek is a workbench — the category is the same
		     one-click cell as in the table. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Details
			</h3>
			<dl class="grid grid-cols-[auto_1fr] items-center gap-x-4 gap-y-1.5">
				<dt class="text-[color:var(--bb-text-muted)]">Category</dt>
				<dd><CategoryCell :receipt="receipt" /></dd>
				<dt class="text-[color:var(--bb-text-muted)]">Uploaded</dt>
				<dd>{{ longDate(receipt.uploadedAt) }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Report</dt>
				<dd>{{ receipt.reportName ?? 'Not on a report yet' }}</dd>
			</dl>
		</section>

		<!-- Activity feed. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Activity
			</h3>
			<ul class="flex flex-col gap-2">
				<li
					v-for="entry in receipt.activity"
					:key="entry.id"
					class="flex gap-2"
				>
					<BbIcon
						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
						:icon="entry.icon"
						size="14"
					/>
					<div class="flex flex-col">
						<span>{{ entry.text }}</span>
						<span class="text-xs text-[color:var(--bb-text-muted)]"
							>{{ entry.actor }} · {{ longDate(entry.at) }}</span
						>
					</div>
				</li>
			</ul>
		</section>

		<!-- Act here, or leave for the original file. -->
		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				v-if="receipt.status === 'draft'"
				prepend:icon="lucide:send"
				size="sm"
				variant="secondary"
				@click="() => ctx.submitReceipt(receipt!)"
			>
				Submit
			</BbButton>
			<!-- A real file download, not a Nuxt page — stays a raw `href`. -->
			<BbButton
				append:icon="lucide:arrow-up-right"
				:href="`/receipts/${receipt.id}/file`"
				size="sm"
				variant="ghost"
			>
				Download original
			</BbButton>
			<BbButton
				v-if="receipt.status === 'draft'"
				class="ml-auto"
				prepend:icon="lucide:trash-2"
				size="sm"
				variant="destructive"
				@click="removeAndClose"
			>
				Remove
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { ref, watchEffect } from 'vue';
import { BbBadge, BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
import CategoryCell from './CategoryCell.vue';
import { useUploadCenter } from './context';
import type { ReceiptDetail } from '@/types';

const props = defineProps<{ receiptId: string }>();

const ctx = useUploadCenter();

// Re-fetches whenever the stack shows a different receipt; `ctx.rows` changes
// on every server `refresh()` (mutations) or upload completion, so watching
// it makes inline edits (category, submit) reflect here immediately.
const receipt = ref<ReceiptDetail | null>(null);
watchEffect(async () => {
	void ctx.rows.value;
	receipt.value = await $fetch<ReceiptDetail>(
		`/api/receipts/${props.receiptId}`
	);
});

// deleteReceipt resolves true only when the confirm was accepted — don't
// close the peek on a cancelled dialog.
const removeAndClose = async () => {
	if (!receipt.value) return;
	if (await ctx.deleteReceipt(receipt.value)) ctx.shell.close();
};

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
const longDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
		year: 'numeric',
	});
</script>
```

### MerchantPeek.vue

```vue
<!-- UploadCenter/MerchantPeek.vue -->
<template>
	<div v-if="merchant" class="flex flex-col gap-4 text-sm">
		<header class="flex items-center gap-3">
			<div
				class="grid h-9 w-9 shrink-0 place-items-center rounded-[var(--bb-radius)] border"
			>
				<BbIcon
					class="text-[color:var(--bb-text-muted)]"
					icon="lucide:store"
					size="18"
				/>
			</div>
			<div class="flex flex-col">
				<h2 class="text-base font-semibold">{{ merchant.name }}</h2>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					{{ merchant.defaultCategoryName }} · this year
				</p>
			</div>
		</header>

		<!-- Stat strip. -->
		<div class="grid grid-cols-3 gap-2">
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Total spent</p>
				<p class="font-semibold">{{ currency.format(merchant.totalSpent) }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Receipts</p>
				<p class="font-semibold">{{ merchant.receiptCount }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Average</p>
				<p class="font-semibold">
					{{ currency.format(merchant.averageAmount) }}
				</p>
			</div>
		</div>

		<!-- Recent receipts: names drill down again — the stack keeps growing. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Recent receipts
			</h3>
			<ul class="flex flex-col">
				<li
					v-for="recent in merchant.recentReceipts"
					:key="recent.id"
					class="flex items-center justify-between gap-2 border-b py-1.5 last:border-b-0"
				>
					<BbButton
						size="sm"
						variant="link"
						@click="() => ctx.stackReceipt(recent.id)"
					>
						{{ recent.filename }}
					</BbButton>
					<BbBadge variant="outline">{{ recent.status }}</BbBadge>
					<span class="text-xs tabular-nums text-[color:var(--bb-text-muted)]">
						{{ currency.format(recent.amount) }}
					</span>
				</li>
			</ul>
		</section>

		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<!-- An internal listing page — a real Nuxt route, so this uses `to`. -->
			<BbButton
				append:icon="lucide:arrow-up-right"
				size="sm"
				:to="`/expenses/receipts?merchant=${encodeURIComponent(merchant.name)}`"
				variant="ghost"
			>
				All receipts from {{ merchant.name }}
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { ref, watchEffect } from 'vue';
import { BbBadge, BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
import { useUploadCenter } from './context';
import type { MerchantSummary } from '@/types';

const props = defineProps<{ merchantName: string }>();

const ctx = useUploadCenter();

const merchant = ref<MerchantSummary | null>(null);
watchEffect(async () => {
	merchant.value = await $fetch<MerchantSummary>(
		`/api/merchants/${encodeURIComponent(props.merchantName)}`
	);
});

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
</script>
```

## Why it is built this way

- **The context coopts, leaves consume.** `shell`, `table` **and the
  category catalog** are joined once in `provideUploadCenter()`; thirteen
  components share the filters, the queue, selection, the peek stack and
  every action through one `useUploadCenter()` call. No leaf imports
  `$fetch`, `@/api` or a store directly — even the query-aware merchant
  pill gets its provider (`ctx.searchMerchants`) from the context, so the
  page has exactly one import surface.
- **The URL is the filter store, `useAsyncData` is the fetch.** Filters
  and tab are seeded from `route.query` once at setup, mirrored back with
  `navigateTo` on every change (debounced for free text), and
  `useAsyncData('receipts', …, { watch: [() => route.query, table.page] })`
  is the single refetch trigger for the _server_ page — there is exactly
  one place server data loads.
- **The upload queue crosses the data-layer swap untouched.** It was
  always client-only reactive state, so it needed no adaptation: `uploads`
  stays a plain `ref`, progress ticks still mutate the row objects in
  place, and `rows` (a computed merging `uploads` ahead of the fetched
  `serverRows`) is what `BbTable` binds to directly — no items function, no
  `dependencies`, no `refreshKey`. A completed upload's own `refresh()`
  call is what swaps it into `serverRows` on the next tick.
- **`$fetch` can't stream upload progress, so the transfer itself doesn't
  use it.** `api.receipts.upload()` posts `FormData` through a small XHR
  wrapper instead — the only place this recipe steps outside `$fetch` —
  while every other mutation (`updateReceipt`, `submitReceipt`, the bulk
  actions) is a plain `$fetch` call followed by `await refresh()`.
- **The table context still owns paging and selection.** `useBbTableContext`
  is unchanged from the Vue recipe: it seeds `perPage`, `BbPagination`
  joins by `table-id`, and `SelectionBar` reads `table.selected` — only the
  _server_ rows move from an items-function to a resolved array merged
  into `rows`.
- **Peeks watch `ctx.rows.value`, not a manual refresh counter.** Since
  every mutation already calls the list's `refresh()`, and `rows` recomputes
  whenever the underlying `data` changes, a peek's `watchEffect(() => {
void ctx.rows.value; … })` re-fetches its own JSON detail for free — the
  same signal drives both surfaces.
- **`peekX` vs `stackX` is the whole stack grammar.** Filename →
  `peekReceipt` (replaces the stack); merchant name inside the peek →
  `stackMerchant` (pushes, back arrow appears); a recent receipt inside
  the merchant peek → `stackReceipt` (deeper still). The grammar lives in
  the context — a leaf cannot accidentally nuke the stack.
- **Tabs carry `href` and live counts**, exactly as in the Vue recipe — the
  client-side pushState they perform keeps `route.query.tab` in sync, which
  is what seeds `tab` on load and what `useAsyncData`'s `route.query` watch
  reacts to.
- **Internal links use `to`; real file downloads stay `href`.** The
  merchant peek's "All receipts from…" link is a genuine Nuxt route, so it
  uses `to` for client-side navigation. "Download original" (row `…`, peek
  footer) hits a raw file-serving endpoint, not a page — it deliberately
  keeps a plain `href` so the browser performs a real download instead of
  the router trying to resolve it as a route.
- **Sizing:** topbar follows `md`-first (`compact` search at 28px flush
  beside the default-size primary); `sm` appears exactly where the
  doctrine allows — row actions, pills, peek footers, the bulk bar — and
  the one `xs` (inline Retry) sits inside a table cell, the densest
  surface on the page. **One `variant="primary"`** (Submit all, with its
  live count and auto-tracked loading). Destructive actions — single,
  bulk, in-peek — all ride `useConfirm` with the filename or count in the
  message.

## Variations

- **Expense reports**: group receipts into named reports (a `reportId`
  column + a "Add to report" bulk action feeding a `BbSelectPopover` of
  open reports); the Submit-all primary becomes "Submit report".
- **Policy checks**: server flags out-of-policy drafts
  (`receipt.policyWarning`); tint the row, badge the amount cell, and
  render a `BbAlert` above the table summarizing the count.
- **Camera-first mobile**: keep `accept` image-heavy and rely on the
  native picker offering the camera; the dropzone slot collapses to a
  single "Snap a receipt" affordance under the mobile breakpoint.
- **Auto-submit on high confidence**: when `extracted.confidence` ≥ 95 and
  all four fields resolved, submit server-side on upload and toast an
  undo — the Drafts tab then only holds receipts needing review.
- **SSR-populated peeks**: swap the peeks' `$fetch` calls for
  `useAsyncData` keyed by id if the peek content should be part of the
  server-rendered payload rather than a client-side follow-up fetch.

---

<!-- dist/ai/recipes/nuxt/wizard-form.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/nuxt/wizard-form.md -->

# Recipe: Wizard Form (Nuxt)

The same Mailchimp-grade "Create campaign" wizard adapted for **Nuxt**: four
steps (Audience → Content → Schedule → Review) behind a custom stepper
header, per-step validation gating forward progress, the active step
mirrored into the URL, save-draft everywhere, and a dirty-state leave guard.
Anatomy, components, the context shape, copy and data are identical to the
Vue recipe; only the data/URL/mutation layer changes — the draft loads
through `useAsyncData`, mutations go through `$fetch` with `FetchError` 422
errors merged into the same per-step validation summary, and the step
mirrors into the URL with `navigateTo`.

Sibling recipes: [Vue](../vue/wizard-form.md) ·
[Inertia](../inertia/wizard-form.md).

## Prerequisites

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell` and `usePageShellContext` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
- `<BbConfirm />` and `<BbToast />` mounted once in `app.vue` — never in a page.
- [App Layout](../../guides/app-layout.md) and
  [Page Shell](../../guides/page-shell.md) copied into
  `src/components/layout/` per their guides — the page renders inside this
  chrome.
- Server routes: `GET /api/campaigns/:id` (returns `{ campaign, draft }`),
  `PATCH /api/campaigns/:id` (save draft — `422` with
  `{ errors: { field: ['message'] } }` on validation failure),
  `POST /api/campaigns/:id/send-test`, `POST /api/campaigns/:id/send`,
  `DELETE /api/campaigns/:id`; plus `GET /api/segments/:id`,
  `GET /api/segments/:id/estimate`, `GET /api/segments` (query-aware
  search) and `GET /api/segments/:id/detail` for the peek.

## Key ideas

- **One coopting page context.** `provideCampaignWizard()` joins the
  page-shell stack once and owns the draft, the current step, the live
  validation, and every action. All seven leaves call
  `useCampaignWizard()` and nothing else — the only prop on the page is
  the id the segment peek renders.
- **The stepper is derived state, not navigation chrome.** A step is
  reachable exactly when every step before it validates — the same
  predicate `goNext()` uses — so jumping from the header can never outrun
  the validation gate. Steps already passed show `done` (checkmarked),
  reachable future steps stay numbered (`upcoming`), and `locked` steps
  render as disabled `BbBaseButton`s.
- **Validation is computed live and merges server errors.** `issues`
  recomputes on every keystroke from client-side checks _and_ any `422`
  field errors left over from the last save, so a failed save surfaces on
  the owning step exactly like a blocked Next. The `BbAlert` summary and
  the inline field errors still appear only after a blocked Next
  (`attempted`), and shrink live as each problem clears.
- **The step lives in the URL, the draft lives on the server.** `?step=3`
  is mirrored with `navigateTo({ query }, { replace: true })`; on refresh
  `useAsyncData` re-fetches the saved draft and the requested step is
  clamped to the first incomplete one, so a shared link can never open a
  locked step.
- **One `BbSmoothHeight` wraps the alert + step outlet together**, so the
  step swap _and_ the validation summary appearing both glide instead of
  snapping. Conditional regions inside a step (the scheduled-date fields)
  need no wrapper of their own — the same resize observer catches them.
- **Back and Save draft are always free; validation only guards forward.**
  The page's one `variant="primary"` is the final Send/Schedule submit,
  with `:loading` riding `ctx.submitting`.
- **Leaving is guarded by a snapshot compare.** `dirty` is a JSON diff
  against the last saved draft; `onBeforeRouteLeave` (works unchanged in
  Nuxt) + `useConfirm` ask before losing changes, and both submit and
  discard reset the snapshot so they never double-prompt.

## Page anatomy

```
CampaignWizard/
	Index.vue          ← assembly: PageShell slots, stepper, BbSmoothHeight outlet, footer
	context.ts         ← coopting page context (shell + draft + step + validation + actions)
	StepperHeader.vue  ← BbBaseButton steps with done/current/upcoming/locked states
	AudienceStep.vue   ← segment select, audience filters, live recipient estimate
	ContentStep.vue    ← subject/preheader, body, template picker, send-test
	ScheduleStep.vue   ← send-now vs scheduled, date + timezone
	ReviewStep.vue     ← read-only summary with per-section Edit links
	WizardFooter.vue   ← Back · Save draft · Next / Send with :loading
	SegmentPeek.vue    ← sidebar workbench for the selected segment
```

Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
(left nav + fat footer) and [Page Shell](../../guides/page-shell.md).
Wizard archetype: no filter rail, no tabs, no table, no pagination, no bulk
bar — the work surface is the step outlet.

## Action inventory

| #   | Action                      | Trigger                          | Mechanism                                                                |
| --- | --------------------------- | -------------------------------- | ------------------------------------------------------------------------ |
| 1   | Advance a step (validated)  | footer **Next** (secondary)      | `goNext()` — blocks and raises the `BbAlert` summary on issues           |
| 2   | Go back                     | footer **Back** (ghost)          | `goBack()` — never validated                                             |
| 3   | Jump to an unlocked step    | stepper header                   | `goToStep()`; locked steps are disabled `BbBaseButton`s                  |
| 4   | Edit a section from Review  | per-section **Edit** links       | `goToStep()` back to that step                                           |
| 5   | Save draft                  | footer ghost, on every step      | `saveDraft()` → `$fetch` PATCH + snapshot reset + toast                  |
| 6   | Send a test email           | Content step ghost               | `sendTest()` → `$fetch` POST, validates content first                    |
| 7   | Send / schedule campaign    | Review, the page's one `primary` | `submit()` with `:loading`, whole-wizard validation, `$fetch` PATCH+POST |
| 8   | Discard draft               | topbar, destructive              | `useConfirm` → `$fetch` DELETE + `navigateTo('/campaigns')`              |
| 9   | Peek the segment            | segment name (Audience & Review) | `peekSegment()` → shell stack                                            |
| 10  | Leave with unsaved changes  | any route navigation             | `onBeforeRouteLeave` guard → `useConfirm`                                |
| 11  | Restore position on refresh | URL `?step=N`                    | step mirrored via `navigateTo(..., { replace: true })`, clamped on load  |

## The code

### context.ts

```ts
// CampaignWizard/context.ts
import {
	computed,
	inject,
	provide,
	reactive,
	ref,
	watch,
	watchEffect,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import { onBeforeRouteLeave } from 'vue-router';
import { FetchError } from 'ofetch';
import { useConfirm, useToast } from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import type { Campaign, Segment } from '@/types';

/** What the sidebar can show: the audience segment behind the campaign. */
export type PeekItem = { type: 'segment'; id: number };

export type StepKey = 'audience' | 'content' | 'schedule' | 'review';
export type StepStatus = 'done' | 'current' | 'upcoming' | 'locked';
export type SendMode = 'now' | 'scheduled';

export const STEPS: { key: StepKey; label: string }[] = [
	{ key: 'audience', label: 'Audience' },
	{ key: 'content', label: 'Content' },
	{ key: 'schedule', label: 'Schedule' },
	{ key: 'review', label: 'Review' },
];

export interface CampaignTemplate {
	id: string;
	name: string;
	description: string;
}

export const TEMPLATES: CampaignTemplate[] = [
	{
		id: 'product-update',
		name: 'Product update',
		description: 'Hero image, feature blocks, one CTA.',
	},
	{
		id: 'newsletter',
		name: 'Newsletter',
		description: 'Multi-story digest with section dividers.',
	},
	{
		id: 'plain-text',
		name: 'Plain text',
		description: 'No chrome — reads like a personal email.',
	},
];

export const TIMEZONES = [
	{ label: 'Rome (CET)', value: 'Europe/Rome' },
	{ label: 'London (GMT)', value: 'Europe/London' },
	{ label: 'New York (ET)', value: 'America/New_York' },
	{ label: 'Chicago (CT)', value: 'America/Chicago' },
	{ label: 'Los Angeles (PT)', value: 'America/Los_Angeles' },
	{ label: 'Tokyo (JST)', value: 'Asia/Tokyo' },
	{ label: 'Sydney (AEST)', value: 'Australia/Sydney' },
];

export const COUNTRIES = [
	{ label: 'Italy', value: 'IT' },
	{ label: 'France', value: 'FR' },
	{ label: 'Germany', value: 'DE' },
	{ label: 'United Kingdom', value: 'GB' },
	{ label: 'United States', value: 'US' },
	{ label: 'Canada', value: 'CA' },
];

/** Everything the four steps edit. Persisted verbatim by saveDraft/submit. */
export interface CampaignDraft {
	// Audience
	segmentId: number | null;
	/** Empty array = every country in the segment. */
	countries: string[];
	/** Skip contacts already emailed in the last 7 days. */
	excludeRecent: boolean;
	// Content
	subject: string;
	preheader: string;
	body: string;
	templateId: string | null;
	// Schedule
	sendMode: SendMode;
	/** ISO string from BbDatePickerInput; only meaningful when scheduled. */
	sendAt: string | null;
	timezone: string;
}

export interface StepIssue {
	/** Draft field the issue belongs to — leaves match on it for inline errors. */
	field: string;
	message: string;
}

export interface CampaignWizardContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	// -- Wizard state ----------------------------------------------------------
	loading: Ref<boolean>;
	campaign: Ref<Campaign | null>;
	draft: CampaignDraft;
	step: Ref<StepKey>;
	dirty: ComputedRef<boolean>;
	lastSavedAt: Ref<string | null>;
	submitting: Ref<boolean>;
	// -- Validation ------------------------------------------------------------
	issues: ComputedRef<Record<StepKey, StepIssue[]>>;
	/** Steps whose Next was blocked at least once — only they show errors. */
	attempted: Record<StepKey, boolean>;
	stepStatus: (key: StepKey) => StepStatus;
	fieldErrors: (step: StepKey, field: string) => string[];
	// -- Audience intel --------------------------------------------------------
	selectedSegment: Ref<Segment | null>;
	estimatedRecipients: Ref<number | null>;
	// -- Peek grammar ----------------------------------------------------------
	peekSegment: () => void;
	// -- Actions (complete: API + state + toast) --------------------------------
	goToStep: (key: StepKey) => void;
	goBack: () => void;
	goNext: () => void;
	saveDraft: () => Promise<void>;
	sendTest: () => Promise<void>;
	submit: () => Promise<void>;
	discardDraft: () => Promise<void>;
}

const key: InjectionKey<CampaignWizardContext> = Symbol('campaign-wizard');

/** Which step owns each server-validated field — used to route a failed
 * save's 422 errors onto the right step, merged into `issues` below. */
const FIELDS_BY_STEP: Record<StepKey, string[]> = {
	audience: ['segmentId'],
	content: ['subject', 'body', 'templateId'],
	schedule: ['sendAt', 'timezone'],
	review: [],
};
const stepForField = (field: string): StepKey | undefined =>
	(Object.keys(FIELDS_BY_STEP) as StepKey[]).find((stepKey) =>
		FIELDS_BY_STEP[stepKey].includes(field)
	);

export function provideCampaignWizard(): CampaignWizardContext {
	const { toast } = useToast();
	const { confirm } = useConfirm();
	const route = useRoute();

	// -- Coopt the specific contexts: once, here, for the whole page. ----------
	const shell = usePageShellContext<PeekItem>();

	// -- Wizard state -----------------------------------------------------------
	const campaignId = Number(route.params.campaignId);

	const draft = reactive<CampaignDraft>({
		segmentId: null,
		countries: [],
		excludeRecent: true,
		subject: '',
		preheader: '',
		body: '',
		templateId: null,
		sendMode: 'now',
		sendAt: null,
		timezone: 'Europe/Rome',
	});

	// The draft lives on the server (the list page created it before
	// navigating here, Mailchimp-style); useAsyncData both fetches it and
	// gives the page a reactive `pending` flag.
	const { data } = useAsyncData('campaign', () =>
		$fetch<{ campaign: Campaign; draft: CampaignDraft }>(
			`/api/campaigns/${campaignId}`
		)
	);
	const campaign = computed(() => data.value?.campaign ?? null);
	const loading = computed(() => data.value === null);

	// -- Server-side (422) errors, merged into `issues` below so the stepper,
	// the alert summary and the inline errors all read one source. -------------
	const serverErrors = reactive<Record<string, string[]>>({});

	// -- Validation ---------------------------------------------------------------
	// Live on every keystroke; SURFACED only per `attempted` (set when a Next,
	// submit or save is blocked), so untouched steps never open covered in red.
	const issues = computed<Record<StepKey, StepIssue[]>>(() => {
		const audience: StepIssue[] = [];
		if (draft.segmentId === null)
			audience.push({
				field: 'segmentId',
				message: 'Choose the segment this campaign goes to.',
			});

		const content: StepIssue[] = [];
		if (!draft.subject.trim())
			content.push({ field: 'subject', message: 'Write a subject line.' });
		else if (draft.subject.length > 150)
			content.push({
				field: 'subject',
				message: 'Keep the subject under 150 characters.',
			});
		if (!draft.body.trim())
			content.push({
				field: 'body',
				message: 'The email body cannot be empty.',
			});
		if (draft.templateId === null)
			content.push({ field: 'templateId', message: 'Pick a template.' });

		const schedule: StepIssue[] = [];
		if (draft.sendMode === 'scheduled') {
			if (!draft.sendAt)
				schedule.push({ field: 'sendAt', message: 'Pick a send date.' });
			if (!draft.timezone)
				schedule.push({ field: 'timezone', message: 'Pick a timezone.' });
		}

		// Merge server (422) errors onto the step that owns each field, so a
		// failed save surfaces exactly like a blocked Next.
		const withServerErrors = (
			stepKey: StepKey,
			list: StepIssue[]
		): StepIssue[] => [
			...list,
			...FIELDS_BY_STEP[stepKey]
				.filter((field) => serverErrors[field]?.length)
				.flatMap((field) =>
					serverErrors[field].map((message) => ({ field, message }))
				),
		];

		return {
			audience: withServerErrors('audience', audience),
			content: withServerErrors('content', content),
			schedule: withServerErrors('schedule', schedule),
			review: [],
		};
	});

	const attempted = reactive<Record<StepKey, boolean>>({
		audience: false,
		content: false,
		schedule: false,
		review: false,
	});

	const fieldErrors = (stepKey: StepKey, field: string): string[] =>
		attempted[stepKey]
			? issues.value[stepKey]
					.filter((issue) => issue.field === field)
					.map((issue) => issue.message)
			: [];

	// -- Step machine ---------------------------------------------------------------
	const step = ref<StepKey>('audience');

	const indexOf = (stepKey: StepKey) =>
		STEPS.findIndex((item) => item.key === stepKey);

	// The single gating predicate: a step is reachable when every step
	// before it validates. Next, the stepper, and submit all derive from it.
	const unlocked = (stepKey: StepKey) =>
		STEPS.slice(0, indexOf(stepKey)).every(
			(item) => issues.value[item.key].length === 0
		);

	const stepStatus = (stepKey: StepKey): StepStatus => {
		if (stepKey === step.value) return 'current';
		// Only steps already passed count as done — unlocked future steps stay
		// numbered (upcoming), not checkmarked.
		if (indexOf(stepKey) < indexOf(step.value)) return 'done';
		return unlocked(stepKey) ? 'upcoming' : 'locked';
	};

	const firstIncompleteStep = (): StepKey =>
		STEPS.find((item) => issues.value[item.key].length > 0)?.key ?? 'review';

	const goToStep = (stepKey: StepKey) => {
		if (stepKey !== step.value && stepStatus(stepKey) === 'locked') return;
		step.value = stepKey;
	};

	const goBack = () => {
		const previous = STEPS[indexOf(step.value) - 1];
		if (previous) step.value = previous.key;
	};

	const goNext = () => {
		const current = step.value;
		if (issues.value[current].length > 0) {
			attempted[current] = true; // raises the alert + inline errors
			return;
		}
		attempted[current] = false;
		const next = STEPS[indexOf(current) + 1];
		if (next) step.value = next.key;
	};

	// Mirror the step into the URL. `navigateTo` + `replace: true` is Nuxt's
	// router.replace — no full navigation, no extra history entry.
	watch(step, (next) => {
		void navigateTo(
			{ query: { ...route.query, step: String(indexOf(next) + 1) } },
			{ replace: true }
		);
	});

	// -- Audience intel ---------------------------------------------------------------
	// The select's v-model holds only the id; Review and the summary box need
	// the record. Same resolve-by-id pattern as the flagship's customer pill.
	const selectedSegment = ref<Segment | null>(null);
	watchEffect(async () => {
		selectedSegment.value =
			draft.segmentId === null
				? null
				: await $fetch<Segment>(`/api/segments/${draft.segmentId}`);
	});

	const estimatedRecipients = ref<number | null>(null);
	watchEffect(async () => {
		if (draft.segmentId === null) {
			estimatedRecipients.value = null;
			return;
		}
		estimatedRecipients.value = await $fetch<number>(
			`/api/segments/${draft.segmentId}/estimate`,
			{
				query: {
					countries: draft.countries,
					excludeRecent: draft.excludeRecent,
				},
			}
		);
	});

	// -- Peek grammar ----------------------------------------------------------------
	const peekSegment = () => {
		if (draft.segmentId !== null)
			shell.push({ type: 'segment', id: draft.segmentId }, true);
	};

	// -- Persistence + dirty guard ------------------------------------------------------
	const snapshot = ref('');
	const lastSavedAt = ref<string | null>(null);
	const dirty = computed(
		() => !loading.value && JSON.stringify(draft) !== snapshot.value
	);

	// Seed the draft once the fetch lands, and clamp ?step so a stale or
	// forged link can't open a locked step.
	watch(
		data,
		(response) => {
			if (!response) return;
			Object.assign(draft, response.draft);
			snapshot.value = JSON.stringify(draft);
			const requested = STEPS[Number(route.query.step) - 1]?.key ?? 'audience';
			step.value =
				stepStatus(requested) === 'locked' ? firstIncompleteStep() : requested;
		},
		{ immediate: true }
	);

	onBeforeRouteLeave(async () => {
		if (!dirty.value) return true;
		return confirm({
			variant: 'destructive',
			title: 'Leave campaign setup?',
			text: 'You have unsaved changes. Leave and lose them, or stay and save the draft.',
			yes: 'Leave',
			no: 'Keep editing',
		});
	});

	// -- Actions --------------------------------------------------------------------
	// `$fetch` throws a typed `FetchError`; 422 means field errors — merge
	// them into `serverErrors` (read by `issues` above) and jump to the
	// first broken step, exactly like a blocked Next.
	const applyServerErrors = (error: unknown): void => {
		if (!(error instanceof FetchError) || error.statusCode !== 422) throw error;
		Object.keys(serverErrors).forEach((field) => delete serverErrors[field]);
		const incoming = (error.data?.errors as Record<string, string[]>) ?? {};
		Object.assign(serverErrors, incoming);
		const brokenStep = Object.keys(incoming)
			.map(stepForField)
			.find((found): found is StepKey => Boolean(found));
		if (brokenStep) {
			attempted[brokenStep] = true;
			step.value = brokenStep;
		}
	};

	const saveDraft = async () => {
		Object.keys(serverErrors).forEach((field) => delete serverErrors[field]);
		try {
			await $fetch(`/api/campaigns/${campaignId}`, {
				method: 'PATCH',
				body: { ...draft },
			});
			snapshot.value = JSON.stringify(draft);
			lastSavedAt.value = new Date().toISOString();
			toast({ title: 'Draft saved.', variant: 'success' });
		} catch (error) {
			applyServerErrors(error);
		}
	};

	const sendTest = async () => {
		if (issues.value.content.length > 0) {
			attempted.content = true; // same surfacing as a blocked Next
			return;
		}
		await $fetch(`/api/campaigns/${campaignId}/send-test`, {
			method: 'POST',
			body: { ...draft },
		});
		toast({ title: 'Test email sent to your address.', variant: 'success' });
	};

	const submitting = ref(false);
	const submit = async () => {
		// Whole-wizard validation: land the user on the first broken step.
		const incomplete = STEPS.find((item) => issues.value[item.key].length > 0);
		if (incomplete) {
			attempted[incomplete.key] = true;
			step.value = incomplete.key;
			return;
		}
		submitting.value = true;
		Object.keys(serverErrors).forEach((field) => delete serverErrors[field]);
		try {
			await $fetch(`/api/campaigns/${campaignId}`, {
				method: 'PATCH',
				body: { ...draft },
			});
			await $fetch(`/api/campaigns/${campaignId}/send`, { method: 'POST' });
			snapshot.value = JSON.stringify(draft); // the guard has nothing left to protect
			toast({
				title:
					draft.sendMode === 'now'
						? 'Campaign is on its way.'
						: 'Campaign scheduled.',
				variant: 'success',
			});
			await navigateTo(`/campaigns/${campaignId}`);
		} catch (error) {
			applyServerErrors(error);
		} finally {
			submitting.value = false;
		}
	};

	const discardDraft = async () => {
		const ok = await confirm({
			variant: 'destructive',
			title: 'Discard draft',
			text: `Delete "${campaign.value?.name ?? 'this campaign'}" and everything entered so far? This cannot be undone.`,
			yes: 'Discard',
			no: 'Keep draft',
		});
		if (!ok) return;
		snapshot.value = JSON.stringify(draft); // don't double-prompt via the leave guard
		await $fetch(`/api/campaigns/${campaignId}`, { method: 'DELETE' });
		toast({ title: 'Draft discarded.', variant: 'success' });
		await navigateTo('/campaigns');
	};

	const ctx: CampaignWizardContext = {
		shell,
		loading,
		campaign,
		draft,
		step,
		dirty,
		lastSavedAt,
		submitting,
		issues,
		attempted,
		stepStatus,
		fieldErrors,
		selectedSegment,
		estimatedRecipients,
		peekSegment,
		goToStep,
		goBack,
		goNext,
		saveDraft,
		sendTest,
		submit,
		discardDraft,
	};
	provide(key, ctx);
	return ctx;
}

export function useCampaignWizard(): CampaignWizardContext {
	const ctx = inject(key);
	if (!ctx)
		throw new Error('useCampaignWizard() called outside CampaignWizard');
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- CampaignWizard/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left; save state + the destructive escape right.
		     Wizard archetype: no page search, no filter rail, no tabs. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs class="min-w-0 flex-auto" :items="crumbs" />
				<div class="flex shrink-0 items-center gap-3">
					<span
						v-if="savedLabel"
						class="text-xs text-[color:var(--bb-text-muted)]"
						>{{ savedLabel }}</span
					>
					<BbButton
						prepend:icon="lucide:trash-2"
						variant="destructive"
						@click="ctx.discardDraft"
					>
						Discard draft
					</BbButton>
				</div>
			</div>
		</template>

		<div class="mx-auto flex w-full max-w-3xl flex-col gap-5 p-4">
			<header class="flex flex-col gap-0.5">
				<h1 class="text-lg font-semibold">
					{{ ctx.campaign.value?.name ?? 'New campaign' }}
				</h1>
				<p class="text-sm text-[color:var(--bb-text-muted)]">
					Set up the audience, content and schedule, then review and send.
				</p>
			</header>

			<StepperHeader />

			<!-- One wrapper around the alert AND the step outlet: the step swap
			     and the validation summary appearing/shrinking both glide. -->
			<!-- Enable height motion only after mount so first paint does not
			     animate in; later step swaps still glide. -->
			<BbSmoothHeight :disabled="!stepHeightReady">
				<div class="flex flex-col gap-4">
					<BbAlert
						v-if="summaryIssues.length"
						hide-close
						icon="lucide:circle-x"
						:title="`Fix ${summaryIssues.length} ${summaryIssues.length === 1 ? 'issue' : 'issues'} to continue`"
						variant="destructive"
					>
						<template #text>
							<ul class="list-disc pl-4">
								<li v-for="issue in summaryIssues" :key="issue.field">
									{{ issue.message }}
								</li>
							</ul>
						</template>
					</BbAlert>

					<div v-if="ctx.loading.value" class="flex justify-center p-10">
						<BbSpinner />
					</div>
					<AudienceStep v-else-if="ctx.step.value === 'audience'" />
					<ContentStep v-else-if="ctx.step.value === 'content'" />
					<ScheduleStep v-else-if="ctx.step.value === 'schedule'" />
					<ReviewStep v-else />
				</div>
			</BbSmoothHeight>

			<WizardFooter />
		</div>

		<!-- Clicking the segment's NAME peeks it — Audience step and Review. -->
		<template #sidebar>
			<SegmentPeek
				v-if="ctx.shell.current.value?.type === 'segment'"
				:segment-id="ctx.shell.current.value.id"
			/>
		</template>
	</PageShell>
</template>

<script setup lang="ts">
import { computed, onMounted, ref } from 'vue';
import {
	BbAlert,
	BbBreadcrumbs,
	BbButton,
	BbSmoothHeight,
	BbSpinner,
} from 'bitboss-ui';
import PageShell from '@/components/layout/PageShell.vue';
import { provideCampaignWizard } from './context';
import AudienceStep from './AudienceStep.vue';
import ContentStep from './ContentStep.vue';
import ReviewStep from './ReviewStep.vue';
import ScheduleStep from './ScheduleStep.vue';
import SegmentPeek from './SegmentPeek.vue';
import StepperHeader from './StepperHeader.vue';
import WizardFooter from './WizardFooter.vue';

const ctx = provideCampaignWizard();

/** Keep SmoothHeight off while the first paint settles (initial load swaps
 * spinner → step content); enable after 300ms for step-to-step glides. */
const stepHeightReady = ref(false);
onMounted(() => {
	setTimeout(() => {
		stepHeightReady.value = true;
	}, 300);
});

const crumbs = computed(() => [
	{ key: 'dashboard', text: 'Dashboard', to: '/dashboard' },
	{ key: 'campaigns', text: 'Campaigns', to: '/campaigns' },
	{ key: 'setup', text: ctx.campaign.value?.name ?? 'New campaign' },
]);

// The summary shows only the CURRENT step's issues, and only once the user
// tried to leave it — it shrinks live as each problem is fixed.
const summaryIssues = computed(() =>
	ctx.attempted[ctx.step.value] ? ctx.issues.value[ctx.step.value] : []
);

const savedLabel = computed(() => {
	if (ctx.dirty.value) return 'Unsaved changes';
	if (!ctx.lastSavedAt.value) return null;
	const time = new Date(ctx.lastSavedAt.value).toLocaleTimeString('en-US', {
		hour: 'numeric',
		minute: '2-digit',
	});
	return `Draft saved at ${time}`;
});
</script>
```

### StepperHeader.vue

```vue
<!-- CampaignWizard/StepperHeader.vue -->
<template>
	<nav aria-label="Campaign setup steps" class="flex items-center gap-1">
		<template v-for="(stepMeta, index) in STEPS" :key="stepMeta.key">
			<!-- Connector line between steps. -->
			<div
				v-if="index > 0"
				aria-hidden="true"
				class="h-px min-w-3 flex-1 bg-[var(--bb-border)]"
			/>

			<!-- The primitive gives element semantics + disabled handling; the
			     look is entirely ours. Done and upcoming steps jump, locked
			     steps are inert. -->
			<BbBaseButton
				:aria-current="status(stepMeta.key) === 'current' ? 'step' : undefined"
				class="flex items-center gap-2 rounded-[var(--bb-radius)] px-2 py-1.5 text-sm focus-visible:ring-2 focus-visible:ring-[var(--bb-primary)]"
				:class="{
					'bg-[var(--bb-hover)] font-medium':
						status(stepMeta.key) === 'current',
					'hover:bg-[var(--bb-hover)]': ['done', 'upcoming'].includes(
						status(stepMeta.key)
					),
					'text-[color:var(--bb-text-muted)]':
						status(stepMeta.key) === 'locked',
				}"
				:disabled="status(stepMeta.key) === 'locked'"
				@click="() => ctx.goToStep(stepMeta.key)"
			>
				<span
					class="flex size-5 shrink-0 items-center justify-center rounded-full border text-xs"
					:class="{
						'border-transparent bg-[var(--bb-primary)] text-[var(--bb-primary-fg)]':
							status(stepMeta.key) === 'done',
						'border-[var(--bb-primary)] text-[color:var(--bb-primary)]':
							status(stepMeta.key) === 'current',
						'border-[var(--bb-border)]': status(stepMeta.key) === 'locked',
					}"
				>
					<BbIcon
						v-if="status(stepMeta.key) === 'done'"
						icon="lucide:check"
						size="12"
					/>
					<template v-else>{{ index + 1 }}</template>
				</span>
				{{ stepMeta.label }}
			</BbBaseButton>
		</template>
	</nav>
</template>

<script setup lang="ts">
import { BbBaseButton, BbIcon } from 'bitboss-ui';
import { STEPS, useCampaignWizard, type StepKey } from './context';

const ctx = useCampaignWizard();

const status = (key: StepKey) => ctx.stepStatus(key);
</script>
```

### AudienceStep.vue

```vue
<!-- CampaignWizard/AudienceStep.vue -->
<template>
	<section class="flex flex-col gap-4">
		<div class="flex flex-col gap-0.5">
			<h2 class="text-base font-semibold">Who gets this email?</h2>
			<p class="text-sm text-[color:var(--bb-text-muted)]">
				Pick a segment, then narrow it with delivery filters.
			</p>
		</div>

		<!-- Query-aware items function: the select searches the API as you type. -->
		<BbSelect
			v-model="ctx.draft.segmentId"
			:errors="segmentErrors"
			item-text="name"
			item-value="id"
			:items="searchSegments"
			label="Segment"
			label-mode="outside"
			placeholder="Search segments…"
			required
		/>

		<!-- Resolved segment + live estimate: the context owns both fetches. -->
		<div
			v-if="ctx.selectedSegment.value"
			class="flex flex-col gap-1 rounded-[var(--bb-radius)] border p-3 text-sm"
		>
			<div class="flex items-center justify-between gap-2">
				<BbButton size="sm" variant="link" @click="ctx.peekSegment">
					{{ ctx.selectedSegment.value.name }}
				</BbButton>
				<span class="text-xs text-[color:var(--bb-text-muted)]">
					Last synced {{ shortDate(ctx.selectedSegment.value.lastSyncedAt) }}
				</span>
			</div>
			<p class="text-[color:var(--bb-text-muted)]">
				{{ number.format(ctx.selectedSegment.value.contactCount) }} contacts in
				the segment ·
				<strong class="text-[var(--bb-text)]">
					{{
						ctx.estimatedRecipients.value === null
							? '…'
							: number.format(ctx.estimatedRecipients.value)
					}}
				</strong>
				estimated recipients after filters
			</p>
		</div>

		<BbSelect
			v-model="ctx.draft.countries"
			:items="COUNTRIES"
			item-text="label"
			item-value="value"
			label="Limit to countries"
			label-mode="outside"
			multiple
			placeholder="All countries"
		/>

		<BbSwitch
			v-model="ctx.draft.excludeRecent"
			description="Avoids fatigue: anyone who already received a campaign this week is skipped."
			label="Skip contacts emailed in the last 7 days"
		/>
	</section>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbSelect, BbSwitch } from 'bitboss-ui';
import { COUNTRIES, useCampaignWizard } from './context';
import type { Segment } from '@/types';

const ctx = useCampaignWizard();

// A small JSON endpoint — query-aware, so it stays a live search instead of
// a static lazy list.
const searchSegments = (query: string): Promise<Segment[]> =>
	$fetch<Segment[]>('/api/segments', { query: { search: query } });

// Inline errors appear only after a blocked Next (attempted), per the context.
const segmentErrors = computed(() => ctx.fieldErrors('audience', 'segmentId'));

const number = new Intl.NumberFormat('en-US');
const shortDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
	});
</script>
```

### ContentStep.vue

```vue
<!-- CampaignWizard/ContentStep.vue -->
<template>
	<section class="flex flex-col gap-4">
		<div class="flex flex-col gap-0.5">
			<h2 class="text-base font-semibold">What does it say?</h2>
			<p class="text-sm text-[color:var(--bb-text-muted)]">
				Subject and preheader are what people see in the inbox list.
			</p>
		</div>

		<BbTextInput
			v-model="ctx.draft.subject"
			:description="`${ctx.draft.subject.length}/150 characters`"
			:errors="errorsFor('subject')"
			label="Subject line"
			label-mode="outside"
			placeholder="The July roast drop is here — 20% off subscriptions"
			required
		/>

		<BbTextInput
			v-model="ctx.draft.preheader"
			description="Optional. Shows after the subject in most inboxes — keep it under 90 characters."
			label="Preheader"
			label-mode="outside"
			placeholder="Three new single origins, roasted this week."
		/>

		<!-- Fixed rows on purpose: an auto-growing textarea inside BbSmoothHeight
		     would re-animate the outlet on every line break while typing. -->
		<BbTextarea
			v-model="ctx.draft.body"
			:errors="errorsFor('body')"
			label="Body"
			label-mode="outside"
			placeholder="Write the email…"
			required
			:rows="10"
		/>

		<BbRadioGroup
			v-model="ctx.draft.templateId"
			:errors="errorsFor('templateId')"
			item-text="name"
			item-value="id"
			:items="TEMPLATES"
			legend="Template"
			name="template"
			required
		>
			<!-- Name + one-line description per option, from the same items. -->
			<template #label="{ item, text }">
				<span class="flex flex-col">
					<span>{{ text }}</span>
					<span class="text-xs text-[color:var(--bb-text-muted)]">{{
						item.description
					}}</span>
				</span>
			</template>
		</BbRadioGroup>

		<!-- Auto-loading: the button tracks the async handler by itself. -->
		<div>
			<BbButton
				prepend:icon="lucide:send"
				variant="ghost"
				@click="ctx.sendTest"
			>
				Send test email
			</BbButton>
		</div>
	</section>
</template>

<script setup lang="ts">
import { BbButton, BbRadioGroup, BbTextarea, BbTextInput } from 'bitboss-ui';
import { TEMPLATES, useCampaignWizard } from './context';

const ctx = useCampaignWizard();

const errorsFor = (field: string) => ctx.fieldErrors('content', field);
</script>
```

### ScheduleStep.vue

```vue
<!-- CampaignWizard/ScheduleStep.vue -->
<template>
	<section class="flex flex-col gap-4">
		<div class="flex flex-col gap-0.5">
			<h2 class="text-base font-semibold">When does it go out?</h2>
			<p class="text-sm text-[color:var(--bb-text-muted)]">
				Send it as soon as you confirm, or pick a date.
			</p>
		</div>

		<BbRadioGroup
			v-model="ctx.draft.sendMode"
			item-text="label"
			item-value="value"
			:items="[
				{
					label: 'Send now — goes out as soon as you confirm on Review',
					value: 'now',
				},
				{ label: 'Schedule for later', value: 'scheduled' },
			]"
			legend="When to send"
			name="send-mode"
		/>

		<!-- No inner BbSmoothHeight: the page-level wrapper's resize observer
		     already animates this region appearing and disappearing. -->
		<div
			v-if="ctx.draft.sendMode === 'scheduled'"
			class="grid gap-4 sm:grid-cols-2"
		>
			<BbDatePickerInput
				v-model="ctx.draft.sendAt"
				description="Campaigns go out at 9:00 AM local to the timezone you pick."
				:errors="errorsFor('sendAt')"
				label="Send date"
				label-mode="outside"
				:min="today"
				required
			/>
			<BbSelect
				v-model="ctx.draft.timezone"
				:errors="errorsFor('timezone')"
				item-text="label"
				item-value="value"
				:items="TIMEZONES"
				label="Timezone"
				label-mode="outside"
				required
			/>
		</div>
	</section>
</template>

<script setup lang="ts">
import { BbDatePickerInput, BbRadioGroup, BbSelect } from 'bitboss-ui';
import { TIMEZONES, useCampaignWizard } from './context';

const ctx = useCampaignWizard();

const errorsFor = (field: string) => ctx.fieldErrors('schedule', field);

// BbDatePickerInput's min takes YYYY-MM-DD.
const today = new Date().toISOString().slice(0, 10);
</script>
```

### ReviewStep.vue

```vue
<!-- CampaignWizard/ReviewStep.vue -->
<template>
	<section class="flex flex-col gap-5">
		<div class="flex flex-col gap-0.5">
			<h2 class="text-base font-semibold">Review and send</h2>
			<p class="text-sm text-[color:var(--bb-text-muted)]">
				Everything below is what goes out. Edit any section — your progress is
				kept.
			</p>
		</div>

		<!-- Audience -->
		<section
			class="flex flex-col gap-2 rounded-[var(--bb-radius)] border p-3 text-sm"
		>
			<div class="flex items-center justify-between gap-2">
				<h3
					class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
				>
					Audience
				</h3>
				<BbButton
					prepend:icon="lucide:pencil"
					size="sm"
					variant="ghost"
					@click="() => ctx.goToStep('audience')"
				>
					Edit
				</BbButton>
			</div>
			<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
				<dt class="text-[color:var(--bb-text-muted)]">Segment</dt>
				<dd>
					<BbButton size="sm" variant="link" @click="ctx.peekSegment">
						{{ ctx.selectedSegment.value?.name ?? '—' }}
					</BbButton>
				</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Countries</dt>
				<dd>{{ countryNames || 'All countries' }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Fatigue filter</dt>
				<dd>
					{{
						ctx.draft.excludeRecent
							? 'Skipping contacts emailed in the last 7 days'
							: 'Off'
					}}
				</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Estimated recipients</dt>
				<dd class="font-medium">
					{{
						ctx.estimatedRecipients.value === null
							? '—'
							: number.format(ctx.estimatedRecipients.value)
					}}
				</dd>
			</dl>
		</section>

		<!-- Content -->
		<section
			class="flex flex-col gap-2 rounded-[var(--bb-radius)] border p-3 text-sm"
		>
			<div class="flex items-center justify-between gap-2">
				<h3
					class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
				>
					Content
				</h3>
				<BbButton
					prepend:icon="lucide:pencil"
					size="sm"
					variant="ghost"
					@click="() => ctx.goToStep('content')"
				>
					Edit
				</BbButton>
			</div>
			<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
				<dt class="text-[color:var(--bb-text-muted)]">Subject</dt>
				<dd class="font-medium">{{ ctx.draft.subject }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Preheader</dt>
				<dd>{{ ctx.draft.preheader || '—' }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Template</dt>
				<dd>{{ templateName }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Body</dt>
				<dd class="text-[color:var(--bb-text-muted)]">{{ bodyExcerpt }}</dd>
			</dl>
		</section>

		<!-- Schedule -->
		<section
			class="flex flex-col gap-2 rounded-[var(--bb-radius)] border p-3 text-sm"
		>
			<div class="flex items-center justify-between gap-2">
				<h3
					class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
				>
					Schedule
				</h3>
				<BbButton
					prepend:icon="lucide:pencil"
					size="sm"
					variant="ghost"
					@click="() => ctx.goToStep('schedule')"
				>
					Edit
				</BbButton>
			</div>
			<p>{{ scheduleSummary }}</p>
		</section>
	</section>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton } from 'bitboss-ui';
import { COUNTRIES, TEMPLATES, TIMEZONES, useCampaignWizard } from './context';

const ctx = useCampaignWizard();

const number = new Intl.NumberFormat('en-US');

const countryNames = computed(() =>
	ctx.draft.countries
		.map(
			(code) =>
				COUNTRIES.find((country) => country.value === code)?.label ?? code
		)
		.join(', ')
);

const templateName = computed(
	() =>
		TEMPLATES.find((template) => template.id === ctx.draft.templateId)?.name ??
		'—'
);

const bodyExcerpt = computed(() =>
	ctx.draft.body.length > 140
		? `${ctx.draft.body.slice(0, 140)}…`
		: ctx.draft.body
);

const scheduleSummary = computed(() => {
	if (ctx.draft.sendMode === 'now')
		return 'Sends immediately after you confirm.';
	if (!ctx.draft.sendAt) return '—';
	const date = new Date(ctx.draft.sendAt).toLocaleDateString('en-US', {
		weekday: 'short',
		month: 'short',
		day: 'numeric',
		year: 'numeric',
	});
	const zone =
		TIMEZONES.find((timezone) => timezone.value === ctx.draft.timezone)
			?.label ?? ctx.draft.timezone;
	return `Scheduled for ${date} · 9:00 AM · ${zone}`;
});
</script>
```

### WizardFooter.vue

```vue
<!-- CampaignWizard/WizardFooter.vue -->
<template>
	<footer class="flex items-center justify-between gap-2 border-t pt-4">
		<!-- Back is always free — never validated, only bounded. -->
		<BbButton
			:disabled="isFirst"
			prepend:icon="lucide:chevron-left"
			variant="ghost"
			@click="ctx.goBack"
		>
			Back
		</BbButton>

		<div class="flex items-center gap-2">
			<!-- On every step, whatever the validation state. -->
			<BbButton
				prepend:icon="lucide:save"
				variant="ghost"
				@click="ctx.saveDraft"
			>
				Save draft
			</BbButton>

			<BbButton
				v-if="!isReview"
				append:icon="lucide:chevron-right"
				variant="secondary"
				@click="ctx.goNext"
			>
				Next
			</BbButton>

			<!-- The page's single primary. -->
			<BbButton
				v-else
				:loading="ctx.submitting.value"
				prepend:icon="lucide:send"
				variant="primary"
				@click="ctx.submit"
			>
				{{
					ctx.draft.sendMode === 'now' ? 'Send campaign' : 'Schedule campaign'
				}}
			</BbButton>
		</div>
	</footer>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton } from 'bitboss-ui';
import { STEPS, useCampaignWizard } from './context';

const ctx = useCampaignWizard();

const isFirst = computed(() => ctx.step.value === STEPS[0].key);
const isReview = computed(() => ctx.step.value === 'review');
</script>
```

### SegmentPeek.vue

```vue
<!-- CampaignWizard/SegmentPeek.vue -->
<template>
	<div v-if="segment" class="flex flex-col gap-4 text-sm">
		<header class="flex flex-col gap-0.5">
			<h2 class="text-base font-semibold">{{ segment.name }}</h2>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				{{ number.format(segment.contactCount) }} contacts · last synced
				{{ longDate(segment.lastSyncedAt) }}
			</p>
		</header>

		<!-- Stat strip. -->
		<div class="grid grid-cols-3 gap-2">
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Avg. open rate</p>
				<p class="font-semibold">{{ percent(segment.openRate) }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Avg. click rate</p>
				<p class="font-semibold">{{ percent(segment.clickRate) }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					Unsubscribes / mo
				</p>
				<p class="font-semibold">
					{{ number.format(segment.monthlyUnsubscribes) }}
				</p>
			</div>
		</div>

		<!-- The segment's definition, so "who is in here" is answerable in place. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Conditions
			</h3>
			<ul class="flex flex-col gap-1">
				<li v-for="rule in segment.rules" :key="rule" class="flex gap-2">
					<BbIcon
						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
						icon="lucide:filter"
						size="14"
					/>
					<span>{{ rule }}</span>
				</li>
			</ul>
		</section>

		<!-- Recent campaigns to this segment: fatigue check before sending. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Recent campaigns
			</h3>
			<ul class="flex flex-col">
				<li
					v-for="recent in segment.recentCampaigns"
					:key="recent.id"
					class="flex items-center justify-between gap-2 border-b py-1.5 last:border-b-0"
				>
					<span>{{ recent.name }}</span>
					<span class="text-xs text-[color:var(--bb-text-muted)]">{{
						longDate(recent.sentAt)
					}}</span>
				</li>
			</ul>
		</section>

		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				append:icon="lucide:arrow-up-right"
				size="sm"
				:to="`/segments/${segment.id}`"
				variant="ghost"
			>
				Open segment
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { ref, watchEffect } from 'vue';
import { BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
import type { SegmentDetail } from '@/types';

const props = defineProps<{ segmentId: number }>();

const segment = ref<SegmentDetail | null>(null);
watchEffect(async () => {
	segment.value = await $fetch<SegmentDetail>(
		`/api/segments/${props.segmentId}/detail`
	);
});

const number = new Intl.NumberFormat('en-US');
const percent = (value: number) => `${(value * 100).toFixed(1)}%`;
const longDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
		year: 'numeric',
	});
</script>
```

## Why it is built this way

- **The context coopts, leaves consume.** `shell` is joined once in
  `provideCampaignWizard()`; seven components share the draft, the step
  machine, validation and every action through one `useCampaignWizard()`
  call. The only data prop on the page is `SegmentPeek`'s `segment-id`;
  no component receives a callback.
- **One gating predicate rules everything.** `unlocked(step)` — every
  step before it validates — drives the stepper's `upcoming`/`locked`
  states, `goToStep`'s guard, and (via `issues[current]`) `goNext`. A
  stepper jump is therefore exactly as safe as pressing Next the right
  number of times; the header can never smuggle the user past validation.
  Only steps already passed count as `done` — a defaulted step (Schedule
  starts valid on "send now") stays numbered (`upcoming`), not
  checkmarked, until the user actually moves past it, though it is
  jumpable straight away: there is genuinely nothing left to do there.
- **`FetchError` is the error contract for saves.** `statusCode === 422`
  means field errors — `applyServerErrors` merges `error.data.errors` into
  `serverErrors`, which `issues` folds onto the owning step, so a failed
  save renders in the exact same `BbAlert` summary and inline errors as a
  client-side block, and jumps the user to the first broken step. Live
  issues, deferred surfacing still holds: errors render only for
  `attempted` steps, and shrink as each fix lands.
- **The step lives in the URL, the draft lives on the server.** `?step=3`
  mirrors via `navigateTo({ query }, { replace: true })` — no extra
  history entry; `useAsyncData` re-fetches the saved draft on load, and
  the requested step is clamped to the first incomplete one, so a stale or
  forged link degrades to the right place instead of an unusable locked
  screen.
- **Steps are four components, not one with a `type` prop.** Each step
  owns its inputs, its formatting helpers, and nothing else; the assembly
  is a `v-if` chain inside the `BbSmoothHeight` outlet. A single
  `WizardStep` with a renderer switch is the API-monster seed.
- **`BbBaseButton` is the right stepper primitive.** The steps are
  clickable surfaces whose look is entirely bespoke — token-styled pills
  with a number/check bullet — and the primitive contributes what CSS
  can't: a real `<button>`, native `disabled` for locked steps, and a
  focus scaffold (the visible ring is ours, per its guide). `aria-current="step"`
  is set manually — the prop-based `ariaCurrentValue` only applies to
  exact-active _links_.
- **One `BbSmoothHeight`, wrapping alert + outlet.** Both height changes
  on this page — the step swap and the summary toggling — animate through
  the same wrapper, so they compose into one glide when Next is blocked.
  Regions that appear _inside_ a step (the scheduled-date grid) are caught
  by the same resize observer; and the body textarea keeps fixed `rows`
  because an auto-growing textarea inside the wrapper would re-animate the
  outlet on every line break. Height motion is enabled only after mount
  (`:disabled` until a 300ms `onMounted` flag flips), so the first paint
  never animates in.
- **The guard, submit and discard share one snapshot.** `dirty` is a JSON
  compare against the last save; `submit` and `discardDraft` reset the
  snapshot before navigating so `onBeforeRouteLeave` (works unchanged in
  Nuxt) never re-asks about changes that were just sent or deliberately
  destroyed.
- **Sizing:** everything follows `md`-first — footer, topbar and step
  forms use default-size buttons and regular inputs; `sm` appears only on
  the dense inline surfaces (Review's Edit/segment links, the peek
  footer). One `variant="primary"` (Send/Schedule); Next is `secondary`;
  Save draft, Back and Send test are ghosts; the two destructive actions
  (discard, leave-with-changes) both ride `useConfirm`.

## Variations

- **Branching steps**: make `STEPS` a computed — e.g. an A/B test
  campaign inserts a "Variants" step after Content. The status predicate,
  URL mapping and footer already work off the array, so nothing else
  changes.
- **Autosave**: debounce a watcher on `draft` that calls a silent
  `saveDraft` (no toast); the footer button and the topbar save-state stay
  as the manual escape, and the leave guard almost never fires.
- **Vertical checklist stepper** (Mailchimp's actual layout): swap
  `StepperHeader` for a left rail where each step row also shows its
  one-line summary and the step bodies expand in place — the context and
  its predicate are unchanged.
- **Send time**: add an hour `BbSelect` beside the timezone and fold it
  into `sendAt` on save, replacing the fixed 9:00 AM policy.

---

<!-- dist/ai/recipes/vue/approvals-inbox.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/vue/approvals-inbox.md -->

# Recipe: Approvals Inbox (Vue)

The densest advanced-page recipe in the folder: a Linear-triage ×
Expensify-approvals expense inbox for a **plain Vue SPA with vue-router**.
`keyboard-navigation` turns the table into a single tab stop; the row under
the roving tabindex drives the peek sidebar directly (no click handler);
approve, reject-with-reason and snooze are each reachable from the row, the
peek footer, and an `A`/`R`/`S` shortcut bar — three dispatch surfaces
calling the exact same context actions; and a floating bottom panel adds
bulk approve/reject on top of the selection axis, fully independent of
highlight. All of it is wired through one coopting page context so every
leaf component takes zero props beyond the record it renders.

Sibling recipes: [Nuxt](../nuxt/approvals-inbox.md) ·
[Inertia](../inertia/approvals-inbox.md).

## Prerequisites

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell`, `usePageShellContext` and `FloatingBottomPanel` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
- `<BbConfirm />` and `<BbToast />` mounted once in the app root (`App.vue`) — never in a page.
- [App Layout](../../guides/app-layout.md), [Page Shell](../../guides/page-shell.md)
  and [Floating Bottom Panel](../../guides/floating-bottom-panel.md) copied
  into `src/components/layout/` per their guides — every recipe page assumes
  this chrome exists and renders inside it.

## Key ideas

- **Highlight drives the peek, not a click handler.** The table gets
  `keyboard-navigation`; `ctx.table.highlighted` (the coopted table
  context) is watched in `context.ts`, and every highlight change
  replaces the sidebar's stack with that expense — arrowing through rows
  previews each one with zero markup in `Index.vue`. Selection stays a
  fully independent axis, free for the bulk bar.
- **One coopting page context.** `provideApprovalsInbox()` joins the
  page-shell stack and the table context once, owns filters/tab/dialogs,
  and exposes complete actions. Every leaf calls `useApprovalsInbox()` and
  nothing else.
- **Three dispatch surfaces, one set of actions.** Approve / reject /
  snooze are reachable from the row, from inside the peek, and from the
  `A`/`R`/`S` keyboard shortcuts — all three call the exact same context
  functions (`approve`, `openReject`, `openSnooze`), so there is exactly
  one place each action's API call, refresh and toast live.
- **Reason and date are dialogs, not confirms.** Reject needs a typed
  reason and snooze needs a date, so both open a small `BbDialog` (the
  dialog itself is the confirmation gate) — a plain `useConfirm` is
  reserved for actions that need no input.
- **The shortcut bar mirrors `useDeleteCmd`'s guard.** A small keydown
  handler in the context checks `isInteractiveElementFocused()` before
  firing — typing "reason" in the reject textarea never triggers `R`.
- **Clicking a submitter's name always stacks**, from a row or from inside
  the expense peek — the back arrow appears once the stack is two deep,
  exactly the "peek vs stack" grammar of the flagship.
- **Tabs are URL filters with live counts** (`Needs approval` / `Approved`
  / `Rejected` / `All`), same shape as every other workspace in the
  folder.
- **Buttons are `md` by default**; `sm`/`xs` apply only where the doctrine
  allows it — table rows, the peek footers, the bulk bar, the shortcut
  bar.

- **Spread the filters object into `dependencies`.** `BbTable` hash-compares
  `dependencies`; it does not deep-watch them. Passing the reactive `filters`
  proxy itself tracks only its identity — which never changes — so the table
  never refetches. `{ ...ctx.filters }` reads every field during render, so any
  field change yields a new, differently-hashed array. Read `.value` off the
  refs for the same reason: context members are not auto-unwrapped in a template.

## Page anatomy

```
ApprovalsInbox/
	Index.vue            ← assembly: PageShell slots, table, tabs, pagination
	context.ts            ← coopting page context (shell + table + filters + shortcuts + actions)
	FilterRail.vue         ← pill filters + clear-all
	ShortcutsHint.vue       ← A / R / S icon buttons, tooltip-labelled, act on the highlighted row
	ReceiptThumbnail.vue   ← receipt image/placeholder cell
	RowActions.vue         ← per-row approve / reject / snooze icon buttons
	SelectionBar.vue       ← bulk approve / reject in the floating bottom panel
	RejectDialog.vue       ← single-row reject, required reason
	BulkRejectDialog.vue   ← bulk reject, required reason
	SnoozeDialog.vue       ← single-row snooze, date picker
	ExpensePeek.vue        ← sidebar workbench, stack level 1 (opens from highlight)
	SubmitterPeek.vue      ← stacked peek, back arrow via the shell
```

Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
(left nav + fat footer), [Page Shell](../../guides/page-shell.md),
[Floating Bottom Panel](../../guides/floating-bottom-panel.md).

## Action inventory

| #   | Action                           | Trigger                                                | Mechanism                                                 |
| --- | -------------------------------- | ------------------------------------------------------ | --------------------------------------------------------- |
| 1   | Page search (merchant/submitter) | topbar right                                           | `filters.search` → fetch dependency                       |
| 2   | Filter by submitter              | filter rail pill                                       | `BbSelectPopover` single, query-aware                     |
| 3   | Filter by category               | filter rail pill                                       | `BbSelectPopover` multiple                                |
| 4   | Quick filter: amount over        | filter rail pill                                       | `BbSelectPopover` single, preset thresholds               |
| 5   | Clear filters                    | rail right (only when active)                          | context `clearFilters()`                                  |
| 6   | Switch tab                       | href tabs with counts                                  | URL + fetch dependency                                    |
| 7   | Arrow through rows               | `keyboard-navigation` roving tabindex                  | table's own Arrow/Home/End                                |
| 8   | Preview an expense               | highlight a row (click, Enter/Space, arrow-then-Enter) | `ctx.table.highlighted` watcher → `peekExpense` (replace) |
| 9   | Approve (one click)              | row icon button, peek footer, key `A`                  | `approve(expense)` — API + refresh + toast                |
| 10  | Reject with reason               | row icon button, peek footer, key `R`                  | `openReject` → `RejectDialog` (required `BbTextarea`)     |
| 11  | Snooze                           | row icon button, peek footer, key `S`                  | `openSnooze` → `SnoozeDialog` (`BbDatePickerInput`)       |
| 12  | Select rows / select all         | table checkboxes                                       | table context                                             |
| 13  | Bulk approve                     | floating bottom panel                                  | `bulkApprove()` on `table.selected`                       |
| 14  | Bulk reject with reason          | floating bottom panel                                  | `BulkRejectDialog`, destructive                           |
| 15  | Stack a submitter                | submitter cell / peek property                         | `stackSubmitter(id)` → shell stack, back arrow            |
| 16  | Stack an expense from a profile  | recent-expense row inside `SubmitterPeek`              | `stackExpense(id)` → shell stack                          |
| 17  | View full-size receipt           | peek "View receipt" link                               | navigation (`href`, new tab)                              |
| 18  | Open full expense                | peek footer                                            | navigation (`/expenses/:id`)                              |
| 19  | Back / close peek                | shell chrome                                           | shell stack pop / close                                   |

Nineteen distinct actions, spanning inline one-click mutation (8),
input-gated mutation via dialog (10, 11, 14), bulk mutation (13, 14),
keyboard dispatch (7, 9, 10, 11), navigation (17, 18, 19) and contextual
drill-down (15, 16) — well past the ≥ 12 bar.

## The code

### context.ts

```ts
// ApprovalsInbox/context.ts
import {
	computed,
	inject,
	provide,
	reactive,
	ref,
	watch,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import { useMagicKeys, whenever } from '@vueuse/core';
import {
	useBbTableContext,
	useConfirm,
	useToast,
	type BbTableContext,
} from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import { api } from '@/api';
import type { Expense, ExpenseCategory } from '@/types';

/** What the stacked sidebar can show. Clicking a name pushes one of these. */
export type PeekItem =
	| { type: 'expense'; id: number }
	| { type: 'submitter'; id: number };

export type ApprovalsTab = 'needsApproval' | 'approved' | 'rejected' | 'all';

export interface ApprovalsFilters {
	search: string;
	submitterId: number | null;
	categories: ExpenseCategory[];
	/** Preset threshold from the quick filter (`50`, `100`, `250`…), or `null`. */
	amountOver: number | null;
}

export interface ApprovalsInboxContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	table: BbTableContext;
	// -- Page-owned state --------------------------------------------------------
	filters: ApprovalsFilters;
	hasActiveFilters: ComputedRef<boolean>;
	tab: Ref<ApprovalsTab>;
	tabCounts: Ref<Record<ApprovalsTab, number>>;
	refreshKey: Ref<number>;
	dialogs: {
		reject: Ref<Expense | null>;
		bulkReject: Ref<boolean>;
		snooze: Ref<Expense | null>;
	};
	/** The expense under the roving tabindex, resolved from the last fetch. */
	highlightedExpense: ComputedRef<Expense | null>;
	// -- Data ----------------------------------------------------------------
	fetchExpenses: () => Promise<Expense[]>;
	// -- Peek grammar ----------------------------------------------------------
	// (peekExpense — the highlight-driven replace — is internal to the watcher
	// below, not part of the public surface: leaves never open the peek
	// directly, only highlight drives it.)
	stackExpense: (id: number) => void;
	stackSubmitter: (id: number) => void;
	// -- Actions (complete: API + refresh + toast) ------------------------------
	clearFilters: () => void;
	approve: (expense: Expense) => Promise<void>;
	openReject: (expense: Expense) => void;
	reject: (expense: Expense, reason: string) => Promise<void>;
	openSnooze: (expense: Expense) => void;
	snooze: (expense: Expense, until: string) => Promise<void>;
	bulkApprove: () => Promise<void>;
	openBulkReject: () => void;
	bulkReject: (reason: string) => Promise<void>;
	// -- Keyboard-shortcut dispatch (mirrors the row/peek buttons) --------------
	approveHighlighted: () => void;
	rejectHighlighted: () => void;
	snoozeHighlighted: () => void;
}

const key: InjectionKey<ApprovalsInboxContext> = Symbol('approvals-inbox');

/** Mirrors `useDeleteCmd`'s guard: skip shortcuts while the user is typing. */
const isInteractiveElementFocused = (): boolean => {
	const active = document.activeElement;
	if (!active) return false;
	const tag = active.tagName.toLowerCase();
	if (tag === 'input' || tag === 'textarea' || tag === 'select') return true;
	return active.getAttribute('contenteditable') === 'true';
};

export function provideApprovalsInbox(): ApprovalsInboxContext {
	const { toast } = useToast();
	const { confirm } = useConfirm();

	// -- Coopt the specific contexts: once, here, for the whole page. ----------
	const shell = usePageShellContext<PeekItem>();
	const table = useBbTableContext('approvals-table', { perPage: 25 });

	// -- Page state ---------------------------------------------------------------
	const filters = reactive<ApprovalsFilters>({
		search: '',
		submitterId: null,
		categories: [],
		amountOver: null,
	});
	const hasActiveFilters = computed(
		() =>
			filters.search !== '' ||
			filters.submitterId !== null ||
			filters.categories.length > 0 ||
			filters.amountOver !== null
	);
	const tab = ref<ApprovalsTab>('needsApproval');
	const tabCounts = ref<Record<ApprovalsTab, number>>({
		needsApproval: 0,
		approved: 0,
		rejected: 0,
		all: 0,
	});
	const refreshKey = ref(0);
	const dialogs = {
		reject: ref<Expense | null>(null),
		bulkReject: ref(false),
		snooze: ref<Expense | null>(null),
	};

	const clearFilters = () => {
		filters.search = '';
		filters.submitterId = null;
		filters.categories = [];
		filters.amountOver = null;
	};

	// -- Data -----------------------------------------------------------------------
	// Cached so the keyboard shortcuts and the peek watcher can resolve a full
	// expense from the id the table context reports.
	const lastItems = ref<Expense[]>([]);
	const fetchExpenses = async (): Promise<Expense[]> => {
		const response = await api.expenses.list({
			...filters,
			tab: tab.value,
			page: table.page.value,
			perPage: table.perPage.value,
		});
		table.totalItems.value = response.total;
		tabCounts.value = response.tabCounts;
		lastItems.value = response.data;
		return response.data;
	};

	// -- Peek grammar -----------------------------------------------------------------
	// peekX replaces the stack (from the list / highlight); stackX drills down.
	const peekExpense = (id: number) => shell.push({ type: 'expense', id }, true);
	const stackExpense = (id: number) => shell.push({ type: 'expense', id });
	const stackSubmitter = (id: number) => shell.push({ type: 'submitter', id });

	// Highlighting IS the peek trigger: arrowing (or clicking) a row opens it,
	// clearing the highlight closes it. `item-value="id"` on the table means
	// `table.highlighted` already holds the plain id.
	watch(table.highlighted, (id) => {
		if (id == null) {
			shell.close();
		} else {
			peekExpense(id as number);
		}
	});

	const highlightedExpense = computed<Expense | null>(
		() =>
			lastItems.value.find(
				(expense) => expense.id === table.highlighted.value
			) ?? null
	);

	// -- Actions ----------------------------------------------------------------------
	const refresh = () => {
		refreshKey.value++;
	};
	const clearSelection = () => {
		table.selected.value = [];
	};

	const approve = async (expense: Expense) => {
		await api.expenses.approve(expense.id);
		refresh();
		toast({
			title: `Approved ${expense.merchant} — $${expense.amount.toFixed(2)}.`,
			variant: 'success',
		});
	};

	const openReject = (expense: Expense) => {
		dialogs.reject.value = expense;
	};
	const reject = async (expense: Expense, reason: string) => {
		await api.expenses.reject(expense.id, reason);
		dialogs.reject.value = null;
		refresh();
		toast({ title: `Rejected ${expense.merchant}.`, variant: 'success' });
	};

	const openSnooze = (expense: Expense) => {
		dialogs.snooze.value = expense;
	};
	const snooze = async (expense: Expense, until: string) => {
		await api.expenses.snooze(expense.id, until);
		dialogs.snooze.value = null;
		refresh();
		toast({ title: `${expense.merchant} snoozed.`, variant: 'success' });
	};

	const bulkApprove = async () => {
		const ids = table.selected.value as number[];
		await api.expenses.approveMany(ids);
		clearSelection();
		refresh();
		toast({ title: `${ids.length} expenses approved.`, variant: 'success' });
	};

	const openBulkReject = () => {
		dialogs.bulkReject.value = true;
	};
	const bulkReject = async (reason: string) => {
		const ids = table.selected.value as number[];
		const ok = await confirm({
			variant: 'destructive',
			title: 'Reject expenses',
			text: `Reject ${ids.length} expenses? The submitters are notified.`,
			yes: 'Reject',
			no: 'Cancel',
		});
		if (!ok) return;
		await api.expenses.rejectMany(ids, reason);
		dialogs.bulkReject.value = false;
		clearSelection();
		refresh();
		toast({ title: `${ids.length} expenses rejected.`, variant: 'success' });
	};

	// -- Keyboard-shortcut dispatch: same actions, resolved against the row
	// under the roving tabindex. Guarded exactly like `useDeleteCmd`.
	const keys = useMagicKeys();
	const withHighlighted = (run: (expense: Expense) => void) => {
		if (isInteractiveElementFocused()) return;
		if (
			dialogs.reject.value ||
			dialogs.bulkReject.value ||
			dialogs.snooze.value
		)
			return;
		const expense = highlightedExpense.value;
		if (expense) run(expense);
	};
	const approveHighlighted = () =>
		withHighlighted((expense) => void approve(expense));
	const rejectHighlighted = () => withHighlighted(openReject);
	const snoozeHighlighted = () => withHighlighted(openSnooze);

	whenever(keys['a'], approveHighlighted);
	whenever(keys['r'], rejectHighlighted);
	whenever(keys['s'], snoozeHighlighted);

	const ctx: ApprovalsInboxContext = {
		shell,
		table,
		filters,
		hasActiveFilters,
		tab,
		tabCounts,
		refreshKey,
		dialogs,
		highlightedExpense,
		fetchExpenses,
		stackExpense,
		stackSubmitter,
		clearFilters,
		approve,
		openReject,
		reject,
		openSnooze,
		snooze,
		bulkApprove,
		openBulkReject,
		bulkReject,
		approveHighlighted,
		rejectHighlighted,
		snoozeHighlighted,
	};
	provide(key, ctx);
	return ctx;
}

export function useApprovalsInbox(): ApprovalsInboxContext {
	const ctx = inject(key);
	if (!ctx)
		throw new Error('useApprovalsInbox() called outside ApprovalsInbox');
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- ApprovalsInbox/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left, page search right. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs
					class="min-w-0 flex-auto"
					:items="[
						{ key: 'dashboard', text: 'Dashboard', to: '/dashboard' },
						{ key: 'finance', text: 'Finance', to: '/finance' },
						{ key: 'approvals', text: 'Approvals' },
					]"
				/>
				<BbTextInput
					v-model="ctx.filters.search"
					autocomplete="off"
					class="shrink-0"
					clearable
					compact
					hide-label
					label="Search expenses"
					placeholder="Search merchant or submitter…"
					prepend:icon="lucide:search"
				/>
			</div>
		</template>

		<div class="flex flex-col gap-3 p-4">
			<FilterRail />

			<div class="flex items-center justify-between gap-2">
				<!-- Tabs as URL filters: counts come from the server on every fetch. -->
				<BbTabs
					v-model="ctx.tab.value"
					compact
					:items="[
						{
							key: 'needsApproval',
							label: `Needs approval · ${ctx.tabCounts.value.needsApproval}`,
							href: '?tab=needsApproval',
						},
						{
							key: 'approved',
							label: `Approved · ${ctx.tabCounts.value.approved}`,
							href: '?tab=approved',
						},
						{
							key: 'rejected',
							label: `Rejected · ${ctx.tabCounts.value.rejected}`,
							href: '?tab=rejected',
						},
						{
							key: 'all',
							label: `All · ${ctx.tabCounts.value.all}`,
							href: '?tab=all',
						},
					]"
				/>
				<ShortcutsHint />
			</div>

			<BbTable
				id="approvals-table"
				actions
				caption="Expense approvals"
				:columns="columns"
				compact
				:dependencies="[
					{ ...ctx.filters },
					ctx.tab.value,
					ctx.refreshKey.value,
				]"
				:deps-debounce-time="300"
				item-value="id"
				:items="ctx.fetchExpenses"
				keyboard-navigation
				legend="Select expenses"
				loading-text="Loading expenses…"
				:row-class="rowClass"
				selectable
			>
				<template #receipt="{ item }">
					<ReceiptThumbnail :expense="item" />
				</template>

				<template #merchant="{ content }">
					<span class="font-medium">{{ content }}</span>
				</template>

				<template #submitter_name="{ item }">
					<BbButton
						size="sm"
						variant="ghost"
						@click="() => ctx.stackSubmitter(item.submitter.id)"
					>
						{{ item.submitter.name }}
					</BbButton>
				</template>

				<template #category="{ item }">
					<BbBadge variant="outline">{{ item.category }}</BbBadge>
				</template>

				<template #status="{ item }">
					<BbBadge variant="outline">{{ statusLabel(item.status) }}</BbBadge>
				</template>

				<template #actions="{ item }">
					<RowActions :expense="item" />
				</template>

				<template #no-data>
					<div class="flex flex-col items-center gap-2 p-6 text-center">
						<p class="text-sm text-[color:var(--bb-text-muted)]">
							No expenses match
							{{
								ctx.hasActiveFilters.value ? 'the current filters' : 'this tab'
							}}.
						</p>
						<BbButton
							v-if="ctx.hasActiveFilters.value"
							variant="ghost"
							@click="ctx.clearFilters"
						>
							Clear filters
						</BbButton>
					</div>
				</template>
			</BbTable>

			<BbPagination table-id="approvals-table" />
		</div>

		<SelectionBar />

		<!-- Stacked peek sidebar: highlight opens the expense; names drill down. -->
		<template #sidebar>
			<ExpensePeek
				v-if="ctx.shell.current.value?.type === 'expense'"
				:expense-id="ctx.shell.current.value.id"
			/>
			<SubmitterPeek
				v-else-if="ctx.shell.current.value?.type === 'submitter'"
				:submitter-id="ctx.shell.current.value.id"
			/>
		</template>

		<template #dialogs>
			<RejectDialog />
			<BulkRejectDialog />
			<SnoozeDialog />
		</template>
	</PageShell>
</template>

<script setup lang="ts">
import {
	BbBadge,
	BbBreadcrumbs,
	BbButton,
	BbPagination,
	BbTable,
	BbTabs,
	BbTextInput,
} from 'bitboss-ui';
import PageShell from '@/components/layout/PageShell.vue';
import { provideApprovalsInbox } from './context';
import BulkRejectDialog from './BulkRejectDialog.vue';
import ExpensePeek from './ExpensePeek.vue';
import FilterRail from './FilterRail.vue';
import ReceiptThumbnail from './ReceiptThumbnail.vue';
import RejectDialog from './RejectDialog.vue';
import RowActions from './RowActions.vue';
import SelectionBar from './SelectionBar.vue';
import ShortcutsHint from './ShortcutsHint.vue';
import SnoozeDialog from './SnoozeDialog.vue';
import SubmitterPeek from './SubmitterPeek.vue';
import type { Expense, ExpenseStatus } from '@/types';

const ctx = provideApprovalsInbox();

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
const shortDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
	});
const statusLabel = (status: ExpenseStatus) =>
	({
		needsApproval: 'Needs approval',
		approved: 'Approved',
		rejected: 'Rejected',
		snoozed: 'Snoozed',
	})[status];

const columns = [
	{ key: 'receipt', label: 'Receipt', width: 48 },
	{ key: 'merchant', label: 'Merchant' },
	{ key: 'submitter.name', label: 'Submitter' },
	{ key: 'category', label: 'Category' },
	{
		key: 'amount',
		label: 'Amount',
		align: 'right' as const,
		formatter: (value: number) => currency.format(value),
	},
	{ key: 'submittedAt', label: 'Submitted', formatter: shortDate },
	{ key: 'status', label: 'Status' },
];

// A default highlight tint ships out of the box; row-class customizes it.
const rowClass = (item: Expense) =>
	ctx.table.highlighted.value === item.id
		? 'bg-indigo-50 dark:bg-indigo-950/20'
		: undefined;
</script>
```

### FilterRail.vue

```vue
<!-- ApprovalsInbox/FilterRail.vue -->
<template>
	<div class="flex flex-wrap items-center gap-2">
		<!-- Submitter: single, query-aware search against the API. -->
		<BbSelectPopover
			v-model="ctx.filters.submitterId"
			item-text="name"
			item-value="id"
			:items="searchSubmitters"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filter by submitter"
					append:icon="lucide:chevron-down"
					size="sm"
					variant="outline"
				>
					{{ submitterLabel }}
				</BbButton>
			</template>
		</BbSelectPopover>

		<!-- Category: multi-select pill. -->
		<BbSelectPopover
			v-model="ctx.filters.categories"
			:items="['travel', 'meals', 'software', 'office', 'client', 'other']"
			multiple
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filter by category"
					append:icon="lucide:chevron-down"
					size="sm"
					variant="outline"
				>
					Category{{
						ctx.filters.categories.length
							? ` · ${ctx.filters.categories.length}`
							: ''
					}}
				</BbButton>
			</template>
		</BbSelectPopover>

		<!-- Amount over: a quick-filter pill from preset thresholds. -->
		<BbSelectPopover
			v-model="ctx.filters.amountOver"
			disable-writing
			:items="[50, 100, 250, 500, 1000]"
			width="160px"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filter by amount"
					append:icon="lucide:chevron-down"
					size="sm"
					variant="outline"
				>
					{{
						ctx.filters.amountOver
							? `Over $${ctx.filters.amountOver}`
							: 'Amount'
					}}
				</BbButton>
			</template>
		</BbSelectPopover>

		<!-- Clear-all renders only while something is active. -->
		<BbButton
			v-if="ctx.hasActiveFilters.value"
			class="ml-auto"
			prepend:icon="lucide:x"
			size="sm"
			variant="ghost"
			@click="ctx.clearFilters"
		>
			Clear filters
		</BbButton>
	</div>
</template>

<script setup lang="ts">
import { computed, ref, watchEffect } from 'vue';
import { BbButton, BbSelectPopover } from 'bitboss-ui';
import { useApprovalsInbox } from './context';
import { api } from '@/api';
import type { Submitter } from '@/types';

const ctx = useApprovalsInbox();

const searchSubmitters = (query: string): Promise<Submitter[]> =>
	api.submitters.list({ search: query });

// The trigger labels itself from page state (a standalone popover with a
// seeded model stays lazy and has no resolvable `text` before first open).
const selectedSubmitter = ref<Submitter | null>(null);
watchEffect(async () => {
	selectedSubmitter.value =
		ctx.filters.submitterId == null
			? null
			: await api.submitters.get(ctx.filters.submitterId);
});
const submitterLabel = computed(
	() => selectedSubmitter.value?.name ?? 'Submitter'
);
</script>
```

### ShortcutsHint.vue

```vue
<!-- ApprovalsInbox/ShortcutsHint.vue -->
<template>
	<div class="flex items-center gap-1">
		<span class="mr-1 text-xs text-[color:var(--bb-text-muted)]"
			>Shortcuts</span
		>
		<BbTooltip>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Approve highlighted expense"
					:disabled="!ctx.highlightedExpense.value"
					icon="lucide:check"
					size="xs"
					variant="ghost"
					@click="ctx.approveHighlighted"
				/>
			</template>
			<span class="flex items-center gap-1.5">
				Approve
				<kbd
					class="rounded border border-current px-1 font-mono text-[10px] leading-4 opacity-75"
					>A</kbd
				>
			</span>
		</BbTooltip>
		<BbTooltip>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Reject highlighted expense"
					:disabled="!ctx.highlightedExpense.value"
					icon="lucide:x"
					size="xs"
					variant="ghost"
					@click="ctx.rejectHighlighted"
				/>
			</template>
			<span class="flex items-center gap-1.5">
				Reject
				<kbd
					class="rounded border border-current px-1 font-mono text-[10px] leading-4 opacity-75"
					>R</kbd
				>
			</span>
		</BbTooltip>
		<BbTooltip>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Snooze highlighted expense"
					:disabled="!ctx.highlightedExpense.value"
					icon="lucide:clock"
					size="xs"
					variant="ghost"
					@click="ctx.snoozeHighlighted"
				/>
			</template>
			<span class="flex items-center gap-1.5">
				Snooze
				<kbd
					class="rounded border border-current px-1 font-mono text-[10px] leading-4 opacity-75"
					>S</kbd
				>
			</span>
		</BbTooltip>
	</div>
</template>

<script setup lang="ts">
import { BbButton, BbTooltip } from 'bitboss-ui';
import { useApprovalsInbox } from './context';

const ctx = useApprovalsInbox();
</script>
```

### ReceiptThumbnail.vue

```vue
<!-- ApprovalsInbox/ReceiptThumbnail.vue -->
<template>
	<img
		v-if="expense.receiptUrl"
		:alt="`Receipt from ${expense.merchant}`"
		class="h-8 w-8 rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] object-cover"
		:src="expense.receiptUrl"
	/>
	<div
		v-else
		aria-hidden="true"
		class="flex h-8 w-8 items-center justify-center rounded-[var(--bb-radius)] border border-dashed border-[color:var(--bb-border)] text-[color:var(--bb-text-muted)]"
	>
		<BbIcon icon="lucide:receipt" size="14" />
	</div>
</template>

<script setup lang="ts">
import { BbIcon } from 'bitboss-ui';
import type { Expense } from '@/types';

defineProps<{ expense: Expense }>();
</script>
```

### RowActions.vue

```vue
<!-- ApprovalsInbox/RowActions.vue -->
<template>
	<div class="flex items-center gap-1">
		<BbTooltip text="Approve">
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Approve"
					:disabled="resolved"
					icon="lucide:check"
					size="xs"
					variant="ghost"
					@click="() => ctx.approve(expense)"
				/>
			</template>
		</BbTooltip>
		<BbTooltip text="Reject">
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Reject"
					:disabled="resolved"
					icon="lucide:x"
					size="xs"
					variant="ghost"
					@click="() => ctx.openReject(expense)"
				/>
			</template>
		</BbTooltip>
		<BbTooltip text="Snooze">
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Snooze"
					:disabled="resolved"
					icon="lucide:clock"
					size="xs"
					variant="ghost"
					@click="() => ctx.openSnooze(expense)"
				/>
			</template>
		</BbTooltip>
	</div>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbTooltip } from 'bitboss-ui';
import { useApprovalsInbox } from './context';
import type { Expense } from '@/types';

const props = defineProps<{ expense: Expense }>();

const ctx = useApprovalsInbox();

const resolved = computed(
	() =>
		props.expense.status === 'approved' || props.expense.status === 'rejected'
);
</script>
```

### RejectDialog.vue

```vue
<!-- ApprovalsInbox/RejectDialog.vue -->
<template>
	<BbDialog
		:model-value="expense !== null"
		size="sm"
		:title="expense ? `Reject — ${expense.merchant}` : ''"
		@show="reason = ''"
		@update:model-value="close"
	>
		<form
			v-if="expense"
			class="flex flex-col gap-3"
			novalidate
			@submit.prevent="submit"
		>
			<BbTextarea
				v-model="reason"
				label="Reason"
				label-mode="outside"
				placeholder="Why is this expense being rejected?"
				rows="3"
			/>
			<div class="mt-1 flex justify-end gap-2">
				<BbButton type="button" variant="ghost" @click="close">Cancel</BbButton>
				<BbButton
					:disabled="reason.trim().length < 3"
					type="submit"
					variant="destructive"
				>
					Reject expense
				</BbButton>
			</div>
		</form>
	</BbDialog>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbButton, BbDialog, BbTextarea } from 'bitboss-ui';
import { useApprovalsInbox } from './context';

const ctx = useApprovalsInbox();

// The dialog's subject lives in the page context — the row action and the
// peek's reject button both just assign it.
const expense = computed(() => ctx.dialogs.reject.value);
const close = () => {
	ctx.dialogs.reject.value = null;
};

const reason = ref('');
const submit = () =>
	expense.value ? ctx.reject(expense.value, reason.value.trim()) : undefined;
</script>
```

### BulkRejectDialog.vue

```vue
<!-- ApprovalsInbox/BulkRejectDialog.vue -->
<template>
	<BbDialog
		:model-value="ctx.dialogs.bulkReject.value"
		size="sm"
		:title="`Reject ${count} expenses`"
		@show="reason = ''"
		@update:model-value="close"
	>
		<form class="flex flex-col gap-3" novalidate @submit.prevent="submit">
			<BbTextarea
				v-model="reason"
				label="Reason"
				label-mode="outside"
				placeholder="Applied to every selected expense."
				rows="3"
			/>
			<div class="mt-1 flex justify-end gap-2">
				<BbButton type="button" variant="ghost" @click="close">Cancel</BbButton>
				<BbButton
					:disabled="reason.trim().length < 3"
					type="submit"
					variant="destructive"
				>
					Reject {{ count }} expenses
				</BbButton>
			</div>
		</form>
	</BbDialog>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbButton, BbDialog, BbTextarea } from 'bitboss-ui';
import { useApprovalsInbox } from './context';

const ctx = useApprovalsInbox();

const count = computed(() => (ctx.table.selected.value as number[]).length);
const close = () => {
	ctx.dialogs.bulkReject.value = false;
};

const reason = ref('');
const submit = () => ctx.bulkReject(reason.value.trim());
</script>
```

### SnoozeDialog.vue

```vue
<!-- ApprovalsInbox/SnoozeDialog.vue -->
<template>
	<BbDialog
		:model-value="expense !== null"
		size="xs"
		:title="expense ? `Snooze — ${expense.merchant}` : ''"
		@show="until = tomorrow"
		@update:model-value="close"
	>
		<form
			v-if="expense"
			class="flex flex-col gap-3"
			novalidate
			@submit.prevent="submit"
		>
			<BbDatePickerInput
				v-model="until"
				floating
				label="Snooze until"
				label-mode="outside"
				:min="tomorrow"
			/>
			<div class="mt-1 flex justify-end gap-2">
				<BbButton type="button" variant="ghost" @click="close">Cancel</BbButton>
				<BbButton type="submit" variant="secondary">Snooze</BbButton>
			</div>
		</form>
	</BbDialog>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbButton, BbDatePickerInput, BbDialog } from 'bitboss-ui';
import { useApprovalsInbox } from './context';

const ctx = useApprovalsInbox();

const expense = computed(() => ctx.dialogs.snooze.value);
const close = () => {
	ctx.dialogs.snooze.value = null;
};

const tomorrow = new Date(Date.now() + 86_400_000).toISOString().slice(0, 10);
const until = ref(tomorrow);
const submit = () =>
	expense.value ? ctx.snooze(expense.value, until.value) : undefined;
</script>
```

### SelectionBar.vue

```vue
<!-- ApprovalsInbox/SelectionBar.vue -->
<template>
	<FloatingBottomPanel :open="selectedCount > 0">
		<span class="px-2 text-sm">{{ selectedCount }} selected</span>
		<BbButton
			prepend:icon="lucide:check"
			size="sm"
			variant="ghost"
			@click="ctx.bulkApprove"
		>
			Approve
		</BbButton>
		<div class="floating-bottom-panel__right flex items-center gap-1">
			<BbButton size="sm" variant="destructive" @click="ctx.openBulkReject">
				Reject
			</BbButton>
			<BbButton
				aria-label="Clear selection"
				icon="lucide:x"
				size="sm"
				variant="ghost"
				@click="clearSelection"
			/>
		</div>
	</FloatingBottomPanel>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton } from 'bitboss-ui';
import FloatingBottomPanel from '@/components/layout/FloatingBottomPanel.vue';
import { useApprovalsInbox } from './context';

const ctx = useApprovalsInbox();

const selectedCount = computed(() => ctx.table.selected.value?.length ?? 0);
const clearSelection = () => {
	ctx.table.selected.value = [];
};
</script>
```

### ExpensePeek.vue

```vue
<!-- ApprovalsInbox/ExpensePeek.vue -->
<template>
	<div v-if="expense" class="flex flex-col gap-4 text-sm">
		<!-- Header: identity + amount + status. -->
		<header class="flex flex-col gap-1.5">
			<div class="flex items-center justify-between gap-2">
				<h2 class="text-base font-semibold">{{ expense.merchant }}</h2>
				<BbBadge variant="outline">{{ statusLabel(expense.status) }}</BbBadge>
			</div>
			<p class="text-xl font-semibold">{{ currency.format(expense.amount) }}</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Submitted {{ longDate(expense.submittedAt) }}
			</p>
		</header>

		<!-- Receipt: bigger than the row thumbnail, with a full-size link out. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Receipt
			</h3>
			<img
				v-if="expense.receiptUrl"
				:alt="`Receipt from ${expense.merchant}`"
				class="h-40 w-full rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] object-cover"
				:src="expense.receiptUrl"
			/>
			<p v-else class="text-xs text-[color:var(--bb-text-muted)]">
				No receipt attached.
			</p>
			<BbButton
				v-if="expense.receiptUrl"
				append:icon="lucide:arrow-up-right"
				:href="expense.receiptUrl"
				size="sm"
				target="_blank"
				variant="ghost"
			>
				View full-size receipt
			</BbButton>
		</section>

		<!-- Properties: submitter name drills DOWN — stacked peek, back arrow. -->
		<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
			<dt class="text-[color:var(--bb-text-muted)]">Submitter</dt>
			<dd>
				<!-- A person's NAME is an identity cell: an inline link, never a
				     padded button (BTG-015 / agent-contract § Inline Links). -->
				<BbBaseButton
					class="plain-link"
					@click="() => ctx.stackSubmitter(expense!.submitter.id)"
				>
					{{ expense.submitter.name }}
				</BbBaseButton>
			</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Category</dt>
			<dd class="capitalize">{{ expense.category }}</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Memo</dt>
			<dd>{{ expense.memo ?? '—' }}</dd>
		</dl>

		<!-- Activity feed. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Activity
			</h3>
			<ul class="flex flex-col gap-2">
				<li
					v-for="entry in expense.activity"
					:key="entry.id"
					class="flex gap-2"
				>
					<BbIcon
						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
						:icon="entry.icon"
						size="14"
					/>
					<div class="flex flex-col">
						<span>{{ entry.text }}</span>
						<span class="text-xs text-[color:var(--bb-text-muted)]"
							>{{ entry.actor }} · {{ longDate(entry.at) }}</span
						>
					</div>
				</li>
			</ul>
		</section>

		<!-- Peek is a workbench: the same three actions as the row, plus the real page. -->
		<footer class="mt-2 flex flex-wrap items-center gap-2 border-t pt-3">
			<BbButton
				:disabled="resolved"
				prepend:icon="lucide:check"
				size="sm"
				variant="secondary"
				@click="() => ctx.approve(expense!)"
			>
				Approve
			</BbButton>
			<BbButton
				:disabled="resolved"
				prepend:icon="lucide:x"
				size="sm"
				variant="destructive"
				@click="() => ctx.openReject(expense!)"
			>
				Reject
			</BbButton>
			<BbButton
				:disabled="resolved"
				prepend:icon="lucide:clock"
				size="sm"
				variant="outline"
				@click="() => ctx.openSnooze(expense!)"
			>
				Snooze
			</BbButton>
			<BbButton
				append:icon="lucide:arrow-up-right"
				class="ml-auto"
				size="sm"
				:to="`/expenses/${expense.id}`"
				variant="ghost"
			>
				Open full expense
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { computed, ref, watchEffect } from 'vue';
import { BbBadge, BbBaseButton, BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
import { useApprovalsInbox } from './context';
import { api } from '@/api';
import type { ExpenseDetail, ExpenseStatus } from '@/types';

const props = defineProps<{ expenseId: number }>();

const ctx = useApprovalsInbox();

// Re-fetches whenever the stack shows a different expense; refreshKey makes
// approve/reject/snooze reflect here immediately.
const expense = ref<ExpenseDetail | null>(null);
watchEffect(async () => {
	void ctx.refreshKey.value;
	expense.value = await api.expenses.get(props.expenseId);
});

const resolved = computed(
	() =>
		expense.value?.status === 'approved' || expense.value?.status === 'rejected'
);

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
const longDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
		year: 'numeric',
	});
const statusLabel = (status: ExpenseStatus) =>
	({
		needsApproval: 'Needs approval',
		approved: 'Approved',
		rejected: 'Rejected',
		snoozed: 'Snoozed',
	})[status];
</script>
```

### SubmitterPeek.vue

```vue
<!-- ApprovalsInbox/SubmitterPeek.vue -->
<template>
	<div v-if="submitter" class="flex flex-col gap-4 text-sm">
		<header class="flex items-center gap-3">
			<BbAvatar :alt="submitter.name" :src="submitter.avatarUrl" />
			<div class="flex flex-col">
				<h2 class="text-base font-semibold">{{ submitter.name }}</h2>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					{{ submitter.email }} · {{ submitter.team }}
				</p>
			</div>
		</header>

		<!-- Stat strip. -->
		<div class="grid grid-cols-3 gap-2">
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Submitted (YTD)</p>
				<p class="font-semibold">
					{{ currency.format(submitter.totalSubmitted) }}
				</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Pending</p>
				<p class="font-semibold">{{ submitter.pendingCount }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Approval rate</p>
				<p class="font-semibold">{{ submitter.approvalRate }}%</p>
			</div>
		</div>

		<!-- Recent expenses: names drill down again — the stack keeps growing. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Recent expenses
			</h3>
			<ul class="flex flex-col">
				<li
					v-for="recent in submitter.recentExpenses"
					:key="recent.id"
					class="flex items-center justify-between gap-2 border-b py-1.5 last:border-b-0"
				>
					<BbBaseButton
						class="plain-link"
						@click="() => ctx.stackExpense(recent.id)"
					>
						{{ recent.merchant }}
					</BbBaseButton>
					<BbBadge variant="outline">{{ recent.status }}</BbBadge>
					<span class="text-xs text-[color:var(--bb-text-muted)]">{{
						currency.format(recent.amount)
					}}</span>
				</li>
			</ul>
		</section>

		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				append:icon="lucide:arrow-up-right"
				size="sm"
				:to="`/people/${submitter.id}`"
				variant="ghost"
			>
				Open profile
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { ref, watchEffect } from 'vue';
import {
	BbAvatar,
	BbBadge,
	BbBaseButton,
	BbButton,
	BbSpinner,
} from 'bitboss-ui';
import { useApprovalsInbox } from './context';
import { api } from '@/api';
import type { SubmitterDetail } from '@/types';

const props = defineProps<{ submitterId: number }>();

const ctx = useApprovalsInbox();

const submitter = ref<SubmitterDetail | null>(null);
watchEffect(async () => {
	submitter.value = await api.submitters.getDetail(props.submitterId);
});

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
</script>
```

## Why it is built this way

- **The context coopts, leaves consume.** `shell` and `table` are joined
  once in `provideApprovalsInbox()`; twelve components share filters,
  selection, highlight, the peek stack, the keyboard shortcuts and every
  action through one `useApprovalsInbox()` call.
- **Highlight is the trigger, not a bespoke click handler.** Per the
  `BbTable` guide, `highlighted` is "a parallel, UI-intent state…
  independent of selection" that ships unstyled — this recipe is exactly
  the case the guide's Row Highlight section describes: a `watch` on
  `table.highlighted` is the entire wiring between "arrow to a row" and
  "the peek is open", and `keyboard-navigation`'s Enter/Space "activate…
  through the same path as a mouse click" means the mouse and the keyboard
  share one code path for free.
- **`item-value="id"`** is what lets `table.highlighted` (and
  `table.selected`) hold plain ids instead of whole objects — the keyboard
  handler and the peek both resolve the full `Expense` from a small
  `lastItems` cache populated by `fetchExpenses`, never from the table's
  internal row wrapper.
- **One dispatch path per action, three entry points.** `approve`,
  `openReject` and `openSnooze` are called identically from `RowActions`,
  `ExpensePeek`'s footer, and the `A`/`R`/`S` keyboard handlers
  (`approveHighlighted` etc. are the same functions, resolved against
  `highlightedExpense` instead of a row prop) — there is exactly one place
  each action's API call, refresh and toast live.
- **Reason and date are dialogs, not confirms.** Per the pattern catalog
  (§6.2), "anything needing input opens a `BbDialog`" — reject needs a
  typed reason, snooze needs a date, so both get a small dialog whose
  open-state is the subject itself (`ctx.dialogs.reject` holds the
  `Expense`, not a boolean), exactly like the flagship's
  `RecordPaymentDialog`. Bulk reject is destructive **and** needs input,
  so it layers a `useConfirm` on top of the dialog's own submit.
- **The shortcut guard mirrors `useDeleteCmd`.** `isInteractiveElementFocused()`
  is copied verbatim from the Inertia Helpers guide's `useDeleteCmd` (which
  the guide notes "works on any platform") so typing a rejection reason
  never fires `R`; the handler also bails while any dialog is open.
- **`peekX` vs `stackX` is the whole stack grammar**, unchanged from the
  flagship: highlighting always **replaces** (`peekExpense`, `true`),
  clicking a submitter's name always **pushes** (`stackSubmitter`), and the
  shell renders the back arrow once depth > 1 — from a row, from inside
  the expense peek, or drilling back from the submitter peek's own recent
  expenses.
- **Sizing:** topbar and rail follow `md`-first; `sm`/`xs` appear exactly
  where the doctrine allows — table rows (`xs`, the densest surface), the
  shortcut bar (`xs`), the peek footers and the bulk bar (`sm`).
- **No `variant="primary"` on this page.** Triage has no "create" action —
  the one-primary-action rule is satisfied vacuously; every action here is
  either a one-click mutation, a gated mutation via dialog, or navigation.

## Variations

- **No snooze**: drop `SnoozeDialog.vue`, the `S` shortcut, and the
  `snoozed` tab state — the remaining approve/reject pair still clears the
  ≥ 12 action bar on its own via the bulk/keyboard/peek spread.
- **Auto-advance after action**: after `approve`/`reject` resolves, call
  `table.highlighted.value = nextExpenseId` (the id following the acted-on
  row in `lastItems`) so triage keeps moving without a re-highlight —
  the classic "Superhuman" flow.
- **Per-category routing**: seed `filters.categories` from a saved view
  per approver role (a store-backed default) instead of starting empty.

---

<!-- dist/ai/recipes/vue/command-palette.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/vue/command-palette.md -->

# Recipe: Command Palette (Vue)

`BbCommand` does not exist — the [component picker](../../guides/component-picker.md)
says to compose `BbDialog` + `BbSelectPopover`, and this recipe is that
composition, worked end to end: a `⌘K`/`Ctrl+K` shortcut (plus an optional
visible topbar trigger) opens a dialog; inside it, `BbSelectPopover`'s
search-and-pick engine — debouncing, race protection, grouping — drives a
single query against your backend and returns **grouped** results (Pages,
Records, Actions, or whatever taxonomy fits your app). Picking a result
navigates and closes the palette. No new component ships anywhere in this
recipe — it is `BbDialog` and `BbSelectPopover`'s existing engine, wired.

Sibling recipes: [Nuxt](../nuxt/command-palette.md) ·
[Inertia](../inertia/command-palette.md).

## Prerequisites

- `<BbConfirm />` and `<BbToast />` mounted once in the app root (`App.vue`) —
  never in a page. `CommandPalette.vue` (below) mounts the same way, once, in
  the same root — the shortcut must work from every page, not just ones that
  remember to render it.
- A backend search endpoint that returns **grouped** results — this recipe
  assumes `GET /search?q=…` responding
  `{ pages: Result[], records: Result[], actions: Result[] }` where each
  `Result` is `{ id, title, subtitle?, href, icon }`. Shape it to your own
  taxonomy; only the "grouped array of navigable rows" contract matters below.

## Key ideas

- **`BbSelectPopover` is the documented tool for this.** Its own guide says
  outright: "It is the right tool for command-palette and inline-edit
  patterns." This recipe does not fight that — it gives the popover a real,
  on-screen activator inside a dialog, not a hidden one.
- **The activator must be real and visible, never `sr-only`.** `BbSelectPopover`
  closes itself when its activator's intersection ratio drops below 1 (it
  assumes an off-screen/invisible trigger means "the anchor scrolled away, so
  close"). A hidden activator forced open programmatically opens and then
  immediately auto-closes — a broken pattern worth naming so nobody reaches
  for it. This recipe's activator is a normal, painted search button sitting
  inside the open dialog, so its intersection ratio is always 1.
- **`BbSelectPopover` has no imperative `ref.open()`** (its `defineExpose` is
  empty) — the only way to open it from outside its own activator slot is a
  real DOM interaction on that activator. So the dialog's `@shown` handler
  (fires after the native `showModal()` call and initial focus — later than
  `@show`, so the trigger is guaranteed painted) calls `.click()` on our own
  template ref to the trigger button. This is not a workaround; it is how the
  popover is designed to be opened.
- **A fresh popover instance every open.** `BbSelectPopover` keeps its typed
  query and open state internally with no external reset hook. Keying the
  popover on an integer that increments on `@show` remounts it cleanly each
  time the palette opens, so a stale query from the last search never
  reappears.
- **`prefill: false`** makes the provider **search-first**: nothing loads on
  open, and the panel shows a "type to search" hint until the first
  keystroke — exactly right for a palette where browsing the full result set
  makes no sense. Debouncing (default 500ms), race protection and loading
  state are the popover's built-in guarantees; this recipe does not
  re-implement any of them.
- **Options here have no `href`/`to`.** Unlike `BbDropdown` (or `BbButton`),
  `BbSelectPopover`'s options are picked, not linked — there is no
  navigation prop to reach for. Picking updates `v-model` with the chosen
  `href`, and the `update:model-value` handler is where navigation actually
  happens — the one place in this recipe a click handler drives routing
  instead of a `to`/`href` prop, and it is the only place that could.
- **A shared `open` ref, not a prop.** `useCommandPalette()` is a tiny
  module-level singleton so both the `⌘K` shortcut and an optional visible
  topbar "Search" button flip the same state — see
  [Layout Scaffold](./layout-scaffold.md#topbar-value-pickers-account-menu-theme-warehouse)
  for the account-menu neighbourhood this typically sits in.

## The code

### `src/composables/useCommandPalette.ts`

```ts
// src/composables/useCommandPalette.ts
import { ref } from 'vue';

// Module-level singleton: one palette per app. The `⌘K` shortcut and any
// visible "Search" trigger (topbar button, empty-state CTA, …) all flip this
// same ref instead of each owning their own boolean.
const open = ref(false);

export function useCommandPalette() {
	return { open };
}
```

### `src/components/CommandPalette.vue`

```vue
<!-- CommandPalette.vue — mount once in App.vue, alongside BbConfirm/BbToast -->
<template>
	<BbDialog v-model="open" size="lg" title="Search" @shown="onShown">
		<BbSelectPopover
			:key="instance"
			:adaptive="false"
			group-by="group"
			item-text="title"
			item-value="href"
			:items="search"
			:model-value="null"
			no-data-text="No results."
			placement="bottom-start"
			:prefill="false"
			width="100%"
			@update:model-value="onPick"
		>
			<template #activator="{ props }">
				<!-- The real, painted activator — see "Key ideas" for why it must
				     be visible, not `sr-only`. -->
				<button
					ref="triggerRef"
					v-bind="props"
					class="command-palette__trigger"
					type="button"
				>
					<BbIcon icon="lucide:search" />
					<span>Type to search…</span>
				</button>
			</template>

			<template #option="{ item }">
				<div class="command-palette__option">
					<BbIcon :icon="item.icon" />
					<div class="flex min-w-0 flex-col">
						<span class="truncate">{{ item.title }}</span>
						<span
							v-if="item.subtitle"
							class="truncate text-xs text-[color:var(--bb-text-muted)]"
						>
							{{ item.subtitle }}
						</span>
					</div>
				</div>
			</template>

			<template #no-data="{ query }">
				<p class="p-3 text-sm text-[color:var(--bb-text-muted)]">
					{{ query ? `No results for "${query}".` : 'Type to search.' }}
				</p>
			</template>
		</BbSelectPopover>
	</BbDialog>
</template>

<script setup lang="ts">
import { nextTick, ref } from 'vue';
import { useMagicKeys, whenever } from '@vueuse/core';
import { useRouter } from 'vue-router';
import { BbDialog, BbIcon, BbSelectPopover } from 'bitboss-ui';
import { useCommandPalette } from '@/composables/useCommandPalette';

interface Result {
	id: string;
	title: string;
	subtitle?: string;
	href: string;
	icon: string;
	group: 'Pages' | 'Records' | 'Actions';
}

const { open } = useCommandPalette();
const router = useRouter();

// `⌘K` on Mac, `Ctrl+K` elsewhere; `preventDefault` stops the browser's own
// address-bar shortcut (Firefox/Edge) from firing alongside ours.
const keys = useMagicKeys({
	passive: false,
	onEventFired(event) {
		if (event.key === 'k' && (event.metaKey || event.ctrlKey)) {
			event.preventDefault();
		}
	},
});
whenever(keys['cmd+k'], () => (open.value = true));
whenever(keys['ctrl+k'], () => (open.value = true));

// Remounting the popover on every open (see "Key ideas") clears its typed
// query and closed state without hand-rolling a reset API it doesn't expose.
const instance = ref(0);
const triggerRef = ref<HTMLButtonElement>();
const onShown = () => {
	instance.value++;
	void nextTick(() => triggerRef.value?.click());
};

const search = async (query: string): Promise<Result[]> => {
	if (query.trim() === '') return [];
	const data: { pages: Result[]; records: Result[]; actions: Result[] } =
		await fetch(`/search?q=${encodeURIComponent(query)}`).then((res) =>
			res.json()
		);
	return [
		...data.pages.map((r) => ({ ...r, group: 'Pages' as const })),
		...data.records.map((r) => ({ ...r, group: 'Records' as const })),
		...data.actions.map((r) => ({ ...r, group: 'Actions' as const })),
	];
};

// The one place this recipe navigates from a handler instead of `to`/`href`
// — see "Key ideas": select options carry no navigation prop.
const onPick = (href: string | null) => {
	if (href == null) return;
	open.value = false;
	void router.push(href);
};
</script>

<style scoped>
.command-palette__trigger {
	align-items: center;
	background: var(--bb-panel);
	border: 1px solid var(--bb-border);
	border-radius: var(--bb-radius);
	color: var(--bb-text-muted);
	display: flex;
	gap: 0.5rem;
	padding: 0.5rem 0.75rem;
	width: 100%;
}

.command-palette__option {
	align-items: center;
	display: flex;
	gap: 0.5rem;
	min-width: 0;
}
</style>
```

### An optional visible trigger, anywhere

Any button can open the same palette without touching the shortcut logic —
this is the button that replaces "a top-bar link to `/search`":

```vue
<script setup lang="ts">
import { BbButton } from 'bitboss-ui';
import { useCommandPalette } from '@/composables/useCommandPalette';

const { open } = useCommandPalette();
</script>

<template>
	<BbButton
		aria-label="Search (⌘K)"
		icon="lucide:search"
		size="sm"
		variant="ghost"
		@click="open = true"
	/>
</template>
```

## Why it is built this way

- **The popover's own guide already names this use case** — reaching for
  `BbSelectPopover` here is not a stretch of its design, it is the
  documented one.
- **Visibility, not exposed imperative methods, is what opens the panel.**
  `BbSelectPopover` deliberately exposes nothing on its component ref; the
  only supported way in is a real interaction on the activator you rendered.
  Clicking a real, on-screen `triggerRef` from `@shown` **is** that
  interaction, not a bypass of it.
- **`@shown`, not `@show`.** `@show` fires the instant the model flips to
  `true`, before the dialog's native `showModal()` call and before the
  trigger is guaranteed painted; `@shown` fires after both, so the
  programmatic click always lands on a real, visible element.
- **Grouping is server-shaped, not client-invented.** `group-by="group"`
  buckets the flattened response exactly the way `BbSelect`'s "Group
  options" playbook describes — no bespoke section-rendering markup.

## Gotchas

- **Escape inside the search field closes the popover, not the dialog.**
  The search input's own `keydown.esc` handler stops propagation, so the
  first `Escape` clears/closes the panel and a second one closes the dialog.
  This mirrors most native command palettes (clear query, then dismiss) —
  do not "fix" it by removing the popover's own Escape handling.
- **`fetch('/search?q=…')` is a placeholder route.** Swap it for your app's
  real search endpoint; keep the grouped-array response shape or adjust
  `group-by`/`item-text`/`item-value` to match your own.
- **Do not read `text`/`selectedOptions` for the trigger label.** This
  recipe's trigger is static ("Type to search…") on purpose — a command
  palette's activator never needs to reflect a "current selection" the way a
  filter pill does.
- **`BbSelectPopover` has no `placeholder` prop.** The search field only
  carries an accessible name (from `config.locale`) — there is no visible
  placeholder text to set. The trigger's own "Type to search…" label is
  what carries that instruction, not a prop on the popover.
  </content>

---

<!-- dist/ai/recipes/vue/inline-edit-workspace.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/vue/inline-edit-workspace.md -->

# Recipe: Inline-Edit Workspace (Vue)

The flagship of pattern **§6.8 — autosave cells**: a Linear-grade sprint
backlog for a **plain Vue SPA with vue-router** where **every cell persists
itself and the page has no Save button anywhere**. Change a status, retype a
title, clear an estimate — it is already saved, or it has already rolled back
and told you.

Sibling recipes: [Nuxt](../nuxt/inline-edit-workspace.md) ·
[Inertia](../inertia/inline-edit-workspace.md).

Domain: **Sprint 24** of a product team — fourteen issues (`BB-227` …
`BB-241`), four statuses, three priorities, a six-member team (Sofia Reyes,
Jonah Weiss, Priya Natarajan, Tom Okafor, Elif Demir, Marco Bianchi).
Deliberately distinct from the invoices/members/expenses of the sibling
recipes.

## Prerequisites

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell`, `usePageShellContext` and `FloatingBottomPanel` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
  Components: [BbTable](../../BbTable.md) ·
  [BbSelectPopover](../../BbSelectPopover.md) (§ One popover per table row is
  load-bearing here) · [BbBadge](../../BbBadge.md) (the `loading` /
  `append:icon` interplay).

Guides: [Inline Edit Playbook](../../guides/inline-edit-playbook.md) (who owns
the edit — this page is the autosave answer) ·
[Design language](../../guides/design-language.md) (§ Using color, § Badges
label state) · [Page Shell](../../guides/page-shell.md) ·
[Floating Bottom Panel](../../guides/floating-bottom-panel.md).

## Key ideas

- **No Save button anywhere.** Every cell commits itself through one context
  action, `persistField(issue, key, value)` — optimistic write, single-field
  PATCH, refetch; failure rolls back just that field and toasts. Nothing on
  the page is ever "changed but unsaved", so there is no dirty ring and no
  dirty-gated button — the only transient state is _saving_, and the spinner
  carries it.
- **The optimistic overlay is page state, not cell state.** `pending` maps
  `issue.id → { field: value }` on **rung 3** of the state ladder: the grid
  cells, the peek workbench _and the fetch itself_ all read it. This is the
  deliberate contrast with the one-shot §6.1 status cell (see
  `records-workspace`), whose `saving` flag is a rung-1 local ref — in an
  autosave grid the fetch must also know what is in flight, so the flag
  cannot live inside a cell.
- **The overlay is retired in the fetch, never when a save resolves** — and
  only for fields the response actually confirms. Retiring on save-resolve
  makes the cell flash new → old → new for the whole reload, because the
  table still holds the stale row until the refetch lands.
- **Typed inputs commit on `@change` (blur/Enter), never `v-model`.** A
  `v-model` autosave is one request per keystroke. Pickers commit on pick —
  the click already _is_ the commit.
- **One coopting page context.** `provideBacklogWorkspace()` joins the
  page-shell stack and the table context once, owns filters/tab/overlay, and
  exposes complete actions. Eleven components share everything through one
  `useBacklogWorkspace()` call — zero prop drilling.
- **Options resolve once, at page level.** Status and priority are static
  module-level catalogs (fifty rows, zero requests); the assignee picker
  shares **one** query provider across every row, so unopened rows cost
  nothing.
- **Status is color, per the soft palette.** The registered `soft-*` badge
  variants label the closed status/priority sets; the internal trailing
  chevron says "clickable", and the badge's `loading` swaps the spinner into
  the chevron's place while that one field saves.
- **Buttons are `md` by default**; `sm` appears only in row actions, the
  filter pills, the peek footer and the bulk bar.

- **Spread the filters object into `dependencies`.** `BbTable` hash-compares
  `dependencies`; it does not deep-watch them. Passing the reactive `filters`
  proxy itself tracks only its identity — which never changes — so the table
  never refetches. `{ ...ctx.filters }` reads every field during render, so any
  field change yields a new, differently-hashed array. Read `.value` off the
  refs for the same reason: context members are not auto-unwrapped in a template.

## Page anatomy

```
BacklogWorkspace/
	Index.vue               ← assembly: PageShell slots, table, tabs, pagination
	context.ts              ← coopts shell + table ctx; owns filters + the pending overlay + persistField
	FilterRail.vue          ← status / priority / assignee filter pills + clear-all
	EditableTitleCell.vue   ← commit-on-blur text (@change, never v-model)
	EstimateCell.vue        ← commit-on-change number cell
	StatusCell.vue          ← editable soft badge (chevron at rest, spinner in flight)
	PriorityCell.vue        ← same grammar, its own leaf (§6.3: never one EditableCell with a type prop)
	AssigneeCell.vue        ← provider-backed people picker badge (ONE shared query fn)
	RowActions.vue          ← … dropdown: duplicate, move to next sprint, delete (confirm)
	SelectionBar.vue        ← bulk status / bulk assign / bulk move (floating bottom panel)
	IssuePeek.vue           ← peek workbench reusing the SAME Status/Priority/Assignee cells
```

Chrome assumed from the guides: `AppLayout` (left nav + fat footer),
`PageShell`, `FloatingBottomPanel`. Note what is _missing_ compared to the
records workspace: there is no dialog component and the shell's `#dialogs`
slot stays empty — on an autosave page the grid _is_ the form, so nothing
needs a modal to edit.

## Action inventory

| #   | Action                   | Trigger                            | Mechanism                                            |
| --- | ------------------------ | ---------------------------------- | ---------------------------------------------------- |
| 1   | New issue                | topbar, the page's one `primary`   | navigation (`/issues/new`)                           |
| 2   | Page search              | topbar right                       | `filters.search` → fetch dependency                  |
| 3   | Switch sprint tab        | href tabs with live counts         | URL + fetch dependency                               |
| 4   | Filter by status         | rail pill                          | `BbSelectPopover` multiple over the static catalog   |
| 5   | Filter by priority       | rail pill                          | `BbSelectPopover` multiple over the static catalog   |
| 6   | Filter by assignee       | rail pill                          | the shared people provider, single select            |
| 7   | Clear filters            | rail right (only when active)      | context `clearFilters()`                             |
| 8   | Rename issue             | title cell (grid)                  | commit-on-blur `@change` → `persistField('title')`   |
| 9   | Re-estimate              | estimate cell (grid)               | commit-on-change number → `persistField('estimate')` |
| 10  | Change status            | status badge (grid **and** peek)   | pick = commit; spinner in the chevron (§6.8)         |
| 11  | Change priority          | priority badge (grid **and** peek) | same grammar, its own leaf                           |
| 12  | Reassign                 | assignee badge (grid **and** peek) | async people search; one shared provider             |
| 13  | Peek issue               | issue ref cell                     | `peekIssue(id)` → shell stack                        |
| 14  | Duplicate                | row `…` dropdown                   | context action + toast                               |
| 15  | Move to next sprint      | row `…` **and** bulk bar           | `moveToNextSprint` / `bulkMoveToNextSprint`          |
| 16  | Delete                   | row `…`, peek footer               | destructive behind `useConfirm`                      |
| 17  | Bulk set status          | bottom panel picker                | `bulkStatus` on `table.selected`                     |
| 18  | Bulk assign              | bottom panel picker                | `bulkAssign` on `table.selected`                     |
| 19  | Select rows / select all | table checkboxes                   | table context                                        |
| 20  | Open full issue          | peek footer                        | navigation (`/issues/:id`)                           |
| 21  | Close peek               | shell chrome                       | shell stack close                                    |

Rows 8–12 are the recipe's reason to exist: five editable fields of three
different control kinds, each persisting itself, two of them able to be in
flight **on the same row at the same time**.

## The code

### Project setup — the soft status palette

Status and priority are small closed sets — the textbook case for the soft
semantic accents. The names are registered in the build plugin (that makes
them type-check as `BbBadge` variants); the CSS is the project's own,
kept in a stylesheet separate from the library defaults:

```ts
// vite.config.ts — the names; the library ships no CSS for them.
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { bitbossUi } from 'bitboss-ui/vite';

export default defineConfig({
	plugins: [
		vue(),
		bitbossUi({
			iconDir: './src/assets/icons',
			badgeVariants: [
				'soft-gray',
				'soft-blue',
				'soft-green',
				'soft-amber',
				'soft-red',
			],
		}),
	],
});
```

```css
/* src/styles/badge-variants.css — trimmed. Canonical palette + the full
   recipe (why the selectors are doubled, why the hue lives in a local
   --accent): design-language.md § Using color. */
.bb-badge.bb-badge--soft-gray {
	--accent: #64748b;
}
.bb-badge.bb-badge--soft-blue {
	--accent: #2563eb;
}
.bb-badge.bb-badge--soft-green {
	--accent: #16a34a;
}
.bb-badge.bb-badge--soft-amber {
	--accent: #d97706;
}
.bb-badge.bb-badge--soft-red {
	--accent: #dc2626;
}

.bb-badge.bb-badge--soft-gray,
.bb-badge.bb-badge--soft-blue,
.bb-badge.bb-badge--soft-green,
.bb-badge.bb-badge--soft-amber,
.bb-badge.bb-badge--soft-red {
	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
	--border-width: 1px;
	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
}
```

### context.ts

```ts
// BacklogWorkspace/context.ts
import {
	computed,
	inject,
	provide,
	reactive,
	ref,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import {
	useBbTableContext,
	useConfirm,
	useToast,
	type BadgeVariantType,
	type BbTableContext,
} from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import { api } from '@/api';
import type { Issue, IssuePriority, IssueStatus, Member } from '@/types';

/** What the peek sidebar can show. Clicking an issue ref pushes one of these. */
export type PeekItem = { type: 'issue'; id: string };

export type SprintTab = 'backlog' | 'current' | 'done';

/**
 * Exactly what a save can carry: the subset of Issue the user edits inline.
 * Five fields of three control kinds on purpose — the pattern only proves
 * itself once a row can be PARTIALLY in flight (title saving while the same
 * row's status saves), once a field is backed by a search (assignee), and
 * once a field changes on every keystroke (title, estimate).
 */
export type IssuePatch = Partial<
	Pick<Issue, 'title' | 'estimate' | 'status' | 'priority' | 'assignee'>
>;
export type EditableKey = keyof IssuePatch;

export interface BacklogFilters {
	search: string;
	status: IssueStatus[];
	priority: IssuePriority[];
	/** The whole member, not an id — the pill labels itself with zero fetches. */
	assignee: Member | null;
}

// -- Option catalogs: resolved once, at module level, for the whole page. ----
// Static arrays cost fifty rows zero requests; a per-row provider would cost
// one request per opened row (BbSelectPopover § One popover per table row).
export const STATUS_OPTIONS: { value: IssueStatus; label: string }[] = [
	{ value: 'open', label: 'Open' },
	{ value: 'in-progress', label: 'In progress' },
	{ value: 'blocked', label: 'Blocked' },
	{ value: 'done', label: 'Done' },
];
export const PRIORITY_OPTIONS: { value: IssuePriority; label: string }[] = [
	{ value: 'high', label: 'High' },
	{ value: 'normal', label: 'Normal' },
	{ value: 'low', label: 'Low' },
];

// Status/priority are small closed sets — the textbook case for the soft
// accents (design-language.md § Using color). Registered in vite.config.ts.
export const STATUS_VARIANT: Record<IssueStatus, BadgeVariantType> = {
	open: 'soft-gray',
	'in-progress': 'soft-blue',
	blocked: 'soft-red',
	done: 'soft-green',
};
export const PRIORITY_VARIANT: Record<IssuePriority, BadgeVariantType> = {
	high: 'soft-amber',
	normal: 'secondary',
	low: 'outline',
};

/**
 * `id: null` is the real "Unassigned" option, not an absence. The assignee is
 * stored on the row as the whole member, so a row's badge always labels
 * itself from its own data — no client-side directory cache, and the trigger
 * never depends on the picker having loaded.
 */
export const UNASSIGNED: Member = { id: null, name: 'Unassigned' };

/**
 * ONE query provider shared by every assignee picker on the page — each
 * row's cell, the peek's cell, the rail pill and the bulk-assign picker.
 * Providers are lazy, so a row nobody opens costs nothing. Contract
 * (fetch-items-playbook): component-initiated calls (`prefill === true`) and
 * an empty query return the whole team — six people, one cheap request — so
 * the current selection always stays resolvable; typed queries search.
 */
export const searchMembers = async (
	query: string,
	prefill: boolean
): Promise<Member[]> => {
	const q = query.trim();
	const members =
		prefill || !q ? await api.members.list() : await api.members.search(q);
	return [UNASSIGNED, ...members];
};

export interface BacklogWorkspaceContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	table: BbTableContext;
	// -- Page-owned state ------------------------------------------------------
	filters: BacklogFilters;
	hasActiveFilters: ComputedRef<boolean>;
	tab: Ref<SprintTab>;
	tabCounts: Ref<Record<SprintTab, number>>;
	refreshKey: Ref<number>;
	// -- The autosave overlay (§6.8) --------------------------------------------
	/**
	 * Optimistic values per row PER FIELD, held until the server's own data
	 * carries them. Reactive. Rung 3 on purpose: the cells, the peek and
	 * `fetchIssues` all read it. Cells never touch it directly — they go
	 * through `valueOf` / `isSaving`.
	 */
	pending: Record<string, IssuePatch>;
	/** Fields whose last save failed, keyed `${id}:${field}`. */
	failed: Readonly<Ref<Set<string>>>;
	/** Read-through: the overlay wins, the row is the fallback. */
	valueOf: <K extends EditableKey>(issue: Issue, key: K) => Issue[K];
	/** Whether THIS field of THIS row has a save in flight. */
	isSaving: (issue: Issue, key: EditableKey) => boolean;
	/** The one write path every cell commits through. */
	persistField: <K extends EditableKey>(
		issue: Issue,
		key: K,
		value: Issue[K]
	) => Promise<void>;
	// -- Data ------------------------------------------------------------------
	/** The one place the list is fetched. Retires confirmed overlay fields. */
	fetchIssues: () => Promise<Issue[]>;
	// -- Peek ------------------------------------------------------------------
	peekIssue: (id: string) => void;
	// -- Actions (complete: API + refresh + toast) ------------------------------
	clearFilters: () => void;
	duplicateIssue: (issue: Issue) => Promise<void>;
	moveToNextSprint: (issue: Issue) => Promise<void>;
	deleteIssue: (issue: Issue) => Promise<void>;
	bulkStatus: (status: IssueStatus) => Promise<void>;
	bulkAssign: (assignee: Member) => Promise<void>;
	bulkMoveToNextSprint: () => Promise<void>;
}

const key: InjectionKey<BacklogWorkspaceContext> = Symbol('backlog-workspace');

export function provideBacklogWorkspace(): BacklogWorkspaceContext {
	const { toast } = useToast();
	const { confirm } = useConfirm();

	// -- Coopt the specific contexts: once, here, for the whole page. ----------
	const shell = usePageShellContext<PeekItem>();
	const table = useBbTableContext('backlog-table', { perPage: 25 });

	// -- Page state -------------------------------------------------------------
	const filters = reactive<BacklogFilters>({
		search: '',
		status: [],
		priority: [],
		assignee: null,
	});
	const hasActiveFilters = computed(
		() =>
			filters.search !== '' ||
			filters.status.length > 0 ||
			filters.priority.length > 0 ||
			filters.assignee !== null
	);
	const tab = ref<SprintTab>('current');
	const tabCounts = ref<Record<SprintTab, number>>({
		backlog: 0,
		current: 0,
		done: 0,
	});
	const refreshKey = ref(0);

	const clearFilters = () => {
		filters.search = '';
		filters.status = [];
		filters.priority = [];
		filters.assignee = null;
	};

	// -- The autosave overlay -----------------------------------------------------
	const pending = reactive<Record<string, IssuePatch>>({});
	const failed = ref(new Set<string>());
	// The current list, stashed on every fetch. The Undo action reads it to
	// re-resolve the live row by id (the captured `issue` goes stale after a
	// refetch — see persistField).
	const rows = ref<Issue[]>([]);

	const valueOf = <K extends EditableKey>(issue: Issue, key: K): Issue[K] => {
		const patch = pending[issue.id];
		// `key in patch`, not `patch[key] ?? issue[key]`: null is a legitimate
		// committed value here (a cleared estimate), and `??` would drop that
		// overlay and show the stale row value while the save runs.
		return patch && key in patch ? (patch[key] as Issue[K]) : issue[key];
	};

	const isSaving = (issue: Issue, key: EditableKey): boolean => {
		const patch = pending[issue.id];
		return patch !== undefined && key in patch;
	};

	/** Human labels for the editable fields — used in the autosave/undo toasts. */
	const FIELD_LABELS: Record<EditableKey, string> = {
		title: 'title',
		estimate: 'estimate',
		status: 'status',
		priority: 'priority',
		assignee: 'assignee',
	};

	/**
	 * The complete autosave action, one per commit, for every control kind:
	 * no-op guard → snapshot-for-undo → optimistic set → single-field PATCH →
	 * refetch. On failure it deletes JUST this field from the overlay (the cell
	 * snaps back — a second field of the same row still in flight is untouched)
	 * and toasts destructive.
	 *
	 * On SUCCESS it fires a soft "Undo" toast: every inline edit is one click from
	 * reverting, the old value PATCHed back (and re-doable, since Undo is itself a
	 * persistField call). The Undo action must RE-RESOLVE the row by id — the
	 * `issue` captured in the closure goes stale after the refetch, and the no-op
	 * guard would then compare the revert against the stale value and swallow it.
	 */
	const persistField = async <K extends EditableKey>(
		issue: Issue,
		key: K,
		value: Issue[K]
	): Promise<void> => {
		// Snapshot what the user SEES right now — the value Undo restores.
		const previous = valueOf(issue, key);
		// No-op-commit guard: a blur without a change, or re-picking the on-screen
		// value, must not fire a request.
		if (JSON.stringify(value) === JSON.stringify(previous)) return;

		const flag = `${issue.id}:${key}`;
		(pending[issue.id] ??= {})[key] = value; // optimistic: the UI moves NOW
		failed.value.delete(flag);
		try {
			await api.issues.patch(issue.id, { [key]: value } as IssuePatch);
			// Reload — but do NOT retire the overlay here. fetchIssues drops it
			// once the server's own data carries the value (see below).
			refreshKey.value++;
			// Auto-undo: soft confirmation the edit can reverse in one click.
			toast({
				title: `${issue.ref}: ${FIELD_LABELS[key]} updated`,
				variant: 'success',
				actions: [
					{
						text: 'Undo',
						'prepend:icon': 'lucide:undo-2',
						onClick: () => {
							const current =
								rows.value.find((r) => r.id === issue.id) ?? issue;
							return persistField(current, key, previous);
						},
					},
				],
			});
		} catch {
			// Rollback: drop just this field.
			const patch = pending[issue.id];
			if (patch) {
				delete patch[key];
				if (!Object.keys(patch).length) delete pending[issue.id];
			}
			failed.value.add(flag);
			toast({
				title: `Couldn't save the ${key} of ${issue.ref} — reverted.`,
				variant: 'destructive',
			});
		}
	};

	// -- Data ---------------------------------------------------------------------
	// The one place the list is fetched. Writes the paging totals into the
	// table context, keeps the tab counts live, and — the §6.8 subtlety —
	// retires the overlay.
	const fetchIssues = async (): Promise<Issue[]> => {
		const response = await api.issues.list({
			...filters,
			tab: tab.value,
			page: table.page.value,
			perPage: table.perPage.value,
		});
		table.totalItems.value = response.total;
		tabCounts.value = response.tabCounts;

		// Retire the overlay HERE, not when a save resolves — and only the
		// fields this response actually CONFIRMS. Between a save landing and
		// this reload arriving, the table still holds the OLD row; clearing the
		// overlay early makes the cell revert to the stale value for the whole
		// reload — visibly, new → old → new. A field still in flight (the
		// response doesn't carry its value yet) is left alone.
		for (const issue of response.data) {
			const patch = pending[issue.id];
			if (!patch) continue;
			for (const field of Object.keys(patch) as EditableKey[]) {
				if (JSON.stringify(patch[field]) === JSON.stringify(issue[field])) {
					delete patch[field]; // the server's own data carries it now
				}
			}
			if (!Object.keys(patch).length) delete pending[issue.id];
		}
		rows.value = response.data; // stash for the Undo re-find (see persistField)
		return response.data;
	};

	// -- Peek ------------------------------------------------------------------------
	// One record type on this page, so the grammar is one verb: fresh stack.
	const peekIssue = (id: string) => shell.push({ type: 'issue', id }, true);

	// -- Discrete actions (row `…`, bulk bar) -------------------------------------
	// These are ordinary complete actions, records-workspace style: they
	// mutate whole rows, not single fields, so they bypass the overlay and
	// simply refetch — and being discrete (not a blur), they DO toast success.
	const refresh = () => {
		refreshKey.value++;
	};

	const duplicateIssue = async (issue: Issue) => {
		const copy = await api.issues.duplicate(issue.id);
		refresh();
		toast({ title: `Duplicated as ${copy.ref}.`, variant: 'success' });
	};

	const moveToNextSprint = async (issue: Issue) => {
		await api.issues.moveToNextSprint([issue.id]);
		refresh();
		toast({ title: `${issue.ref} moved to Sprint 25.`, variant: 'success' });
	};

	const deleteIssue = async (issue: Issue) => {
		const ok = await confirm({
			variant: 'destructive',
			title: 'Delete issue',
			text: `Delete ${issue.ref} — “${issue.title}”? This cannot be undone.`,
			yes: 'Delete',
			no: 'Cancel',
		});
		if (!ok) return;
		await api.issues.delete(issue.id);
		refresh();
		toast({ title: `${issue.ref} deleted.`, variant: 'success' });
	};

	// Bulk actions read and clear the coopted table context themselves.
	const bulkIds = (): string[] => table.selected.value;
	const clearSelection = () => {
		table.selected.value = [];
	};

	const bulkStatus = async (status: IssueStatus) => {
		const ids = bulkIds();
		await api.issues.patchMany(ids, { status });
		clearSelection();
		refresh();
		const label = STATUS_OPTIONS.find((o) => o.value === status)?.label;
		toast({
			title: `${ids.length} issues moved to ${label}.`,
			variant: 'success',
		});
	};

	const bulkAssign = async (assignee: Member) => {
		const ids = bulkIds();
		await api.issues.patchMany(ids, { assignee });
		clearSelection();
		refresh();
		toast({
			title: `${ids.length} issues assigned to ${assignee.name}.`,
			variant: 'success',
		});
	};

	const bulkMoveToNextSprint = async () => {
		const ids = bulkIds();
		await api.issues.moveToNextSprint(ids);
		clearSelection();
		refresh();
		toast({
			title: `${ids.length} issues moved to Sprint 25.`,
			variant: 'success',
		});
	};

	const ctx: BacklogWorkspaceContext = {
		shell,
		table,
		filters,
		hasActiveFilters,
		tab,
		tabCounts,
		refreshKey,
		pending,
		failed,
		valueOf,
		isSaving,
		persistField,
		fetchIssues,
		peekIssue,
		clearFilters,
		duplicateIssue,
		moveToNextSprint,
		deleteIssue,
		bulkStatus,
		bulkAssign,
		bulkMoveToNextSprint,
	};
	provide(key, ctx);
	return ctx;
}

export function useBacklogWorkspace(): BacklogWorkspaceContext {
	const ctx = inject(key);
	if (!ctx)
		throw new Error('useBacklogWorkspace() called outside BacklogWorkspace');
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- BacklogWorkspace/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left, page search + primary action right. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs
					class="min-w-0 flex-auto"
					:items="[
						{ key: 'product', text: 'Product', to: '/product' },
						{ key: 'sprints', text: 'Sprints', to: '/sprints' },
						{ key: 'sprint-24', text: 'Sprint 24' },
					]"
				/>
				<div class="flex shrink-0 items-center gap-2">
					<!-- `label` is required across the input family; `hide-label`
					     keeps the accessible name while hiding it visually. -->
					<BbTextInput
						v-model="ctx.filters.search"
						autocomplete="off"
						clearable
						compact
						hide-label
						label="Search issues"
						placeholder="Search ref or title…"
						prepend:icon="lucide:search"
					/>
					<BbButton
						prepend:icon="lucide:plus"
						to="/issues/new"
						variant="primary"
					>
						New issue
					</BbButton>
				</div>
			</div>
		</template>

		<div class="flex flex-col gap-3 p-4">
			<FilterRail />

			<!-- Tabs as URL filters: href updates the query, the key feeds the
			     fetch. Counts come back from the server on every fetch. -->
			<BbTabs
				v-model="ctx.tab.value"
				compact
				:items="[
					{
						key: 'backlog',
						label: `Backlog · ${ctx.tabCounts.value.backlog}`,
						href: '?tab=backlog',
					},
					{
						key: 'current',
						label: `Current sprint · ${ctx.tabCounts.value.current}`,
						href: '?tab=current',
					},
					{
						key: 'done',
						label: `Done · ${ctx.tabCounts.value.done}`,
						href: '?tab=done',
					},
				]"
			/>

			<BbTable
				id="backlog-table"
				v-model:highlighted="highlightedIssue"
				actions
				caption="Sprint 24 backlog"
				:columns="columns"
				compact
				:dependencies="[
					{ ...ctx.filters },
					ctx.tab.value,
					ctx.refreshKey.value,
				]"
				:deps-debounce-time="300"
				item-value="id"
				:items="ctx.fetchIssues"
				legend="Sprint 24 backlog issues"
				interactive-while-loading
				loading-text="Loading issues…"
				:row-class="rowClass"
				selectable
			>
				<!-- The ref is the peek handle — the title can't be, it's an input.
				     `.plain-link` is the project-owned inline-link helper
				     (design-language.md § Guide helper), not a BbButton variant. -->
				<template #ref="{ item, content }">
					<BbBaseButton
						class="plain-link font-semibold"
						@click="() => ctx.peekIssue(item.id)"
					>
						{{ content }}
					</BbBaseButton>
				</template>

				<!-- Five self-persisting cells, three control kinds, one leaf each. -->
				<template #title="{ item }">
					<EditableTitleCell :issue="item" />
				</template>

				<template #estimate="{ item }">
					<EstimateCell :issue="item" />
				</template>

				<template #status="{ item }">
					<StatusCell :issue="item" />
				</template>

				<template #priority="{ item }">
					<PriorityCell :issue="item" />
				</template>

				<template #assignee="{ item }">
					<AssigneeCell :issue="item" />
				</template>

				<template #actions="{ item }">
					<RowActions :issue="item" />
				</template>

				<template #no-data>
					<div class="flex flex-col items-center gap-2 p-6 text-center">
						<p class="text-sm text-[color:var(--bb-text-muted)]">
							No issues match
							{{
								ctx.hasActiveFilters.value ? 'the current filters' : 'this tab'
							}}.
						</p>
						<BbButton
							v-if="ctx.hasActiveFilters.value"
							variant="ghost"
							@click="ctx.clearFilters"
						>
							Clear filters
						</BbButton>
					</div>
				</template>
			</BbTable>

			<!-- Joins the table context by id: no page/totalPages wiring at all. -->
			<BbPagination table-id="backlog-table" />
		</div>

		<SelectionBar />

		<!-- Peek sidebar: the shell owns close; we render by type. -->
		<template #sidebar>
			<IssuePeek
				v-if="ctx.shell.current.value?.type === 'issue'"
				:issue-id="ctx.shell.current.value.id"
			/>
		</template>

		<!-- Deliberately no #dialogs content: every mutation on this page is
		     inline. The grid is the form. -->
	</PageShell>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import {
	BbBaseButton,
	BbBreadcrumbs,
	BbButton,
	BbPagination,
	BbTable,
	BbTabs,
	BbTextInput,
} from 'bitboss-ui';
import PageShell from '@/components/layout/PageShell.vue';
import { provideBacklogWorkspace } from './context';
import AssigneeCell from './AssigneeCell.vue';
import EditableTitleCell from './EditableTitleCell.vue';
import EstimateCell from './EstimateCell.vue';
import FilterRail from './FilterRail.vue';
import IssuePeek from './IssuePeek.vue';
import PriorityCell from './PriorityCell.vue';
import RowActions from './RowActions.vue';
import SelectionBar from './SelectionBar.vue';
import StatusCell from './StatusCell.vue';
import type { Issue } from '@/types';

const ctx = provideBacklogWorkspace();

// Row highlight tracks the open peek — the peeked row stays marked, and
// highlighting a row opens its peek; clearing the highlight closes it.
const highlightedIssue = computed<string | null>({
	get: () =>
		ctx.shell.current.value?.type === 'issue'
			? ctx.shell.current.value.id
			: null,
	set: (id) => {
		if (id == null) ctx.shell.close();
		else ctx.peekIssue(id);
	},
});

const columns = [
	{ key: 'ref', label: 'Ref', width: 90 },
	{ key: 'title', label: 'Title' },
	{ key: 'estimate', label: 'Est.', width: 90 },
	{ key: 'status', label: 'Status', width: 170 },
	{ key: 'priority', label: 'Priority', width: 140 },
	{ key: 'assignee', label: 'Assignee', width: 200 },
];

// Blocked rows get a tinted background — public row-class API, no internals.
// Even the tint reads THROUGH the overlay: unblock an issue and the row
// clears the moment the pick commits, not when the refetch lands.
const rowClass = (item: Issue) =>
	ctx.valueOf(item, 'status') === 'blocked'
		? 'bg-red-50 dark:bg-red-950/20'
		: undefined;
</script>
```

### FilterRail.vue

```vue
<!-- BacklogWorkspace/FilterRail.vue -->
<template>
	<div class="flex flex-wrap items-center gap-2">
		<!-- Status: multi-select pill over the same static catalog the cells use.
		     `disable-writing` means there's no search field to host an in-popover
		     clear, so these tiny fixed-list filters clear from a rail-level chip
		     (×) instead — the searchable filter below clears from inside the
		     popover. -->
		<div class="inline-flex items-center gap-1">
			<BbSelectPopover
				v-model="ctx.filters.status"
				disable-writing
				item-text="label"
				item-value="value"
				:items="STATUS_OPTIONS"
				multiple
			>
				<template #activator="{ props }">
					<BbButton
						v-bind="props"
						aria-label="Filter by status"
						append:icon="lucide:chevron-down"
						size="sm"
						variant="outline"
					>
						Status{{
							ctx.filters.status.length ? ` · ${ctx.filters.status.length}` : ''
						}}
					</BbButton>
				</template>
			</BbSelectPopover>
			<BbButton
				v-if="ctx.filters.status.length"
				aria-label="Clear status filter"
				prepend:icon="lucide:x"
				size="sm"
				variant="ghost"
				@click="ctx.filters.status = []"
			/>
		</div>

		<!-- Priority: same shape, three options. -->
		<div class="inline-flex items-center gap-1">
			<BbSelectPopover
				v-model="ctx.filters.priority"
				disable-writing
				item-text="label"
				item-value="value"
				:items="PRIORITY_OPTIONS"
				multiple
			>
				<template #activator="{ props }">
					<BbButton
						v-bind="props"
						aria-label="Filter by priority"
						append:icon="lucide:chevron-down"
						size="sm"
						variant="outline"
					>
						Priority{{
							ctx.filters.priority.length
								? ` · ${ctx.filters.priority.length}`
								: ''
						}}
					</BbButton>
				</template>
			</BbSelectPopover>
			<BbButton
				v-if="ctx.filters.priority.length"
				aria-label="Clear priority filter"
				prepend:icon="lucide:x"
				size="sm"
				variant="ghost"
				@click="ctx.filters.priority = []"
			/>
		</div>

		<!-- Assignee: the SAME shared provider as every assignee cell. The whole
		     member is the value, so the pill labels itself from page state with
		     zero fetches — no watchEffect-to-resolve-a-name here. Query-aware
		     (searchable), so the filter clears from inside the popover search. -->
		<BbSelectPopover
			v-model="ctx.filters.assignee"
			clearable
			item-text="name"
			:items="searchMembers"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filter by assignee"
					append:icon="lucide:chevron-down"
					size="sm"
					variant="outline"
				>
					{{ ctx.filters.assignee?.name ?? 'Assignee' }}
				</BbButton>
			</template>
		</BbSelectPopover>

		<!-- Clear-all renders only while something is active. -->
		<BbButton
			v-if="ctx.hasActiveFilters.value"
			class="ml-auto"
			prepend:icon="lucide:x"
			size="sm"
			variant="ghost"
			@click="ctx.clearFilters"
		>
			Clear filters
		</BbButton>
	</div>
</template>

<script setup lang="ts">
import { BbButton, BbSelectPopover } from 'bitboss-ui';
import {
	PRIORITY_OPTIONS,
	STATUS_OPTIONS,
	searchMembers,
	useBacklogWorkspace,
} from './context';

const ctx = useBacklogWorkspace();
</script>
```

### EditableTitleCell.vue

```vue
<!-- BacklogWorkspace/EditableTitleCell.vue -->
<template>
	<!-- Commit on @change (blur/Enter), NEVER v-model: a v-model autosave is
	one request per keystroke. `:model-value` binds the read-through value
	down; the user's in-progress typing lives in the DOM until blur commits
	it. A failed save marks the field until the next commit attempt. -->
	<BbTextInput
		compact
		:has-errors="ctx.failed.value.has(`${issue.id}:title`)"
		hide-label
		label="Issue title"
		:loading="ctx.isSaving(issue, 'title')"
		:model-value="ctx.valueOf(issue, 'title')"
		@change="commit"
	/>
</template>

<script setup lang="ts">
import { BbTextInput } from 'bitboss-ui';
import { useBacklogWorkspace } from './context';
import type { Issue } from '@/types';

const props = defineProps<{ issue: Issue }>();

const ctx = useBacklogWorkspace();

// `@change` is the native event; the committed text is on the target.
const commit = (event: Event) =>
	ctx.persistField(
		props.issue,
		'title',
		(event.target as HTMLInputElement).value
	);
</script>
```

### EstimateCell.vue

```vue
<!-- BacklogWorkspace/EstimateCell.vue -->
<template>
	<BbNumberInput
		compact
		:has-errors="ctx.failed.value.has(`${issue.id}:estimate`)"
		hide-label
		label="Estimate"
		:loading="ctx.isSaving(issue, 'estimate')"
		:min="0"
		:model-value="ctx.valueOf(issue, 'estimate')"
		placeholder="—"
		@change="commit"
	/>
</template>

<script setup lang="ts">
import { BbNumberInput } from 'bitboss-ui';
import { useBacklogWorkspace } from './context';
import type { Issue } from '@/types';

const props = defineProps<{ issue: Issue }>();

const ctx = useBacklogWorkspace();

// A number input's `change` carries the RAW STRING; '' means cleared. A
// cleared estimate is a real commit (estimate: null), not a no-op — which is
// exactly why the context's valueOf checks `key in patch` instead of `??`.
const commit = (event: Event) => {
	const raw = (event.target as HTMLInputElement).value;
	ctx.persistField(props.issue, 'estimate', raw === '' ? null : Number(raw));
};
</script>
```

### StatusCell.vue

```vue
<!-- BacklogWorkspace/StatusCell.vue -->
<template>
	<BbSelectPopover
		compact
		disable-writing
		item-text="label"
		item-value="value"
		:items="STATUS_OPTIONS"
		:model-value="status"
		width="180px"
		@update:model-value="
			(next) => ctx.persistField(issue, 'status', next as IssueStatus)
		"
	>
		<template #activator="{ props: activatorProps, shown }">
			<!-- The badge IS the trigger: BbBadgeButton turns the badge's own
			body into the button, so the pill is the hit target and draws its own
			focus ring — no wrapper element, no chrome class. The internal
			trailing chevron says "this can change" and sits inside the button
			with the label; while THIS field's save runs the badge's `loading`
			swaps the spinner into the chevron's place — same size, nothing
			shifts. Unlike the one-shot §6.1 cell there is no local `saving` ref:
			the flag comes from the context overlay, because in an autosave grid
			the fetch must also know what's in flight. -->
			<BbBadge
				append:icon="lucide:chevron-down"
				:class="{ 'status-cell--open': shown }"
				:loading="ctx.isSaving(issue, 'status')"
				:variant="STATUS_VARIANT[status]"
			>
				<BbBadgeButton
					:aria-label="`Change status for ${issue.ref}`"
					v-bind="activatorProps"
					>{{ label }}</BbBadgeButton
				>
			</BbBadge>
		</template>
	</BbSelectPopover>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
import { STATUS_OPTIONS, STATUS_VARIANT, useBacklogWorkspace } from './context';
import type { Issue, IssueStatus } from '@/types';

const props = defineProps<{ issue: Issue }>();

const ctx = useBacklogWorkspace();

// Read through the overlay, so the badge moves the instant a pick commits —
// color and label both.
const status = computed(() => ctx.valueOf(props.issue, 'status'));
const label = computed(
	() =>
		STATUS_OPTIONS.find((option) => option.value === status.value)?.label ??
		status.value
);
</script>

<style scoped>
/* Open = the badge's own hue, deepened, plus its variant ring — derived from
   the badge's --color/--ring tokens so every status keeps its identity
   instead of washing out to a neutral. */
.status-cell--open {
	--bg: color-mix(in oklab, var(--color) 24%, var(--bb-panel));
	--border-color: color-mix(in oklab, var(--color) 45%, var(--bb-panel));
	box-shadow: 0 0 0 var(--bb-ring-size) var(--ring);
}
</style>
```

### PriorityCell.vue

```vue
<!-- BacklogWorkspace/PriorityCell.vue -->
<template>
	<!-- Same grammar as StatusCell, its OWN leaf (§6.3): one `EditableCell`
	with a `type` prop growing a renderer switch is the API-monster seed. The
	sixty percent that repeats is cheaper than the prop that accumulates. -->
	<BbSelectPopover
		compact
		disable-writing
		item-text="label"
		item-value="value"
		:items="PRIORITY_OPTIONS"
		:model-value="priority"
		width="160px"
		@update:model-value="
			(next) => ctx.persistField(issue, 'priority', next as IssuePriority)
		"
	>
		<template #activator="{ props: activatorProps, shown }">
			<BbBadge
				append:icon="lucide:chevron-down"
				:class="{ 'priority-cell--open': shown }"
				:loading="ctx.isSaving(issue, 'priority')"
				:variant="PRIORITY_VARIANT[priority]"
			>
				<BbBadgeButton
					:aria-label="`Change priority for ${issue.ref}`"
					v-bind="activatorProps"
					>{{ label }}</BbBadgeButton
				>
			</BbBadge>
		</template>
	</BbSelectPopover>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
import {
	PRIORITY_OPTIONS,
	PRIORITY_VARIANT,
	useBacklogWorkspace,
} from './context';
import type { Issue, IssuePriority } from '@/types';

const props = defineProps<{ issue: Issue }>();

const ctx = useBacklogWorkspace();

const priority = computed(() => ctx.valueOf(props.issue, 'priority'));
const label = computed(
	() =>
		PRIORITY_OPTIONS.find((option) => option.value === priority.value)?.label ??
		priority.value
);
</script>

<style scoped>
/* Open = the badge's own hue, deepened, plus its variant ring (see
   StatusCell). */
.priority-cell--open {
	--bg: color-mix(in oklab, var(--color) 24%, var(--bb-panel));
	--border-color: color-mix(in oklab, var(--color) 45%, var(--bb-panel));
	box-shadow: 0 0 0 var(--bb-ring-size) var(--ring);
}
</style>
```

### AssigneeCell.vue

```vue
<!-- BacklogWorkspace/AssigneeCell.vue -->
<template>
	<!-- Provider-backed people picker. The provider is the ONE shared
	`searchMembers` — lazy per instance, so a row nobody opens never fetches.
	The whole member is the value (no item-value), matching how the row
	stores it. -->
	<BbSelectPopover
		compact
		item-text="name"
		:items="searchMembers"
		:model-value="assignee"
		width="220px"
		@update:model-value="
			(next) => ctx.persistField(issue, 'assignee', next as Member)
		"
	>
		<template #activator="{ props: activatorProps, shown }">
			<!-- Labelled from the ROW (through the overlay), never from the
			popover's `text`: a lazy provider has no items until first open, so
			`text` is empty — and the rows nobody opens must still read right on
			first paint. An assignee is a person, not a semantic status, so the
			badge stays neutral (`secondary`), no soft accent. -->
			<BbBadge
				append:icon="lucide:chevron-down"
				:class="{ 'assignee-cell--open': shown }"
				:loading="ctx.isSaving(issue, 'assignee')"
				variant="secondary"
			>
				<BbBadgeButton
					:aria-label="`Change assignee for ${issue.ref}`"
					v-bind="activatorProps"
					>{{ assignee.name }}</BbBadgeButton
				>
			</BbBadge>
		</template>
	</BbSelectPopover>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
import { searchMembers, useBacklogWorkspace } from './context';
import type { Issue, Member } from '@/types';

const props = defineProps<{ issue: Issue }>();

const ctx = useBacklogWorkspace();

const assignee = computed(() => ctx.valueOf(props.issue, 'assignee'));
</script>

<style scoped>
/* Open = the badge's own hue, deepened, plus its variant ring (see
   StatusCell). */
.assignee-cell--open {
	--bg: color-mix(in oklab, var(--color) 24%, var(--bb-panel));
	--border-color: color-mix(in oklab, var(--color) 45%, var(--bb-panel));
	box-shadow: 0 0 0 var(--bb-ring-size) var(--ring);
}
</style>
```

### RowActions.vue

```vue
<!-- BacklogWorkspace/RowActions.vue -->
<template>
	<BbDropdown
		:items="[
			{
				key: 'duplicate',
				text: 'Duplicate',
				'prepend:icon': 'lucide:copy',
				onClick: () => ctx.duplicateIssue(issue),
			},
			{
				key: 'next-sprint',
				text: 'Move to next sprint',
				'prepend:icon': 'lucide:arrow-right',
				onClick: () => ctx.moveToNextSprint(issue),
			},
			{
				key: 'delete',
				text: 'Delete',
				'prepend:icon': 'lucide:trash-2',
				variant: 'destructive',
				onClick: () => ctx.deleteIssue(issue),
			},
		]"
	>
		<template #activator="{ props }">
			<BbButton v-bind="props" icon="lucide:ellipsis" size="sm" variant="ghost">
				Issue actions
			</BbButton>
		</template>
	</BbDropdown>
</template>

<script setup lang="ts">
import { BbButton, BbDropdown } from 'bitboss-ui';
import { useBacklogWorkspace } from './context';
import type { Issue } from '@/types';

defineProps<{ issue: Issue }>();

const ctx = useBacklogWorkspace();
</script>
```

### SelectionBar.vue

```vue
<!-- BacklogWorkspace/SelectionBar.vue -->
<template>
	<FloatingBottomPanel :open="selectedCount > 0">
		<span class="px-2 text-sm">{{ selectedCount }} selected</span>

		<!-- Bulk pickers are DISPATCHERS, not fields: model stays null, every
		pick fires the bulk action and the popover closes. The bar holds no
		state of its own. `placement="top"` because the bar hugs the viewport
		bottom — open upward instead of flipping — with an 8px `offset` so the
		menu clears the bar. -->
		<BbSelectPopover
			disable-writing
			item-text="label"
			item-value="value"
			:items="STATUS_OPTIONS"
			:model-value="null"
			:offset="8"
			placement="top"
			width="180px"
			@update:model-value="(next) => ctx.bulkStatus(next as IssueStatus)"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Set status for selected issues"
					append:icon="lucide:chevron-up"
					size="sm"
					variant="ghost"
				>
					Set status
				</BbButton>
			</template>
		</BbSelectPopover>

		<BbSelectPopover
			item-text="name"
			:items="searchMembers"
			:model-value="null"
			:offset="8"
			placement="top"
			width="220px"
			@update:model-value="(next) => ctx.bulkAssign(next as Member)"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Assign selected issues"
					append:icon="lucide:chevron-up"
					size="sm"
					variant="ghost"
				>
					Assign
				</BbButton>
			</template>
		</BbSelectPopover>

		<BbButton
			prepend:icon="lucide:arrow-right"
			size="sm"
			variant="ghost"
			@click="ctx.bulkMoveToNextSprint"
		>
			Next sprint
		</BbButton>

		<div class="floating-bottom-panel__right flex items-center gap-1">
			<BbButton
				aria-label="Clear selection"
				icon="lucide:x"
				size="sm"
				variant="ghost"
				@click="clearSelection"
			/>
		</div>
	</FloatingBottomPanel>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbSelectPopover } from 'bitboss-ui';
import FloatingBottomPanel from '@/components/layout/FloatingBottomPanel.vue';
import { STATUS_OPTIONS, searchMembers, useBacklogWorkspace } from './context';
import type { IssueStatus, Member } from '@/types';

const ctx = useBacklogWorkspace();

const selectedCount = computed(() => ctx.table.selected.value?.length ?? 0);
const clearSelection = () => {
	ctx.table.selected.value = [];
};
</script>
```

### IssuePeek.vue

```vue
<!-- BacklogWorkspace/IssuePeek.vue -->
<template>
	<div v-if="issue" class="flex flex-col gap-4 text-sm">
		<!-- Identity header. -->
		<header class="flex flex-col gap-1">
			<p class="text-xs font-medium text-[color:var(--bb-text-muted)]">
				{{ issue.ref }}
			</p>
			<h2 class="text-base font-semibold">{{ issue.title }}</h2>
		</header>

		<!-- Properties: the SAME editable cells as the grid — one leaf, two
		call sites. Change the status here and the grid's badge (and even the
		blocked-row tint) moves in the same tick, because both surfaces read
		the same overlay; the spinner shows in both places at once. -->
		<dl class="grid grid-cols-[auto_1fr] items-center gap-x-4 gap-y-2">
			<dt class="text-[color:var(--bb-text-muted)]">Status</dt>
			<dd><StatusCell :issue="issue" /></dd>
			<dt class="text-[color:var(--bb-text-muted)]">Priority</dt>
			<dd><PriorityCell :issue="issue" /></dd>
			<dt class="text-[color:var(--bb-text-muted)]">Assignee</dt>
			<dd><AssigneeCell :issue="issue" /></dd>
			<dt class="text-[color:var(--bb-text-muted)]">Estimate</dt>
			<dd>
				{{
					ctx.valueOf(issue, 'estimate') === null
						? 'Unestimated'
						: `${ctx.valueOf(issue, 'estimate')} points`
				}}
			</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Sprint</dt>
			<dd>{{ issue.sprint }}</dd>
		</dl>

		<!-- Description. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Description
			</h3>
			<p class="whitespace-pre-line text-[color:var(--bb-text-muted)]">
				{{ issue.description }}
			</p>
		</section>

		<!-- Activity feed. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Activity
			</h3>
			<ul class="flex flex-col gap-2">
				<li v-for="entry in issue.activity" :key="entry.id" class="flex gap-2">
					<BbIcon
						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
						:icon="entry.icon"
						size="14"
					/>
					<div class="flex flex-col">
						<span>{{ entry.text }}</span>
						<span class="text-xs text-[color:var(--bb-text-muted)]"
							>{{ entry.actor }} · {{ longDate(entry.at) }}</span
						>
					</div>
				</li>
			</ul>
		</section>

		<!-- Peek is a workbench: act here, or leave for the full page. -->
		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				prepend:icon="lucide:arrow-right"
				size="sm"
				variant="secondary"
				@click="() => ctx.moveToNextSprint(issue!)"
			>
				Next sprint
			</BbButton>
			<BbButton
				size="sm"
				variant="destructive"
				@click="() => ctx.deleteIssue(issue!)"
			>
				Delete
			</BbButton>
			<BbButton
				append:icon="lucide:arrow-up-right"
				size="sm"
				:to="`/issues/${issue.id}`"
				variant="ghost"
			>
				Open full page
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { ref, watchEffect } from 'vue';
import { BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
import AssigneeCell from './AssigneeCell.vue';
import PriorityCell from './PriorityCell.vue';
import StatusCell from './StatusCell.vue';
import { useBacklogWorkspace } from './context';
import { api } from '@/api';
import type { IssueDetail } from '@/types';

const props = defineProps<{ issueId: string }>();

const ctx = useBacklogWorkspace();

// Re-fetches whenever the stack shows a different issue; refreshKey makes
// every commit (from the grid OR from this panel) reflect here immediately.
// The cells inside don't flash across that reload either — they read the
// overlay, and the overlay only retires when the fresh data confirms it.
const issue = ref<IssueDetail | null>(null);
watchEffect(async () => {
	void ctx.refreshKey.value;
	issue.value = await api.issues.get(props.issueId);
});

const longDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
		year: 'numeric',
	});
</script>
```

## Why it is built this way

- **`pending` sits on rung 3, and the recipe's whole shape follows from
  that.** Three consumers force it up the ladder: the cells read it to render
  optimistically, the peek reads it so the second call site of every cell
  agrees with the first, and `fetchIssues` reads it to retire confirmed
  fields. Contrast the records workspace's §6.1 status cell, where `saving`
  is a rung-1 local `ref` around one awaited action — correct **there**
  because nothing but that one cell ever cares. Here the fetch must know
  what's in flight, so a local flag physically cannot work; that is why the
  picker cells bind `:loading="ctx.isSaving(issue, 'status')"` instead of
  owning a `saving` ref.
- **`persistField` is one complete action for every control kind.** Text,
  number, and three pickers all commit through the same guard → optimistic
  set → PATCH → refetch pipeline, so the failure story (drop one field,
  destructive toast) and the no-op story (blur without change costs nothing)
  are written once. The guard compares against `valueOf`, not the raw row —
  what the user _sees_ is the value they are re-committing.
- **Retirement lives in the fetch because that is when the truth changes.**
  A resolved PATCH proves the server accepted the value, not that the table
  shows it — the rows in memory are still old until the refetch lands.
  Retiring per-field (only values the response confirms) means a slow title
  save survives a fast status save's reload untouched. The comment in
  `fetchIssues` ships with the recipe on purpose: this is the §6.8 bug
  everyone writes once.
- **`valueOf` checks `key in patch`, not `??`.** A cleared estimate commits
  `null`, and `null ?? row.estimate` would silently un-render the overlay
  while the save runs. The one-line comment in the context is load-bearing.
- **No dirty ring anywhere, no success toasts for cell commits.** Autosave
  has no "changed but unsaved" state, so the ring (the draft-map pattern's
  grammar) would lie; and a page where every blur saves would toast
  constantly. The spinner in the chevron's place is the feedback; failure is
  the exception worth announcing (destructive toast + `has-errors` on the
  text/number cells via the `failed` set; badge cells announce by visibly
  snapping back). Discrete actions — duplicate, move, delete, bulk — _do_
  toast success: they are events, not keystrokes.
- **Five cells, five leaves.** `EditableTitleCell`, `EstimateCell`,
  `StatusCell`, `PriorityCell`, `AssigneeCell` — never one `EditableCell`
  with a `type` prop growing a renderer switch (§6.3/§4). Each takes exactly
  one data prop (`issue`) and gets its behavior from the context.
- **Typed inputs commit on `@change`; pickers commit on pick.** The text and
  number cells bind `:model-value` down and read the committed value from the
  native event (`event.target`); the number cell's change carries the raw
  string where `''` means cleared. No debounce machinery — blur/Enter and
  pick are natural commit points, so the request count equals the commit
  count.
- **Options resolve once.** Status and priority are module-level catalogs
  shared by the cells, the rail pills and the bulk picker — zero requests.
  The assignee is genuinely query-driven, so it gets the one exception: a
  **single** shared provider (`searchMembers`), lazy per instance, keeping
  unopened rows free; prefill calls return the whole six-person team so the
  current selection always resolves. Rows store the whole member, so every
  badge and the filter pill label themselves from data they already hold —
  no `watchEffect`-to-resolve-a-name anywhere on this page.
- **The ref cell is the peek handle** because the title — the "name" of an
  issue — is an input here, and a click that sometimes edits and sometimes
  navigates is a broken affordance. One record type also collapses the stack
  grammar to a single verb (`peekIssue`, fresh stack).
- **The peek reuses the grid's cells verbatim** — one leaf, two call sites.
  Both read the same overlay, so a status change made in the panel updates
  the grid row (badge, tint, spinner) in the same tick, and vice versa.
- **Sizing:** topbar follows `md`-first (`compact` inputs at 28px flush
  beside the default buttons); `sm` appears exactly where the doctrine
  allows — rail pills, row actions, the bulk bar, the peek footer. Cell
  inputs are `compact`.
- **One `variant="primary"`** (New issue). The only irreversible action
  (delete — row menu and peek footer) rides `useConfirm`; moving between
  sprints is reversible, so it deliberately does not.

## Variations

- **Keyboard triage**: add `keyboard-navigation` to the table —
  `v-model:highlighted` already drives the peek — the approvals-inbox recipe
  is the full treatment; the overlay needs no changes, since it never cared
  how a commit was triggered.
- **Review-before-save domains**: if the product wants a batch the user
  confirms (accounting lines, permissions), swap the overlay for the
  draft-map pattern — dirty ring, dirty-gated Save — per the
  [Inline Edit Playbook](../../guides/inline-edit-playbook.md); the
  record-form recipe's line-item editor assembles it. Never mix both
  grammars on one table.
- **Undo instead of confirm**: for softer destructive-ish moves (Done →
  reopened), a success toast with an Undo action that PATCHes the old value
  back is more Linear than a confirm dialog.
- **Live board**: because refetches retire the overlay per confirmed field,
  a polling `refreshKey` bump (or a websocket-triggered one) is safe — a
  poll landing mid-save cannot destroy an in-flight edit, which is exactly
  the property the write-back anti-pattern lacks.

---

<!-- dist/ai/recipes/vue/layout-scaffold.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/vue/layout-scaffold.md -->

<!--
	GENERATED FILE — do not edit by hand.
	Source: fixtures/vue/app/components/layout/usePageShellContext.ts, fixtures/vue/app/components/layout/PageShell.vue, fixtures/vue/app/components/layout/FloatingBottomPanel.vue
	Regenerate: npm run docs:scaffold
-->

# Recipe: Layout Scaffold (Vue)

**Build this first.** Every page recipe imports `PageShell`,
`usePageShellContext` and `FloatingBottomPanel` from your own app — they are
_not_ package exports, by design: page chrome is yours to own and restyle. The
recipes assume the files below already exist. Create them verbatim, then the
rest of the recipes compile as written.

Sibling scaffolds: [Inertia](../inertia/layout-scaffold.md) · [Nuxt](../nuxt/layout-scaffold.md).

## Prerequisites

- `@vueuse/core` — `usePageShellContext.ts` imports `injectLocal`/`provideLocal`
  from it. `npm i @vueuse/core`. This library also depends on it, so it may
  already be resolvable via hoisting — don't rely on that: a package your own
  code imports belongs in your own `package.json`, or a strict installer
  (pnpm, Yarn PnP) will fail to resolve it.

## Why these are not package exports

A shell is the one part of an app that every product wants to own. Exporting it
would force our page grammar on your product and make every future change to it
a breaking change for you. Copying it costs you three files once and leaves the
chrome yours.

What you must **not** do is invent your own. These files encode behaviour the
page recipes depend on: the peek renders from a _stack_ (so a peek can open a
peek, and the back arrow works), `close()` empties that stack rather than
hiding a panel, and the closed sidebar is removed from flow with
`overflow-x: clip` on the body instead of an animated `padding-right` that
thrashes layout on every open.

## The files

### `src/components/layout/usePageShellContext.ts`

The peek **stack**, not a boolean. `push(item)` opens a peek on top of the current one (so a peek can open a peek and the back arrow works), `push(item, true)` resets to a single top-level peek, and `close()` empties the stack. Provide/inject is idempotent — the page context and `PageShell` call it and share one instance, so neither has to pass it to the other.

```ts
import { injectLocal, provideLocal } from '@vueuse/core';
import { computed, ref, type ComputedRef, type Ref } from 'vue';

export type PageShellContext<T> = {
	/** The peek stack; the last entry is what the sidebar shows. */
	stack: Ref<T[]>;
	/** The top of the stack, or null when the sidebar is closed. */
	current: ComputedRef<T | null>;
	/** Stack depth — the shell shows a back arrow when > 1. */
	depth: ComputedRef<number>;
	/** Push a peek. `reset` opens a fresh stack (a top-level peek). */
	push: (item: T, reset?: boolean) => void;
	/**
	 * Open `item` as a fresh top-level peek — what a row click does. Reads as
	 * the intent rather than as `push(item, true)`, whose boolean says nothing
	 * at the call site.
	 */
	peek: (item: T) => void;
	/**
	 * Drill from the open peek into a related record, keeping the back arrow.
	 * The other half of the same intent pair.
	 */
	stackItem: (item: T) => void;
	/** Pop one level (the back arrow). */
	pop: () => void;
	/** Close the sidebar entirely. */
	close: () => void;
};

const KEY = 'page-shell';

export function usePageShellContext<T>(): PageShellContext<T> {
	const existing = injectLocal<PageShellContext<T> | null>(KEY, null);
	if (existing != null) return existing;

	const stack = ref<T[]>([]) as Ref<T[]>;
	const current = computed<T | null>(() => stack.value.at(-1) ?? null);
	const depth = computed(() => stack.value.length);

	const push = (item: T, reset = false) => {
		stack.value = reset ? [item] : [...stack.value, item];
	};
	// Named intents over the same primitive: `push(item, true)` at a call site
	// reads as "push, and something about true", which is how pilots end up
	// resetting a stack they meant to drill into.
	const peek = (item: T) => push(item, true);
	const stackItem = (item: T) => push(item);
	const pop = () => {
		stack.value = stack.value.slice(0, -1);
	};
	const close = () => {
		stack.value = [];
	};

	const context: PageShellContext<T> = {
		stack,
		current,
		depth,
		push,
		peek,
		stackItem,
		pop,
		close,
	};
	provideLocal(KEY, context);
	return context;
}
```

### `src/components/layout/PageShell.vue`

The page frame: sticky topbar, body, and the peek sidebar with its own back/close chrome. The closed sidebar is taken out of flow by `overflow-x: clip` on the body — **not** by animating `padding-right` on the content, which thrashes layout on every open and leaves a phantom column behind.

```vue
<template>
	<div class="page-shell">
		<div v-if="$slots.topbar" class="page-shell__topbar">
			<slot name="topbar" />
		</div>

		<div class="page-shell__body">
			<!-- A `<div>`, not `<main>`: the app-side layout (AppLayout /
			     AppShell) already owns the page's one `<main>` landmark. A
			     second `<main>` here would nest two landmarks. -->
			<div class="page-shell__content">
				<slot />
			</div>

			<transition name="page-shell-sidebar">
				<aside
					v-if="shell.current.value"
					ref="panel"
					:aria-label="$slots['sidebar-title'] ? undefined : 'Details'"
					:aria-labelledby="$slots['sidebar-title'] ? titleId : undefined"
					class="page-shell__sidebar"
					data-test="page-shell-sidebar"
					tabindex="-1"
					@keydown.esc="onEscape"
				>
					<header class="page-shell__sidebar-chrome">
						<BbButton
							v-if="shell.depth.value > 1"
							aria-label="Back"
							data-test="peek-back"
							icon="lucide:arrow-left"
							size="sm"
							variant="ghost"
							@click="shell.pop"
						>
							Back
						</BbButton>
						<h2
							v-if="$slots['sidebar-title']"
							:id="titleId"
							class="page-shell__sidebar-title"
							data-test="peek-title"
						>
							<slot name="sidebar-title" />
						</h2>
						<span v-else class="page-shell__sidebar-spacer" />
						<BbButton
							aria-label="Close"
							data-test="peek-close"
							icon="lucide:x"
							size="sm"
							variant="ghost"
							@click="shell.close"
						>
							Close
						</BbButton>
					</header>
					<div class="page-shell__sidebar-body">
						<slot name="sidebar" />
					</div>
				</aside>
			</transition>
		</div>

		<slot name="dialogs" />
	</div>
</template>

<script setup lang="ts" generic="T">
import { nextTick, ref, useId, watch } from 'vue';
import { BbButton, useMobile, useSafeArea } from 'bitboss-ui';
import { usePageShellContext } from '@/components/layout/usePageShellContext';

const shell = usePageShellContext<T>();

/**
 * The peek sidebar is docked in the page, not floating over it, so nothing in
 * the library can tell it is there — and a toast would land on top of it. This
 * claims the right edge while it is open, and the toast stack slides clear.
 * Only on desktop: below the mobile breakpoint the sidebar covers the page
 * instead of sitting beside it (the `@media` block at the end of the styles),
 * so there is no edge to claim.
 *
 * SIDEBAR_W must stay in step with `.page-shell__sidebar { width }` below — it
 * is the same fact stated twice. (Pass `element: <the aside>` instead if you
 * make the panel resizable; the claim is then measured, not declared.)
 */
const SIDEBAR_W = 352; // 22rem
const { isMobile } = useMobile();
useSafeArea({
	side: 'right',
	// A declared size can't tell whether the panel is on screen — say so here
	// (`null` = nothing docked), or the edge stays claimed with no sidebar up.
	size: () => (shell.current.value ? SIDEBAR_W : null),
	active: () => !isMobile.value,
});

/**
 * Keyboard and screen-reader baseline for the peek. Deliberately NOT a focus
 * trap: on desktop this is a docked, non-modal panel and the page beside it
 * stays live and clickable, so trapping Tab would strand the keyboard in a
 * region the user can see past. What a non-modal panel does owe is a name,
 * focus that lands in it when it opens, focus that goes back where it came
 * from when it closes, and Escape. (The mobile sheet form below covers the
 * page, and that IS the shape where containment starts to matter — see the
 * Page Shell guide before adding a trap for it.)
 */
const panel = ref<HTMLElement | null>(null);
const titleId = useId();

/** The page-side control that opened the peek, to hand focus back to. */
let opener: HTMLElement | null = null;

watch(shell.current, async (item) => {
	if (item) {
		// Runs on flush 'pre', so the DOM is still the pre-change one: whatever
		// is focused now is the control that caused this. Only page-side ones
		// are worth remembering — a drill-down link lives inside the panel and
		// is destroyed by the very record it opens.
		const active = document.activeElement;
		if (active instanceof HTMLElement && !panel.value?.contains(active)) {
			opener = active;
		}

		// Focus the panel on every change, not just on open: a drill-down or a
		// Back destroys the control that was focused, and focus would otherwise
		// fall to <body> mid-consult. Landing on the panel also re-announces
		// its title, which is the record that just changed.
		await nextTick();
		panel.value?.focus();
		return;
	}

	const trigger = opener;
	opener = null;
	// The row may have been filtered away or re-rendered while the peek was
	// open; focusing a detached node quietly drops focus on <body> instead.
	if (trigger?.isConnected) trigger.focus();
});

const onEscape = (event: KeyboardEvent) => {
	// Library overlays (dropdown, popover, dialog) take Escape at the document
	// in the capture phase and stop it there, so this only ever sees the key
	// when the peek itself is the top-most open surface. `defaultPrevented`
	// covers anything app-side that handles Escape without stopping it.
	if (event.defaultPrevented) return;
	shell.close();
};
</script>

<style scoped>
.page-shell {
	display: flex;
	flex: 1;
	flex-direction: column;
	min-height: 0;
}

.page-shell__topbar {
	background: var(--bb-panel);
	position: sticky;
	/* Flush with the viewport by default. If your app layout puts a
	   sticky bar above the page (a brand/app bar), set --app-bar-h on an
	   ancestor and this topbar sits under it instead of overlapping it.

	   Two bars stacking is INTENTIONAL, not a layout bug to collapse: an
	   app/brand bar belongs to the SHELL, a topbar belongs to the PAGE. Keep
	   the two variables apart — --app-bar-h is the shell bar's height used
	   here as a sticky OFFSET, while that bar's own row height (if it needs a
	   name) is --app-bar-row-h. Conflating them is what makes a page topbar
	   sit exactly one bar too low. (Ruled PG-018, 2026-08-07.) */
	top: var(--app-bar-h, 0);
	z-index: 5;
}

.page-shell__body {
	display: flex;
	flex: 1;
	min-height: 0;
	overflow-x: clip;
}

.page-shell__content {
	flex: 1;
	min-width: 0;
}

/* Overlay sheet pinned on the parcel — same hairline as every other divider,
   no lead pin: the sidebar's edge stays uniform with the page grid. */
.page-shell__sidebar {
	background: color-mix(in oklab, var(--bb-panel) 92%, transparent);
	border-inline-start: 1px solid var(--bb-border);
	display: flex;
	flex-direction: column;
	flex-shrink: 0;
	/* Keep in step with SIDEBAR_W in the script — the safe-area claim that
	   keeps toasts off this panel is declared from that number. */
	width: 22rem;
}

.page-shell__sidebar-chrome {
	align-items: center;
	border-block-end: 1px solid var(--bb-border);
	display: flex;
	gap: 0.5rem;
	padding: 0.5rem 1rem;
}

.page-shell__sidebar-spacer {
	flex: 1;
}

.page-shell__sidebar-title {
	flex: 1;
	font-size: 15px;
	font-weight: 600;
	letter-spacing: -0.01em;
	min-width: 0;
	overflow: hidden;
	text-overflow: ellipsis;
	white-space: nowrap;
}

.page-shell__sidebar-body {
	overflow-y: auto;
	padding: 1rem;
}

.page-shell-sidebar-enter-active,
.page-shell-sidebar-leave-active {
	transition:
		transform var(--bb-transition-fast) var(--bb-ease),
		opacity var(--bb-transition-fast) var(--bb-ease);
}

.page-shell-sidebar-enter-from,
.page-shell-sidebar-leave-to {
	opacity: 0;
	transform: translateX(0.75rem);
}

/* Below the mobile breakpoint there is no room for a 22rem column beside the
   content, so the peek stops being a column and becomes a sheet over the whole
   page — chrome included, since its own header carries Back and Close.

   767.98px is `config.mobileMaxWidth` (768) minus a hair: the exact query
   `useMobile()` runs. The two must agree, or there is a band of widths where
   the safe-area claim above still thinks a panel is docked at the right edge
   while this rule has it covering the page. */
@media (max-width: 767.98px) {
	.page-shell__sidebar {
		/* Opaque here — the docked form is translucent over the page grid, but
		   a sheet that covers content must not let it show through. */
		background: var(--bb-panel);
		border-inline-start: 0;
		inset: 0;
		position: fixed;
		width: auto;
		/* Above the page topbar (5) and the floating bottom panel (30): while
		   the sheet is up, it is the page. */
		z-index: 40;
	}

	.page-shell__sidebar-body {
		/* The sheet runs to the bottom edge, so its own padding is what keeps
		   the last row clear of the home indicator. */
		padding-block-end: calc(1rem + env(safe-area-inset-bottom));
	}
}
</style>
```

### `src/components/layout/FloatingBottomPanel.vue`

The selection dock. It hugs its content (`width: max-content` + `margin-inline: auto`) rather than stretching edge to edge — a full-bleed bar reads as broken viewport chrome instead of a response to your selection.

```vue
<template>
	<transition name="floating-bottom-panel">
		<div
			v-if="open"
			aria-label="Selection actions"
			class="floating-bottom-panel"
			data-test="selection-bar"
			role="region"
		>
			<slot />
		</div>
	</transition>
</template>

<script setup lang="ts">
defineProps<{ open?: boolean }>();
</script>

<style scoped>
.floating-bottom-panel {
	align-items: center;
	background: var(--bb-panel);
	border: 1px solid var(--bb-border);
	border-radius: var(--bb-radius-surface);
	box-shadow: var(--bb-shadow);
	display: flex;
	gap: 0.5rem;
	inset-block-end: 1.25rem;
	inset-inline: 0;
	margin-inline: auto;
	max-width: calc(100% - 2rem);
	padding: 0.375rem 0.5rem;
	position: fixed;
	width: max-content;
	z-index: 30;
}

.floating-bottom-panel :deep(.floating-bottom-panel__right) {
	border-inline-start: 1px solid var(--bb-border);
	margin-inline-start: 0.75rem;
	padding-inline-start: 0.75rem;
}

.floating-bottom-panel-enter-active,
.floating-bottom-panel-leave-active {
	transition:
		transform var(--bb-transition-fast) var(--bb-ease),
		opacity var(--bb-transition-fast) var(--bb-ease);
}

.floating-bottom-panel-enter-from,
.floating-bottom-panel-leave-to {
	opacity: 0;
	transform: translateY(0.75rem);
}
</style>
```

## Wiring a page

**One topbar per page (GROK-BTG-013).** The `#topbar` slot is the page's single
top command bar — breadcrumbs/title on the left, page commands (search, the
primary action) on the right. `PageShell` renders it as its own sticky bar; do
**not** stack a second brand/utility bar above it. Primary navigation lives in
the [App Layout](../../guides/app-layout.md) sidebar, and app-wide utilities
(global search, a user menu) go **into** this same topbar — never a second
stacked row.

The topbar row is `justify-between`: the breadcrumb trail and the trailing
controls both shrink by default, so the trail collapses to its own overflow
menu while free space sits unused in the middle. Give the trail
`class="min-w-0 flex-auto"` so it consumes that slack on a stable basis, and
`shrink-0` to its siblings so they stay content-sized — the same contract
the `BbBreadcrumbs` guide documents for exactly this row.

```vue
<template>
	<PageShell>
		<template #topbar>
			<div class="flex items-center justify-between gap-4 px-4">
				<!-- `flex-auto min-w-0` lets the trail consume the row's slack (and
             shrink/overflow) instead of being sized by its content. -->
				<BbBreadcrumbs class="min-w-0 flex-auto" :items="breadcrumbs" />
				<!-- `shrink-0` keeps search/actions/the account menu content-sized so
             they never lose the tug-of-war with the trail above. -->
				<div class="flex shrink-0 items-center gap-2">
					<!-- page search, primary action, AccountMenu (see below) -->
				</div>
			</div>
		</template>

		<!-- default slot: the page body -->
		<!-- The shipped `--highlighted` tint already marks the current row;
         `row-class` is how this page says WHY it is current (the open peek)
         and how you override the look. See the BbTable guide's Row highlight
         section. -->
		<BbTable
			v-model:highlighted="highlighted"
			:columns="columns"
			:items="items"
			:row-class="rowClass"
		/>

		<template #sidebar>
			<RecordPeek v-if="shell.current.value" :id="shell.current.value" />
		</template>

		<template #dialogs>
			<!-- dialogs mount here so they escape the body's overflow clip -->
		</template>
	</PageShell>

	<FloatingBottomPanel :open="selectedCount > 0">
		<span>{{ selectedCount }} selected</span>
	</FloatingBottomPanel>
</template>
```

## Topbar value pickers (account menu, theme, warehouse)

App-chrome value pickers — theme, an active warehouse/location, anything the
user picks occasionally rather than filters by — do not belong on a bordered
form `BbSelect` in the topbar; that is a field control, and the topbar has
no form. Reach for a ghost `BbButton` opening a `BbSelectPopover`, or (when
it lives next to other account actions) an account `BbDropdown` with nested
selectable submenus, exactly like the `NestedMenu` and `SelectableMenu`
patterns in the `BbDropdown` guide, combined: each category is a submenu
opener whose own `items` holds one selectable group, so picking a value
closes the whole menu back to the top level.

```vue
<template>
	<BbDropdown :items="accountMenuItems" placement="bottom-end" :width="240">
		<template #activator="{ props }">
			<BbButton
				v-bind="props"
				aria-label="Account menu"
				class="gap-1.5"
				size="sm"
				variant="ghost"
			>
				<BbAvatar size="xs">SE</BbAvatar>
			</BbButton>
		</template>
		<!-- Companions bind to a group by `id`; the group itself stays declared
         in `items` below. -->
		<BbDropdownGroup id="theme-opts" v-model="theme" />
		<BbDropdownGroup id="warehouse-opts" v-model="warehouseId" />
	</BbDropdown>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbAvatar, BbButton, BbDropdown, BbDropdownGroup } from 'bitboss-ui';
import type { BbDropdownItem } from 'bitboss-ui';

const theme = ref<'system' | 'light' | 'dark'>('system');
const warehouseId = ref('denver');

const accountMenuItems: BbDropdownItem[] = [
	{
		key: 'theme',
		text: 'Theme',
		'prepend:icon': 'lucide:sun-moon',
		// A submenu opener (`items`) whose own `items` is one selectable
		// group — `selectable: true` gives single-choice radio semantics and a
		// check on the picked row, with no bordered field anywhere.
		items: [
			{
				key: 'theme-opts',
				selectable: true,
				items: [
					{ key: 'system', text: 'System' },
					{ key: 'light', text: 'Light' },
					{ key: 'dark', text: 'Dark' },
				],
			},
		],
	},
	{
		key: 'warehouse',
		text: 'Warehouse',
		'prepend:icon': 'lucide:warehouse',
		items: [
			{
				key: 'warehouse-opts',
				selectable: true,
				items: [
					{ key: 'denver', text: 'Denver DC' },
					{ key: 'reno', text: 'Reno DC' },
					{ key: 'columbus', text: 'Columbus DC' },
				],
			},
		],
	},
	// A trailing separator section (a nested array) for plain navigation rows.
	[
		{
			key: 'settings',
			text: 'Settings',
			'prepend:icon': 'lucide:settings',
			href: '/settings',
		},
		{
			key: 'signout',
			text: 'Sign out',
			'prepend:icon': 'lucide:log-out',
			href: '/logout',
			method: 'post',
		},
	],
];
</script>
```

Watch `theme`/`warehouseId` and act on the change (flip `html.dark`, refetch
scoped to the new warehouse) the same way any other v-model-driven picker
would — the dropdown only owns the menu, never the side effect.

## The peek must stay in sync with the table highlight

`BbTable`'s `v-model:highlighted` and the shell stack are two pieces of state
pointing at one idea ("which row is open"). Wire **both** directions or the
second click on a row does nothing: the user closes the peek, the highlight is
still set, and a re-click leaves it unchanged so no watcher fires.

```ts
watch(highlighted, (id) => {
	if (id == null) {
		if (shell.current.value != null) shell.close();
		return;
	}
	shell.peek(id);
});

// The other direction: closing the peek clears the highlight, so the same row
// can open it again.
watch(shell.current, (current) => {
	if (current == null && highlighted.value != null) highlighted.value = null;
});
```

If a page has no peek, omit `v-model:highlighted` entirely. A highlight that
paints a selected row but opens nothing is a dead affordance.

## `workspace-surfaces.css` — the helpers every page re-invents

`.plain-link`, `.table-flush` and the row tints are project CSS by design (the
library ships no such classes), but they are the _same_ project CSS on every
workspace page. (`.table-flush`'s edge-inset rules address the table through
its grid containers — `> .bb-table__table > .bb-table__body > [role='row'] >
:first-child` — never through `table`/`tbody`/`tr`/`td`, which the table no
longer renders; the canonical block is in the BbTable guide § Styling hooks.)
Author them **once**, next to the layout, and import that file
from the app entry — not per page, and never copy-pasted into a page's
`<style scoped>`, which is how three pages end up with three underline colours.

```css
/* src/components/layout/workspace-surfaces.css */
.plain-link {
	color: inherit;
	text-decoration: underline;
	text-underline-offset: 2px;
	text-decoration-color: color-mix(in oklab, var(--bb-text) 25%, transparent);
	transition: text-decoration-color var(--bb-transition-fast) var(--bb-ease);
}
.plain-link:hover,
.plain-link:focus-visible {
	text-decoration-color: currentColor;
	outline: none;
}

.row-danger {
	background: color-mix(in oklab, var(--bb-danger) 6%, var(--bb-panel));
}
.row-danger:hover {
	background: color-mix(in oklab, var(--bb-danger) 10%, var(--bb-panel));
}
.row-warn {
	background: color-mix(in oklab, var(--bb-warn) 6%, var(--bb-panel));
}
.row-warn:hover {
	background: color-mix(in oklab, var(--bb-warn) 10%, var(--bb-panel));
}
```

Every rule here is built from `--bb-*` tokens, so the whole sheet follows the
theme and dark mode without a second dark block. See
[design-language](../../guides/design-language.md) § Row tint and § the
`.plain-link` helper for the reasoning behind each.

## Shortcuts live in the topbar, not in the page

A keyboard-driven screen needs its shortcuts discoverable, and the reflex is an
inline hint bar above the table. That bar is permanent chrome for information
read once. Default to a **topbar affordance**: a keyboard icon in
`#topbar-actions` opening a `BbPopover` that lists the bindings.

```vue
<BbPopover>
	<template #activator="{ props }">
		<BbButton v-bind="props" aria-label="Keyboard shortcuts" icon="lucide:keyboard" size="sm" variant="ghost" />
	</template>
	<dl class="shortcuts">…</dl>
</BbPopover>
```

An **inline** shortcut bar is a triage exception — a queue whose entire purpose
is rapid keyboard disposition (see the approvals-inbox recipe), where the
bindings are the primary UI rather than a reference. Everywhere else, the
topbar popover keeps the body for the records.

## The height chain — `flex: 1` only works if its parent fills the viewport

`PageShell` sets `flex: 1` on itself and `min-height: 0` on its body, but that
is a claim on space its **parent** has to actually own. If the main column is a
plain block, the shell is as tall as its content: a short page leaves the peek
sidebar floating mid-screen, and a long one scrolls the whole document instead
of the content area.

Every link in the chain has to hold, top to bottom:

| Level        | Rule                                                      |
| ------------ | --------------------------------------------------------- |
| layout root  | `min-height: 100dvh` (grid or flex — it just has to fill) |
| main column  | `display: flex; flex-direction: column; min-height: 0`    |
| content slot | `flex: 1; min-height: 0`                                  |
| `PageShell`  | `flex: 1` (already in the component)                      |

`min-height: 0` on every flex child is the part people drop. Without it a flex
item refuses to shrink below its content, so the _inner_ scroll container never
scrolls and the page grows instead — the classic "why is my sticky topbar
scrolling away" symptom.

## Do not nest a drawer inside the peek

The `#sidebar` slot **is** the drawer. Putting a `BbOffCanvas` inside it gives
you two stacked drawers with two close buttons. Pick one: the PageShell stack
for in-page detail, or a standalone `BbOffCanvas` for chrome that is not about
the current page (mobile nav, global filters).

---

<!-- dist/ai/recipes/vue/onboarding.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/vue/onboarding.md -->

# Recipe: Workspace Onboarding (Vue)

A Linear/Slack-grade first-run checklist for a **plain Vue SPA with
vue-router**: a live progress header, an accordion checklist whose steps
carry the **real actions inline** — integration switches, a tag-input invite
flow, a mini project-create form, a CSV import — and a "see what you'll get"
preview peek per step, all wired through one coopting page context so every
leaf component takes zero props beyond the step (or id) it renders.

Sibling recipes: [Nuxt](../nuxt/onboarding.md) ·
[Inertia](../inertia/onboarding.md).

## Prerequisites

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell` and `usePageShellContext` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
- `<BbConfirm />` and `<BbToast />` mounted once in the app root (`App.vue`) — never in a page.
- [App Layout](../../guides/app-layout.md) and
  [Page Shell](../../guides/page-shell.md) copied into `src/components/layout/`
  per their guides — this page assumes the chrome exists and renders inside
  it.

## Key ideas

- **One coopting page context.** `provideOnboardingWorkspace()` joins the
  page-shell stack once, owns the step statuses, the integration and invite
  state, and every action. Every leaf calls `useOnboardingWorkspace()` and
  nothing else — zero prop drilling anywhere on the page.
- **Steps act inline; the checklist ticks itself.** Each step body _is_ the
  feature: switches connect integrations, a tag input sends invites, a mini
  form creates the project, a dropzone imports the CSV. Completing the real
  action persists the step status through one private `persistStatus` —
  the same verb the manual "Mark as done" / "Skip for now" ghosts use.
- **Single-open accordion, modeled — not wrapped.** `BbAccordion` is one
  panel per boolean; there is no group component by design. One
  `activeStep` key in the context derives every panel's `model-value`, and
  finishing a step advances the key to the next unfinished one.
- **Each step body is its own leaf component.** `IntegrationsStep`,
  `InviteStep`, `FirstProjectStep`… — never one `Step` component with a
  `type` prop. The shared chrome (`StepHeader`, `StepActions`) is two more
  single-concern leaves, not props on a monster.
- **Previews ride the shell stack.** "See what you'll get" pushes a
  `step-preview` peek (replace semantics — previews never stack); the peek
  is a workbench: identity header, benefit list, a stat, and a "Set it up
  now" action that jumps back to the step.
- **Checklist archetype, so rows 4/5/7/8 of the standard anatomy don't
  apply**: no filter rail, no tabs, no pagination, no selection/bulk bar —
  and no page search, since the page has no filterable collection. Page
  Shell, breadcrumbs topbar and the stacked peek sidebar stay.
- **Buttons are `md` by default**; one `variant="primary"` on the page
  ("Go to dashboard" in the topbar); step submits are `secondary`,
  done/skip/preview are `ghost`; "Dismiss onboarding" rides `useConfirm`.

## Page anatomy

```
OnboardingChecklist/
	Index.vue                ← assembly: PageShell slots, accordion loop, thin
	context.ts               ← coopting page context (shell + steps + actions)
	ProgressHeader.vue       ← title, dismiss, BbProgress + "4 of 7 complete"
	StepHeader.vue           ← status icon, title, minutes, chevron (in the header button)
	StepActions.vue          ← per-step done / skip / preview footer row
	ProfileStep.vue          ← step 1 body: completed-at-signup summary + edit link
	IntegrationsStep.vue     ← step 2 body: BbSwitch rows (Stripe, QuickBooks, Slack, Drive)
	InviteStep.vue           ← step 3 body: BbTag emails + role BbSelect + send
	FirstProjectStep.vue     ← step 4 body: mini create-project form
	ImportCustomersStep.vue  ← step 5 body: BbDropzone CSV + BbProgress upload
	FirstInvoiceStep.vue     ← step 6 body: link-out to the invoice composer
	RemindersStep.vue        ← step 7 body: reminders switch + cadence select
	StepPreviewPeek.vue      ← sidebar "what you'll get" workbench per step
```

Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
(left nav + fat footer) and [Page Shell](../../guides/page-shell.md). The
dismiss confirmation renders through the app-wide `useConfirm` host, so this
page needs no `#dialogs` content of its own.

## Action inventory

| #   | Action                           | Trigger                             | Mechanism                                                          |
| --- | -------------------------------- | ----------------------------------- | ------------------------------------------------------------------ |
| 1   | Go to dashboard                  | topbar, the page's one `primary`    | navigation (`/dashboard`)                                          |
| 2   | Dismiss onboarding               | progress header, ghost              | `useConfirm` (destructive) → context action + toast                |
| 3   | Expand / collapse a step         | accordion header (single-open)      | `activeStep` key derives each panel's `model-value`                |
| 4   | See what you'll get              | every step footer                   | `previewStep(id)` → shell peek (replace)                           |
| 5   | Mark step done / skip step       | step footer ghosts                  | `completeStep` / `skipStep` + advance to next todo                 |
| 6   | Connect / disconnect integration | switch rows in _Connect your tools_ | optimistic toggle, `readonly` in flight, revert + toast on failure |
| 7   | Compose the invite list          | `BbTag` (Enter/comma, max 10)       | local ref; `duplicate`/`max` surfaced via `errors`                 |
| 8   | Choose the invite role           | `BbSelect` beside the tags          | local ref                                                          |
| 9   | Send invitations                 | secondary button in step body       | `sendInvites` → API + auto-complete + toast                        |
| 10  | Create the first project         | mini form submit                    | `createProject` → API + auto-complete + toast                      |
| 11  | Import customers CSV             | `BbDropzone` + Import button        | `importCustomers`; `BbProgress` driven by `importState`            |
| 12  | Open the invoice composer        | outline button in step 6            | navigation (`/invoices/create`)                                    |
| 13  | Turn reminders on / pick cadence | switch + select in step 7           | `setReminders` / `setReminderCadence` + toast                      |
| 14  | Jump to a step from its preview  | peek footer                         | `jumpToStep(id)` → open step + close peek                          |
| 15  | Edit the workspace profile       | link in the completed profile step  | navigation (`/settings/general`)                                   |
| 16  | Close the peek                   | shell chrome                        | shell stack close                                                  |

## The code

### context.ts

```ts
// OnboardingChecklist/context.ts
import {
	computed,
	inject,
	provide,
	reactive,
	ref,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import { useConfirm, useToast } from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import { api } from '@/api';
import type {
	InviteRole,
	PendingInvite,
	Project,
	ProjectDraft,
	ReminderCadence,
	WorkspaceProfile,
} from '@/types';

export type StepId =
	| 'profile'
	| 'integrations'
	| 'invites'
	| 'first-project'
	| 'import-customers'
	| 'first-invoice'
	| 'reminders';

export type StepStatus = 'todo' | 'complete' | 'skipped';

export interface OnboardingStep {
	id: StepId;
	title: string;
	description: string;
	/** Rough time estimate shown in the header while the step is open. */
	minutes: number;
	status: StepStatus;
}

export interface WorkspaceIntegration {
	id: string;
	name: string;
	description: string;
	/** Full static literal — the production icon scanner only bundles names it can see. */
	icon: string;
	connected: boolean;
	/** True while a connect/disconnect request is in flight (drives `readonly`). */
	busy: boolean;
}

/** What the stacked sidebar can show: the per-step "what you'll get" preview. */
export type PeekItem = { type: 'step-preview'; stepId: StepId };

export interface OnboardingWorkspaceContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	// -- Page-owned state ------------------------------------------------------
	steps: OnboardingStep[];
	/** The one open panel; `null` collapses everything (single-open accordion). */
	activeStep: Ref<StepId | null>;
	/** Steps no longer todo (complete or skipped) — drives the progress bar. */
	doneCount: ComputedRef<number>;
	allDone: ComputedRef<boolean>;
	workspace: Ref<WorkspaceProfile | null>;
	integrations: WorkspaceIntegration[];
	invites: Ref<PendingInvite[]>;
	firstProject: Ref<Project | null>;
	importState: {
		uploading: boolean;
		sentBytes: number;
		totalBytes: number;
		importedCount: number | null;
	};
	reminders: { enabled: boolean; cadence: ReminderCadence };
	// -- Step grammar ----------------------------------------------------------
	openStep: (id: StepId | null) => void;
	previewStep: (id: StepId) => void;
	jumpToStep: (id: StepId) => void;
	// -- Actions (complete: API + state + toast) --------------------------------
	completeStep: (id: StepId) => Promise<void>;
	skipStep: (id: StepId) => Promise<void>;
	toggleIntegration: (
		integration: WorkspaceIntegration,
		next: boolean
	) => Promise<void>;
	sendInvites: (emails: string[], role: InviteRole) => Promise<void>;
	createProject: (draft: ProjectDraft) => Promise<void>;
	importCustomers: (file: File) => Promise<void>;
	setReminders: (enabled: boolean) => Promise<void>;
	setReminderCadence: (cadence: ReminderCadence) => Promise<void>;
	dismissOnboarding: () => Promise<void>;
}

const key: InjectionKey<OnboardingWorkspaceContext> = Symbol(
	'onboarding-workspace'
);

export function provideOnboardingWorkspace(): OnboardingWorkspaceContext {
	const { toast } = useToast();
	const { confirm } = useConfirm();

	// -- Coopt the specific contexts: once, here, for the whole page. ----------
	const shell = usePageShellContext<PeekItem>();

	// -- The checklist definition lives client-side; the API owns statuses. ----
	const steps = reactive<OnboardingStep[]>([
		{
			id: 'profile',
			title: 'Set up your company profile',
			description: 'Legal name, billing address and tax details.',
			minutes: 2,
			status: 'todo',
		},
		{
			id: 'integrations',
			title: 'Connect your tools',
			description:
				'Stripe for payments, QuickBooks for the books, Slack for alerts.',
			minutes: 3,
			status: 'todo',
		},
		{
			id: 'invites',
			title: 'Invite your teammates',
			description:
				'Billing works better when the whole team sees the same numbers.',
			minutes: 2,
			status: 'todo',
		},
		{
			id: 'first-project',
			title: 'Create your first project',
			description:
				'Projects group invoices, budgets and time entries per client.',
			minutes: 1,
			status: 'todo',
		},
		{
			id: 'import-customers',
			title: 'Import your customers',
			description: 'Bring your existing customer list over as a CSV.',
			minutes: 5,
			status: 'todo',
		},
		{
			id: 'first-invoice',
			title: 'Send your first invoice',
			description: 'Compose, preview and send — payment link included.',
			minutes: 4,
			status: 'todo',
		},
		{
			id: 'reminders',
			title: 'Turn on payment reminders',
			description: 'Stop chasing overdue invoices by hand.',
			minutes: 1,
			status: 'todo',
		},
	]);

	// Icon names are full static literals: the production icon scanner bundles
	// only literals it can see, and brand SVGs live in the app's iconDir.
	const integrations = reactive<WorkspaceIntegration[]>([
		{
			id: 'stripe',
			name: 'Stripe',
			description: 'Accept card payments; payouts reconcile against invoices.',
			icon: 'local:stripe',
			connected: false,
			busy: false,
		},
		{
			id: 'quickbooks',
			name: 'QuickBooks Online',
			description: 'Push paid invoices straight into your accounting.',
			icon: 'local:quickbooks',
			connected: false,
			busy: false,
		},
		{
			id: 'slack',
			name: 'Slack',
			description: 'A message in #finance when an invoice is paid or overdue.',
			icon: 'local:slack',
			connected: false,
			busy: false,
		},
		{
			id: 'google-drive',
			name: 'Google Drive',
			description: 'Attach contracts and receipts from your shared drives.',
			icon: 'local:google-drive',
			connected: false,
			busy: false,
		},
	]);

	const activeStep = ref<StepId | null>(null);
	const workspace = ref<WorkspaceProfile | null>(null);
	const invites = ref<PendingInvite[]>([]);
	const firstProject = ref<Project | null>(null);
	const importState = reactive({
		uploading: false,
		sentBytes: 0,
		totalBytes: 0,
		importedCount: null as number | null,
	});
	const reminders = reactive({
		enabled: false,
		cadence: '3-7-14' as ReminderCadence,
	});

	// Skipped counts as done: the bar rewards moving on, like Linear's checklist.
	const doneCount = computed(
		() => steps.filter((step) => step.status !== 'todo').length
	);
	const allDone = computed(() => doneCount.value === steps.length);

	const step = (id: StepId): OnboardingStep =>
		steps.find((candidate) => candidate.id === id)!;

	// -- Data --------------------------------------------------------------------
	// One initial fetch: the server owns statuses (it also flips
	// 'first-invoice' to complete on its own once the first invoice is sent).
	const load = async () => {
		const state = await api.onboarding.state();
		for (const item of steps) item.status = state.steps[item.id];
		const connected = new Set(state.connectedIntegrations);
		for (const integration of integrations)
			integration.connected = connected.has(integration.id);
		workspace.value = state.workspace;
		invites.value = state.invites;
		firstProject.value = state.firstProject;
		importState.importedCount = state.importedCustomers;
		reminders.enabled = state.reminders.enabled;
		reminders.cadence = state.reminders.cadence;
		// Open the first unfinished step on arrival.
		activeStep.value =
			steps.find((candidate) => candidate.status === 'todo')?.id ?? null;
	};
	void load();

	// -- Step grammar ----------------------------------------------------------------
	const openStep = (id: StepId | null) => {
		activeStep.value = id;
	};
	// Previews replace: a checklist preview never stacks on another preview.
	const previewStep = (id: StepId) =>
		shell.push({ type: 'step-preview', stepId: id }, true);
	// From the peek back into the page: open the step and drop the sidebar.
	const jumpToStep = (id: StepId) => {
		activeStep.value = id;
		shell.close();
	};
	const openNextTodo = (after: StepId) => {
		const index = steps.findIndex((candidate) => candidate.id === after);
		const next = [...steps.slice(index + 1), ...steps.slice(0, index)].find(
			(candidate) => candidate.status === 'todo'
		);
		activeStep.value = next?.id ?? null;
	};

	// -- Actions --------------------------------------------------------------------
	// The one status writer. Domain actions (send invites, import…) auto-check
	// their step through it; the manual done/skip ghosts use the same verb.
	const persistStatus = async (id: StepId, status: StepStatus) => {
		if (step(id).status === status) return;
		await api.onboarding.setStepStatus(id, status);
		step(id).status = status;
	};

	const completeStep = async (id: StepId) => {
		await persistStatus(id, 'complete');
		toast({ title: `"${step(id).title}" checked off.`, variant: 'success' });
		openNextTodo(id);
	};

	// Skipping is quiet: it is a dismissal, not an achievement.
	const skipStep = async (id: StepId) => {
		await persistStatus(id, 'skipped');
		openNextTodo(id);
	};

	// Optimistic, per the BbSwitch doctrine: flip now, revert + toast on failure.
	// `busy` drives `readonly` so conflicting toggles cannot queue.
	const toggleIntegration = async (
		integration: WorkspaceIntegration,
		next: boolean
	) => {
		integration.busy = true;
		integration.connected = next;
		try {
			await (next
				? api.integrations.connect(integration.id)
				: api.integrations.disconnect(integration.id));
			toast({
				title: `${integration.name} ${next ? 'connected' : 'disconnected'}.`,
				variant: 'success',
			});
			if (next) await persistStatus('integrations', 'complete');
		} catch {
			integration.connected = !next;
			toast({
				title: `Could not ${next ? 'connect' : 'disconnect'} ${integration.name}.`,
				variant: 'destructive',
			});
		} finally {
			integration.busy = false;
		}
	};

	// The client gate catches most bad input, but the server validates too (work-
	// email domains here, a non-empty name below). Without a catch, a gate that
	// lets something through becomes an unhandled promise rejection and the user
	// sees nothing at all — so surface the server's own message.
	const sendInvites = async (emails: string[], role: InviteRole) => {
		try {
			const sent = await api.team.invite(emails, role);
			invites.value = [...invites.value, ...sent];
		} catch (error) {
			const err = error as {
				status?: number;
				body?: { errors?: Record<string, string[]> };
			};
			toast({
				title:
					err.status === 422
						? (err.body?.errors?.emails?.[0] ??
							'Check the addresses and try again.')
						: 'Something went wrong. Try again.',
				variant: 'destructive',
			});
			return;
		}
		await persistStatus('invites', 'complete');
		toast({
			title: `${emails.length} invitation${emails.length === 1 ? '' : 's'} sent.`,
			variant: 'success',
		});
	};

	const createProject = async (draft: ProjectDraft) => {
		try {
			firstProject.value = await api.projects.create(draft);
		} catch (error) {
			const err = error as {
				status?: number;
				body?: { errors?: Record<string, string[]> };
			};
			toast({
				title:
					err.status === 422
						? (err.body?.errors?.name?.[0] ?? 'Check the project details.')
						: 'Something went wrong. Try again.',
				variant: 'destructive',
			});
			return;
		}
		await persistStatus('first-project', 'complete');
		toast({ title: `${draft.name} created.`, variant: 'success' });
	};

	const importCustomers = async (file: File) => {
		importState.uploading = true;
		importState.totalBytes = file.size;
		importState.sentBytes = 0;
		try {
			const result = await api.customers.import(file, {
				onProgress: (sentBytes: number) => {
					importState.sentBytes = sentBytes;
				},
			});
			importState.importedCount = result.imported;
			await persistStatus('import-customers', 'complete');
			toast({
				title: `${result.imported} customers imported.`,
				variant: 'success',
			});
		} finally {
			importState.uploading = false;
		}
	};

	const setReminders = async (enabled: boolean) => {
		reminders.enabled = enabled;
		try {
			await api.billing.updateReminders({
				enabled,
				cadence: reminders.cadence,
			});
			if (enabled) await persistStatus('reminders', 'complete');
			toast({
				title: enabled
					? 'Payment reminders are on.'
					: 'Payment reminders turned off.',
				variant: 'success',
			});
		} catch {
			reminders.enabled = !enabled;
			toast({ title: 'Could not update reminders.', variant: 'destructive' });
		}
	};

	const setReminderCadence = async (cadence: ReminderCadence) => {
		reminders.cadence = cadence;
		await api.billing.updateReminders({ enabled: reminders.enabled, cadence });
		toast({ title: 'Reminder schedule updated.', variant: 'success' });
	};

	const dismissOnboarding = async () => {
		const ok = await confirm({
			variant: 'destructive',
			title: 'Dismiss onboarding',
			text: 'Hide the setup checklist for everyone in this workspace? Unfinished steps stay available under Settings → Setup.',
			yes: 'Dismiss',
			no: 'Keep it',
		});
		if (!ok) return;
		await api.onboarding.dismiss();
		// The app's navigation reacts to the dismissed flag (the checklist entry
		// disappears and the router sends the user to /dashboard).
		toast({
			title: 'Onboarding dismissed. Find it again under Settings → Setup.',
			variant: 'success',
		});
	};

	const ctx: OnboardingWorkspaceContext = {
		shell,
		steps,
		activeStep,
		doneCount,
		allDone,
		workspace,
		integrations,
		invites,
		firstProject,
		importState,
		reminders,
		openStep,
		previewStep,
		jumpToStep,
		completeStep,
		skipStep,
		toggleIntegration,
		sendInvites,
		createProject,
		importCustomers,
		setReminders,
		setReminderCadence,
		dismissOnboarding,
	};
	provide(key, ctx);
	return ctx;
}

export function useOnboardingWorkspace(): OnboardingWorkspaceContext {
	const ctx = inject(key);
	if (!ctx)
		throw new Error(
			'useOnboardingWorkspace() called outside OnboardingChecklist'
		);
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- OnboardingChecklist/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left, the page's one primary action right. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs
					class="min-w-0 flex-auto"
					:items="[
						{ key: 'dashboard', text: 'Dashboard', to: '/dashboard' },
						{ key: 'getting-started', text: 'Getting started' },
					]"
				/>
				<BbButton
					append:icon="lucide:arrow-right"
					class="shrink-0"
					to="/dashboard"
					variant="primary"
				>
					Go to dashboard
				</BbButton>
			</div>
		</template>

		<div class="mx-auto flex w-full max-w-3xl flex-col gap-6 p-4">
			<ProgressHeader />

			<!-- Single-open checklist: one active key in the context derives every
			     panel's model-value; opening one closes the rest, and clicking the
			     open header collapses everything (payload is false → key null). -->
			<div class="flex flex-col divide-y rounded-[var(--bb-radius)] border">
				<BbAccordion
					v-for="item in ctx.steps"
					:key="item.id"
					:model-value="ctx.activeStep.value === item.id"
					@update:model-value="(open) => ctx.openStep(open ? item.id : null)"
				>
					<template #header="{ value }">
						<StepHeader :open="value" :step="item" />
					</template>
					<div class="flex flex-col gap-4 px-11 pb-4">
						<component :is="stepBodies[item.id]" />
						<StepActions :step="item" />
					</div>
				</BbAccordion>
			</div>

			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Stuck on a step?
				<BbButton size="sm" to="/docs/setup" variant="link"
					>Read the setup guide</BbButton
				>
				— it covers every integration and the CSV format.
			</p>
		</div>

		<!-- The peek sidebar: the shell owns back/close; we render by type. -->
		<template #sidebar>
			<StepPreviewPeek
				v-if="ctx.shell.current.value?.type === 'step-preview'"
				:step-id="ctx.shell.current.value.stepId"
			/>
		</template>
	</PageShell>
</template>

<script setup lang="ts">
import type { Component } from 'vue';
import { BbAccordion, BbBreadcrumbs, BbButton } from 'bitboss-ui';
import PageShell from '@/components/layout/PageShell.vue';
import { provideOnboardingWorkspace, type StepId } from './context';
import FirstInvoiceStep from './FirstInvoiceStep.vue';
import FirstProjectStep from './FirstProjectStep.vue';
import ImportCustomersStep from './ImportCustomersStep.vue';
import IntegrationsStep from './IntegrationsStep.vue';
import InviteStep from './InviteStep.vue';
import ProfileStep from './ProfileStep.vue';
import ProgressHeader from './ProgressHeader.vue';
import RemindersStep from './RemindersStep.vue';
import StepActions from './StepActions.vue';
import StepHeader from './StepHeader.vue';
import StepPreviewPeek from './StepPreviewPeek.vue';

const ctx = provideOnboardingWorkspace();

// Each step body is its own component — a lookup, not a `type` prop.
const stepBodies: Record<StepId, Component> = {
	profile: ProfileStep,
	integrations: IntegrationsStep,
	invites: InviteStep,
	'first-project': FirstProjectStep,
	'import-customers': ImportCustomersStep,
	'first-invoice': FirstInvoiceStep,
	reminders: RemindersStep,
};
</script>
```

### ProgressHeader.vue

```vue
<!-- OnboardingChecklist/ProgressHeader.vue -->
<template>
	<header class="flex flex-col gap-3">
		<div class="flex items-start justify-between gap-4">
			<div class="flex flex-col gap-1">
				<h1 class="text-xl font-semibold">Set up Acme</h1>
				<p class="text-sm text-[color:var(--bb-text-muted)]">
					A few steps to get your billing workspace ready for the whole team.
				</p>
			</div>
			<BbButton variant="ghost" @click="ctx.dismissOnboarding">
				Dismiss onboarding
			</BbButton>
		</div>

		<div class="flex flex-col gap-1.5">
			<div class="flex items-center justify-between gap-4 text-sm">
				<span class="font-medium">
					{{
						ctx.allDone.value
							? 'All set — your workspace is ready.'
							: 'Your setup checklist'
					}}
				</span>
				<span class="text-[color:var(--bb-text-muted)]">
					{{ ctx.doneCount.value }} of {{ ctx.steps.length }} complete
				</span>
			</div>
			<!-- Real units in, no pre-computed percentage: max = number of steps. -->
			<BbProgress
				aria-label="Setup progress"
				:aria-valuetext="`${ctx.doneCount.value} of ${ctx.steps.length} steps complete`"
				:max="ctx.steps.length"
				:model-value="ctx.doneCount.value"
			/>
		</div>
	</header>
</template>

<script setup lang="ts">
import { BbButton, BbProgress } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';

const ctx = useOnboardingWorkspace();
</script>
```

### StepHeader.vue

```vue
<!-- OnboardingChecklist/StepHeader.vue -->
<template>
	<!-- Rendered INSIDE the accordion's header button: everything here is
	     non-interactive and click-transparent by design — the whole row toggles. -->
	<span class="flex w-full items-center gap-3 px-3 py-3 text-left">
		<BbIcon
			class="shrink-0"
			:class="
				step.status === 'complete'
					? 'text-green-600'
					: 'text-[color:var(--bb-text-muted)]'
			"
			:icon="statusIcon"
			size="20"
		/>
		<span class="flex min-w-0 flex-1 flex-col">
			<span
				class="text-sm font-medium"
				:class="
					step.status === 'todo' ? '' : 'text-[color:var(--bb-text-muted)]'
				"
			>
				{{ step.title }}
			</span>
			<span class="truncate text-xs text-[color:var(--bb-text-muted)]">{{
				step.description
			}}</span>
		</span>
		<span
			v-if="step.status === 'skipped'"
			class="shrink-0 text-xs uppercase tracking-wide text-[color:var(--bb-text-muted)]"
		>
			Skipped
		</span>
		<span
			v-else-if="step.status === 'todo'"
			class="shrink-0 text-xs text-[color:var(--bb-text-muted)]"
		>
			~{{ step.minutes }} min
		</span>
		<BbIcon
			class="shrink-0 text-[color:var(--bb-text-muted)] transition-transform"
			:class="open ? 'rotate-180' : ''"
			icon="lucide:chevron-down"
			size="16"
		/>
	</span>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbIcon } from 'bitboss-ui';
import type { OnboardingStep } from './context';

const props = defineProps<{ open: boolean; step: OnboardingStep }>();

// Full literals — the production icon scanner needs complete names.
const icons = {
	todo: 'lucide:circle-dashed',
	complete: 'lucide:circle-check',
	skipped: 'lucide:circle-check',
} as const;
const statusIcon = computed(() => icons[props.step.status]);
</script>
```

### StepActions.vue

```vue
<!-- OnboardingChecklist/StepActions.vue -->
<template>
	<footer class="flex flex-wrap items-center gap-2 border-t pt-3">
		<template v-if="step.status === 'todo'">
			<BbButton
				prepend:icon="lucide:check"
				variant="ghost"
				@click="() => ctx.completeStep(step.id)"
			>
				Mark as done
			</BbButton>
			<BbButton variant="ghost" @click="() => ctx.skipStep(step.id)">
				Skip for now
			</BbButton>
		</template>
		<span v-else class="text-xs text-[color:var(--bb-text-muted)]">
			{{ step.status === 'complete' ? 'Completed' : 'Skipped' }} — revisit any
			time from Settings → Setup.
		</span>
		<BbButton
			append:icon="lucide:chevron-right"
			class="ml-auto"
			variant="ghost"
			@click="() => ctx.previewStep(step.id)"
		>
			See what you'll get
		</BbButton>
	</footer>
</template>

<script setup lang="ts">
import { BbButton } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';
import type { OnboardingStep } from './context';

defineProps<{ step: OnboardingStep }>();

const ctx = useOnboardingWorkspace();
</script>
```

### ProfileStep.vue

```vue
<!-- OnboardingChecklist/ProfileStep.vue -->
<template>
	<div v-if="ctx.workspace.value" class="flex flex-col gap-3 text-sm">
		<p class="text-[color:var(--bb-text-muted)]">
			Done at signup — these details appear on every invoice you send.
		</p>
		<dl class="grid grid-cols-[auto_1fr] gap-x-6 gap-y-1.5">
			<dt class="text-[color:var(--bb-text-muted)]">Company</dt>
			<dd>{{ ctx.workspace.value.company }}</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Billing address</dt>
			<dd>{{ ctx.workspace.value.address }}</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Tax ID</dt>
			<dd>{{ ctx.workspace.value.taxId }}</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Currency</dt>
			<dd>{{ ctx.workspace.value.currency }}</dd>
		</dl>
		<div>
			<BbButton
				prepend:icon="lucide:pencil"
				size="sm"
				to="/settings/general"
				variant="link"
			>
				Edit workspace profile
			</BbButton>
		</div>
	</div>
</template>

<script setup lang="ts">
import { BbButton } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';

const ctx = useOnboardingWorkspace();
</script>
```

### IntegrationsStep.vue

```vue
<!-- OnboardingChecklist/IntegrationsStep.vue -->
<template>
	<div class="flex flex-col text-sm">
		<p class="pb-1 text-[color:var(--bb-text-muted)]">
			Flip a switch to connect — you'll be sent through the provider's consent
			screen the first time.
		</p>
		<div
			v-for="integration in ctx.integrations"
			:key="integration.id"
			class="flex items-center gap-3 border-b py-2.5 last:border-b-0"
		>
			<BbIcon class="shrink-0" :icon="integration.icon" size="20" />
			<div class="flex min-w-0 flex-1 flex-col">
				<span class="font-medium">{{ integration.name }}</span>
				<span class="truncate text-xs text-[color:var(--bb-text-muted)]">
					{{ integration.description }}
				</span>
			</div>
			<!-- Instant-effect toggle: the context flips optimistically, holds the
			     switch readonly while in flight, and reverts + toasts on failure. -->
			<BbSwitch
				hide-label
				:label="`Connect ${integration.name}`"
				:model-value="integration.connected"
				:name="`integration-${integration.id}`"
				:readonly="integration.busy"
				@update:model-value="(next) => ctx.toggleIntegration(integration, next)"
			/>
		</div>
	</div>
</template>

<script setup lang="ts">
import { BbIcon, BbSwitch } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';

const ctx = useOnboardingWorkspace();
</script>
```

### InviteStep.vue

```vue
<!-- OnboardingChecklist/InviteStep.vue -->
<template>
	<div class="flex flex-col gap-3 text-sm">
		<p class="text-[color:var(--bb-text-muted)]">
			Paste addresses or type them — Enter or a comma adds each one.
		</p>

		<div class="flex flex-wrap items-end gap-2">
			<BbTag
				v-model="emails"
				class="min-w-64 flex-1"
				compact
				:divider="['Enter', ',']"
				:errors="inviteError"
				label="Email addresses"
				:max="10"
				placeholder="ada.rossi@acme.com"
				prepend:icon="lucide:mail"
				@duplicate="
					(email) => (inviteError = `${email} is already in the list.`)
				"
				@max="() => (inviteError = 'You can invite up to 10 people at once.')"
			/>
			<BbSelect
				v-model="role"
				class="w-44"
				compact
				item-text="label"
				item-value="value"
				:items="roles"
				label="Role"
				label-mode="outside"
			/>
			<BbButton prepend:icon="lucide:send" variant="secondary" @click="send">
				Send invitations
			</BbButton>
		</div>

		<ul v-if="ctx.invites.value.length" class="flex flex-col gap-1">
			<li
				v-for="invite in ctx.invites.value"
				:key="invite.email"
				class="flex items-center justify-between gap-2 text-xs"
			>
				<span>{{ invite.email }}</span>
				<span class="text-[color:var(--bb-text-muted)]"
					>{{ invite.role }} · invited {{ invite.sentAt }}</span
				>
			</li>
		</ul>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbSelect, BbTag } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';
import type { InviteRole } from '@/types';

const ctx = useOnboardingWorkspace();

// Draft state only this leaf touches: local refs, not context fields.
const emails = ref<string[]>([]);
const role = ref<InviteRole>('member');
const inviteError = ref('');

const roles: { value: InviteRole; label: string }[] = [
	{ value: 'admin', label: 'Admin' },
	{ value: 'member', label: 'Member' },
	{ value: 'accountant', label: 'Accountant' },
];

// Returning the promise lets the button's automatic loading track the send.
const send = async () => {
	inviteError.value = '';
	if (emails.value.length === 0) {
		inviteError.value = 'Add at least one email address.';
		return;
	}
	const invalid = emails.value.filter((email) => !email.includes('@'));
	if (invalid.length > 0) {
		inviteError.value = `${invalid.join(', ')} ${invalid.length === 1 ? 'is' : 'are'} not a valid address.`;
		return;
	}
	await ctx.sendInvites(emails.value, role.value);
	emails.value = [];
};
</script>
```

### FirstProjectStep.vue

```vue
<!-- OnboardingChecklist/FirstProjectStep.vue -->
<template>
	<!-- Already created (by this session or a teammate): show it, not the form. -->
	<div v-if="ctx.firstProject.value" class="flex items-center gap-2 text-sm">
		<BbIcon class="text-green-600" icon="lucide:circle-check" size="16" />
		<span>
			<span class="font-medium">{{ ctx.firstProject.value.name }}</span>
			is ready for its first invoice.
		</span>
		<BbButton
			append:icon="lucide:arrow-up-right"
			size="sm"
			:to="`/projects/${ctx.firstProject.value.id}`"
			variant="link"
		>
			Open project
		</BbButton>
	</div>

	<form
		v-else
		class="flex flex-col gap-3 text-sm"
		novalidate
		@submit.prevent="submit"
	>
		<p class="text-[color:var(--bb-text-muted)]">
			A project keeps one client's invoices, budget and time entries together.
		</p>
		<div class="flex flex-wrap items-end gap-2">
			<BbTextInput
				v-model="draft.name"
				class="min-w-56 flex-1"
				compact
				:errors="nameError"
				label="Project name"
				label-mode="outside"
				placeholder="Website redesign"
			/>
			<BbTextInput
				v-model="draft.client"
				class="min-w-56 flex-1"
				compact
				label="Client"
				label-mode="outside"
				placeholder="Globex Corporation"
			/>
			<BbButton prepend:icon="lucide:plus" type="submit" variant="secondary">
				Create project
			</BbButton>
		</div>
	</form>
</template>

<script setup lang="ts">
import { reactive, ref } from 'vue';
import { BbButton, BbIcon, BbTextInput } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';

const ctx = useOnboardingWorkspace();

const draft = reactive({ name: '', client: '' });
const nameError = ref('');

// Returning the promise lets the submit button track the async work.
const submit = () => {
	nameError.value = '';
	if (!draft.name.trim()) {
		nameError.value = 'Give the project a name.';
		return;
	}
	return ctx.createProject({ ...draft });
};
</script>
```

### ImportCustomersStep.vue

```vue
<!-- OnboardingChecklist/ImportCustomersStep.vue -->
<template>
	<div class="flex flex-col gap-3 text-sm">
		<!-- Already imported: report it instead of showing an empty dropzone. -->
		<div
			v-if="ctx.importState.importedCount !== null"
			class="flex items-center gap-2"
		>
			<BbIcon class="text-green-600" icon="lucide:circle-check" size="16" />
			<span>
				<span class="font-medium">{{ ctx.importState.importedCount }}</span>
				customers imported.
			</span>
			<BbButton
				append:icon="lucide:arrow-up-right"
				size="sm"
				to="/customers"
				variant="link"
			>
				View customers
			</BbButton>
		</div>

		<template v-else>
			<!-- MIME + extension pairing: Excel exports often carry a non-CSV MIME
			     type (or none at all on drag-drop) — '.csv' is what admits them. -->
			<BbDropzone
				v-model="file"
				:accept="['text/csv', '.csv']"
				:disabled="ctx.importState.uploading"
				:errors="fileError"
				:max-size="10 * 1024 * 1024"
				@error="onReject"
			>
				<template #default="{ dragging, focused, open }">
					<div
						class="flex flex-col items-center gap-2 rounded-[var(--bb-radius)] border-2 border-dashed p-6 text-center transition-colors"
						:class="[
							dragging
								? 'border-[color:var(--bb-primary)] bg-[color:var(--bb-panel)]'
								: '',
							focused ? 'ring-2 ring-[color:var(--bb-ring)]' : '',
						]"
					>
						<BbIcon
							class="text-[color:var(--bb-text-muted)]"
							icon="lucide:file-spreadsheet"
							size="24"
						/>
						<p class="font-medium">
							{{
								dragging ? 'Drop your CSV here' : 'Drag your customers CSV here'
							}}
						</p>
						<p class="text-xs text-[color:var(--bb-text-muted)]">
							We map name, email, VAT number and address columns. Up to 10 MB.
						</p>
						<BbButton size="sm" variant="ghost" @click="open"
							>or browse files</BbButton
						>
					</div>
				</template>
			</BbDropzone>

			<!-- Captured, not yet imported: confirm before touching the workspace. -->
			<div v-if="file" class="flex items-center gap-2">
				<BbIcon
					class="shrink-0 text-[color:var(--bb-text-muted)]"
					icon="lucide:file-text"
					size="16"
				/>
				<span class="min-w-0 flex-1 truncate">
					{{ file.name }}
					<span class="text-xs text-[color:var(--bb-text-muted)]"
						>· {{ formatSize(file.size) }}</span
					>
				</span>
				<BbButton
					aria-label="Remove selected file"
					:disabled="ctx.importState.uploading"
					icon="lucide:x"
					size="sm"
					variant="ghost"
					@click="() => (file = null)"
				/>
				<BbButton
					:disabled="ctx.importState.uploading"
					prepend:icon="lucide:upload"
					variant="secondary"
					@click="startImport"
				>
					Import customers
				</BbButton>
			</div>

			<!-- The dropzone captures; the context uploads and drives the bar. -->
			<div v-if="ctx.importState.uploading" class="flex flex-col gap-1">
				<BbProgress
					aria-label="Upload progress"
					:max="ctx.importState.totalBytes"
					:model-value="ctx.importState.sentBytes"
				/>
				<span class="text-xs text-[color:var(--bb-text-muted)]">
					Uploading… {{ formatSize(ctx.importState.sentBytes) }} of
					{{ formatSize(ctx.importState.totalBytes) }}
				</span>
			</div>
		</template>
	</div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbDropzone, BbIcon, BbProgress } from 'bitboss-ui';
import type { DropZoneError } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';

const ctx = useOnboardingWorkspace();

// The captured-but-not-imported file is this leaf's own state.
const file = ref<File | null>(null);
const fileError = ref('');

// Rejects never reach the model — map the typed error to a message and feed
// it back through `errors` (the display is a round-trip, not automatic).
const onReject = (error: DropZoneError) => {
	fileError.value =
		error.type === 'maxSize'
			? `${error.filename} is ${error.formattedSize} — the limit is ${error.formattedMaxSize}.`
			: error.type === 'accept'
				? `${error.filename} is not a CSV file.`
				: `${error.filename} was rejected.`;
};

const startImport = async () => {
	if (!file.value) return;
	fileError.value = '';
	await ctx.importCustomers(file.value);
	file.value = null;
};

const formatSize = (bytes: number) =>
	bytes >= 1024 * 1024
		? `${(bytes / 1024 / 1024).toFixed(1)} MB`
		: `${Math.max(1, Math.round(bytes / 1024))} KB`;
</script>
```

### FirstInvoiceStep.vue

```vue
<!-- OnboardingChecklist/FirstInvoiceStep.vue -->
<template>
	<div class="flex flex-col gap-3 text-sm">
		<p class="text-[color:var(--bb-text-muted)]">
			The composer walks you through line items, taxes and payment terms. Every
			invoice goes out with a payment link — customers pay by card or bank
			transfer without creating an account. This step checks itself off when
			your first invoice is sent.
		</p>
		<div>
			<BbButton
				append:icon="lucide:arrow-up-right"
				prepend:icon="lucide:receipt"
				to="/invoices/create"
				variant="outline"
			>
				Open the invoice composer
			</BbButton>
		</div>
	</div>
</template>

<script setup lang="ts">
import { BbButton } from 'bitboss-ui';
</script>
```

### RemindersStep.vue

```vue
<!-- OnboardingChecklist/RemindersStep.vue -->
<template>
	<div class="flex flex-col gap-3 text-sm">
		<!-- Instant-effect switch: the context applies optimistically and reverts
		     with a toast if the server rejects the change. -->
		<BbSwitch
			description="Email customers automatically when an invoice goes overdue. Replies land in your inbox."
			label="Automatic payment reminders"
			:model-value="ctx.reminders.enabled"
			name="payment-reminders"
			@update:model-value="(next) => ctx.setReminders(next)"
		/>
		<BbSelect
			v-if="ctx.reminders.enabled"
			class="max-w-72"
			compact
			item-text="label"
			item-value="value"
			:items="cadences"
			label="Reminder schedule"
			label-mode="outside"
			:model-value="ctx.reminders.cadence"
			@update:model-value="(cadence) => ctx.setReminderCadence(cadence)"
		/>
	</div>
</template>

<script setup lang="ts">
import { BbSelect, BbSwitch } from 'bitboss-ui';
import { useOnboardingWorkspace } from './context';
import type { ReminderCadence } from '@/types';

const ctx = useOnboardingWorkspace();

const cadences: { value: ReminderCadence; label: string }[] = [
	{ value: '3-7-14', label: '3, 7 and 14 days overdue' },
	{ value: '7', label: '7 days overdue' },
	{ value: '7-30', label: '7 and 30 days overdue' },
];
</script>
```

### StepPreviewPeek.vue

```vue
<!-- OnboardingChecklist/StepPreviewPeek.vue -->
<template>
	<div class="flex flex-col gap-4 text-sm">
		<!-- Identity header. -->
		<header class="flex items-center gap-3">
			<span
				class="flex h-9 w-9 shrink-0 items-center justify-center rounded-[var(--bb-radius)] border"
			>
				<BbIcon :icon="preview.icon" size="18" />
			</span>
			<div class="flex min-w-0 flex-col">
				<h2 class="text-base font-semibold">{{ preview.title }}</h2>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					{{ preview.tagline }}
				</p>
			</div>
		</header>

		<p
			v-if="step.status !== 'todo'"
			class="flex items-center gap-1.5 text-xs text-[color:var(--bb-text-muted)]"
		>
			<!-- Green is earned: skipped reads as reached-but-unmeasured, not done. -->
			<BbIcon
				:class="
					step.status === 'complete'
						? 'text-green-600'
						: 'text-[color:var(--bb-text-muted)]'
				"
				icon="lucide:circle-check"
				size="14"
			/>
			{{
				step.status === 'complete'
					? 'Already done in this workspace.'
					: 'Skipped — you can still set it up.'
			}}
		</p>

		<!-- What you'll get. -->
		<section class="flex flex-col gap-2.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				What you'll get
			</h3>
			<ul class="flex flex-col gap-2.5">
				<li
					v-for="bullet in preview.bullets"
					:key="bullet.title"
					class="flex gap-2"
				>
					<BbIcon
						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
						:icon="bullet.icon"
						size="14"
					/>
					<div class="flex flex-col">
						<span class="font-medium">{{ bullet.title }}</span>
						<span class="text-xs text-[color:var(--bb-text-muted)]">{{
							bullet.text
						}}</span>
					</div>
				</li>
			</ul>
		</section>

		<!-- One concrete number beats three adjectives. -->
		<div class="rounded-[var(--bb-radius)] border p-3">
			<p class="text-lg font-semibold">{{ preview.stat.value }}</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				{{ preview.stat.label }}
			</p>
		</div>

		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				v-if="step.status === 'todo'"
				prepend:icon="lucide:check"
				variant="secondary"
				@click="() => ctx.jumpToStep(stepId)"
			>
				Set it up now
			</BbButton>
			<BbButton v-else variant="ghost" @click="() => ctx.jumpToStep(stepId)">
				Review this step
			</BbButton>
		</footer>
	</div>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbIcon } from 'bitboss-ui';
import { useOnboardingWorkspace, type StepId } from './context';

const props = defineProps<{ stepId: StepId }>();

const ctx = useOnboardingWorkspace();

const step = computed(
	() => ctx.steps.find((candidate) => candidate.id === props.stepId)!
);
const preview = computed(() => previews[props.stepId]);

interface StepPreview {
	icon: string;
	title: string;
	tagline: string;
	bullets: { icon: string; title: string; text: string }[];
	stat: { value: string; label: string };
}

// Presentation content with a single consumer: it lives in the leaf, not the
// context. Icon names are full static literals for the production scanner.
const previews: Record<StepId, StepPreview> = {
	profile: {
		icon: 'lucide:building-2',
		title: 'A complete company profile',
		tagline: 'Set once, printed on every document.',
		bullets: [
			{
				icon: 'lucide:file-text',
				title: 'Compliant invoices',
				text: 'Legal name, address and tax ID appear on every PDF automatically.',
			},
			{
				icon: 'lucide:euro',
				title: 'One currency for the books',
				text: 'Amounts, totals and reports all use your workspace currency.',
			},
		],
		stat: {
			value: '2 min',
			label: 'to update it later under Settings → General',
		},
	},
	integrations: {
		icon: 'lucide:link',
		title: 'Your tools, wired together',
		tagline:
			'Payments, accounting and alerts stop being three separate chores.',
		bullets: [
			{
				icon: 'lucide:credit-card',
				title: 'Payments reconcile themselves',
				text: 'Stripe payouts are matched against open invoices automatically.',
			},
			{
				icon: 'lucide:receipt',
				title: 'Books stay current',
				text: 'Paid invoices flow into QuickBooks the moment they settle.',
			},
			{
				icon: 'lucide:bell',
				title: 'The team finds out in Slack',
				text: '#finance gets a message on every paid and overdue invoice.',
			},
		],
		stat: {
			value: '9 days',
			label: 'faster average payment for teams with Stripe connected',
		},
	},
	invites: {
		icon: 'lucide:users',
		title: 'Everyone on the same numbers',
		tagline: 'Roles keep access right-sized from day one.',
		bullets: [
			{
				icon: 'lucide:user-plus',
				title: 'Sign-in with work email',
				text: 'Invitees join with their address — no shared passwords.',
			},
			{
				icon: 'lucide:key-round',
				title: 'Permissions per role',
				text: 'Accountants see reports; members see their own projects.',
			},
			{
				icon: 'lucide:clock',
				title: 'Invitations expire safely',
				text: 'Unaccepted invites lapse after 7 days and can be re-sent.',
			},
		],
		stat: { value: '10', label: 'invitations per batch' },
	},
	'first-project': {
		icon: 'lucide:folder',
		title: 'A home for each client',
		tagline: 'Projects keep invoices, budgets and time in one place.',
		bullets: [
			{
				icon: 'lucide:folder-open',
				title: 'Everything grouped',
				text: 'Invoices, budgets and time entries organized per client.',
			},
			{
				icon: 'lucide:chart-line',
				title: 'Profitability from day one',
				text: 'A per-project margin view as soon as the first invoice is paid.',
			},
		],
		stat: {
			value: '3',
			label: 'projects created by the average team in week one',
		},
	},
	'import-customers': {
		icon: 'lucide:file-spreadsheet',
		title: 'Your customer list, moved over',
		tagline: 'The CSV you already have is enough.',
		bullets: [
			{
				icon: 'lucide:upload',
				title: 'Columns mapped for you',
				text: 'Name, email, VAT number and address are detected automatically.',
			},
			{
				icon: 'lucide:check',
				title: 'No double imports',
				text: 'Rows are merged by email — re-running an import never duplicates.',
			},
		],
		stat: { value: '5,000', label: 'rows per import' },
	},
	'first-invoice': {
		icon: 'lucide:receipt',
		title: 'Your first invoice, out the door',
		tagline: 'Composed, sent and tracked in one flow.',
		bullets: [
			{
				icon: 'lucide:send',
				title: 'Sent from your domain',
				text: 'Invoices arrive from billing@your-company, not a noreply void.',
			},
			{
				icon: 'lucide:banknote',
				title: 'Payment link included',
				text: 'Customers pay by card or bank transfer without an account.',
			},
			{
				icon: 'lucide:clock',
				title: 'Overdue tracking starts itself',
				text: 'Due dates and aging are tracked from the moment you hit send.',
			},
		],
		stat: {
			value: '2×',
			label: 'faster payment on invoices with a payment link',
		},
	},
	reminders: {
		icon: 'lucide:bell',
		title: 'Overdue chasing, automated',
		tagline: 'Polite nudges on a schedule you choose.',
		bullets: [
			{
				icon: 'lucide:clock',
				title: 'A schedule, not a scramble',
				text: 'Reminders at 3, 7 and 14 days overdue — or the cadence you pick.',
			},
			{
				icon: 'lucide:mail',
				title: 'Replies reach a human',
				text: 'Customers answer straight into your inbox thread.',
			},
		],
		stat: {
			value: '38%',
			label: 'fewer invoices reach 30 days overdue with reminders on',
		},
	},
};
</script>
```

## Why it is built this way

- **The context coopts the shell, leaves consume.** The only specific
  context on a checklist page is the peek stack; `provideOnboardingWorkspace()`
  joins it once and thirteen components share step state, integration
  state and every action through one `useOnboardingWorkspace()` call. No
  component receives a callback prop; the only data props are the `step` /
  `stepId` an item renders (`StepHeader`, `StepActions`, `StepPreviewPeek`)
  — everything else is injection.
- **Single-open is one key, per the BbAccordion doctrine.** `BbAccordion`
  is deliberately one panel per boolean with no group wrapper; the
  `activeStep` key derives each `model-value`, the `update:modelValue`
  payload (`false` on closing the open header) resets it to `null`, and
  `openNextTodo` gives the Linear feel of the checklist walking itself
  forward. No watchers force-closing siblings.
- **Headers stay passive, actions live in the body.** The accordion header
  is already a `<button>`; the status icon, minutes estimate and chevron in
  `StepHeader` are click-transparent metadata. Everything interactive —
  done, skip, preview, the step's real controls — is body content, so the
  markup stays valid and the click target stays whole.
- **One status verb, two entry points.** Domain actions auto-check their
  step (`sendInvites`, `createProject`, `importCustomers`, a successful
  connect, enabling reminders) through the same private `persistStatus`
  that `completeStep`/`skipStep` use — the checklist can never disagree
  with the workspace's real state, and manual done/skip remains for
  out-of-band completion.
- **Every rung of the state ladder is deliberate.** Draft state one leaf
  touches is a local ref (invite emails and role, the project draft, the
  captured CSV file, the reject message); everything two components read
  sits on the context (statuses, `importState` driving `BbProgress`,
  reminders); nothing on this page outlives it, so no store is involved.
- **The switch promise is kept.** Integration and reminder toggles apply
  optimistically, hold the control `readonly` while the request flies, and
  revert with a `destructive` toast on failure — the async-save pattern
  from the BbSwitch guide, owned by context actions so no leaf ever talks
  to `@/api` or toasts on its own.
- **The dropzone captures; the context uploads.** `BbDropzone` has no
  request surface by design: the leaf holds the captured `File`, maps the
  typed `@error` union back through `errors` (the display round-trip), and
  `importCustomers` drives `BbProgress` from real bytes — `max` is the file
  size, never a pre-computed percentage.
- **Previews are peeks, not dialogs.** "See what you'll get" is the
  checklist's version of clicking a record's name: `previewStep` pushes
  onto the coopted shell stack with `replace` (previews never stack), and
  `jumpToStep` owns the way back — leaves never touch the stack grammar
  directly.
- **Sizing and variants:** `md`-first throughout the bodies (28px buttons
  flush beside `compact` inputs in the invite and project rows); `sm` only
  for genuinely dense spots (inline links, the file-row remove); exactly
  one `variant="primary"` (Go to dashboard); step submits are `secondary`;
  dismissal is a ghost gated by a `destructive` `useConfirm`.

## Variations

- **Personal onboarding**: scope statuses per user instead of per
  workspace (`api.onboarding.state({ scope: 'user' })`) and drop the
  workspace-wide dismiss confirm copy; the page shape is unchanged.
- **Sequential (gated) steps**: lock each accordion until the previous
  step is done by rendering the body's controls `disabled` with an
  explanatory line; for hard gates with per-step validation, the
  wizard-form recipe is the full treatment.
- **Preview follows the open step**: call `previewStep(id)` from
  `openStep` so the sidebar always previews the active step; keep the
  explicit footer button for touch users.
- **All-done celebration**: when `allDone` flips, swap `ProgressHeader`'s
  copy block for a success panel with the dashboard CTA and a "book an
  onboarding call" link.

---

<!-- dist/ai/recipes/vue/record-form.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/vue/record-form.md -->

# Recipe: Record Form (Vue)

The form archetype at full standard anatomy for a **plain Vue SPA with
vue-router**: a Stripe-grade invoice create/edit page — sectioned fields with
tied selects, server-side 422 error mapping onto every input (including
line items), inline-editing line-item rows, a dirty-snapshot
route-leave guard, a sticky action row, and a customer peek workbench, all
through one coopting page context so every leaf component takes zero props
beyond the record it renders.

Sibling recipes: [Nuxt](../nuxt/record-form.md) ·
[Inertia](../inertia/record-form.md). The listing this page belongs with is
[Records Workspace (Vue)](./records-workspace.md).

## Prerequisites

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell` and `usePageShellContext` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
- `<BbConfirm />` and `<BbToast />` mounted once in the app root (`App.vue`) — never in a page.
- `@/api` exposes `api.invoices.get/create/update/delete`,
  `api.customers.list/byIds/getDetail` and `api.projects.list` — typed
  async functions returning the shapes below; a 422 response rejects with
  `{ status: 422, body: { errors } }`.

## Key ideas

- **One coopting page context.** `provideInvoiceForm()` joins the
  page-shell stack once, owns the draft, the server errors, the dirty
  snapshot and every action (including the route-leave guard). Every leaf
  calls `useInvoiceForm()` and nothing else — cells, sections, the sticky
  bar and the peek share state with zero prop drilling.
- **The draft is the page's single mutable surface.** Inline cell edits,
  the peek's "apply billing defaults", add/duplicate/remove line — all of
  it mutates `ctx.draft`. The API boundary is exactly one call: the save,
  whose 422 response maps back onto the same draft's fields.
- **422 errors reach every input — including line-item rows.** Laravel-style
  keys (`customerId`, `lineItems.2.unitPrice`) land in one `errors` map;
  scalar fields bind `ctx.errors.value.<key>` and the editable cells
  resolve their row key through `ctx.lineItemError(line, field)`.
- **Tied selects are declarative.** Project depends on customer via
  `dependencies` + `enforce-coherence`; switching customers refetches the
  projects and clears a now-invalid pick automatically. No watchers.
- **Line items are inline-editing rows (§6.3).** Each row is a
  `LineItemCard` with labeled fields — quantity, unit price, a computed
  amount readout, and a full-width description — one leaf per cell type,
  swapping to an input on click, committing on blur (Enter too on the
  number cells) and reverting on Esc.
- **Dirty state is a JSON snapshot,** re-baselined before every navigation
  the page itself causes (save redirect, delete redirect), so the
  route-leave confirm only fires on genuinely abandoned edits.
- **Clicking the customer's name peeks the customer** — a workbench, not a
  preview: billing profile, stats, recent invoices, and an action that
  writes the customer's defaults back into the draft.
- **Buttons are `md` by default;** `sm` only in the line-item rows and
  the peek. One `variant="primary"`: the save. No filter rail, no tabs, no
  bulk bar — the form archetype has no list to filter and no selection.

## Page anatomy

```
InvoiceForm/
	Index.vue                   ← assembly: PageShell slots, header, <form>, sections
	context.ts                  ← coopting page context (shell + draft + errors + actions + leave guard)
	DetailsSection.vue          ← tied selects, dates, terms, PO, tax rate
	LineItemsSection.vue        ← line-item rows + add line + live totals
	LineItemCard.vue            ← one row: labeled inline-edit cells + duplicate/remove
	EditableDescriptionCell.vue ← inline textarea edit (commit on blur, Esc reverts)
	EditableQuantityCell.vue    ← inline quantity edit with outer stepper buttons
	EditableRateCell.vue        ← inline unit-price edit, currency-formatted display
	NotesSection.vue            ← BbCollapsible disclosure over notes + terms
	FormActions.vue             ← sticky action row: delete / cancel / save draft / save
	CustomerPeek.vue            ← sidebar workbench for the picked customer
```

Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
(left nav + fat footer) and [Page Shell](../../guides/page-shell.md)
(topbar / content / stacked sidebar). The floating bottom panel is
deliberately absent — it is selection chrome, and a form has no selection.

## Action inventory

| #   | Action                          | Trigger                               | Mechanism                                              |
| --- | ------------------------------- | ------------------------------------- | ------------------------------------------------------ |
| 1   | Save invoice                    | sticky bar, the page's one `primary`  | `type="submit"` → `persist()` + 422 mapping + redirect |
| 2   | Save as draft                   | sticky bar outline (create mode)      | `persist('draft')`, URL swaps to edit in place         |
| 3   | Delete invoice                  | sticky bar destructive (edit mode)    | `useConfirm` → API → toast → redirect                  |
| 4   | Cancel                          | sticky bar ghost                      | navigation (`to`); leave guard intercepts if dirty     |
| 5   | Pick customer                   | details section select                | query-aware `items` provider                           |
| 6   | Pick project                    | details section select                | `dependencies` + `enforce-coherence` (§ tied selects)  |
| 7   | Peek customer                   | "View customer" link under the select | `ctx.peekCustomer()` → shell stack                     |
| 8   | Apply billing defaults          | peek workbench button                 | writes terms + tax rate into the draft, toast          |
| 9   | Edit description inline         | line-item cell                        | §6.3 with `BbTextarea`: commit on blur, Esc reverts    |
| 10  | Edit quantity / rate inline     | line-item cells                       | §6.3 with `BbNumberInput` + outer stepper buttons      |
| 11  | Add line item                   | section header + empty state          | `ctx.addLineItem()` pushes a blank draft row           |
| 12  | Duplicate line                  | row actions                           | `ctx.duplicateLineItem(line)` inserts a copy below     |
| 13  | Remove line                     | row actions                           | `ctx.removeLineItem(line)`                             |
| 14  | Search line items               | topbar page search                    | `lineItemSearch` → `visibleLineItems` filter           |
| 15  | Toggle notes & terms            | section disclosure button             | `BbCollapsible` + `aria-expanded`/`aria-controls`      |
| 16  | Open customer / recent invoices | peek links                            | real `to` navigation (leave guard applies)             |

## The code

### The shapes

What `@/types` contributes and what `api.invoices.get(2107)` returns — the
record every block below is grounded in:

```ts
// @/types (excerpt)
export type InvoiceStatus = 'draft' | 'pending' | 'paid' | 'overdue';

export interface LineItemDraft {
	/** Server id; unsaved rows carry a negative local id. */
	id: number;
	description: string;
	quantity: number;
	unitPrice: number;
}

export interface InvoiceDraft {
	customerId: number | null;
	projectId: number | null;
	/** `YYYY-MM-DD` (the date inputs run with `floating`). */
	issuedAt: string | null;
	dueDate: string | null;
	paymentTerms: string | null;
	poNumber: string | null;
	taxRate: number | null;
	lineItems: LineItemDraft[];
	notes: string | null;
	terms: string | null;
}
```

```ts
// The invoice being edited (api.invoices.get(2107))
const invoice = {
	id: 2107,
	number: 'INV-2107',
	status: 'draft',
	customerId: 18, // Northwind Traders
	projectId: 112, // Website relaunch
	issuedAt: '2026-07-01',
	dueDate: '2026-07-31',
	paymentTerms: 'Net 30',
	poNumber: 'PO-2026-0641',
	taxRate: 8.875,
	lineItems: [
		{
			id: 9001,
			description: 'Design sprint — homepage & navigation',
			quantity: 3,
			unitPrice: 1850,
		},
		{
			id: 9002,
			description: 'Frontend build — catalogue & product views',
			quantity: 5,
			unitPrice: 1200,
		},
		{
			id: 9003,
			description: 'CMS integration & content migration',
			quantity: 2,
			unitPrice: 1400,
		},
		{
			id: 9004,
			description: 'QA & cross-browser pass',
			quantity: 1,
			unitPrice: 950,
		},
		{
			id: 9005,
			description: 'Staging infrastructure (June)',
			quantity: 1,
			unitPrice: 240,
		},
	],
	notes: 'Second milestone of the relaunch engagement. Hosting billed at cost.',
	terms:
		'Payment due within 30 days. 1.5% monthly interest on overdue balances.',
};
```

### context.ts

```ts
// InvoiceForm/context.ts
import {
	computed,
	inject,
	provide,
	reactive,
	ref,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import { onBeforeRouteLeave, useRoute, useRouter } from 'vue-router';
import { useConfirm, useToast, type BadgeVariantType } from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import { api } from '@/api';
import type {
	Customer,
	CustomerDetail,
	Invoice,
	InvoiceDraft,
	InvoiceStatus,
	LineItemDraft,
	Project,
} from '@/types';

/** What the stacked sidebar can show. Clicking the customer's name pushes one. */
export type PeekItem = { type: 'customer'; id: number };

// Status is a small closed set — the textbook case for the soft accents
// (design-language.md § Using color; the `soft-*` variants are registered
// app-side). A badge takes its color from the VARIANT map and its label from
// the LABEL map; it never renders the raw enum. Used by the customer peek's
// recent-invoice list.
export const INVOICE_STATUS_LABEL: Record<InvoiceStatus, string> = {
	draft: 'Draft',
	pending: 'Pending',
	paid: 'Paid',
	overdue: 'Overdue',
};
export const INVOICE_STATUS_VARIANT: Record<InvoiceStatus, BadgeVariantType> = {
	draft: 'soft-gray',
	pending: 'soft-amber',
	paid: 'soft-green',
	overdue: 'soft-red',
};

type LineItemField = 'description' | 'quantity' | 'unitPrice';

export interface InvoiceFormContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	// -- Page-owned state ------------------------------------------------------
	mode: 'create' | 'edit';
	loaded: Ref<boolean>;
	invoiceNumber: Ref<string | null>;
	status: Ref<InvoiceStatus>;
	draft: InvoiceDraft;
	/** Server 422 errors, keyed Laravel-style (`customerId`, `lineItems.2.unitPrice`). */
	errors: Ref<Record<string, string[]>>;
	saving: Ref<boolean>;
	isDirty: ComputedRef<boolean>;
	lineItemSearch: Ref<string>;
	visibleLineItems: ComputedRef<LineItemDraft[]>;
	subtotal: ComputedRef<number>;
	taxAmount: ComputedRef<number>;
	total: ComputedRef<number>;
	// -- Item providers (handed straight to the selects) ------------------------
	fetchCustomers: (query: string, prefill: boolean) => Promise<Customer[]>;
	fetchProjects: () => Promise<Project[]>;
	// -- Row-level error lookup --------------------------------------------------
	lineItemError: (
		line: LineItemDraft,
		field: LineItemField
	) => string[] | undefined;
	// -- Draft mutations (the cells and the peek write through these) -----------
	updateLineItem: (
		line: LineItemDraft,
		patch: Partial<Omit<LineItemDraft, 'id'>>
	) => void;
	addLineItem: () => void;
	duplicateLineItem: (line: LineItemDraft) => void;
	removeLineItem: (line: LineItemDraft) => void;
	applyCustomerDefaults: (customer: CustomerDetail) => void;
	// -- Peek grammar ------------------------------------------------------------
	peekCustomer: () => void;
	// -- Actions (complete: API + 422 mapping + toast + redirect) ----------------
	saveInvoice: () => Promise<void>;
	saveAsDraft: () => Promise<void>;
	deleteInvoice: () => Promise<void>;
}

const key: InjectionKey<InvoiceFormContext> = Symbol('invoice-form');

export function provideInvoiceForm(): InvoiceFormContext {
	const route = useRoute();
	const router = useRouter();
	const { toast } = useToast();
	const { confirm } = useConfirm();

	// -- Coopt the shell: once, here, for the whole page. ------------------------
	const shell = usePageShellContext<PeekItem>();

	// /invoices/create has no id; /invoices/:id/edit does.
	//
	// NOT `const`: both routes render THIS component, so the create→edit
	// `router.replace` in `saveAsDraft` patches the existing instance rather than
	// remounting it — setup never runs again. Promote them by hand there, or
	// `mode` stays 'create' forever and a second "Save as draft" creates a
	// SECOND invoice.
	let invoiceId = route.params.id ? Number(route.params.id) : null;
	let mode: 'create' | 'edit' = invoiceId === null ? 'create' : 'edit';

	// -- The draft ---------------------------------------------------------------
	// Unsaved rows get negative local ids so `item-value` stays stable and the
	// payload can tell the server which lines are new (negative → null).
	let nextLocalId = -1;
	const blankLineItem = (): LineItemDraft => ({
		id: nextLocalId--,
		description: '',
		quantity: 1,
		unitPrice: 0,
	});

	const draft = reactive<InvoiceDraft>({
		customerId: null,
		projectId: null,
		issuedAt: null,
		dueDate: null,
		paymentTerms: null,
		poNumber: null,
		taxRate: null,
		lineItems: [blankLineItem()],
		notes: null,
		terms: null,
	});

	const loaded = ref(mode === 'create');
	const invoiceNumber = ref<string | null>(null);
	const status = ref<InvoiceStatus>('draft');
	const errors = ref<Record<string, string[]>>({});
	const saving = ref(false);

	// Dirty = the draft's JSON diverged from the last committed snapshot.
	// Gated on `loaded` so the async seed of edit mode never reads as dirty.
	const snapshot = ref(JSON.stringify(draft));
	const isDirty = computed(
		() => loaded.value && JSON.stringify(draft) !== snapshot.value
	);

	if (mode === 'edit' && invoiceId !== null) {
		api.invoices.get(invoiceId).then((invoice: Invoice) => {
			invoiceNumber.value = invoice.number;
			status.value = invoice.status;
			draft.customerId = invoice.customerId;
			draft.projectId = invoice.projectId;
			draft.issuedAt = invoice.issuedAt;
			draft.dueDate = invoice.dueDate;
			draft.paymentTerms = invoice.paymentTerms;
			draft.poNumber = invoice.poNumber;
			draft.taxRate = invoice.taxRate;
			draft.lineItems = invoice.lineItems.map((line) => ({ ...line }));
			draft.notes = invoice.notes;
			draft.terms = invoice.terms;
			snapshot.value = JSON.stringify(draft);
			loaded.value = true;
		});
	}

	// -- Item providers -----------------------------------------------------------
	// Component-initiated calls (`prefill === true`) must keep the current
	// selection resolvable, or the chip loses its text.
	const fetchCustomers = async (
		query: string,
		prefill: boolean
	): Promise<Customer[]> => {
		if (prefill && draft.customerId !== null) {
			return api.customers.byIds([draft.customerId]);
		}
		return api.customers.list({ search: query });
	};

	// Re-run by the project select's `dependencies: [draft.customerId]`; the
	// response always contains the customer's full project list, so an existing
	// `projectId` stays resolvable and `enforce-coherence` never wipes a valid pick.
	const fetchProjects = (): Promise<Project[]> =>
		draft.customerId === null
			? Promise.resolve([])
			: api.projects.list({ customer: draft.customerId });

	// -- Line items -----------------------------------------------------------------
	const lineItemSearch = ref('');
	const visibleLineItems = computed(() => {
		// A `clearable` BbTextInput emits **null** when it is emptied, not `''` —
		// so coalesce before calling a string method, or the first clear throws
		// `Cannot read properties of null (reading 'trim')` and the section stops
		// re-rendering.
		const query = (lineItemSearch.value ?? '').trim().toLowerCase();
		if (!query) return draft.lineItems;
		return draft.lineItems.filter((line) =>
			line.description.toLowerCase().includes(query)
		);
	});

	const subtotal = computed(() =>
		draft.lineItems.reduce(
			(sum, line) => sum + line.quantity * line.unitPrice,
			0
		)
	);
	const taxAmount = computed(
		() => subtotal.value * ((draft.taxRate ?? 0) / 100)
	);
	const total = computed(() => subtotal.value + taxAmount.value);

	// Server 422 keys index lines by payload position, which is draft order —
	// resolve a row's key through its id so the lookup survives filtering.
	const lineItemError = (
		line: LineItemDraft,
		field: LineItemField
	): string[] | undefined => {
		const index = draft.lineItems.findIndex(
			(candidate) => candidate.id === line.id
		);
		return errors.value[`lineItems.${index}.${field}`];
	};

	const updateLineItem = (
		line: LineItemDraft,
		patch: Partial<Omit<LineItemDraft, 'id'>>
	) => {
		const target = draft.lineItems.find(
			(candidate) => candidate.id === line.id
		);
		if (target) Object.assign(target, patch);
	};
	const addLineItem = () => {
		draft.lineItems.push(blankLineItem());
	};
	const duplicateLineItem = (line: LineItemDraft) => {
		const index = draft.lineItems.findIndex(
			(candidate) => candidate.id === line.id
		);
		draft.lineItems.splice(index + 1, 0, { ...line, id: nextLocalId-- });
	};
	const removeLineItem = (line: LineItemDraft) => {
		draft.lineItems = draft.lineItems.filter(
			(candidate) => candidate.id !== line.id
		);
	};

	// The peek writes back into the draft: the sidebar is a workbench.
	const applyCustomerDefaults = (customer: CustomerDetail) => {
		draft.paymentTerms = customer.defaultPaymentTerms;
		draft.taxRate = customer.defaultTaxRate;
		toast({
			title: `Applied ${customer.name}'s billing defaults.`,
			variant: 'success',
		});
	};

	// -- Peek grammar ----------------------------------------------------------------
	const peekCustomer = () => {
		if (draft.customerId === null) return;
		shell.push({ type: 'customer', id: draft.customerId }, true);
	};

	// -- Persistence -----------------------------------------------------------------
	// New lines travel with `id: null`; the server assigns real ids on save.
	const payload = (nextStatus: InvoiceStatus) => ({
		...draft,
		status: nextStatus,
		lineItems: draft.lineItems.map((line) => ({
			...line,
			id: line.id > 0 ? line.id : null,
		})),
	});

	const persist = async (
		nextStatus: InvoiceStatus
	): Promise<Invoice | null> => {
		saving.value = true;
		errors.value = {};
		try {
			const saved =
				mode === 'edit' && invoiceId !== null
					? await api.invoices.update(invoiceId, payload(nextStatus))
					: await api.invoices.create(payload(nextStatus));
			// Re-baseline BEFORE navigating so the leave guard lets the redirect through.
			snapshot.value = JSON.stringify(draft);
			status.value = saved.status;
			invoiceNumber.value = saved.number;
			return saved;
		} catch (error: unknown) {
			const err = error as {
				status?: number;
				body?: { errors?: Record<string, string[]> };
			};
			if (err.status === 422) {
				// Laravel-style: { errors: { 'lineItems.2.unitPrice': ['Must be positive.'] } }
				errors.value = err.body?.errors ?? {};
				toast({ title: 'Some fields need attention.', variant: 'destructive' });
			} else {
				toast({
					title: 'Something went wrong. Try again.',
					variant: 'destructive',
				});
			}
			return null;
		} finally {
			saving.value = false;
		}
	};

	const saveInvoice = async () => {
		// Creating finalizes the invoice; editing keeps whatever status it has.
		const saved = await persist(mode === 'edit' ? status.value : 'pending');
		if (!saved) return;
		toast({ title: `Invoice ${saved.number} saved.`, variant: 'success' });
		router.push(`/invoices/${saved.id}`);
	};

	const saveAsDraft = async () => {
		const saved = await persist('draft');
		if (!saved) return;
		toast({ title: `Draft ${saved.number} saved.`, variant: 'success' });
		// Stay on the page; swap the URL so a refresh lands in edit mode. The
		// component is patched, not remounted, so promote this instance too.
		if (mode === 'create') {
			await router.replace(`/invoices/${saved.id}/edit`);
			invoiceId = saved.id;
			mode = 'edit';
		}
	};

	const deleteInvoice = async () => {
		if (mode !== 'edit' || invoiceId === null) return;
		const ok = await confirm({
			variant: 'destructive',
			title: 'Delete invoice',
			text: `Delete ${invoiceNumber.value}? This cannot be undone.`,
			yes: 'Delete',
			no: 'Cancel',
		});
		if (!ok) return;
		await api.invoices.delete(invoiceId);
		// Re-baseline so the guard doesn't ask about a record that no longer exists.
		snapshot.value = JSON.stringify(draft);
		toast({ title: `${invoiceNumber.value} deleted.`, variant: 'success' });
		router.push('/invoices');
	};

	// -- Route-leave guard ---------------------------------------------------------
	// Lives with the state it protects. `onBeforeRouteLeave` registers against
	// the page component because provideInvoiceForm() runs in its setup.
	onBeforeRouteLeave(async () => {
		if (!isDirty.value) return true;
		return await confirm({
			variant: 'destructive',
			title: 'Unsaved changes',
			text: 'You have unsaved changes on this invoice. Leave without saving?',
			yes: 'Discard changes',
			no: 'Keep editing',
		});
	});

	const ctx: InvoiceFormContext = {
		shell,
		mode,
		loaded,
		invoiceNumber,
		status,
		draft,
		errors,
		saving,
		isDirty,
		lineItemSearch,
		visibleLineItems,
		subtotal,
		taxAmount,
		total,
		fetchCustomers,
		fetchProjects,
		lineItemError,
		updateLineItem,
		addLineItem,
		duplicateLineItem,
		removeLineItem,
		applyCustomerDefaults,
		peekCustomer,
		saveInvoice,
		saveAsDraft,
		deleteInvoice,
	};
	provide(key, ctx);
	return ctx;
}

export function useInvoiceForm(): InvoiceFormContext {
	const ctx = inject(key);
	if (!ctx) throw new Error('useInvoiceForm() called outside InvoiceForm');
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- InvoiceForm/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left, page search right. The search scopes the
		     work surface — here, the line items. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs class="min-w-0 flex-auto" :items="trail" />
				<BbTextInput
					v-model="ctx.lineItemSearch.value"
					autocomplete="off"
					class="shrink-0"
					clearable
					compact
					hide-label
					label="Search line items"
					placeholder="Search line items…"
					prepend:icon="lucide:search"
				/>
			</div>
		</template>

		<div
			v-if="ctx.loaded.value"
			class="mx-auto flex w-full max-w-4xl flex-col gap-6 p-4"
		>
			<header class="flex items-center gap-3">
				<h1 class="text-lg font-semibold">
					{{
						ctx.mode === 'edit'
							? `Edit ${ctx.invoiceNumber.value}`
							: 'New invoice'
					}}
				</h1>
				<BbBadge v-if="ctx.mode === 'edit'" variant="outline">{{
					ctx.status.value
				}}</BbBadge>
			</header>

			<!-- One form, one submit. `novalidate` keeps error UX on the inputs'
			     `errors` surface instead of browser bubbles; `autocomplete="off"`
			     (echoed on every field) keeps browser autofill off the draft. -->
			<form
				autocomplete="off"
				class="flex flex-col gap-6"
				novalidate
				@submit.prevent="ctx.saveInvoice"
			>
				<DetailsSection />
				<LineItemsSection />
				<NotesSection />
				<FormActions />
			</form>
		</div>

		<div v-else class="flex justify-center p-12">
			<BbSpinner label="Loading invoice…" />
		</div>

		<!-- Stacked peek sidebar: the shell owns back/close; we render by type. -->
		<template #sidebar>
			<CustomerPeek
				v-if="ctx.shell.current.value?.type === 'customer'"
				:customer-id="ctx.shell.current.value.id"
			/>
		</template>
	</PageShell>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbBadge, BbBreadcrumbs, BbSpinner, BbTextInput } from 'bitboss-ui';
import PageShell from '@/components/layout/PageShell.vue';
import { provideInvoiceForm } from './context';
import CustomerPeek from './CustomerPeek.vue';
import DetailsSection from './DetailsSection.vue';
import FormActions from './FormActions.vue';
import LineItemsSection from './LineItemsSection.vue';
import NotesSection from './NotesSection.vue';

const ctx = provideInvoiceForm();

// A real trail, ≥ 2 linked levels; the current page carries no target.
const trail = computed(() => [
	{ key: 'dashboard', text: 'Dashboard', to: '/dashboard' },
	{ key: 'billing', text: 'Billing', to: '/billing' },
	{ key: 'invoices', text: 'Invoices', to: '/invoices' },
	{
		key: 'invoice',
		text:
			ctx.mode === 'edit'
				? (ctx.invoiceNumber.value ?? 'Invoice')
				: 'New invoice',
	},
]);
</script>
```

### DetailsSection.vue

```vue
<!-- InvoiceForm/DetailsSection.vue -->
<template>
	<section class="flex flex-col gap-3">
		<h2
			class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
		>
			Details
		</h2>

		<div class="grid gap-4 sm:grid-cols-2">
			<!-- Tied selects: project depends on customer. `dependencies` re-runs
			     the project provider; `enforce-coherence` clears a project that is
			     no longer among the new options. No watchers. -->
			<div class="flex flex-col gap-1">
				<BbSelect
					v-model="ctx.draft.customerId"
					autocomplete="off"
					:errors="ctx.errors.value.customerId"
					item-text="name"
					item-value="id"
					:items="ctx.fetchCustomers"
					label="Customer"
					placeholder="Search customers…"
				/>
				<!-- Clicking the NAME of a thing peeks it. -->
				<BbButton
					v-if="ctx.draft.customerId !== null"
					append:icon="lucide:panel-right-open"
					class="self-start"
					size="sm"
					variant="link"
					@click="ctx.peekCustomer"
				>
					View customer
				</BbButton>
			</div>

			<BbSelect
				v-model="ctx.draft.projectId"
				autocomplete="off"
				:dependencies="[ctx.draft.customerId]"
				:disabled="ctx.draft.customerId === null"
				enforce-coherence
				:errors="ctx.errors.value.projectId"
				item-text="name"
				item-value="id"
				:items="ctx.fetchProjects"
				label="Project"
				placeholder="Pick the customer first"
			/>

			<!-- `floating` keeps the model a plain YYYY-MM-DD string, so the due
			     date's `min` can be fed straight from the issue date. -->
			<BbDatePickerInput
				v-model="ctx.draft.issuedAt"
				autocomplete="off"
				:errors="ctx.errors.value.issuedAt"
				floating
				label="Issue date"
				prepend:icon="lucide:calendar"
			/>
			<BbDatePickerInput
				v-model="ctx.draft.dueDate"
				autocomplete="off"
				:errors="ctx.errors.value.dueDate"
				floating
				label="Due date"
				:min="ctx.draft.issuedAt ?? undefined"
				prepend:icon="lucide:calendar"
			/>

			<BbSelect
				v-model="ctx.draft.paymentTerms"
				autocomplete="off"
				:errors="ctx.errors.value.paymentTerms"
				:items="['Due on receipt', 'Net 15', 'Net 30', 'Net 60']"
				label="Payment terms"
				placeholder="Choose terms"
			/>

			<BbTextInput
				v-model="ctx.draft.poNumber"
				autocomplete="off"
				:errors="ctx.errors.value.poNumber"
				label="PO / reference"
				placeholder="PO-2026-0641"
			/>

			<BbNumberInput
				v-model="ctx.draft.taxRate"
				autocomplete="off"
				:errors="ctx.errors.value.taxRate"
				hint="Applied to the subtotal below."
				label="Tax rate"
				:max="100"
				:max-precision="3"
				:min="0"
			>
				<template #suffix>%</template>
			</BbNumberInput>
		</div>
	</section>
</template>

<script setup lang="ts">
import {
	BbButton,
	BbDatePickerInput,
	BbNumberInput,
	BbSelect,
	BbTextInput,
} from 'bitboss-ui';
import { useInvoiceForm } from './context';

const ctx = useInvoiceForm();
</script>
```

### LineItemsSection.vue

```vue
<!-- InvoiceForm/LineItemsSection.vue -->
<template>
	<section class="flex flex-col gap-3">
		<div class="flex items-center justify-between">
			<h2
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Line items
			</h2>
			<BbButton
				prepend:icon="lucide:plus"
				variant="outline"
				@click="ctx.addLineItem"
			>
				Add line item
			</BbButton>
		</div>

		<!-- One bordered panel whose rows are divided by hairlines — not a
		     BbTable (no selection, paging or fetch) and not a stack of floating
		     cards. Each row keeps the same §6.3 inline-edit cells per field. -->
		<div
			v-if="ctx.visibleLineItems.value.length"
			class="flex flex-col rounded-[var(--bb-radius)] border"
		>
			<LineItemCard
				v-for="line in ctx.visibleLineItems.value"
				:key="line.id"
				:line="line"
			/>
		</div>

		<!-- Soft empty band — a wash, not a dashed outline. -->
		<div
			v-else
			class="flex flex-col items-center gap-2 rounded-[var(--bb-radius)] bg-[color:var(--bb-muted)] p-6 text-center"
		>
			<p class="text-sm text-[color:var(--bb-text-muted)]">
				{{
					ctx.lineItemSearch.value
						? 'No line items match your search.'
						: 'No line items yet.'
				}}
			</p>
			<BbButton
				v-if="!ctx.lineItemSearch.value"
				variant="outline"
				@click="ctx.addLineItem"
			>
				Add the first line
			</BbButton>
		</div>

		<!-- Totals: live computed from the draft — they move as cells commit. -->
		<dl class="ml-auto grid w-60 grid-cols-[1fr_auto] gap-y-1 text-sm">
			<dt class="text-[color:var(--bb-text-muted)]">Subtotal</dt>
			<dd class="text-right tabular-nums">
				{{ currency.format(ctx.subtotal.value) }}
			</dd>
			<dt class="text-[color:var(--bb-text-muted)]">
				Tax ({{ ctx.draft.taxRate ?? 0 }}%)
			</dt>
			<dd class="text-right tabular-nums">
				{{ currency.format(ctx.taxAmount.value) }}
			</dd>
			<dt class="font-semibold">Total</dt>
			<dd class="text-right font-semibold tabular-nums">
				{{ currency.format(ctx.total.value) }}
			</dd>
		</dl>
	</section>
</template>

<script setup lang="ts">
import { BbButton } from 'bitboss-ui';
import LineItemCard from './LineItemCard.vue';
import { useInvoiceForm } from './context';

const ctx = useInvoiceForm();

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
</script>
```

### LineItemCard.vue

```vue
<!-- InvoiceForm/LineItemCard.vue -->
<template>
	<article class="flex flex-col gap-3 border-b p-3 last:border-b-0">
		<div class="flex items-end gap-3">
			<div class="grid min-w-0 flex-1 grid-cols-3 gap-3">
				<div>
					<p
						class="mb-1 text-right text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
					>
						Qty
					</p>
					<EditableQuantityCell :line="line" />
				</div>
				<div>
					<p
						class="mb-1 text-right text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
					>
						Unit price
					</p>
					<EditableRateCell :line="line" />
				</div>
				<div>
					<p
						class="mb-1 text-right text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
					>
						Amount
					</p>
					<!-- Virtual field: computed from the row, never edited. -->
					<p class="px-1 py-0.5 text-right tabular-nums">
						{{ currency.format(line.quantity * line.unitPrice) }}
					</p>
				</div>
			</div>

			<div class="flex shrink-0 items-center gap-1">
				<BbButton
					icon="lucide:copy"
					size="sm"
					variant="ghost"
					@click="() => ctx.duplicateLineItem(line)"
				>
					Duplicate line
				</BbButton>
				<BbButton
					icon="lucide:trash-2"
					size="sm"
					variant="ghost"
					@click="() => ctx.removeLineItem(line)"
				>
					Remove line
				</BbButton>
			</div>
		</div>

		<div>
			<p
				class="mb-1 text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Description
			</p>
			<EditableDescriptionCell :line="line" />
		</div>
	</article>
</template>

<script setup lang="ts">
import { BbButton } from 'bitboss-ui';
import EditableDescriptionCell from './EditableDescriptionCell.vue';
import EditableQuantityCell from './EditableQuantityCell.vue';
import EditableRateCell from './EditableRateCell.vue';
import { useInvoiceForm } from './context';
import type { LineItemDraft } from '@/types';

defineProps<{ line: LineItemDraft }>();

const ctx = useInvoiceForm();

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
</script>
```

### EditableDescriptionCell.vue

```vue
<!-- InvoiceForm/EditableDescriptionCell.vue -->
<template>
	<BbTextarea
		v-if="editing"
		ref="inputRef"
		v-model="value"
		auto-grow
		compact
		:errors="ctx.lineItemError(line, 'description')"
		hide-label
		label="Line description"
		placeholder="What was delivered?"
		:rows="2"
		@blur="commit"
		@keydown.esc="revert"
	/>
	<button
		v-else
		class="w-full whitespace-pre-wrap rounded-[var(--bb-radius)] px-1 py-0.5 text-left hover:bg-[color:var(--bb-hover)]"
		:class="{
			'text-[color:var(--bb-text-muted)]': !line.description,
			'text-[color:var(--bb-danger)]': hasError,
		}"
		type="button"
		@click="start"
	>
		{{ line.description || 'Add a description…' }}
	</button>
</template>

<script setup lang="ts">
import { computed, nextTick, ref } from 'vue';
import { BbTextarea } from 'bitboss-ui';
import { useInvoiceForm } from './context';
import type { LineItemDraft } from '@/types';

const props = defineProps<{ line: LineItemDraft }>();

const ctx = useInvoiceForm();

// Rung 1 of the ladder: only this cell reads or writes its editing state.
const editing = ref(false);
const value = ref<string | null>(null);
const inputRef = ref<{ $el?: HTMLElement } | null>(null);

const hasError = computed(() => !!ctx.lineItemError(props.line, 'description'));

/** Focus the native textarea after the editor mounts — HTML `autofocus` only
 *  runs on page load, not on later mounts. */
const focusInput = async () => {
	await nextTick();
	inputRef.value?.$el?.querySelector('textarea')?.focus();
};

const start = () => {
	value.value = props.line.description;
	editing.value = true;
	void focusInput();
};

// Commit on blur, revert on Esc (§6.3). Enter inserts a newline (textarea),
// so it is not wired to commit the way a single-line input would be; the
// `editing` guard keeps the blur that follows an Esc from re-committing.
const commit = () => {
	if (!editing.value) return;
	editing.value = false;
	ctx.updateLineItem(props.line, { description: value.value ?? '' });
};

const revert = () => {
	editing.value = false;
};
</script>
```

### EditableQuantityCell.vue

```vue
<!-- InvoiceForm/EditableQuantityCell.vue -->
<template>
	<BbNumberInput
		v-if="editing"
		ref="inputRef"
		v-model="value"
		class="[&_input]:text-right"
		compact
		:errors="ctx.lineItemError(line, 'quantity')"
		hide-label
		label="Quantity"
		:max-precision="2"
		:min="0"
		@blur="commit"
		@keydown.enter.prevent="commit"
		@keydown.esc="revert"
	>
		<!-- Outer steppers: mousedown.prevent keeps focus in the field so blur
		     doesn't commit/unmount before the click lands. -->
		<template #prepend-outer="{ decrease }">
			<BbButton
				aria-label="Decrease quantity"
				icon="lucide:minus"
				size="xs"
				variant="ghost"
				@click="decrease"
				@mousedown.prevent
			/>
		</template>
		<template #append-outer="{ increase }">
			<BbButton
				aria-label="Increase quantity"
				icon="lucide:plus"
				size="xs"
				variant="ghost"
				@click="increase"
				@mousedown.prevent
			/>
		</template>
	</BbNumberInput>
	<button
		v-else
		class="w-full rounded-[var(--bb-radius)] px-1 py-0.5 text-right tabular-nums hover:bg-[color:var(--bb-hover)]"
		:class="{ 'text-[color:var(--bb-danger)]': hasError }"
		type="button"
		@click="start"
	>
		{{ line.quantity }}
	</button>
</template>

<script setup lang="ts">
import { computed, nextTick, ref } from 'vue';
import { BbButton, BbNumberInput } from 'bitboss-ui';
import { useInvoiceForm } from './context';
import type { LineItemDraft } from '@/types';

const props = defineProps<{ line: LineItemDraft }>();

const ctx = useInvoiceForm();

const editing = ref(false);
const value = ref<number | null>(null);
const inputRef = ref<{ $el?: HTMLElement } | null>(null);

const hasError = computed(() => !!ctx.lineItemError(props.line, 'quantity'));

/** Focus the native input after the editor mounts — HTML `autofocus` only
 *  runs on page load, not on later mounts. */
const focusInput = async () => {
	await nextTick();
	inputRef.value?.$el?.querySelector('input')?.focus();
};

const start = () => {
	value.value = props.line.quantity;
	editing.value = true;
	void focusInput();
};

const commit = () => {
	if (!editing.value) return;
	editing.value = false;
	// An emptied field emits null — treat it as a revert, not a zero.
	if (value.value === null) return;
	ctx.updateLineItem(props.line, { quantity: value.value });
};

const revert = () => {
	editing.value = false;
};
</script>
```

### EditableRateCell.vue

```vue
<!-- InvoiceForm/EditableRateCell.vue -->
<template>
	<BbNumberInput
		v-if="editing"
		ref="inputRef"
		v-model="value"
		class="[&_input]:text-right"
		compact
		:errors="ctx.lineItemError(line, 'unitPrice')"
		hide-label
		label="Unit price"
		:max-precision="2"
		:min="0"
		@blur="commit"
		@keydown.enter.prevent="commit"
		@keydown.esc="revert"
	>
		<template #prefix>$</template>
	</BbNumberInput>
	<button
		v-else
		class="w-full rounded-[var(--bb-radius)] px-1 py-0.5 text-right tabular-nums hover:bg-[color:var(--bb-hover)]"
		:class="{ 'text-[color:var(--bb-danger)]': hasError }"
		type="button"
		@click="start"
	>
		{{ currency.format(line.unitPrice) }}
	</button>
</template>

<script setup lang="ts">
import { computed, nextTick, ref } from 'vue';
import { BbNumberInput } from 'bitboss-ui';
import { useInvoiceForm } from './context';
import type { LineItemDraft } from '@/types';

const props = defineProps<{ line: LineItemDraft }>();

const ctx = useInvoiceForm();

const editing = ref(false);
const value = ref<number | null>(null);
const inputRef = ref<{ $el?: HTMLElement } | null>(null);

const hasError = computed(() => !!ctx.lineItemError(props.line, 'unitPrice'));

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});

/** Focus the native input after the editor mounts — HTML `autofocus` only
 *  runs on page load, not on later mounts. */
const focusInput = async () => {
	await nextTick();
	inputRef.value?.$el?.querySelector('input')?.focus();
};

const start = () => {
	value.value = props.line.unitPrice;
	editing.value = true;
	void focusInput();
};

const commit = () => {
	if (!editing.value) return;
	editing.value = false;
	if (value.value === null) return;
	ctx.updateLineItem(props.line, { unitPrice: value.value });
};

const revert = () => {
	editing.value = false;
};
</script>
```

### NotesSection.vue

```vue
<!-- InvoiceForm/NotesSection.vue -->
<template>
	<section class="flex flex-col gap-2">
		<!-- BbCollapsible ships no trigger: this button owns the disclosure
		     ARIA (`aria-expanded` + `aria-controls`). -->
		<BbButton
			append:icon="lucide:chevron-down"
			aria-controls="invoice-notes"
			:aria-expanded="open"
			class="self-start"
			variant="ghost"
			@click="open = !open"
		>
			Notes &amp; terms
		</BbButton>

		<!-- `eager` mounts the fields up front so their 422 errors render even
		     if the user never opened the section. Spacing lives on the inner
		     content — the collapsible zeroes its own box when closed. -->
		<BbCollapsible id="invoice-notes" v-model="open" eager>
			<div class="flex flex-col gap-4 pt-1">
				<BbTextarea
					v-model="ctx.draft.notes"
					auto-grow
					description="Shown on the invoice, under the line items."
					:errors="ctx.errors.value.notes"
					label="Notes to the customer"
					placeholder="Second milestone of the relaunch engagement…"
					:rows="2"
				/>
				<BbTextarea
					v-model="ctx.draft.terms"
					auto-grow
					description="Payment terms printed in the invoice footer."
					:errors="ctx.errors.value.terms"
					label="Terms"
					placeholder="Payment due within 30 days…"
					:rows="2"
				/>
			</div>
		</BbCollapsible>
	</section>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbButton, BbCollapsible, BbTextarea } from 'bitboss-ui';
import { useInvoiceForm } from './context';

const ctx = useInvoiceForm();

// Rung 1: only this section cares whether it is open. The section mounts
// after the invoice loaded (Index gates on ctx.loaded), so seeding from the
// draft starts an annotated invoice open and a blank one closed.
const open = ref(ctx.draft.notes !== null || ctx.draft.terms !== null);
</script>
```

### FormActions.vue

```vue
<!-- InvoiceForm/FormActions.vue -->
<template>
	<!-- Sticky action row: the commit affordance never scrolls away. Not the
	     floating bottom panel — that is selection chrome, and a form has no
	     selection. -->
	<div
		class="sticky bottom-0 z-10 -mx-4 flex items-center gap-3 border-t bg-[color:var(--bb-panel)] px-4 py-3"
	>
		<BbButton
			v-if="ctx.mode === 'edit'"
			prepend:icon="lucide:trash-2"
			variant="destructive"
			@click="ctx.deleteInvoice"
		>
			Delete
		</BbButton>
		<p
			v-if="ctx.isDirty.value"
			class="text-xs text-[color:var(--bb-text-muted)]"
		>
			Unsaved changes
		</p>

		<div class="ml-auto flex items-center gap-2">
			<!-- Cancel is navigation: the route-leave guard asks about a dirty
			     draft, so no bespoke confirm here. -->
			<BbButton :disabled="ctx.saving.value" to="/invoices" variant="ghost">
				Cancel
			</BbButton>
			<BbButton
				v-if="ctx.mode === 'create'"
				:disabled="ctx.saving.value"
				variant="outline"
				@click="ctx.saveAsDraft"
			>
				Save as draft
			</BbButton>
			<BbButton :loading="ctx.saving.value" type="submit" variant="primary">
				{{ ctx.mode === 'edit' ? 'Save changes' : 'Create invoice' }}
			</BbButton>
		</div>
	</div>
</template>

<script setup lang="ts">
import { BbButton } from 'bitboss-ui';
import { useInvoiceForm } from './context';

const ctx = useInvoiceForm();
</script>
```

### CustomerPeek.vue

```vue
<!-- InvoiceForm/CustomerPeek.vue -->
<template>
	<div v-if="customer" class="flex flex-col gap-4 text-sm">
		<header class="flex items-center gap-3">
			<BbAvatar :alt="customer.name" :src="customer.avatarUrl" />
			<div class="flex flex-col">
				<h2 class="text-base font-semibold">{{ customer.name }}</h2>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					{{ customer.email }} · {{ customer.country }}
				</p>
			</div>
		</header>

		<!-- Stat strip. -->
		<div class="grid grid-cols-3 gap-2">
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Total billed</p>
				<p class="font-semibold">{{ currency.format(customer.totalBilled) }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Outstanding</p>
				<p class="font-semibold">{{ currency.format(customer.outstanding) }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Invoices</p>
				<p class="font-semibold">{{ customer.invoiceCount }}</p>
			</div>
		</div>

		<!-- Billing profile: exactly the fields this form negotiates. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Billing profile
			</h3>
			<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
				<dt class="text-[color:var(--bb-text-muted)]">Default terms</dt>
				<dd>{{ customer.defaultPaymentTerms }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Default tax rate</dt>
				<dd>{{ customer.defaultTaxRate }}%</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Tax ID</dt>
				<dd>{{ customer.taxId }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Billing email</dt>
				<dd>{{ customer.billingEmail }}</dd>
			</dl>
			<!-- The peek acts on the form: this writes into the draft. -->
			<BbButton
				class="mt-1 self-start"
				prepend:icon="lucide:sparkles"
				size="sm"
				variant="secondary"
				@click="() => ctx.applyCustomerDefaults(customer!)"
			>
				Apply billing defaults
			</BbButton>
		</section>

		<!-- Recent invoices: real links — leaving a dirty draft still goes
		     through the route-leave guard. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Recent invoices
			</h3>
			<ul class="flex flex-col">
				<li
					v-for="recent in customer.recentInvoices"
					:key="recent.id"
					class="flex items-center justify-between gap-2 border-b py-1.5 last:border-b-0"
				>
					<BbBaseButton class="plain-link" :to="`/invoices/${recent.id}`">
						{{ recent.number }}
					</BbBaseButton>
					<BbBadge variant="outline">{{ recent.status }}</BbBadge>
					<span class="text-xs tabular-nums text-[color:var(--bb-text-muted)]">
						{{ currency.format(recent.amount) }}
					</span>
				</li>
			</ul>
		</section>

		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				append:icon="lucide:arrow-up-right"
				size="sm"
				:to="`/customers/${customer.id}`"
				variant="ghost"
			>
				Open customer
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { ref, watchEffect } from 'vue';
import { BbAvatar, BbBadge, BbButton, BbSpinner } from 'bitboss-ui';
import { useInvoiceForm } from './context';
import { api } from '@/api';
import type { CustomerDetail } from '@/types';

const props = defineProps<{ customerId: number }>();

const ctx = useInvoiceForm();

const customer = ref<CustomerDetail | null>(null);
watchEffect(async () => {
	customer.value = await api.customers.getDetail(props.customerId);
});

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
</script>
```

## Why it is built this way

- **The context coopts, leaves consume.** The shell is joined once in
  `provideInvoiceForm()`; ten components share the draft, the errors, the
  peek stack and every action through one `useInvoiceForm()` call. The only
  props on the page are data-identity props: the cells' `line` and the
  peek's `customer-id`. Notably there is **no table context** here — the
  line-items table has no selection, no paging and no fetch; its entire
  state _is_ the draft, so there is nothing for a `useBbTableContext`
  handle to carry.
- **The draft is the mutation boundary.** On a workspace page every action
  hits the API; on a form the unsaved state is the product. Cell commits,
  line add/duplicate/remove and "apply billing defaults" therefore mutate
  `ctx.draft` (still context actions — leaves never reach around it), and
  the single `persist()` call is where the API, the 422 mapping, the toast
  and the snapshot re-baseline live.
- **422 keys are the server's shape, not reshaped.** Scalar inputs bind
  `ctx.errors.value.<field>` directly; row errors keep their
  `lineItems.<index>.<field>` keys and the cells resolve them through
  `lineItemError`, which derives the index from the row's id — so the
  lookup survives the page-search filter reordering what is visible.
- **Tied selects trust the machinery.** `dependencies: [draft.customerId]`
  re-runs the project provider, `enforce-coherence` prunes a stale pick,
  and both providers honor the prefill contract (return the selected
  record on component-initiated calls) so a valid selection is never
  wiped — the exact failure mode the BbSelect guide warns about.
- **The inline-edit grammar is three tiny leaves, not one configurable
  cell.** Each editable cell owns rung-1 state (`editing`, the in-flight
  value), commits on blur/Enter and reverts on Esc. Enter is
  `.prevent`-ed so it commits the cell instead of submitting the enclosing
  form, and the `editing` guard keeps the unmount blur after an Esc from
  re-committing the reverted value.
- **The dirty snapshot re-baselines before every self-inflicted
  navigation** — successful save, draft save, delete — so the
  `onBeforeRouteLeave` confirm fires only when the user genuinely walks
  away. Cancel is a plain `to` link for the same reason: the guard _is_ the
  confirm, so the button needs none of its own.
- **A sticky action row, not the floating bottom panel.** The panel from
  the guides is selection-driven chrome that comes and goes; a form's
  commit affordance must be permanently visible, so it is a sticky row on
  the page surface (`--bb-panel` background, top border) hosting the one
  `variant="primary"` of the page.
- **Sizing:** the form fields are full-height — a form is not a dense
  surface. `compact` appears where density is real: the topbar search, the
  line-items table and its cell inputs. `sm` buttons appear only in the
  table's row actions, the "View customer" link and the peek; everything
  in the sticky row is default `md`.
- **Destructive actions ride `useConfirm`** — delete and the leave guard
  both — and the peek is a workbench: it acts on the draft and links out
  with real `to` links, never `@click` + router.

## Variations

- **Inside a `BbDialog`** (quick create from the invoices workspace): drop
  the route guard and breadcrumbs, keep `isDirty`, confirm on the dialog's
  close instead, and move the action row into the dialog `#footer` — the
  context and sections carry over unchanged.
- **Autosave drafts**: debounce a watcher on `draft` that calls
  `persist('draft')` silently and re-baselines per save; the "Save as
  draft" button disappears and the sticky row shows "Saved 12s ago".
- **Client-side pre-validation**: validate required fields on submit
  before calling the API and merge the messages into the same `errors`
  map — the inputs cannot tell the difference, which is the point.
- **Per-line tax**: add an `EditableTaxCell` per row (its own leaf, per
  the no-API-monster rule) and group the totals block by rate.
- **Send flow**: the primary becomes "Save and send" and opens a
  `BbDialog` preview (recipient, subject, PDF) whose open-state lives on
  the context, before persisting with `status: 'pending'`.
- **Per-field persistence**: this page deliberately has no per-cell save
  feedback because no per-cell save exists — the draft is the mutation
  boundary and Save is the one commit. When the domain wants every field
  to persist itself (no Save button), that is the autosave pattern: see
  the [Inline Edit Playbook](../../guides/inline-edit-playbook.md) and
  the inline-edit-workspace recipe.

## Related

- [Records Workspace (Vue)](./records-workspace.md) — the listing page
  this form is reached from.
- [Page Shell](../../guides/page-shell.md) — the app-side layout the
  customer peek renders inside.
- [BbTable](../../BbTable.md), [BbSelect](../../BbSelect.md),
  [BbCollapsible](../../BbCollapsible.md) — the components this page
  leans on hardest.

---

<!-- dist/ai/recipes/vue/records-workspace.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/vue/records-workspace.md -->

# Recipe: Records Workspace (Vue)

The flagship advanced-page recipe: a Stripe-invoices × Linear list workspace
for a **plain Vue SPA with vue-router**. Every row of the standard anatomy —
app chrome, breadcrumbs + page search, chip filter rail (one Filters menu + editable filter chips), href tabs with live
counts, a dense server-paged table, a floating bulk-action bar, and a
stacked peek sidebar — wired through one coopting page context so every leaf
component takes zero props beyond the record it renders.

Sibling recipes: [Nuxt](../nuxt/records-workspace.md) ·
[Inertia](../inertia/records-workspace.md).

## Prerequisites

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell`, `usePageShellContext` and `FloatingBottomPanel` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
- `<BbConfirm />` and `<BbToast />` mounted once in the app root (`App.vue`) — never in a page.
- [App Layout](../../guides/app-layout.md), [Page Shell](../../guides/page-shell.md)
  and [Floating Bottom Panel](../../guides/floating-bottom-panel.md) copied
  into `src/components/layout/` per their guides — every recipe page assumes
  this chrome exists and renders inside it.

## Key ideas

- **One coopting page context.** `provideInvoicesWorkspace()` joins the
  page-shell stack and the table context once, owns filters/tab/dialogs,
  and exposes complete actions. Every leaf calls `useInvoicesWorkspace()`
  and nothing else — zero prop drilling anywhere on the page.
- **The table is driven entirely through its context.** No selection
  v-models, no page refs: the context handle seeds `perPage`, the fetch
  writes `totalItems`, `BbPagination` joins by `table-id`, and the bulk bar
  reads the same handle.
- **Tabs are URL filters.** `BbTabs` items carry `href` (`?tab=paid`) and
  live counts; the active tab is one more dependency of the fetch.
- **Clicking the name of a thing peeks it.** Invoice number → invoice peek
  (fresh stack); customer name — in a row or inside a peek — → customer
  peek **stacked** with a back arrow. Peeks are workbenches: status
  control, properties, line items, activity, payments.
- **One Filters menu, one chip per applied facet.** A single `BbDropdown`
  (`BbDropdown.md` § Nested submenus + § Selectable groups) nests category →
  selectable/searchable group (Status, Customer); one chip per APPLIED facet
  — never one per value — renders below it, each a small `BbDropdown` scoped
  to that same group via an external `activator` ref, reading its label from
  `useBbDropdownContext` so it never re-fetches what the menu already
  resolved. **Never** `BbSelectPopover` + an imperative `ref.open()`: it
  exposes nothing to call, and its floating mode closes an
  `sr-only`/off-screen activator the instant it opens. Due date is a
  free-form range, not a discrete facet, so it stays its own compact
  `BbDatePickerInput` pill with a clear-all that renders only while something
  is active.
- **Buttons are `md` by default** (28px, flush beside `compact` inputs);
  `sm` only in the table rows, the peeks' headers and the bottom bar.

- **Spread the filters object into `dependencies`.** `BbTable` hash-compares
  `dependencies`; it does not deep-watch them. Passing the reactive `filters`
  proxy itself tracks only its identity — which never changes — so the table
  never refetches. `{ ...ctx.filters }` reads every field during render, so any
  field change yields a new, differently-hashed array. Read `.value` off the
  refs for the same reason: context members are not auto-unwrapped in a template.

## Page anatomy

```
InvoicesWorkspace/
	Index.vue               ← assembly: PageShell slots, table, tabs, pagination
	context.ts               ← coopting page context (shell + table + filters + actions)
	FilterRail.vue           ← one Filters menu + one chip per applied facet
	FilterChip.vue           ← applied-facet chip — itself a dropdown onto the same filter
	StatusCell.vue           ← one-click status change (badge → BbSelectPopover)
	RowActions.vue           ← per-row "…" dropdown
	SelectionBar.vue         ← bulk actions in the floating bottom panel
	InvoicePeek.vue          ← sidebar workbench, stack level 1
	CustomerPeek.vue         ← stacked peek, back arrow via the shell
	RecordPaymentDialog.vue  ← page-level dialog, driven by the context
```

Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
(left nav + fat footer), [Page Shell](../../guides/page-shell.md),
[Floating Bottom Panel](../../guides/floating-bottom-panel.md).

## Action inventory

| #   | Action                   | Trigger                          | Mechanism                                                                                      |
| --- | ------------------------ | -------------------------------- | ---------------------------------------------------------------------------------------------- |
| 1   | New invoice              | topbar, the page's one `primary` | navigation (`/invoices/create`)                                                                |
| 2   | Page search              | topbar right                     | `filters.search` → fetch dependency                                                            |
| 3   | Filter status / customer | Filters menu + filter chips      | `BbDropdown` nested facets; chip = small scoped `BbDropdown` on the same group                 |
| 3b  | Filter due date          | date-range pill                  | `BbDatePickerInput` range — not a Filters-menu facet                                           |
| 4   | Clear a filter           | chip clear button / date pill    | badge `@click:clear` (status/customer) or input `clearable` (due) — one at a time, no bulk CTA |
| 5   | Switch tab               | href tabs with counts            | URL + fetch dependency                                                                         |
| 6   | Peek invoice             | invoice number cell / peek lists | `peekInvoice(id)` → shell stack                                                                |
| 7   | Peek customer (stacked)  | customer cell / inside peeks     | `stackCustomer(id)` → back arrow                                                               |
| 8   | Change status inline     | status badge in row & peek       | one-click `BbSelectPopover`                                                                    |
| 9   | Record payment           | row `…`, peek button             | `BbDialog` via `ctx.dialogs`                                                                   |
| 10  | Edit / duplicate         | row `…` dropdown                 | navigation / context action                                                                    |
| 11  | Archive / delete         | row `…`, bulk bar                | destructive behind `useConfirm`                                                                |
| 12  | Bulk mark paid / remind  | floating bottom panel            | context actions on `table.selected`                                                            |
| 13  | Select rows / select all | table checkboxes                 | table context                                                                                  |
| 14  | Open full invoice        | peek footer                      | navigation (`/invoices/:id`)                                                                   |
| 15  | Back / close peek        | shell chrome                     | shell stack pop / close                                                                        |

## The code

### context.ts

```ts
// InvoicesWorkspace/context.ts
import {
	computed,
	inject,
	provide,
	reactive,
	ref,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import {
	useBbTableContext,
	useConfirm,
	useToast,
	type BbTableContext,
} from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import { api } from '@/api';
import type { Invoice, InvoiceStatus, PaymentDraft } from '@/types';

/**
 * What the stacked sidebar can show — a discriminated union of EVERY related
 * type the rows and the peeks expose, so one shell serves the whole consult.
 * `label` rides along because `#sidebar-title` has to name the top of the
 * stack before that record's own fetch has resolved.
 */
export type PeekItem =
	| { type: 'invoice'; id: number; label: string }
	| { type: 'customer'; id: number; label: string };

export type WorkspaceTab = 'all' | 'outstanding' | 'paid' | 'archived';

export interface InvoiceFilters {
	search: string;
	status: InvoiceStatus[];
	customerId: number | null;
	/**
	 * `[start, end]` ISO strings, or `[]` when unset. Range mode requires an
	 * array modelValue -- binding `null` throws, so the empty filter is `[]`.
	 */
	dueBetween: string[];
}

export interface InvoicesWorkspaceContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	table: BbTableContext;
	// -- Page-owned state ------------------------------------------------------
	filters: InvoiceFilters;
	hasActiveFilters: ComputedRef<boolean>;
	tab: Ref<WorkspaceTab>;
	tabCounts: Ref<Record<WorkspaceTab, number>>;
	refreshKey: Ref<number>;
	dialogs: { recordPayment: Ref<Invoice | null> };
	// -- Data ------------------------------------------------------------------
	fetchInvoices: () => Promise<Invoice[]>;
	// -- Peek grammar ----------------------------------------------------------
	peekInvoice: (id: number) => void;
	stackInvoice: (id: number) => void;
	stackCustomer: (id: number) => void;
	// -- Actions (complete: API + refresh + toast) ------------------------------
	clearFilters: () => void;
	updateStatus: (invoice: Invoice, status: InvoiceStatus) => Promise<void>;
	duplicateInvoice: (invoice: Invoice) => Promise<void>;
	recordPayment: (invoice: Invoice, draft: PaymentDraft) => Promise<void>;
	archiveInvoice: (invoice: Invoice) => Promise<void>;
	deleteInvoice: (invoice: Invoice) => Promise<void>;
	bulkMarkPaid: () => Promise<void>;
	bulkRemind: () => Promise<void>;
	bulkArchive: () => Promise<void>;
}

const key: InjectionKey<InvoicesWorkspaceContext> =
	Symbol('invoices-workspace');

export function provideInvoicesWorkspace(): InvoicesWorkspaceContext {
	const { toast } = useToast();
	const { confirm } = useConfirm();

	// -- Coopt the specific contexts: once, here, for the whole page. ----------
	const shell = usePageShellContext<PeekItem>();
	const table = useBbTableContext('invoices-table', { perPage: 25 });

	// -- Page state -------------------------------------------------------------
	const filters = reactive<InvoiceFilters>({
		search: '',
		status: [],
		customerId: null,
		dueBetween: [],
	});
	const hasActiveFilters = computed(
		() =>
			filters.search !== '' ||
			filters.status.length > 0 ||
			filters.customerId !== null ||
			filters.dueBetween.length > 0
	);
	const tab = ref<WorkspaceTab>('all');
	const tabCounts = ref<Record<WorkspaceTab, number>>({
		all: 0,
		outstanding: 0,
		paid: 0,
		archived: 0,
	});
	const refreshKey = ref(0);
	const dialogs = { recordPayment: ref<Invoice | null>(null) };

	const clearFilters = () => {
		filters.search = '';
		filters.status = [];
		filters.customerId = null;
		filters.dueBetween = [];
	};

	// -- Data ---------------------------------------------------------------------
	// The one place the list is fetched. Writes the paging totals into the
	// table context and keeps the tab counts live.
	const fetchInvoices = async (): Promise<Invoice[]> => {
		const response = await api.invoices.list({
			...filters,
			tab: tab.value,
			page: table.page.value,
			perPage: table.perPage.value,
		});
		table.totalItems.value = response.total;
		tabCounts.value = response.tabCounts;
		return response.data;
	};

	// -- Peek grammar ----------------------------------------------------------------
	// peekX opens a fresh stack (from the list); stackX drills down (from a peek).
	// `peek` opens a fresh top-level peek (a row click); `stackItem` drills from
	// the open one, keeping the back arrow. Named intents beat `push(item, true)`,
	// whose boolean silently resets a stack you meant to drill into.
	const peekInvoice = (id: number, label: string) =>
		shell.peek({ type: 'invoice', id, label });
	const stackInvoice = (id: number, label: string) =>
		shell.stackItem({ type: 'invoice', id, label });
	const stackCustomer = (id: number, label: string) =>
		shell.stackItem({ type: 'customer', id, label });

	// -- Actions --------------------------------------------------------------------
	const refresh = () => {
		refreshKey.value++;
	};

	const updateStatus = async (invoice: Invoice, status: InvoiceStatus) => {
		await api.invoices.update(invoice.id, { status });
		refresh();
		toast({
			title: `${invoice.number} moved to ${status}.`,
			variant: 'success',
		});
	};

	const duplicateInvoice = async (invoice: Invoice) => {
		const copy = await api.invoices.duplicate(invoice.id);
		refresh();
		toast({ title: `Duplicated as ${copy.number}.`, variant: 'success' });
	};

	const recordPayment = async (invoice: Invoice, draft: PaymentDraft) => {
		await api.invoices.recordPayment(invoice.id, draft);
		dialogs.recordPayment.value = null;
		refresh();
		toast({
			title: `Payment recorded on ${invoice.number}.`,
			variant: 'success',
		});
	};

	const archiveInvoice = async (invoice: Invoice) => {
		await api.invoices.archive(invoice.id);
		refresh();
		toast({ title: `${invoice.number} archived.`, variant: 'success' });
	};

	const deleteInvoice = async (invoice: Invoice) => {
		const ok = await confirm({
			variant: 'destructive',
			title: 'Delete invoice',
			text: `Delete ${invoice.number}? This cannot be undone.`,
			yes: 'Delete',
			no: 'Cancel',
		});
		if (!ok) return;
		await api.invoices.delete(invoice.id);
		refresh();
		toast({ title: `${invoice.number} deleted.`, variant: 'success' });
	};

	// Bulk actions read and clear the coopted table context themselves.
	const bulkIds = (): number[] => table.selected.value;
	const clearSelection = () => {
		table.selected.value = [];
	};

	const bulkMarkPaid = async () => {
		const ids = bulkIds();
		await api.invoices.markPaidMany(ids);
		clearSelection();
		refresh();
		toast({
			title: `${ids.length} invoices marked as paid.`,
			variant: 'success',
		});
	};

	const bulkRemind = async () => {
		const ids = bulkIds();
		await api.invoices.remindMany(ids);
		clearSelection();
		toast({
			title: `Reminder sent for ${ids.length} invoices.`,
			variant: 'success',
		});
	};

	const bulkArchive = async () => {
		const ids = bulkIds();
		const ok = await confirm({
			variant: 'destructive',
			title: 'Archive invoices',
			text: `Archive ${ids.length} invoices? They move out of every tab except Archived.`,
			yes: 'Archive',
			no: 'Cancel',
		});
		if (!ok) return;
		await api.invoices.archiveMany(ids);
		clearSelection();
		refresh();
		toast({ title: `${ids.length} invoices archived.`, variant: 'success' });
	};

	const ctx: InvoicesWorkspaceContext = {
		shell,
		table,
		filters,
		hasActiveFilters,
		tab,
		tabCounts,
		refreshKey,
		dialogs,
		fetchInvoices,
		peekInvoice,
		stackInvoice,
		stackCustomer,
		clearFilters,
		updateStatus,
		duplicateInvoice,
		recordPayment,
		archiveInvoice,
		deleteInvoice,
		bulkMarkPaid,
		bulkRemind,
		bulkArchive,
	};
	provide(key, ctx);
	return ctx;
}

export function useInvoicesWorkspace(): InvoicesWorkspaceContext {
	const ctx = inject(key);
	if (!ctx)
		throw new Error('useInvoicesWorkspace() called outside InvoicesWorkspace');
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- InvoicesWorkspace/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left, page search + primary action right. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs
					class="min-w-0 flex-auto"
					:items="[
						{ key: 'dashboard', text: 'Dashboard', to: '/dashboard' },
						{ key: 'billing', text: 'Billing', to: '/billing' },
						{ key: 'invoices', text: 'Invoices' },
					]"
				/>
				<div class="flex shrink-0 items-center gap-2">
					<BbTextInput
						v-model="ctx.filters.search"
						autocomplete="off"
						hide-label
						label="Search invoices"
						clearable
						compact
						placeholder="Search number or customer…"
						prepend:icon="lucide:search"
					/>
					<BbButton
						prepend:icon="lucide:plus"
						to="/invoices/create"
						variant="primary"
					>
						New invoice
					</BbButton>
				</div>
			</div>
		</template>

		<div class="flex flex-col gap-3 p-4">
			<FilterRail />

			<!-- Tabs as URL filters: href updates the query, the key feeds the
			     fetch. Counts come from the server on every fetch. -->
			<BbTabs
				v-model="ctx.tab.value"
				compact
				:items="[
					{
						key: 'all',
						label: `All · ${ctx.tabCounts.value.all}`,
						href: '?tab=all',
					},
					{
						key: 'outstanding',
						label: `Outstanding · ${ctx.tabCounts.value.outstanding}`,
						href: '?tab=outstanding',
					},
					{
						key: 'paid',
						label: `Paid · ${ctx.tabCounts.value.paid}`,
						href: '?tab=paid',
					},
					{
						key: 'archived',
						label: `Archived · ${ctx.tabCounts.value.archived}`,
						href: '?tab=archived',
					},
				]"
			/>

			<BbTable
				id="invoices-table"
				actions
				caption="Invoices"
				:columns="columns"
				compact
				:dependencies="[
					{ ...ctx.filters },
					ctx.tab.value,
					ctx.refreshKey.value,
				]"
				:deps-debounce-time="300"
				item-value="id"
				:items="ctx.fetchInvoices"
				legend="Select invoices"
				loading-text="Loading invoices…"
				:row-class="rowClass"
				selectable
			>
				<!-- Clicking the NAME of a thing peeks it. `.plain-link`
				     (design-language.md § Guide helper) is the project-owned
				     inline-link class, not a BbButton variant: `link` keeps
				     button chrome and never flows/truncates like inline text
				     at cell width. -->
				<template #number="{ item, content }">
					<BbBaseButton
						class="plain-link"
						@click="() => ctx.peekInvoice(item.id, item.number)"
					>
						{{ content }}
					</BbBaseButton>
				</template>

				<template #customer_name="{ item, content }">
					<!-- A related name is an inline link, not a button: `BbButton`
					     (any variant) is padded and breaks the row's line-height. -->
					<BbBaseButton
						class="plain-link"
						@click="
							() => ctx.stackCustomer(item.customer.id, item.customer.name)
						"
					>
						{{ content }}
					</BbBaseButton>
				</template>

				<template #status="{ item }">
					<StatusCell :invoice="item" />
				</template>

				<template #actions="{ item }">
					<RowActions :invoice="item" />
				</template>

				<template #no-data>
					<div class="flex flex-col items-center gap-2 p-6 text-center">
						<p class="text-sm text-[color:var(--bb-text-muted)]">
							No invoices match
							{{
								ctx.hasActiveFilters.value ? 'the current filters' : 'this tab'
							}}.
						</p>
						<BbButton
							v-if="ctx.hasActiveFilters.value"
							variant="ghost"
							@click="ctx.clearFilters"
						>
							Clear filters
						</BbButton>
					</div>
				</template>
			</BbTable>

			<!-- Joins the table context by id: no page/totalPages wiring at all. -->
			<BbPagination table-id="invoices-table" />
		</div>

		<SelectionBar />

		<!-- The peek names itself: without `#sidebar-title` the shell opens with
		     back/close flanking empty space, and the entity name ends up as a
		     second title inside the body. It follows the TOP of the stack, so a
		     drill-down renames the chrome. -->
		<template #sidebar-title>{{ ctx.shell.current.value?.label }}</template>

		<!-- Stacked peek sidebar: the shell owns back/close; we render by type. -->
		<template #sidebar>
			<InvoicePeek
				v-if="ctx.shell.current.value?.type === 'invoice'"
				:invoice-id="ctx.shell.current.value.id"
			/>
			<CustomerPeek
				v-else-if="ctx.shell.current.value?.type === 'customer'"
				:customer-id="ctx.shell.current.value.id"
			/>
		</template>

		<template #dialogs>
			<RecordPaymentDialog />
		</template>
	</PageShell>
</template>

<script setup lang="ts">
import {
	BbBaseButton,
	BbBreadcrumbs,
	BbButton,
	BbPagination,
	BbTable,
	BbTabs,
	BbTextInput,
} from 'bitboss-ui';
import PageShell from '@/components/layout/PageShell.vue';
import { provideInvoicesWorkspace } from './context';
import CustomerPeek from './CustomerPeek.vue';
import FilterRail from './FilterRail.vue';
import InvoicePeek from './InvoicePeek.vue';
import RecordPaymentDialog from './RecordPaymentDialog.vue';
import RowActions from './RowActions.vue';
import SelectionBar from './SelectionBar.vue';
import StatusCell from './StatusCell.vue';
import type { Invoice } from '@/types';

const ctx = provideInvoicesWorkspace();

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
const shortDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
	});

const columns = [
	{ key: 'number', label: 'Invoice' },
	{ key: 'customer.name', label: 'Customer' },
	{
		key: 'amount',
		label: 'Amount',
		formatter: (value: number) => currency.format(value),
	},
	{ key: 'status', label: 'Status' },
	{ key: 'dueDate', label: 'Due', formatter: shortDate },
	{ key: 'issuedAt', label: 'Issued', formatter: shortDate },
];

// Overdue rows get a tinted background — public row-class API, no internals.
const rowClass = (item: Invoice) =>
	item.status === 'overdue' ? 'bg-red-50 dark:bg-red-950/20' : undefined;
</script>
```

### FilterRail.vue

```vue
<!-- InvoicesWorkspace/FilterRail.vue -->
<template>
	<div class="flex flex-wrap items-center gap-2">
		<!-- One Filters menu: nested category → selectable/searchable group.
		     Never one BbSelectPopover pill per facet — that component has no
		     `defineExpose`, so a chip can't `ref.open()` it, and its floating
		     mode auto-closes an off-screen/`sr-only` activator on open. -->
		<BbDropdown id="invoice-filters" :items="menu" :width="220">
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filters"
					prepend:icon="lucide:list-filter"
					size="sm"
					variant="outline"
				>
					Filters
				</BbButton>
			</template>
			<BbDropdownGroup id="status" v-model="ctx.filters.status" />
			<BbDropdownGroup id="customer" v-model="ctx.filters.customerId" />
		</BbDropdown>

		<!-- One chip per APPLIED facet — never one per value. See
		     FilterChip.vue: each chip is itself a small dropdown scoped to the
		     same group, reusing the exact descriptor declared below. -->
		<FilterChip
			v-if="ctx.filters.status.length"
			:group="statusGroup"
			group-key="status"
			label="Status"
			:model-value="ctx.filters.status"
			@update:model-value="
				(value) => (ctx.filters.status = value as InvoiceStatus[])
			"
		/>
		<FilterChip
			v-if="ctx.filters.customerId != null"
			:group="customerGroup"
			group-key="customer"
			label="Customer"
			:model-value="ctx.filters.customerId"
			@update:model-value="
				(value) => (ctx.filters.customerId = value as number | null)
			"
		/>

		<!-- Due date is a free-form range, not a discrete facet — its own
		     compact pill outside the Filters menu, no chip. A compact input
		     is 28px — flush with the sm Filters button's row. -->
		<BbDatePickerInput
			v-model="ctx.filters.dueBetween"
			hide-label
			label="Due date range"
			clearable
			compact
			placeholder="Due between…"
			range
		/>

		<!-- Clear-all is the LAST CHIP, not a ghost button floated to the far
		     end by `ml-auto`: it acts on the chips, so it belongs in their row
		     and at their scale. Keep the ghost "Clear filters" for the empty
		     state (`#no-data`), where there are no chips to sit beside. -->
		<BbBadge
			v-if="ctx.hasActiveFilters.value"
			clearable
			:clearable-label="`Clear all filters`"
			size="xl"
			variant="outline"
			@click:clear="ctx.clearFilters"
		>
			Clear all
		</BbBadge>
	</div>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import {
	BbBadge,
	BbButton,
	BbDatePickerInput,
	BbDropdown,
	BbDropdownGroup,
} from 'bitboss-ui';
import type { BbDropdownItem } from 'bitboss-ui';
import { useInvoicesWorkspace } from './context';
import FilterChip from './FilterChip.vue';
import { api } from '@/api';
import type { Customer, InvoiceStatus } from '@/types';

const ctx = useInvoicesWorkspace();

// Query-aware pipeline getter: called with the typed query because the group
// below sets `searchable: true` (same `(query, prefill, modelValue)` shape a
// BbSelect provider uses).
const searchCustomers = (query: string): Promise<Customer[]> =>
	api.customers.list({ search: query });

// Static enum facet: item text resolves synchronously, so its chip reads
// `useBbDropdownContext` (in FilterChip.vue) with zero extra fetch.
const statusGroup: BbDropdownItem = {
	key: 'status',
	label: 'Status',
	hideLabel: true,
	selectable: true,
	multiple: true,
	items: [
		{ key: 'draft', text: 'Draft' },
		{ key: 'pending', text: 'Pending' },
		{ key: 'paid', text: 'Paid' },
		{ key: 'overdue', text: 'Overdue' },
	],
};

// Pipeline facet: `prefill: true` resolves a picked customer's name eagerly,
// so a chip never sits on a bare id while this group's own submenu (inside
// the Filters menu) has never been opened. The eager flag belongs HERE, on
// the menu's copy only — the chip derives its own copy with
// `prefill: 'interaction'` (see FilterChip.vue), because a second dropdown
// redeclaring `prefill: true` would fetch every seeded facet twice on page
// load for nothing.
const customerGroup: BbDropdownItem = {
	key: 'customer',
	label: 'Customer',
	hideLabel: true,
	selectable: true,
	searchable: true,
	prefill: true,
	itemText: 'name',
	itemValue: 'id',
	items: searchCustomers,
};

// Top-level items are submenu openers; each nests exactly one selectable
// group ("nested category › searchable options" — BbDropdown.md § Nested
// submenus). `hideLabel` on the group skips a redundant inner heading since
// the category row already names the facet.
const menu = computed<BbDropdownItem[]>(() => [
	{
		key: 'status-category',
		text: 'Status',
		'prepend:icon': 'lucide:circle-dot',
		items: [statusGroup],
	},
	{
		key: 'customer-category',
		text: 'Customer',
		'prepend:icon': 'lucide:building-2',
		items: [customerGroup],
	},
]);
</script>
```

### FilterChip.vue

```vue
<!-- InvoicesWorkspace/FilterChip.vue -->
<template>
	<BbBadge
		clearable
		:clearable-label="`Remove ${label} filter`"
		size="xl"
		variant="secondary"
		@click:clear="onClear"
	>
		<BbBadgeButton ref="chipRef">{{ chipText }}</BbBadgeButton>
	</BbBadge>
	<!-- External `activator` (a template ref) — NEVER the `#activator` slot: a
	     component sitting between `BbBadge` and `BbBadgeButton` breaks the
	     badge's direct-child vnode scan (the companion must be a literal
	     child). This IS "the chip is itself a dropdown onto the same filter
	     group": `chipGroup` is derived from the exact descriptor FilterRail
	     declared (spread, one override — never redeclared), so this scoped
	     picker and the Filters menu's own submenu can never drift apart. -->
	<BbDropdown :activator="chipRef" :items="[chipGroup]" :width="220">
		<BbDropdownGroup
			:id="groupKey"
			:model-value="modelValue"
			@update:model-value="emit('update:modelValue', $event)"
		/>
	</BbDropdown>
</template>

<script setup lang="ts">
import { computed, useTemplateRef } from 'vue';
import {
	BbBadge,
	BbBadgeButton,
	BbDropdown,
	BbDropdownGroup,
	useBbDropdownContext,
} from 'bitboss-ui';
import type { BbDropdownItem } from 'bitboss-ui';

const props = defineProps<{
	/** Matches the group's `key` in the Filters menu, and its key in
	 * `useBbDropdownContext('invoice-filters').groups`. */
	groupKey: string;
	/** Static fallback/prefix text — the group itself sets `hideLabel`. */
	label: string;
	/** The SAME group descriptor passed to the Filters menu — not redeclared. */
	group: BbDropdownItem;
	modelValue: unknown;
}>();
const emit = defineEmits<{ 'update:modelValue': [value: unknown] }>();

const chipRef = useTemplateRef('chipRef');

// The chip's own copy of the shared descriptor, one override: `prefill:
// 'interaction'`. BbDropdown mounts a pipeline resolver for every group it
// declares at its own root, independent of the panel ever opening — so if
// this second dropdown repeated the menu's `prefill: true` verbatim, each
// seeded pipeline facet would be fetched TWICE on page load, and the chip's
// copy of the result would feed nothing (the label below comes from the
// menu's resolution via context). `'interaction'` defers this copy's fetch
// to the moment the chip's dropdown is actually opened. For static array
// facets the override is inert — arrays resolve synchronously either way.
const chipGroup = computed<BbDropdownItem>(() => ({
	...props.group,
	prefill: 'interaction',
}));

// Reads the Filters menu's already-resolved selection — no twin fetch. A
// pipeline group needs `prefill: true` (set on the MENU's copy of `group` by
// FilterRail) so this never sits on a bare id/value while the menu's own
// submenu is unopened.
const dropdownFilters = useBbDropdownContext('invoice-filters');
const chipText = computed(() => {
	const options =
		dropdownFilters.groups.value[props.groupKey]?.selectedOptions ?? [];
	if (!options.length) return props.label;
	return `${props.label}: ${options
		.map((option) => option.text ?? String(option.value))
		.join(', ')}`;
});

const onClear = () =>
	emit('update:modelValue', Array.isArray(props.modelValue) ? [] : null);
</script>
```

### StatusCell.vue

```vue
<!-- InvoicesWorkspace/StatusCell.vue -->
<template>
	<BbSelectPopover
		:items="['draft', 'pending', 'paid', 'overdue']"
		:model-value="invoice.status"
		width="180"
		@update:model-value="(status) => pick(status as InvoiceStatus)"
	>
		<template #activator="{ props: activatorProps }">
			<!-- The badge IS the trigger: BbBadgeButton turns the badge's own
			body into the button, so the pill is the hit target and draws its
			own focus ring — no wrapper element, no chrome class. The internal
			trailing chevron says "clickable"; while the save runs the badge's
			`loading` swaps the spinner into the chevron's place (§6.1
			niceties). -->
			<BbBadge
				append:icon="lucide:chevron-down"
				:loading="saving"
				variant="outline"
			>
				<BbBadgeButton
					:aria-label="`Change status for invoice ${invoice.number}`"
					v-bind="activatorProps"
					>{{ invoice.status }}</BbBadgeButton
				>
			</BbBadge>
		</template>
	</BbSelectPopover>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
import { useInvoicesWorkspace } from './context';
import type { Invoice, InvoiceStatus } from '@/types';

const props = defineProps<{ invoice: Invoice }>();

const ctx = useInvoicesWorkspace();

// In-flight flag for the save feedback — rung-1 local state, not context.
const saving = ref(false);
const pick = async (status: InvoiceStatus) => {
	saving.value = true;
	try {
		await ctx.updateStatus(props.invoice, status);
	} finally {
		saving.value = false;
	}
};
</script>
```

### RowActions.vue

```vue
<!-- InvoicesWorkspace/RowActions.vue -->
<template>
	<BbDropdown
		:items="[
			{
				key: 'edit',
				text: 'Edit',
				'prepend:icon': 'lucide:pencil',
				to: `/invoices/${invoice.id}/edit`,
			},
			{
				key: 'duplicate',
				text: 'Duplicate',
				'prepend:icon': 'lucide:copy',
				onClick: () => ctx.duplicateInvoice(invoice),
			},
			{
				key: 'payment',
				text: 'Record payment',
				'prepend:icon': 'lucide:banknote',
				onClick: () => (ctx.dialogs.recordPayment.value = invoice),
			},
			{
				key: 'archive',
				text: 'Archive',
				'prepend:icon': 'lucide:archive',
				onClick: () => ctx.archiveInvoice(invoice),
			},
			{
				key: 'delete',
				text: 'Delete',
				'prepend:icon': 'lucide:trash-2',
				variant: 'destructive',
				onClick: () => ctx.deleteInvoice(invoice),
			},
		]"
	>
		<template #activator="{ props }">
			<BbButton v-bind="props" icon="lucide:ellipsis" size="sm" variant="ghost">
				Invoice actions
			</BbButton>
		</template>
	</BbDropdown>
</template>

<script setup lang="ts">
import { BbButton, BbDropdown } from 'bitboss-ui';
import { useInvoicesWorkspace } from './context';
import type { Invoice } from '@/types';

defineProps<{ invoice: Invoice }>();

const ctx = useInvoicesWorkspace();
</script>
```

### SelectionBar.vue

```vue
<!-- InvoicesWorkspace/SelectionBar.vue -->
<template>
	<FloatingBottomPanel :open="selectedCount > 0">
		<span class="px-2 text-sm">{{ selectedCount }} selected</span>
		<BbButton
			prepend:icon="lucide:check"
			size="sm"
			variant="ghost"
			@click="ctx.bulkMarkPaid"
		>
			Mark as paid
		</BbButton>
		<BbButton
			prepend:icon="lucide:send"
			size="sm"
			variant="ghost"
			@click="ctx.bulkRemind"
		>
			Send reminder
		</BbButton>
		<div class="floating-bottom-panel__right flex items-center gap-1">
			<BbButton size="sm" variant="destructive" @click="ctx.bulkArchive"
				>Archive</BbButton
			>
			<BbButton
				aria-label="Clear selection"
				icon="lucide:x"
				size="sm"
				variant="ghost"
				@click="clearSelection"
			/>
		</div>
	</FloatingBottomPanel>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton } from 'bitboss-ui';
import FloatingBottomPanel from '@/components/layout/FloatingBottomPanel.vue';
import { useInvoicesWorkspace } from './context';

const ctx = useInvoicesWorkspace();

const selectedCount = computed(() => ctx.table.selected.value?.length ?? 0);
const clearSelection = () => {
	ctx.table.selected.value = [];
};
</script>
```

### InvoicePeek.vue

```vue
<!-- InvoicesWorkspace/InvoicePeek.vue -->
<template>
	<div v-if="invoice" class="flex flex-col gap-4 text-sm">
		<!-- Header: identity + one-click status + amount. -->
		<header class="flex flex-col gap-1.5">
			<div class="flex items-center justify-between gap-2">
				<h2 class="text-base font-semibold">{{ invoice.number }}</h2>
				<StatusCell :invoice="invoice" />
			</div>
			<p class="text-xl font-semibold">{{ currency.format(invoice.amount) }}</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				Issued {{ longDate(invoice.issuedAt) }} · due
				{{ longDate(invoice.dueDate) }}
			</p>
		</header>

		<!-- Properties: customer name drills DOWN — stacked peek, back arrow.
		     `.plain-link` (design-language.md § Guide helper), not a BbButton
		     variant — a property-grid value is inline text, not a button. -->
		<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
			<dt class="text-[color:var(--bb-text-muted)]">Customer</dt>
			<dd>
				<BbBaseButton
					class="plain-link"
					@click="
						() =>
							ctx.stackCustomer(invoice!.customer.id, invoice!.customer.name)
					"
				>
					{{ invoice.customer.name }}
				</BbBaseButton>
			</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Project</dt>
			<dd>{{ invoice.project.name }}</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Payment terms</dt>
			<dd>{{ invoice.paymentTerms }}</dd>
			<dt class="text-[color:var(--bb-text-muted)]">Reference</dt>
			<dd>{{ invoice.reference }}</dd>
		</dl>

		<!-- Line items: a real mini-table, not a summary sentence. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Line items
			</h3>
			<BbTable
				caption="Invoice line items"
				:columns="[
					{ key: 'description', label: 'Description' },
					{ key: 'quantity', label: 'Qty' },
					{
						key: 'total',
						label: 'Total',
						formatter: (value: number) => currency.format(value),
					},
				]"
				compact
				item-value="id"
				:items="invoice.lineItems"
			/>
		</section>

		<!-- Payments so far. -->
		<section v-if="invoice.payments.length" class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Payments
			</h3>
			<ul class="flex flex-col gap-1">
				<li
					v-for="payment in invoice.payments"
					:key="payment.id"
					class="flex items-center justify-between gap-2"
				>
					<span
						>{{ currency.format(payment.amount) }} · {{ payment.method }}</span
					>
					<span class="text-xs text-[color:var(--bb-text-muted)]">{{
						longDate(payment.paidAt)
					}}</span>
				</li>
			</ul>
		</section>

		<!-- Activity feed. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Activity
			</h3>
			<ul class="flex flex-col gap-2">
				<li
					v-for="entry in invoice.activity"
					:key="entry.id"
					class="flex gap-2"
				>
					<BbIcon
						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
						:icon="entry.icon"
						size="14"
					/>
					<div class="flex flex-col">
						<span>{{ entry.text }}</span>
						<span class="text-xs text-[color:var(--bb-text-muted)]"
							>{{ entry.actor }} · {{ longDate(entry.at) }}</span
						>
					</div>
				</li>
			</ul>
		</section>

		<!-- Peek is a workbench: act here, or leave for the full page. -->
		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				prepend:icon="lucide:banknote"
				size="sm"
				variant="secondary"
				@click="() => (ctx.dialogs.recordPayment.value = invoice)"
			>
				Record payment
			</BbButton>
			<BbButton
				append:icon="lucide:arrow-up-right"
				size="sm"
				:to="`/invoices/${invoice.id}`"
				variant="ghost"
			>
				Open full page
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { ref, watchEffect } from 'vue';
import { BbBaseButton, BbButton, BbIcon, BbSpinner, BbTable } from 'bitboss-ui';
import StatusCell from './StatusCell.vue';
import { useInvoicesWorkspace } from './context';
import { api } from '@/api';
import type { InvoiceDetail } from '@/types';

const props = defineProps<{ invoiceId: number }>();

const ctx = useInvoicesWorkspace();

// Re-fetches whenever the stack shows a different invoice; refreshKey makes
// mutations (status, payment) reflect here immediately.
const invoice = ref<InvoiceDetail | null>(null);
watchEffect(async () => {
	void ctx.refreshKey.value;
	invoice.value = await api.invoices.get(props.invoiceId);
});

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
const longDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
		year: 'numeric',
	});
</script>
```

### CustomerPeek.vue

```vue
<!-- InvoicesWorkspace/CustomerPeek.vue -->
<template>
	<div v-if="customer" class="flex flex-col gap-4 text-sm">
		<header class="flex items-center gap-3">
			<BbAvatar :alt="customer.name" :src="customer.avatarUrl" />
			<div class="flex flex-col">
				<h2 class="text-base font-semibold">{{ customer.name }}</h2>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					{{ customer.email }} · {{ customer.country }}
				</p>
			</div>
		</header>

		<!-- Stat strip. -->
		<div class="grid grid-cols-3 gap-2">
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Total billed</p>
				<p class="font-semibold">{{ currency.format(customer.totalBilled) }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Outstanding</p>
				<p class="font-semibold">{{ currency.format(customer.outstanding) }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Invoices</p>
				<p class="font-semibold">{{ customer.invoiceCount }}</p>
			</div>
		</div>

		<!-- Recent invoices: names drill down again — the stack keeps growing.
		     `.plain-link` (design-language.md § Guide helper), not a BbButton
		     variant — same identity-cell rule as the invoices table. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Recent invoices
			</h3>
			<ul class="flex flex-col">
				<li
					v-for="recent in customer.recentInvoices"
					:key="recent.id"
					class="flex items-center justify-between gap-2 border-b py-1.5 last:border-b-0"
				>
					<BbBaseButton
						class="plain-link"
						@click="() => ctx.stackInvoice(recent.id, recent.number)"
					>
						{{ recent.number }}
					</BbBaseButton>
					<BbBadge variant="outline">{{ recent.status }}</BbBadge>
					<span class="text-xs text-[color:var(--bb-text-muted)]">{{
						currency.format(recent.amount)
					}}</span>
				</li>
			</ul>
		</section>

		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				append:icon="lucide:arrow-up-right"
				size="sm"
				:to="`/customers/${customer.id}`"
				variant="ghost"
			>
				Open customer
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { ref, watchEffect } from 'vue';
import {
	BbAvatar,
	BbBadge,
	BbBaseButton,
	BbButton,
	BbSpinner,
} from 'bitboss-ui';
import { useInvoicesWorkspace } from './context';
import { api } from '@/api';
import type { CustomerDetail } from '@/types';

const props = defineProps<{ customerId: number }>();

const ctx = useInvoicesWorkspace();

const customer = ref<CustomerDetail | null>(null);
watchEffect(async () => {
	customer.value = await api.customers.getDetail(props.customerId);
});

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
</script>
```

### RecordPaymentDialog.vue

```vue
<!-- InvoicesWorkspace/RecordPaymentDialog.vue -->
<template>
	<BbDialog
		:model-value="invoice !== null"
		size="sm"
		:title="invoice ? `Record payment — ${invoice.number}` : ''"
		@update:model-value="close"
	>
		<form
			v-if="invoice"
			class="flex flex-col gap-3"
			novalidate
			@submit.prevent="submit"
		>
			<BbNumberInput
				v-model="draft.amount"
				label="Amount"
				label-mode="outside"
				:max-precision="2"
				:min="0"
			>
				<template #prefix>$</template>
			</BbNumberInput>
			<BbDatePickerInput
				v-model="draft.paidAt"
				label="Paid on"
				label-mode="outside"
			/>
			<BbSelect
				v-model="draft.method"
				:items="['bank transfer', 'card', 'check', 'cash']"
				label="Method"
				label-mode="outside"
			/>
			<div class="mt-1 flex justify-end gap-2">
				<BbButton type="button" variant="ghost" @click="close">Cancel</BbButton>
				<BbButton type="submit" variant="secondary">Record payment</BbButton>
			</div>
		</form>
	</BbDialog>
</template>

<script setup lang="ts">
import { computed, reactive, watch } from 'vue';
import {
	BbButton,
	BbDatePickerInput,
	BbDialog,
	BbNumberInput,
	BbSelect,
} from 'bitboss-ui';
import { useInvoicesWorkspace } from './context';
import type { PaymentDraft } from '@/types';

const ctx = useInvoicesWorkspace();

// The dialog's subject lives in the page context — any component on the
// page (row actions, the peek) can open it by assigning the invoice.
const invoice = computed(() => ctx.dialogs.recordPayment.value);
const close = () => {
	ctx.dialogs.recordPayment.value = null;
};

const draft = reactive<PaymentDraft>({
	amount: null,
	paidAt: null,
	method: null,
});
watch(invoice, (next) => {
	// Re-seed per invoice: default to paying the remaining balance today.
	draft.amount = next?.amountDue ?? null;
	draft.paidAt = next ? new Date().toISOString() : null;
	draft.method = null;
});

// Returning the promise lets the submit button track the async work.
const submit = () =>
	invoice.value ? ctx.recordPayment(invoice.value, { ...draft }) : undefined;
</script>
```

## Why it is built this way

- **The context coopts, leaves consume.** `shell` and `table` are joined
  once in `provideInvoicesWorkspace()`; nine components share filters,
  selection, the peek stack and every action through one
  `useInvoicesWorkspace()` call. No component on this page receives a
  callback prop, and only peeks/cells receive data props (the item or id
  they render).
- **The table context is the paging spine.** `useBbTableContext(id, { perPage })`
  seeds paging; `fetchInvoices` writes `table.totalItems`; `BbPagination
table-id` joins by id. Page state exists in exactly one place and the
  assembly wires none of it by hand.
- **`peekX` vs `stackX` is the whole stack grammar.** Fresh peeks replace,
  drill-downs push; the shell renders the back arrow when depth > 1. The
  grammar lives in the context — a leaf cannot accidentally nuke the
  stack.
- **Tabs carry `href` and live counts.** Client-side pushState keeps the
  URL shareable while `v-model` feeds the fetch; counts re-arrive with
  every fetch so tab labels never go stale.
- **Dialogs hang off the context** (`ctx.dialogs.recordPayment` holds the
  subject invoice, not a boolean) so row actions and the peek open the
  same dialog with zero coordination.
- **Sizing:** topbar and rail follow `md`-first (`compact` inputs at 28px
  flush beside the default buttons); `sm` appears exactly where the
  doctrine allows — row actions, pills, peek footers, the bulk bar.
- **One `variant="primary"`** (New invoice). Destructive actions —
  single, bulk, in-peek — all ride `useConfirm`.
- **The status badge tells you it saves.** `StatusCell` carries the §6.1
  niceties: an internal trailing chevron (a clickable status must say so)
  and `:loading` around the awaited context action, so the spinner takes
  the chevron's place while the save runs. The flag is a local `ref` —
  rung 1, not context state. The ownership grammar behind inline edits is
  the [Inline Edit Playbook](../../guides/inline-edit-playbook.md).

## Variations

- **Keyboard triage**: add `keyboard-navigation` to the table and open the
  peek from `v-model:highlighted` — the approvals-inbox recipe is the
  full treatment.
- **Saved views**: persist `filters` + `tab` per user in a store
  (`useSavedViewsStore`) and render a view switcher before the tabs.
- **Inline amount editing**: swap the amount cell for an
  `EditableAmountCell` per the inline-editing pattern. Choosing between
  explicit-commit cells and a fully autosaving grid is the
  [Inline Edit Playbook](../../guides/inline-edit-playbook.md); the
  autosave treatment is the inline-edit-workspace recipe.

### Tabs are lifecycle; chips are facets

The rail and the tab strip answer two different questions, and twinning them is
the fastest way to make a workspace feel arbitrary:

- **Tabs = one lifecycle segment.** Where the record _is_ in its own flow —
  All / Outstanding / Paid / Archived. Mutually exclusive, always visible,
  carrying the counts.
- **Chips = cross-cutting facets.** Anything that can apply to a record in any
  segment — customer, owner, due date, tag. Additive, and only rendered while
  applied.

Never expose the same dimension both ways: a `status` facet inside the Filters
menu next to a status tab strip lets the user set two conflicting answers to one
question, and neither control shows the other's state. If a dimension deserves
both roles (a lifecycle you also want to combine), pick one and give the other
distinct chrome — never the same values with different affordances.

**Rail anatomy** — one row, one scale:

| Slot                    | What                                                    |
| ----------------------- | ------------------------------------------------------- |
| `.filter-rail`          | the row itself: Filters trigger, chips, free-form pills |
| Filters trigger         | one `BbDropdown` of the _unapplied_ facets              |
| `.filter-rail__applied` | one chip per **applied facet** — never one per value    |
| free-form controls      | ranges (dates, amounts) that are not discrete facets    |
| clear-all               | the last chip in the row, same scale as the others      |

Sizes come from the pairing table in [BbBadge](../../BbBadge.md): the trigger
here is a `sm` button, so every chip in the row is `xl`.

## Conformance — a listing is done when

Peek, highlight and title are one feature; shipping two of the three leaves a
dead affordance behind. Before calling a records screen finished:

- [ ] **`v-model:highlighted` is wired both ways** — closing the peek clears
      the highlight, or the same row cannot reopen it (see the Layout
      Scaffold's sync section).
- [ ] **`#sidebar-title` is filled**, or the peek opens with back/close
      flanking empty space.
- [ ] **`#sidebar` renders every `PeekItem` branch** the union declares.
- [ ] **Related names stack** — `BbBaseButton` + `.plain-link` calling
      `stackItem`, never a padded `BbButton`, and never dead text.
- [ ] **The row highlight follows the root of the stack**, so drilling
      invoice → customer does not un-highlight the row the consult began on.

If a page genuinely has no peek, delete the shell wiring rather than leaving
`v-model:highlighted` painting rows that open nothing.

---

<!-- dist/ai/recipes/vue/upload-center.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/vue/upload-center.md -->

# Recipe: Upload Center (Vue)

An Expensify-grade expense receipts submission page for a **plain Vue SPA
with vue-router**, at full standard anatomy: a multi-file dropzone feeding
an inline-editable table, per-file upload progress with inline retry,
one-click category cells, bulk actions in the floating bottom panel, and a
stacked receipt/merchant peek sidebar.

Sibling recipes: [Nuxt](../nuxt/upload-center.md) ·
[Inertia](../inertia/upload-center.md).

## Prerequisites

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell`, `usePageShellContext` and `FloatingBottomPanel` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
- `<BbConfirm />` and `<BbToast />` mounted once in the app root (`App.vue`) — never in a page.
- [App Layout](../../guides/app-layout.md), [Page Shell](../../guides/page-shell.md)
  and [Floating Bottom Panel](../../guides/floating-bottom-panel.md) copied
  into `src/components/layout/` per their guides — every recipe page assumes
  this chrome exists and renders inside it.
- A `useCategoriesStore()` Pinia store exposing the shared expense-category
  catalog (Travel, Meals & entertainment, Lodging, Rideshare & transit,
  Software & subscriptions, Office supplies, Fuel, Client entertainment).
- The registered `soft-*` badge variants (`soft-gray` / `soft-amber` /
  `soft-green`) from the [Inline Edit Workspace](./inline-edit-workspace.md)
  recipe — the receipt-status maps in `context.ts` use them
  (design-language § Using color).

## Key ideas

- **One coopting page context.** `provideUploadCenter()` joins the
  page-shell stack and the table context once, coopts the shared category
  catalog from `useCategoriesStore()`, owns the filters, the tab, and the
  **upload queue**, and exposes complete actions. Every leaf calls
  `useUploadCenter()` and nothing else.
- **Capture and transfer are two layers.** `BbDropzone` only validates and
  hands over `File[]`; the context runs the uploads (AbortController +
  progress callback per file) and the dropzone leaf immediately drains its
  model into `ctx.enqueueFiles()`. The component never uploads — that is
  its documented contract.
- **The drafts table lists two kinds of rows.** In-flight/failed uploads
  (`kind: 'upload'`, local state) render above the server drafts
  (`kind: 'receipt'`, fetched). Progress ticks mutate the live row objects
  — no refetch per tick; only membership changes (enqueue, remove,
  completion) bump `refreshKey`.
- **Every draft cell edits in place.** Merchant is a text cell committing
  on blur/Enter (§6.3), category is a one-click badge popover (§6.1),
  amount is a `$`-prefixed number cell, date commits on pick. Each cell
  type is its own leaf with a single `receipt` prop; failed saves revert
  via refetch and toast destructive.
- **Tabs are URL filters.** Drafts / Submitted / Reimbursed carry `href`
  (`?tab=drafts`) and live counts from every fetch; the same table is the
  pane, read-only outside Drafts.
- **Clicking the name of a thing peeks it.** Filename → receipt peek
  (fresh stack) with preview placeholder, extracted OCR fields and
  activity; the merchant name inside the peek → merchant peek **stacked**
  with a back arrow, whose recent receipts drill back down.
- **Buttons are `md` by default**; `sm`/`xs` only in the table rows, the
  filter pills, the peek footers and the bottom bar. One
  `variant="primary"`: **Submit all** with its live count.

- **Spread the filters object into `dependencies`.** `BbTable` hash-compares
  `dependencies`; it does not deep-watch them. Passing the reactive `filters`
  proxy itself tracks only its identity — which never changes — so the table
  never refetches. `{ ...ctx.filters }` reads every field during render, so any
  field change yields a new, differently-hashed array. Read `.value` off the
  refs for the same reason: context members are not auto-unwrapped in a template.

## Page anatomy

```
UploadCenter/
	Index.vue              ← assembly: PageShell slots, dropzone, tabs, table, pagination
	context.ts              ← coopting page context (shell + table + categories + upload queue + actions)
	ReceiptDropzone.vue    ← multi-file capture, constraint errors mapped to messages
	FilterRail.vue          ← pill filters + clear-all
	ReceiptFileCell.vue     ← file icon + name (peek link) + size, both row kinds
	UploadProgressCell.vue ← per-file BbProgress / failed state with inline retry
	MerchantCell.vue        ← inline text edit, commit on blur/Enter (§6.3)
	CategoryCell.vue        ← one-click badge → BbSelectPopover (§6.1)
	AmountCell.vue           ← inline number edit with $ prefix
	DateCell.vue             ← date picker cell, commit on pick
	RowActions.vue           ← remove-from-queue / per-receipt "…" dropdown
	SelectionBar.vue         ← bulk categorize + bulk remove in the floating bottom panel
	ReceiptPeek.vue          ← sidebar workbench, stack level 1
	MerchantPeek.vue         ← stacked peek, back arrow via the shell
```

Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
(left nav + fat footer), [Page Shell](../../guides/page-shell.md),
[Floating Bottom Panel](../../guides/floating-bottom-panel.md).

## Action inventory

| #   | Action                            | Trigger                            | Mechanism                                             |
| --- | --------------------------------- | ---------------------------------- | ----------------------------------------------------- |
| 1   | Upload receipts                   | dropzone (drag, click, Browse)     | `enqueueFiles()` → per-file upload with progress      |
| 2   | Retry a failed upload             | inline in the progress cell        | `retryUpload(id)` re-issues the request               |
| 3   | Remove an in-flight upload        | row actions (x)                    | `removeUpload(id)` aborts + drops the row             |
| 4   | Page search                       | topbar right                       | `filters.search` → fetch dependency                   |
| 5   | Filter category / merchant / date | filter rail pills                  | `BbSelectPopover` multiple / query-aware / date range |
| 6   | Clear filters                     | rail right (only when active)      | context `clearFilters()`                              |
| 7   | Switch tab                        | href tabs with counts              | URL + fetch dependency                                |
| 8   | Edit merchant inline              | merchant cell                      | commit on blur/Enter, Esc reverts (§6.3)              |
| 9   | Change category one-click         | category badge in row & peek       | `BbSelectPopover` on the badge (§6.1)                 |
| 10  | Edit amount inline                | amount cell ($ prefix)             | commit on blur/Enter, Esc reverts                     |
| 11  | Edit expense date inline          | date cell                          | commit on pick                                        |
| 12  | Submit one receipt                | row `…`, peek footer               | `submitReceipt()` (API + refresh + toast)             |
| 13  | Submit all with count             | topbar, the page's one `primary`   | `submitAll()` — count from every fetch                |
| 14  | Remove a draft                    | row `…`, peek footer               | destructive behind `useConfirm`                       |
| 15  | Bulk categorize                   | floating bottom panel popover      | `bulkCategorize()` on `table.selected`                |
| 16  | Bulk remove                       | floating bottom panel              | destructive behind `useConfirm`, count in message     |
| 17  | Select rows / select all          | table checkboxes (drafts only)     | table context, `selectable` predicate                 |
| 18  | Peek receipt                      | filename cell / merchant peek list | `peekReceipt(id)` → shell stack                       |
| 19  | Peek merchant (stacked)           | merchant name inside the peek      | `stackMerchant(name)` → back arrow                    |
| 20  | Download original                 | row `…`, peek footer               | navigation (`/receipts/:id/file`)                     |

## The code

### context.ts

```ts
// UploadCenter/context.ts
import {
	computed,
	inject,
	provide,
	reactive,
	ref,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import {
	useBbTableContext,
	useConfirm,
	useToast,
	type BadgeVariantType,
	type BbTableContext,
} from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import { useCategoriesStore } from '@/stores/categories';
import { api } from '@/api';
import type { Category, Receipt, ReceiptStatus } from '@/types';

/** What the stacked sidebar can show. Clicking a name pushes one of these. */
export type PeekItem =
	| { type: 'receipt'; id: string }
	| { type: 'merchant'; name: string };

export type UploadCenterTab = 'drafts' | 'submitted' | 'reimbursed';

export interface ReceiptFilters {
	search: string;
	categoryIds: string[];
	merchant: string | null;
	/**
	 * `[start, end]` as `YYYY-MM-DD`, or `[]` when unset. Range mode requires an
	 * array modelValue -- binding `null` throws, so the empty filter is `[]`.
	 */
	spentBetween: string[];
}

/** A dropped file whose transfer is still in flight (or failed). Local-only. */
export type UploadRow = {
	/** Local id (`upload-…`) — never collides with server receipt ids. */
	id: string;
	kind: 'upload';
	filename: string;
	size: number;
	/** 0–100. Mutated in place per progress tick — reactive, no refetch. */
	progress: number;
	failed: boolean;
};

/** A server receipt as the table renders it. */
export type ReceiptRow = Receipt & { kind: 'receipt' };

/** What the table actually lists on the Drafts tab: uploads first. */
export type UploadCenterRow = UploadRow | ReceiptRow;

/** The only fields the inline cells may change. */
export type ReceiptPatch = Partial<
	Pick<Receipt, 'merchant' | 'categoryId' | 'amount' | 'date'>
>;

// -- Receipt-status badge maps: one closed set, mapped once for the whole page.
// The receipt lifecycle (table rows, the receipt peek header, the merchant
// peek's recent list) is a small closed set — the textbook case for the soft
// accents (design-language.md § Using color), registered via badge-variants.d.ts.
// draft = idle/neutral, submitted = pending approval, reimbursed = done.
export const STATUS_LABEL: Record<ReceiptStatus, string> = {
	draft: 'Draft',
	submitted: 'Submitted',
	reimbursed: 'Reimbursed',
};
export const STATUS_VARIANT: Record<ReceiptStatus, BadgeVariantType> = {
	draft: 'soft-gray',
	submitted: 'soft-amber',
	reimbursed: 'soft-green',
};

export interface UploadCenterContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	table: BbTableContext;
	/** Shared expense-category catalog, coopted from the store. */
	categories: ComputedRef<Category[]>;
	// -- Page-owned state ------------------------------------------------------
	filters: ReceiptFilters;
	hasActiveFilters: ComputedRef<boolean>;
	tab: Ref<UploadCenterTab>;
	tabCounts: Ref<Record<UploadCenterTab, number>>;
	/** Drafts that are complete (merchant + category + amount + date). */
	readyCount: Ref<number>;
	/** The live upload queue — in-flight and failed transfers. */
	uploads: Ref<UploadRow[]>;
	refreshKey: Ref<number>;
	// -- Data ------------------------------------------------------------------
	fetchRows: () => Promise<UploadCenterRow[]>;
	searchMerchants: (query: string) => Promise<string[]>;
	// -- Peek grammar ----------------------------------------------------------
	peekReceipt: (id: string) => void;
	stackReceipt: (id: string) => void;
	stackMerchant: (name: string) => void;
	// -- Actions (complete: API + refresh + toast) ------------------------------
	clearFilters: () => void;
	enqueueFiles: (files: File[]) => void;
	retryUpload: (id: string) => void;
	removeUpload: (id: string) => void;
	updateReceipt: (receipt: Receipt, patch: ReceiptPatch) => Promise<void>;
	submitReceipt: (receipt: Receipt) => Promise<void>;
	submitAll: () => Promise<void>;
	/** Resolves `true` when the receipt was actually deleted (confirm accepted). */
	deleteReceipt: (receipt: Receipt) => Promise<boolean>;
	bulkCategorize: (categoryId: string) => Promise<void>;
	bulkRemove: () => Promise<void>;
}

const key: InjectionKey<UploadCenterContext> = Symbol('upload-center');

export function provideUploadCenter(): UploadCenterContext {
	const { toast } = useToast();
	const { confirm } = useConfirm();

	// -- Coopt the specific contexts: once, here, for the whole page. ----------
	const shell = usePageShellContext<PeekItem>();
	const table = useBbTableContext('receipts-table', { perPage: 25 });
	const categoriesStore = useCategoriesStore();
	const categories = computed(() => categoriesStore.categories);
	// A shared catalog store does not seed itself just by being read. Kick the
	// load here (idempotent — the store dedupes on an in-flight promise), or the
	// category cells and the bulk-categorize popover stay permanently empty.
	void categoriesStore.load();

	// -- Page state -------------------------------------------------------------
	const filters = reactive<ReceiptFilters>({
		search: '',
		categoryIds: [],
		merchant: null,
		spentBetween: [],
	});
	const hasActiveFilters = computed(
		() =>
			filters.search !== '' ||
			filters.categoryIds.length > 0 ||
			filters.merchant !== null ||
			filters.spentBetween.length > 0
	);
	const tab = ref<UploadCenterTab>('drafts');
	const tabCounts = ref<Record<UploadCenterTab, number>>({
		drafts: 0,
		submitted: 0,
		reimbursed: 0,
	});
	const readyCount = ref(0);
	const refreshKey = ref(0);

	const clearFilters = () => {
		filters.search = '';
		filters.categoryIds = [];
		filters.merchant = null;
		filters.spentBetween = [];
	};

	const refresh = () => {
		refreshKey.value++;
	};

	// -- Data ---------------------------------------------------------------------
	// The one place the list is fetched. Writes the paging totals into the
	// table context and keeps the tab counts and submit-all count live. A
	// drafts page looks like:
	//   { id: 'rcp_3128', filename: 'uber-2026-07-08.pdf',   merchant: 'Uber',
	//     categoryId: 'cat-rideshare', amount: 42.8,  date: '2026-07-08', … }
	//   { id: 'rcp_3127', filename: 'IMG_4021.jpg',          merchant: 'Starbucks Reserve',
	//     categoryId: 'cat-meals',     amount: 11.4,  date: '2026-07-08', … }
	//   { id: 'rcp_3120', filename: 'delta-ticket-0472.pdf', merchant: 'Delta Air Lines',
	//     categoryId: 'cat-travel',    amount: 428.6, date: '2026-07-06', … }
	//   { id: 'rcp_3117', filename: 'marriott-folio.pdf',    merchant: 'Marriott Marquis SF',
	//     categoryId: 'cat-lodging',   amount: 612.33, date: '2026-07-05', … }
	// On the Drafts tab the live upload queue renders above the fetched page.
	const uploads = ref<UploadRow[]>([]);

	const fetchRows = async (): Promise<UploadCenterRow[]> => {
		const response = await api.receipts.list({
			...filters,
			tab: tab.value,
			page: table.page.value,
			perPage: table.perPage.value,
		});
		table.totalItems.value = response.total;
		tabCounts.value = response.tabCounts;
		readyCount.value = response.readyCount;
		const rows = response.data.map(
			(receipt): ReceiptRow => ({ ...receipt, kind: 'receipt' })
		);
		return tab.value === 'drafts' ? [...uploads.value, ...rows] : rows;
	};

	const searchMerchants = (query: string): Promise<string[]> =>
		api.merchants.search(query);

	// -- Upload machinery ----------------------------------------------------------
	// The queue rows are reactive: progress ticks mutate them in place and the
	// rendered cells update without a refetch. Only membership changes
	// (enqueue, remove, completion) bump refreshKey so the table re-runs its
	// items function. Files and abort controllers live in closure maps — they
	// are not render state.
	const uploadFiles = new Map<string, File>();
	const controllers = new Map<string, AbortController>();

	const startUpload = async (id: string) => {
		const file = uploadFiles.get(id);
		const row = uploads.value.find((upload) => upload.id === id);
		if (!file || !row) return;
		row.failed = false;
		row.progress = 0;
		const controller = new AbortController();
		controllers.set(id, controller);
		try {
			await api.receipts.upload(file, {
				signal: controller.signal,
				onProgress: (percent) => {
					row.progress = percent;
				},
			});
			// Success: the file re-enters as a server draft with OCR-extracted
			// merchant/amount/date prefilled — the refetch swaps the rows.
			uploads.value = uploads.value.filter((upload) => upload.id !== id);
			uploadFiles.delete(id);
			refresh();
		} catch {
			// Keep the row: the progress cell renders the inline Retry.
			row.failed = true;
		} finally {
			controllers.delete(id);
		}
	};

	const enqueueFiles = (files: File[]) => {
		for (const file of files) {
			const id = `upload-${crypto.randomUUID()}`;
			uploadFiles.set(id, file);
			uploads.value.push({
				id,
				kind: 'upload',
				filename: file.name,
				size: file.size,
				progress: 0,
				failed: false,
			});
			void startUpload(id);
		}
		refresh();
	};

	const retryUpload = (id: string) => {
		void startUpload(id);
	};

	const removeUpload = (id: string) => {
		controllers.get(id)?.abort();
		controllers.delete(id);
		uploadFiles.delete(id);
		uploads.value = uploads.value.filter((upload) => upload.id !== id);
		refresh();
	};

	// -- Peek grammar ----------------------------------------------------------------
	// peekX opens a fresh stack (from the list); stackX drills down (from a peek).
	const peekReceipt = (id: string) => shell.push({ type: 'receipt', id }, true);
	const stackReceipt = (id: string) => shell.push({ type: 'receipt', id });
	const stackMerchant = (name: string) =>
		shell.push({ type: 'merchant', name });

	// -- Actions --------------------------------------------------------------------
	const updateReceipt = async (receipt: Receipt, patch: ReceiptPatch) => {
		try {
			await api.receipts.update(receipt.id, patch);
			refresh(); // silent on success — the cell already shows the new value
		} catch {
			refresh(); // the refetch reverts the cell to the server value
			toast({
				title: `Could not save ${receipt.filename}. Changes were reverted.`,
				variant: 'destructive',
			});
		}
	};

	const submitReceipt = async (receipt: Receipt) => {
		await api.receipts.submit(receipt.id);
		refresh();
		toast({
			title: `${receipt.merchant ?? receipt.filename} submitted for approval.`,
			variant: 'success',
		});
	};

	const submitAll = async () => {
		const { submitted } = await api.receipts.submitDrafts();
		refresh();
		toast({
			title: `${submitted} receipts submitted for approval.`,
			variant: 'success',
		});
	};

	const deleteReceipt = async (receipt: Receipt): Promise<boolean> => {
		const ok = await confirm({
			variant: 'destructive',
			title: 'Remove receipt',
			text: `Remove ${receipt.filename}? The file is deleted and cannot be recovered.`,
			yes: 'Remove',
			no: 'Cancel',
		});
		if (!ok) return false;
		await api.receipts.delete(receipt.id);
		refresh();
		toast({ title: `${receipt.filename} removed.`, variant: 'success' });
		return true;
	};

	// Bulk actions read and clear the coopted table context themselves. Only
	// draft receipt rows are selectable, so `selected` holds receipt ids.
	const bulkIds = (): string[] => table.selected.value;
	const clearSelection = () => {
		table.selected.value = [];
	};

	const bulkCategorize = async (categoryId: string) => {
		const ids = bulkIds();
		await api.receipts.categorizeMany(ids, categoryId);
		const category = categories.value.find((entry) => entry.id === categoryId);
		clearSelection();
		refresh();
		toast({
			title: `${ids.length} receipts filed under ${category?.name ?? 'the selected category'}.`,
			variant: 'success',
		});
	};

	const bulkRemove = async () => {
		const ids = bulkIds();
		const ok = await confirm({
			variant: 'destructive',
			title: 'Remove receipts',
			text: `Remove ${ids.length} receipts? Their files are deleted and cannot be recovered.`,
			yes: 'Remove',
			no: 'Cancel',
		});
		if (!ok) return;
		await api.receipts.deleteMany(ids);
		clearSelection();
		refresh();
		toast({ title: `${ids.length} receipts removed.`, variant: 'success' });
	};

	const ctx: UploadCenterContext = {
		shell,
		table,
		categories,
		filters,
		hasActiveFilters,
		tab,
		tabCounts,
		readyCount,
		uploads,
		refreshKey,
		fetchRows,
		searchMerchants,
		peekReceipt,
		stackReceipt,
		stackMerchant,
		clearFilters,
		enqueueFiles,
		retryUpload,
		removeUpload,
		updateReceipt,
		submitReceipt,
		submitAll,
		deleteReceipt,
		bulkCategorize,
		bulkRemove,
	};
	provide(key, ctx);
	return ctx;
}

export function useUploadCenter(): UploadCenterContext {
	const ctx = inject(key);
	if (!ctx) throw new Error('useUploadCenter() called outside UploadCenter');
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- UploadCenter/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left, page search + submit-all right. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs
					class="min-w-0 flex-auto"
					:items="[
						{ key: 'dashboard', text: 'Dashboard', to: '/dashboard' },
						{ key: 'expenses', text: 'Expenses', to: '/expenses' },
						{ key: 'receipts', text: 'Receipts' },
					]"
				/>
				<div class="flex shrink-0 items-center gap-2">
					<BbTextInput
						v-model="ctx.filters.search"
						autocomplete="off"
						clearable
						compact
						hide-label
						label="Search receipts"
						placeholder="Search merchant or filename…"
						prepend:icon="lucide:search"
					/>
					<!-- The page's single primary: submit-all with a live count.
					     BbButton tracks the async handler, so it shows its own
					     loading state while the batch submits. -->
					<BbButton
						:disabled="ctx.readyCount.value === 0"
						prepend:icon="lucide:send"
						variant="primary"
						@click="ctx.submitAll"
					>
						{{ submitLabel }}
					</BbButton>
				</div>
			</div>
		</template>

		<div class="flex flex-col gap-3 p-4">
			<!-- Capture surface: drafts tab only. -->
			<ReceiptDropzone v-if="ctx.tab.value === 'drafts'" />

			<FilterRail />

			<!-- Tabs as URL filters: href updates the query, the key feeds the
			     fetch. Counts come from the server on every fetch. -->
			<BbTabs
				v-model="ctx.tab.value"
				compact
				:items="[
					{
						key: 'drafts',
						label: `Drafts · ${ctx.tabCounts.value.drafts}`,
						href: '?tab=drafts',
					},
					{
						key: 'submitted',
						label: `Submitted · ${ctx.tabCounts.value.submitted}`,
						href: '?tab=submitted',
					},
					{
						key: 'reimbursed',
						label: `Reimbursed · ${ctx.tabCounts.value.reimbursed}`,
						href: '?tab=reimbursed',
					},
				]"
			/>

			<BbTable
				id="receipts-table"
				actions
				caption="Expense receipts"
				:columns="columns"
				compact
				:dependencies="[
					{ ...ctx.filters },
					ctx.tab.value,
					ctx.refreshKey.value,
				]"
				:deps-debounce-time="300"
				item-value="id"
				:items="ctx.fetchRows"
				legend="Select receipts"
				loading-text="Loading receipts…"
				:row-class="rowClass"
				:selectable="isDraft"
			>
				<!-- Clicking the NAME of a thing peeks it. -->
				<template #filename="{ item }">
					<ReceiptFileCell :row="item" />
				</template>

				<!-- Editable cells on draft rows; plain text everywhere else. -->
				<template #merchant="{ item }">
					<MerchantCell v-if="isDraft(item)" :receipt="item" />
					<span
						v-else-if="item.kind === 'upload'"
						class="text-[color:var(--bb-text-muted)]"
						>—</span
					>
					<span v-else>{{ item.merchant ?? '—' }}</span>
				</template>

				<!-- Slot names are normalized: `categoryId` → `#categoryid`. -->
				<template #categoryid="{ item }">
					<CategoryCell v-if="isDraft(item)" :receipt="item" />
					<span
						v-else-if="item.kind === 'upload'"
						class="text-[color:var(--bb-text-muted)]"
						>—</span
					>
					<span v-else>{{ categoryName(item.categoryId) }}</span>
				</template>

				<template #amount="{ item }">
					<AmountCell v-if="isDraft(item)" :receipt="item" />
					<span
						v-else-if="item.kind === 'upload'"
						class="text-[color:var(--bb-text-muted)]"
						>—</span
					>
					<span v-else>{{
						item.amount === null ? '—' : currency.format(item.amount)
					}}</span>
				</template>

				<template #date="{ item }">
					<DateCell v-if="isDraft(item)" :receipt="item" />
					<span
						v-else-if="item.kind === 'upload'"
						class="text-[color:var(--bb-text-muted)]"
						>—</span
					>
					<span v-else>{{ item.date ? shortDate(item.date) : '—' }}</span>
				</template>

				<!-- Status column doubles as the transfer surface for queue rows. -->
				<template #status="{ item }">
					<UploadProgressCell v-if="item.kind === 'upload'" :upload="item" />
					<BbBadge v-else :variant="STATUS_VARIANT[item.status]">{{
						STATUS_LABEL[item.status]
					}}</BbBadge>
				</template>

				<template #actions="{ item }">
					<RowActions :row="item" />
				</template>

				<template #no-data>
					<div class="flex flex-col items-center gap-2 p-8 text-center">
						<BbIcon
							aria-hidden="true"
							class="text-[color:var(--bb-text-muted)]"
							:icon="
								ctx.hasActiveFilters.value
									? 'lucide:search-x'
									: 'lucide:receipt'
							"
							size="2xl"
						/>
						<p class="text-sm font-semibold">
							{{
								ctx.hasActiveFilters.value
									? 'No matching receipts'
									: ctx.tab.value === 'drafts'
										? 'No drafts yet'
										: 'Nothing in this tab yet'
							}}
						</p>
						<p class="text-xs text-[color:var(--bb-text-muted)]">
							{{
								ctx.hasActiveFilters.value
									? 'Loosen a filter above, or switch tabs to widen the view.'
									: ctx.tab.value === 'drafts'
										? 'Drop receipts above to get started.'
										: 'Submitted and reimbursed receipts land in their own tabs.'
							}}
						</p>
						<BbButton
							v-if="ctx.hasActiveFilters.value"
							prepend:icon="lucide:x"
							variant="ghost"
							@click="ctx.clearFilters"
						>
							Clear filters
						</BbButton>
					</div>
				</template>
			</BbTable>

			<!-- Joins the table context by id: no page/totalPages wiring at all. -->
			<BbPagination table-id="receipts-table" />
		</div>

		<SelectionBar />

		<!-- Stacked peek sidebar: the shell owns back/close; we render by type. -->
		<template #sidebar>
			<ReceiptPeek
				v-if="ctx.shell.current.value?.type === 'receipt'"
				:receipt-id="ctx.shell.current.value.id"
			/>
			<MerchantPeek
				v-else-if="ctx.shell.current.value?.type === 'merchant'"
				:merchant-name="ctx.shell.current.value.name"
			/>
		</template>
	</PageShell>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import {
	BbBadge,
	BbBreadcrumbs,
	BbButton,
	BbIcon,
	BbPagination,
	BbTable,
	BbTabs,
	BbTextInput,
} from 'bitboss-ui';
import PageShell from '@/components/layout/PageShell.vue';
import {
	provideUploadCenter,
	STATUS_LABEL,
	STATUS_VARIANT,
	type ReceiptRow,
	type UploadCenterRow,
} from './context';
import AmountCell from './AmountCell.vue';
import CategoryCell from './CategoryCell.vue';
import DateCell from './DateCell.vue';
import FilterRail from './FilterRail.vue';
import MerchantCell from './MerchantCell.vue';
import MerchantPeek from './MerchantPeek.vue';
import ReceiptDropzone from './ReceiptDropzone.vue';
import ReceiptFileCell from './ReceiptFileCell.vue';
import ReceiptPeek from './ReceiptPeek.vue';
import RowActions from './RowActions.vue';
import SelectionBar from './SelectionBar.vue';
import UploadProgressCell from './UploadProgressCell.vue';

const ctx = provideUploadCenter();

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
const shortDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
	});

// Every cell renders through a slot, so columns stay label-only definitions.
const columns = [
	{ key: 'filename', label: 'Receipt' },
	{ key: 'merchant', label: 'Merchant' },
	{ key: 'categoryId', label: 'Category' },
	{ key: 'amount', label: 'Amount', align: 'right' as const },
	{ key: 'date', label: 'Date' },
	{ key: 'status', label: 'Status' },
];

// Only server-side drafts are editable and selectable; queue rows and
// submitted/reimbursed receipts are not. The narrow predicate keeps the
// `v-else` (non-draft receipt) branch a real `ReceiptRow`, not `never`.
const isDraft = (
	item: UploadCenterRow
): item is ReceiptRow & { status: 'draft' } =>
	item.kind === 'receipt' && item.status === 'draft';

// Failed transfers get a tinted row — public row-class API, no internals.
const rowClass = (item: UploadCenterRow) =>
	item.kind === 'upload' && item.failed
		? 'bg-red-50 dark:bg-red-950/20'
		: undefined;

const categoryName = (categoryId: string | null) =>
	ctx.categories.value.find((category) => category.id === categoryId)?.name ??
	'—';

const submitLabel = computed(() =>
	ctx.readyCount.value === 0
		? 'Submit receipts'
		: `Submit ${ctx.readyCount.value} ${ctx.readyCount.value === 1 ? 'receipt' : 'receipts'}`
);
</script>
```

### ReceiptDropzone.vue

```vue
<!-- UploadCenter/ReceiptDropzone.vue -->
<template>
	<BbDropzone
		v-model="pending"
		:accept="ACCEPT"
		:errors="dropError"
		:max-files="20"
		:max-size="MAX_SIZE"
		multiple
		@error="onError"
	>
		<template #default="{ dragging, focused, open }">
			<div
				class="flex flex-col items-center gap-2 rounded-[var(--bb-radius)] border-2 border-dashed p-6 text-center transition-colors"
				:class="[
					dragging ? 'border-[var(--bb-primary)]' : 'border-[var(--bb-border)]',
					focused ? 'ring-2 ring-[var(--bb-primary)] ring-offset-2' : '',
				]"
			>
				<BbIcon
					class="text-[color:var(--bb-text-muted)]"
					icon="lucide:receipt"
					size="lg"
				/>
				<p class="text-sm font-medium">
					{{ dragging ? 'Drop to add receipts' : 'Drop receipts here' }}
				</p>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					JPG, PNG, HEIC or PDF · up to 10 MB each · 20 files per drop
				</p>
				<BbButton
					prepend:icon="lucide:folder-open"
					variant="ghost"
					@click="open"
				>
					Browse files
				</BbButton>
			</div>
		</template>
	</BbDropzone>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue';
import { BbButton, BbDropzone, BbIcon, type DropZoneError } from 'bitboss-ui';
import { useUploadCenter } from './context';

// Pair every extension with its MIME type: the MIME rule matches by content
// type, the .ext rule catches drag-drops where the OS leaves file.type empty.
const ACCEPT = [
	'image/jpeg',
	'.jpg',
	'.jpeg',
	'image/png',
	'.png',
	'image/heic',
	'.heic',
	'application/pdf',
	'.pdf',
];
const MAX_SIZE = 10 * 1024 * 1024; // 10 MB per receipt

const ctx = useUploadCenter();

// BbDropzone captures and validates; the context uploads. The model is a
// hand-off buffer: drain every validated batch into the queue, then clear it
// (which also resets the duplicate check for future corrections).
const pending = ref<File[]>([]);
watch(pending, (files) => {
	if (files.length === 0) return;
	dropError.value = undefined;
	ctx.enqueueFiles(files);
	pending.value = [];
});

// The errors display is a round-trip: map each typed reject to a sentence
// and feed it back through the `errors` prop (rendered in the built-in
// aria-live region and referenced from the input's aria-describedby). Batch drops emit one error per file; showing the last
// message keeps the surface calm.
const dropError = ref<string | undefined>();
const onError = (error: DropZoneError) => {
	if (error.type === 'maxSize') {
		dropError.value = `${error.filename} is ${error.formattedSize} — receipts are capped at ${error.formattedMaxSize}.`;
	} else if (error.type === 'accept') {
		dropError.value = `${error.filename} is not a JPG, PNG, HEIC or PDF.`;
	} else if (error.type === 'uniqueness') {
		dropError.value = `${error.filename} is already in this drop.`;
	} else {
		dropError.value = `That drop had ${error.totalFiles} files — add at most 20 at a time.`;
	}
};
</script>
```

### FilterRail.vue

```vue
<!-- UploadCenter/FilterRail.vue -->
<template>
	<div class="flex flex-wrap items-center gap-2">
		<!-- Category: multi-select pill over the coopted catalog. -->
		<BbSelectPopover
			v-model="ctx.filters.categoryIds"
			item-text="name"
			item-value="id"
			:items="ctx.categories.value"
			multiple
			width="240px"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filter by category"
					append:icon="lucide:chevron-down"
					size="sm"
					variant="outline"
				>
					Category{{
						ctx.filters.categoryIds.length
							? ` · ${ctx.filters.categoryIds.length}`
							: ''
					}}
				</BbButton>
			</template>
		</BbSelectPopover>

		<!-- Merchant: query-aware search. Merchant names are their own values,
		     so the pill labels itself straight from the filter state. -->
		<BbSelectPopover
			v-model="ctx.filters.merchant"
			:items="ctx.searchMerchants"
			width="240px"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Filter by merchant"
					append:icon="lucide:chevron-down"
					size="sm"
					variant="outline"
				>
					{{ ctx.filters.merchant ?? 'Merchant' }}
				</BbButton>
			</template>
		</BbSelectPopover>

		<!-- Spent-between range: a compact input is 28px — flush with the pills. -->
		<BbDatePickerInput
			v-model="ctx.filters.spentBetween"
			clearable
			compact
			floating
			hide-label
			label="Spent between"
			placeholder="Spent between…"
			range
		/>

		<!-- Clear-all renders only while something is active. -->
		<BbButton
			v-if="ctx.hasActiveFilters.value"
			class="ml-auto"
			prepend:icon="lucide:x"
			size="sm"
			variant="ghost"
			@click="ctx.clearFilters"
		>
			Clear filters
		</BbButton>
	</div>
</template>

<script setup lang="ts">
import { BbButton, BbDatePickerInput, BbSelectPopover } from 'bitboss-ui';
import { useUploadCenter } from './context';

const ctx = useUploadCenter();
</script>
```

### ReceiptFileCell.vue

```vue
<!-- UploadCenter/ReceiptFileCell.vue -->
<template>
	<div class="flex items-center gap-2">
		<BbIcon
			class="shrink-0 text-[color:var(--bb-text-muted)]"
			:icon="fileIcon"
			size="16"
		/>
		<div class="flex min-w-0 flex-col">
			<!-- Server receipts peek on click; queue rows are not peekable yet. -->
			<BbButton
				v-if="row.kind === 'receipt'"
				class="justify-start"
				size="sm"
				variant="link"
				@click="() => ctx.peekReceipt(row.id)"
			>
				{{ row.filename }}
			</BbButton>
			<span v-else class="truncate text-sm">{{ row.filename }}</span>
			<span class="text-xs text-[color:var(--bb-text-muted)]">{{
				formattedSize
			}}</span>
		</div>
	</div>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbIcon } from 'bitboss-ui';
import { useUploadCenter, type UploadCenterRow } from './context';

const props = defineProps<{ row: UploadCenterRow }>();

const ctx = useUploadCenter();

const fileIcon = computed(() =>
	props.row.filename.toLowerCase().endsWith('.pdf')
		? 'lucide:file-text'
		: 'lucide:image'
);

const formattedSize = computed(() => {
	const bytes =
		props.row.kind === 'upload' ? props.row.size : props.row.fileSize;
	return bytes >= 1024 * 1024
		? `${(bytes / (1024 * 1024)).toFixed(1)} MB`
		: `${Math.max(1, Math.round(bytes / 1024))} KB`;
});
</script>
```

### UploadProgressCell.vue

```vue
<!-- UploadCenter/UploadProgressCell.vue -->
<template>
	<!-- In flight: a live bar. `upload.progress` is a reactive field mutated
	     by the context's progress callback — no refetch per tick. -->
	<div v-if="!upload.failed" class="flex min-w-32 items-center gap-2">
		<BbProgress
			:aria-label="`Uploading ${upload.filename}`"
			class="flex-1"
			:model-value="upload.progress"
		/>
		<span class="text-xs tabular-nums text-[color:var(--bb-text-muted)]"
			>{{ upload.progress }}%</span
		>
	</div>

	<!-- Failed: say so and retry inline. `xs` is fine here — this is the
	     densest surface on the page. -->
	<div v-else class="flex items-center gap-2">
		<span class="text-xs font-medium text-red-600 dark:text-red-400"
			>Upload failed</span
		>
		<BbButton
			prepend:icon="lucide:rotate-cw"
			size="xs"
			variant="outline"
			@click="() => ctx.retryUpload(upload.id)"
		>
			Retry
		</BbButton>
	</div>
</template>

<script setup lang="ts">
import { BbButton, BbProgress } from 'bitboss-ui';
import { useUploadCenter, type UploadRow } from './context';

defineProps<{ upload: UploadRow }>();

const ctx = useUploadCenter();
</script>
```

### MerchantCell.vue

```vue
<!-- UploadCenter/MerchantCell.vue -->
<template>
	<BbTextInput
		v-model="draft"
		compact
		hide-label
		label="Merchant"
		placeholder="Add merchant"
		@change="commit"
		@keydown.esc="revert"
	/>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue';
import { BbTextInput } from 'bitboss-ui';
import { useUploadCenter } from './context';
import type { Receipt } from '@/types';

const props = defineProps<{ receipt: Receipt }>();

const ctx = useUploadCenter();

// Inline-edit doctrine (§6.3): a local draft, commit on @change — which
// fires once for the whole blur/Enter sequence, unlike binding @blur AND
// @keydown.enter separately (that double-fires: Enter commits, then the
// field still blurs right after). Revert on Esc. The server value re-seeds
// the draft whenever a refetch updates the row — which is also how a
// failed save reverts.
const draft = ref<string | null>(props.receipt.merchant);
watch(
	() => props.receipt.merchant,
	(value) => {
		draft.value = value;
	}
);

const commit = () => {
	const merchant = draft.value?.trim() || null;
	if (merchant === props.receipt.merchant) return;
	void ctx.updateReceipt(props.receipt, { merchant });
};
const revert = () => {
	draft.value = props.receipt.merchant;
};
</script>
```

### CategoryCell.vue

```vue
<!-- UploadCenter/CategoryCell.vue -->
<template>
	<BbSelectPopover
		compact
		disable-writing
		item-text="name"
		item-value="id"
		:items="ctx.categories.value"
		:model-value="receipt.categoryId"
		width="220px"
		@update:model-value="(categoryId) => pick(categoryId as string)"
	>
		<template #activator="{ props: activatorProps, shown }">
			<!-- One-click pattern (§6.1): the badge is the focusable trigger —
			     BbBadgeButton takes over the badge body, the trailing chevron says
			     "this can change", and while the save runs `loading` swaps the
			     spinner into the chevron's place. A category is a label, not a
			     semantic status, so a set category reads neutral (`secondary`);
			     only the unset state stays `outline` so empty cells read as
			     quieter to-dos, not values. -->
			<BbBadge
				append:icon="lucide:chevron-down"
				:class="{ 'category-cell--open': shown }"
				:loading="saving"
				:variant="receipt.categoryId ? 'secondary' : 'outline'"
			>
				<BbBadgeButton
					:aria-label="`Change category for ${receipt.filename}`"
					v-bind="activatorProps"
					>{{ categoryName }}</BbBadgeButton
				>
			</BbBadge>
		</template>
	</BbSelectPopover>
</template>

<script setup lang="ts">
import { computed, ref } from 'vue';
import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
import { useUploadCenter } from './context';
import type { Receipt } from '@/types';

const props = defineProps<{ receipt: Receipt }>();

const ctx = useUploadCenter();

// In-flight flag for the save feedback — rung-1 local state, not context.
const saving = ref(false);
const pick = async (categoryId: string) => {
	saving.value = true;
	try {
		await ctx.updateReceipt(props.receipt, { categoryId });
	} finally {
		saving.value = false;
	}
};

// The trigger labels itself from the coopted catalog, never from the
// popover's lazy `text` slot prop.
const categoryName = computed(
	() =>
		ctx.categories.value.find(
			(category) => category.id === props.receipt.categoryId
		)?.name ?? 'Set category'
);
</script>

<style scoped>
/* Open = the badge's own hue, deepened, plus its variant ring — the same
   grammar as every badge-activator cell. */
.category-cell--open {
	--bg: color-mix(in oklab, var(--color) 24%, var(--bb-panel));
	--border-color: color-mix(in oklab, var(--color) 45%, var(--bb-panel));
	box-shadow: 0 0 0 var(--bb-ring-size) var(--ring);
}
</style>
```

### AmountCell.vue

```vue
<!-- UploadCenter/AmountCell.vue -->
<template>
	<BbNumberInput
		v-model="draft"
		compact
		hide-label
		label="Amount"
		:max-precision="2"
		:min="0"
		placeholder="0.00"
		@change="commit"
		@keydown.esc="revert"
	>
		<template #prefix>$</template>
	</BbNumberInput>
</template>

<script setup lang="ts">
import { ref, watch } from 'vue';
import { BbNumberInput } from 'bitboss-ui';
import { useUploadCenter } from './context';
import type { Receipt } from '@/types';

const props = defineProps<{ receipt: Receipt }>();

const ctx = useUploadCenter();

// Same commit/revert contract as the merchant cell, on the number model —
// commit on @change, not @blur + @keydown.enter (see MerchantCell.vue).
const draft = ref<number | string | null>(props.receipt.amount);
watch(
	() => props.receipt.amount,
	(value) => {
		draft.value = value;
	}
);

const commit = () => {
	const amount =
		draft.value === null || draft.value === '' ? null : Number(draft.value);
	if (amount === props.receipt.amount) return;
	void ctx.updateReceipt(props.receipt, { amount });
};
const revert = () => {
	draft.value = props.receipt.amount;
};
</script>
```

### DateCell.vue

```vue
<!-- UploadCenter/DateCell.vue -->
<template>
	<!-- Picking a date IS the commit — no blur dance for calendar input.
	     `floating` keeps the model a plain YYYY-MM-DD string. -->
	<BbDatePickerInput
		compact
		floating
		hide-label
		label="Expense date"
		:model-value="receipt.date"
		placeholder="YYYY-MM-DD"
		@update:model-value="commit"
	/>
</template>

<script setup lang="ts">
import { BbDatePickerInput } from 'bitboss-ui';
import { useUploadCenter } from './context';
import type { Receipt } from '@/types';

const props = defineProps<{ receipt: Receipt }>();

const ctx = useUploadCenter();

const commit = (value: string | string[] | null) => {
	const date = Array.isArray(value) ? (value[0] ?? null) : value;
	if (date === props.receipt.date) return;
	void ctx.updateReceipt(props.receipt, { date });
};
</script>
```

### RowActions.vue

```vue
<!-- UploadCenter/RowActions.vue -->
<template>
	<!-- Queue rows: one explicit remove (aborts the transfer). -->
	<BbButton
		v-if="row.kind === 'upload'"
		:aria-label="`Remove ${row.filename} from the queue`"
		icon="lucide:x"
		size="sm"
		variant="ghost"
		@click="() => ctx.removeUpload(row.id)"
	/>

	<!-- Server receipts: contextual dropdown, entries vary by status. -->
	<BbDropdown v-else :items="items">
		<template #activator="{ props }">
			<BbButton v-bind="props" icon="lucide:ellipsis" size="sm" variant="ghost">
				Receipt actions
			</BbButton>
		</template>
	</BbDropdown>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbDropdown } from 'bitboss-ui';
import { useUploadCenter, type UploadCenterRow } from './context';

const props = defineProps<{ row: UploadCenterRow }>();

const ctx = useUploadCenter();

const items = computed(() => {
	if (props.row.kind !== 'receipt') return [];
	const receipt = props.row;
	const isDraft = receipt.status === 'draft';
	return [
		...(isDraft
			? [
					{
						key: 'submit',
						text: 'Submit for approval',
						'prepend:icon': 'lucide:send',
						onClick: () => ctx.submitReceipt(receipt),
					},
				]
			: []),
		{
			key: 'download',
			text: 'Download original',
			'prepend:icon': 'lucide:download',
			href: `/receipts/${receipt.id}/file`,
		},
		...(isDraft
			? [
					{
						key: 'remove',
						text: 'Remove',
						'prepend:icon': 'lucide:trash-2',
						variant: 'destructive' as const,
						onClick: () => ctx.deleteReceipt(receipt),
					},
				]
			: []),
	];
});
</script>
```

### SelectionBar.vue

```vue
<!-- UploadCenter/SelectionBar.vue -->
<template>
	<FloatingBottomPanel :open="selectedCount > 0">
		<span class="px-2 text-sm">{{ selectedCount }} selected</span>

		<!-- Bulk categorize: the picker lives right in the bar — a one-shot
		     popover (model stays null) whose selection IS the action. -->
		<BbSelectPopover
			item-text="name"
			item-value="id"
			:items="ctx.categories.value"
			:model-value="null"
			placement="top"
			width="220px"
			@update:model-value="
				(categoryId) => categoryId && ctx.bulkCategorize(categoryId)
			"
		>
			<template #activator="{ props }">
				<BbButton
					v-bind="props"
					aria-label="Set category for selected receipts"
					prepend:icon="lucide:tag"
					size="sm"
					variant="ghost"
				>
					Set category
				</BbButton>
			</template>
		</BbSelectPopover>

		<div class="floating-bottom-panel__right flex items-center gap-1">
			<BbButton size="sm" variant="destructive" @click="ctx.bulkRemove"
				>Remove</BbButton
			>
			<BbButton
				aria-label="Clear selection"
				icon="lucide:x"
				size="sm"
				variant="ghost"
				@click="clearSelection"
			/>
		</div>
	</FloatingBottomPanel>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbSelectPopover } from 'bitboss-ui';
import FloatingBottomPanel from '@/components/layout/FloatingBottomPanel.vue';
import { useUploadCenter } from './context';

const ctx = useUploadCenter();

const selectedCount = computed(() => ctx.table.selected.value?.length ?? 0);
const clearSelection = () => {
	ctx.table.selected.value = [];
};
</script>
```

### ReceiptPeek.vue

```vue
<!-- UploadCenter/ReceiptPeek.vue -->
<template>
	<div v-if="receipt" class="flex flex-col gap-4 text-sm">
		<!-- Header: merchant identity + amount + status. The merchant name
		     drills DOWN — stacked peek, back arrow via the shell. -->
		<header class="flex flex-col gap-1.5">
			<div class="flex items-center justify-between gap-2">
				<BbButton
					v-if="receipt.merchant"
					size="sm"
					variant="link"
					@click="() => ctx.stackMerchant(receipt!.merchant!)"
				>
					{{ receipt.merchant }}
				</BbButton>
				<span v-else class="text-[color:var(--bb-text-muted)]"
					>No merchant yet</span
				>
				<BbBadge variant="outline">{{ receipt.status }}</BbBadge>
			</div>
			<p class="text-xl font-semibold">
				{{
					receipt.amount === null
						? 'Amount missing'
						: currency.format(receipt.amount)
				}}
			</p>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				{{ receipt.filename }} · spent
				{{ receipt.date ? longDate(receipt.date) : '—' }}
			</p>
		</header>

		<!-- Preview placeholder: the real app renders the scanned image here. -->
		<div
			class="flex h-44 flex-col items-center justify-center gap-1 rounded-[var(--bb-radius)] border bg-[var(--bb-panel)] text-[color:var(--bb-text-muted)]"
		>
			<BbIcon icon="lucide:receipt" size="lg" />
			<span class="text-xs">Receipt preview</span>
		</div>

		<!-- Extracted fields: what OCR read off the scan, with confidence. -->
		<section class="flex flex-col gap-1.5">
			<div class="flex items-center justify-between">
				<h3
					class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
				>
					Extracted fields
				</h3>
				<BbBadge size="xs" variant="outline">{{
					`OCR · ${receipt.extracted.confidence}%`
				}}</BbBadge>
			</div>
			<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
				<dt class="text-[color:var(--bb-text-muted)]">Merchant</dt>
				<dd>{{ receipt.extracted.merchant ?? '—' }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Total</dt>
				<dd>
					{{
						receipt.extracted.total === null
							? '—'
							: currency.format(receipt.extracted.total)
					}}
				</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Tax</dt>
				<dd>
					{{
						receipt.extracted.tax === null
							? '—'
							: currency.format(receipt.extracted.tax)
					}}
				</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Date</dt>
				<dd>
					{{ receipt.extracted.date ? longDate(receipt.extracted.date) : '—' }}
				</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Paid with</dt>
				<dd>{{ receipt.extracted.paymentMethod ?? '—' }}</dd>
			</dl>
		</section>

		<!-- Properties: the peek is a workbench — the category is the same
		     one-click cell as in the table. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Details
			</h3>
			<dl class="grid grid-cols-[auto_1fr] items-center gap-x-4 gap-y-1.5">
				<dt class="text-[color:var(--bb-text-muted)]">Category</dt>
				<dd><CategoryCell :receipt="receipt" /></dd>
				<dt class="text-[color:var(--bb-text-muted)]">Uploaded</dt>
				<dd>{{ longDate(receipt.uploadedAt) }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Report</dt>
				<dd>{{ receipt.reportName ?? 'Not on a report yet' }}</dd>
			</dl>
		</section>

		<!-- Activity feed. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Activity
			</h3>
			<ul class="flex flex-col gap-2">
				<li
					v-for="entry in receipt.activity"
					:key="entry.id"
					class="flex gap-2"
				>
					<BbIcon
						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
						:icon="entry.icon"
						size="14"
					/>
					<div class="flex flex-col">
						<span>{{ entry.text }}</span>
						<span class="text-xs text-[color:var(--bb-text-muted)]"
							>{{ entry.actor }} · {{ longDate(entry.at) }}</span
						>
					</div>
				</li>
			</ul>
		</section>

		<!-- Act here, or leave for the original file. -->
		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				v-if="receipt.status === 'draft'"
				prepend:icon="lucide:send"
				size="sm"
				variant="secondary"
				@click="() => ctx.submitReceipt(receipt!)"
			>
				Submit
			</BbButton>
			<BbButton
				append:icon="lucide:arrow-up-right"
				:href="`/receipts/${receipt.id}/file`"
				size="sm"
				variant="ghost"
			>
				Download original
			</BbButton>
			<BbButton
				v-if="receipt.status === 'draft'"
				class="ml-auto"
				prepend:icon="lucide:trash-2"
				size="sm"
				variant="destructive"
				@click="removeAndClose"
			>
				Remove
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { ref, watchEffect } from 'vue';
import { BbBadge, BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
import CategoryCell from './CategoryCell.vue';
import { useUploadCenter } from './context';
import { api } from '@/api';
import type { ReceiptDetail } from '@/types';

const props = defineProps<{ receiptId: string }>();

const ctx = useUploadCenter();

// Re-fetches whenever the stack shows a different receipt; refreshKey makes
// inline edits (category, submit) reflect here immediately.
const receipt = ref<ReceiptDetail | null>(null);
watchEffect(async () => {
	void ctx.refreshKey.value;
	receipt.value = await api.receipts.get(props.receiptId);
});

// deleteReceipt resolves true only when the confirm was accepted — don't
// close the peek on a cancelled dialog.
const removeAndClose = async () => {
	if (!receipt.value) return;
	if (await ctx.deleteReceipt(receipt.value)) ctx.shell.close();
};

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
const longDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
		year: 'numeric',
	});
</script>
```

### MerchantPeek.vue

```vue
<!-- UploadCenter/MerchantPeek.vue -->
<template>
	<div v-if="merchant" class="flex flex-col gap-4 text-sm">
		<header class="flex items-center gap-3">
			<div
				class="grid h-9 w-9 shrink-0 place-items-center rounded-[var(--bb-radius)] border"
			>
				<BbIcon
					class="text-[color:var(--bb-text-muted)]"
					icon="lucide:store"
					size="18"
				/>
			</div>
			<div class="flex flex-col">
				<h2 class="text-base font-semibold">{{ merchant.name }}</h2>
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					{{ merchant.defaultCategoryName }} · this year
				</p>
			</div>
		</header>

		<!-- Stat strip. -->
		<div class="grid grid-cols-3 gap-2">
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Total spent</p>
				<p class="font-semibold">{{ currency.format(merchant.totalSpent) }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Receipts</p>
				<p class="font-semibold">{{ merchant.receiptCount }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Average</p>
				<p class="font-semibold">
					{{ currency.format(merchant.averageAmount) }}
				</p>
			</div>
		</div>

		<!-- Recent receipts: names drill down again — the stack keeps growing. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Recent receipts
			</h3>
			<ul class="flex flex-col">
				<li
					v-for="recent in merchant.recentReceipts"
					:key="recent.id"
					class="flex items-center justify-between gap-2 border-b py-1.5 last:border-b-0"
				>
					<BbButton
						size="sm"
						variant="link"
						@click="() => ctx.stackReceipt(recent.id)"
					>
						{{ recent.filename }}
					</BbButton>
					<BbBadge variant="outline">{{ recent.status }}</BbBadge>
					<span class="text-xs tabular-nums text-[color:var(--bb-text-muted)]">
						{{ currency.format(recent.amount) }}
					</span>
				</li>
			</ul>
		</section>

		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				append:icon="lucide:arrow-up-right"
				size="sm"
				:to="`/expenses/receipts?merchant=${encodeURIComponent(merchant.name)}`"
				variant="ghost"
			>
				All receipts from {{ merchant.name }}
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { ref, watchEffect } from 'vue';
import { BbBadge, BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
import { useUploadCenter } from './context';
import { api } from '@/api';
import type { MerchantSummary } from '@/types';

const props = defineProps<{ merchantName: string }>();

const ctx = useUploadCenter();

const merchant = ref<MerchantSummary | null>(null);
watchEffect(async () => {
	merchant.value = await api.merchants.get(props.merchantName);
});

const currency = new Intl.NumberFormat('en-US', {
	style: 'currency',
	currency: 'USD',
});
</script>
```

## Why it is built this way

- **The context coopts, leaves consume.** `shell`, `table` **and the
  category catalog** are joined once in `provideUploadCenter()`; thirteen
  components share the filters, the queue, selection, the peek stack and
  every action through one `useUploadCenter()` call. No leaf imports
  `@/api` or a store directly — even the query-aware merchant pill gets
  its provider (`ctx.searchMerchants`) from the context, so the page has
  exactly one import surface.
- **Capture ≠ transfer.** `BbDropzone`'s documented contract is "these
  files are valid", nothing more: no request, no progress, no retry. So
  the dropzone leaf drains its model into `ctx.enqueueFiles()` and resets
  it, and the context owns the whole transfer lifecycle — one
  `AbortController` per file in a closure map (not render state), a
  progress callback writing into the reactive queue row, retry as a plain
  re-issue of the same upload. Constraint rejects never reach the model;
  they arrive as typed `@error` events that the leaf maps to sentences and
  feeds back through `errors` (the display is a round-trip by design).
- **Progress ticks don't refetch.** The items function returns the _live_
  queue row objects ahead of the fetched page, so a progress mutation
  re-renders exactly the one cell reading it. Membership changes —
  enqueue, remove, upload completed — are the only events that bump
  `refreshKey`; a completed upload re-enters as a server draft with the
  OCR-extracted fields prefilled, which is the row's "done" feedback (no
  per-file success toast for a 15-file drop).
- **Each editable cell type is its own leaf** — `MerchantCell`,
  `CategoryCell`, `AmountCell`, `DateCell` — never one `EditableCell` with
  a `type` prop. All four take exactly one data prop (`receipt`) and call
  one context action; the text/number cells hold a local draft (rung 1)
  with commit-on-blur/Enter and Esc-revert, the option/date cells commit
  on pick. Failed saves converge on the same path: `updateReceipt`
  refetches (reverting the cell to the server value) and toasts
  `destructive`.
- **The table context is the paging and selection spine.**
  `useBbTableContext('receipts-table', { perPage: 25 })` seeds paging;
  `fetchRows` writes `table.totalItems`; `BbPagination table-id` joins by id;
  the bulk bar reads `table.selected` with zero props from the table. The
  `selectable` predicate limits selection to server-side drafts, so bulk
  ids are always submittable receipt ids.
- **Tabs carry `href` and live counts** (`?tab=drafts`) and the same table
  is the pane — outside Drafts the cell slots fall through to plain
  formatted text, so Submitted/Reimbursed are read-only views of the same
  columns rather than a second table component.
- **`peekX` vs `stackX` is the whole stack grammar.** Filename →
  `peekReceipt` (replaces the stack); merchant name inside the peek →
  `stackMerchant` (pushes, back arrow appears); a recent receipt inside
  the merchant peek → `stackReceipt` (deeper still). The grammar lives in
  the context — a leaf cannot accidentally nuke the stack. The peek is a
  workbench: one-click category (the same `CategoryCell`), submit,
  download, confirm-guarded remove.
- **Sizing:** topbar follows `md`-first (`compact` search at 28px flush
  beside the default-size primary); `sm` appears exactly where the
  doctrine allows — row actions, pills, peek footers, the bulk bar — and
  the one `xs` (inline Retry) sits inside a table cell, the densest
  surface on the page. **One `variant="primary"`** (Submit all, with its
  live count and auto-tracked loading). Destructive actions — single,
  bulk, in-peek — all ride `useConfirm` with the filename or count in the
  message.

## Variations

- **Expense reports**: group receipts into named reports (a `reportId`
  column + a "Add to report" bulk action feeding a `BbSelectPopover` of
  open reports); the Submit-all primary becomes "Submit report".
- **Policy checks**: server flags out-of-policy drafts
  (`receipt.policyWarning`); tint the row, badge the amount cell, and
  render a `BbAlert` above the table summarizing the count.
- **Camera-first mobile**: keep `accept` image-heavy and rely on the
  native picker offering the camera; the dropzone slot collapses to a
  single "Snap a receipt" affordance under the mobile breakpoint.
- **Auto-submit on high confidence**: when `extracted.confidence` ≥ 95 and
  all four fields resolved, submit server-side on upload and toast an
  undo — the Drafts tab then only holds receipts needing review.

---

<!-- dist/ai/recipes/vue/wizard-form.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/recipes/vue/wizard-form.md -->

# Recipe: Wizard Form (Vue)

A Mailchimp-grade "Create campaign" wizard for a **plain Vue SPA with
vue-router**: four steps (Audience → Content → Schedule → Review) behind a
custom stepper header, per-step validation gating forward progress, the
active step mirrored into the URL, save-draft everywhere, and a dirty-state
leave guard — all driven by one coopting page context so every leaf
component takes zero props beyond the id the segment peek renders.

Sibling recipes: [Nuxt](../nuxt/wizard-form.md) ·
[Inertia](../inertia/wizard-form.md).

## Prerequisites

- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
  imports `PageShell` and `usePageShellContext` from your own app.
  They are not package exports; the scaffold recipe is their source. Copy
  those files before anything below, and do not hand-roll replacements —
  the peek stack, the close semantics and the sidebar's out-of-flow
  behaviour are all load-bearing here.
- `<BbConfirm />` and `<BbToast />` mounted once in the app root (`App.vue`) — never in a page.
- [App Layout](../../guides/app-layout.md) and
  [Page Shell](../../guides/page-shell.md) copied into
  `src/components/layout/` per their guides — the page renders inside this
  chrome.

## Key ideas

- **One coopting page context.** `provideCampaignWizard()` joins the
  page-shell stack once and owns the draft, the current step, the live
  validation, and every action. All seven leaves call
  `useCampaignWizard()` and nothing else — the only prop on the page is
  the id the segment peek renders.
- **The stepper is derived state, not navigation chrome.** A step is
  reachable exactly when every step before it validates — the same
  predicate `goNext()` uses — so jumping from the header can never outrun
  the validation gate. Steps already passed show `done` (checkmarked),
  reachable future steps stay numbered (`upcoming`), and `locked` steps
  render as disabled `BbBaseButton`s.
- **Validation is computed live, surfaced on demand.** `issues`
  recomputes on every keystroke, but the `BbAlert` summary and the inline
  field errors appear only after a blocked Next (`attempted`), and shrink
  live as the user fixes each problem.
- **The step lives in the URL, the draft lives on the server.** `?step=3`
  is mirrored with `router.replace`; on refresh the saved draft is
  re-fetched and the requested step is clamped to the first incomplete
  one, so a shared link can never open a locked step.
- **One `BbSmoothHeight` wraps the alert + step outlet together**, so the
  step swap _and_ the validation summary appearing both glide instead of
  snapping. Conditional regions inside a step (the scheduled-date fields)
  need no wrapper of their own — the same resize observer catches them.
- **Back and Save draft are always free; validation only guards forward.**
  The page's one `variant="primary"` is the final Send/Schedule submit,
  with `:loading` riding `ctx.submitting`.
- **Leaving is guarded by a snapshot compare.** `dirty` is a JSON diff
  against the last saved draft; `onBeforeRouteLeave` + `useConfirm` ask
  before losing changes, and both submit and discard reset the snapshot so
  they never double-prompt.

## Page anatomy

```
CampaignWizard/
	Index.vue          ← assembly: PageShell slots, stepper, BbSmoothHeight outlet, footer
	context.ts         ← coopting page context (shell + draft + step + validation + actions)
	StepperHeader.vue  ← BbBaseButton steps with done/current/upcoming/locked states
	AudienceStep.vue   ← segment select, audience filters, live recipient estimate
	ContentStep.vue    ← subject/preheader, body, template picker, send-test
	ScheduleStep.vue   ← send-now vs scheduled, date + timezone
	ReviewStep.vue     ← read-only summary with per-section Edit links
	WizardFooter.vue   ← Back · Save draft · Next / Send with :loading
	SegmentPeek.vue    ← sidebar workbench for the selected segment
```

Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
(left nav + fat footer) and [Page Shell](../../guides/page-shell.md).
Wizard archetype: no filter rail, no tabs, no table, no pagination, no bulk
bar — the work surface is the step outlet.

## Action inventory

| #   | Action                      | Trigger                          | Mechanism                                                      |
| --- | --------------------------- | -------------------------------- | -------------------------------------------------------------- |
| 1   | Advance a step (validated)  | footer **Next** (secondary)      | `goNext()` — blocks and raises the `BbAlert` summary on issues |
| 2   | Go back                     | footer **Back** (ghost)          | `goBack()` — never validated                                   |
| 3   | Jump to an unlocked step    | stepper header                   | `goToStep()`; locked steps are disabled `BbBaseButton`s        |
| 4   | Edit a section from Review  | per-section **Edit** links       | `goToStep()` back to that step                                 |
| 5   | Save draft                  | footer ghost, on every step      | `saveDraft()` → API + snapshot reset + toast                   |
| 6   | Send a test email           | Content step ghost               | `sendTest()` — validates content first, auto-loading button    |
| 7   | Send / schedule campaign    | Review, the page's one `primary` | `submit()` with `:loading`, whole-wizard validation            |
| 8   | Discard draft               | topbar, destructive              | `useConfirm` → delete + navigate to `/campaigns`               |
| 9   | Peek the segment            | segment name (Audience & Review) | `peekSegment()` → shell stack                                  |
| 10  | Leave with unsaved changes  | any route navigation             | `onBeforeRouteLeave` guard → `useConfirm`                      |
| 11  | Restore position on refresh | URL `?step=N`                    | step mirrored via `router.replace`, clamped on load            |

## The code

### context.ts

```ts
// CampaignWizard/context.ts
import {
	computed,
	inject,
	provide,
	reactive,
	ref,
	watch,
	watchEffect,
	type ComputedRef,
	type InjectionKey,
	type Ref,
} from 'vue';
import { onBeforeRouteLeave, useRoute, useRouter } from 'vue-router';
import { useConfirm, useToast } from 'bitboss-ui';
import {
	usePageShellContext,
	type PageShellContext,
} from '@/components/layout/usePageShellContext';
import { api } from '@/api';
import type { Campaign, Segment } from '@/types';

/**
 * What the sidebar can show: the audience segment behind the campaign.
 * `title` is what `PageShell`'s `#sidebar-title` slot renders — without it the
 * peek opens with an empty header.
 */
export type PeekItem = { type: 'segment'; id: number; title: string };

export type StepKey = 'audience' | 'content' | 'schedule' | 'review';
export type StepStatus = 'done' | 'current' | 'upcoming' | 'locked';
export type SendMode = 'now' | 'scheduled';

export const STEPS: Array<{ key: StepKey; label: string }> = [
	{ key: 'audience', label: 'Audience' },
	{ key: 'content', label: 'Content' },
	{ key: 'schedule', label: 'Schedule' },
	{ key: 'review', label: 'Review' },
];

export interface CampaignTemplate {
	id: string;
	name: string;
	description: string;
}

export const TEMPLATES: CampaignTemplate[] = [
	{
		id: 'product-update',
		name: 'Product update',
		description: 'Hero image, feature blocks, one CTA.',
	},
	{
		id: 'newsletter',
		name: 'Newsletter',
		description: 'Multi-story digest with section dividers.',
	},
	{
		id: 'plain-text',
		name: 'Plain text',
		description: 'No chrome — reads like a personal email.',
	},
];

export const TIMEZONES = [
	{ label: 'Rome (CET)', value: 'Europe/Rome' },
	{ label: 'London (GMT)', value: 'Europe/London' },
	{ label: 'New York (ET)', value: 'America/New_York' },
	{ label: 'Chicago (CT)', value: 'America/Chicago' },
	{ label: 'Los Angeles (PT)', value: 'America/Los_Angeles' },
	{ label: 'Tokyo (JST)', value: 'Asia/Tokyo' },
	{ label: 'Sydney (AEST)', value: 'Australia/Sydney' },
];

export const COUNTRIES = [
	{ label: 'Italy', value: 'IT' },
	{ label: 'France', value: 'FR' },
	{ label: 'Germany', value: 'DE' },
	{ label: 'United Kingdom', value: 'GB' },
	{ label: 'United States', value: 'US' },
	{ label: 'Canada', value: 'CA' },
];

/** Everything the four steps edit. Persisted verbatim by saveDraft/submit. */
export interface CampaignDraft {
	// Audience
	segmentId: number | null;
	/** Empty array = every country in the segment. */
	countries: string[];
	/** Skip contacts already emailed in the last 7 days. */
	excludeRecent: boolean;
	// Content
	subject: string;
	preheader: string;
	body: string;
	templateId: string | null;
	// Schedule
	sendMode: SendMode;
	/** ISO string from BbDatePickerInput; only meaningful when scheduled. */
	sendAt: string | null;
	timezone: string;
}

export interface StepIssue {
	/** Draft field the issue belongs to — leaves match on it for inline errors. */
	field: string;
	message: string;
}

export interface CampaignWizardContext {
	// -- Coopted contexts ------------------------------------------------------
	shell: PageShellContext<PeekItem>;
	// -- Wizard state ----------------------------------------------------------
	loading: Ref<boolean>;
	campaign: Ref<Campaign | null>;
	draft: CampaignDraft;
	step: Ref<StepKey>;
	dirty: ComputedRef<boolean>;
	lastSavedAt: Ref<string | null>;
	submitting: Ref<boolean>;
	// -- Validation ------------------------------------------------------------
	issues: ComputedRef<Record<StepKey, StepIssue[]>>;
	/** Steps whose Next was blocked at least once — only they show errors. */
	attempted: Record<StepKey, boolean>;
	stepStatus: (key: StepKey) => StepStatus;
	fieldErrors: (step: StepKey, field: string) => string[];
	// -- Audience intel --------------------------------------------------------
	selectedSegment: Ref<Segment | null>;
	estimatedRecipients: Ref<number | null>;
	// -- Peek grammar ----------------------------------------------------------
	peekSegment: () => void;
	// -- Actions (complete: API + state + toast) --------------------------------
	goToStep: (key: StepKey) => void;
	goBack: () => void;
	goNext: () => void;
	saveDraft: () => Promise<void>;
	sendTest: () => Promise<void>;
	submit: () => Promise<void>;
	discardDraft: () => Promise<void>;
}

const key: InjectionKey<CampaignWizardContext> = Symbol('campaign-wizard');

export function provideCampaignWizard(): CampaignWizardContext {
	const { toast } = useToast();
	const { confirm } = useConfirm();
	const route = useRoute();
	const router = useRouter();

	// -- Coopt the specific contexts: once, here, for the whole page. ----------
	const shell = usePageShellContext<PeekItem>();

	// -- Wizard state -----------------------------------------------------------
	// Route: `{ path: '/campaigns/:id/edit', component: … }` — the param name
	// here must match the one your route declares.
	const campaignId = Number(route.params.id);
	const campaign = ref<Campaign | null>(null);
	const loading = ref(true);

	const draft = reactive<CampaignDraft>({
		segmentId: null,
		countries: [],
		excludeRecent: true,
		subject: '',
		preheader: '',
		body: '',
		templateId: null,
		sendMode: 'now',
		sendAt: null,
		timezone: 'Europe/Rome',
	});

	// -- Validation ---------------------------------------------------------------
	// Live on every keystroke; SURFACED only per `attempted` (set when a Next
	// or submit is blocked), so untouched steps never open covered in red.
	const issues = computed<Record<StepKey, StepIssue[]>>(() => {
		const audience: StepIssue[] = [];
		if (draft.segmentId === null)
			audience.push({
				field: 'segmentId',
				message: 'Choose the segment this campaign goes to.',
			});

		const content: StepIssue[] = [];
		if (!draft.subject.trim())
			content.push({ field: 'subject', message: 'Write a subject line.' });
		else if (draft.subject.length > 150)
			content.push({
				field: 'subject',
				message: 'Keep the subject under 150 characters.',
			});
		if (!draft.body.trim())
			content.push({
				field: 'body',
				message: 'The email body cannot be empty.',
			});
		if (draft.templateId === null)
			content.push({ field: 'templateId', message: 'Pick a template.' });

		const schedule: StepIssue[] = [];
		if (draft.sendMode === 'scheduled') {
			if (!draft.sendAt)
				schedule.push({ field: 'sendAt', message: 'Pick a send date.' });
			if (!draft.timezone)
				schedule.push({ field: 'timezone', message: 'Pick a timezone.' });
		}

		return { audience, content, schedule, review: [] };
	});

	const attempted = reactive<Record<StepKey, boolean>>({
		audience: false,
		content: false,
		schedule: false,
		review: false,
	});

	const fieldErrors = (stepKey: StepKey, field: string): string[] =>
		attempted[stepKey]
			? issues.value[stepKey]
					.filter((issue) => issue.field === field)
					.map((issue) => issue.message)
			: [];

	// -- Step machine ---------------------------------------------------------------
	const step = ref<StepKey>('audience');

	const indexOf = (stepKey: StepKey) =>
		STEPS.findIndex((item) => item.key === stepKey);

	// The single gating predicate: a step is reachable when every step
	// before it validates. Next, the stepper, and submit all derive from it.
	const unlocked = (stepKey: StepKey) =>
		STEPS.slice(0, indexOf(stepKey)).every(
			(item) => issues.value[item.key].length === 0
		);

	const stepStatus = (stepKey: StepKey): StepStatus => {
		if (stepKey === step.value) return 'current';
		// Only steps already passed count as done — unlocked future steps stay
		// numbered (upcoming), not checkmarked.
		if (indexOf(stepKey) < indexOf(step.value)) return 'done';
		return unlocked(stepKey) ? 'upcoming' : 'locked';
	};

	const firstIncompleteStep = (): StepKey =>
		STEPS.find((item) => issues.value[item.key].length > 0)?.key ?? 'review';

	const goToStep = (stepKey: StepKey) => {
		if (stepKey !== step.value && stepStatus(stepKey) === 'locked') return;
		step.value = stepKey;
	};

	const goBack = () => {
		const previous = STEPS[indexOf(step.value) - 1];
		if (previous) step.value = previous.key;
	};

	const goNext = () => {
		const current = step.value;
		if (issues.value[current].length > 0) {
			attempted[current] = true; // raises the alert + inline errors
			return;
		}
		attempted[current] = false;
		const next = STEPS[indexOf(current) + 1];
		if (next) step.value = next.key;
	};

	// Mirror the step into the URL so refresh and shared links restore it.
	watch(step, (next) => {
		void router.replace({
			query: { ...route.query, step: String(indexOf(next) + 1) },
		});
	});

	// -- Audience intel ---------------------------------------------------------------
	// The select's v-model holds only the id; Review and the summary box need
	// the record. Same resolve-by-id pattern as the flagship's customer pill.
	const selectedSegment = ref<Segment | null>(null);
	watchEffect(async () => {
		selectedSegment.value =
			draft.segmentId === null ? null : await api.segments.get(draft.segmentId);
	});

	const estimatedRecipients = ref<number | null>(null);
	watchEffect(async () => {
		if (draft.segmentId === null) {
			estimatedRecipients.value = null;
			return;
		}
		estimatedRecipients.value = await api.segments.estimate(draft.segmentId, {
			countries: [...draft.countries],
			excludeRecent: draft.excludeRecent,
		});
	});

	// -- Peek grammar ----------------------------------------------------------------
	const peekSegment = () => {
		if (draft.segmentId !== null)
			shell.push({ type: 'segment', id: draft.segmentId }, true);
	};

	// -- Persistence + dirty guard ------------------------------------------------------
	const snapshot = ref('');
	const lastSavedAt = ref<string | null>(null);
	const dirty = computed(
		() => !loading.value && JSON.stringify(draft) !== snapshot.value
	);

	// Registered here because provideCampaignWizard() runs in the setup of the
	// route component (Index.vue) — exactly where vue-router allows it.
	onBeforeRouteLeave(async () => {
		if (!dirty.value) return true;
		return confirm({
			variant: 'destructive',
			title: 'Leave campaign setup?',
			text: 'You have unsaved changes. Leave and lose them, or stay and save the draft.',
			yes: 'Leave',
			no: 'Keep editing',
		});
	});

	// The client gate only guards FORWARD navigation — it never blocks this call.
	// The endpoint, though, runs the same whole-draft validation the final submit
	// runs, so saving a half-filled draft rejects with 422. Handle it: an
	// unhandled rejection here surfaces as a console error and the user gets no
	// feedback at all.
	const saveDraft = async () => {
		try {
			await api.campaigns.update(campaignId, { ...draft });
		} catch (error) {
			const err = error as { status?: number };
			if (err.status === 422) {
				toast({
					title: 'Finish the highlighted fields before saving.',
					variant: 'destructive',
				});
				return;
			}
			toast({
				title: 'Something went wrong. Try again.',
				variant: 'destructive',
			});
			return;
		}
		snapshot.value = JSON.stringify(draft);
		lastSavedAt.value = new Date().toISOString();
		toast({ title: 'Draft saved.', variant: 'success' });
	};

	const sendTest = async () => {
		if (issues.value.content.length > 0) {
			attempted.content = true; // same surfacing as a blocked Next
			return;
		}
		await api.campaigns.sendTest(campaignId, { ...draft });
		toast({ title: 'Test email sent to your address.', variant: 'success' });
	};

	const submitting = ref(false);
	const submit = async () => {
		// Whole-wizard validation: land the user on the first broken step.
		const incomplete = STEPS.find((item) => issues.value[item.key].length > 0);
		if (incomplete) {
			attempted[incomplete.key] = true;
			step.value = incomplete.key;
			return;
		}
		submitting.value = true;
		try {
			await api.campaigns.update(campaignId, { ...draft });
			await api.campaigns.send(campaignId);
			snapshot.value = JSON.stringify(draft); // the guard has nothing left to protect
			toast({
				title:
					draft.sendMode === 'now'
						? 'Campaign is on its way.'
						: 'Campaign scheduled.',
				variant: 'success',
			});
			await router.push('/campaigns');
		} finally {
			submitting.value = false;
		}
	};

	const discardDraft = async () => {
		const ok = await confirm({
			variant: 'destructive',
			title: 'Discard draft',
			text: `Delete "${campaign.value?.name ?? 'this campaign'}" and everything entered so far? This cannot be undone.`,
			yes: 'Discard',
			no: 'Keep draft',
		});
		if (!ok) return;
		snapshot.value = JSON.stringify(draft); // don't double-prompt via the leave guard
		await api.campaigns.delete(campaignId);
		toast({ title: 'Draft discarded.', variant: 'success' });
		await router.push('/campaigns');
	};

	// -- Load ------------------------------------------------------------------------
	// The wizard edits a server-side draft (the list page created it before
	// navigating here, Mailchimp-style), so a refresh restores every field —
	// and ?step restores the position, clamped so it can't open a locked step.
	const initialize = async () => {
		// `get` resolves `null` for an unknown id (a hand-typed URL), so it cannot
		// be destructured blind — that both fails to type-check and throws at
		// runtime. Baseline the snapshot either way, otherwise an empty draft
		// reads as "unsaved changes" and the leave guard fires on a dead page.
		const loaded = await api.campaigns.get(campaignId);
		if (loaded) {
			campaign.value = loaded.campaign;
			Object.assign(draft, loaded.draft);
		}
		snapshot.value = JSON.stringify(draft);
		const requested = STEPS[Number(route.query.step) - 1]?.key ?? 'audience';
		step.value =
			stepStatus(requested) === 'locked' ? firstIncompleteStep() : requested;
		loading.value = false;
	};
	void initialize();

	const ctx: CampaignWizardContext = {
		shell,
		loading,
		campaign,
		draft,
		step,
		dirty,
		lastSavedAt,
		submitting,
		issues,
		attempted,
		stepStatus,
		fieldErrors,
		selectedSegment,
		estimatedRecipients,
		peekSegment,
		goToStep,
		goBack,
		goNext,
		saveDraft,
		sendTest,
		submit,
		discardDraft,
	};
	provide(key, ctx);
	return ctx;
}

export function useCampaignWizard(): CampaignWizardContext {
	const ctx = inject(key);
	if (!ctx)
		throw new Error('useCampaignWizard() called outside CampaignWizard');
	return ctx;
}
```

### Index.vue — the assembly

```vue
<!-- CampaignWizard/Index.vue -->
<template>
	<PageShell>
		<!-- Topbar: breadcrumbs left; save state + the destructive escape right.
		     Wizard archetype: no page search, no filter rail, no tabs. -->
		<template #topbar>
			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
				     without it their overflow recompute fights the flex layout every frame. -->
				<BbBreadcrumbs class="min-w-0 flex-auto" :items="crumbs" />
				<div class="flex shrink-0 items-center gap-3">
					<span
						v-if="savedLabel"
						class="text-xs text-[color:var(--bb-text-muted)]"
						>{{ savedLabel }}</span
					>
					<BbButton
						prepend:icon="lucide:trash-2"
						variant="destructive"
						@click="ctx.discardDraft"
					>
						Discard draft
					</BbButton>
				</div>
			</div>
		</template>

		<div class="mx-auto flex w-full max-w-3xl flex-col gap-5 p-4">
			<header class="flex flex-col gap-0.5">
				<h1 class="text-lg font-semibold">
					{{ ctx.campaign.value?.name ?? 'New campaign' }}
				</h1>
				<p class="text-sm text-[color:var(--bb-text-muted)]">
					Set up the audience, content and schedule, then review and send.
				</p>
			</header>

			<StepperHeader />

			<!-- One wrapper around the alert AND the step outlet: the step swap
			     and the validation summary appearing/shrinking both glide. -->
			<!-- Enable height motion only after mount so first paint does not
			     animate in; later step swaps still glide. -->
			<BbSmoothHeight :disabled="!stepHeightReady">
				<div class="flex flex-col gap-4">
					<BbAlert
						v-if="summaryIssues.length"
						hide-close
						icon="lucide:circle-x"
						:title="`Fix ${summaryIssues.length} ${summaryIssues.length === 1 ? 'issue' : 'issues'} to continue`"
						variant="destructive"
					>
						<template #text>
							<ul class="list-disc pl-4">
								<li v-for="issue in summaryIssues" :key="issue.field">
									{{ issue.message }}
								</li>
							</ul>
						</template>
					</BbAlert>

					<div v-if="ctx.loading.value" class="flex justify-center p-10">
						<BbSpinner />
					</div>
					<AudienceStep v-else-if="ctx.step.value === 'audience'" />
					<ContentStep v-else-if="ctx.step.value === 'content'" />
					<ScheduleStep v-else-if="ctx.step.value === 'schedule'" />
					<ReviewStep v-else />
				</div>
			</BbSmoothHeight>

			<WizardFooter />
		</div>

		<!-- Clicking the segment's NAME peeks it — Audience step and Review. -->
		<template #sidebar>
			<SegmentPeek
				v-if="ctx.shell.current.value?.type === 'segment'"
				:segment-id="ctx.shell.current.value.id"
			/>
		</template>
	</PageShell>
</template>

<script setup lang="ts">
import { computed, onMounted, ref } from 'vue';
import {
	BbAlert,
	BbBreadcrumbs,
	BbButton,
	BbSmoothHeight,
	BbSpinner,
} from 'bitboss-ui';
import PageShell from '@/components/layout/PageShell.vue';
import { provideCampaignWizard } from './context';
import AudienceStep from './AudienceStep.vue';
import ContentStep from './ContentStep.vue';
import ReviewStep from './ReviewStep.vue';
import ScheduleStep from './ScheduleStep.vue';
import SegmentPeek from './SegmentPeek.vue';
import StepperHeader from './StepperHeader.vue';
import WizardFooter from './WizardFooter.vue';

const ctx = provideCampaignWizard();

/** Keep SmoothHeight off while the first paint settles (initial load swaps
 * spinner → step content); enable after 300ms for step-to-step glides. */
const stepHeightReady = ref(false);
onMounted(() => {
	setTimeout(() => {
		stepHeightReady.value = true;
	}, 300);
});

const crumbs = computed(() => [
	{ key: 'dashboard', text: 'Dashboard', to: '/dashboard' },
	{ key: 'campaigns', text: 'Campaigns', to: '/campaigns' },
	{ key: 'setup', text: ctx.campaign.value?.name ?? 'New campaign' },
]);

// The summary shows only the CURRENT step's issues, and only once the user
// tried to leave it — it shrinks live as each problem is fixed.
const summaryIssues = computed(() =>
	ctx.attempted[ctx.step.value] ? ctx.issues.value[ctx.step.value] : []
);

const savedLabel = computed(() => {
	if (ctx.dirty.value) return 'Unsaved changes';
	if (!ctx.lastSavedAt.value) return null;
	const time = new Date(ctx.lastSavedAt.value).toLocaleTimeString('en-US', {
		hour: 'numeric',
		minute: '2-digit',
	});
	return `Draft saved at ${time}`;
});
</script>
```

### StepperHeader.vue

```vue
<!-- CampaignWizard/StepperHeader.vue -->
<template>
	<nav aria-label="Campaign setup steps" class="flex items-center gap-1">
		<template v-for="(stepMeta, index) in STEPS" :key="stepMeta.key">
			<!-- Connector line between steps. -->
			<div
				v-if="index > 0"
				aria-hidden="true"
				class="h-px min-w-3 flex-1 bg-[var(--bb-border)]"
			/>

			<!-- The primitive gives element semantics + disabled handling; the
			     look is entirely ours. Done and upcoming steps jump, locked
			     steps are inert. -->
			<BbBaseButton
				:aria-current="status(stepMeta.key) === 'current' ? 'step' : undefined"
				class="flex items-center gap-2 rounded-[var(--bb-radius)] px-2 py-1.5 text-sm focus-visible:ring-2 focus-visible:ring-[var(--bb-primary)]"
				:class="{
					'bg-[var(--bb-hover)] font-medium':
						status(stepMeta.key) === 'current',
					'hover:bg-[var(--bb-hover)]': ['done', 'upcoming'].includes(
						status(stepMeta.key)
					),
					'text-[color:var(--bb-text-muted)]':
						status(stepMeta.key) === 'locked',
				}"
				:disabled="status(stepMeta.key) === 'locked'"
				@click="() => ctx.goToStep(stepMeta.key)"
			>
				<span
					class="flex size-5 shrink-0 items-center justify-center rounded-full border text-xs"
					:class="{
						'border-transparent bg-[var(--bb-primary)] text-[var(--bb-primary-fg)]':
							status(stepMeta.key) === 'done',
						'border-[var(--bb-primary)] text-[color:var(--bb-primary)]':
							status(stepMeta.key) === 'current',
						'border-[var(--bb-border)]': status(stepMeta.key) === 'locked',
					}"
				>
					<BbIcon
						v-if="status(stepMeta.key) === 'done'"
						icon="lucide:check"
						size="12"
					/>
					<template v-else>{{ index + 1 }}</template>
				</span>
				{{ stepMeta.label }}
			</BbBaseButton>
		</template>
	</nav>
</template>

<script setup lang="ts">
import { BbBaseButton, BbIcon } from 'bitboss-ui';
import { STEPS, useCampaignWizard, type StepKey } from './context';

const ctx = useCampaignWizard();

const status = (key: StepKey) => ctx.stepStatus(key);
</script>
```

### AudienceStep.vue

```vue
<!-- CampaignWizard/AudienceStep.vue -->
<template>
	<section class="flex flex-col gap-4">
		<div class="flex flex-col gap-0.5">
			<h2 class="text-base font-semibold">Who gets this email?</h2>
			<p class="text-sm text-[color:var(--bb-text-muted)]">
				Pick a segment, then narrow it with delivery filters.
			</p>
		</div>

		<!-- Query-aware items function: the select searches the API as you type. -->
		<BbSelect
			v-model="ctx.draft.segmentId"
			:errors="segmentErrors"
			item-text="name"
			item-value="id"
			:items="searchSegments"
			label="Segment"
			label-mode="outside"
			placeholder="Search segments…"
			required
		/>

		<!-- Resolved segment + live estimate: the context owns both fetches. -->
		<div
			v-if="ctx.selectedSegment.value"
			class="flex flex-col gap-1 rounded-[var(--bb-radius)] border p-3 text-sm"
		>
			<div class="flex items-center justify-between gap-2">
				<BbButton size="sm" variant="link" @click="ctx.peekSegment">
					{{ ctx.selectedSegment.value.name }}
				</BbButton>
				<span class="text-xs text-[color:var(--bb-text-muted)]">
					Last synced {{ shortDate(ctx.selectedSegment.value.lastSyncedAt) }}
				</span>
			</div>
			<p class="text-[color:var(--bb-text-muted)]">
				{{ number.format(ctx.selectedSegment.value.contactCount) }} contacts in
				the segment ·
				<strong class="text-[var(--bb-text)]">
					{{
						ctx.estimatedRecipients.value === null
							? '…'
							: number.format(ctx.estimatedRecipients.value)
					}}
				</strong>
				estimated recipients after filters
			</p>
		</div>

		<BbSelect
			v-model="ctx.draft.countries"
			:items="COUNTRIES"
			item-text="label"
			item-value="value"
			label="Limit to countries"
			label-mode="outside"
			multiple
			placeholder="All countries"
		/>

		<BbSwitch
			v-model="ctx.draft.excludeRecent"
			description="Avoids fatigue: anyone who already received a campaign this week is skipped."
			label="Skip contacts emailed in the last 7 days"
		/>
	</section>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton, BbSelect, BbSwitch } from 'bitboss-ui';
import { COUNTRIES, useCampaignWizard } from './context';
import { api } from '@/api';
import type { Segment } from '@/types';

const ctx = useCampaignWizard();

const searchSegments = (query: string): Promise<Segment[]> =>
	api.segments.list({ search: query });

// Inline errors appear only after a blocked Next (attempted), per the context.
const segmentErrors = computed(() => ctx.fieldErrors('audience', 'segmentId'));

const number = new Intl.NumberFormat('en-US');
const shortDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
	});
</script>
```

### ContentStep.vue

```vue
<!-- CampaignWizard/ContentStep.vue -->
<template>
	<section class="flex flex-col gap-4">
		<div class="flex flex-col gap-0.5">
			<h2 class="text-base font-semibold">What does it say?</h2>
			<p class="text-sm text-[color:var(--bb-text-muted)]">
				Subject and preheader are what people see in the inbox list.
			</p>
		</div>

		<BbTextInput
			v-model="ctx.draft.subject"
			:description="`${ctx.draft.subject.length}/150 characters`"
			:errors="errorsFor('subject')"
			label="Subject line"
			label-mode="outside"
			placeholder="The July roast drop is here — 20% off subscriptions"
			required
		/>

		<BbTextInput
			v-model="ctx.draft.preheader"
			description="Optional. Shows after the subject in most inboxes — keep it under 90 characters."
			label="Preheader"
			label-mode="outside"
			placeholder="Three new single origins, roasted this week."
		/>

		<!-- Fixed rows on purpose: an auto-growing textarea inside BbSmoothHeight
		     would re-animate the outlet on every line break while typing. -->
		<BbTextarea
			v-model="ctx.draft.body"
			:errors="errorsFor('body')"
			label="Body"
			label-mode="outside"
			placeholder="Write the email…"
			required
			:rows="10"
		/>

		<BbRadioGroup
			v-model="ctx.draft.templateId"
			:errors="errorsFor('templateId')"
			item-text="name"
			item-value="id"
			:items="TEMPLATES"
			legend="Template"
			name="template"
			required
		>
			<!-- Name + one-line description per option, from the same items. -->
			<template #label="{ item, text }">
				<span class="flex flex-col">
					<span>{{ text }}</span>
					<span class="text-xs text-[color:var(--bb-text-muted)]">{{
						item.description
					}}</span>
				</span>
			</template>
		</BbRadioGroup>

		<!-- Auto-loading: the button tracks the async handler by itself. -->
		<div>
			<BbButton
				prepend:icon="lucide:send"
				variant="ghost"
				@click="ctx.sendTest"
			>
				Send test email
			</BbButton>
		</div>
	</section>
</template>

<script setup lang="ts">
import { BbButton, BbRadioGroup, BbTextarea, BbTextInput } from 'bitboss-ui';
import { TEMPLATES, useCampaignWizard } from './context';

const ctx = useCampaignWizard();

const errorsFor = (field: string) => ctx.fieldErrors('content', field);
</script>
```

### ScheduleStep.vue

```vue
<!-- CampaignWizard/ScheduleStep.vue -->
<template>
	<section class="flex flex-col gap-4">
		<div class="flex flex-col gap-0.5">
			<h2 class="text-base font-semibold">When does it go out?</h2>
			<p class="text-sm text-[color:var(--bb-text-muted)]">
				Send it as soon as you confirm, or pick a date.
			</p>
		</div>

		<BbRadioGroup
			v-model="ctx.draft.sendMode"
			item-text="label"
			item-value="value"
			:items="[
				{
					label: 'Send now — goes out as soon as you confirm on Review',
					value: 'now',
				},
				{ label: 'Schedule for later', value: 'scheduled' },
			]"
			legend="When to send"
			name="send-mode"
		/>

		<!-- No inner BbSmoothHeight: the page-level wrapper's resize observer
		     already animates this region appearing and disappearing. -->
		<div
			v-if="ctx.draft.sendMode === 'scheduled'"
			class="grid gap-4 sm:grid-cols-2"
		>
			<BbDatePickerInput
				v-model="ctx.draft.sendAt"
				description="Campaigns go out at 9:00 AM local to the timezone you pick."
				:errors="errorsFor('sendAt')"
				label="Send date"
				label-mode="outside"
				:min="today"
				required
			/>
			<BbSelect
				v-model="ctx.draft.timezone"
				:errors="errorsFor('timezone')"
				item-text="label"
				item-value="value"
				:items="TIMEZONES"
				label="Timezone"
				label-mode="outside"
				required
			/>
		</div>
	</section>
</template>

<script setup lang="ts">
import { BbDatePickerInput, BbRadioGroup, BbSelect } from 'bitboss-ui';
import { TIMEZONES, useCampaignWizard } from './context';

const ctx = useCampaignWizard();

const errorsFor = (field: string) => ctx.fieldErrors('schedule', field);

// BbDatePickerInput's min takes YYYY-MM-DD.
const today = new Date().toISOString().slice(0, 10);
</script>
```

### ReviewStep.vue

```vue
<!-- CampaignWizard/ReviewStep.vue -->
<template>
	<section class="flex flex-col gap-5">
		<div class="flex flex-col gap-0.5">
			<h2 class="text-base font-semibold">Review and send</h2>
			<p class="text-sm text-[color:var(--bb-text-muted)]">
				Everything below is what goes out. Edit any section — your progress is
				kept.
			</p>
		</div>

		<!-- Audience -->
		<section
			class="flex flex-col gap-2 rounded-[var(--bb-radius)] border p-3 text-sm"
		>
			<div class="flex items-center justify-between gap-2">
				<h3
					class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
				>
					Audience
				</h3>
				<BbButton
					prepend:icon="lucide:pencil"
					size="sm"
					variant="ghost"
					@click="() => ctx.goToStep('audience')"
				>
					Edit
				</BbButton>
			</div>
			<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
				<dt class="text-[color:var(--bb-text-muted)]">Segment</dt>
				<dd>
					<BbButton size="sm" variant="link" @click="ctx.peekSegment">
						{{ ctx.selectedSegment.value?.name ?? '—' }}
					</BbButton>
				</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Countries</dt>
				<dd>{{ countryNames || 'All countries' }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Fatigue filter</dt>
				<dd>
					{{
						ctx.draft.excludeRecent
							? 'Skipping contacts emailed in the last 7 days'
							: 'Off'
					}}
				</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Estimated recipients</dt>
				<dd class="font-medium">
					{{
						ctx.estimatedRecipients.value === null
							? '—'
							: number.format(ctx.estimatedRecipients.value)
					}}
				</dd>
			</dl>
		</section>

		<!-- Content -->
		<section
			class="flex flex-col gap-2 rounded-[var(--bb-radius)] border p-3 text-sm"
		>
			<div class="flex items-center justify-between gap-2">
				<h3
					class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
				>
					Content
				</h3>
				<BbButton
					prepend:icon="lucide:pencil"
					size="sm"
					variant="ghost"
					@click="() => ctx.goToStep('content')"
				>
					Edit
				</BbButton>
			</div>
			<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
				<dt class="text-[color:var(--bb-text-muted)]">Subject</dt>
				<dd class="font-medium">{{ ctx.draft.subject }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Preheader</dt>
				<dd>{{ ctx.draft.preheader || '—' }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Template</dt>
				<dd>{{ templateName }}</dd>
				<dt class="text-[color:var(--bb-text-muted)]">Body</dt>
				<dd class="text-[color:var(--bb-text-muted)]">{{ bodyExcerpt }}</dd>
			</dl>
		</section>

		<!-- Schedule -->
		<section
			class="flex flex-col gap-2 rounded-[var(--bb-radius)] border p-3 text-sm"
		>
			<div class="flex items-center justify-between gap-2">
				<h3
					class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
				>
					Schedule
				</h3>
				<BbButton
					prepend:icon="lucide:pencil"
					size="sm"
					variant="ghost"
					@click="() => ctx.goToStep('schedule')"
				>
					Edit
				</BbButton>
			</div>
			<p>{{ scheduleSummary }}</p>
		</section>
	</section>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton } from 'bitboss-ui';
import { COUNTRIES, TEMPLATES, TIMEZONES, useCampaignWizard } from './context';

const ctx = useCampaignWizard();

const number = new Intl.NumberFormat('en-US');

const countryNames = computed(() =>
	ctx.draft.countries
		.map(
			(code) =>
				COUNTRIES.find((country) => country.value === code)?.label ?? code
		)
		.join(', ')
);

const templateName = computed(
	() =>
		TEMPLATES.find((template) => template.id === ctx.draft.templateId)?.name ??
		'—'
);

const bodyExcerpt = computed(() =>
	ctx.draft.body.length > 140
		? `${ctx.draft.body.slice(0, 140)}…`
		: ctx.draft.body
);

const scheduleSummary = computed(() => {
	if (ctx.draft.sendMode === 'now')
		return 'Sends immediately after you confirm.';
	if (!ctx.draft.sendAt) return '—';
	const date = new Date(ctx.draft.sendAt).toLocaleDateString('en-US', {
		weekday: 'short',
		month: 'short',
		day: 'numeric',
		year: 'numeric',
	});
	const zone =
		TIMEZONES.find((timezone) => timezone.value === ctx.draft.timezone)
			?.label ?? ctx.draft.timezone;
	return `Scheduled for ${date} · 9:00 AM · ${zone}`;
});
</script>
```

### WizardFooter.vue

```vue
<!-- CampaignWizard/WizardFooter.vue -->
<template>
	<footer class="flex items-center justify-between gap-2 border-t pt-4">
		<!-- Back is always free — never validated, only bounded. -->
		<BbButton
			:disabled="isFirst"
			prepend:icon="lucide:chevron-left"
			variant="ghost"
			@click="ctx.goBack"
		>
			Back
		</BbButton>

		<div class="flex items-center gap-2">
			<!-- On every step, whatever the validation state. -->
			<BbButton
				prepend:icon="lucide:save"
				variant="ghost"
				@click="ctx.saveDraft"
			>
				Save draft
			</BbButton>

			<BbButton
				v-if="!isReview"
				append:icon="lucide:chevron-right"
				variant="secondary"
				@click="ctx.goNext"
			>
				Next
			</BbButton>

			<!-- The page's single primary. -->
			<BbButton
				v-else
				:loading="ctx.submitting.value"
				prepend:icon="lucide:send"
				variant="primary"
				@click="ctx.submit"
			>
				{{
					ctx.draft.sendMode === 'now' ? 'Send campaign' : 'Schedule campaign'
				}}
			</BbButton>
		</div>
	</footer>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import { BbButton } from 'bitboss-ui';
import { STEPS, useCampaignWizard } from './context';

const ctx = useCampaignWizard();

const isFirst = computed(() => ctx.step.value === STEPS[0].key);
const isReview = computed(() => ctx.step.value === 'review');
</script>
```

### SegmentPeek.vue

```vue
<!-- CampaignWizard/SegmentPeek.vue -->
<template>
	<div v-if="segment" class="flex flex-col gap-4 text-sm">
		<header class="flex flex-col gap-0.5">
			<h2 class="text-base font-semibold">{{ segment.name }}</h2>
			<p class="text-xs text-[color:var(--bb-text-muted)]">
				{{ number.format(segment.contactCount) }} contacts · last synced
				{{ longDate(segment.lastSyncedAt) }}
			</p>
		</header>

		<!-- Stat strip. -->
		<div class="grid grid-cols-3 gap-2">
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Avg. open rate</p>
				<p class="font-semibold">{{ percent(segment.openRate) }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">Avg. click rate</p>
				<p class="font-semibold">{{ percent(segment.clickRate) }}</p>
			</div>
			<div class="rounded-[var(--bb-radius)] border p-2">
				<p class="text-xs text-[color:var(--bb-text-muted)]">
					Unsubscribes / mo
				</p>
				<p class="font-semibold">
					{{ number.format(segment.monthlyUnsubscribes) }}
				</p>
			</div>
		</div>

		<!-- The segment's definition, so "who is in here" is answerable in place. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Conditions
			</h3>
			<ul class="flex flex-col gap-1">
				<li v-for="rule in segment.rules" :key="rule" class="flex gap-2">
					<BbIcon
						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
						icon="lucide:filter"
						size="14"
					/>
					<span>{{ rule }}</span>
				</li>
			</ul>
		</section>

		<!-- Recent campaigns to this segment: fatigue check before sending. -->
		<section class="flex flex-col gap-1.5">
			<h3
				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
			>
				Recent campaigns
			</h3>
			<ul class="flex flex-col">
				<li
					v-for="recent in segment.recentCampaigns"
					:key="recent.id"
					class="flex items-center justify-between gap-2 border-b py-1.5 last:border-b-0"
				>
					<span>{{ recent.name }}</span>
					<span class="text-xs text-[color:var(--bb-text-muted)]">{{
						longDate(recent.sentAt)
					}}</span>
				</li>
			</ul>
		</section>

		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
			<BbButton
				append:icon="lucide:arrow-up-right"
				size="sm"
				:to="`/segments/${segment.id}`"
				variant="ghost"
			>
				Open segment
			</BbButton>
		</footer>
	</div>

	<div v-else class="flex justify-center p-8">
		<BbSpinner />
	</div>
</template>

<script setup lang="ts">
import { ref, watchEffect } from 'vue';
import { BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
import { api } from '@/api';
import type { SegmentDetail } from '@/types';

const props = defineProps<{ segmentId: number }>();

const segment = ref<SegmentDetail | null>(null);
watchEffect(async () => {
	segment.value = await api.segments.getDetail(props.segmentId);
});

const number = new Intl.NumberFormat('en-US');
const percent = (value: number) => `${(value * 100).toFixed(1)}%`;
const longDate = (value: string) =>
	new Date(value).toLocaleDateString('en-US', {
		month: 'short',
		day: 'numeric',
		year: 'numeric',
	});
</script>
```

## Why it is built this way

- **The context coopts, leaves consume.** `shell` is joined once in
  `provideCampaignWizard()`; seven components share the draft, the step
  machine, validation and every action through one `useCampaignWizard()`
  call. The only data prop on the page is `SegmentPeek`'s `segment-id`;
  no component receives a callback.
- **One gating predicate rules everything.** `unlocked(step)` — every
  step before it validates — drives the stepper's `upcoming`/`locked`
  states, `goToStep`'s guard, and (via `issues[current]`) `goNext`. A
  stepper jump is therefore exactly as safe as pressing Next the right
  number of times; the header can never smuggle the user past validation.
  Only steps already passed count as `done` — a defaulted step (Schedule
  starts valid on "send now") stays numbered (`upcoming`), not
  checkmarked, until the user actually moves past it, though it is
  jumpable straight away: there is genuinely nothing left to do there.
- **Live issues, deferred surfacing.** Recomputing `issues` on every
  keystroke keeps the stepper and the summary truthful, but errors render
  only for `attempted` steps — a form that opens covered in red before the
  user typed anything is the classic wizard failure. Once raised, the
  summary and inline errors shrink live as each fix lands, and the inputs
  take plain `:errors` arrays (a non-empty `errors` prop already implies
  the error state — no separate `has-errors` wiring).
- **Steps are four components, not one with a `type` prop.** Each step
  owns its inputs, its formatting helpers, and nothing else; the assembly
  is a `v-if` chain inside the `BbSmoothHeight` outlet. A single
  `WizardStep` with a renderer switch is the API-monster seed.
- **`BbBaseButton` is the right stepper primitive.** The steps are
  clickable surfaces whose look is entirely bespoke — token-styled pills
  with a number/check bullet — and the primitive contributes what CSS
  can't: a real `<button>`, native `disabled` for locked steps, and a
  focus scaffold (the visible ring is ours, per its guide). `aria-current="step"`
  is set manually — the prop-based `ariaCurrentValue` only applies to
  exact-active _links_.
- **One `BbSmoothHeight`, wrapping alert + outlet.** Both height changes
  on this page — the step swap and the summary toggling — animate through
  the same wrapper, so they compose into one glide when Next is blocked.
  Regions that appear _inside_ a step (the scheduled-date grid) are caught
  by the same resize observer; and the body textarea keeps fixed `rows`
  because an auto-growing textarea inside the wrapper would re-animate the
  outlet on every line break. Height motion is enabled only after mount
  (`:disabled` until a 300ms `onMounted` flag flips), so the first paint
  never animates in.
- **Refresh restores everything** because the two halves of wizard state
  live in the right places: field values on the server (the list page
  created the draft record before navigating here, so `saveDraft` is an
  update, not a create), position in the URL. On load the requested
  `?step` is clamped to the first incomplete step, so a stale or forged
  link degrades to the right place instead of an unusable locked screen.
- **The guard, submit and discard share one snapshot.** `dirty` is a JSON
  compare against the last save; `submit` and `discardDraft` reset the
  snapshot before navigating so the route-leave confirm never re-asks
  about changes that were just sent or deliberately destroyed.
- **Sizing:** everything follows `md`-first — footer, topbar and step
  forms use default-size buttons and regular inputs; `sm` appears only on
  the dense inline surfaces (Review's Edit/segment links, the peek
  footer). One `variant="primary"` (Send/Schedule); Next is `secondary`;
  Save draft, Back and Send test are ghosts; the two destructive actions
  (discard, leave-with-changes) both ride `useConfirm`.

## Variations

- **Branching steps**: make `STEPS` a computed — e.g. an A/B test
  campaign inserts a "Variants" step after Content. The status predicate,
  URL mapping and footer already work off the array, so nothing else
  changes.
- **Autosave**: debounce a watcher on `draft` that calls a silent
  `saveDraft` (no toast); the footer button and the topbar save-state stay
  as the manual escape, and the leave guard almost never fires.
- **Vertical checklist stepper** (Mailchimp's actual layout): swap
  `StepperHeader` for a left rail where each step row also shows its
  one-line summary and the step bodies expand in place — the context and
  its predicate are unchanged.
- **Send time**: add an hour `BbSelect` beside the timezone and fold it
  into `sendAt` on save, replacing the fixed 9:00 AM policy.

---

<!-- dist/ai/WarningIcon.md -->
<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/WarningIcon.md -->

# WarningIcon

## Agent Contract

- Safety level: **Reference Only - Internal**
- Group: **Feedback**
- Description: Renders the reusable warning-state icon glyph used in validation UIs.
- Usage rule: Do not use this component in consumer-facing solutions unless explicitly requested.
- Implementation source (only when the contract below is not enough): [source/WarningIcon.md](./source/WarningIcon.md)

## Props

- None.

## Events

- None.

## Slots

- None.

---