bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/recipes/nuxt/upload-center.md

@@ -0,0 +1,1886 @@
+---
+title: Upload Center (Nuxt)
+summary: Full-anatomy expense-receipts upload center for Nuxt — multi-file dropzone into an inline-editable table (text, category popover, amount, date cells), per-file progress with inline retry, submit-all with count, bulk bottom panel, and a stacked receipt/merchant peek sidebar, filters URL-synced and drafts fetched with useAsyncData while the upload queue stays client-only, all through one coopting page context.
+---
+
+# Recipe: Upload Center (Nuxt)
+
+The Expensify-grade expense receipts submission page adapted for **Nuxt**:
+the same multi-file dropzone feeding an inline-editable table, per-file
+upload progress with inline retry, one-click category cells, bulk actions
+in the floating bottom panel, and a stacked receipt/merchant peek sidebar —
+but filters and the active tab live in the URL, the drafts page loads
+through `useAsyncData` watching `route.query`, and the live upload queue
+stays exactly what it is: client-only reactive state merged above the
+fetched rows. 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/upload-center.md) ·
+[Inertia](../inertia/upload-center.md).
+
+## Prerequisites
+
+- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
+  imports `PageShell`, `usePageShellContext` and `FloatingBottomPanel` 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 `app.vue` — never in a page.
+- [App Layout](../../guides/app-layout.md), [Page Shell](../../guides/page-shell.md)
+  and [Floating Bottom Panel](../../guides/floating-bottom-panel.md) copied
+  into `src/components/layout/` per their guides — every recipe page assumes
+  this chrome exists and renders inside it.
+- A `useCategoriesStore()` Pinia store exposing the shared expense-category
+  catalog (Travel, Meals & entertainment, Lodging, Rideshare & transit,
+  Software & subscriptions, Office supplies, Fuel, Client entertainment).
+- Server routes: `GET /api/receipts` (accepts `search`, `categoryIds[]`,
+  `merchant`, `spentBetween[]`, `tab`, `page`, `perPage`, returns
+  `{ data, total, tabCounts, readyCount }`), `GET /api/merchants/search`,
+  plus the mutation routes referenced below (`PATCH /api/receipts/:id`,
+  `POST /api/receipts/:id/submit`, `POST /api/receipts/submit-drafts`,
+  `DELETE /api/receipts/:id`, `PATCH /api/receipts/bulk/categorize`,
+  `POST /api/receipts/bulk/delete`). A dedicated `POST /api/receipts/upload`
+  endpoint backs `api.receipts.upload()` — see the upload note below.
+
+## Key ideas
+
+- **One coopting page context.** `provideUploadCenter()` joins the
+  page-shell stack and the table context once, coopts the shared category
+  catalog from `useCategoriesStore()`, owns the URL-backed filters/tab and
+  the **upload queue**, and exposes complete actions. Every leaf calls
+  `useUploadCenter()` and nothing else.
+- **Filters and tab live in the URL, not in local refs.** They are seeded
+  from `route.query` at setup and every change writes back through
+  `navigateTo` — the page is bookmarkable and survives reload.
+- **`useAsyncData` watches `route.query`.** That single watch source is
+  the whole refetch trigger for the _server_ page — filters, tab and page
+  changes all funnel through the URL first, so there is exactly one fetch
+  path for drafts/submitted/reimbursed rows.
+- **The upload queue is untouched by the data-layer swap.** It stays
+  client-only reactive state (`uploads`), merged above the fetched server
+  rows in a computed (`rows`) passed straight to `BbTable`'s `:items` —
+  no `dependencies`, no `refreshKey`; progress ticks mutate the queue rows
+  in place and Vue's own reactivity re-renders the one cell reading them.
+- **Capture and transfer are two layers.** `BbDropzone` only validates and
+  hands over `File[]`; the context runs the uploads (AbortController +
+  progress callback per file) and the dropzone leaf immediately drains its
+  model into `ctx.enqueueFiles()`. `$fetch` has no upload-progress events,
+  so the transfer itself posts `FormData` through a small XHR wrapper in
+  `@/api` — the call site (`api.receipts.upload(file, { signal, onProgress })`)
+  stays identical to the other platforms.
+- **Every draft cell edits in place**, exactly as in the Vue recipe:
+  merchant (§6.3), category (§6.1), amount, date — each its own leaf with
+  a single `receipt` prop, failed saves revert via `refresh()` and toast
+  destructive.
+- **Tabs are URL filters.** Drafts / Submitted / Reimbursed carry `href`
+  (`?tab=drafts`) and live counts from every fetch; the same table is the
+  pane, read-only outside Drafts.
+- **Clicking the name of a thing peeks it.** Filename → receipt peek
+  (fresh stack); merchant name inside the peek → merchant peek **stacked**
+  with a back arrow. Peeks fetch their own JSON and re-run whenever
+  `ctx.rows.value` changes (the same signal a server `refresh()` updates).
+- **Buttons are `md` by default**; `sm`/`xs` only in the table rows, the
+  filter pills, the peek footers and the bottom bar. One
+  `variant="primary"`: **Submit all** with its live count. Internal SPA
+  navigation (the merchant peek's "All receipts from…" link) uses `to`;
+  the file-download links (`Download original`) stay a raw `href` — they
+  serve a real file, not a Nuxt page, so they must not be intercepted by
+  the router.
+
+## Page anatomy
+
+```
+UploadCenter/
+	Index.vue              ← assembly: PageShell slots, dropzone, tabs, table, pagination
+	context.ts              ← coopting page context (shell + table + categories + URL filters + upload queue + actions)
+	ReceiptDropzone.vue    ← multi-file capture, constraint errors mapped to messages
+	FilterRail.vue          ← pill filters + clear-all
+	ReceiptFileCell.vue     ← file icon + name (peek link) + size, both row kinds
+	UploadProgressCell.vue ← per-file BbProgress / failed state with inline retry
+	MerchantCell.vue        ← inline text edit, commit on blur/Enter (§6.3)
+	CategoryCell.vue        ← one-click badge → BbSelectPopover (§6.1)
+	AmountCell.vue           ← inline number edit with $ prefix
+	DateCell.vue             ← date picker cell, commit on pick
+	RowActions.vue           ← remove-from-queue / per-receipt "…" dropdown
+	SelectionBar.vue         ← bulk categorize + bulk remove in the floating bottom panel
+	ReceiptPeek.vue          ← sidebar workbench, stack level 1
+	MerchantPeek.vue         ← stacked peek, back arrow via the shell
+```
+
+Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
+(left nav + fat footer), [Page Shell](../../guides/page-shell.md),
+[Floating Bottom Panel](../../guides/floating-bottom-panel.md).
+
+## Action inventory
+
+| #   | Action                            | Trigger                            | Mechanism                                             |
+| --- | --------------------------------- | ---------------------------------- | ----------------------------------------------------- |
+| 1   | Upload receipts                   | dropzone (drag, click, Browse)     | `enqueueFiles()` → per-file upload with progress      |
+| 2   | Retry a failed upload             | inline in the progress cell        | `retryUpload(id)` re-issues the request               |
+| 3   | Remove an in-flight upload        | row actions (x)                    | `removeUpload(id)` aborts + drops the row             |
+| 4   | Page search                       | topbar right                       | `filters.search` → URL → `useAsyncData` refetch       |
+| 5   | Filter category / merchant / date | filter rail pills                  | `BbSelectPopover` multiple / query-aware / date range |
+| 6   | Clear filters                     | rail right (only when active)      | context `clearFilters()`                              |
+| 7   | Switch tab                        | href tabs with counts              | URL + `useAsyncData` refetch                          |
+| 8   | Edit merchant inline              | merchant cell                      | commit on blur/Enter, Esc reverts (§6.3)              |
+| 9   | Change category one-click         | category badge in row & peek       | `BbSelectPopover` on the badge (§6.1)                 |
+| 10  | Edit amount inline                | amount cell ($ prefix)             | commit on blur/Enter, Esc reverts                     |
+| 11  | Edit expense date inline          | date cell                          | commit on pick                                        |
+| 12  | Submit one receipt                | row `…`, peek footer               | `submitReceipt()` ($fetch + refresh + toast)          |
+| 13  | Submit all with count             | topbar, the page's one `primary`   | `submitAll()` — count from every fetch                |
+| 14  | Remove a draft                    | row `…`, peek footer               | destructive behind `useConfirm`                       |
+| 15  | Bulk categorize                   | floating bottom panel popover      | `bulkCategorize()` on `table.selected`                |
+| 16  | Bulk remove                       | floating bottom panel              | destructive behind `useConfirm`, count in message     |
+| 17  | Select rows / select all          | table checkboxes (drafts only)     | table context, `selectable` predicate                 |
+| 18  | Peek receipt                      | filename cell / merchant peek list | `peekReceipt(id)` → shell stack                       |
+| 19  | Peek merchant (stacked)           | merchant name inside the peek      | `stackMerchant(name)` → back arrow                    |
+| 20  | Download original                 | row `…`, peek footer               | navigation (raw `href`, real file endpoint)           |
+
+## The code
+
+### context.ts
+
+```ts
+// UploadCenter/context.ts
+import {
+	computed,
+	inject,
+	provide,
+	reactive,
+	ref,
+	watch,
+	type ComputedRef,
+	type InjectionKey,
+	type Ref,
+} from 'vue';
+import {
+	useBbTableContext,
+	useConfirm,
+	useToast,
+	type BbTableContext,
+} from 'bitboss-ui';
+import {
+	usePageShellContext,
+	type PageShellContext,
+} from '@/components/layout/usePageShellContext';
+import { useCategoriesStore } from '@/stores/categories';
+import { api } from '@/api';
+import { watchDebounced } from '@vueuse/core';
+import type { Category, Receipt } from '@/types';
+
+/** What the stacked sidebar can show. Clicking a name pushes one of these. */
+export type PeekItem =
+	| { type: 'receipt'; id: string }
+	| { type: 'merchant'; name: string };
+
+export type UploadCenterTab = 'drafts' | 'submitted' | 'reimbursed';
+
+export interface ReceiptFilters {
+	search: string;
+	categoryIds: string[];
+	merchant: string | null;
+	/**
+	 * `[start, end]` as `YYYY-MM-DD`, or `[]` when unset. Range mode requires an
+	 * array modelValue -- binding `null` throws, so the empty filter is `[]`.
+	 */
+	spentBetween: string[];
+}
+
+/** A dropped file whose transfer is still in flight (or failed). Local-only. */
+export type UploadRow = {
+	/** Local id (`upload-…`) — never collides with server receipt ids. */
+	id: string;
+	kind: 'upload';
+	filename: string;
+	size: number;
+	/** 0–100. Mutated in place per progress tick — reactive, no refetch. */
+	progress: number;
+	failed: boolean;
+};
+
+/** A server receipt as the table renders it. */
+export type ReceiptRow = Receipt & { kind: 'receipt' };
+
+/** What the table actually lists on the Drafts tab: uploads first. */
+export type UploadCenterRow = UploadRow | ReceiptRow;
+
+/** The only fields the inline cells may change. */
+export type ReceiptPatch = Partial<
+	Pick<Receipt, 'merchant' | 'categoryId' | 'amount' | 'date'>
+>;
+
+type ReceiptListResponse = {
+	data: Receipt[];
+	total: number;
+	tabCounts: Record<UploadCenterTab, number>;
+	readyCount: number;
+};
+
+export interface UploadCenterContext {
+	// -- Coopted contexts ------------------------------------------------------
+	shell: PageShellContext<PeekItem>;
+	table: BbTableContext;
+	/** Shared expense-category catalog, coopted from the store. */
+	categories: ComputedRef<Category[]>;
+	// -- Page-owned state ------------------------------------------------------
+	filters: ReceiptFilters;
+	hasActiveFilters: ComputedRef<boolean>;
+	tab: Ref<UploadCenterTab>;
+	tabCounts: ComputedRef<Record<UploadCenterTab, number>>;
+	/** Drafts that are complete (merchant + category + amount + date). */
+	readyCount: ComputedRef<number>;
+	/** The live upload queue — in-flight and failed transfers. */
+	uploads: Ref<UploadRow[]>;
+	// -- Data (server-rendered, URL-driven) -------------------------------------
+	/** Drafts tab: queue rows first, then the fetched server page. */
+	rows: ComputedRef<UploadCenterRow[]>;
+	rowsPending: Ref<boolean>;
+	searchMerchants: (query: string) => Promise<string[]>;
+	// -- Peek grammar ----------------------------------------------------------
+	peekReceipt: (id: string) => void;
+	stackReceipt: (id: string) => void;
+	stackMerchant: (name: string) => void;
+	// -- Actions (complete: API + refresh + toast) ------------------------------
+	clearFilters: () => void;
+	enqueueFiles: (files: File[]) => void;
+	retryUpload: (id: string) => void;
+	removeUpload: (id: string) => void;
+	updateReceipt: (receipt: Receipt, patch: ReceiptPatch) => Promise<void>;
+	submitReceipt: (receipt: Receipt) => Promise<void>;
+	submitAll: () => Promise<void>;
+	/** Resolves `true` when the receipt was actually deleted (confirm accepted). */
+	deleteReceipt: (receipt: Receipt) => Promise<boolean>;
+	bulkCategorize: (categoryId: string) => Promise<void>;
+	bulkRemove: () => Promise<void>;
+}
+
+const key: InjectionKey<UploadCenterContext> = Symbol('upload-center');
+
+/** Comma-joined query value → string[] (or null when absent). */
+const toArray = (value: unknown): string[] | null => {
+	if (value == null || value === '') return null;
+	return Array.isArray(value) ? value.map(String) : String(value).split(',');
+};
+
+export function provideUploadCenter(): UploadCenterContext {
+	const { toast } = useToast();
+	const { confirm } = useConfirm();
+	const route = useRoute();
+
+	// -- Coopt the specific contexts: once, here, for the whole page. ----------
+	const shell = usePageShellContext<PeekItem>();
+	const table = useBbTableContext('receipts-table', { perPage: 25 });
+	const categoriesStore = useCategoriesStore();
+	const categories = computed(() => categoriesStore.categories);
+
+	// -- Filters + tab: seeded from the URL, the single source of truth. -------
+	const filters = reactive<ReceiptFilters>({
+		search: (route.query.search as string) ?? '',
+		categoryIds: toArray(route.query.categoryIds) ?? [],
+		merchant: (route.query.merchant as string) ?? null,
+		spentBetween: toArray(route.query.spentBetween) ?? [],
+	});
+	const tab = ref<UploadCenterTab>(
+		(route.query.tab as UploadCenterTab) ?? 'drafts'
+	);
+
+	const hasActiveFilters = computed(
+		() =>
+			filters.search !== '' ||
+			filters.categoryIds.length > 0 ||
+			filters.merchant !== null ||
+			filters.spentBetween.length > 0
+	);
+
+	const clearFilters = () => {
+		filters.search = '';
+		filters.categoryIds = [];
+		filters.merchant = null;
+		filters.spentBetween = [];
+	};
+
+	// Every filter/tab change mirrors into the query string; `useAsyncData`
+	// below watches `route.query`, so this is the whole refetch trigger.
+	const syncQuery = () =>
+		navigateTo({
+			query: {
+				search: filters.search || undefined,
+				categoryIds: filters.categoryIds.length
+					? filters.categoryIds.join(',')
+					: undefined,
+				merchant: filters.merchant ?? undefined,
+				spentBetween: filters.spentBetween.length
+					? filters.spentBetween.join(',')
+					: undefined,
+				tab: tab.value,
+			},
+		});
+	watchDebounced(filters, syncQuery, { deep: true, debounce: 300 });
+	watch(tab, () => {
+		table.page.value = 1;
+		syncQuery();
+	});
+
+	// -- Data ---------------------------------------------------------------------
+	// The one place the *server* page is fetched. A drafts page looks like:
+	//   { id: 'rcp_3128', filename: 'uber-2026-07-08.pdf',   merchant: 'Uber',
+	//     categoryId: 'cat-rideshare', amount: 42.8,  date: '2026-07-08', … }
+	//   { id: 'rcp_3127', filename: 'IMG_4021.jpg',          merchant: 'Starbucks Reserve',
+	//     categoryId: 'cat-meals',     amount: 11.4,  date: '2026-07-08', … }
+	//   { id: 'rcp_3120', filename: 'delta-ticket-0472.pdf', merchant: 'Delta Air Lines',
+	//     categoryId: 'cat-travel',    amount: 428.6, date: '2026-07-06', … }
+	//   { id: 'rcp_3117', filename: 'marriott-folio.pdf',    merchant: 'Marriott Marquis SF',
+	//     categoryId: 'cat-lodging',   amount: 612.33, date: '2026-07-05', … }
+	// The live upload queue is NOT part of this response — it is client-only
+	// reactive state merged in below, ahead of the fetched rows.
+	const { data, pending, refresh } = useAsyncData<ReceiptListResponse>(
+		'receipts',
+		() =>
+			$fetch<ReceiptListResponse>('/api/receipts', {
+				query: {
+					search: filters.search || undefined,
+					categoryIds: filters.categoryIds,
+					merchant: filters.merchant ?? undefined,
+					spentBetween: filters.spentBetween.length
+						? filters.spentBetween
+						: undefined,
+					tab: tab.value,
+					page: table.page.value,
+					perPage: table.perPage.value,
+				},
+			}),
+		{ watch: [() => route.query, table.page] }
+	);
+	const serverRows = computed<ReceiptRow[]>(
+		() =>
+			data.value?.data.map(
+				(receipt): ReceiptRow => ({ ...receipt, kind: 'receipt' })
+			) ?? []
+	);
+	// Drafts tab: queue rows render above the fetched page; a completed upload
+	// re-enters here once the next `refresh()` lands it as a server draft.
+	const uploads = ref<UploadRow[]>([]);
+	const rows = computed<UploadCenterRow[]>(() =>
+		tab.value === 'drafts'
+			? [...uploads.value, ...serverRows.value]
+			: serverRows.value
+	);
+	const rowsPending = pending;
+	const tabCounts = computed(
+		() => data.value?.tabCounts ?? { drafts: 0, submitted: 0, reimbursed: 0 }
+	);
+	const readyCount = computed(() => data.value?.readyCount ?? 0);
+	watch(
+		data,
+		(response) => {
+			if (response) table.total.value = response.total;
+		},
+		{ immediate: true }
+	);
+
+	const searchMerchants = (query: string): Promise<string[]> =>
+		$fetch<string[]>('/api/merchants/search', { query: { q: query } });
+
+	// -- Upload machinery ----------------------------------------------------------
+	// Untouched by the URL/useAsyncData swap: the queue is client-only state,
+	// mutated in place per progress tick — reactive, no refetch — and `rows`
+	// above re-derives on every push/filter. Files and abort controllers live
+	// in closure maps, not render state.
+	const uploadFiles = new Map<string, File>();
+	const controllers = new Map<string, AbortController>();
+
+	const startUpload = async (id: string) => {
+		const file = uploadFiles.get(id);
+		const row = uploads.value.find((upload) => upload.id === id);
+		if (!file || !row) return;
+		row.failed = false;
+		row.progress = 0;
+		const controller = new AbortController();
+		controllers.set(id, controller);
+		try {
+			// `$fetch` has no upload-progress events, so `api.receipts.upload`
+			// posts FormData through a small XHR wrapper in `@/api` instead of
+			// `$fetch` — the call shape here is identical to the other platforms.
+			await api.receipts.upload(file, {
+				signal: controller.signal,
+				onProgress: (percent) => {
+					row.progress = percent;
+				},
+			});
+			// Success: the file re-enters as a server draft with OCR-extracted
+			// merchant/amount/date prefilled — the refresh swaps the rows.
+			uploads.value = uploads.value.filter((upload) => upload.id !== id);
+			uploadFiles.delete(id);
+			await refresh();
+		} catch {
+			// Keep the row: the progress cell renders the inline Retry.
+			row.failed = true;
+		} finally {
+			controllers.delete(id);
+		}
+	};
+
+	const enqueueFiles = (files: File[]) => {
+		for (const file of files) {
+			const id = `upload-${crypto.randomUUID()}`;
+			uploadFiles.set(id, file);
+			uploads.value.push({
+				id,
+				kind: 'upload',
+				filename: file.name,
+				size: file.size,
+				progress: 0,
+				failed: false,
+			});
+			void startUpload(id);
+		}
+	};
+
+	const retryUpload = (id: string) => {
+		void startUpload(id);
+	};
+
+	const removeUpload = (id: string) => {
+		controllers.get(id)?.abort();
+		controllers.delete(id);
+		uploadFiles.delete(id);
+		uploads.value = uploads.value.filter((upload) => upload.id !== id);
+	};
+
+	// -- Peek grammar ----------------------------------------------------------------
+	// peekX opens a fresh stack (from the list); stackX drills down (from a peek).
+	const peekReceipt = (id: string) => shell.push({ type: 'receipt', id }, true);
+	const stackReceipt = (id: string) => shell.push({ type: 'receipt', id });
+	const stackMerchant = (name: string) =>
+		shell.push({ type: 'merchant', name });
+
+	// -- Actions --------------------------------------------------------------------
+	const updateReceipt = async (receipt: Receipt, patch: ReceiptPatch) => {
+		try {
+			await $fetch(`/api/receipts/${receipt.id}`, {
+				method: 'PATCH',
+				body: patch,
+			});
+			await refresh(); // silent on success — the cell already shows the new value
+		} catch {
+			await refresh(); // the refetch reverts the cell to the server value
+			toast({
+				title: `Could not save ${receipt.filename}. Changes were reverted.`,
+				variant: 'destructive',
+			});
+		}
+	};
+
+	const submitReceipt = async (receipt: Receipt) => {
+		await $fetch(`/api/receipts/${receipt.id}/submit`, { method: 'POST' });
+		await refresh();
+		toast({
+			title: `${receipt.merchant ?? receipt.filename} submitted for approval.`,
+			variant: 'success',
+		});
+	};
+
+	const submitAll = async () => {
+		const { submitted } = await $fetch<{ submitted: number }>(
+			'/api/receipts/submit-drafts',
+			{ method: 'POST' }
+		);
+		await refresh();
+		toast({
+			title: `${submitted} receipts submitted for approval.`,
+			variant: 'success',
+		});
+	};
+
+	const deleteReceipt = async (receipt: Receipt): Promise<boolean> => {
+		const ok = await confirm({
+			variant: 'destructive',
+			title: 'Remove receipt',
+			text: `Remove ${receipt.filename}? The file is deleted and cannot be recovered.`,
+			yes: 'Remove',
+			no: 'Cancel',
+		});
+		if (!ok) return false;
+		await $fetch(`/api/receipts/${receipt.id}`, { method: 'DELETE' });
+		await refresh();
+		toast({ title: `${receipt.filename} removed.`, variant: 'success' });
+		return true;
+	};
+
+	// Bulk actions read and clear the coopted table context themselves. Only
+	// draft receipt rows are selectable, so `selected` holds receipt ids.
+	const bulkIds = (): string[] => table.selected.value;
+	const clearSelection = () => {
+		table.selected.value = [];
+	};
+
+	const bulkCategorize = async (categoryId: string) => {
+		const ids = bulkIds();
+		await $fetch('/api/receipts/bulk/categorize', {
+			method: 'PATCH',
+			body: { ids, categoryId },
+		});
+		const category = categories.value.find((entry) => entry.id === categoryId);
+		clearSelection();
+		await refresh();
+		toast({
+			title: `${ids.length} receipts filed under ${category?.name ?? 'the selected category'}.`,
+			variant: 'success',
+		});
+	};
+
+	const bulkRemove = async () => {
+		const ids = bulkIds();
+		const ok = await confirm({
+			variant: 'destructive',
+			title: 'Remove receipts',
+			text: `Remove ${ids.length} receipts? Their files are deleted and cannot be recovered.`,
+			yes: 'Remove',
+			no: 'Cancel',
+		});
+		if (!ok) return;
+		await $fetch('/api/receipts/bulk/delete', {
+			method: 'POST',
+			body: { ids },
+		});
+		clearSelection();
+		await refresh();
+		toast({ title: `${ids.length} receipts removed.`, variant: 'success' });
+	};
+
+	const ctx: UploadCenterContext = {
+		shell,
+		table,
+		categories,
+		filters,
+		hasActiveFilters,
+		tab,
+		tabCounts,
+		readyCount,
+		uploads,
+		rows,
+		rowsPending,
+		searchMerchants,
+		peekReceipt,
+		stackReceipt,
+		stackMerchant,
+		clearFilters,
+		enqueueFiles,
+		retryUpload,
+		removeUpload,
+		updateReceipt,
+		submitReceipt,
+		submitAll,
+		deleteReceipt,
+		bulkCategorize,
+		bulkRemove,
+	};
+	provide(key, ctx);
+	return ctx;
+}
+
+export function useUploadCenter(): UploadCenterContext {
+	const ctx = inject(key);
+	if (!ctx) throw new Error('useUploadCenter() called outside UploadCenter');
+	return ctx;
+}
+```
+
+### Index.vue — the assembly
+
+```vue
+<!-- UploadCenter/Index.vue -->
+<template>
+	<PageShell>
+		<!-- Topbar: breadcrumbs left, page search + submit-all right. -->
+		<template #topbar>
+			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
+				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
+				     without it their overflow recompute fights the flex layout every frame. -->
+				<BbBreadcrumbs
+					class="min-w-0 flex-auto"
+					:items="[
+						{ key: 'dashboard', text: 'Dashboard', to: '/dashboard' },
+						{ key: 'expenses', text: 'Expenses', to: '/expenses' },
+						{ key: 'receipts', text: 'Receipts' },
+					]"
+				/>
+				<div class="flex shrink-0 items-center gap-2">
+					<BbTextInput
+						v-model="ctx.filters.search"
+						autocomplete="off"
+						clearable
+						compact
+						hide-label
+						label="Search receipts"
+						placeholder="Search merchant or filename…"
+						prepend:icon="lucide:search"
+					/>
+					<!-- The page's single primary: submit-all with a live count.
+					     BbButton tracks the async handler, so it shows its own
+					     loading state while the batch submits. -->
+					<BbButton
+						:disabled="ctx.readyCount.value === 0"
+						prepend:icon="lucide:send"
+						variant="primary"
+						@click="ctx.submitAll"
+					>
+						{{ submitLabel }}
+					</BbButton>
+				</div>
+			</div>
+		</template>
+
+		<div class="flex flex-col gap-3 p-4">
+			<!-- Capture surface: drafts tab only. -->
+			<ReceiptDropzone v-if="ctx.tab.value === 'drafts'" />
+
+			<FilterRail />
+
+			<!-- Tabs as URL filters: href updates the query, the key feeds the
+			     fetch. Counts come from the server on every fetch. -->
+			<BbTabs
+				v-model="ctx.tab.value"
+				compact
+				:items="[
+					{
+						key: 'drafts',
+						label: `Drafts · ${ctx.tabCounts.value.drafts}`,
+						href: '?tab=drafts',
+					},
+					{
+						key: 'submitted',
+						label: `Submitted · ${ctx.tabCounts.value.submitted}`,
+						href: '?tab=submitted',
+					},
+					{
+						key: 'reimbursed',
+						label: `Reimbursed · ${ctx.tabCounts.value.reimbursed}`,
+						href: '?tab=reimbursed',
+					},
+				]"
+			/>
+
+			<BbTable
+				id="receipts-table"
+				actions
+				caption="Expense receipts"
+				:columns="columns"
+				compact
+				item-value="id"
+				:items="ctx.rows.value"
+				:loading="ctx.rowsPending.value"
+				loading-text="Loading receipts…"
+				:row-class="rowClass"
+				:selectable="isDraft"
+			>
+				<!-- Clicking the NAME of a thing peeks it. -->
+				<template #filename="{ item }">
+					<ReceiptFileCell :row="item" />
+				</template>
+
+				<!-- Editable cells on draft rows; plain text everywhere else. -->
+				<template #merchant="{ item }">
+					<MerchantCell v-if="isDraft(item)" :receipt="item" />
+					<span
+						v-else-if="item.kind === 'upload'"
+						class="text-[color:var(--bb-text-muted)]"
+						>—</span
+					>
+					<span v-else>{{ item.merchant ?? '—' }}</span>
+				</template>
+
+				<template #categoryId="{ item }">
+					<CategoryCell v-if="isDraft(item)" :receipt="item" />
+					<span
+						v-else-if="item.kind === 'upload'"
+						class="text-[color:var(--bb-text-muted)]"
+						>—</span
+					>
+					<span v-else>{{ categoryName(item.categoryId) }}</span>
+				</template>
+
+				<template #amount="{ item }">
+					<AmountCell v-if="isDraft(item)" :receipt="item" />
+					<span
+						v-else-if="item.kind === 'upload'"
+						class="text-[color:var(--bb-text-muted)]"
+						>—</span
+					>
+					<span v-else>{{
+						item.amount === null ? '—' : currency.format(item.amount)
+					}}</span>
+				</template>
+
+				<template #date="{ item }">
+					<DateCell v-if="isDraft(item)" :receipt="item" />
+					<span
+						v-else-if="item.kind === 'upload'"
+						class="text-[color:var(--bb-text-muted)]"
+						>—</span
+					>
+					<span v-else>{{ item.date ? shortDate(item.date) : '—' }}</span>
+				</template>
+
+				<!-- Status column doubles as the transfer surface for queue rows. -->
+				<template #status="{ item }">
+					<UploadProgressCell v-if="item.kind === 'upload'" :upload="item" />
+					<BbBadge v-else variant="outline">{{ item.status }}</BbBadge>
+				</template>
+
+				<template #actions="{ item }">
+					<RowActions :row="item" />
+				</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.hasActiveFilters.value
+									? 'No receipts match the current filters.'
+									: ctx.tab.value === 'drafts'
+										? 'No drafts — drop receipts above to get started.'
+										: 'Nothing here yet.'
+							}}
+						</p>
+						<BbButton
+							v-if="ctx.hasActiveFilters.value"
+							variant="ghost"
+							@click="ctx.clearFilters"
+						>
+							Clear filters
+						</BbButton>
+					</div>
+				</template>
+			</BbTable>
+
+			<!-- Joins the table context by id: no page/totalPages wiring at all. -->
+			<BbPagination table-id="receipts-table" />
+		</div>
+
+		<SelectionBar />
+
+		<!-- Stacked peek sidebar: the shell owns back/close; we render by type. -->
+		<template #sidebar>
+			<ReceiptPeek
+				v-if="ctx.shell.current.value?.type === 'receipt'"
+				:receipt-id="ctx.shell.current.value.id"
+			/>
+			<MerchantPeek
+				v-else-if="ctx.shell.current.value?.type === 'merchant'"
+				:merchant-name="ctx.shell.current.value.name"
+			/>
+		</template>
+	</PageShell>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import {
+	BbBadge,
+	BbBreadcrumbs,
+	BbButton,
+	BbPagination,
+	BbTable,
+	BbTabs,
+	BbTextInput,
+} from 'bitboss-ui';
+import PageShell from '@/components/layout/PageShell.vue';
+import {
+	provideUploadCenter,
+	type ReceiptRow,
+	type UploadCenterRow,
+} from './context';
+import AmountCell from './AmountCell.vue';
+import CategoryCell from './CategoryCell.vue';
+import DateCell from './DateCell.vue';
+import FilterRail from './FilterRail.vue';
+import MerchantCell from './MerchantCell.vue';
+import MerchantPeek from './MerchantPeek.vue';
+import ReceiptDropzone from './ReceiptDropzone.vue';
+import ReceiptFileCell from './ReceiptFileCell.vue';
+import ReceiptPeek from './ReceiptPeek.vue';
+import RowActions from './RowActions.vue';
+import SelectionBar from './SelectionBar.vue';
+import UploadProgressCell from './UploadProgressCell.vue';
+
+const ctx = provideUploadCenter();
+
+const currency = new Intl.NumberFormat('en-US', {
+	style: 'currency',
+	currency: 'USD',
+});
+const shortDate = (value: string) =>
+	new Date(value).toLocaleDateString('en-US', {
+		month: 'short',
+		day: 'numeric',
+	});
+
+// Every cell renders through a slot, so columns stay label-only definitions.
+const columns = [
+	{ key: 'filename', label: 'Receipt' },
+	{ key: 'merchant', label: 'Merchant' },
+	{ key: 'categoryId', label: 'Category' },
+	{ key: 'amount', label: 'Amount', align: 'right' as const },
+	{ key: 'date', label: 'Date' },
+	{ key: 'status', label: 'Status' },
+];
+
+// Only server-side drafts are editable and selectable; queue rows and
+// submitted/reimbursed receipts are not.
+const isDraft = (item: UploadCenterRow): item is ReceiptRow =>
+	item.kind === 'receipt' && item.status === 'draft';
+
+// Failed transfers get a tinted row — public row-class API, no internals.
+const rowClass = (item: UploadCenterRow) =>
+	item.kind === 'upload' && item.failed
+		? 'bg-red-50 dark:bg-red-950/20'
+		: undefined;
+
+const categoryName = (categoryId: string | null) =>
+	ctx.categories.value.find((category) => category.id === categoryId)?.name ??
+	'—';
+
+const submitLabel = computed(() =>
+	ctx.readyCount.value === 0
+		? 'Submit receipts'
+		: `Submit ${ctx.readyCount.value} ${ctx.readyCount.value === 1 ? 'receipt' : 'receipts'}`
+);
+</script>
+```
+
+### ReceiptDropzone.vue
+
+```vue
+<!-- UploadCenter/ReceiptDropzone.vue -->
+<template>
+	<BbDropzone
+		v-model="pending"
+		:accept="ACCEPT"
+		:errors="dropError"
+		:max-files="20"
+		:max-size="MAX_SIZE"
+		multiple
+		@error="onError"
+	>
+		<template #default="{ dragging, focused, open }">
+			<div
+				class="flex flex-col items-center gap-2 rounded-[var(--bb-radius)] border-2 border-dashed p-6 text-center transition-colors"
+				:class="[
+					dragging ? 'border-[var(--bb-primary)]' : 'border-[var(--bb-border)]',
+					focused ? 'ring-2 ring-[var(--bb-primary)] ring-offset-2' : '',
+				]"
+			>
+				<BbIcon
+					class="text-[color:var(--bb-text-muted)]"
+					icon="lucide:receipt"
+					size="lg"
+				/>
+				<p class="text-sm font-medium">
+					{{ dragging ? 'Drop to add receipts' : 'Drop receipts here' }}
+				</p>
+				<p class="text-xs text-[color:var(--bb-text-muted)]">
+					JPG, PNG, HEIC or PDF · up to 10 MB each · 20 files per drop
+				</p>
+				<BbButton
+					prepend:icon="lucide:folder-open"
+					variant="ghost"
+					@click="open"
+				>
+					Browse files
+				</BbButton>
+			</div>
+		</template>
+	</BbDropzone>
+</template>
+
+<script setup lang="ts">
+import { ref, watch } from 'vue';
+import { BbButton, BbDropzone, BbIcon, type DropZoneError } from 'bitboss-ui';
+import { useUploadCenter } from './context';
+
+// Pair every extension with its MIME type: the MIME rule matches by content
+// type, the .ext rule catches drag-drops where the OS leaves file.type empty.
+const ACCEPT = [
+	'image/jpeg',
+	'.jpg',
+	'.jpeg',
+	'image/png',
+	'.png',
+	'image/heic',
+	'.heic',
+	'application/pdf',
+	'.pdf',
+];
+const MAX_SIZE = 10 * 1024 * 1024; // 10 MB per receipt
+
+const ctx = useUploadCenter();
+
+// BbDropzone captures and validates; the context uploads (posting FormData
+// through an XHR wrapper — see context.ts). The model is a hand-off buffer:
+// drain every validated batch into the queue, then clear it (which also
+// resets the duplicate check for future corrections).
+const pending = ref<File[]>([]);
+watch(pending, (files) => {
+	if (files.length === 0) return;
+	dropError.value = undefined;
+	ctx.enqueueFiles(files);
+	pending.value = [];
+});
+
+// The errors display is a round-trip: map each typed reject to a sentence
+// and feed it back through the `errors` prop (rendered in the built-in
+// aria-live region and referenced from the input's aria-describedby). Batch drops emit one error per file; showing the last
+// message keeps the surface calm.
+const dropError = ref<string | undefined>();
+const onError = (error: DropZoneError) => {
+	if (error.type === 'maxSize') {
+		dropError.value = `${error.filename} is ${error.formattedSize} — receipts are capped at ${error.formattedMaxSize}.`;
+	} else if (error.type === 'accept') {
+		dropError.value = `${error.filename} is not a JPG, PNG, HEIC or PDF.`;
+	} else if (error.type === 'uniqueness') {
+		dropError.value = `${error.filename} is already in this drop.`;
+	} else {
+		dropError.value = `That drop had ${error.totalFiles} files — add at most 20 at a time.`;
+	}
+};
+</script>
+```
+
+### FilterRail.vue
+
+```vue
+<!-- UploadCenter/FilterRail.vue -->
+<template>
+	<div class="flex flex-wrap items-center gap-2">
+		<!-- Category: multi-select pill over the coopted catalog. -->
+		<BbSelectPopover
+			v-model="ctx.filters.categoryIds"
+			item-text="name"
+			item-value="id"
+			:items="ctx.categories.value"
+			multiple
+			width="240px"
+		>
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					append:icon="lucide:chevron-down"
+					size="sm"
+					variant="outline"
+				>
+					Category{{
+						ctx.filters.categoryIds.length
+							? ` · ${ctx.filters.categoryIds.length}`
+							: ''
+					}}
+				</BbButton>
+			</template>
+		</BbSelectPopover>
+
+		<!-- Merchant: query-aware search. Merchant names are their own values,
+		     so the pill labels itself straight from the filter state. -->
+		<BbSelectPopover
+			v-model="ctx.filters.merchant"
+			:items="ctx.searchMerchants"
+			width="240px"
+		>
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					append:icon="lucide:chevron-down"
+					size="sm"
+					variant="outline"
+				>
+					{{ ctx.filters.merchant ?? 'Merchant' }}
+				</BbButton>
+			</template>
+		</BbSelectPopover>
+
+		<!-- Spent-between range: a compact input is 28px — flush with the pills. -->
+		<BbDatePickerInput
+			v-model="ctx.filters.spentBetween"
+			clearable
+			compact
+			floating
+			hide-label
+			label="Spent between"
+			placeholder="Spent between…"
+			range
+		/>
+
+		<!-- Clear-all renders only while something is active. -->
+		<BbButton
+			v-if="ctx.hasActiveFilters.value"
+			class="ml-auto"
+			prepend:icon="lucide:x"
+			size="sm"
+			variant="ghost"
+			@click="ctx.clearFilters"
+		>
+			Clear filters
+		</BbButton>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbButton, BbDatePickerInput, BbSelectPopover } from 'bitboss-ui';
+import { useUploadCenter } from './context';
+
+const ctx = useUploadCenter();
+</script>
+```
+
+### ReceiptFileCell.vue
+
+```vue
+<!-- UploadCenter/ReceiptFileCell.vue -->
+<template>
+	<div class="flex items-center gap-2">
+		<BbIcon
+			class="shrink-0 text-[color:var(--bb-text-muted)]"
+			:icon="fileIcon"
+			size="16"
+		/>
+		<div class="flex min-w-0 flex-col">
+			<!-- Server receipts peek on click; queue rows are not peekable yet. -->
+			<BbButton
+				v-if="row.kind === 'receipt'"
+				class="justify-start"
+				size="sm"
+				variant="link"
+				@click="() => ctx.peekReceipt(row.id)"
+			>
+				{{ row.filename }}
+			</BbButton>
+			<span v-else class="truncate text-sm">{{ row.filename }}</span>
+			<span class="text-xs text-[color:var(--bb-text-muted)]">{{
+				formattedSize
+			}}</span>
+		</div>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbButton, BbIcon } from 'bitboss-ui';
+import { useUploadCenter, type UploadCenterRow } from './context';
+
+const props = defineProps<{ row: UploadCenterRow }>();
+
+const ctx = useUploadCenter();
+
+const fileIcon = computed(() =>
+	props.row.filename.toLowerCase().endsWith('.pdf')
+		? 'lucide:file-text'
+		: 'lucide:image'
+);
+
+const formattedSize = computed(() => {
+	const bytes =
+		props.row.kind === 'upload' ? props.row.size : props.row.fileSize;
+	return bytes >= 1024 * 1024
+		? `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+		: `${Math.max(1, Math.round(bytes / 1024))} KB`;
+});
+</script>
+```
+
+### UploadProgressCell.vue
+
+```vue
+<!-- UploadCenter/UploadProgressCell.vue -->
+<template>
+	<!-- In flight: a live bar. `upload.progress` is a reactive field mutated
+	     by the context's progress callback — no refetch per tick. -->
+	<div v-if="!upload.failed" class="flex min-w-32 items-center gap-2">
+		<BbProgress
+			:aria-label="`Uploading ${upload.filename}`"
+			class="flex-1"
+			:model-value="upload.progress"
+		/>
+		<span class="text-xs tabular-nums text-[color:var(--bb-text-muted)]"
+			>{{ upload.progress }}%</span
+		>
+	</div>
+
+	<!-- Failed: say so and retry inline. `xs` is fine here — this is the
+	     densest surface on the page. -->
+	<div v-else class="flex items-center gap-2">
+		<span class="text-xs font-medium text-red-600 dark:text-red-400"
+			>Upload failed</span
+		>
+		<BbButton
+			prepend:icon="lucide:rotate-cw"
+			size="xs"
+			variant="outline"
+			@click="() => ctx.retryUpload(upload.id)"
+		>
+			Retry
+		</BbButton>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbButton, BbProgress } from 'bitboss-ui';
+import { useUploadCenter, type UploadRow } from './context';
+
+defineProps<{ upload: UploadRow }>();
+
+const ctx = useUploadCenter();
+</script>
+```
+
+### MerchantCell.vue
+
+```vue
+<!-- UploadCenter/MerchantCell.vue -->
+<template>
+	<BbTextInput
+		v-model="draft"
+		compact
+		hide-label
+		label="Merchant"
+		placeholder="Add merchant"
+		@blur="commit"
+		@keydown.enter="commit"
+		@keydown.esc="revert"
+	/>
+</template>
+
+<script setup lang="ts">
+import { ref, watch } from 'vue';
+import { BbTextInput } from 'bitboss-ui';
+import { useUploadCenter } from './context';
+import type { Receipt } from '@/types';
+
+const props = defineProps<{ receipt: Receipt }>();
+
+const ctx = useUploadCenter();
+
+// Inline-edit doctrine (§6.3): a local draft, commit on blur/Enter, revert
+// on Esc. The server value re-seeds the draft whenever a refetch updates the
+// row — which is also how a failed save reverts.
+const draft = ref<string | null>(props.receipt.merchant);
+watch(
+	() => props.receipt.merchant,
+	(value) => {
+		draft.value = value;
+	}
+);
+
+const commit = () => {
+	const merchant = draft.value?.trim() || null;
+	if (merchant === props.receipt.merchant) return;
+	void ctx.updateReceipt(props.receipt, { merchant });
+};
+const revert = () => {
+	draft.value = props.receipt.merchant;
+};
+</script>
+```
+
+### CategoryCell.vue
+
+```vue
+<!-- UploadCenter/CategoryCell.vue -->
+<template>
+	<BbSelectPopover
+		compact
+		disable-writing
+		item-text="name"
+		item-value="id"
+		:items="ctx.categories.value"
+		:model-value="receipt.categoryId"
+		width="220px"
+		@update:model-value="(categoryId) => pick(categoryId as string)"
+	>
+		<template #activator="{ props: activatorProps, shown }">
+			<!-- One-click pattern (§6.1): the badge is the focusable trigger —
+			     BbBadgeButton takes over the badge body, the trailing chevron says
+			     "this can change", and while the save runs `loading` swaps the
+			     spinner into the chevron's place. A category is a label, not a
+			     semantic status, so a set category reads neutral (`secondary`);
+			     only the unset state stays `outline` so empty cells read as
+			     quieter to-dos, not values. -->
+			<BbBadge
+				append:icon="lucide:chevron-down"
+				:class="{ 'category-cell--open': shown }"
+				:loading="saving"
+				:variant="receipt.categoryId ? 'secondary' : 'outline'"
+			>
+				<BbBadgeButton v-bind="activatorProps">{{
+					categoryName
+				}}</BbBadgeButton>
+			</BbBadge>
+		</template>
+	</BbSelectPopover>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
+import { useUploadCenter } from './context';
+import type { Receipt } from '@/types';
+
+const props = defineProps<{ receipt: Receipt }>();
+
+const ctx = useUploadCenter();
+
+// In-flight flag for the save feedback — rung-1 local state, not context.
+const saving = ref(false);
+const pick = async (categoryId: string) => {
+	saving.value = true;
+	try {
+		await ctx.updateReceipt(props.receipt, { categoryId });
+	} finally {
+		saving.value = false;
+	}
+};
+
+// The trigger labels itself from the coopted catalog, never from the
+// popover's lazy `text` slot prop.
+const categoryName = computed(
+	() =>
+		ctx.categories.value.find(
+			(category) => category.id === props.receipt.categoryId
+		)?.name ?? 'Set category'
+);
+</script>
+
+<style scoped>
+/* Open = the badge's own hue, deepened, plus its variant ring — the same
+   grammar as every badge-activator cell. */
+.category-cell--open {
+	--bg: color-mix(in oklab, var(--color) 24%, var(--bb-panel));
+	--border-color: color-mix(in oklab, var(--color) 45%, var(--bb-panel));
+	box-shadow: 0 0 0 var(--bb-ring-size) var(--ring);
+}
+</style>
+```
+
+### AmountCell.vue
+
+```vue
+<!-- UploadCenter/AmountCell.vue -->
+<template>
+	<BbNumberInput
+		v-model="draft"
+		compact
+		hide-label
+		label="Amount"
+		:max-precision="2"
+		:min="0"
+		placeholder="0.00"
+		@blur="commit"
+		@keydown.enter="commit"
+		@keydown.esc="revert"
+	>
+		<template #prefix>$</template>
+	</BbNumberInput>
+</template>
+
+<script setup lang="ts">
+import { ref, watch } from 'vue';
+import { BbNumberInput } from 'bitboss-ui';
+import { useUploadCenter } from './context';
+import type { Receipt } from '@/types';
+
+const props = defineProps<{ receipt: Receipt }>();
+
+const ctx = useUploadCenter();
+
+// Same commit/revert contract as the merchant cell, on the number model.
+const draft = ref<number | string | null>(props.receipt.amount);
+watch(
+	() => props.receipt.amount,
+	(value) => {
+		draft.value = value;
+	}
+);
+
+const commit = () => {
+	const amount =
+		draft.value === null || draft.value === '' ? null : Number(draft.value);
+	if (amount === props.receipt.amount) return;
+	void ctx.updateReceipt(props.receipt, { amount });
+};
+const revert = () => {
+	draft.value = props.receipt.amount;
+};
+</script>
+```
+
+### DateCell.vue
+
+```vue
+<!-- UploadCenter/DateCell.vue -->
+<template>
+	<!-- Picking a date IS the commit — no blur dance for calendar input.
+	     `floating` keeps the model a plain YYYY-MM-DD string. -->
+	<BbDatePickerInput
+		compact
+		floating
+		hide-label
+		label="Expense date"
+		:model-value="receipt.date"
+		placeholder="YYYY-MM-DD"
+		@update:model-value="commit"
+	/>
+</template>
+
+<script setup lang="ts">
+import { BbDatePickerInput } from 'bitboss-ui';
+import { useUploadCenter } from './context';
+import type { Receipt } from '@/types';
+
+const props = defineProps<{ receipt: Receipt }>();
+
+const ctx = useUploadCenter();
+
+const commit = (value: string | string[] | null) => {
+	const date = Array.isArray(value) ? (value[0] ?? null) : value;
+	if (date === props.receipt.date) return;
+	void ctx.updateReceipt(props.receipt, { date });
+};
+</script>
+```
+
+### RowActions.vue
+
+```vue
+<!-- UploadCenter/RowActions.vue -->
+<template>
+	<!-- Queue rows: one explicit remove (aborts the transfer). -->
+	<BbButton
+		v-if="row.kind === 'upload'"
+		:aria-label="`Remove ${row.filename} from the queue`"
+		icon="lucide:x"
+		size="sm"
+		variant="ghost"
+		@click="() => ctx.removeUpload(row.id)"
+	/>
+
+	<!-- Server receipts: contextual dropdown, entries vary by status. -->
+	<BbDropdown v-else :items="items">
+		<template #activator="{ props }">
+			<BbButton v-bind="props" icon="lucide:ellipsis" size="sm" variant="ghost">
+				Receipt actions
+			</BbButton>
+		</template>
+	</BbDropdown>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbButton, BbDropdown } from 'bitboss-ui';
+import { useUploadCenter, type UploadCenterRow } from './context';
+
+const props = defineProps<{ row: UploadCenterRow }>();
+
+const ctx = useUploadCenter();
+
+const items = computed(() => {
+	if (props.row.kind !== 'receipt') return [];
+	const receipt = props.row;
+	const isDraft = receipt.status === 'draft';
+	return [
+		...(isDraft
+			? [
+					{
+						key: 'submit',
+						text: 'Submit for approval',
+						'prepend:icon': 'lucide:send',
+						onClick: () => ctx.submitReceipt(receipt),
+					},
+				]
+			: []),
+		{
+			// A real file download, not a Nuxt page — a raw `href` triggers a
+			// normal browser navigation instead of being intercepted by the
+			// router, which is what a client-side `to` would otherwise do.
+			key: 'download',
+			text: 'Download original',
+			'prepend:icon': 'lucide:download',
+			href: `/receipts/${receipt.id}/file`,
+		},
+		...(isDraft
+			? [
+					{
+						key: 'remove',
+						text: 'Remove',
+						'prepend:icon': 'lucide:trash-2',
+						variant: 'destructive' as const,
+						onClick: () => ctx.deleteReceipt(receipt),
+					},
+				]
+			: []),
+	];
+});
+</script>
+```
+
+### SelectionBar.vue
+
+```vue
+<!-- UploadCenter/SelectionBar.vue -->
+<template>
+	<FloatingBottomPanel :open="selectedCount > 0">
+		<span class="px-2 text-sm">{{ selectedCount }} selected</span>
+
+		<!-- Bulk categorize: the picker lives right in the bar — a one-shot
+		     popover (model stays null) whose selection IS the action. -->
+		<BbSelectPopover
+			item-text="name"
+			item-value="id"
+			:items="ctx.categories.value"
+			:model-value="null"
+			placement="top"
+			width="220px"
+			@update:model-value="
+				(categoryId) => categoryId && ctx.bulkCategorize(categoryId)
+			"
+		>
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					prepend:icon="lucide:tag"
+					size="sm"
+					variant="ghost"
+				>
+					Set category
+				</BbButton>
+			</template>
+		</BbSelectPopover>
+
+		<div class="floating-bottom-panel__right flex items-center gap-1">
+			<BbButton size="sm" variant="destructive" @click="ctx.bulkRemove"
+				>Remove</BbButton
+			>
+			<BbButton
+				aria-label="Clear selection"
+				icon="lucide:x"
+				size="sm"
+				variant="ghost"
+				@click="clearSelection"
+			/>
+		</div>
+	</FloatingBottomPanel>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbButton, BbSelectPopover } from 'bitboss-ui';
+import FloatingBottomPanel from '@/components/layout/FloatingBottomPanel.vue';
+import { useUploadCenter } from './context';
+
+const ctx = useUploadCenter();
+
+const selectedCount = computed(() => ctx.table.selected.value?.length ?? 0);
+const clearSelection = () => {
+	ctx.table.selected.value = [];
+};
+</script>
+```
+
+### ReceiptPeek.vue
+
+```vue
+<!-- UploadCenter/ReceiptPeek.vue -->
+<template>
+	<div v-if="receipt" class="flex flex-col gap-4 text-sm">
+		<!-- Header: merchant identity + amount + status. The merchant name
+		     drills DOWN — stacked peek, back arrow via the shell. -->
+		<header class="flex flex-col gap-1.5">
+			<div class="flex items-center justify-between gap-2">
+				<BbButton
+					v-if="receipt.merchant"
+					size="sm"
+					variant="link"
+					@click="() => ctx.stackMerchant(receipt!.merchant!)"
+				>
+					{{ receipt.merchant }}
+				</BbButton>
+				<span v-else class="text-[color:var(--bb-text-muted)]"
+					>No merchant yet</span
+				>
+				<BbBadge variant="outline">{{ receipt.status }}</BbBadge>
+			</div>
+			<p class="text-xl font-semibold">
+				{{
+					receipt.amount === null
+						? 'Amount missing'
+						: currency.format(receipt.amount)
+				}}
+			</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				{{ receipt.filename }} · spent
+				{{ receipt.date ? longDate(receipt.date) : '—' }}
+			</p>
+		</header>
+
+		<!-- Preview placeholder: the real app renders the scanned image here. -->
+		<div
+			class="flex h-44 flex-col items-center justify-center gap-1 rounded-[var(--bb-radius)] border bg-[var(--bb-panel)] text-[color:var(--bb-text-muted)]"
+		>
+			<BbIcon icon="lucide:receipt" size="lg" />
+			<span class="text-xs">Receipt preview</span>
+		</div>
+
+		<!-- Extracted fields: what OCR read off the scan, with confidence. -->
+		<section class="flex flex-col gap-1.5">
+			<div class="flex items-center justify-between">
+				<h3
+					class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
+				>
+					Extracted fields
+				</h3>
+				<BbBadge size="xs" variant="outline">{{
+					`OCR · ${receipt.extracted.confidence}%`
+				}}</BbBadge>
+			</div>
+			<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
+				<dt class="text-[color:var(--bb-text-muted)]">Merchant</dt>
+				<dd>{{ receipt.extracted.merchant ?? '—' }}</dd>
+				<dt class="text-[color:var(--bb-text-muted)]">Total</dt>
+				<dd>
+					{{
+						receipt.extracted.total === null
+							? '—'
+							: currency.format(receipt.extracted.total)
+					}}
+				</dd>
+				<dt class="text-[color:var(--bb-text-muted)]">Tax</dt>
+				<dd>
+					{{
+						receipt.extracted.tax === null
+							? '—'
+							: currency.format(receipt.extracted.tax)
+					}}
+				</dd>
+				<dt class="text-[color:var(--bb-text-muted)]">Date</dt>
+				<dd>
+					{{ receipt.extracted.date ? longDate(receipt.extracted.date) : '—' }}
+				</dd>
+				<dt class="text-[color:var(--bb-text-muted)]">Paid with</dt>
+				<dd>{{ receipt.extracted.paymentMethod ?? '—' }}</dd>
+			</dl>
+		</section>
+
+		<!-- Properties: the peek is a workbench — the category is the same
+		     one-click cell as in the table. -->
+		<section class="flex flex-col gap-1.5">
+			<h3
+				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
+			>
+				Details
+			</h3>
+			<dl class="grid grid-cols-[auto_1fr] items-center gap-x-4 gap-y-1.5">
+				<dt class="text-[color:var(--bb-text-muted)]">Category</dt>
+				<dd><CategoryCell :receipt="receipt" /></dd>
+				<dt class="text-[color:var(--bb-text-muted)]">Uploaded</dt>
+				<dd>{{ longDate(receipt.uploadedAt) }}</dd>
+				<dt class="text-[color:var(--bb-text-muted)]">Report</dt>
+				<dd>{{ receipt.reportName ?? 'Not on a report yet' }}</dd>
+			</dl>
+		</section>
+
+		<!-- Activity feed. -->
+		<section class="flex flex-col gap-1.5">
+			<h3
+				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
+			>
+				Activity
+			</h3>
+			<ul class="flex flex-col gap-2">
+				<li
+					v-for="entry in receipt.activity"
+					:key="entry.id"
+					class="flex gap-2"
+				>
+					<BbIcon
+						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
+						:icon="entry.icon"
+						size="14"
+					/>
+					<div class="flex flex-col">
+						<span>{{ entry.text }}</span>
+						<span class="text-xs text-[color:var(--bb-text-muted)]"
+							>{{ entry.actor }} · {{ longDate(entry.at) }}</span
+						>
+					</div>
+				</li>
+			</ul>
+		</section>
+
+		<!-- Act here, or leave for the original file. -->
+		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
+			<BbButton
+				v-if="receipt.status === 'draft'"
+				prepend:icon="lucide:send"
+				size="sm"
+				variant="secondary"
+				@click="() => ctx.submitReceipt(receipt!)"
+			>
+				Submit
+			</BbButton>
+			<!-- A real file download, not a Nuxt page — stays a raw `href`. -->
+			<BbButton
+				append:icon="lucide:arrow-up-right"
+				:href="`/receipts/${receipt.id}/file`"
+				size="sm"
+				variant="ghost"
+			>
+				Download original
+			</BbButton>
+			<BbButton
+				v-if="receipt.status === 'draft'"
+				class="ml-auto"
+				prepend:icon="lucide:trash-2"
+				size="sm"
+				variant="destructive"
+				@click="removeAndClose"
+			>
+				Remove
+			</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 { BbBadge, BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
+import CategoryCell from './CategoryCell.vue';
+import { useUploadCenter } from './context';
+import type { ReceiptDetail } from '@/types';
+
+const props = defineProps<{ receiptId: string }>();
+
+const ctx = useUploadCenter();
+
+// Re-fetches whenever the stack shows a different receipt; `ctx.rows` changes
+// on every server `refresh()` (mutations) or upload completion, so watching
+// it makes inline edits (category, submit) reflect here immediately.
+const receipt = ref<ReceiptDetail | null>(null);
+watchEffect(async () => {
+	void ctx.rows.value;
+	receipt.value = await $fetch<ReceiptDetail>(
+		`/api/receipts/${props.receiptId}`
+	);
+});
+
+// deleteReceipt resolves true only when the confirm was accepted — don't
+// close the peek on a cancelled dialog.
+const removeAndClose = async () => {
+	if (!receipt.value) return;
+	if (await ctx.deleteReceipt(receipt.value)) ctx.shell.close();
+};
+
+const currency = new Intl.NumberFormat('en-US', {
+	style: 'currency',
+	currency: 'USD',
+});
+const longDate = (value: string) =>
+	new Date(value).toLocaleDateString('en-US', {
+		month: 'short',
+		day: 'numeric',
+		year: 'numeric',
+	});
+</script>
+```
+
+### MerchantPeek.vue
+
+```vue
+<!-- UploadCenter/MerchantPeek.vue -->
+<template>
+	<div v-if="merchant" class="flex flex-col gap-4 text-sm">
+		<header class="flex items-center gap-3">
+			<div
+				class="grid h-9 w-9 shrink-0 place-items-center rounded-[var(--bb-radius)] border"
+			>
+				<BbIcon
+					class="text-[color:var(--bb-text-muted)]"
+					icon="lucide:store"
+					size="18"
+				/>
+			</div>
+			<div class="flex flex-col">
+				<h2 class="text-base font-semibold">{{ merchant.name }}</h2>
+				<p class="text-xs text-[color:var(--bb-text-muted)]">
+					{{ merchant.defaultCategoryName }} · this year
+				</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 spent</p>
+				<p class="font-semibold">{{ currency.format(merchant.totalSpent) }}</p>
+			</div>
+			<div class="rounded-[var(--bb-radius)] border p-2">
+				<p class="text-xs text-[color:var(--bb-text-muted)]">Receipts</p>
+				<p class="font-semibold">{{ merchant.receiptCount }}</p>
+			</div>
+			<div class="rounded-[var(--bb-radius)] border p-2">
+				<p class="text-xs text-[color:var(--bb-text-muted)]">Average</p>
+				<p class="font-semibold">
+					{{ currency.format(merchant.averageAmount) }}
+				</p>
+			</div>
+		</div>
+
+		<!-- Recent receipts: names drill down again — the stack keeps growing. -->
+		<section class="flex flex-col gap-1.5">
+			<h3
+				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
+			>
+				Recent receipts
+			</h3>
+			<ul class="flex flex-col">
+				<li
+					v-for="recent in merchant.recentReceipts"
+					:key="recent.id"
+					class="flex items-center justify-between gap-2 border-b py-1.5 last:border-b-0"
+				>
+					<BbButton
+						size="sm"
+						variant="link"
+						@click="() => ctx.stackReceipt(recent.id)"
+					>
+						{{ recent.filename }}
+					</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">
+			<!-- An internal listing page — a real Nuxt route, so this uses `to`. -->
+			<BbButton
+				append:icon="lucide:arrow-up-right"
+				size="sm"
+				:to="`/expenses/receipts?merchant=${encodeURIComponent(merchant.name)}`"
+				variant="ghost"
+			>
+				All receipts from {{ merchant.name }}
+			</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 { BbBadge, BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
+import { useUploadCenter } from './context';
+import type { MerchantSummary } from '@/types';
+
+const props = defineProps<{ merchantName: string }>();
+
+const ctx = useUploadCenter();
+
+const merchant = ref<MerchantSummary | null>(null);
+watchEffect(async () => {
+	merchant.value = await $fetch<MerchantSummary>(
+		`/api/merchants/${encodeURIComponent(props.merchantName)}`
+	);
+});
+
+const currency = new Intl.NumberFormat('en-US', {
+	style: 'currency',
+	currency: 'USD',
+});
+</script>
+```
+
+## Why it is built this way
+
+- **The context coopts, leaves consume.** `shell`, `table` **and the
+  category catalog** are joined once in `provideUploadCenter()`; thirteen
+  components share the filters, the queue, selection, the peek stack and
+  every action through one `useUploadCenter()` call. No leaf imports
+  `$fetch`, `@/api` or a store directly — even the query-aware merchant
+  pill gets its provider (`ctx.searchMerchants`) from the context, so the
+  page has exactly one import surface.
+- **The URL is the filter store, `useAsyncData` is the fetch.** Filters
+  and tab are seeded from `route.query` once at setup, mirrored back with
+  `navigateTo` on every change (debounced for free text), and
+  `useAsyncData('receipts', …, { watch: [() => route.query, table.page] })`
+  is the single refetch trigger for the _server_ page — there is exactly
+  one place server data loads.
+- **The upload queue crosses the data-layer swap untouched.** It was
+  always client-only reactive state, so it needed no adaptation: `uploads`
+  stays a plain `ref`, progress ticks still mutate the row objects in
+  place, and `rows` (a computed merging `uploads` ahead of the fetched
+  `serverRows`) is what `BbTable` binds to directly — no items function, no
+  `dependencies`, no `refreshKey`. A completed upload's own `refresh()`
+  call is what swaps it into `serverRows` on the next tick.
+- **`$fetch` can't stream upload progress, so the transfer itself doesn't
+  use it.** `api.receipts.upload()` posts `FormData` through a small XHR
+  wrapper instead — the only place this recipe steps outside `$fetch` —
+  while every other mutation (`updateReceipt`, `submitReceipt`, the bulk
+  actions) is a plain `$fetch` call followed by `await refresh()`.
+- **The table context still owns paging and selection.** `useBbTableContext`
+  is unchanged from the Vue recipe: it seeds `perPage`, `BbPagination`
+  joins by `table-id`, and `SelectionBar` reads `table.selected` — only the
+  _server_ rows move from an items-function to a resolved array merged
+  into `rows`.
+- **Peeks watch `ctx.rows.value`, not a manual refresh counter.** Since
+  every mutation already calls the list's `refresh()`, and `rows` recomputes
+  whenever the underlying `data` changes, a peek's `watchEffect(() => {
+void ctx.rows.value; … })` re-fetches its own JSON detail for free — the
+  same signal drives both surfaces.
+- **`peekX` vs `stackX` is the whole stack grammar.** Filename →
+  `peekReceipt` (replaces the stack); merchant name inside the peek →
+  `stackMerchant` (pushes, back arrow appears); a recent receipt inside
+  the merchant peek → `stackReceipt` (deeper still). The grammar lives in
+  the context — a leaf cannot accidentally nuke the stack.
+- **Tabs carry `href` and live counts**, exactly as in the Vue recipe — the
+  client-side pushState they perform keeps `route.query.tab` in sync, which
+  is what seeds `tab` on load and what `useAsyncData`'s `route.query` watch
+  reacts to.
+- **Internal links use `to`; real file downloads stay `href`.** The
+  merchant peek's "All receipts from…" link is a genuine Nuxt route, so it
+  uses `to` for client-side navigation. "Download original" (row `…`, peek
+  footer) hits a raw file-serving endpoint, not a page — it deliberately
+  keeps a plain `href` so the browser performs a real download instead of
+  the router trying to resolve it as a route.
+- **Sizing:** topbar follows `md`-first (`compact` search at 28px flush
+  beside the default-size primary); `sm` appears exactly where the
+  doctrine allows — row actions, pills, peek footers, the bulk bar — and
+  the one `xs` (inline Retry) sits inside a table cell, the densest
+  surface on the page. **One `variant="primary"`** (Submit all, with its
+  live count and auto-tracked loading). Destructive actions — single,
+  bulk, in-peek — all ride `useConfirm` with the filename or count in the
+  message.
+
+## Variations
+
+- **Expense reports**: group receipts into named reports (a `reportId`
+  column + a "Add to report" bulk action feeding a `BbSelectPopover` of
+  open reports); the Submit-all primary becomes "Submit report".
+- **Policy checks**: server flags out-of-policy drafts
+  (`receipt.policyWarning`); tint the row, badge the amount cell, and
+  render a `BbAlert` above the table summarizing the count.
+- **Camera-first mobile**: keep `accept` image-heavy and rely on the
+  native picker offering the camera; the dropzone slot collapses to a
+  single "Snap a receipt" affordance under the mobile breakpoint.
+- **Auto-submit on high confidence**: when `extracted.confidence` ≥ 95 and
+  all four fields resolved, submit server-side on upload and toast an
+  undo — the Drafts tab then only holds receipts needing review.
+- **SSR-populated peeks**: swap the peeks' `$fetch` calls for
+  `useAsyncData` keyed by id if the peek content should be part of the
+  server-rendered payload rather than a client-side follow-up fetch.