bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/recipes/nuxt/records-workspace.md

@@ -0,0 +1,1314 @@
+---
+title: Records Workspace (Nuxt)
+summary: Full-anatomy invoices workspace for Nuxt — breadcrumbs + page search, pill filter rail, href tabs with counts, one-click status cells, bulk bottom panel, and a stacked peek sidebar, filters URL-synced and data fetched with useAsyncData, all through one coopting page context.
+---
+
+# Recipe: Records Workspace (Nuxt)
+
+The flagship advanced-page recipe adapted for **Nuxt**: the same Stripe-
+invoices × Linear list workspace — app chrome, breadcrumbs + page search,
+pill filter rail, href tabs with live counts, a dense server-paged table, a
+floating bulk-action bar, and a stacked peek sidebar — but filters and the
+active tab live in the URL and the list loads through `useAsyncData`
+watching `route.query`. Anatomy, components, the context shape, copy and
+data are identical to the Vue recipe; only the data/URL/mutation layer
+changes.
+
+Sibling recipes: [Vue](../vue/records-workspace.md) ·
+[Inertia](../inertia/records-workspace.md).
+
+## Prerequisites
+
+- `<BbConfirm />` and `<BbToast />` mounted once in `app.vue`.
+- [App Layout](../../guides/app-layout.md), [Page Shell](../../guides/page-shell.md)
+  and [Floating Bottom Panel](../../guides/floating-bottom-panel.md) copied
+  into `src/components/layout/` per their guides — every recipe page assumes
+  this chrome exists and renders inside it.
+- Server routes: `GET /api/invoices` (accepts `search`, `status[]`,
+  `customerId`, `dueBetween[]`, `tab`, `page`, `perPage`, returns
+  `{ data, total, tabCounts }`), plus the mutation routes referenced below
+  (`PATCH /api/invoices/:id`, `POST /api/invoices/:id/duplicate`, …).
+
+## Key ideas
+
+- **One coopting page context.** `provideInvoicesWorkspace()` joins the
+  page-shell stack and the table context once, owns filters/tab/dialogs,
+  and exposes complete actions. Every leaf calls `useInvoicesWorkspace()`
+  and nothing else — zero prop drilling anywhere on the page.
+- **Filters and tab live in the URL, not in local refs.** They are seeded
+  from `route.query` at setup and every change writes back through
+  `navigateTo` — the page is bookmarkable and survives reload.
+- **`useAsyncData` watches `route.query`.** That single watch source is
+  the whole refetch trigger — filters, tab and page changes all funnel
+  through the URL first, so there is exactly one fetch path.
+- **The table keeps its selection/paging context.** `useBbTableContext`
+  still owns `page`/`perPage`/`selected`/`total` by id — only the _items_
+  become a resolved array (`:items` + `:loading`) instead of an items
+  function, since the page now owns the fetch.
+- **Clicking the name of a thing peeks it.** Invoice number → invoice peek
+  (fresh stack); customer name — in a row or inside a peek — → customer
+  peek **stacked** with a back arrow. Peeks are workbenches: status
+  control, properties, line items, activity, payments.
+- **Filters are compact pills** (`BbSelectPopover` triggers + a range date
+  input) with a clear-all that renders only while something is active.
+- **Buttons are `md` by default** (28px, flush beside `compact` inputs);
+  `sm` only in the table rows, the peeks' headers and the bottom bar.
+  Internal navigation (`New invoice`, row `Edit`, peek `Open…` links) uses
+  `to`, Nuxt's Vue Router prop, instead of a raw `href`.
+
+## Page anatomy
+
+```
+InvoicesWorkspace/
+	Index.vue               ← assembly: PageShell slots, table, tabs, pagination
+	context.ts               ← coopting page context (shell + table + URL filters + actions)
+	FilterRail.vue           ← pill filters + clear-all
+	StatusCell.vue           ← one-click status change (badge → BbSelectPopover)
+	RowActions.vue           ← per-row "…" dropdown
+	SelectionBar.vue         ← bulk actions in the floating bottom panel
+	InvoicePeek.vue          ← sidebar workbench, stack level 1
+	CustomerPeek.vue         ← stacked peek, back arrow via the shell
+	RecordPaymentDialog.vue  ← page-level dialog, driven by the context
+```
+
+Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
+(left nav + fat footer), [Page Shell](../../guides/page-shell.md),
+[Floating Bottom Panel](../../guides/floating-bottom-panel.md).
+
+## Action inventory
+
+| #   | Action                         | Trigger                          | Mechanism                                             |
+| --- | ------------------------------ | -------------------------------- | ----------------------------------------------------- |
+| 1   | New invoice                    | topbar, the page's one `primary` | navigation (`to="/invoices/create"`)                  |
+| 2   | Page search                    | topbar right                     | `filters.search` → URL → `useAsyncData` refetch       |
+| 3   | Filter status / customer / due | filter rail pills                | `BbSelectPopover` multiple / query-aware / date range |
+| 4   | Clear filters                  | rail right (only when active)    | context `clearFilters()`                              |
+| 5   | Switch tab                     | href tabs with counts            | URL + `useAsyncData` refetch                          |
+| 6   | Peek invoice                   | invoice number cell / peek lists | `peekInvoice(id)` → shell stack                       |
+| 7   | Peek customer (stacked)        | customer cell / inside peeks     | `stackCustomer(id)` → back arrow                      |
+| 8   | Change status inline           | status badge in row & peek       | one-click `BbSelectPopover`                           |
+| 9   | Record payment                 | row `…`, peek button             | `BbDialog` via `ctx.dialogs`                          |
+| 10  | Edit / duplicate               | row `…` dropdown                 | navigation (`to`) / context action                    |
+| 11  | Archive / delete               | row `…`, bulk bar                | destructive behind `useConfirm`                       |
+| 12  | Bulk mark paid / remind        | floating bottom panel            | context actions on `table.selected`                   |
+| 13  | Select rows / select all       | table checkboxes                 | table context                                         |
+| 14  | Open full invoice              | peek footer                      | navigation (`to="/invoices/:id"`)                     |
+| 15  | Back / close peek              | shell chrome                     | shell stack pop / close                               |
+
+## The code
+
+### context.ts
+
+```ts
+// InvoicesWorkspace/context.ts
+import {
+	computed,
+	inject,
+	provide,
+	reactive,
+	ref,
+	watch,
+	type ComputedRef,
+	type InjectionKey,
+	type Ref,
+} from 'vue';
+import {
+	useBbTableContext,
+	useConfirm,
+	useToast,
+	type BbTableContext,
+} from 'bitboss-ui';
+import {
+	usePageShellContext,
+	type PageShellContext,
+} from '@/components/layout/usePageShellContext';
+import { watchDebounced } from '@vueuse/core';
+import type { Invoice, InvoiceStatus, PaymentDraft } from '@/types';
+
+/** What the stacked sidebar can show. Clicking a name pushes one of these. */
+export type PeekItem =
+	| { type: 'invoice'; id: number }
+	| { type: 'customer'; id: number };
+
+export type WorkspaceTab = 'all' | 'outstanding' | 'paid' | 'archived';
+
+export interface InvoiceFilters {
+	search: string;
+	status: InvoiceStatus[];
+	customerId: number | null;
+	/**
+	 * `[start, end]` ISO strings, or `[]` when unset. Range mode requires an
+	 * array modelValue -- binding `null` throws, so the empty filter is `[]`.
+	 */
+	dueBetween: string[];
+}
+
+type InvoiceListResponse = {
+	data: Invoice[];
+	total: number;
+	tabCounts: Record<WorkspaceTab, number>;
+};
+
+export interface InvoicesWorkspaceContext {
+	// -- Coopted contexts ------------------------------------------------------
+	shell: PageShellContext<PeekItem>;
+	table: BbTableContext;
+	// -- Page-owned state ------------------------------------------------------
+	filters: InvoiceFilters;
+	hasActiveFilters: ComputedRef<boolean>;
+	tab: Ref<WorkspaceTab>;
+	tabCounts: ComputedRef<Record<WorkspaceTab, number>>;
+	dialogs: { recordPayment: Ref<Invoice | null> };
+	// -- Data (server-rendered, URL-driven) -------------------------------------
+	invoices: ComputedRef<Invoice[]>;
+	invoicesPending: Ref<boolean>;
+	// -- Peek grammar ----------------------------------------------------------
+	peekInvoice: (id: number) => void;
+	stackInvoice: (id: number) => void;
+	stackCustomer: (id: number) => void;
+	// -- Actions (complete: API + refresh + toast) ------------------------------
+	clearFilters: () => void;
+	updateStatus: (invoice: Invoice, status: InvoiceStatus) => Promise<void>;
+	duplicateInvoice: (invoice: Invoice) => Promise<void>;
+	recordPayment: (invoice: Invoice, draft: PaymentDraft) => Promise<void>;
+	archiveInvoice: (invoice: Invoice) => Promise<void>;
+	deleteInvoice: (invoice: Invoice) => Promise<void>;
+	bulkMarkPaid: () => Promise<void>;
+	bulkRemind: () => Promise<void>;
+	bulkArchive: () => Promise<void>;
+}
+
+const key: InjectionKey<InvoicesWorkspaceContext> =
+	Symbol('invoices-workspace');
+
+/** Comma-joined query value → string[] (or null when absent). */
+const toArray = (value: unknown): string[] | null => {
+	if (value == null || value === '') return null;
+	return Array.isArray(value) ? value.map(String) : String(value).split(',');
+};
+
+export function provideInvoicesWorkspace(): InvoicesWorkspaceContext {
+	const { toast } = useToast();
+	const { confirm } = useConfirm();
+	const route = useRoute();
+
+	// -- Coopt the specific contexts: once, here, for the whole page. ----------
+	const shell = usePageShellContext<PeekItem>();
+	const table = useBbTableContext('invoices-table', { perPage: 25 });
+
+	// -- Filters + tab: seeded from the URL, the single source of truth. -------
+	const filters = reactive<InvoiceFilters>({
+		search: (route.query.search as string) ?? '',
+		status: (toArray(route.query.status) ?? []) as InvoiceStatus[],
+		customerId: route.query.customerId ? Number(route.query.customerId) : null,
+		dueBetween: toArray(route.query.dueBetween) ?? [],
+	});
+	const tab = ref<WorkspaceTab>((route.query.tab as WorkspaceTab) ?? 'all');
+
+	const hasActiveFilters = computed(
+		() =>
+			filters.search !== '' ||
+			filters.status.length > 0 ||
+			filters.customerId !== null ||
+			filters.dueBetween.length > 0
+	);
+
+	const clearFilters = () => {
+		filters.search = '';
+		filters.status = [];
+		filters.customerId = null;
+		filters.dueBetween = [];
+	};
+
+	// Every filter/tab change mirrors into the query string; `useAsyncData`
+	// below watches `route.query`, so this is the whole refetch trigger.
+	const syncQuery = () =>
+		navigateTo({
+			query: {
+				search: filters.search || undefined,
+				status: filters.status.length ? filters.status.join(',') : undefined,
+				customerId: filters.customerId ?? undefined,
+				dueBetween: filters.dueBetween.length
+					? filters.dueBetween.join(',')
+					: undefined,
+				tab: tab.value,
+			},
+		});
+	watchDebounced(filters, syncQuery, { deep: true, debounce: 300 });
+	watch(tab, () => {
+		table.page.value = 1;
+		syncQuery();
+	});
+
+	// -- Data ---------------------------------------------------------------------
+	const { data, pending, refresh } = useAsyncData<InvoiceListResponse>(
+		'invoices',
+		() =>
+			$fetch<InvoiceListResponse>('/api/invoices', {
+				query: {
+					search: filters.search || undefined,
+					status: filters.status,
+					customerId: filters.customerId ?? undefined,
+					dueBetween: filters.dueBetween.length
+						? filters.dueBetween
+						: undefined,
+					tab: tab.value,
+					page: table.page.value,
+					perPage: table.perPage.value,
+				},
+			}),
+		{ watch: [() => route.query, table.page] }
+	);
+	const invoices = computed(() => data.value?.data ?? []);
+	const invoicesPending = pending;
+	const tabCounts = computed(
+		() =>
+			data.value?.tabCounts ?? {
+				all: 0,
+				outstanding: 0,
+				paid: 0,
+				archived: 0,
+			}
+	);
+	watch(
+		data,
+		(response) => {
+			if (response) table.total.value = response.total;
+		},
+		{ immediate: true }
+	);
+
+	const dialogs = { recordPayment: ref<Invoice | null>(null) };
+
+	// -- Peek grammar ----------------------------------------------------------------
+	// peekX opens a fresh stack (from the list); stackX drills down (from a peek).
+	const peekInvoice = (id: number) => shell.push({ type: 'invoice', id }, true);
+	const stackInvoice = (id: number) => shell.push({ type: 'invoice', id });
+	const stackCustomer = (id: number) => shell.push({ type: 'customer', id });
+
+	// -- Actions --------------------------------------------------------------------
+	const updateStatus = async (invoice: Invoice, status: InvoiceStatus) => {
+		await $fetch(`/api/invoices/${invoice.id}`, {
+			method: 'PATCH',
+			body: { status },
+		});
+		await refresh();
+		toast({
+			title: `${invoice.number} moved to ${status}.`,
+			variant: 'success',
+		});
+	};
+
+	const duplicateInvoice = async (invoice: Invoice) => {
+		const copy = await $fetch<Invoice>(
+			`/api/invoices/${invoice.id}/duplicate`,
+			{
+				method: 'POST',
+			}
+		);
+		await refresh();
+		toast({ title: `Duplicated as ${copy.number}.`, variant: 'success' });
+	};
+
+	const recordPayment = async (invoice: Invoice, draft: PaymentDraft) => {
+		await $fetch(`/api/invoices/${invoice.id}/payments`, {
+			method: 'POST',
+			body: draft,
+		});
+		dialogs.recordPayment.value = null;
+		await refresh();
+		toast({
+			title: `Payment recorded on ${invoice.number}.`,
+			variant: 'success',
+		});
+	};
+
+	const archiveInvoice = async (invoice: Invoice) => {
+		await $fetch(`/api/invoices/${invoice.id}/archive`, { method: 'PATCH' });
+		await refresh();
+		toast({ title: `${invoice.number} archived.`, variant: 'success' });
+	};
+
+	const deleteInvoice = async (invoice: Invoice) => {
+		const ok = await confirm({
+			variant: 'destructive',
+			title: 'Delete invoice',
+			text: `Delete ${invoice.number}? This cannot be undone.`,
+			yes: 'Delete',
+			no: 'Cancel',
+		});
+		if (!ok) return;
+		await $fetch(`/api/invoices/${invoice.id}`, { method: 'DELETE' });
+		await refresh();
+		toast({ title: `${invoice.number} deleted.`, variant: 'success' });
+	};
+
+	// Bulk actions read and clear the coopted table context themselves.
+	const bulkIds = (): number[] => table.selected.value;
+	const clearSelection = () => {
+		table.selected.value = [];
+	};
+
+	const bulkMarkPaid = async () => {
+		const ids = bulkIds();
+		await $fetch('/api/invoices/bulk/mark-paid', {
+			method: 'PATCH',
+			body: { ids },
+		});
+		clearSelection();
+		await refresh();
+		toast({
+			title: `${ids.length} invoices marked as paid.`,
+			variant: 'success',
+		});
+	};
+
+	const bulkRemind = async () => {
+		const ids = bulkIds();
+		await $fetch('/api/invoices/bulk/remind', {
+			method: 'POST',
+			body: { ids },
+		});
+		clearSelection();
+		toast({
+			title: `Reminder sent for ${ids.length} invoices.`,
+			variant: 'success',
+		});
+	};
+
+	const bulkArchive = async () => {
+		const ids = bulkIds();
+		const ok = await confirm({
+			variant: 'destructive',
+			title: 'Archive invoices',
+			text: `Archive ${ids.length} invoices? They move out of every tab except Archived.`,
+			yes: 'Archive',
+			no: 'Cancel',
+		});
+		if (!ok) return;
+		await $fetch('/api/invoices/bulk/archive', {
+			method: 'PATCH',
+			body: { ids },
+		});
+		clearSelection();
+		await refresh();
+		toast({ title: `${ids.length} invoices archived.`, variant: 'success' });
+	};
+
+	const ctx: InvoicesWorkspaceContext = {
+		shell,
+		table,
+		filters,
+		hasActiveFilters,
+		tab,
+		tabCounts,
+		dialogs,
+		invoices,
+		invoicesPending,
+		peekInvoice,
+		stackInvoice,
+		stackCustomer,
+		clearFilters,
+		updateStatus,
+		duplicateInvoice,
+		recordPayment,
+		archiveInvoice,
+		deleteInvoice,
+		bulkMarkPaid,
+		bulkRemind,
+		bulkArchive,
+	};
+	provide(key, ctx);
+	return ctx;
+}
+
+export function useInvoicesWorkspace(): InvoicesWorkspaceContext {
+	const ctx = inject(key);
+	if (!ctx)
+		throw new Error('useInvoicesWorkspace() called outside InvoicesWorkspace');
+	return ctx;
+}
+```
+
+### Index.vue — the assembly
+
+```vue
+<!-- InvoicesWorkspace/Index.vue -->
+<template>
+	<PageShell>
+		<!-- Topbar: breadcrumbs left, page search + primary action right. -->
+		<template #topbar>
+			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
+				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
+				     without it their overflow recompute fights the flex layout every frame. -->
+				<BbBreadcrumbs
+					class="min-w-0 flex-auto"
+					:items="[
+						{ key: 'dashboard', text: 'Dashboard', to: '/dashboard' },
+						{ key: 'billing', text: 'Billing', to: '/billing' },
+						{ key: 'invoices', text: 'Invoices' },
+					]"
+				/>
+				<div class="flex shrink-0 items-center gap-2">
+					<BbTextInput
+						v-model="ctx.filters.search"
+						hide-label
+						label="Search invoices"
+						clearable
+						compact
+						placeholder="Search number or customer…"
+						prepend:icon="lucide:search"
+					/>
+					<BbButton
+						prepend:icon="lucide:plus"
+						to="/invoices/create"
+						variant="primary"
+					>
+						New invoice
+					</BbButton>
+				</div>
+			</div>
+		</template>
+
+		<div class="flex flex-col gap-3 p-4">
+			<FilterRail />
+
+			<!-- Tabs as URL filters: href updates the query, the key feeds the
+			     fetch. Counts come from the server on every fetch. -->
+			<BbTabs
+				v-model="ctx.tab.value"
+				compact
+				:items="[
+					{
+						key: 'all',
+						label: `All · ${ctx.tabCounts.value.all}`,
+						href: '?tab=all',
+					},
+					{
+						key: 'outstanding',
+						label: `Outstanding · ${ctx.tabCounts.value.outstanding}`,
+						href: '?tab=outstanding',
+					},
+					{
+						key: 'paid',
+						label: `Paid · ${ctx.tabCounts.value.paid}`,
+						href: '?tab=paid',
+					},
+					{
+						key: 'archived',
+						label: `Archived · ${ctx.tabCounts.value.archived}`,
+						href: '?tab=archived',
+					},
+				]"
+			/>
+
+			<BbTable
+				id="invoices-table"
+				actions
+				caption="Invoices"
+				:columns="columns"
+				compact
+				item-value="id"
+				:items="ctx.invoices.value"
+				:loading="ctx.invoicesPending.value"
+				loading-text="Loading invoices…"
+				:row-class="rowClass"
+				selectable
+			>
+				<!-- Clicking the NAME of a thing peeks it. -->
+				<template #number="{ item, content }">
+					<BbButton
+						size="sm"
+						variant="link"
+						@click="() => ctx.peekInvoice(item.id)"
+					>
+						{{ content }}
+					</BbButton>
+				</template>
+
+				<template #customer_name="{ item, content }">
+					<BbButton
+						size="sm"
+						variant="ghost"
+						@click="() => ctx.stackCustomer(item.customer.id)"
+					>
+						{{ content }}
+					</BbButton>
+				</template>
+
+				<template #status="{ item }">
+					<StatusCell :invoice="item" />
+				</template>
+
+				<template #actions="{ item }">
+					<RowActions :invoice="item" />
+				</template>
+
+				<template #no-data>
+					<div class="flex flex-col items-center gap-2 p-6 text-center">
+						<p class="text-sm text-gray-500">
+							No invoices match
+							{{
+								ctx.hasActiveFilters.value ? 'the current filters' : 'this tab'
+							}}.
+						</p>
+						<BbButton
+							v-if="ctx.hasActiveFilters.value"
+							variant="ghost"
+							@click="ctx.clearFilters"
+						>
+							Clear filters
+						</BbButton>
+					</div>
+				</template>
+			</BbTable>
+
+			<!-- Joins the table context by id: no page/totalPages wiring at all. -->
+			<BbPagination table-id="invoices-table" />
+		</div>
+
+		<SelectionBar />
+
+		<!-- Stacked peek sidebar: the shell owns back/close; we render by type. -->
+		<template #sidebar>
+			<InvoicePeek
+				v-if="ctx.shell.current.value?.type === 'invoice'"
+				:invoice-id="ctx.shell.current.value.id"
+			/>
+			<CustomerPeek
+				v-else-if="ctx.shell.current.value?.type === 'customer'"
+				:customer-id="ctx.shell.current.value.id"
+			/>
+		</template>
+
+		<template #dialogs>
+			<RecordPaymentDialog />
+		</template>
+	</PageShell>
+</template>
+
+<script setup lang="ts">
+import {
+	BbBreadcrumbs,
+	BbButton,
+	BbPagination,
+	BbTable,
+	BbTabs,
+	BbTextInput,
+} from 'bitboss-ui';
+import PageShell from '@/components/layout/PageShell.vue';
+import { provideInvoicesWorkspace } from './context';
+import CustomerPeek from './CustomerPeek.vue';
+import FilterRail from './FilterRail.vue';
+import InvoicePeek from './InvoicePeek.vue';
+import RecordPaymentDialog from './RecordPaymentDialog.vue';
+import RowActions from './RowActions.vue';
+import SelectionBar from './SelectionBar.vue';
+import StatusCell from './StatusCell.vue';
+import type { Invoice } from '@/types';
+
+const ctx = provideInvoicesWorkspace();
+
+const currency = new Intl.NumberFormat('en-US', {
+	style: 'currency',
+	currency: 'USD',
+});
+const shortDate = (value: string) =>
+	new Date(value).toLocaleDateString('en-US', {
+		month: 'short',
+		day: 'numeric',
+	});
+
+const columns = [
+	{ key: 'number', label: 'Invoice' },
+	{ key: 'customer.name', label: 'Customer' },
+	{
+		key: 'amount',
+		label: 'Amount',
+		formatter: (value: number) => currency.format(value),
+	},
+	{ key: 'status', label: 'Status' },
+	{ key: 'dueDate', label: 'Due', formatter: shortDate },
+	{ key: 'issuedAt', label: 'Issued', formatter: shortDate },
+];
+
+// Overdue rows get a tinted background — public row-class API, no internals.
+const rowClass = (item: Invoice) =>
+	item.status === 'overdue' ? 'bg-red-50 dark:bg-red-950/20' : undefined;
+</script>
+```
+
+### FilterRail.vue
+
+```vue
+<!-- InvoicesWorkspace/FilterRail.vue -->
+<template>
+	<div class="flex flex-wrap items-center gap-2">
+		<!-- Status: multi-select pill. -->
+		<BbSelectPopover
+			v-model="ctx.filters.status"
+			:items="['draft', 'pending', 'paid', 'overdue']"
+			multiple
+		>
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					append:icon="lucide:chevron-down"
+					size="sm"
+					variant="outline"
+				>
+					Status{{
+						ctx.filters.status.length ? ` · ${ctx.filters.status.length}` : ''
+					}}
+				</BbButton>
+			</template>
+		</BbSelectPopover>
+
+		<!-- Customer: single, query-aware search against the API. -->
+		<BbSelectPopover
+			v-model="ctx.filters.customerId"
+			item-text="name"
+			item-value="id"
+			:items="searchCustomers"
+		>
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					append:icon="lucide:chevron-down"
+					size="sm"
+					variant="outline"
+				>
+					{{ customerLabel }}
+				</BbButton>
+			</template>
+		</BbSelectPopover>
+
+		<!-- Due date range: a compact input is 28px — flush with the sm pills' row. -->
+		<BbDatePickerInput
+			v-model="ctx.filters.dueBetween"
+			hide-label
+			label="Due date range"
+			clearable
+			compact
+			placeholder="Due between…"
+			range
+		/>
+
+		<!-- Clear-all renders only while something is active. -->
+		<BbButton
+			v-if="ctx.hasActiveFilters.value"
+			class="ml-auto"
+			prepend:icon="lucide:x"
+			size="sm"
+			variant="ghost"
+			@click="ctx.clearFilters"
+		>
+			Clear filters
+		</BbButton>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref, watchEffect } from 'vue';
+import { BbButton, BbDatePickerInput, BbSelectPopover } from 'bitboss-ui';
+import { useInvoicesWorkspace } from './context';
+import type { Customer } from '@/types';
+
+const ctx = useInvoicesWorkspace();
+
+// Query-aware items function: BbSelectPopover calls it with the search text.
+const searchCustomers = (query: string): Promise<Customer[]> =>
+	$fetch<Customer[]>('/api/customers', { query: { search: query } });
+
+// The trigger labels itself from page state (the popover is lazy by design
+// and cannot know the selected label before its first open).
+const selectedCustomer = ref<Customer | null>(null);
+watchEffect(async () => {
+	selectedCustomer.value =
+		ctx.filters.customerId == null
+			? null
+			: await $fetch<Customer>(`/api/customers/${ctx.filters.customerId}`);
+});
+const customerLabel = computed(
+	() => selectedCustomer.value?.name ?? 'Customer'
+);
+</script>
+```
+
+### StatusCell.vue
+
+```vue
+<!-- InvoicesWorkspace/StatusCell.vue -->
+<template>
+	<BbSelectPopover
+		:items="['draft', 'pending', 'paid', 'overdue']"
+		:model-value="invoice.status"
+		@update:model-value="(status) => pick(status as InvoiceStatus)"
+	>
+		<template #activator="{ props: activatorProps }">
+			<!-- The badge IS the trigger: BbBadgeButton turns the badge's own
+			body into the button, so the pill is the hit target and draws its
+			own focus ring — no wrapper element, no chrome class. The internal
+			trailing chevron says "clickable"; while the save runs the badge's
+			`loading` swaps the spinner into the chevron's place (§6.1
+			niceties). -->
+			<BbBadge
+				append:icon="lucide:chevron-down"
+				:loading="saving"
+				variant="outline"
+			>
+				<BbBadgeButton v-bind="activatorProps">{{
+					invoice.status
+				}}</BbBadgeButton>
+			</BbBadge>
+		</template>
+	</BbSelectPopover>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
+import { useInvoicesWorkspace } from './context';
+import type { Invoice, InvoiceStatus } from '@/types';
+
+const props = defineProps<{ invoice: Invoice }>();
+
+const ctx = useInvoicesWorkspace();
+
+// In-flight flag for the save feedback — rung-1 local state, not context.
+const saving = ref(false);
+const pick = async (status: InvoiceStatus) => {
+	saving.value = true;
+	try {
+		await ctx.updateStatus(props.invoice, status);
+	} finally {
+		saving.value = false;
+	}
+};
+</script>
+```
+
+### RowActions.vue
+
+```vue
+<!-- InvoicesWorkspace/RowActions.vue -->
+<template>
+	<BbDropdown
+		:items="[
+			{
+				key: 'edit',
+				text: 'Edit',
+				'prepend:icon': 'lucide:pencil',
+				to: `/invoices/${invoice.id}/edit`,
+			},
+			{
+				key: 'duplicate',
+				text: 'Duplicate',
+				'prepend:icon': 'lucide:copy',
+				onClick: () => ctx.duplicateInvoice(invoice),
+			},
+			{
+				key: 'payment',
+				text: 'Record payment',
+				'prepend:icon': 'lucide:banknote',
+				onClick: () => (ctx.dialogs.recordPayment.value = invoice),
+			},
+			{
+				key: 'archive',
+				text: 'Archive',
+				'prepend:icon': 'lucide:archive',
+				onClick: () => ctx.archiveInvoice(invoice),
+			},
+			{
+				key: 'delete',
+				text: 'Delete',
+				'prepend:icon': 'lucide:trash-2',
+				variant: 'destructive',
+				onClick: () => ctx.deleteInvoice(invoice),
+			},
+		]"
+	>
+		<template #activator="{ props }">
+			<BbButton v-bind="props" icon="lucide:ellipsis" size="sm" variant="ghost">
+				Invoice actions
+			</BbButton>
+		</template>
+	</BbDropdown>
+</template>
+
+<script setup lang="ts">
+import { BbButton, BbDropdown } from 'bitboss-ui';
+import { useInvoicesWorkspace } from './context';
+import type { Invoice } from '@/types';
+
+defineProps<{ invoice: Invoice }>();
+
+const ctx = useInvoicesWorkspace();
+</script>
+```
+
+### SelectionBar.vue
+
+```vue
+<!-- InvoicesWorkspace/SelectionBar.vue -->
+<template>
+	<FloatingBottomPanel :open="selectedCount > 0">
+		<span class="px-2 text-sm">{{ selectedCount }} selected</span>
+		<BbButton
+			prepend:icon="lucide:check"
+			size="sm"
+			variant="ghost"
+			@click="ctx.bulkMarkPaid"
+		>
+			Mark as paid
+		</BbButton>
+		<BbButton
+			prepend:icon="lucide:send"
+			size="sm"
+			variant="ghost"
+			@click="ctx.bulkRemind"
+		>
+			Send reminder
+		</BbButton>
+		<div class="floating-bottom-panel__right flex items-center gap-1">
+			<BbButton size="sm" variant="destructive" @click="ctx.bulkArchive"
+				>Archive</BbButton
+			>
+			<BbButton
+				aria-label="Clear selection"
+				icon="lucide:x"
+				size="sm"
+				variant="ghost"
+				@click="clearSelection"
+			/>
+		</div>
+	</FloatingBottomPanel>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbButton } from 'bitboss-ui';
+import FloatingBottomPanel from '@/components/layout/FloatingBottomPanel.vue';
+import { useInvoicesWorkspace } from './context';
+
+const ctx = useInvoicesWorkspace();
+
+const selectedCount = computed(() => ctx.table.selected.value?.length ?? 0);
+const clearSelection = () => {
+	ctx.table.selected.value = [];
+};
+</script>
+```
+
+### InvoicePeek.vue
+
+```vue
+<!-- InvoicesWorkspace/InvoicePeek.vue -->
+<template>
+	<div v-if="invoice" class="flex flex-col gap-4 text-sm">
+		<!-- Header: identity + one-click status + amount. -->
+		<header class="flex flex-col gap-1.5">
+			<div class="flex items-center justify-between gap-2">
+				<h2 class="text-base font-semibold">{{ invoice.number }}</h2>
+				<StatusCell :invoice="invoice" />
+			</div>
+			<p class="text-xl font-semibold">{{ currency.format(invoice.amount) }}</p>
+			<p class="text-xs text-gray-500">
+				Issued {{ longDate(invoice.issuedAt) }} · due
+				{{ longDate(invoice.dueDate) }}
+			</p>
+		</header>
+
+		<!-- Properties: customer name drills DOWN — stacked peek, back arrow. -->
+		<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
+			<dt class="text-gray-500">Customer</dt>
+			<dd>
+				<BbButton
+					size="sm"
+					variant="link"
+					@click="() => ctx.stackCustomer(invoice!.customer.id)"
+				>
+					{{ invoice.customer.name }}
+				</BbButton>
+			</dd>
+			<dt class="text-gray-500">Project</dt>
+			<dd>{{ invoice.project.name }}</dd>
+			<dt class="text-gray-500">Payment terms</dt>
+			<dd>{{ invoice.paymentTerms }}</dd>
+			<dt class="text-gray-500">Reference</dt>
+			<dd>{{ invoice.reference }}</dd>
+		</dl>
+
+		<!-- Line items: a real mini-table, not a summary sentence. -->
+		<section class="flex flex-col gap-1.5">
+			<h3 class="text-xs font-semibold uppercase tracking-wide text-gray-500">
+				Line items
+			</h3>
+			<BbTable
+				caption="Invoice line items"
+				:columns="[
+					{ key: 'description', label: 'Description' },
+					{ key: 'quantity', label: 'Qty' },
+					{
+						key: 'total',
+						label: 'Total',
+						formatter: (value: number) => currency.format(value),
+					},
+				]"
+				compact
+				item-value="id"
+				:items="invoice.lineItems"
+			/>
+		</section>
+
+		<!-- Payments so far. -->
+		<section v-if="invoice.payments.length" class="flex flex-col gap-1.5">
+			<h3 class="text-xs font-semibold uppercase tracking-wide text-gray-500">
+				Payments
+			</h3>
+			<ul class="flex flex-col gap-1">
+				<li
+					v-for="payment in invoice.payments"
+					:key="payment.id"
+					class="flex items-center justify-between gap-2"
+				>
+					<span
+						>{{ currency.format(payment.amount) }} · {{ payment.method }}</span
+					>
+					<span class="text-xs text-gray-500">{{
+						longDate(payment.paidAt)
+					}}</span>
+				</li>
+			</ul>
+		</section>
+
+		<!-- Activity feed. -->
+		<section class="flex flex-col gap-1.5">
+			<h3 class="text-xs font-semibold uppercase tracking-wide text-gray-500">
+				Activity
+			</h3>
+			<ul class="flex flex-col gap-2">
+				<li
+					v-for="entry in invoice.activity"
+					:key="entry.id"
+					class="flex gap-2"
+				>
+					<BbIcon
+						class="mt-0.5 shrink-0 text-gray-400"
+						:icon="entry.icon"
+						size="14"
+					/>
+					<div class="flex flex-col">
+						<span>{{ entry.text }}</span>
+						<span class="text-xs text-gray-500"
+							>{{ entry.actor }} · {{ longDate(entry.at) }}</span
+						>
+					</div>
+				</li>
+			</ul>
+		</section>
+
+		<!-- Peek is a workbench: act here, or leave for the full page. -->
+		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
+			<BbButton
+				prepend:icon="lucide:banknote"
+				size="sm"
+				variant="secondary"
+				@click="() => (ctx.dialogs.recordPayment.value = invoice)"
+			>
+				Record payment
+			</BbButton>
+			<BbButton
+				append:icon="lucide:arrow-up-right"
+				size="sm"
+				:to="`/invoices/${invoice.id}`"
+				variant="ghost"
+			>
+				Open full page
+			</BbButton>
+		</footer>
+	</div>
+
+	<div v-else class="flex justify-center p-8">
+		<BbSpinner />
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref, watchEffect } from 'vue';
+import { BbButton, BbIcon, BbSpinner, BbTable } from 'bitboss-ui';
+import StatusCell from './StatusCell.vue';
+import { useInvoicesWorkspace } from './context';
+import type { InvoiceDetail } from '@/types';
+
+const props = defineProps<{ invoiceId: number }>();
+
+const ctx = useInvoicesWorkspace();
+
+// Re-fetches whenever the stack shows a different invoice; the surrounding
+// list's `refresh()` re-renders `ctx.invoices`, but this JSON fetch is its
+// own concern so it re-runs whenever the invoice list refreshes too.
+const invoice = ref<InvoiceDetail | null>(null);
+watchEffect(async () => {
+	void ctx.invoices.value;
+	invoice.value = await $fetch<InvoiceDetail>(
+		`/api/invoices/${props.invoiceId}`
+	);
+});
+
+const currency = new Intl.NumberFormat('en-US', {
+	style: 'currency',
+	currency: 'USD',
+});
+const longDate = (value: string) =>
+	new Date(value).toLocaleDateString('en-US', {
+		month: 'short',
+		day: 'numeric',
+		year: 'numeric',
+	});
+</script>
+```
+
+### CustomerPeek.vue
+
+```vue
+<!-- InvoicesWorkspace/CustomerPeek.vue -->
+<template>
+	<div v-if="customer" class="flex flex-col gap-4 text-sm">
+		<header class="flex items-center gap-3">
+			<BbAvatar :alt="customer.name" :src="customer.avatarUrl" />
+			<div class="flex flex-col">
+				<h2 class="text-base font-semibold">{{ customer.name }}</h2>
+				<p class="text-xs text-gray-500">
+					{{ customer.email }} · {{ customer.country }}
+				</p>
+			</div>
+		</header>
+
+		<!-- Stat strip. -->
+		<div class="grid grid-cols-3 gap-2">
+			<div class="rounded-[var(--bb-radius)] border p-2">
+				<p class="text-xs text-gray-500">Total billed</p>
+				<p class="font-semibold">{{ currency.format(customer.totalBilled) }}</p>
+			</div>
+			<div class="rounded-[var(--bb-radius)] border p-2">
+				<p class="text-xs text-gray-500">Outstanding</p>
+				<p class="font-semibold">{{ currency.format(customer.outstanding) }}</p>
+			</div>
+			<div class="rounded-[var(--bb-radius)] border p-2">
+				<p class="text-xs text-gray-500">Invoices</p>
+				<p class="font-semibold">{{ customer.invoiceCount }}</p>
+			</div>
+		</div>
+
+		<!-- Recent invoices: names drill down again — the stack keeps growing. -->
+		<section class="flex flex-col gap-1.5">
+			<h3 class="text-xs font-semibold uppercase tracking-wide text-gray-500">
+				Recent invoices
+			</h3>
+			<ul class="flex flex-col">
+				<li
+					v-for="recent in customer.recentInvoices"
+					:key="recent.id"
+					class="flex items-center justify-between gap-2 border-b py-1.5 last:border-b-0"
+				>
+					<BbButton
+						size="sm"
+						variant="link"
+						@click="() => ctx.stackInvoice(recent.id)"
+					>
+						{{ recent.number }}
+					</BbButton>
+					<BbBadge variant="outline">{{ recent.status }}</BbBadge>
+					<span class="text-xs text-gray-500">{{
+						currency.format(recent.amount)
+					}}</span>
+				</li>
+			</ul>
+		</section>
+
+		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
+			<BbButton
+				append:icon="lucide:arrow-up-right"
+				size="sm"
+				:to="`/customers/${customer.id}`"
+				variant="ghost"
+			>
+				Open customer
+			</BbButton>
+		</footer>
+	</div>
+
+	<div v-else class="flex justify-center p-8">
+		<BbSpinner />
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref, watchEffect } from 'vue';
+import { BbAvatar, BbBadge, BbButton, BbSpinner } from 'bitboss-ui';
+import { useInvoicesWorkspace } from './context';
+import type { CustomerDetail } from '@/types';
+
+const props = defineProps<{ customerId: number }>();
+
+const ctx = useInvoicesWorkspace();
+
+const customer = ref<CustomerDetail | null>(null);
+watchEffect(async () => {
+	customer.value = await $fetch<CustomerDetail>(
+		`/api/customers/${props.customerId}`
+	);
+});
+
+const currency = new Intl.NumberFormat('en-US', {
+	style: 'currency',
+	currency: 'USD',
+});
+</script>
+```
+
+### RecordPaymentDialog.vue
+
+```vue
+<!-- InvoicesWorkspace/RecordPaymentDialog.vue -->
+<template>
+	<BbDialog
+		:model-value="invoice !== null"
+		size="sm"
+		:title="invoice ? `Record payment — ${invoice.number}` : ''"
+		@update:model-value="close"
+	>
+		<form
+			v-if="invoice"
+			class="flex flex-col gap-3"
+			novalidate
+			@submit.prevent="submit"
+		>
+			<BbNumberInput
+				v-model="draft.amount"
+				label="Amount"
+				label-mode="outside"
+				:max-precision="2"
+				:min="0"
+			>
+				<template #prefix>$</template>
+			</BbNumberInput>
+			<BbDatePickerInput
+				v-model="draft.paidAt"
+				label="Paid on"
+				label-mode="outside"
+			/>
+			<BbSelect
+				v-model="draft.method"
+				:items="['bank transfer', 'card', 'check', 'cash']"
+				label="Method"
+				label-mode="outside"
+			/>
+			<div class="mt-1 flex justify-end gap-2">
+				<BbButton type="button" variant="ghost" @click="close">Cancel</BbButton>
+				<BbButton type="submit" variant="secondary">Record payment</BbButton>
+			</div>
+		</form>
+	</BbDialog>
+</template>
+
+<script setup lang="ts">
+import { computed, reactive, watch } from 'vue';
+import {
+	BbButton,
+	BbDatePickerInput,
+	BbDialog,
+	BbNumberInput,
+	BbSelect,
+} from 'bitboss-ui';
+import { useInvoicesWorkspace } from './context';
+import type { PaymentDraft } from '@/types';
+
+const ctx = useInvoicesWorkspace();
+
+// The dialog's subject lives in the page context — any component on the
+// page (row actions, the peek) can open it by assigning the invoice.
+const invoice = computed(() => ctx.dialogs.recordPayment.value);
+const close = () => {
+	ctx.dialogs.recordPayment.value = null;
+};
+
+const draft = reactive<PaymentDraft>({
+	amount: null,
+	paidAt: null,
+	method: null,
+});
+watch(invoice, (next) => {
+	// Re-seed per invoice: default to paying the remaining balance today.
+	draft.amount = next?.amountDue ?? null;
+	draft.paidAt = next ? new Date().toISOString() : null;
+	draft.method = null;
+});
+
+// Returning the promise lets the submit button track the async work.
+const submit = () =>
+	invoice.value ? ctx.recordPayment(invoice.value, { ...draft }) : undefined;
+</script>
+```
+
+## Why it is built this way
+
+- **The context coopts, leaves consume.** `shell` and `table` are joined
+  once in `provideInvoicesWorkspace()`; nine components share filters,
+  selection, the peek stack and every action through one
+  `useInvoicesWorkspace()` call. No component on this page receives a
+  callback prop, and only peeks/cells receive data props (the item or id
+  they render).
+- **The URL is the filter store, `useAsyncData` is the fetch.** Filters and
+  tab are seeded from `route.query` once at setup, mirrored back with
+  `navigateTo` on every change (debounced for free text), and
+  `useAsyncData('invoices', …, { watch: [() => route.query, table.page] })`
+  is the single refetch trigger — there is exactly one place data loads.
+- **The table context still owns paging and selection.** `useBbTableContext`
+  is unchanged from the Vue recipe: it seeds `perPage`, `BbPagination`
+  joins by `table-id`, and `SelectionBar` reads `table.selected` — only the
+  _items_ move from an items-function to a resolved `:items` array written
+  by the page's own fetch.
+- **`peekX` vs `stackX` is the whole stack grammar.** Fresh peeks replace,
+  drill-downs push; the shell renders the back arrow when depth > 1. The
+  grammar lives in the context — a leaf cannot accidentally nuke the
+  stack.
+- **Tabs carry `href` and live counts**, exactly as in the Vue recipe — the
+  client-side pushState they perform keeps `route.query.tab` in sync, which
+  is what seeds `tab` on load and what `useAsyncData`'s `route.query` watch
+  reacts to.
+- **Internal links use `to`, not `href`.** `to` renders a real Vue Router
+  link (client-side navigation); a raw `href` would force a full page
+  reload. Every same-app link in this recipe — the primary "New invoice"
+  action, the row `Edit` item, both peek "Open…" links — uses `to`.
+- **Dialogs hang off the context** (`ctx.dialogs.recordPayment` holds the
+  subject invoice, not a boolean) so row actions and the peek open the
+  same dialog with zero coordination.
+- **Sizing:** topbar and rail follow `md`-first (`compact` inputs at 28px
+  flush beside the default buttons); `sm` appears exactly where the
+  doctrine allows — row actions, pills, peek footers, the bulk bar.
+- **One `variant="primary"`** (New invoice). Destructive actions —
+  single, bulk, in-peek — all ride `useConfirm`.
+- **The status badge tells you it saves.** `StatusCell` carries the §6.1
+  niceties: an internal trailing chevron (a clickable status must say so)
+  and `:loading` around the awaited context action, so the spinner takes
+  the chevron's place while the save runs. The flag is a local `ref` —
+  rung 1, not context state. The ownership grammar behind inline edits is
+  the [Inline Edit Playbook](../../guides/inline-edit-playbook.md).
+
+## Variations
+
+- **Keyboard triage**: add `keyboard-navigation` to the table and open the
+  peek from `v-model:highlighted` — the approvals-inbox recipe is the
+  full treatment.
+- **Saved views**: persist `filters` + `tab` per user in a store
+  (`useSavedViewsStore`) and render a view switcher before the tabs.
+- **Inline amount editing**: swap the amount cell for an
+  `EditableAmountCell` per the inline-editing pattern. Choosing between
+  explicit-commit cells and a fully autosaving grid is the
+  [Inline Edit Playbook](../../guides/inline-edit-playbook.md); the
+  autosave treatment is the inline-edit-workspace recipe.
+- **SSR-populated peeks**: swap the peeks' `$fetch` calls for
+  `useAsyncData` keyed by id if the peek content should be part of the
+  server-rendered payload rather than a client-side follow-up fetch.