bitboss-ui 2.1.134 → 3.0.0-alpha.1

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

@@ -0,0 +1,1328 @@
+---
+title: Records Workspace (Inertia)
+summary: Full-anatomy invoices workspace for Laravel + Inertia — breadcrumbs + page search, chip filter rail (one Filters menu + editable filter chips), server-visit tabs with counts, one-click status cells via promise-wrapped visits, bulk bottom panel with select-all-across-pages, and a stacked peek sidebar, all through one page context that coopts the Inertia Helpers toolkit.
+---
+
+# Recipe: Records Workspace (Inertia)
+
+The flagship advanced-page recipe adapted for **Laravel + Inertia**: the
+same Stripe-invoices × Linear list workspace — app chrome, breadcrumbs +
+page search, chip filter rail, tabs with live counts, a dense server-paged
+table, a floating bulk-action bar, and a stacked peek sidebar — but the list
+is a page prop, filters mirror into the URL through
+[`useQueryObject`](../../guides/inertia-helpers.md), selection and paging
+come from the keyed [`useTableContext`](../../guides/inertia-helpers.md),
+and every mutation is a promise-wrapped `router.visit`. Anatomy, components,
+the context shape, copy and data are identical to the Vue recipe; only the
+data/URL/mutation layer changes.
+
+Sibling recipes: [Vue](../vue/records-workspace.md) ·
+[Nuxt](../nuxt/records-workspace.md).
+
+## Prerequisites
+
+- `<BbConfirm />` and `<BbToast />` mounted once in the app layout.
+- From the [Inertia Helpers](../../guides/inertia-helpers.md) toolkit:
+  `useTableContext`, `useQueryObject`, `useResourceContext`.
+- Controller: `Inertia::render('Invoices/Index', ['invoices' =>
+InvoicePaginator::make(...), 'tabCounts' => [...]])` — `invoices` is a
+  standard Laravel paginator (`PaginatedResponse<Invoice>`) and `tabCounts`
+  a plain `{ all, outstanding, paid, archived }` map. Both are re-sent on
+  every partial reload the page triggers (`only: ['invoices', 'tabCounts']`).
+  Mutation routes are plain Laravel routes (`PATCH /invoices/:id`,
+  `POST /invoices/:id/duplicate`, …) that redirect back; small JSON GET
+  endpoints (`GET /invoices/:id/peek`, `GET /customers/:id/peek`,
+  `GET /customers/search`) back the sidebar peeks and the customer filter
+  facet so neither is a full-page visit.
+
+## Key ideas
+
+- **One coopting page context.** `provideInvoicesWorkspace()` joins the
+  page-shell stack **and** the keyed `useTableContext('invoices')` once,
+  owns filters/tab/dialogs, and exposes complete actions. Every leaf calls
+  `useInvoicesWorkspace()` and nothing else — zero prop drilling anywhere
+  on the page.
+- **The table has no client-side fetch at all.** `invoices` arrives as a
+  page prop; `useTableContext('invoices')` turns it into `items` +
+  `totalItems`/`page`/`perPage` (URL-backed) + `selected`/`unselected`/`all`
+  (select-all-across-pages), and `BbTable` binds directly to that handle —
+  no `dependencies`, no items function.
+- **Filters mirror into the URL with `useQueryObject`.** Changing a filter
+  performs a debounced partial Inertia visit
+  (`only: ['invoices', 'tabCounts']`); the server is the single source of
+  filtered, paginated truth.
+- **One Filters menu, one chip per applied facet.** The rail is a single
+  `BbDropdown` of searchable categories (status / customer / due-date
+  presets) plus one chip per APPLIED facet — never one per value. Each chip
+  is itself a dropdown onto the same filter group, so it edits in place;
+  clearing happens chip by chip (no bulk clear-all).
+- **Tabs are real visits.** `BbTabs` items carry `href` + `server: true`
+  (component-level `navigation` is required alongside it) so switching tabs
+  is a genuine, partial-reloaded Inertia visit — not a client-only URL
+  change.
+- **Mutations are promise-wrapped `router.visit` calls.** A tiny local
+  `visit()` helper turns Inertia's callback-based API into a promise, so
+  context actions stay `async function`s exactly like the Vue/Nuxt
+  versions — `await ctx.updateStatus(...)` reads the same everywhere.
+- **Clicking a row peeks it.** `v-model:highlighted` is bound to the shell
+  stack, so the highlighted row and the open peek are the same fact; the
+  invoice number cell links to the full detail page instead. Peeks fetch
+  from a small JSON endpoint via `useResourceContext` — not a full-page
+  visit, so opening the sidebar never replaces the list underneath it.
+- **Buttons are `md` by default** (28px, flush beside `compact` inputs);
+  `sm` only in the table rows, the peeks' headers and the bottom bar.
+
+## Page anatomy
+
+```
+InvoicesWorkspace/
+	Index.vue               ← assembly: PageShell slots, table, tabs, pagination
+	context.ts               ← coopting page context (shell + useTableContext + filters + actions)
+	facets.ts                ← the facet contract (shape only — deliberately no shared builder)
+	dueRange.ts              ← due-date preset keys + range math
+	FilterRail.vue           ← one Filters menu + one chip per applied facet
+	FilterChip.vue           ← applied-facet chip — itself a dropdown onto the same filter
+	StatusCell.vue           ← one-click status change (soft badge → BbSelectPopover)
+	DueDateCell.vue          ← inline due-date reschedule (BbPopover calendar)
+	RowActions.vue           ← per-row "…" dropdown
+	SelectionBar.vue         ← bulk actions in the floating bottom panel
+	InvoicePeek.vue          ← sidebar workbench, stack level 1
+	CustomerPeek.vue         ← stacked peek, back arrow via the shell
+	RecordPaymentDialog.vue  ← page-level dialog, driven by the context
+```
+
+Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
+(left nav + fat footer), [Page Shell](../../guides/page-shell.md),
+[Floating Bottom Panel](../../guides/floating-bottom-panel.md).
+
+## Action inventory
+
+| #   | Action                         | Trigger                          | Mechanism                                              |
+| --- | ------------------------------ | -------------------------------- | ------------------------------------------------------ |
+| 1   | New invoice                    | topbar, the page's one `primary` | navigation (`href="/invoices/create"`)                 |
+| 2   | Page search                    | topbar right                     | `filters.search` → `useQueryObject` partial visit      |
+| 3   | Filter status / customer / due | Filters menu + filter chips      | `BbDropdown` facets; chips edit the filter in place    |
+| 4   | Clear a filter                 | chip clear button                | facet `clear()` — one facet at a time, no bulk CTA     |
+| 5   | Switch tab                     | server-visit tabs with counts    | `BbTabs` `href` + `server: true` visit                 |
+| 6   | Peek invoice                   | row click / peek lists           | `v-model:highlighted` → `peekInvoice(id)`, JSON fetch  |
+| 7   | Peek customer                  | customer cell (fresh) / in peeks | `peekCustomer(id)` / `stackCustomer(id)` → back arrow  |
+| 8   | Change status inline           | status badge in row & peek       | one-click `BbSelectPopover` → undoable visit           |
+| 9   | Reschedule due date inline     | due-date cell                    | `BbPopover` calendar → undoable visit                  |
+| 10  | Record payment                 | row `…`, peek button             | `BbDialog` via `ctx.dialogs` → promise-wrapped visit   |
+| 11  | Edit / duplicate               | row `…` dropdown                 | navigation (`href`) / context action                   |
+| 12  | Archive / delete               | row `…`, bulk bar                | destructive behind `useConfirm`                        |
+| 13  | Bulk mark paid / remind        | floating bottom panel            | context actions on `table.selected`/`all`/`unselected` |
+| 14  | Select rows / select all       | table checkboxes                 | `useTableContext` selection (across pages)             |
+| 15  | Open full invoice              | invoice number cell, peek footer | navigation (`href="/invoices/:id"`)                    |
+| 16  | Back / close peek              | shell chrome                     | shell stack pop / close                                |
+
+## The code
+
+### context.ts
+
+```ts
+// InvoicesWorkspace/context.ts
+import {
+	computed,
+	inject,
+	provide,
+	reactive,
+	ref,
+	type ComputedRef,
+	type InjectionKey,
+	type Ref,
+} from 'vue';
+import { router } from '@inertiajs/vue3';
+import type { RequestPayload } from '@inertiajs/core';
+import { useConfirm, useToast } from 'bitboss-ui';
+import {
+	usePageShellContext,
+	type PageShellContext,
+} from '@/components/layout/usePageShellContext';
+import {
+	useTableContext,
+	type TableContext,
+} from '@/composables/useTableContext';
+import { useQueryObject } from '@/composables/useQueryObject';
+import { useProp } from '@/composables/useProp';
+import { useQuery } from '@/composables/useQuery';
+import type { Invoice, InvoiceStatus, PaymentDraft } from '@/types';
+
+/** What the stacked sidebar can show. 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[];
+}
+
+const RELOAD_PROPS = ['invoices', 'tabCounts'] as const;
+
+export interface InvoicesWorkspaceContext {
+	// -- Coopted contexts ------------------------------------------------------
+	shell: PageShellContext<PeekItem>;
+	table: TableContext<Invoice, number>;
+	// -- Page-owned state ------------------------------------------------------
+	filters: InvoiceFilters;
+	hasActiveFilters: ComputedRef<boolean>;
+	tab: Ref<WorkspaceTab>;
+	tabCounts: ComputedRef<Record<WorkspaceTab, number>>;
+	dialogs: { recordPayment: Ref<Invoice | null> };
+	/** Bumped after every mutation — peeks watch it to re-fetch their JSON detail. */
+	refreshKey: Ref<number>;
+	// -- Peek grammar ----------------------------------------------------------
+	peekInvoice: (id: number) => void;
+	stackInvoice: (id: number) => void;
+	stackCustomer: (id: number) => void;
+	// -- Actions (complete: visit + refresh + toast) -----------------------------
+	clearFilters: () => void;
+	updateStatus: (invoice: Invoice, status: InvoiceStatus) => Promise<void>;
+	duplicateInvoice: (invoice: Invoice) => Promise<void>;
+	recordPayment: (invoice: Invoice, draft: PaymentDraft) => Promise<void>;
+	archiveInvoice: (invoice: Invoice) => Promise<void>;
+	deleteInvoice: (invoice: Invoice) => Promise<void>;
+	bulkMarkPaid: () => Promise<void>;
+	bulkRemind: () => Promise<void>;
+	bulkArchive: () => Promise<void>;
+}
+
+const key: InjectionKey<InvoicesWorkspaceContext> =
+	Symbol('invoices-workspace');
+
+/** Comma-joined query value → string[] (or null when absent). */
+const toArray = (value: unknown): string[] | null => {
+	if (value == null || value === '') return null;
+	return Array.isArray(value) ? value.map(String) : String(value).split(',');
+};
+
+/** Inertia's callback-based visit, wrapped as a promise — so every context
+ * action stays `async`, exactly like the Vue/Nuxt versions. Always a
+ * partial reload of the props this page depends on. */
+const visit = (
+	method: 'post' | 'put' | 'patch' | 'delete',
+	url: string,
+	// Inertia's own payload type — strings/numbers/booleans/arrays/files.
+	// (`Record<string, unknown>` does not satisfy it.)
+	data: RequestPayload = {}
+): Promise<void> =>
+	new Promise((resolve, reject) => {
+		router.visit(url, {
+			method,
+			data,
+			only: [...RELOAD_PROPS],
+			preserveScroll: true,
+			preserveState: true,
+			onSuccess: () => resolve(),
+			onError: (errors) => reject(errors),
+		});
+	});
+
+export function provideInvoicesWorkspace(): InvoicesWorkspaceContext {
+	const { toast } = useToast();
+	const { confirm } = useConfirm();
+
+	// -- Coopt the specific contexts: once, here, for the whole page. ----------
+	const shell = usePageShellContext<PeekItem>();
+	// `Invoice, number`: BbTable's `item-value="id"` resolves selection to
+	// invoice ids, matching the Vue/Nuxt `table.selected: number[]` shape.
+	const table = useTableContext<Invoice, number>('invoices');
+
+	// -- Filters: seeded from the current URL, mirrored back by useQueryObject. -
+	const query = useQuery();
+	const filters = reactive<InvoiceFilters>({
+		search: (query.search as string) ?? '',
+		status: (toArray(query.status) ?? []) as InvoiceStatus[],
+		customerId: query.customerId ? Number(query.customerId) : null,
+		dueBetween: toArray(query.dueBetween) ?? [],
+	});
+	useQueryObject(filters, { only: [...RELOAD_PROPS] });
+
+	const hasActiveFilters = computed(
+		() =>
+			filters.search !== '' ||
+			filters.status.length > 0 ||
+			filters.customerId !== null ||
+			filters.dueBetween.length > 0
+	);
+	const clearFilters = () => {
+		filters.search = '';
+		filters.status = [];
+		filters.customerId = null;
+		filters.dueBetween = [];
+	};
+
+	// Tab: seeded from the URL; BbTabs' own `href` + `server` visit updates
+	// the URL, and its `v-model` write keeps this ref in sync with the click.
+	const tab = ref<WorkspaceTab>((query.tab as WorkspaceTab) ?? 'all');
+	const tabCounts = useProp<Record<WorkspaceTab, number>>('tabCounts');
+
+	const refreshKey = ref(0);
+	const dialogs = { recordPayment: ref<Invoice | null>(null) };
+
+	// -- Peek grammar ----------------------------------------------------------------
+	// peekX opens a fresh stack (from the list); stackX drills down (from a peek).
+	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 refresh = () => {
+		refreshKey.value++;
+	};
+
+	const updateStatus = async (invoice: Invoice, status: InvoiceStatus) => {
+		await visit('patch', `/invoices/${invoice.id}`, { status });
+		refresh();
+		toast({
+			title: `${invoice.number} moved to ${status}.`,
+			variant: 'success',
+		});
+	};
+
+	const duplicateInvoice = async (invoice: Invoice) => {
+		await visit('post', `/invoices/${invoice.id}/duplicate`);
+		refresh();
+		toast({ title: `${invoice.number} duplicated.`, variant: 'success' });
+	};
+
+	const recordPayment = async (invoice: Invoice, draft: PaymentDraft) => {
+		await visit('post', `/invoices/${invoice.id}/payments`, { ...draft });
+		dialogs.recordPayment.value = null;
+		refresh();
+		toast({
+			title: `Payment recorded on ${invoice.number}.`,
+			variant: 'success',
+		});
+	};
+
+	const archiveInvoice = async (invoice: Invoice) => {
+		await visit('patch', `/invoices/${invoice.id}/archive`);
+		refresh();
+		toast({ title: `${invoice.number} archived.`, variant: 'success' });
+	};
+
+	const deleteInvoice = async (invoice: Invoice) => {
+		const ok = await confirm({
+			variant: 'destructive',
+			title: 'Delete invoice',
+			text: `Delete ${invoice.number}? This cannot be undone.`,
+			yes: 'Delete',
+			no: 'Cancel',
+		});
+		if (!ok) return;
+		await visit('delete', `/invoices/${invoice.id}`);
+		refresh();
+		toast({ title: `${invoice.number} deleted.`, variant: 'success' });
+	};
+
+	// Bulk actions carry the full select-all-across-pages payload — the
+	// server combines `all` + `unselected` the same way BbTable does.
+	const bulkPayload = () => ({
+		ids: table.selected.value,
+		all: table.all.value,
+		unselected: table.unselected.value,
+	});
+	const bulkCount = () =>
+		table.all.value
+			? table.totalItems.value - table.unselected.value.length
+			: table.selected.value.length;
+
+	const bulkMarkPaid = async () => {
+		const count = bulkCount();
+		await visit('patch', '/invoices/bulk/mark-paid', bulkPayload());
+		table.resetSelection();
+		toast({ title: `${count} invoices marked as paid.`, variant: 'success' });
+	};
+
+	const bulkRemind = async () => {
+		const count = bulkCount();
+		await visit('post', '/invoices/bulk/remind', bulkPayload());
+		table.resetSelection();
+		toast({
+			title: `Reminder sent for ${count} invoices.`,
+			variant: 'success',
+		});
+	};
+
+	const bulkArchive = async () => {
+		const count = bulkCount();
+		const ok = await confirm({
+			variant: 'destructive',
+			title: 'Archive invoices',
+			text: `Archive ${count} invoices? They move out of every tab except Archived.`,
+			yes: 'Archive',
+			no: 'Cancel',
+		});
+		if (!ok) return;
+		await visit('patch', '/invoices/bulk/archive', bulkPayload());
+		table.resetSelection();
+		toast({ title: `${count} invoices archived.`, variant: 'success' });
+	};
+
+	const ctx: InvoicesWorkspaceContext = {
+		shell,
+		table,
+		filters,
+		hasActiveFilters,
+		tab,
+		tabCounts,
+		dialogs,
+		refreshKey,
+		peekInvoice,
+		stackInvoice,
+		stackCustomer,
+		clearFilters,
+		updateStatus,
+		duplicateInvoice,
+		recordPayment,
+		archiveInvoice,
+		deleteInvoice,
+		bulkMarkPaid,
+		bulkRemind,
+		bulkArchive,
+	};
+	provide(key, ctx);
+	return ctx;
+}
+
+export function useInvoicesWorkspace(): InvoicesWorkspaceContext {
+	const ctx = inject(key);
+	if (!ctx)
+		throw new Error('useInvoicesWorkspace() called outside InvoicesWorkspace');
+	return ctx;
+}
+```
+
+### Index.vue — the assembly
+
+```vue
+<!-- InvoicesWorkspace/Index.vue -->
+<template>
+	<PageShell>
+		<!-- Topbar: breadcrumbs left, page search + primary action right. -->
+		<template #topbar>
+			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
+				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
+				     without it their overflow recompute fights the flex layout every frame. -->
+				<BbBreadcrumbs
+					class="min-w-0 flex-auto"
+					:items="[
+						{ key: 'dashboard', text: 'Dashboard', href: '/dashboard' },
+						{ key: 'billing', text: 'Billing', href: '/billing' },
+						{ key: 'invoices', text: 'Invoices' },
+					]"
+				/>
+				<div class="flex shrink-0 items-center gap-2">
+					<BbTextInput
+						v-model="ctx.filters.search"
+						hide-label
+						label="Search invoices"
+						clearable
+						compact
+						placeholder="Search number or customer…"
+						prepend:icon="lucide:search"
+					/>
+					<BbButton
+						href="/invoices/create"
+						prepend:icon="lucide:plus"
+						variant="primary"
+					>
+						New invoice
+					</BbButton>
+				</div>
+			</div>
+		</template>
+
+		<div class="flex flex-col gap-3 p-4">
+			<FilterRail />
+
+			<!-- Tabs are real visits: href + server (component-level `navigation`
+			     is required alongside per-item `server`), each carrying the same
+			     partial-reload prop list as the filter watcher. `preserve-state`
+			     keeps this page (and the tabs instance) alive across the visit so
+			     the sliding pill animates to the new tab instead of the page
+			     remounting and the pill snapping — matching the filter watcher,
+			     which already visits with preserveState. -->
+			<BbTabs
+				v-model="ctx.tab.value"
+				compact
+				navigation
+				preserve-scroll
+				preserve-state
+				replace
+				:items="[
+					{
+						key: 'all',
+						label: `All · ${ctx.tabCounts.value.all}`,
+						href: '/invoices?tab=all',
+						server: true,
+						only: ['invoices', 'tabCounts'],
+					},
+					{
+						key: 'outstanding',
+						label: `Outstanding · ${ctx.tabCounts.value.outstanding}`,
+						href: '/invoices?tab=outstanding',
+						server: true,
+						only: ['invoices', 'tabCounts'],
+					},
+					{
+						key: 'paid',
+						label: `Paid · ${ctx.tabCounts.value.paid}`,
+						href: '/invoices?tab=paid',
+						server: true,
+						only: ['invoices', 'tabCounts'],
+					},
+					{
+						key: 'archived',
+						label: `Archived · ${ctx.tabCounts.value.archived}`,
+						href: '/invoices?tab=archived',
+						server: true,
+						only: ['invoices', 'tabCounts'],
+					},
+				]"
+			/>
+
+			<!-- No dependencies/items-fn: `invoices` is a page prop, and selection
+			     (across pages) binds straight onto the keyed table context. -->
+			<BbTable
+				v-model="ctx.table.selected.value"
+				v-model:select-all="ctx.table.all.value"
+				v-model:unselected-items="ctx.table.unselected.value"
+				actions
+				caption="Invoices"
+				:columns="columns"
+				compact
+				item-value="id"
+				:items="ctx.table.items.value"
+				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>
+
+			<!-- No table-id: the keyed table context is the page count here. -->
+			<BbPagination
+				v-model="ctx.table.page.value"
+				label="Invoices pagination"
+				:total-pages="ctx.table.totalPages.value"
+			/>
+		</div>
+
+		<SelectionBar />
+
+		<!-- 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 a small JSON endpoint. -->
+		<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.
+// A small JSON endpoint, not an Inertia visit — searching a filter pill
+// must not re-render the page.
+const searchCustomers = (query: string): Promise<Customer[]> =>
+	fetch(`/customers/search?q=${encodeURIComponent(query)}`).then((res) =>
+		res.json()
+	);
+
+// The trigger labels itself from page state (the popover is lazy by design
+// and cannot know the selected label before its first open).
+const selectedCustomer = ref<Customer | null>(null);
+watchEffect(async () => {
+	selectedCustomer.value =
+		ctx.filters.customerId == null
+			? null
+			: await fetch(`/customers/${ctx.filters.customerId}/peek`).then((res) =>
+					res.json()
+				);
+});
+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',
+				href: `/invoices/${invoice.id}/edit`,
+			},
+			{
+				key: 'duplicate',
+				text: 'Duplicate',
+				'prepend:icon': 'lucide:copy',
+				onClick: () => ctx.duplicateInvoice(invoice),
+			},
+			{
+				key: 'payment',
+				text: 'Record payment',
+				'prepend:icon': 'lucide:banknote',
+				onClick: () => (ctx.dialogs.recordPayment.value = invoice),
+			},
+			{
+				key: 'archive',
+				text: 'Archive',
+				'prepend:icon': 'lucide:archive',
+				onClick: () => ctx.archiveInvoice(invoice),
+			},
+			{
+				key: 'delete',
+				text: 'Delete',
+				'prepend:icon': 'lucide:trash-2',
+				variant: 'destructive',
+				onClick: () => ctx.deleteInvoice(invoice),
+			},
+		]"
+	>
+		<template #activator="{ props }">
+			<BbButton v-bind="props" icon="lucide:ellipsis" size="sm" variant="ghost">
+				Invoice actions
+			</BbButton>
+		</template>
+	</BbDropdown>
+</template>
+
+<script setup lang="ts">
+import { BbButton, BbDropdown } from 'bitboss-ui';
+import { useInvoicesWorkspace } from './context';
+import type { Invoice } from '@/types';
+
+defineProps<{ invoice: Invoice }>();
+
+const ctx = useInvoicesWorkspace();
+</script>
+```
+
+### SelectionBar.vue
+
+```vue
+<!-- InvoicesWorkspace/SelectionBar.vue -->
+<template>
+	<FloatingBottomPanel :open="selectedCount > 0">
+		<span class="px-2 text-sm">{{ selectedCount }} selected</span>
+		<BbButton
+			prepend:icon="lucide:check"
+			size="sm"
+			variant="ghost"
+			@click="ctx.bulkMarkPaid"
+		>
+			Mark as paid
+		</BbButton>
+		<BbButton
+			prepend:icon="lucide:send"
+			size="sm"
+			variant="ghost"
+			@click="ctx.bulkRemind"
+		>
+			Send reminder
+		</BbButton>
+		<div class="floating-bottom-panel__right flex items-center gap-1">
+			<BbButton size="sm" variant="destructive" @click="ctx.bulkArchive"
+				>Archive</BbButton
+			>
+			<BbButton
+				aria-label="Clear selection"
+				icon="lucide:x"
+				size="sm"
+				variant="ghost"
+				@click="ctx.table.resetSelection"
+			/>
+		</div>
+	</FloatingBottomPanel>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbButton } from 'bitboss-ui';
+import { useInvoicesWorkspace } from './context';
+import FloatingBottomPanel from '@/components/layout/FloatingBottomPanel.vue';
+
+const ctx = useInvoicesWorkspace();
+
+// `all` (select-all-across-pages) does not enumerate rows, so the visible
+// count is the total minus whatever the user manually deselected.
+const selectedCount = computed(() =>
+	ctx.table.all.value
+		? ctx.table.totalItems.value - ctx.table.unselected.value.length
+		: ctx.table.selected.value.length
+);
+</script>
+```
+
+### InvoicePeek.vue
+
+```vue
+<!-- InvoicesWorkspace/InvoicePeek.vue -->
+<template>
+	<div v-if="invoice" class="flex flex-col gap-4 text-sm">
+		<!-- Header: identity + one-click status + amount. -->
+		<header class="flex flex-col gap-1.5">
+			<div class="flex items-center justify-between gap-2">
+				<h2 class="text-base font-semibold">{{ invoice.number }}</h2>
+				<StatusCell :invoice="invoice" />
+			</div>
+			<p class="text-xl font-semibold">{{ currency.format(invoice.amount) }}</p>
+			<p class="text-xs text-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"
+				:href="`/invoices/${invoice.id}`"
+				size="sm"
+				variant="ghost"
+			>
+				Open full page
+			</BbButton>
+		</footer>
+	</div>
+
+	<div v-else class="flex justify-center p-8">
+		<BbSpinner />
+	</div>
+</template>
+
+<script setup lang="ts">
+import { watch } from 'vue';
+import { BbButton, BbIcon, BbSpinner, BbTable } from 'bitboss-ui';
+import { useResourceContext } from '@/composables/useResourceContext';
+import StatusCell from './StatusCell.vue';
+import { useInvoicesWorkspace } from './context';
+import type { InvoiceDetail } from '@/types';
+
+const props = defineProps<{ invoiceId: number }>();
+
+const ctx = useInvoicesWorkspace();
+
+// A small JSON endpoint, not a page visit — opening the peek never
+// re-renders the list underneath it. Re-fetches whenever the stack shows a
+// different invoice; `refreshKey` makes mutations (status, payment) reflect
+// here immediately.
+const { data: invoice, refresh } = useResourceContext<InvoiceDetail, number>(
+	() => props.invoiceId,
+	(id) => fetch(`/invoices/${id}/peek`).then((res) => res.json())
+);
+watch(() => ctx.refreshKey.value, refresh);
+
+const currency = new Intl.NumberFormat('en-US', {
+	style: 'currency',
+	currency: 'USD',
+});
+const longDate = (value: string) =>
+	new Date(value).toLocaleDateString('en-US', {
+		month: 'short',
+		day: 'numeric',
+		year: 'numeric',
+	});
+</script>
+```
+
+### CustomerPeek.vue
+
+```vue
+<!-- InvoicesWorkspace/CustomerPeek.vue -->
+<template>
+	<div v-if="customer" class="flex flex-col gap-4 text-sm">
+		<header class="flex items-center gap-3">
+			<BbAvatar :alt="customer.name" :src="customer.avatarUrl" />
+			<div class="flex flex-col">
+				<h2 class="text-base font-semibold">{{ customer.name }}</h2>
+				<p class="text-xs text-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"
+				:href="`/customers/${customer.id}`"
+				size="sm"
+				variant="ghost"
+			>
+				Open customer
+			</BbButton>
+		</footer>
+	</div>
+
+	<div v-else class="flex justify-center p-8">
+		<BbSpinner />
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbAvatar, BbBadge, BbButton, BbSpinner } from 'bitboss-ui';
+import { useResourceContext } from '@/composables/useResourceContext';
+import { useInvoicesWorkspace } from './context';
+import type { CustomerDetail } from '@/types';
+
+const props = defineProps<{ customerId: number }>();
+
+const ctx = useInvoicesWorkspace();
+
+const { data: customer } = useResourceContext<CustomerDetail, number>(
+	() => props.customerId,
+	(id) => fetch(`/customers/${id}/peek`).then((res) => res.json())
+);
+
+const currency = new Intl.NumberFormat('en-US', {
+	style: 'currency',
+	currency: 'USD',
+});
+</script>
+```
+
+### RecordPaymentDialog.vue
+
+```vue
+<!-- InvoicesWorkspace/RecordPaymentDialog.vue -->
+<template>
+	<BbDialog
+		:model-value="invoice !== null"
+		size="sm"
+		:title="invoice ? `Record payment — ${invoice.number}` : ''"
+		@update:model-value="close"
+	>
+		<form
+			v-if="invoice"
+			class="flex flex-col gap-3"
+			novalidate
+			@submit.prevent="submit"
+		>
+			<BbNumberInput
+				v-model="draft.amount"
+				label="Amount"
+				label-mode="outside"
+				:max-precision="2"
+				:min="0"
+			>
+				<template #prefix>$</template>
+			</BbNumberInput>
+			<BbDatePickerInput
+				v-model="draft.paidAt"
+				label="Paid on"
+				label-mode="outside"
+			/>
+			<BbSelect
+				v-model="draft.method"
+				:items="['bank transfer', 'card', 'check', 'cash']"
+				label="Method"
+				label-mode="outside"
+			/>
+			<div class="mt-1 flex justify-end gap-2">
+				<BbButton type="button" variant="ghost" @click="close">Cancel</BbButton>
+				<BbButton type="submit" variant="secondary">Record payment</BbButton>
+			</div>
+		</form>
+	</BbDialog>
+</template>
+
+<script setup lang="ts">
+import { computed, reactive, watch } from 'vue';
+import {
+	BbButton,
+	BbDatePickerInput,
+	BbDialog,
+	BbNumberInput,
+	BbSelect,
+} from 'bitboss-ui';
+import { useInvoicesWorkspace } from './context';
+import type { PaymentDraft } from '@/types';
+
+const ctx = useInvoicesWorkspace();
+
+// The dialog's subject lives in the page context — any component on the
+// page (row actions, the peek) can open it by assigning the invoice.
+const invoice = computed(() => ctx.dialogs.recordPayment.value);
+const close = () => {
+	ctx.dialogs.recordPayment.value = null;
+};
+
+const draft = reactive<PaymentDraft>({
+	amount: null,
+	paidAt: null,
+	method: null,
+});
+watch(invoice, (next) => {
+	// Re-seed per invoice: default to paying the remaining balance today.
+	draft.amount = next?.amountDue ?? null;
+	draft.paidAt = next ? new Date().toISOString() : null;
+	draft.method = null;
+});
+
+// Returning the promise lets the submit button track the async work.
+const submit = () =>
+	invoice.value ? ctx.recordPayment(invoice.value, { ...draft }) : undefined;
+</script>
+```
+
+## Why it is built this way
+
+- **The context coopts, leaves consume.** `shell` and the keyed
+  `useTableContext('invoices')` are joined once in
+  `provideInvoicesWorkspace()`; nine components share filters, selection,
+  the peek stack and every action through one `useInvoicesWorkspace()`
+  call. No component on this page receives a callback prop, and only
+  peeks/cells receive data props (the item or id they render).
+- **`invoices` is a page prop, not a client fetch.** `useTableContext`
+  turns the Laravel paginator into `items`/`totalItems`/`page`/`perPage`
+  (URL-backed) plus `selected`/`unselected`/`all`; `BbTable` binds directly
+  to that handle with `v-model`/`v-model:select-all`/`v-model:unselected-items`
+  — there is no items function and no `dependencies` array, because the
+  server already did the filtering, sorting and paging before the props
+  arrived.
+- **One watcher for filters, one visit mechanism for tabs.**
+  `useQueryObject(filters, { only: ['invoices', 'tabCounts'] })` is the
+  entire filter-to-URL wiring; `BbTabs`' `href` + `server: true` items (with
+  the required component-level `navigation`) make tab switches real,
+  partial-reloaded visits with the same `only` list — one source of
+  server truth, reached two ways.
+- **The `visit()` helper is the promise-wrapped router-visit pattern** the
+  base's adaptation notes call for: it turns Inertia's
+  `onSuccess`/`onError` callbacks into a promise so every context action
+  (`updateStatus`, `duplicateInvoice`, the bulk actions, …) stays an
+  `async function` — identical call sites to the Vue/Nuxt recipes,
+  `await ctx.updateStatus(...)`.
+- **Bulk actions carry the full select-all-across-pages payload**
+  (`ids`/`all`/`unselected`) so "select all, deselect three, archive" sends
+  the same semantics the table itself models — never just an enumerated id
+  list that silently drops rows outside the current page.
+- **Peeks are JSON fetches, not visits.** `useResourceContext` re-fetches
+  on id change and exposes a `refresh()` the peek re-runs whenever
+  `ctx.refreshKey` bumps (every mutation bumps it) — opening or updating a
+  peek never re-renders the list page underneath it.
+- **`peekX` vs `stackX` is the whole stack grammar.** Fresh peeks replace,
+  drill-downs push; the shell renders the back arrow when depth > 1. The
+  grammar lives in the context — a leaf cannot accidentally nuke the
+  stack.
+- **Dialogs hang off the context** (`ctx.dialogs.recordPayment` holds the
+  subject invoice, not a boolean) so row actions and the peek open the
+  same dialog with zero coordination.
+- **Sizing:** topbar and rail follow `md`-first (`compact` inputs at 28px
+  flush beside the default buttons); `sm` appears exactly where the
+  doctrine allows — row actions, pills, peek footers, the bulk bar.
+- **One `variant="primary"`** (New invoice). Destructive actions —
+  single, bulk, in-peek — all ride `useConfirm`.
+- **The status badge tells you it saves.** `StatusCell` carries the §6.1
+  niceties: an internal trailing chevron (a clickable status must say so)
+  and `:loading` around the awaited context action, so the spinner takes
+  the chevron's place while the save runs. The flag is a local `ref` —
+  rung 1, not context state. The ownership grammar behind inline edits is
+  the [Inline Edit Playbook](../../guides/inline-edit-playbook.md).
+
+## Variations
+
+- **Keyboard triage**: add `keyboard-navigation` to the table and open the
+  peek from `v-model:highlighted` — the approvals-inbox recipe is the
+  full treatment.
+- **Saved views**: persist `filters` + `tab` per user in a store
+  (`useSavedViewsStore`) and render a view switcher before the tabs.
+- **Inline amount editing**: swap the amount cell for an
+  `EditableAmountCell` per the inline-editing pattern. Choosing between
+  explicit-commit cells and a fully autosaving grid is the
+  [Inline Edit Playbook](../../guides/inline-edit-playbook.md); the
+  autosave treatment is the inline-edit-workspace recipe.
+- **Lazy tab counts**: if `tabCounts` is expensive to compute, share it as
+  `Inertia::lazy()` and read it with `useLazyProp` instead of a plain
+  prop — the tab labels resolve once it lands instead of blocking the
+  first render.