bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/recipes/vue/record-form.md

@@ -0,0 +1,1540 @@
+---
+title: Record Form (Vue)
+summary: Full-anatomy invoice create/edit form for a vue-router SPA — sectioned fields with tied selects and 422 error mapping, inline-editing line-item rows, a dirty-snapshot route-leave guard, a sticky action row, and a customer peek sidebar, all through one coopting page context.
+---
+
+# Recipe: Record Form (Vue)
+
+The form archetype at full standard anatomy for a **plain Vue SPA with
+vue-router**: a Stripe-grade invoice create/edit page — sectioned fields with
+tied selects, server-side 422 error mapping onto every input (including
+line items), inline-editing line-item rows, a dirty-snapshot
+route-leave guard, a sticky action row, and a customer peek workbench, all
+through one coopting page context so every leaf component takes zero props
+beyond the record it renders.
+
+Sibling recipes: [Nuxt](../nuxt/record-form.md) ·
+[Inertia](../inertia/record-form.md). The listing this page belongs with is
+[Records Workspace (Vue)](./records-workspace.md).
+
+## Prerequisites
+
+- `<BbConfirm />` and `<BbToast />` mounted once in the app root.
+- `@/api` exposes `api.invoices.get/create/update/delete`,
+  `api.customers.list/byIds/getDetail` and `api.projects.list` — typed
+  async functions returning the shapes below; a 422 response rejects with
+  `{ status: 422, body: { errors } }`.
+
+## Key ideas
+
+- **One coopting page context.** `provideInvoiceForm()` joins the
+  page-shell stack once, owns the draft, the server errors, the dirty
+  snapshot and every action (including the route-leave guard). Every leaf
+  calls `useInvoiceForm()` and nothing else — cells, sections, the sticky
+  bar and the peek share state with zero prop drilling.
+- **The draft is the page's single mutable surface.** Inline cell edits,
+  the peek's "apply billing defaults", add/duplicate/remove line — all of
+  it mutates `ctx.draft`. The API boundary is exactly one call: the save,
+  whose 422 response maps back onto the same draft's fields.
+- **422 errors reach every input — including line-item rows.** Laravel-style
+  keys (`customerId`, `lineItems.2.unitPrice`) land in one `errors` map;
+  scalar fields bind `ctx.errors.value.<key>` and the editable cells
+  resolve their row key through `ctx.lineItemError(line, field)`.
+- **Tied selects are declarative.** Project depends on customer via
+  `dependencies` + `enforce-coherence`; switching customers refetches the
+  projects and clears a now-invalid pick automatically. No watchers.
+- **Line items are inline-editing rows (§6.3).** Each row is a
+  `LineItemCard` with labeled fields — quantity, unit price, a computed
+  amount readout, and a full-width description — one leaf per cell type,
+  swapping to an input on click, committing on blur (Enter too on the
+  number cells) and reverting on Esc.
+- **Dirty state is a JSON snapshot,** re-baselined before every navigation
+  the page itself causes (save redirect, delete redirect), so the
+  route-leave confirm only fires on genuinely abandoned edits.
+- **Clicking the customer's name peeks the customer** — a workbench, not a
+  preview: billing profile, stats, recent invoices, and an action that
+  writes the customer's defaults back into the draft.
+- **Buttons are `md` by default;** `sm` only in the line-item rows and
+  the peek. One `variant="primary"`: the save. No filter rail, no tabs, no
+  bulk bar — the form archetype has no list to filter and no selection.
+
+## Page anatomy
+
+```
+InvoiceForm/
+	Index.vue                   ← assembly: PageShell slots, header, <form>, sections
+	context.ts                  ← coopting page context (shell + draft + errors + actions + leave guard)
+	DetailsSection.vue          ← tied selects, dates, terms, PO, tax rate
+	LineItemsSection.vue        ← line-item rows + add line + live totals
+	LineItemCard.vue            ← one row: labeled inline-edit cells + duplicate/remove
+	EditableDescriptionCell.vue ← inline textarea edit (commit on blur, Esc reverts)
+	EditableQuantityCell.vue    ← inline quantity edit with outer stepper buttons
+	EditableRateCell.vue        ← inline unit-price edit, currency-formatted display
+	NotesSection.vue            ← BbCollapsible disclosure over notes + terms
+	FormActions.vue             ← sticky action row: delete / cancel / save draft / save
+	CustomerPeek.vue            ← sidebar workbench for the picked customer
+```
+
+Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
+(left nav + fat footer) and [Page Shell](../../guides/page-shell.md)
+(topbar / content / stacked sidebar). The floating bottom panel is
+deliberately absent — it is selection chrome, and a form has no selection.
+
+## Action inventory
+
+| #   | Action                          | Trigger                               | Mechanism                                              |
+| --- | ------------------------------- | ------------------------------------- | ------------------------------------------------------ |
+| 1   | Save invoice                    | sticky bar, the page's one `primary`  | `type="submit"` → `persist()` + 422 mapping + redirect |
+| 2   | Save as draft                   | sticky bar outline (create mode)      | `persist('draft')`, URL swaps to edit in place         |
+| 3   | Delete invoice                  | sticky bar destructive (edit mode)    | `useConfirm` → API → toast → redirect                  |
+| 4   | Cancel                          | sticky bar ghost                      | navigation (`to`); leave guard intercepts if dirty     |
+| 5   | Pick customer                   | details section select                | query-aware `items` provider                           |
+| 6   | Pick project                    | details section select                | `dependencies` + `enforce-coherence` (§ tied selects)  |
+| 7   | Peek customer                   | "View customer" link under the select | `ctx.peekCustomer()` → shell stack                     |
+| 8   | Apply billing defaults          | peek workbench button                 | writes terms + tax rate into the draft, toast          |
+| 9   | Edit description inline         | line-item cell                        | §6.3 with `BbTextarea`: commit on blur, Esc reverts    |
+| 10  | Edit quantity / rate inline     | line-item cells                       | §6.3 with `BbNumberInput` + outer stepper buttons      |
+| 11  | Add line item                   | section header + empty state          | `ctx.addLineItem()` pushes a blank draft row           |
+| 12  | Duplicate line                  | row actions                           | `ctx.duplicateLineItem(line)` inserts a copy below     |
+| 13  | Remove line                     | row actions                           | `ctx.removeLineItem(line)`                             |
+| 14  | Search line items               | topbar page search                    | `lineItemSearch` → `visibleLineItems` filter           |
+| 15  | Toggle notes & terms            | section disclosure button             | `BbCollapsible` + `aria-expanded`/`aria-controls`      |
+| 16  | Open customer / recent invoices | peek links                            | real `to` navigation (leave guard applies)             |
+
+## The code
+
+### The shapes
+
+What `@/types` contributes and what `api.invoices.get(2107)` returns — the
+record every block below is grounded in:
+
+```ts
+// @/types (excerpt)
+export type InvoiceStatus = 'draft' | 'pending' | 'paid' | 'overdue';
+
+export interface LineItemDraft {
+	/** Server id; unsaved rows carry a negative local id. */
+	id: number;
+	description: string;
+	quantity: number;
+	unitPrice: number;
+}
+
+export interface InvoiceDraft {
+	customerId: number | null;
+	projectId: number | null;
+	/** `YYYY-MM-DD` (the date inputs run with `floating`). */
+	issuedAt: string | null;
+	dueDate: string | null;
+	paymentTerms: string | null;
+	poNumber: string | null;
+	taxRate: number | null;
+	lineItems: LineItemDraft[];
+	notes: string | null;
+	terms: string | null;
+}
+```
+
+```ts
+// The invoice being edited (api.invoices.get(2107))
+{
+	id: 2107,
+	number: 'INV-2107',
+	status: 'draft',
+	customerId: 18, // Northwind Traders
+	projectId: 112, // Website relaunch
+	issuedAt: '2026-07-01',
+	dueDate: '2026-07-31',
+	paymentTerms: 'Net 30',
+	poNumber: 'PO-2026-0641',
+	taxRate: 8.875,
+	lineItems: [
+		{ id: 9001, description: 'Design sprint — homepage & navigation', quantity: 3, unitPrice: 1850 },
+		{ id: 9002, description: 'Frontend build — catalogue & product views', quantity: 5, unitPrice: 1200 },
+		{ id: 9003, description: 'CMS integration & content migration', quantity: 2, unitPrice: 1400 },
+		{ id: 9004, description: 'QA & cross-browser pass', quantity: 1, unitPrice: 950 },
+		{ id: 9005, description: 'Staging infrastructure (June)', quantity: 1, unitPrice: 240 },
+	],
+	notes: 'Second milestone of the relaunch engagement. Hosting billed at cost.',
+	terms: 'Payment due within 30 days. 1.5% monthly interest on overdue balances.',
+}
+```
+
+### context.ts
+
+```ts
+// InvoiceForm/context.ts
+import {
+	computed,
+	inject,
+	provide,
+	reactive,
+	ref,
+	type ComputedRef,
+	type InjectionKey,
+	type Ref,
+} from 'vue';
+import { onBeforeRouteLeave, useRoute, useRouter } from 'vue-router';
+import { useConfirm, useToast, type BadgeVariantType } from 'bitboss-ui';
+import {
+	usePageShellContext,
+	type PageShellContext,
+} from '@/components/layout/usePageShellContext';
+import { api } from '@/api';
+import type {
+	Customer,
+	CustomerDetail,
+	Invoice,
+	InvoiceDraft,
+	InvoiceStatus,
+	LineItemDraft,
+	Project,
+} from '@/types';
+
+/** What the stacked sidebar can show. Clicking the customer's name pushes one. */
+export type PeekItem = { type: 'customer'; id: number };
+
+// Status is a small closed set — the textbook case for the soft accents
+// (design-language.md § Using color; the `soft-*` variants are registered
+// app-side). A badge takes its color from the VARIANT map and its label from
+// the LABEL map; it never renders the raw enum. Used by the customer peek's
+// recent-invoice list.
+export const INVOICE_STATUS_LABEL: Record<InvoiceStatus, string> = {
+	draft: 'Draft',
+	pending: 'Pending',
+	paid: 'Paid',
+	overdue: 'Overdue',
+};
+export const INVOICE_STATUS_VARIANT: Record<InvoiceStatus, BadgeVariantType> = {
+	draft: 'soft-gray',
+	pending: 'soft-amber',
+	paid: 'soft-green',
+	overdue: 'soft-red',
+};
+
+type LineItemField = 'description' | 'quantity' | 'unitPrice';
+
+export interface InvoiceFormContext {
+	// -- Coopted contexts ------------------------------------------------------
+	shell: PageShellContext<PeekItem>;
+	// -- Page-owned state ------------------------------------------------------
+	mode: 'create' | 'edit';
+	loaded: Ref<boolean>;
+	invoiceNumber: Ref<string | null>;
+	status: Ref<InvoiceStatus>;
+	draft: InvoiceDraft;
+	/** Server 422 errors, keyed Laravel-style (`customerId`, `lineItems.2.unitPrice`). */
+	errors: Ref<Record<string, string[]>>;
+	saving: Ref<boolean>;
+	isDirty: ComputedRef<boolean>;
+	lineItemSearch: Ref<string>;
+	visibleLineItems: ComputedRef<LineItemDraft[]>;
+	subtotal: ComputedRef<number>;
+	taxAmount: ComputedRef<number>;
+	total: ComputedRef<number>;
+	// -- Item providers (handed straight to the selects) ------------------------
+	fetchCustomers: (query: string, prefill: boolean) => Promise<Customer[]>;
+	fetchProjects: () => Promise<Project[]>;
+	// -- Row-level error lookup --------------------------------------------------
+	lineItemError: (
+		line: LineItemDraft,
+		field: LineItemField
+	) => string[] | undefined;
+	// -- Draft mutations (the cells and the peek write through these) -----------
+	updateLineItem: (
+		line: LineItemDraft,
+		patch: Partial<Omit<LineItemDraft, 'id'>>
+	) => void;
+	addLineItem: () => void;
+	duplicateLineItem: (line: LineItemDraft) => void;
+	removeLineItem: (line: LineItemDraft) => void;
+	applyCustomerDefaults: (customer: CustomerDetail) => void;
+	// -- Peek grammar ------------------------------------------------------------
+	peekCustomer: () => void;
+	// -- Actions (complete: API + 422 mapping + toast + redirect) ----------------
+	saveInvoice: () => Promise<void>;
+	saveAsDraft: () => Promise<void>;
+	deleteInvoice: () => Promise<void>;
+}
+
+const key: InjectionKey<InvoiceFormContext> = Symbol('invoice-form');
+
+export function provideInvoiceForm(): InvoiceFormContext {
+	const route = useRoute();
+	const router = useRouter();
+	const { toast } = useToast();
+	const { confirm } = useConfirm();
+
+	// -- Coopt the shell: once, here, for the whole page. ------------------------
+	const shell = usePageShellContext<PeekItem>();
+
+	// /invoices/create has no id; /invoices/:id/edit does.
+	//
+	// NOT `const`: both routes render THIS component, so the create→edit
+	// `router.replace` in `saveAsDraft` patches the existing instance rather than
+	// remounting it — setup never runs again. Promote them by hand there, or
+	// `mode` stays 'create' forever and a second "Save as draft" creates a
+	// SECOND invoice.
+	let invoiceId = route.params.id ? Number(route.params.id) : null;
+	let mode: 'create' | 'edit' = invoiceId === null ? 'create' : 'edit';
+
+	// -- The draft ---------------------------------------------------------------
+	// Unsaved rows get negative local ids so `item-value` stays stable and the
+	// payload can tell the server which lines are new (negative → null).
+	let nextLocalId = -1;
+	const blankLineItem = (): LineItemDraft => ({
+		id: nextLocalId--,
+		description: '',
+		quantity: 1,
+		unitPrice: 0,
+	});
+
+	const draft = reactive<InvoiceDraft>({
+		customerId: null,
+		projectId: null,
+		issuedAt: null,
+		dueDate: null,
+		paymentTerms: null,
+		poNumber: null,
+		taxRate: null,
+		lineItems: [blankLineItem()],
+		notes: null,
+		terms: null,
+	});
+
+	const loaded = ref(mode === 'create');
+	const invoiceNumber = ref<string | null>(null);
+	const status = ref<InvoiceStatus>('draft');
+	const errors = ref<Record<string, string[]>>({});
+	const saving = ref(false);
+
+	// Dirty = the draft's JSON diverged from the last committed snapshot.
+	// Gated on `loaded` so the async seed of edit mode never reads as dirty.
+	const snapshot = ref(JSON.stringify(draft));
+	const isDirty = computed(
+		() => loaded.value && JSON.stringify(draft) !== snapshot.value
+	);
+
+	if (mode === 'edit' && invoiceId !== null) {
+		api.invoices.get(invoiceId).then((invoice: Invoice) => {
+			invoiceNumber.value = invoice.number;
+			status.value = invoice.status;
+			draft.customerId = invoice.customerId;
+			draft.projectId = invoice.projectId;
+			draft.issuedAt = invoice.issuedAt;
+			draft.dueDate = invoice.dueDate;
+			draft.paymentTerms = invoice.paymentTerms;
+			draft.poNumber = invoice.poNumber;
+			draft.taxRate = invoice.taxRate;
+			draft.lineItems = invoice.lineItems.map((line) => ({ ...line }));
+			draft.notes = invoice.notes;
+			draft.terms = invoice.terms;
+			snapshot.value = JSON.stringify(draft);
+			loaded.value = true;
+		});
+	}
+
+	// -- Item providers -----------------------------------------------------------
+	// Component-initiated calls (`prefill === true`) must keep the current
+	// selection resolvable, or the chip loses its text.
+	const fetchCustomers = async (
+		query: string,
+		prefill: boolean
+	): Promise<Customer[]> => {
+		if (prefill && draft.customerId !== null) {
+			return api.customers.byIds([draft.customerId]);
+		}
+		return api.customers.list({ search: query });
+	};
+
+	// Re-run by the project select's `dependencies: [draft.customerId]`; the
+	// response always contains the customer's full project list, so an existing
+	// `projectId` stays resolvable and `enforce-coherence` never wipes a valid pick.
+	const fetchProjects = (): Promise<Project[]> =>
+		draft.customerId === null
+			? Promise.resolve([])
+			: api.projects.list({ customer: draft.customerId });
+
+	// -- Line items -----------------------------------------------------------------
+	const lineItemSearch = ref('');
+	const visibleLineItems = computed(() => {
+		// A `clearable` BbTextInput emits **null** when it is emptied, not `''` —
+		// so coalesce before calling a string method, or the first clear throws
+		// `Cannot read properties of null (reading 'trim')` and the section stops
+		// re-rendering.
+		const query = (lineItemSearch.value ?? '').trim().toLowerCase();
+		if (!query) return draft.lineItems;
+		return draft.lineItems.filter((line) =>
+			line.description.toLowerCase().includes(query)
+		);
+	});
+
+	const subtotal = computed(() =>
+		draft.lineItems.reduce(
+			(sum, line) => sum + line.quantity * line.unitPrice,
+			0
+		)
+	);
+	const taxAmount = computed(
+		() => subtotal.value * ((draft.taxRate ?? 0) / 100)
+	);
+	const total = computed(() => subtotal.value + taxAmount.value);
+
+	// Server 422 keys index lines by payload position, which is draft order —
+	// resolve a row's key through its id so the lookup survives filtering.
+	const lineItemError = (
+		line: LineItemDraft,
+		field: LineItemField
+	): string[] | undefined => {
+		const index = draft.lineItems.findIndex(
+			(candidate) => candidate.id === line.id
+		);
+		return errors.value[`lineItems.${index}.${field}`];
+	};
+
+	const updateLineItem = (
+		line: LineItemDraft,
+		patch: Partial<Omit<LineItemDraft, 'id'>>
+	) => {
+		const target = draft.lineItems.find(
+			(candidate) => candidate.id === line.id
+		);
+		if (target) Object.assign(target, patch);
+	};
+	const addLineItem = () => {
+		draft.lineItems.push(blankLineItem());
+	};
+	const duplicateLineItem = (line: LineItemDraft) => {
+		const index = draft.lineItems.findIndex(
+			(candidate) => candidate.id === line.id
+		);
+		draft.lineItems.splice(index + 1, 0, { ...line, id: nextLocalId-- });
+	};
+	const removeLineItem = (line: LineItemDraft) => {
+		draft.lineItems = draft.lineItems.filter(
+			(candidate) => candidate.id !== line.id
+		);
+	};
+
+	// The peek writes back into the draft: the sidebar is a workbench.
+	const applyCustomerDefaults = (customer: CustomerDetail) => {
+		draft.paymentTerms = customer.defaultPaymentTerms;
+		draft.taxRate = customer.defaultTaxRate;
+		toast({
+			title: `Applied ${customer.name}'s billing defaults.`,
+			variant: 'success',
+		});
+	};
+
+	// -- Peek grammar ----------------------------------------------------------------
+	const peekCustomer = () => {
+		if (draft.customerId === null) return;
+		shell.push({ type: 'customer', id: draft.customerId }, true);
+	};
+
+	// -- Persistence -----------------------------------------------------------------
+	// New lines travel with `id: null`; the server assigns real ids on save.
+	const payload = (nextStatus: InvoiceStatus) => ({
+		...draft,
+		status: nextStatus,
+		lineItems: draft.lineItems.map((line) => ({
+			...line,
+			id: line.id > 0 ? line.id : null,
+		})),
+	});
+
+	const persist = async (
+		nextStatus: InvoiceStatus
+	): Promise<Invoice | null> => {
+		saving.value = true;
+		errors.value = {};
+		try {
+			const saved =
+				mode === 'edit' && invoiceId !== null
+					? await api.invoices.update(invoiceId, payload(nextStatus))
+					: await api.invoices.create(payload(nextStatus));
+			// Re-baseline BEFORE navigating so the leave guard lets the redirect through.
+			snapshot.value = JSON.stringify(draft);
+			status.value = saved.status;
+			invoiceNumber.value = saved.number;
+			return saved;
+		} catch (error: unknown) {
+			const err = error as {
+				status?: number;
+				body?: { errors?: Record<string, string[]> };
+			};
+			if (err.status === 422) {
+				// Laravel-style: { errors: { 'lineItems.2.unitPrice': ['Must be positive.'] } }
+				errors.value = err.body?.errors ?? {};
+				toast({ title: 'Some fields need attention.', variant: 'destructive' });
+			} else {
+				toast({
+					title: 'Something went wrong. Try again.',
+					variant: 'destructive',
+				});
+			}
+			return null;
+		} finally {
+			saving.value = false;
+		}
+	};
+
+	const saveInvoice = async () => {
+		// Creating finalizes the invoice; editing keeps whatever status it has.
+		const saved = await persist(mode === 'edit' ? status.value : 'pending');
+		if (!saved) return;
+		toast({ title: `Invoice ${saved.number} saved.`, variant: 'success' });
+		router.push(`/invoices/${saved.id}`);
+	};
+
+	const saveAsDraft = async () => {
+		const saved = await persist('draft');
+		if (!saved) return;
+		toast({ title: `Draft ${saved.number} saved.`, variant: 'success' });
+		// Stay on the page; swap the URL so a refresh lands in edit mode. The
+		// component is patched, not remounted, so promote this instance too.
+		if (mode === 'create') {
+			await router.replace(`/invoices/${saved.id}/edit`);
+			invoiceId = saved.id;
+			mode = 'edit';
+		}
+	};
+
+	const deleteInvoice = async () => {
+		if (mode !== 'edit' || invoiceId === null) return;
+		const ok = await confirm({
+			variant: 'destructive',
+			title: 'Delete invoice',
+			text: `Delete ${invoiceNumber.value}? This cannot be undone.`,
+			yes: 'Delete',
+			no: 'Cancel',
+		});
+		if (!ok) return;
+		await api.invoices.delete(invoiceId);
+		// Re-baseline so the guard doesn't ask about a record that no longer exists.
+		snapshot.value = JSON.stringify(draft);
+		toast({ title: `${invoiceNumber.value} deleted.`, variant: 'success' });
+		router.push('/invoices');
+	};
+
+	// -- Route-leave guard ---------------------------------------------------------
+	// Lives with the state it protects. `onBeforeRouteLeave` registers against
+	// the page component because provideInvoiceForm() runs in its setup.
+	onBeforeRouteLeave(async () => {
+		if (!isDirty.value) return true;
+		return await confirm({
+			variant: 'destructive',
+			title: 'Unsaved changes',
+			text: 'You have unsaved changes on this invoice. Leave without saving?',
+			yes: 'Discard changes',
+			no: 'Keep editing',
+		});
+	});
+
+	const ctx: InvoiceFormContext = {
+		shell,
+		mode,
+		loaded,
+		invoiceNumber,
+		status,
+		draft,
+		errors,
+		saving,
+		isDirty,
+		lineItemSearch,
+		visibleLineItems,
+		subtotal,
+		taxAmount,
+		total,
+		fetchCustomers,
+		fetchProjects,
+		lineItemError,
+		updateLineItem,
+		addLineItem,
+		duplicateLineItem,
+		removeLineItem,
+		applyCustomerDefaults,
+		peekCustomer,
+		saveInvoice,
+		saveAsDraft,
+		deleteInvoice,
+	};
+	provide(key, ctx);
+	return ctx;
+}
+
+export function useInvoiceForm(): InvoiceFormContext {
+	const ctx = inject(key);
+	if (!ctx) throw new Error('useInvoiceForm() called outside InvoiceForm');
+	return ctx;
+}
+```
+
+### Index.vue — the assembly
+
+```vue
+<!-- InvoiceForm/Index.vue -->
+<template>
+	<PageShell>
+		<!-- Topbar: breadcrumbs left, page search right. The search scopes the
+		     work surface — here, the line items. -->
+		<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="trail" />
+				<BbTextInput
+					v-model="ctx.lineItemSearch.value"
+					class="shrink-0"
+					clearable
+					compact
+					hide-label
+					label="Search line items"
+					placeholder="Search line items…"
+					prepend:icon="lucide:search"
+				/>
+			</div>
+		</template>
+
+		<div
+			v-if="ctx.loaded.value"
+			class="mx-auto flex w-full max-w-4xl flex-col gap-6 p-4"
+		>
+			<header class="flex items-center gap-3">
+				<h1 class="text-lg font-semibold">
+					{{
+						ctx.mode === 'edit'
+							? `Edit ${ctx.invoiceNumber.value}`
+							: 'New invoice'
+					}}
+				</h1>
+				<BbBadge v-if="ctx.mode === 'edit'" variant="outline">{{
+					ctx.status.value
+				}}</BbBadge>
+			</header>
+
+			<!-- One form, one submit. `novalidate` keeps error UX on the inputs'
+			     `errors` surface instead of browser bubbles; `autocomplete="off"`
+			     (echoed on every field) keeps browser autofill off the draft. -->
+			<form
+				autocomplete="off"
+				class="flex flex-col gap-6"
+				novalidate
+				@submit.prevent="ctx.saveInvoice"
+			>
+				<DetailsSection />
+				<LineItemsSection />
+				<NotesSection />
+				<FormActions />
+			</form>
+		</div>
+
+		<div v-else class="flex justify-center p-12">
+			<BbSpinner label="Loading invoice…" />
+		</div>
+
+		<!-- Stacked peek sidebar: the shell owns back/close; we render by type. -->
+		<template #sidebar>
+			<CustomerPeek
+				v-if="ctx.shell.current.value?.type === 'customer'"
+				:customer-id="ctx.shell.current.value.id"
+			/>
+		</template>
+	</PageShell>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbBadge, BbBreadcrumbs, BbSpinner, BbTextInput } from 'bitboss-ui';
+import PageShell from '@/components/layout/PageShell.vue';
+import { provideInvoiceForm } from './context';
+import CustomerPeek from './CustomerPeek.vue';
+import DetailsSection from './DetailsSection.vue';
+import FormActions from './FormActions.vue';
+import LineItemsSection from './LineItemsSection.vue';
+import NotesSection from './NotesSection.vue';
+
+const ctx = provideInvoiceForm();
+
+// A real trail, ≥ 2 linked levels; the current page carries no target.
+const trail = computed(() => [
+	{ key: 'dashboard', text: 'Dashboard', to: '/dashboard' },
+	{ key: 'billing', text: 'Billing', to: '/billing' },
+	{ key: 'invoices', text: 'Invoices', to: '/invoices' },
+	{
+		key: 'invoice',
+		text:
+			ctx.mode === 'edit'
+				? (ctx.invoiceNumber.value ?? 'Invoice')
+				: 'New invoice',
+	},
+]);
+</script>
+```
+
+### DetailsSection.vue
+
+```vue
+<!-- InvoiceForm/DetailsSection.vue -->
+<template>
+	<section class="flex flex-col gap-3">
+		<h2 class="text-xs font-semibold uppercase tracking-wide text-gray-500">
+			Details
+		</h2>
+
+		<div class="grid gap-4 sm:grid-cols-2">
+			<!-- Tied selects: project depends on customer. `dependencies` re-runs
+			     the project provider; `enforce-coherence` clears a project that is
+			     no longer among the new options. No watchers. -->
+			<div class="flex flex-col gap-1">
+				<BbSelect
+					v-model="ctx.draft.customerId"
+					autocomplete="off"
+					:errors="ctx.errors.value.customerId"
+					item-text="name"
+					item-value="id"
+					:items="ctx.fetchCustomers"
+					label="Customer"
+					placeholder="Search customers…"
+				/>
+				<!-- Clicking the NAME of a thing peeks it. -->
+				<BbButton
+					v-if="ctx.draft.customerId !== null"
+					append:icon="lucide:panel-right-open"
+					class="self-start"
+					size="sm"
+					variant="link"
+					@click="ctx.peekCustomer"
+				>
+					View customer
+				</BbButton>
+			</div>
+
+			<BbSelect
+				v-model="ctx.draft.projectId"
+				autocomplete="off"
+				:dependencies="[ctx.draft.customerId]"
+				:disabled="ctx.draft.customerId === null"
+				enforce-coherence
+				:errors="ctx.errors.value.projectId"
+				item-text="name"
+				item-value="id"
+				:items="ctx.fetchProjects"
+				label="Project"
+				placeholder="Pick the customer first"
+			/>
+
+			<!-- `floating` keeps the model a plain YYYY-MM-DD string, so the due
+			     date's `min` can be fed straight from the issue date. -->
+			<BbDatePickerInput
+				v-model="ctx.draft.issuedAt"
+				autocomplete="off"
+				:errors="ctx.errors.value.issuedAt"
+				floating
+				label="Issue date"
+				prepend:icon="lucide:calendar"
+			/>
+			<BbDatePickerInput
+				v-model="ctx.draft.dueDate"
+				autocomplete="off"
+				:errors="ctx.errors.value.dueDate"
+				floating
+				label="Due date"
+				:min="ctx.draft.issuedAt ?? undefined"
+				prepend:icon="lucide:calendar"
+			/>
+
+			<BbSelect
+				v-model="ctx.draft.paymentTerms"
+				autocomplete="off"
+				:errors="ctx.errors.value.paymentTerms"
+				:items="['Due on receipt', 'Net 15', 'Net 30', 'Net 60']"
+				label="Payment terms"
+				placeholder="Choose terms"
+			/>
+
+			<BbTextInput
+				v-model="ctx.draft.poNumber"
+				autocomplete="off"
+				:errors="ctx.errors.value.poNumber"
+				label="PO / reference"
+				placeholder="PO-2026-0641"
+			/>
+
+			<BbNumberInput
+				v-model="ctx.draft.taxRate"
+				autocomplete="off"
+				:errors="ctx.errors.value.taxRate"
+				hint="Applied to the subtotal below."
+				label="Tax rate"
+				:max="100"
+				:max-precision="3"
+				:min="0"
+			>
+				<template #suffix>%</template>
+			</BbNumberInput>
+		</div>
+	</section>
+</template>
+
+<script setup lang="ts">
+import {
+	BbButton,
+	BbDatePickerInput,
+	BbNumberInput,
+	BbSelect,
+	BbTextInput,
+} from 'bitboss-ui';
+import { useInvoiceForm } from './context';
+
+const ctx = useInvoiceForm();
+</script>
+```
+
+### LineItemsSection.vue
+
+```vue
+<!-- InvoiceForm/LineItemsSection.vue -->
+<template>
+	<section class="flex flex-col gap-3">
+		<div class="flex items-center justify-between">
+			<h2 class="text-xs font-semibold uppercase tracking-wide text-gray-500">
+				Line items
+			</h2>
+			<BbButton
+				prepend:icon="lucide:plus"
+				variant="outline"
+				@click="ctx.addLineItem"
+			>
+				Add line item
+			</BbButton>
+		</div>
+
+		<!-- One bordered panel whose rows are divided by hairlines — not a
+		     BbTable (no selection, paging or fetch) and not a stack of floating
+		     cards. Each row keeps the same §6.3 inline-edit cells per field. -->
+		<div
+			v-if="ctx.visibleLineItems.value.length"
+			class="flex flex-col rounded-[var(--bb-radius)] border"
+		>
+			<LineItemCard
+				v-for="line in ctx.visibleLineItems.value"
+				:key="line.id"
+				:line="line"
+			/>
+		</div>
+
+		<!-- Soft empty band — a wash, not a dashed outline. -->
+		<div
+			v-else
+			class="flex flex-col items-center gap-2 rounded-[var(--bb-radius)] bg-gray-50 p-6 text-center dark:bg-gray-900"
+		>
+			<p class="text-sm text-gray-500">
+				{{
+					ctx.lineItemSearch.value
+						? 'No line items match your search.'
+						: 'No line items yet.'
+				}}
+			</p>
+			<BbButton
+				v-if="!ctx.lineItemSearch.value"
+				variant="outline"
+				@click="ctx.addLineItem"
+			>
+				Add the first line
+			</BbButton>
+		</div>
+
+		<!-- Totals: live computed from the draft — they move as cells commit. -->
+		<dl class="ml-auto grid w-60 grid-cols-[1fr_auto] gap-y-1 text-sm">
+			<dt class="text-gray-500">Subtotal</dt>
+			<dd class="text-right tabular-nums">
+				{{ currency.format(ctx.subtotal.value) }}
+			</dd>
+			<dt class="text-gray-500">Tax ({{ ctx.draft.taxRate ?? 0 }}%)</dt>
+			<dd class="text-right tabular-nums">
+				{{ currency.format(ctx.taxAmount.value) }}
+			</dd>
+			<dt class="font-semibold">Total</dt>
+			<dd class="text-right font-semibold tabular-nums">
+				{{ currency.format(ctx.total.value) }}
+			</dd>
+		</dl>
+	</section>
+</template>
+
+<script setup lang="ts">
+import { BbButton } from 'bitboss-ui';
+import LineItemCard from './LineItemCard.vue';
+import { useInvoiceForm } from './context';
+
+const ctx = useInvoiceForm();
+
+const currency = new Intl.NumberFormat('en-US', {
+	style: 'currency',
+	currency: 'USD',
+});
+</script>
+```
+
+### LineItemCard.vue
+
+```vue
+<!-- InvoiceForm/LineItemCard.vue -->
+<template>
+	<article class="flex flex-col gap-3 border-b p-3 last:border-b-0">
+		<div class="flex items-end gap-3">
+			<div class="grid min-w-0 flex-1 grid-cols-3 gap-3">
+				<div>
+					<p
+						class="mb-1 text-right text-xs font-semibold uppercase tracking-wide text-gray-500"
+					>
+						Qty
+					</p>
+					<EditableQuantityCell :line="line" />
+				</div>
+				<div>
+					<p
+						class="mb-1 text-right text-xs font-semibold uppercase tracking-wide text-gray-500"
+					>
+						Unit price
+					</p>
+					<EditableRateCell :line="line" />
+				</div>
+				<div>
+					<p
+						class="mb-1 text-right text-xs font-semibold uppercase tracking-wide text-gray-500"
+					>
+						Amount
+					</p>
+					<!-- Virtual field: computed from the row, never edited. -->
+					<p class="px-1 py-0.5 text-right tabular-nums">
+						{{ currency.format(line.quantity * line.unitPrice) }}
+					</p>
+				</div>
+			</div>
+
+			<div class="flex shrink-0 items-center gap-1">
+				<BbButton
+					icon="lucide:copy"
+					size="sm"
+					variant="ghost"
+					@click="() => ctx.duplicateLineItem(line)"
+				>
+					Duplicate line
+				</BbButton>
+				<BbButton
+					icon="lucide:trash-2"
+					size="sm"
+					variant="ghost"
+					@click="() => ctx.removeLineItem(line)"
+				>
+					Remove line
+				</BbButton>
+			</div>
+		</div>
+
+		<div>
+			<p
+				class="mb-1 text-xs font-semibold uppercase tracking-wide text-gray-500"
+			>
+				Description
+			</p>
+			<EditableDescriptionCell :line="line" />
+		</div>
+	</article>
+</template>
+
+<script setup lang="ts">
+import { BbButton } from 'bitboss-ui';
+import EditableDescriptionCell from './EditableDescriptionCell.vue';
+import EditableQuantityCell from './EditableQuantityCell.vue';
+import EditableRateCell from './EditableRateCell.vue';
+import { useInvoiceForm } from './context';
+import type { LineItemDraft } from '@/types';
+
+defineProps<{ line: LineItemDraft }>();
+
+const ctx = useInvoiceForm();
+
+const currency = new Intl.NumberFormat('en-US', {
+	style: 'currency',
+	currency: 'USD',
+});
+</script>
+```
+
+### EditableDescriptionCell.vue
+
+```vue
+<!-- InvoiceForm/EditableDescriptionCell.vue -->
+<template>
+	<BbTextarea
+		v-if="editing"
+		ref="inputRef"
+		v-model="value"
+		auto-grow
+		compact
+		:errors="ctx.lineItemError(line, 'description')"
+		hide-label
+		label="Line description"
+		placeholder="What was delivered?"
+		:rows="2"
+		@blur="commit"
+		@keydown.esc="revert"
+	/>
+	<button
+		v-else
+		class="w-full whitespace-pre-wrap rounded-[var(--bb-radius)] px-1 py-0.5 text-left hover:bg-gray-100 dark:hover:bg-gray-800"
+		:class="{
+			'text-[color:var(--bb-text-muted)]': !line.description,
+			'text-[color:var(--bb-danger)]': hasError,
+		}"
+		type="button"
+		@click="start"
+	>
+		{{ line.description || 'Add a description…' }}
+	</button>
+</template>
+
+<script setup lang="ts">
+import { computed, nextTick, ref } from 'vue';
+import { BbTextarea } from 'bitboss-ui';
+import { useInvoiceForm } from './context';
+import type { LineItemDraft } from '@/types';
+
+const props = defineProps<{ line: LineItemDraft }>();
+
+const ctx = useInvoiceForm();
+
+// Rung 1 of the ladder: only this cell reads or writes its editing state.
+const editing = ref(false);
+const value = ref<string | null>(null);
+const inputRef = ref<{ $el?: HTMLElement } | null>(null);
+
+const hasError = computed(() => !!ctx.lineItemError(props.line, 'description'));
+
+/** Focus the native textarea after the editor mounts — HTML `autofocus` only
+ *  runs on page load, not on later mounts. */
+const focusInput = async () => {
+	await nextTick();
+	inputRef.value?.$el?.querySelector('textarea')?.focus();
+};
+
+const start = () => {
+	value.value = props.line.description;
+	editing.value = true;
+	void focusInput();
+};
+
+// Commit on blur, revert on Esc (§6.3). Enter inserts a newline (textarea),
+// so it is not wired to commit the way a single-line input would be; the
+// `editing` guard keeps the blur that follows an Esc from re-committing.
+const commit = () => {
+	if (!editing.value) return;
+	editing.value = false;
+	ctx.updateLineItem(props.line, { description: value.value ?? '' });
+};
+
+const revert = () => {
+	editing.value = false;
+};
+</script>
+```
+
+### EditableQuantityCell.vue
+
+```vue
+<!-- InvoiceForm/EditableQuantityCell.vue -->
+<template>
+	<BbNumberInput
+		v-if="editing"
+		ref="inputRef"
+		v-model="value"
+		class="[&_input]:text-right"
+		compact
+		:errors="ctx.lineItemError(line, 'quantity')"
+		hide-label
+		label="Quantity"
+		:max-precision="2"
+		:min="0"
+		@blur="commit"
+		@keydown.enter.prevent="commit"
+		@keydown.esc="revert"
+	>
+		<!-- Outer steppers: mousedown.prevent keeps focus in the field so blur
+		     doesn't commit/unmount before the click lands. -->
+		<template #prepend-outer="{ decrease }">
+			<BbButton
+				aria-label="Decrease quantity"
+				icon="lucide:minus"
+				size="xs"
+				variant="ghost"
+				@click="decrease"
+				@mousedown.prevent
+			/>
+		</template>
+		<template #append-outer="{ increase }">
+			<BbButton
+				aria-label="Increase quantity"
+				icon="lucide:plus"
+				size="xs"
+				variant="ghost"
+				@click="increase"
+				@mousedown.prevent
+			/>
+		</template>
+	</BbNumberInput>
+	<button
+		v-else
+		class="w-full rounded-[var(--bb-radius)] px-1 py-0.5 text-right tabular-nums hover:bg-gray-100 dark:hover:bg-gray-800"
+		:class="{ 'text-[color:var(--bb-danger)]': hasError }"
+		type="button"
+		@click="start"
+	>
+		{{ line.quantity }}
+	</button>
+</template>
+
+<script setup lang="ts">
+import { computed, nextTick, ref } from 'vue';
+import { BbButton, BbNumberInput } from 'bitboss-ui';
+import { useInvoiceForm } from './context';
+import type { LineItemDraft } from '@/types';
+
+const props = defineProps<{ line: LineItemDraft }>();
+
+const ctx = useInvoiceForm();
+
+const editing = ref(false);
+const value = ref<number | null>(null);
+const inputRef = ref<{ $el?: HTMLElement } | null>(null);
+
+const hasError = computed(() => !!ctx.lineItemError(props.line, 'quantity'));
+
+/** Focus the native input after the editor mounts — HTML `autofocus` only
+ *  runs on page load, not on later mounts. */
+const focusInput = async () => {
+	await nextTick();
+	inputRef.value?.$el?.querySelector('input')?.focus();
+};
+
+const start = () => {
+	value.value = props.line.quantity;
+	editing.value = true;
+	void focusInput();
+};
+
+const commit = () => {
+	if (!editing.value) return;
+	editing.value = false;
+	// An emptied field emits null — treat it as a revert, not a zero.
+	if (value.value === null) return;
+	ctx.updateLineItem(props.line, { quantity: value.value });
+};
+
+const revert = () => {
+	editing.value = false;
+};
+</script>
+```
+
+### EditableRateCell.vue
+
+```vue
+<!-- InvoiceForm/EditableRateCell.vue -->
+<template>
+	<BbNumberInput
+		v-if="editing"
+		ref="inputRef"
+		v-model="value"
+		class="[&_input]:text-right"
+		compact
+		:errors="ctx.lineItemError(line, 'unitPrice')"
+		hide-label
+		label="Unit price"
+		:max-precision="2"
+		:min="0"
+		@blur="commit"
+		@keydown.enter.prevent="commit"
+		@keydown.esc="revert"
+	>
+		<template #prefix>$</template>
+	</BbNumberInput>
+	<button
+		v-else
+		class="w-full rounded-[var(--bb-radius)] px-1 py-0.5 text-right tabular-nums hover:bg-gray-100 dark:hover:bg-gray-800"
+		:class="{ 'text-[color:var(--bb-danger)]': hasError }"
+		type="button"
+		@click="start"
+	>
+		{{ currency.format(line.unitPrice) }}
+	</button>
+</template>
+
+<script setup lang="ts">
+import { computed, nextTick, ref } from 'vue';
+import { BbNumberInput } from 'bitboss-ui';
+import { useInvoiceForm } from './context';
+import type { LineItemDraft } from '@/types';
+
+const props = defineProps<{ line: LineItemDraft }>();
+
+const ctx = useInvoiceForm();
+
+const editing = ref(false);
+const value = ref<number | null>(null);
+const inputRef = ref<{ $el?: HTMLElement } | null>(null);
+
+const hasError = computed(() => !!ctx.lineItemError(props.line, 'unitPrice'));
+
+const currency = new Intl.NumberFormat('en-US', {
+	style: 'currency',
+	currency: 'USD',
+});
+
+/** Focus the native input after the editor mounts — HTML `autofocus` only
+ *  runs on page load, not on later mounts. */
+const focusInput = async () => {
+	await nextTick();
+	inputRef.value?.$el?.querySelector('input')?.focus();
+};
+
+const start = () => {
+	value.value = props.line.unitPrice;
+	editing.value = true;
+	void focusInput();
+};
+
+const commit = () => {
+	if (!editing.value) return;
+	editing.value = false;
+	if (value.value === null) return;
+	ctx.updateLineItem(props.line, { unitPrice: value.value });
+};
+
+const revert = () => {
+	editing.value = false;
+};
+</script>
+```
+
+### NotesSection.vue
+
+```vue
+<!-- InvoiceForm/NotesSection.vue -->
+<template>
+	<section class="flex flex-col gap-2">
+		<!-- BbCollapsible ships no trigger: this button owns the disclosure
+		     ARIA (`aria-expanded` + `aria-controls`). -->
+		<BbButton
+			append:icon="lucide:chevron-down"
+			aria-controls="invoice-notes"
+			:aria-expanded="open"
+			class="self-start"
+			variant="ghost"
+			@click="open = !open"
+		>
+			Notes &amp; terms
+		</BbButton>
+
+		<!-- `eager` mounts the fields up front so their 422 errors render even
+		     if the user never opened the section. Spacing lives on the inner
+		     content — the collapsible zeroes its own box when closed. -->
+		<BbCollapsible id="invoice-notes" v-model="open" eager>
+			<div class="flex flex-col gap-4 pt-1">
+				<BbTextarea
+					v-model="ctx.draft.notes"
+					auto-grow
+					description="Shown on the invoice, under the line items."
+					:errors="ctx.errors.value.notes"
+					label="Notes to the customer"
+					placeholder="Second milestone of the relaunch engagement…"
+					:rows="2"
+				/>
+				<BbTextarea
+					v-model="ctx.draft.terms"
+					auto-grow
+					description="Payment terms printed in the invoice footer."
+					:errors="ctx.errors.value.terms"
+					label="Terms"
+					placeholder="Payment due within 30 days…"
+					:rows="2"
+				/>
+			</div>
+		</BbCollapsible>
+	</section>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbCollapsible, BbTextarea } from 'bitboss-ui';
+import { useInvoiceForm } from './context';
+
+const ctx = useInvoiceForm();
+
+// Rung 1: only this section cares whether it is open. The section mounts
+// after the invoice loaded (Index gates on ctx.loaded), so seeding from the
+// draft starts an annotated invoice open and a blank one closed.
+const open = ref(ctx.draft.notes !== null || ctx.draft.terms !== null);
+</script>
+```
+
+### FormActions.vue
+
+```vue
+<!-- InvoiceForm/FormActions.vue -->
+<template>
+	<!-- Sticky action row: the commit affordance never scrolls away. Not the
+	     floating bottom panel — that is selection chrome, and a form has no
+	     selection. -->
+	<div
+		class="sticky bottom-0 z-10 -mx-4 flex items-center gap-3 border-t bg-[color:var(--bb-panel)] px-4 py-3"
+	>
+		<BbButton
+			v-if="ctx.mode === 'edit'"
+			prepend:icon="lucide:trash-2"
+			variant="destructive"
+			@click="ctx.deleteInvoice"
+		>
+			Delete
+		</BbButton>
+		<p v-if="ctx.isDirty.value" class="text-xs text-gray-500">
+			Unsaved changes
+		</p>
+
+		<div class="ml-auto flex items-center gap-2">
+			<!-- Cancel is navigation: the route-leave guard asks about a dirty
+			     draft, so no bespoke confirm here. -->
+			<BbButton :disabled="ctx.saving.value" to="/invoices" variant="ghost">
+				Cancel
+			</BbButton>
+			<BbButton
+				v-if="ctx.mode === 'create'"
+				:disabled="ctx.saving.value"
+				variant="outline"
+				@click="ctx.saveAsDraft"
+			>
+				Save as draft
+			</BbButton>
+			<BbButton :loading="ctx.saving.value" type="submit" variant="primary">
+				{{ ctx.mode === 'edit' ? 'Save changes' : 'Create invoice' }}
+			</BbButton>
+		</div>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbButton } from 'bitboss-ui';
+import { useInvoiceForm } from './context';
+
+const ctx = useInvoiceForm();
+</script>
+```
+
+### CustomerPeek.vue
+
+```vue
+<!-- InvoiceForm/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>
+
+		<!-- Billing profile: exactly the fields this form negotiates. -->
+		<section class="flex flex-col gap-1.5">
+			<h3 class="text-xs font-semibold uppercase tracking-wide text-gray-500">
+				Billing profile
+			</h3>
+			<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
+				<dt class="text-gray-500">Default terms</dt>
+				<dd>{{ customer.defaultPaymentTerms }}</dd>
+				<dt class="text-gray-500">Default tax rate</dt>
+				<dd>{{ customer.defaultTaxRate }}%</dd>
+				<dt class="text-gray-500">Tax ID</dt>
+				<dd>{{ customer.taxId }}</dd>
+				<dt class="text-gray-500">Billing email</dt>
+				<dd>{{ customer.billingEmail }}</dd>
+			</dl>
+			<!-- The peek acts on the form: this writes into the draft. -->
+			<BbButton
+				class="mt-1 self-start"
+				prepend:icon="lucide:sparkles"
+				size="sm"
+				variant="secondary"
+				@click="() => ctx.applyCustomerDefaults(customer!)"
+			>
+				Apply billing defaults
+			</BbButton>
+		</section>
+
+		<!-- Recent invoices: real links — leaving a dirty draft still goes
+		     through the route-leave guard. -->
+		<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 :to="`/invoices/${recent.id}`" size="sm" variant="link">
+						{{ recent.number }}
+					</BbButton>
+					<BbBadge variant="outline">{{ recent.status }}</BbBadge>
+					<span class="text-xs tabular-nums 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 { useInvoiceForm } from './context';
+import { api } from '@/api';
+import type { CustomerDetail } from '@/types';
+
+const props = defineProps<{ customerId: number }>();
+
+const ctx = useInvoiceForm();
+
+const customer = ref<CustomerDetail | null>(null);
+watchEffect(async () => {
+	customer.value = await api.customers.getDetail(props.customerId);
+});
+
+const currency = new Intl.NumberFormat('en-US', {
+	style: 'currency',
+	currency: 'USD',
+});
+</script>
+```
+
+## Why it is built this way
+
+- **The context coopts, leaves consume.** The shell is joined once in
+  `provideInvoiceForm()`; ten components share the draft, the errors, the
+  peek stack and every action through one `useInvoiceForm()` call. The only
+  props on the page are data-identity props: the cells' `line` and the
+  peek's `customer-id`. Notably there is **no table context** here — the
+  line-items table has no selection, no paging and no fetch; its entire
+  state _is_ the draft, so there is nothing for a `useBbTableContext`
+  handle to carry.
+- **The draft is the mutation boundary.** On a workspace page every action
+  hits the API; on a form the unsaved state is the product. Cell commits,
+  line add/duplicate/remove and "apply billing defaults" therefore mutate
+  `ctx.draft` (still context actions — leaves never reach around it), and
+  the single `persist()` call is where the API, the 422 mapping, the toast
+  and the snapshot re-baseline live.
+- **422 keys are the server's shape, not reshaped.** Scalar inputs bind
+  `ctx.errors.value.<field>` directly; row errors keep their
+  `lineItems.<index>.<field>` keys and the cells resolve them through
+  `lineItemError`, which derives the index from the row's id — so the
+  lookup survives the page-search filter reordering what is visible.
+- **Tied selects trust the machinery.** `dependencies: [draft.customerId]`
+  re-runs the project provider, `enforce-coherence` prunes a stale pick,
+  and both providers honor the prefill contract (return the selected
+  record on component-initiated calls) so a valid selection is never
+  wiped — the exact failure mode the BbSelect guide warns about.
+- **The inline-edit grammar is three tiny leaves, not one configurable
+  cell.** Each editable cell owns rung-1 state (`editing`, the in-flight
+  value), commits on blur/Enter and reverts on Esc. Enter is
+  `.prevent`-ed so it commits the cell instead of submitting the enclosing
+  form, and the `editing` guard keeps the unmount blur after an Esc from
+  re-committing the reverted value.
+- **The dirty snapshot re-baselines before every self-inflicted
+  navigation** — successful save, draft save, delete — so the
+  `onBeforeRouteLeave` confirm fires only when the user genuinely walks
+  away. Cancel is a plain `to` link for the same reason: the guard _is_ the
+  confirm, so the button needs none of its own.
+- **A sticky action row, not the floating bottom panel.** The panel from
+  the guides is selection-driven chrome that comes and goes; a form's
+  commit affordance must be permanently visible, so it is a sticky row on
+  the page surface (`--bb-panel` background, top border) hosting the one
+  `variant="primary"` of the page.
+- **Sizing:** the form fields are full-height — a form is not a dense
+  surface. `compact` appears where density is real: the topbar search, the
+  line-items table and its cell inputs. `sm` buttons appear only in the
+  table's row actions, the "View customer" link and the peek; everything
+  in the sticky row is default `md`.
+- **Destructive actions ride `useConfirm`** — delete and the leave guard
+  both — and the peek is a workbench: it acts on the draft and links out
+  with real `to` links, never `@click` + router.
+
+## Variations
+
+- **Inside a `BbDialog`** (quick create from the invoices workspace): drop
+  the route guard and breadcrumbs, keep `isDirty`, confirm on the dialog's
+  close instead, and move the action row into the dialog `#footer` — the
+  context and sections carry over unchanged.
+- **Autosave drafts**: debounce a watcher on `draft` that calls
+  `persist('draft')` silently and re-baselines per save; the "Save as
+  draft" button disappears and the sticky row shows "Saved 12s ago".
+- **Client-side pre-validation**: validate required fields on submit
+  before calling the API and merge the messages into the same `errors`
+  map — the inputs cannot tell the difference, which is the point.
+- **Per-line tax**: add an `EditableTaxCell` per row (its own leaf, per
+  the no-API-monster rule) and group the totals block by rate.
+- **Send flow**: the primary becomes "Save and send" and opens a
+  `BbDialog` preview (recipient, subject, PDF) whose open-state lives on
+  the context, before persisting with `status: 'pending'`.
+- **Per-field persistence**: this page deliberately has no per-cell save
+  feedback because no per-cell save exists — the draft is the mutation
+  boundary and Save is the one commit. When the domain wants every field
+  to persist itself (no Save button), that is the autosave pattern: see
+  the [Inline Edit Playbook](../../guides/inline-edit-playbook.md) and
+  the inline-edit-workspace recipe.
+
+## Related
+
+- [Records Workspace (Vue)](./records-workspace.md) — the listing page
+  this form is reached from.
+- [Page Shell](../../guides/page-shell.md) — the app-side layout the
+  customer peek renders inside.
+- [BbTable](../../BbTable.md), [BbSelect](../../BbSelect.md),
+  [BbCollapsible](../../BbCollapsible.md) — the components this page
+  leans on hardest.