bitboss-ui 2.1.135 → 3.0.0-alpha.4

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

@@ -0,0 +1,1489 @@
+---
+title: Record Form (Inertia)
+summary: Full-anatomy invoice create/edit form for Laravel + Inertia — sectioned fields with tied selects, usePromiseForm + form.errors for 422 mapping, an inline-editing line-items table, a useConfirmOnRouteLeave dirty guard, a sticky action row, and a customer peek sidebar, all through one coopting page context.
+---
+
+# Recipe: Record Form (Inertia)
+
+The form archetype at full standard anatomy adapted for **Laravel +
+Inertia**: the same Stripe-grade invoice create/edit page — sectioned
+fields with tied selects, an inline-editing line-items table, a
+dirty-guarded sticky action row, and a customer peek workbench — but the
+draft **is** [`usePromiseForm`](../../guides/inertia-helpers.md) state, so
+422 mapping is free on `form.errors`, dirty tracking is native
+`form.isDirty`, saves are promise-wrapped `form.post`/`form.put` visits, and
+the leave guard is the toolkit's
+[`useConfirmOnRouteLeave`](../../guides/inertia-helpers.md). 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/record-form.md) ·
+[Nuxt](../nuxt/record-form.md). The listing this page belongs with is
+[Records Workspace (Inertia)](./records-workspace.md).
+
+## Prerequisites
+
+- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
+  imports `PageShell` and `usePageShellContext` from your own app.
+  They are not package exports; the scaffold recipe is their source. Copy
+  those files before anything below, and do not hand-roll replacements —
+  the peek stack, the close semantics and the sidebar's out-of-flow
+  behaviour are all load-bearing here.
+- `<BbConfirm />` and `<BbToast />` mounted once in the `createInertiaApp` render root — never in a page.
+- From the [Inertia Helpers](../../guides/inertia-helpers.md) toolkit:
+  `usePromiseForm`, `useConfirmOnRouteLeave`, `useProp`.
+- Controller: `Inertia::render('Invoices/Edit', ['invoice' => $invoice])`
+  — `invoice` is `null` on the create route and the full record (including
+  `lineItems`) on the edit route. Standard Laravel validation; on failure
+  Inertia puts messages on `form.errors`. Mutation routes are plain Laravel
+  routes (`POST /invoices`, `PUT /invoices/:id`, `DELETE /invoices/:id`)
+  that redirect back; small JSON GET endpoints (`GET /customers/search`,
+  `GET /customers/:id/projects`, `GET /customers/:id/peek`) back the
+  customer/project selects and the sidebar peek.
+
+## Key ideas
+
+- **One coopting page context.** `provideInvoiceForm()` joins the
+  page-shell stack once, owns the draft, the server errors, the dirty
+  state 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 Inertia form.** `ctx.draft` is `usePromiseForm`'s own
+  reactive fields, so inline cell edits, the peek's "apply billing
+  defaults", and add/duplicate/remove line all mutate `ctx.draft` exactly
+  like the Vue/Nuxt recipes — but there is no separate submission payload
+  to assemble by hand: `form.transform()` shapes the request just before
+  `post`/`put`.
+- **422 errors reach every input — including table rows — through
+  Inertia's own `form.errors`.** Laravel-style keys (`customerId`,
+  `lineItems.2.unitPrice`) arrive pre-mapped; scalar fields bind
+  `ctx.errors.value.<key>` and the editable cells resolve their row key
+  through `ctx.lineItemError(line, field)`, unchanged from the other
+  platforms.
+- **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 an inline-editing table (§6.3).** One leaf per cell
+  type — description, quantity, unit price — each swapping to an input on
+  click, committing on blur/Enter and reverting on Esc. The amount column
+  is virtual, computed from the row.
+- **Dirty state is native.** `form.isDirty` compares the live draft
+  against the baseline `form.defaults()` set on load and re-taken after
+  every successful save — no JSON snapshot to maintain. The route-leave
+  guard is the toolkit's `useConfirmOnRouteLeave({ disabled: () =>
+!form.isDirty, whitelist: [submitUrl] })`, whitelisting the form's own
+  submit URL so a save can't confirm-block itself.
+- **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-items table 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 + usePromiseForm draft + actions + leave guard)
+	DetailsSection.vue          ← tied selects, dates, terms, PO, tax rate
+	LineItemsSection.vue        ← editable BbTable + add line + live totals
+	EditableDescriptionCell.vue ← inline text edit (commit on blur/Enter, Esc reverts)
+	EditableQuantityCell.vue    ← inline quantity edit, same grammar
+	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()` (`form.transform` + `post`/`put`)        |
+| 2   | Save as draft                   | sticky bar outline (create mode)      | `persist('draft')`; controller redirect lands on the edit route        |
+| 3   | Delete invoice                  | sticky bar destructive (edit mode)    | `useConfirm` → `remove()` (promise-wrapped `form.delete`) → toast      |
+| 4   | Cancel                          | sticky bar ghost                      | navigation (`href`, an Inertia visit); leave guard intercepts if dirty |
+| 5   | Pick customer                   | details section select                | query-aware `items` provider (small JSON endpoint)                     |
+| 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: commit on blur/Enter, Esc reverts                                |
+| 10  | Edit quantity / rate inline     | line-item cells                       | §6.3 with `BbNumberInput` (min/precision enforced)                     |
+| 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 `href` navigation (an Inertia visit; leave guard applies)         |
+
+## The code
+
+### The shapes
+
+What the page props contribute — 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;
+}
+
+export interface Invoice extends InvoiceDraft {
+	id: number;
+	number: string;
+	status: InvoiceStatus;
+}
+```
+
+```ts
+// Inertia::render('Invoices/Edit', ['invoice' => ...]) page prop
+const pageProps = {
+	invoice: {
+		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.',
+	}, // null on the create route
+};
+```
+
+### context.ts
+
+```ts
+// InvoiceForm/context.ts
+import {
+	computed,
+	inject,
+	provide,
+	ref,
+	type ComputedRef,
+	type InjectionKey,
+	type Ref,
+} from 'vue';
+import { useConfirm, useToast } from 'bitboss-ui';
+import {
+	usePageShellContext,
+	type PageShellContext,
+} from '@/components/layout/usePageShellContext';
+import { usePromiseForm } from '@/composables/usePromiseForm';
+import { useConfirmOnRouteLeave } from '@/composables/useConfirmOnRouteLeave';
+import { useProp } from '@/composables/useProp';
+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 };
+
+type LineItemField = 'description' | 'quantity' | 'unitPrice';
+
+export interface InvoiceFormContext {
+	// -- Coopted contexts ------------------------------------------------------
+	shell: PageShellContext<PeekItem>;
+	// -- Page-owned state ------------------------------------------------------
+	mode: 'create' | 'edit';
+	/** Inertia delivers `invoice` as a page prop — nothing to await; this stays
+	 *  a trivial computed only so Index.vue's `v-if` reads the same on every
+	 *  platform. */
+	loaded: ComputedRef<true>;
+	invoiceNumber: ComputedRef<string | null>;
+	status: ComputedRef<InvoiceStatus>;
+	/** The Inertia form's own reactive fields — the draft IS `form`. */
+	draft: InvoiceDraft;
+	/** Inertia's own error bag: one message per field (not an array). */
+	errors: ComputedRef<Record<string, string>>;
+	saving: ComputedRef<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: visit + toast) ----------------------------------------
+	saveInvoice: () => Promise<void>;
+	saveAsDraft: () => Promise<void>;
+	deleteInvoice: () => Promise<void>;
+}
+
+const key: InjectionKey<InvoiceFormContext> = Symbol('invoice-form');
+
+export function provideInvoiceForm(): InvoiceFormContext {
+	const { toast } = useToast();
+	const { confirm } = useConfirm();
+
+	// -- Coopt the shell: once, here, for the whole page. ------------------------
+	const shell = usePageShellContext<PeekItem>();
+
+	// `invoice` is null on the create route, the full record on the edit route.
+	const invoice = useProp<Invoice | null>('invoice');
+	const mode: 'create' | 'edit' = invoice.value !== null ? 'edit' : 'create';
+	const invoiceId = invoice.value?.id ?? null;
+	const loaded = computed(() => true as const);
+
+	const invoiceNumber = computed(() => invoice.value?.number ?? null);
+	const status = computed<InvoiceStatus>(
+		() => invoice.value?.status ?? 'draft'
+	);
+
+	// -- The draft IS the Inertia form -------------------------------------------
+	// 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 { form, post, put, remove, isSubmitting } =
+		usePromiseForm<InvoiceDraft>({
+			customerId: invoice.value?.customerId ?? null,
+			projectId: invoice.value?.projectId ?? null,
+			issuedAt: invoice.value?.issuedAt ?? null,
+			dueDate: invoice.value?.dueDate ?? null,
+			paymentTerms: invoice.value?.paymentTerms ?? null,
+			poNumber: invoice.value?.poNumber ?? null,
+			taxRate: invoice.value?.taxRate ?? null,
+			lineItems: invoice.value
+				? invoice.value.lineItems.map((line) => ({ ...line }))
+				: [blankLineItem()],
+			notes: invoice.value?.notes ?? null,
+			terms: invoice.value?.terms ?? null,
+		});
+	const draft = form;
+	const errors = computed(() => form.errors as Record<string, string>);
+	const saving = isSubmitting;
+	const isDirty = computed(() => form.isDirty);
+
+	// -- Item providers -----------------------------------------------------------
+	// Small JSON endpoints, not page visits: searching a select must not
+	// re-render the page. 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 fetch(`/customers/search?ids[]=${draft.customerId}`).then((res) =>
+				res.json()
+			);
+		}
+		return fetch(`/customers/search?q=${encodeURIComponent(query)}`).then(
+			(res) => res.json()
+		);
+	};
+
+	// 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([])
+			: fetch(`/customers/${draft.customerId}/projects`).then((res) =>
+					res.json()
+				);
+
+	// -- Line items -----------------------------------------------------------------
+	const lineItemSearch = ref('');
+	const visibleLineItems = computed(() => {
+		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 error 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 -----------------------------------------------------------------
+	// The submit target doubles as the whitelist entry below: PUT/DELETE and the
+	// create POST land on the same two paths.
+	const submitUrl =
+		mode === 'edit' && invoiceId !== null
+			? `/invoices/${invoiceId}`
+			: '/invoices';
+
+	const persist = async (nextStatus: InvoiceStatus): Promise<boolean> => {
+		// New lines travel with `id: null`; the server assigns real ids on save.
+		// `transform` shapes the request without mutating the draft's own fields.
+		form.transform((data) => ({
+			...data,
+			status: nextStatus,
+			lineItems: (data.lineItems as LineItemDraft[]).map((line) => ({
+				...line,
+				id: line.id > 0 ? line.id : null,
+			})),
+		}));
+		try {
+			await (mode === 'edit' ? put(submitUrl) : post(submitUrl));
+			// Re-baseline: the just-saved values become the new "clean" state,
+			// same purpose as the Vue/Nuxt recipes' JSON snapshot re-take.
+			form.defaults();
+			return true;
+		} catch {
+			// form.errors is already populated by usePromiseForm's reject path.
+			toast({
+				title: form.hasErrors
+					? 'Some fields need attention.'
+					: 'Something went wrong. Try again.',
+				variant: 'destructive',
+			});
+			return false;
+		}
+	};
+
+	const saveInvoice = async () => {
+		// Creating finalizes the invoice; editing keeps whatever status it has.
+		const ok = await persist(mode === 'edit' ? status.value : 'pending');
+		if (!ok) return;
+		// The controller's redirect is followed inside this same visit — no
+		// client-side navigation call needed.
+		toast({
+			title:
+				mode === 'edit'
+					? `Invoice ${invoiceNumber.value} saved.`
+					: 'Invoice created.',
+			variant: 'success',
+		});
+	};
+
+	const saveAsDraft = async () => {
+		const ok = await persist('draft');
+		if (!ok) return;
+		toast({
+			title:
+				mode === 'edit'
+					? `Draft ${invoiceNumber.value} saved.`
+					: 'Draft saved.',
+			variant: 'success',
+		});
+	};
+
+	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 remove(submitUrl);
+		toast({ title: `${invoiceNumber.value} deleted.`, variant: 'success' });
+	};
+
+	// -- Route-leave guard ---------------------------------------------------------
+	// `form.isDirty` needs no snapshot bookkeeping; the submit URL is whitelisted
+	// so saving (which IS a visit) can't confirm-block itself.
+	useConfirmOnRouteLeave({
+		disabled: () => !form.isDirty,
+		whitelist: [submitUrl],
+		title: 'Unsaved changes',
+		text: 'You have unsaved changes on this invoice. Leave without saving?',
+	});
+
+	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 table. -->
+		<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"
+					autocomplete="off"
+					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. -->
+			<form
+				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', href: '/dashboard' },
+	{ key: 'billing', text: 'Billing', href: '/billing' },
+	{ key: 'invoices', text: 'Invoices', href: '/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-[color:var(--bb-text-muted)]"
+		>
+			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"
+					: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"
+				: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"
+				:errors="ctx.errors.value.issuedAt"
+				floating
+				label="Issue date"
+				prepend:icon="lucide:calendar"
+			/>
+			<BbDatePickerInput
+				v-model="ctx.draft.dueDate"
+				:errors="ctx.errors.value.dueDate"
+				floating
+				label="Due date"
+				:min="ctx.draft.issuedAt ?? undefined"
+				prepend:icon="lucide:calendar"
+			/>
+
+			<BbSelect
+				v-model="ctx.draft.paymentTerms"
+				: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"
+				:errors="ctx.errors.value.poNumber"
+				label="PO / reference"
+				placeholder="PO-2026-0641"
+			/>
+
+			<BbNumberInput
+				v-model="ctx.draft.taxRate"
+				: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-[color:var(--bb-text-muted)]"
+			>
+				Line items
+			</h2>
+			<BbButton
+				prepend:icon="lucide:plus"
+				variant="outline"
+				@click="ctx.addLineItem"
+			>
+				Add line item
+			</BbButton>
+		</div>
+
+		<!-- Inline-editing table (§6.3): every editable cell type is its own
+		     leaf. The amount column is virtual — computed from the row. -->
+		<BbTable
+			actions
+			caption="Invoice line items"
+			:columns="columns"
+			compact
+			item-value="id"
+			:items="ctx.visibleLineItems.value"
+		>
+			<template #description="{ item }">
+				<EditableDescriptionCell :line="item" />
+			</template>
+
+			<template #quantity="{ item }">
+				<EditableQuantityCell :line="item" />
+			</template>
+
+			<template #unit_price="{ item }">
+				<EditableRateCell :line="item" />
+			</template>
+
+			<template #actions="{ item }">
+				<div class="flex items-center justify-end gap-1">
+					<BbButton
+						icon="lucide:copy"
+						size="sm"
+						variant="ghost"
+						@click="() => ctx.duplicateLineItem(item)"
+					>
+						Duplicate line
+					</BbButton>
+					<BbButton
+						icon="lucide:trash-2"
+						size="sm"
+						variant="ghost"
+						@click="() => ctx.removeLineItem(item)"
+					>
+						Remove line
+					</BbButton>
+				</div>
+			</template>
+
+			<template #no-data>
+				<div class="flex flex-col items-center gap-2 p-6 text-center">
+					<p class="text-sm text-[color:var(--bb-text-muted)]">
+						{{
+							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>
+			</template>
+		</BbTable>
+
+		<!-- 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-[color:var(--bb-text-muted)]">Subtotal</dt>
+			<dd class="text-right tabular-nums">
+				{{ currency.format(ctx.subtotal.value) }}
+			</dd>
+			<dt class="text-[color:var(--bb-text-muted)]">
+				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, BbTable } 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';
+
+const ctx = useInvoiceForm();
+
+const currency = new Intl.NumberFormat('en-US', {
+	style: 'currency',
+	currency: 'USD',
+});
+
+// `unit_price` and `amount` match no item field on purpose: the first is
+// fully slotted (snake_case key so the slot name reads naturally), the
+// second is a virtual column deriving its content in the formatter.
+const columns = [
+	{ key: 'description', label: 'Description' },
+	{ key: 'quantity', label: 'Qty', align: 'right' as const, width: 96 },
+	{
+		key: 'unit_price',
+		label: 'Unit price',
+		align: 'right' as const,
+		width: 140,
+	},
+	{
+		key: 'amount',
+		label: 'Amount',
+		align: 'right' as const,
+		width: 130,
+		formatter: (_: unknown, __: string, item: LineItemDraft) =>
+			currency.format(item.quantity * item.unitPrice),
+	},
+];
+</script>
+```
+
+### EditableDescriptionCell.vue
+
+```vue
+<!-- InvoiceForm/EditableDescriptionCell.vue -->
+<template>
+	<BbTextInput
+		v-if="editing"
+		v-model="value"
+		autofocus
+		compact
+		:errors="ctx.lineItemError(line, 'description')"
+		hide-label
+		label="Line description"
+		placeholder="What was delivered?"
+		@blur="commit"
+		@keydown.enter.prevent="commit"
+		@keydown.esc="revert"
+	/>
+	<button
+		v-else
+		class="w-full rounded-[var(--bb-radius)] px-1 py-0.5 text-left hover:bg-[color:var(--bb-hover)]"
+		:class="{
+			'text-[color:var(--bb-text-muted)]': !line.description,
+			'text-red-600 dark:text-red-400': hasError,
+		}"
+		type="button"
+		@click="start"
+	>
+		{{ line.description || 'Add a description…' }}
+	</button>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbTextInput } 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 hasError = computed(() => !!ctx.lineItemError(props.line, 'description'));
+
+const start = () => {
+	value.value = props.line.description;
+	editing.value = true;
+};
+
+// Commit on blur/Enter, revert on Esc (§6.3). Enter is prevented so it
+// edits the cell instead of submitting the enclosing invoice form; 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"
+		v-model="value"
+		autofocus
+		compact
+		:errors="ctx.lineItemError(line, 'quantity')"
+		hide-label
+		label="Quantity"
+		:max-precision="2"
+		:min="0"
+		@blur="commit"
+		@keydown.enter.prevent="commit"
+		@keydown.esc="revert"
+	/>
+	<button
+		v-else
+		class="w-full rounded-[var(--bb-radius)] px-1 py-0.5 text-right tabular-nums hover:bg-[color:var(--bb-hover)]"
+		:class="{ 'text-red-600 dark:text-red-400': hasError }"
+		type="button"
+		@click="start"
+	>
+		{{ line.quantity }}
+	</button>
+</template>
+
+<script setup lang="ts">
+import { computed, 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 hasError = computed(() => !!ctx.lineItemError(props.line, 'quantity'));
+
+const start = () => {
+	value.value = props.line.quantity;
+	editing.value = true;
+};
+
+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"
+		v-model="value"
+		autofocus
+		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-[color:var(--bb-hover)]"
+		:class="{ 'text-red-600 dark:text-red-400': hasError }"
+		type="button"
+		@click="start"
+	>
+		{{ currency.format(line.unitPrice) }}
+	</button>
+</template>
+
+<script setup lang="ts">
+import { computed, 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 hasError = computed(() => !!ctx.lineItemError(props.line, 'unitPrice'));
+
+const currency = new Intl.NumberFormat('en-US', {
+	style: 'currency',
+	currency: 'USD',
+});
+
+const start = () => {
+	value.value = props.line.unitPrice;
+	editing.value = true;
+};
+
+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. Inertia delivers the
+// invoice synchronously as a page prop, so seeding from the draft here
+// starts an annotated invoice open and a blank one closed, same as Vue/Nuxt.
+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-[color:var(--bb-text-muted)]"
+		>
+			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" href="/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-[color:var(--bb-text-muted)]">
+					{{ 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-[color:var(--bb-text-muted)]">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-[color:var(--bb-text-muted)]">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-[color:var(--bb-text-muted)]">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-[color:var(--bb-text-muted)]"
+			>
+				Billing profile
+			</h3>
+			<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
+				<dt class="text-[color:var(--bb-text-muted)]">Default terms</dt>
+				<dd>{{ customer.defaultPaymentTerms }}</dd>
+				<dt class="text-[color:var(--bb-text-muted)]">Default tax rate</dt>
+				<dd>{{ customer.defaultTaxRate }}%</dd>
+				<dt class="text-[color:var(--bb-text-muted)]">Tax ID</dt>
+				<dd>{{ customer.taxId }}</dd>
+				<dt class="text-[color:var(--bb-text-muted)]">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-[color:var(--bb-text-muted)]"
+			>
+				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 :href="`/invoices/${recent.id}`" size="sm" variant="link">
+						{{ recent.number }}
+					</BbButton>
+					<BbBadge variant="outline">{{ recent.status }}</BbBadge>
+					<span class="text-xs tabular-nums text-[color:var(--bb-text-muted)]">
+						{{ 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 { useInvoiceForm } from './context';
+import type { CustomerDetail } from '@/types';
+
+const props = defineProps<{ customerId: number }>();
+
+const ctx = useInvoiceForm();
+
+// A small JSON endpoint, not a page visit — opening the peek never
+// re-renders the form underneath it.
+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>
+```
+
+## 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 `usePromiseForm`'s own reactive fields.** Cell commits,
+  line add/duplicate/remove and "apply billing defaults" mutate
+  `ctx.draft` exactly like the Vue/Nuxt recipes (still context actions —
+  leaves never reach around it); the only extra step is `form.transform()`
+  inside `persist()`, which shapes the outgoing request (adds `status`,
+  nulls out negative local ids) without mutating the draft the inputs are
+  bound to.
+- **422 keys are the server's shape, not reshaped.** `form.errors` arrives
+  keyed exactly like Laravel's validation bag (`customerId`,
+  `lineItems.2.unitPrice`) — no manual mapping. Scalar inputs bind
+  `ctx.errors.value.<field>` directly; row errors keep their dotted 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
+  providers themselves are small JSON endpoints (not lazy props), because
+  the customer search is user-typed and the project list is parameterized
+  by the chosen customer.
+- **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.
+- **Dirty tracking is native, so there is no snapshot to maintain.**
+  `form.isDirty` already compares the live draft against its baseline;
+  `form.defaults()` re-takes that baseline after every successful save,
+  the same purpose the Vue/Nuxt JSON snapshot re-take serves. The
+  route-leave guard is `useConfirmOnRouteLeave({ disabled: () =>
+!form.isDirty, whitelist: [submitUrl] })` — the whitelist is required
+  because submitting the form _is_ a visit, and without it the guard would
+  confirm-block the form's own save.
+- **No client-side redirects after save.** Unlike the Vue/Nuxt recipes'
+  explicit `router.push`/`navigateTo`, the Laravel controller's redirect is
+  followed inside the same Inertia visit that `post`/`put` performs —
+  `saveInvoice`, `saveAsDraft` and `deleteInvoice` only toast.
+- **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 `href`s (Inertia visits), never `@click` + `router.visit`.
+
+## Variations
+
+- **Inside a `BbDialog`** (quick create from the invoices workspace): drop
+  `useConfirmOnRouteLeave` and breadcrumbs, keep `form.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-takes `form.defaults()` 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 `post`/`put` and merge the messages into `form.errors`
+  via `form.setError(...)` — 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'`.
+- **Static option catalogs**: if the customer list is small and identical
+  for every render, swap `fetchCustomers`' JSON endpoint for a lazy prop —
+  `const { getter: fetchCustomers } = useLazyPropGetter('customers')` — see
+  `useLazyPropGetter` in the [Inertia Helpers](../../guides/inertia-helpers.md)
+  guide.
+- **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 (Inertia)](./records-workspace.md) — the listing page
+  this form is reached from.
+- [Inertia Helpers](../../guides/inertia-helpers.md) — `usePromiseForm`,
+  `useConfirmOnRouteLeave`, `useResourceContext` in full.
+- [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.