bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/guides/options-items-playbook.md

@@ -0,0 +1,222 @@
+---
+title: Options and Items Playbook
+summary: How item-driven components turn raw domain items into options — mapping, value identity, model seeding, and the supported ways to disable choices.
+---
+
+# 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`.
+- `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.

package/dist/ai/guides/page-shell.md

@@ -0,0 +1,314 @@
+---
+title: Page Shell
+summary: 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), with a mobile drawer fallback.
+---
+
+# 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
+[recipes](../recipes/inertia/crud-listing-page.md) assume a shell like this
+exists; they work without it too.
+
+## The context
+
+State first: the shell's sidebar is a **navigation stack**. `current` is
+the record being peeked; pushing opens the sidebar, popping goes back one
+level, and closing always clears the whole stack (a closed sidebar never
+hides stale history). First caller creates the context, later callers join
+it — provide it from the shell, read it from anywhere on the page.
+
+```ts
+// src/components/layout/usePageShellContext.ts
+import { injectLocal, provideLocal } from '@vueuse/core';
+import {
+	computed,
+	ref,
+	watch,
+	type ComputedRef,
+	type InjectionKey,
+	type Ref,
+} from 'vue';
+
+export type PageShellContext<T> = {
+	/** Whether the sidebar panel is currently visible. */
+	sidebarOpen: Ref<boolean>;
+	/** Full navigation stack. */
+	stack: Ref<T[]>;
+	/** Top of the stack, or `null` when the stack is empty. */
+	current: ComputedRef<T | null>;
+	/** Push an item; opens the sidebar. `replace` clears the stack first. */
+	push: (item: T, replace?: boolean) => void;
+	/** Remove the top item; closes the sidebar when the stack empties. */
+	pop: () => void;
+	/** Close the sidebar and clear the stack. */
+	close: () => void;
+};
+
+const key: InjectionKey<PageShellContext<unknown>> = Symbol('page-shell');
+
+export function usePageShellContext<T>(): PageShellContext<T> {
+	const existing = injectLocal(key, undefined);
+	if (existing) return existing as PageShellContext<T>;
+
+	const sidebarOpen = ref(false);
+	const stack = ref<T[]>([]) as Ref<T[]>;
+	const current = computed<T | null>(
+		() => stack.value[stack.value.length - 1] ?? null
+	);
+
+	const push = (item: T, replace = false): void => {
+		stack.value = [...(replace ? [] : stack.value), item];
+	};
+	const pop = (): void => {
+		stack.value = stack.value.slice(0, -1);
+	};
+	const close = (): void => {
+		sidebarOpen.value = false;
+	};
+
+	// Two-way coupling: the boolean and the stack stay coherent whichever
+	// side drives — closing clears history, pushing opens the panel.
+	watch(sidebarOpen, (open) => {
+		if (!open) stack.value = [];
+	});
+	watch(stack, (items) => {
+		sidebarOpen.value = items.length > 0;
+	});
+
+	const context: PageShellContext<T> = {
+		sidebarOpen,
+		stack,
+		current,
+		push,
+		pop,
+		close,
+	};
+	provideLocal(key, context as PageShellContext<unknown>);
+	return context;
+}
+```
+
+## The component
+
+Desktop: the sidebar overlays from the right and the content smoothly
+reserves its width (padding transition). Mobile: it becomes a full-height
+drawer over a dimmed backdrop. All colors and radii come from `--bb-*`
+tokens.
+
+```vue
+<!-- src/components/layout/PageShell.vue -->
+<template>
+	<div class="page-shell" :class="{ 'page-shell--sidebar': sidebarOpen }">
+		<header class="page-shell__topbar">
+			<slot name="topbar" />
+		</header>
+
+		<div class="page-shell__body">
+			<main class="page-shell__content">
+				<slot />
+			</main>
+
+			<aside
+				aria-label="Details"
+				class="page-shell__sidebar"
+				role="complementary"
+			>
+				<div class="page-shell__sidebar-actions">
+					<BbButton
+						v-if="stack.length > 1"
+						aria-label="Back"
+						icon="lucide:arrow-left"
+						size="sm"
+						variant="ghost"
+						@click="pop"
+					/>
+					<BbButton
+						aria-label="Close panel"
+						icon="lucide:x"
+						size="sm"
+						variant="ghost"
+						@click="close"
+					/>
+				</div>
+				<div class="page-shell__sidebar-body">
+					<slot name="sidebar" />
+				</div>
+			</aside>
+
+			<div class="page-shell__overlay" @click="close" />
+		</div>
+
+		<slot name="dialogs" />
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbButton } from 'bitboss-ui';
+import { usePageShellContext } from './usePageShellContext';
+
+const { sidebarOpen, stack, pop, close } = usePageShellContext();
+</script>
+
+<style scoped>
+.page-shell {
+	--page-shell-sidebar-w: 360px;
+	--page-shell-duration: 300ms;
+
+	display: flex;
+	flex-direction: column;
+	min-height: 100%;
+	position: relative;
+}
+
+.page-shell__body {
+	flex: 1 1 auto;
+	min-width: 0;
+	position: relative;
+}
+
+.page-shell__content {
+	min-width: 0;
+	transition: padding-right var(--page-shell-duration);
+}
+
+/* Sidebar: hidden off-screen right; desktop overlays the body, mobile is a
+   fixed drawer above a backdrop. */
+.page-shell__sidebar {
+	background: var(--bb-panel);
+	border-left: 1px solid var(--bb-border);
+	display: flex;
+	flex-direction: column;
+	inset: 0 0 0 auto;
+	position: fixed;
+	transform: translateX(100%);
+	transition: transform var(--page-shell-duration);
+	width: min(100%, var(--page-shell-sidebar-w));
+	z-index: 40;
+}
+
+.page-shell__sidebar-actions {
+	display: flex;
+	gap: 4px;
+	justify-content: flex-end;
+	padding: 8px;
+}
+
+.page-shell__sidebar-body {
+	flex: 1 1 auto;
+	min-height: 0;
+	overflow-y: auto;
+	overscroll-behavior-y: contain;
+	padding: 0 16px 16px;
+}
+
+.page-shell__overlay {
+	background: rgb(0 0 0 / 0.5);
+	inset: 0;
+	opacity: 0;
+	pointer-events: none;
+	position: fixed;
+	transition: opacity var(--page-shell-duration);
+	z-index: 39;
+}
+
+.page-shell--sidebar .page-shell__sidebar {
+	transform: translateX(0);
+}
+
+@media (width >= 48rem) {
+	/* Desktop: anchor the sidebar to the shell, reserve its width. */
+	.page-shell__sidebar {
+		position: absolute;
+		z-index: 10;
+	}
+
+	.page-shell--sidebar .page-shell__content {
+		padding-right: var(--page-shell-sidebar-w);
+	}
+
+	.page-shell__overlay {
+		display: none;
+	}
+}
+
+@media (width < 48rem) {
+	.page-shell--sidebar .page-shell__overlay {
+		opacity: 1;
+		pointer-events: auto;
+	}
+}
+</style>
+```
+
+## 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>
+```
+
+Deeper components don't need props or events for this — `InvoicePeek` can
+call `usePageShellContext<Invoice>()` itself and `push()` a related record
+(drill-down: the Back button appears automatically once the stack has two
+entries).
+
+## 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).
+  - **Focus trap on mobile**: trap Tab inside the open drawer and close on
+    Escape (`useFocusTrap` from `@vueuse/integrations`).
+  - **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: CRUD Listing Page (Inertia)](../recipes/inertia/crud-listing-page.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.