bitboss-ui 2.1.135 → 3.0.0-alpha.1

package/dist/ai/BbTabs.md

@@ -0,0 +1,1113 @@
+# BbTabs
+
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Navigation**
+- Description: Switches between tabbed content views (shadcn-like strip; BbTabRoot enables 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-gray-500">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-gray-500">
+						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-gray-500">{{ 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-gray-500">{{
+							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-gray-600">{{ 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-gray-500">
+							{{ thread.from }} · {{ thread.when }}
+						</p>
+					</li>
+				</ul>
+			</template>
+			<template #sent>
+				<p class="pt-3 text-sm text-gray-500">12 messages sent this week.</p>
+			</template>
+			<template #spam>
+				<p class="pt-3 text-sm text-gray-500">
+					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-gray-500">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-gray-600 dark:text-gray-300">
+					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-gray-600 dark:text-gray-300">
+					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-gray-500">
+				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-gray-600 dark:text-gray-300">{{ previewBody }}</p>
+					</template>
+					<p v-else class="text-gray-500">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-gray-500">
+				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-gray-500"> · {{ member.email }}</span>
+						</span>
+						<span class="shrink-0 text-xs text-gray-500">{{
+							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-gray-500">
+						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-gray-600">Environment status at a glance.</p></template>
+		<template #integrations><p class="pt-3 text-sm text-gray-600">Connected services.</p></template>
+		<template #billing><p class="pt-3 text-sm text-gray-600">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-gray-600">Workspace basics.</p></template>
+		<template #security><p class="px-3 text-sm text-gray-600">Sessions and 2FA.</p></template>
+		<template #api><p class="px-3 text-sm text-gray-600">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-gray-500">
+				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>
+			<template v-for="release in releases" :key="release.key" #[release.key]>
+				<p class="pt-3 text-sm text-gray-600 dark:text-gray-300">
+					{{ 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 } 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-gray-500">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-gray-600 dark:text-gray-300">
+							Health stable · owners Alex + Sam · objective: cut checkout
+							latency 20%.
+						</p>
+					</template>
+					<template #activity>
+						<p class="text-sm text-gray-600 dark:text-gray-300">
+							Shipped billing retries; fixed avatar upload timeout.
+						</p>
+					</template>
+					<template #members>
+						<p class="text-sm text-gray-600 dark:text-gray-300">
+							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-gray-500">
+						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-gray-600 dark:text-gray-300">
+					Email digests and mention alerts for alex@northwind.io.
+				</p>
+			</template>
+		</BbTabs>
+		<p class="text-xs text-gray-500" 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 and a matching query on
+back/forward re-selects the tab.
+
+**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 each trigger renders as an Inertia link. 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.
+
+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 throws.** With no `modelValue` and no valid first tab the
+  group has nothing to select — always leave at least one enabled tab.
+
+### 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` |  |  | Displays the component as full width. |
+| `compact` | `boolean \| undefined` |  |  | 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` |  |  | Disables the horizontal slide transition between tab panels (enabled by default). |
+| `disableAnimateY` | `boolean \| undefined` |  |  | Disables the smooth height animation when switching between tab panels (enabled by default). |
+| `disabled` | `boolean \| undefined` |  |  | Disables the component |
+| `eager` | `boolean \| undefined` |  |  | 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` |  |  | 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` |  |  | Uses history replacement instead of push navigation. Prefer `replace` whenever `navigation` is on: the URL still carries the active tab (deep-linkable, survives reload), but switching tabs does not stack a history entry per click, so Back l… |
+| `server` | `boolean \| undefined` |  |  | 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.