bitboss-ui 2.1.134 → 3.0.0-alpha.1

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

@@ -0,0 +1,1926 @@
+---
+title: Upload Center (Inertia)
+summary: Full-anatomy expense-receipts upload center for Laravel + Inertia — multi-file dropzone into an inline-editable table (text, category popover, amount, date cells), per-file progress with inline retry via a direct axios/fetch upload path, submit-all with count via promise-wrapped visits, bulk bottom panel, and a stacked receipt/merchant peek sidebar, all through one page context that coopts the Inertia Helpers toolkit.
+---
+
+# Recipe: Upload Center (Inertia)
+
+The Expensify-grade expense receipts submission page adapted for **Laravel +
+Inertia**: 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 the drafts page is a page prop, filters mirror into the URL
+through [`useQueryObject`](../../guides/inertia-helpers.md), selection and
+paging come from the keyed [`useTableContext`](../../guides/inertia-helpers.md),
+and field edits/submit/bulk actions are promise-wrapped `router.visit`
+calls. The raw file transfer itself stays outside Inertia entirely — visits
+cannot stream per-file progress for a background queue — so uploads keep a
+direct axios/fetch path and finish with a partial reload. 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) ·
+[Nuxt](../nuxt/upload-center.md).
+
+## Prerequisites
+
+- `<BbConfirm />` and `<BbToast />` mounted once in the app layout.
+- From the [Inertia Helpers](../../guides/inertia-helpers.md) toolkit:
+  `useTableContext`, `useQueryObject`, `useResourceContext`.
+- 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).
+- Controller: `Inertia::render('Receipts/Index', ['receipts' =>
+ReceiptPaginator::make(...), 'tabCounts' => [...], 'readyCount' => ...])` —
+  `receipts` is a standard Laravel paginator (`PaginatedResponse<Receipt>`),
+  `tabCounts` a plain `{ drafts, submitted, reimbursed }` map, `readyCount`
+  the number of drafts complete enough to submit. All three are re-sent on
+  every partial reload the page triggers
+  (`only: ['receipts', 'tabCounts', 'readyCount']`). Mutation routes are
+  plain Laravel routes (`PATCH /receipts/:id`, `POST /receipts/:id/submit`,
+  …) that redirect back; small JSON GET endpoints (`GET /receipts/:id/peek`,
+  `GET /merchants/:name/peek`, `GET /merchants/search`) back the sidebar
+  peeks and the merchant filter so opening one is not a full-page visit.
+  `POST /receipts/upload` accepts a single `multipart/form-data` file and is
+  hit directly (not through Inertia) so the client can read upload progress.
+
+## Key ideas
+
+- **One coopting page context.** `provideUploadCenter()` joins the
+  page-shell stack **and** the keyed `useTableContext('receipts')` once,
+  coopts the shared category catalog from `useCategoriesStore()`, owns the
+  URL-mirrored filters/tab and the **upload queue**, and exposes complete
+  actions. Every leaf calls `useUploadCenter()` and nothing else.
+- **The server page has no client-side fetch at all.** `receipts` arrives
+  as a page prop; `useTableContext('receipts')` turns it into `items` +
+  `totalItems`/`page`/`perPage` (URL-backed) + `selected`/`unselected`/`all`
+  (select-all-across-pages); the context merges the live upload queue ahead
+  of those items in a computed (`rows`) that `BbTable` binds to directly.
+- **Filters mirror into the URL with `useQueryObject`.** Typing in a pill
+  filter performs a debounced partial Inertia visit
+  (`only: ['receipts', 'tabCounts', 'readyCount']`); the server is the
+  single source of filtered, paginated truth for the drafts/submitted/
+  reimbursed rows.
+- **Tabs are real visits.** `BbTabs` items carry `href` + `server: true`
+  (component-level `navigation` is required alongside it) so switching tabs
+  is a genuine, partial-reloaded Inertia visit — not a client-only URL
+  change.
+- **Capture and transfer are two layers, and transfer never touches
+  Inertia.** `BbDropzone` only validates and hands over `File[]`; the
+  context drains the dropzone's model into `ctx.enqueueFiles()` and runs
+  the uploads itself. Inertia visits have no upload-progress events for a
+  background queue, so each transfer is a direct axios/fetch call (an
+  `AbortController` + progress callback per file, same call shape as the
+  other platforms) that finishes with a plain `router.reload({ only: […] })`
+  instead of a data-carrying visit.
+- **Mutations are promise-wrapped `router.visit` calls.** A tiny local
+  `visit()` helper turns Inertia's callback-based API into a promise, so
+  context actions stay `async function`s exactly like the Vue/Nuxt
+  versions — `await ctx.updateReceipt(...)` reads the same everywhere.
+- **Clicking the name of a thing peeks it**, fetched from a small JSON
+  endpoint via `useResourceContext` — not a full-page visit, so opening the
+  sidebar never replaces the drafts table underneath it.
+- **Buttons are `md` by default** (28px, flush beside `compact` inputs);
+  `sm`/`xs` only in the table rows, the peeks' headers and the bottom bar.
+  Real file downloads (`Download original`) set `target="_blank"` so
+  `BbButton` renders a plain anchor instead of letting Inertia intercept a
+  same-origin `href` as a visit — a raw file response would otherwise be
+  swallowed by the Inertia request/response cycle.
+
+## Page anatomy
+
+```
+UploadCenter/
+	Index.vue              ← assembly: PageShell slots, dropzone, tabs, table, pagination
+	context.ts              ← coopting page context (shell + useTableContext + 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()` → direct axios/fetch upload + partial reload    |
+| 2   | Retry a failed upload             | inline in the progress cell        | `retryUpload(id)` re-issues the same direct request              |
+| 3   | Remove an in-flight upload        | row actions (x)                    | `removeUpload(id)` aborts + drops the row                        |
+| 4   | Page search                       | topbar right                       | `filters.search` → `useQueryObject` partial visit                |
+| 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                        | server-visit tabs with counts      | `BbTabs` `href` + `server: true` visit                           |
+| 8   | Edit merchant inline              | merchant cell                      | commit on blur/Enter → promise-wrapped visit, Esc reverts (§6.3) |
+| 9   | Change category one-click         | category badge in row & peek       | `BbSelectPopover` on the badge (§6.1) → promise-wrapped visit    |
+| 10  | Edit amount inline                | amount cell ($ prefix)             | commit on blur/Enter → promise-wrapped visit, Esc reverts        |
+| 11  | Edit expense date inline          | date cell                          | commit on pick → promise-wrapped visit                           |
+| 12  | Submit one receipt                | row `…`, peek footer               | `submitReceipt()` (visit + 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`/`all`/`unselected`        |
+| 16  | Bulk remove                       | floating bottom panel              | destructive behind `useConfirm`, count in message                |
+| 17  | Select rows / select all          | table checkboxes (drafts only)     | `useTableContext` selection (across pages)                       |
+| 18  | Peek receipt                      | filename cell / merchant peek list | `peekReceipt(id)` → shell stack, JSON fetch                      |
+| 19  | Peek merchant (stacked)           | merchant name inside the peek      | `stackMerchant(name)` → back arrow, JSON fetch                   |
+| 20  | Download original                 | row `…`, peek footer               | navigation (`target="_blank"`, real file endpoint)               |
+
+## The code
+
+### context.ts
+
+```ts
+// UploadCenter/context.ts
+import {
+	computed,
+	inject,
+	provide,
+	reactive,
+	ref,
+	type ComputedRef,
+	type InjectionKey,
+	type Ref,
+} from 'vue';
+import { router } from '@inertiajs/vue3';
+import type { RequestPayload } from '@inertiajs/core';
+import { useConfirm, useToast, type BadgeVariantType } from 'bitboss-ui';
+import {
+	usePageShellContext,
+	type PageShellContext,
+} from '@/components/layout/usePageShellContext';
+import {
+	useTableContext,
+	type TableContext,
+} from '@/composables/useTableContext';
+import { useQueryObject } from '@/composables/useQueryObject';
+import { useProp } from '@/composables/useProp';
+import { useQuery } from '@/composables/useQuery';
+import { 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'>
+>;
+
+const RELOAD_PROPS = ['receipts', 'tabCounts', 'readyCount'] as const;
+
+// -- 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: TableContext<Receipt, string>;
+	/** 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[]>;
+	/** Bumped after every mutation — peeks watch it to re-fetch their JSON detail. */
+	refreshKey: Ref<number>;
+	// -- Data --------------------------------------------------------------------
+	/** Drafts tab: queue rows first, then the fetched server page. */
+	rows: ComputedRef<UploadCenterRow[]>;
+	searchMerchants: (query: string) => Promise<string[]>;
+	// -- Peek grammar ----------------------------------------------------------
+	peekReceipt: (id: string) => void;
+	stackReceipt: (id: string) => void;
+	stackMerchant: (name: string) => void;
+	// -- Actions (complete: visit/reload + 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(',');
+};
+
+/** Inertia's callback-based visit, wrapped as a promise — so every context
+ * action stays `async`, exactly like the Vue/Nuxt versions. Always a
+ * partial reload of the props this page depends on. */
+const visit = (
+	method: 'post' | 'put' | 'patch' | 'delete',
+	url: string,
+	// Inertia's own payload type — strings/numbers/booleans/arrays/files.
+	// (`Record<string, unknown>` does not satisfy it.)
+	data: RequestPayload = {}
+): Promise<void> =>
+	new Promise((resolve, reject) => {
+		router.visit(url, {
+			method,
+			data,
+			only: [...RELOAD_PROPS],
+			preserveScroll: true,
+			preserveState: true,
+			onSuccess: () => resolve(),
+			onError: (errors) => reject(errors),
+		});
+	});
+
+export function provideUploadCenter(): UploadCenterContext {
+	const { toast } = useToast();
+	const { confirm } = useConfirm();
+
+	// -- Coopt the specific contexts: once, here, for the whole page. ----------
+	const shell = usePageShellContext<PeekItem>();
+	// `Receipt, string`: BbTable's `item-value="id"` resolves selection to
+	// receipt ids ('rcp_…'), matching the Vue/Nuxt `table.selected: string[]` shape.
+	const table = useTableContext<Receipt, string>('receipts');
+	const categoriesStore = useCategoriesStore();
+	const categories = computed(() => categoriesStore.categories);
+
+	// -- Filters: seeded from the current URL, mirrored back by useQueryObject. -
+	const query = useQuery();
+	const filters = reactive<ReceiptFilters>({
+		search: (query.search as string) ?? '',
+		categoryIds: toArray(query.categoryIds) ?? [],
+		merchant: (query.merchant as string) ?? null,
+		spentBetween: toArray(query.spentBetween) ?? [],
+	});
+	useQueryObject(filters, { only: [...RELOAD_PROPS] });
+
+	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 = [];
+	};
+
+	// Tab: seeded from the URL; BbTabs' own `href` + `server` visit updates
+	// the URL, and its `v-model` write keeps this ref in sync with the click.
+	const tab = ref<UploadCenterTab>((query.tab as UploadCenterTab) ?? 'drafts');
+	const tabCounts = useProp<Record<UploadCenterTab, number>>('tabCounts');
+	const readyCount = useProp<number>('readyCount');
+
+	const refreshKey = ref(0);
+	const refresh = () => {
+		refreshKey.value++;
+	};
+
+	// -- Data ---------------------------------------------------------------------
+	// The live upload queue is client-only reactive state — it is NOT part of
+	// the `receipts` prop. `rows` merges it above the fetched page for the
+	// Drafts tab; `BbTable` binds to `rows` directly (no items function).
+	const uploads = ref<UploadRow[]>([]);
+	const rows = computed<UploadCenterRow[]>(() => {
+		const serverRows = table.items.value.map(
+			(receipt): ReceiptRow => ({ ...receipt, kind: 'receipt' })
+		);
+		return tab.value === 'drafts'
+			? [...uploads.value, ...serverRows]
+			: serverRows;
+	});
+
+	const searchMerchants = (search: string): Promise<string[]> =>
+		fetch(`/merchants/search?q=${encodeURIComponent(search)}`).then((res) =>
+			res.json()
+		);
+
+	// -- Upload machinery ----------------------------------------------------------
+	// Inertia visits cannot stream per-file progress for a background queue, so
+	// each transfer is a direct axios/fetch call (not router.visit) — the same
+	// call shape as the other platforms — that finishes with a plain partial
+	// reload instead of a data-carrying visit. The queue rows themselves are
+	// reactive: progress ticks mutate them in place and `rows` above re-derives
+	// on every push/filter, no reload needed for that. 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 {
+			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 partial reload swaps the rows.
+			uploads.value = uploads.value.filter((upload) => upload.id !== id);
+			uploadFiles.delete(id);
+			router.reload({ only: [...RELOAD_PROPS] });
+		} 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 visit('patch', `/receipts/${receipt.id}`, { ...patch });
+			refresh(); // silent on success — the cell already shows the new value
+		} catch {
+			refresh(); // the reload 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 visit('post', `/receipts/${receipt.id}/submit`);
+		refresh();
+		toast({
+			title: `${receipt.merchant ?? receipt.filename} submitted for approval.`,
+			variant: 'success',
+		});
+	};
+
+	const submitAll = async () => {
+		await visit('post', '/receipts/submit-drafts');
+		refresh();
+		toast({
+			title: `${readyCount.value} 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 visit('delete', `/receipts/${receipt.id}`);
+		refresh();
+		toast({ title: `${receipt.filename} removed.`, variant: 'success' });
+		return true;
+	};
+
+	// Bulk actions carry the full select-all-across-pages payload — the
+	// server combines `all` + `unselected` the same way BbTable does.
+	const bulkPayload = () => ({
+		ids: table.selected.value,
+		all: table.all.value,
+		unselected: table.unselected.value,
+	});
+	const bulkCount = () =>
+		table.all.value
+			? table.totalItems.value - table.unselected.value.length
+			: table.selected.value.length;
+
+	const bulkCategorize = async (categoryId: string) => {
+		const count = bulkCount();
+		await visit('patch', '/receipts/bulk/categorize', {
+			...bulkPayload(),
+			categoryId,
+		});
+		const category = categories.value.find((entry) => entry.id === categoryId);
+		table.resetSelection();
+		refresh();
+		toast({
+			title: `${count} receipts filed under ${category?.name ?? 'the selected category'}.`,
+			variant: 'success',
+		});
+	};
+
+	const bulkRemove = async () => {
+		const count = bulkCount();
+		const ok = await confirm({
+			variant: 'destructive',
+			title: 'Remove receipts',
+			text: `Remove ${count} receipts? Their files are deleted and cannot be recovered.`,
+			yes: 'Remove',
+			no: 'Cancel',
+		});
+		if (!ok) return;
+		await visit('post', '/receipts/bulk/delete', bulkPayload());
+		table.resetSelection();
+		refresh();
+		toast({ title: `${count} receipts removed.`, variant: 'success' });
+	};
+
+	const ctx: UploadCenterContext = {
+		shell,
+		table,
+		categories,
+		filters,
+		hasActiveFilters,
+		tab,
+		tabCounts,
+		readyCount,
+		uploads,
+		refreshKey,
+		rows,
+		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', href: '/dashboard' },
+						{ key: 'expenses', text: 'Expenses', href: '/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 are real visits: href + server (component-level `navigation`
+			     is required alongside per-item `server`), each carrying the same
+			     partial-reload prop list as the filter watcher. -->
+			<BbTabs
+				v-model="ctx.tab.value"
+				compact
+				navigation
+				preserve-scroll
+				preserve-state
+				replace
+				:items="[
+					{
+						key: 'drafts',
+						label: `Drafts · ${ctx.tabCounts.value.drafts}`,
+						href: '/receipts?tab=drafts',
+						server: true,
+						only: ['receipts', 'tabCounts', 'readyCount'],
+					},
+					{
+						key: 'submitted',
+						label: `Submitted · ${ctx.tabCounts.value.submitted}`,
+						href: '/receipts?tab=submitted',
+						server: true,
+						only: ['receipts', 'tabCounts', 'readyCount'],
+					},
+					{
+						key: 'reimbursed',
+						label: `Reimbursed · ${ctx.tabCounts.value.reimbursed}`,
+						href: '/receipts?tab=reimbursed',
+						server: true,
+						only: ['receipts', 'tabCounts', 'readyCount'],
+					},
+				]"
+			/>
+
+			<!-- No dependencies/items-fn: `receipts` is a page prop, `rows` merges
+			     the live upload queue above it, and selection (across pages) binds
+			     straight onto the keyed table context. -->
+			<BbTable
+				v-model="ctx.table.selected.value"
+				v-model:select-all="ctx.table.all.value"
+				v-model:unselected-items="ctx.table.unselected.value"
+				actions
+				caption="Expense receipts"
+				:columns="columns"
+				compact
+				item-value="id"
+				:items="ctx.rows.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-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>
+
+			<!-- No table-id: the keyed table context is the page count here. -->
+			<BbPagination
+				v-model="ctx.table.page.value"
+				label="Receipts pagination"
+				:total-pages="ctx.table.totalPages.value"
+			/>
+		</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 through a direct
+// axios/fetch path (Inertia visits can't stream progress). 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. Searchable, so
+		     the filter clears from inside the popover search. -->
+		<BbSelectPopover
+			v-model="ctx.filters.categoryIds"
+			clearable
+			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 against a small JSON endpoint, not an
+		     Inertia visit — searching a filter pill must not re-render the page.
+		     Merchant names are their own values, so the pill labels itself
+		     straight from the filter state; searchable, so it clears
+		     in-popover. -->
+		<BbSelectPopover
+			v-model="ctx.filters.merchant"
+			clearable
+			: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 reload 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();
+
+/** Money cells always show two decimals so the column optically aligns. */
+const formatMoney = (value: number | null): string | null =>
+	value === null || Number.isNaN(value) ? null : value.toFixed(2);
+
+// Same commit/revert contract as the merchant cell, on the number model.
+const draft = ref<number | string | null>(formatMoney(props.receipt.amount));
+watch(
+	() => props.receipt.amount,
+	(value) => {
+		draft.value = formatMoney(value);
+	}
+);
+
+const commit = () => {
+	const amount =
+		draft.value === null || draft.value === '' ? null : Number(draft.value);
+	if (amount === props.receipt.amount) {
+		draft.value = formatMoney(props.receipt.amount);
+		return;
+	}
+	void ctx.updateReceipt(props.receipt, { amount });
+	draft.value = formatMoney(amount);
+};
+const revert = () => {
+	draft.value = formatMoney(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 an Inertia page — `target` forces
+			// BbButton to render a plain anchor instead of letting Inertia
+			// intercept this same-origin `href` as a visit (see BbBaseButton's
+			// routing rules).
+			key: 'download',
+			text: 'Download original',
+			'prepend:icon': 'lucide:download',
+			href: `/receipts/${receipt.id}/file`,
+			target: '_blank',
+		},
+		...(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 text-gray-500">
+			<span class="font-semibold tabular-nums">{{ selectedCount }}</span>
+			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"
+			:offset="10"
+			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
+				v-bb-tooltip="{ text: 'Clear selection', delay: 400 }"
+				aria-label="Clear selection"
+				icon="lucide:x"
+				size="sm"
+				variant="ghost"
+				@click="ctx.table.resetSelection"
+			/>
+		</div>
+	</FloatingBottomPanel>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbButton, BbSelectPopover, vBbTooltip } from 'bitboss-ui';
+import { useUploadCenter } from './context';
+import FloatingBottomPanel from '@/components/layout/FloatingBottomPanel.vue';
+
+const ctx = useUploadCenter();
+
+// `all` (select-all-across-pages) does not enumerate rows, so the visible
+// count is the total minus whatever the user manually deselected.
+const selectedCount = computed(() =>
+	ctx.table.all.value
+		? ctx.table.totalItems.value - ctx.table.unselected.value.length
+		: ctx.table.selected.value.length
+);
+</script>
+```
+
+### 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="STATUS_VARIANT[receipt.status]">{{
+					STATUS_LABEL[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>
+			<!-- A real file download, not an Inertia page — `target` forces a
+			     plain anchor instead of an Inertia visit. -->
+			<BbButton
+				append:icon="lucide:arrow-up-right"
+				:href="`/receipts/${receipt.id}/file`"
+				size="sm"
+				target="_blank"
+				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 { watch } from 'vue';
+import { BbBadge, BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
+import { useResourceContext } from '@/composables/useResourceContext';
+import CategoryCell from './CategoryCell.vue';
+import { STATUS_LABEL, STATUS_VARIANT, useUploadCenter } from './context';
+import type { ReceiptDetail } from '@/types';
+
+const props = defineProps<{ receiptId: string }>();
+
+const ctx = useUploadCenter();
+
+// A small JSON endpoint, not a page visit — opening the peek never
+// re-renders the drafts table underneath it. Re-fetches whenever the stack
+// shows a different receipt; `refreshKey` makes mutations (category,
+// submit) and completed uploads reflect here immediately.
+const { data: receipt, refresh } = useResourceContext<ReceiptDetail, string>(
+	() => props.receiptId,
+	(id) => fetch(`/receipts/${id}/peek`).then((res) => res.json())
+);
+watch(() => ctx.refreshKey.value, refresh);
+
+// 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="STATUS_VARIANT[recent.status]">{{
+						STATUS_LABEL[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">
+			<!-- An internal listing page — same-origin `href` auto-upgrades to an
+			     Inertia visit (§3a); no `target` needed here. -->
+			<BbButton
+				append:icon="lucide:arrow-up-right"
+				:href="`/expenses/receipts?merchant=${encodeURIComponent(merchant.name)}`"
+				size="sm"
+				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 { BbBadge, BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
+import { useResourceContext } from '@/composables/useResourceContext';
+import { STATUS_LABEL, STATUS_VARIANT, useUploadCenter } from './context';
+import type { MerchantSummary } from '@/types';
+
+const props = defineProps<{ merchantName: string }>();
+
+const ctx = useUploadCenter();
+
+const { data: merchant } = useResourceContext<MerchantSummary, string>(
+	() => props.merchantName,
+	(name) =>
+		fetch(`/merchants/${encodeURIComponent(name)}/peek`).then((res) =>
+			res.json()
+		)
+);
+
+const currency = new Intl.NumberFormat('en-US', {
+	style: 'currency',
+	currency: 'USD',
+});
+</script>
+```
+
+## Why it is built this way
+
+- **The context coopts, leaves consume.** `shell` and the keyed
+  `useTableContext('receipts')` 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`, `fetch` or a store directly — even the query-aware
+  merchant pill gets its provider (`ctx.searchMerchants`) from the context.
+- **`receipts` is a page prop, not a client fetch.** `useTableContext`
+  turns the Laravel paginator into `items`/`totalItems`/`page`/`perPage`
+  (URL-backed) plus `selected`/`unselected`/`all`; `BbTable` binds directly
+  to `rows` (the queue merged ahead of `table.items`) with
+  `v-model`/`v-model:select-all`/`v-model:unselected-items` — there is no
+  items function and no `dependencies` array, because the server already
+  did the filtering, sorting and paging before the props arrived.
+- **The upload queue crosses the data-layer swap untouched.** It was
+  always client-only reactive state, so it needed no adaptation beyond
+  where it merges: `uploads` stays a plain `ref`, progress ticks still
+  mutate the row objects in place, and `rows` (a computed combining
+  `uploads` with `table.items`) is what `BbTable` binds to — Vue's own
+  reactivity re-renders the one cell reading a progress tick, no reload
+  involved.
+- **Inertia visits can't stream upload progress, so the transfer itself
+  doesn't use one.** `api.receipts.upload()` posts `FormData` through a
+  direct axios/fetch call — an `AbortController` + progress callback per
+  file, same shape as the other platforms — and finishes with a plain
+  `router.reload({ only: [...RELOAD_PROPS] })` instead of a data-carrying
+  visit, since a completed upload only needs the fresh paginator, not a
+  navigation.
+- **One watcher for filters, one visit mechanism for tabs.**
+  `useQueryObject(filters, { only: ['receipts', 'tabCounts', 'readyCount'] })`
+  is the entire filter-to-URL wiring; `BbTabs`' `href` + `server: true`
+  items (with the required component-level `navigation`) make tab switches
+  real, partial-reloaded visits with the same `only` list — one source of
+  server truth, reached two ways.
+- **The `visit()` helper is the promise-wrapped router-visit pattern** the
+  base's adaptation notes call for: it turns Inertia's
+  `onSuccess`/`onError` callbacks into a promise so every context action
+  (`updateReceipt`, `submitReceipt`, the bulk actions, …) stays an `async
+function` — identical call sites to the Vue/Nuxt recipes,
+  `await ctx.updateReceipt(...)`.
+- **Bulk actions carry the full select-all-across-pages payload**
+  (`ids`/`all`/`unselected`) so "select all, deselect three, categorize"
+  sends the same semantics the table itself models — never just an
+  enumerated id list that silently drops rows outside the current page.
+- **Peeks are JSON fetches, not visits.** `useResourceContext` re-fetches
+  on id change and exposes a `refresh()` the peek re-runs whenever
+  `ctx.refreshKey` bumps (every mutation and every completed upload bumps
+  it) — opening or updating a peek never re-renders the drafts page
+  underneath it.
+- **`peekX` vs `stackX` is the whole stack grammar.** Fresh peeks replace,
+  drill-downs push; the shell renders the back arrow when depth > 1. The
+  grammar lives in the context — a leaf cannot accidentally nuke the
+  stack.
+- **Real file downloads set `target`, internal pages don't.** Inertia
+  auto-upgrades any same-origin `href` without a `target` into a visit
+  (§3a) — correct for the merchant peek's "All receipts from…" link, but
+  wrong for "Download original": a raw file response fed through the
+  Inertia request cycle would never reach the browser as a download.
+  Setting `target="_blank"` makes `BbBaseButton` fall back to a plain
+  anchor for exactly those two links (the row `…` dropdown and the peek
+  footer).
+- **Sizing:** topbar and rail follow `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.
+- **Lazy tab counts**: if `tabCounts`/`readyCount` are expensive to
+  compute, share them as `Inertia::lazy()` and read them with
+  `useLazyProp` instead of a plain prop — the tab labels and the submit-all
+  button resolve once the data lands instead of blocking the first render.