bitboss-ui 2.1.134 → 3.0.0-alpha.1

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

@@ -0,0 +1,1806 @@
+---
+title: Upload Center (Vue)
+summary: Full-anatomy expense-receipts upload center for a vue-router SPA — 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, all through one coopting page context.
+---
+
+# Recipe: Upload Center (Vue)
+
+An Expensify-grade expense receipts submission page for a **plain Vue SPA
+with vue-router**, at full standard anatomy: a 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.
+
+Sibling recipes: [Nuxt](../nuxt/upload-center.md) ·
+[Inertia](../inertia/upload-center.md).
+
+## Prerequisites
+
+- `<BbConfirm />` and `<BbToast />` mounted once in the app root.
+- [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).
+- The registered `soft-*` badge variants (`soft-gray` / `soft-amber` /
+  `soft-green`) from the [Inline Edit Workspace](./inline-edit-workspace.md)
+  recipe — the receipt-status maps in `context.ts` use them
+  (design-language § Using color).
+
+## 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 filters, the tab, and the
+  **upload queue**, and exposes complete actions. Every leaf calls
+  `useUploadCenter()` and nothing else.
+- **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()`. The component never uploads — that is
+  its documented contract.
+- **The drafts table lists two kinds of rows.** In-flight/failed uploads
+  (`kind: 'upload'`, local state) render above the server drafts
+  (`kind: 'receipt'`, fetched). Progress ticks mutate the live row objects
+  — no refetch per tick; only membership changes (enqueue, remove,
+  completion) bump `refreshKey`.
+- **Every draft cell edits in place.** Merchant is a text cell committing
+  on blur/Enter (§6.3), category is a one-click badge popover (§6.1),
+  amount is a `$`-prefixed number cell, date commits on pick. Each cell
+  type is its own leaf with a single `receipt` prop; failed saves revert
+  via refetch 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) with preview placeholder, extracted OCR fields and
+  activity; the merchant name inside the peek → merchant peek **stacked**
+  with a back arrow, whose recent receipts drill back down.
+- **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.
+
+- **Spread the filters object into `dependencies`.** `BbTable` hash-compares
+  `dependencies`; it does not deep-watch them. Passing the reactive `filters`
+  proxy itself tracks only its identity — which never changes — so the table
+  never refetches. `{ ...ctx.filters }` reads every field during render, so any
+  field change yields a new, differently-hashed array. Read `.value` off the
+  refs for the same reason: context members are not auto-unwrapped in a template.
+
+## Page anatomy
+
+```
+UploadCenter/
+	Index.vue              ← assembly: PageShell slots, dropzone, tabs, table, pagination
+	context.ts              ← coopting page context (shell + table + categories + 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` → fetch dependency                   |
+| 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 + fetch dependency                                |
+| 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()` (API + 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 (`/receipts/:id/file`)                     |
+
+## The code
+
+### context.ts
+
+```ts
+// UploadCenter/context.ts
+import {
+	computed,
+	inject,
+	provide,
+	reactive,
+	ref,
+	type ComputedRef,
+	type InjectionKey,
+	type Ref,
+} from 'vue';
+import {
+	useBbTableContext,
+	useConfirm,
+	useToast,
+	type BadgeVariantType,
+	type BbTableContext,
+} from 'bitboss-ui';
+import {
+	usePageShellContext,
+	type PageShellContext,
+} from '@/components/layout/usePageShellContext';
+import { useCategoriesStore } from '@/stores/categories';
+import { api } from '@/api';
+import type { Category, Receipt, ReceiptStatus } 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'>
+>;
+
+// -- Receipt-status badge maps: one closed set, mapped once for the whole page.
+// The receipt lifecycle (table rows, the receipt peek header, the merchant
+// peek's recent list) is a small closed set — the textbook case for the soft
+// accents (design-language.md § Using color), registered via badge-variants.d.ts.
+// draft = idle/neutral, submitted = pending approval, reimbursed = done.
+export const STATUS_LABEL: Record<ReceiptStatus, string> = {
+	draft: 'Draft',
+	submitted: 'Submitted',
+	reimbursed: 'Reimbursed',
+};
+export const STATUS_VARIANT: Record<ReceiptStatus, BadgeVariantType> = {
+	draft: 'soft-gray',
+	submitted: 'soft-amber',
+	reimbursed: 'soft-green',
+};
+
+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: Ref<Record<UploadCenterTab, number>>;
+	/** Drafts that are complete (merchant + category + amount + date). */
+	readyCount: Ref<number>;
+	/** The live upload queue — in-flight and failed transfers. */
+	uploads: Ref<UploadRow[]>;
+	refreshKey: Ref<number>;
+	// -- Data ------------------------------------------------------------------
+	fetchRows: () => Promise<UploadCenterRow[]>;
+	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');
+
+export function provideUploadCenter(): UploadCenterContext {
+	const { toast } = useToast();
+	const { confirm } = useConfirm();
+
+	// -- 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);
+	// A shared catalog store does not seed itself just by being read. Kick the
+	// load here (idempotent — the store dedupes on an in-flight promise), or the
+	// category cells and the bulk-categorize popover stay permanently empty.
+	void categoriesStore.load();
+
+	// -- Page state -------------------------------------------------------------
+	const filters = reactive<ReceiptFilters>({
+		search: '',
+		categoryIds: [],
+		merchant: null,
+		spentBetween: [],
+	});
+	const hasActiveFilters = computed(
+		() =>
+			filters.search !== '' ||
+			filters.categoryIds.length > 0 ||
+			filters.merchant !== null ||
+			filters.spentBetween.length > 0
+	);
+	const tab = ref<UploadCenterTab>('drafts');
+	const tabCounts = ref<Record<UploadCenterTab, number>>({
+		drafts: 0,
+		submitted: 0,
+		reimbursed: 0,
+	});
+	const readyCount = ref(0);
+	const refreshKey = ref(0);
+
+	const clearFilters = () => {
+		filters.search = '';
+		filters.categoryIds = [];
+		filters.merchant = null;
+		filters.spentBetween = [];
+	};
+
+	const refresh = () => {
+		refreshKey.value++;
+	};
+
+	// -- Data ---------------------------------------------------------------------
+	// The one place the list is fetched. Writes the paging totals into the
+	// table context and keeps the tab counts and submit-all count live. 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', … }
+	// On the Drafts tab the live upload queue renders above the fetched page.
+	const uploads = ref<UploadRow[]>([]);
+
+	const fetchRows = async (): Promise<UploadCenterRow[]> => {
+		const response = await api.receipts.list({
+			...filters,
+			tab: tab.value,
+			page: table.page.value,
+			perPage: table.perPage.value,
+		});
+		table.total.value = response.total;
+		tabCounts.value = response.tabCounts;
+		readyCount.value = response.readyCount;
+		const rows = response.data.map(
+			(receipt): ReceiptRow => ({ ...receipt, kind: 'receipt' })
+		);
+		return tab.value === 'drafts' ? [...uploads.value, ...rows] : rows;
+	};
+
+	const searchMerchants = (query: string): Promise<string[]> =>
+		api.merchants.search(query);
+
+	// -- Upload machinery ----------------------------------------------------------
+	// The queue rows are reactive: progress ticks mutate them in place and the
+	// rendered cells update without a refetch. Only membership changes
+	// (enqueue, remove, completion) bump refreshKey so the table re-runs its
+	// items function. Files and abort controllers live in closure maps — they
+	// are 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 {
+			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 refetch swaps the rows.
+			uploads.value = uploads.value.filter((upload) => upload.id !== id);
+			uploadFiles.delete(id);
+			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);
+		}
+		refresh();
+	};
+
+	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);
+		refresh();
+	};
+
+	// -- 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 api.receipts.update(receipt.id, patch);
+			refresh(); // silent on success — the cell already shows the new value
+		} catch {
+			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 api.receipts.submit(receipt.id);
+		refresh();
+		toast({
+			title: `${receipt.merchant ?? receipt.filename} submitted for approval.`,
+			variant: 'success',
+		});
+	};
+
+	const submitAll = async () => {
+		const { submitted } = await api.receipts.submitDrafts();
+		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 api.receipts.delete(receipt.id);
+		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 api.receipts.categorizeMany(ids, categoryId);
+		const category = categories.value.find((entry) => entry.id === categoryId);
+		clearSelection();
+		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 api.receipts.deleteMany(ids);
+		clearSelection();
+		refresh();
+		toast({ title: `${ids.length} receipts removed.`, variant: 'success' });
+	};
+
+	const ctx: UploadCenterContext = {
+		shell,
+		table,
+		categories,
+		filters,
+		hasActiveFilters,
+		tab,
+		tabCounts,
+		readyCount,
+		uploads,
+		refreshKey,
+		fetchRows,
+		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"
+						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
+				:dependencies="[
+					{ ...ctx.filters },
+					ctx.tab.value,
+					ctx.refreshKey.value,
+				]"
+				:deps-debounce-time="300"
+				item-value="id"
+				:items="ctx.fetchRows"
+				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-gray-400"
+						>—</span
+					>
+					<span v-else>{{ item.merchant ?? '—' }}</span>
+				</template>
+
+				<!-- Slot names are normalized: `categoryId` → `#categoryid`. -->
+				<template #categoryid="{ item }">
+					<CategoryCell v-if="isDraft(item)" :receipt="item" />
+					<span v-else-if="item.kind === 'upload'" class="text-gray-400"
+						>—</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-gray-400"
+						>—</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-gray-400"
+						>—</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="STATUS_VARIANT[item.status]">{{
+						STATUS_LABEL[item.status]
+					}}</BbBadge>
+				</template>
+
+				<template #actions="{ item }">
+					<RowActions :row="item" />
+				</template>
+
+				<template #no-data>
+					<div class="flex flex-col items-center gap-2 p-8 text-center">
+						<BbIcon
+							aria-hidden="true"
+							class="text-gray-400"
+							:icon="
+								ctx.hasActiveFilters.value
+									? 'lucide:search-x'
+									: 'lucide:receipt'
+							"
+							size="2xl"
+						/>
+						<p class="text-sm font-semibold">
+							{{
+								ctx.hasActiveFilters.value
+									? 'No matching receipts'
+									: ctx.tab.value === 'drafts'
+										? 'No drafts yet'
+										: 'Nothing in this tab yet'
+							}}
+						</p>
+						<p class="text-xs text-gray-500">
+							{{
+								ctx.hasActiveFilters.value
+									? 'Loosen a filter above, or switch tabs to widen the view.'
+									: ctx.tab.value === 'drafts'
+										? 'Drop receipts above to get started.'
+										: 'Submitted and reimbursed receipts land in their own tabs.'
+							}}
+						</p>
+						<BbButton
+							v-if="ctx.hasActiveFilters.value"
+							prepend:icon="lucide:x"
+							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,
+	BbIcon,
+	BbPagination,
+	BbTable,
+	BbTabs,
+	BbTextInput,
+} from 'bitboss-ui';
+import PageShell from '@/components/layout/PageShell.vue';
+import {
+	provideUploadCenter,
+	STATUS_LABEL,
+	STATUS_VARIANT,
+	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. The narrow predicate keeps the
+// `v-else` (non-draft receipt) branch a real `ReceiptRow`, not `never`.
+const isDraft = (
+	item: UploadCenterRow
+): item is ReceiptRow & { status: 'draft' } =>
+	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-gray-400" 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-gray-500">
+					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. 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). 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-gray-400" :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-gray-500">{{ 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-gray-500"
+			>{{ 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),
+					},
+				]
+			: []),
+		{
+			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-gray-500">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-gray-500">
+				{{ 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-gray-400"
+		>
+			<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-gray-500">
+					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-gray-500">Merchant</dt>
+				<dd>{{ receipt.extracted.merchant ?? '—' }}</dd>
+				<dt class="text-gray-500">Total</dt>
+				<dd>
+					{{
+						receipt.extracted.total === null
+							? '—'
+							: currency.format(receipt.extracted.total)
+					}}
+				</dd>
+				<dt class="text-gray-500">Tax</dt>
+				<dd>
+					{{
+						receipt.extracted.tax === null
+							? '—'
+							: currency.format(receipt.extracted.tax)
+					}}
+				</dd>
+				<dt class="text-gray-500">Date</dt>
+				<dd>
+					{{ receipt.extracted.date ? longDate(receipt.extracted.date) : '—' }}
+				</dd>
+				<dt class="text-gray-500">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-gray-500">
+				Details
+			</h3>
+			<dl class="grid grid-cols-[auto_1fr] items-center gap-x-4 gap-y-1.5">
+				<dt class="text-gray-500">Category</dt>
+				<dd><CategoryCell :receipt="receipt" /></dd>
+				<dt class="text-gray-500">Uploaded</dt>
+				<dd>{{ longDate(receipt.uploadedAt) }}</dd>
+				<dt class="text-gray-500">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-gray-500">
+				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-gray-400"
+						:icon="entry.icon"
+						size="14"
+					/>
+					<div class="flex flex-col">
+						<span>{{ entry.text }}</span>
+						<span class="text-xs text-gray-500"
+							>{{ entry.actor }} · {{ longDate(entry.at) }}</span
+						>
+					</div>
+				</li>
+			</ul>
+		</section>
+
+		<!-- 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>
+			<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 { api } from '@/api';
+import type { ReceiptDetail } from '@/types';
+
+const props = defineProps<{ receiptId: string }>();
+
+const ctx = useUploadCenter();
+
+// Re-fetches whenever the stack shows a different receipt; refreshKey makes
+// inline edits (category, submit) reflect here immediately.
+const receipt = ref<ReceiptDetail | null>(null);
+watchEffect(async () => {
+	void ctx.refreshKey.value;
+	receipt.value = await api.receipts.get(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-gray-400" 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-gray-500">
+					{{ 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-gray-500">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-gray-500">Receipts</p>
+				<p class="font-semibold">{{ merchant.receiptCount }}</p>
+			</div>
+			<div class="rounded-[var(--bb-radius)] border p-2">
+				<p class="text-xs text-gray-500">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-gray-500">
+				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-gray-500">
+						{{ currency.format(recent.amount) }}
+					</span>
+				</li>
+			</ul>
+		</section>
+
+		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
+			<BbButton
+				append:icon="lucide:arrow-up-right"
+				size="sm"
+				:to="`/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 { api } from '@/api';
+import type { MerchantSummary } from '@/types';
+
+const props = defineProps<{ merchantName: string }>();
+
+const ctx = useUploadCenter();
+
+const merchant = ref<MerchantSummary | null>(null);
+watchEffect(async () => {
+	merchant.value = await api.merchants.get(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
+  `@/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.
+- **Capture ≠ transfer.** `BbDropzone`'s documented contract is "these
+  files are valid", nothing more: no request, no progress, no retry. So
+  the dropzone leaf drains its model into `ctx.enqueueFiles()` and resets
+  it, and the context owns the whole transfer lifecycle — one
+  `AbortController` per file in a closure map (not render state), a
+  progress callback writing into the reactive queue row, retry as a plain
+  re-issue of the same upload. Constraint rejects never reach the model;
+  they arrive as typed `@error` events that the leaf maps to sentences and
+  feeds back through `errors` (the display is a round-trip by design).
+- **Progress ticks don't refetch.** The items function returns the _live_
+  queue row objects ahead of the fetched page, so a progress mutation
+  re-renders exactly the one cell reading it. Membership changes —
+  enqueue, remove, upload completed — are the only events that bump
+  `refreshKey`; a completed upload re-enters as a server draft with the
+  OCR-extracted fields prefilled, which is the row's "done" feedback (no
+  per-file success toast for a 15-file drop).
+- **Each editable cell type is its own leaf** — `MerchantCell`,
+  `CategoryCell`, `AmountCell`, `DateCell` — never one `EditableCell` with
+  a `type` prop. All four take exactly one data prop (`receipt`) and call
+  one context action; the text/number cells hold a local draft (rung 1)
+  with commit-on-blur/Enter and Esc-revert, the option/date cells commit
+  on pick. Failed saves converge on the same path: `updateReceipt`
+  refetches (reverting the cell to the server value) and toasts
+  `destructive`.
+- **The table context is the paging and selection spine.**
+  `useBbTableContext('receipts-table', { perPage: 25 })` seeds paging;
+  `fetchRows` writes `table.total`; `BbPagination table-id` joins by id;
+  the bulk bar reads `table.selected` with zero props from the table. The
+  `selectable` predicate limits selection to server-side drafts, so bulk
+  ids are always submittable receipt ids.
+- **Tabs carry `href` and live counts** (`?tab=drafts`) and the same table
+  is the pane — outside Drafts the cell slots fall through to plain
+  formatted text, so Submitted/Reimbursed are read-only views of the same
+  columns rather than a second table component.
+- **`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. The peek is a
+  workbench: one-click category (the same `CategoryCell`), submit,
+  download, confirm-guarded remove.
+- **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.