bitboss-ui 2.1.134 → 3.0.0-alpha.1

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

@@ -0,0 +1,295 @@
+---
+title: App Layout
+summary: App-side chrome around every page — collapsible left nav sidebar and a fat footer, with the CSS hooks (layout--sidebar-expanded, --sidebar-max-w) that the floating bottom panel offsets against.
+---
+
+# 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/`).
+
+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.
+
+The [Floating Bottom Panel](./floating-bottom-panel.md) reads both to stay
+centered over the _visible_ content instead of the viewport.
+
+## The component
+
+```vue
+<!-- src/components/layout/AppLayout.vue -->
+<template>
+	<div class="layout" :class="{ 'layout--sidebar-expanded': expanded }">
+		<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="16" />
+					<span v-if="expanded">{{ item.label }}</span>
+				</BbBaseButton>
+			</nav>
+		</aside>
+
+		<div class="layout__main">
+			<main class="layout__page">
+				<!-- 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;
+}
+
+/* ── 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
+  `active-class`, which resolves active state on every platform. Never
+  `@click` + router.
+- **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 CSS hooks are a contract.** `.layout--sidebar-expanded` and
+  `--sidebar-max-w` are read by the
+  [Floating Bottom Panel](./floating-bottom-panel.md)'s sidebar-aware
+  centering; rename them in one place only.
+- 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) — offsets against
+  this layout's hooks.
+- [Recipes](../recipes/vue/records-workspace.md) — every recipe page
+  assumes this chrome exists.

package/dist/ai/guides/coherence-playbook.md

@@ -0,0 +1,136 @@
+---
+title: Coherence Playbook
+summary: Declarative coherence for tied inputs — enforce-coherence, dependencies and debounce props instead of manual watchers, with per-component availability.
+---
+
+# 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                                          | **no** — the table refetches but never prunes the selection; reconcile `v-model` yourself if rows can disappear |
+
+## 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` is the exception where reconciliation is yours: with `dependencies`-driven refetches and a selection model, drop selected ids that left the result set after each fetch.
+
+## 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.
+- Expecting `BbTable` to prune its selection — it doesn't; that reconciliation is application code.
+
+## Validation checklist
+
+- [ ] `enforce-coherence` enabled wherever stale selections are possible (selects, groups, dropdown groups).
+- [ ] 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.
+- [ ] Table selections are reconciled in app code after dependency-driven refetches.

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

@@ -0,0 +1,195 @@
+---
+title: Component Picker
+summary: Decision guide for choosing the right component for common UI needs.
+---
+
+# 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.
+
+---
+
+## 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) |
+| 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                      |
+| ---------------------------------------- | ------------------------------ |
+| Boolean answer in a form (agree, opt in) | [BbCheckbox](../BbCheckbox.md) |
+| Setting with instant effect              | [BbSwitch](../BbSwitch.md)     |
+| One option interleaved with other markup | [BbRadio](../BbRadio.md)       |
+
+**BbCheckbox vs BbSwitch:** a switch promises _something happens now_ (dark mode, notifications); a checkbox promises _this will be saved with the form_. If nothing happens until a Save button, it is a checkbox. 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.
+- `BbBaseButton` — any clickable/navigable surface that is _not_ a variant button: a whole card or list row that links somewhere, 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. Prefer it over hand-rolling `@click="router.push(...)"` on a `<div>`/`<a>`.
+- `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).
+
+**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)     |
+| 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.
+
+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) |
+
+---
+
+## 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)