bitboss-ui 3.0.0-beta.5 → 3.0.0-beta.50

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

@@ -36,8 +36,8 @@ Sibling recipes: [Vue](../vue/upload-center.md) ·
   the peek stack, the close semantics and the sidebar's out-of-flow
   behaviour are all load-bearing here.
 - `<BbConfirm />` and `<BbToast />` mounted once in the `createInertiaApp` render root — never in a page.
-- From the [Inertia Helpers](../../guides/inertia-helpers.md) toolkit:
-  `useTableContext`, `useQueryObject`, `useResourceContext`.
+- From the [Inertia Helpers](../../guides/inertia-helpers.md) toolkit, installed with
+  `npx bitboss-ui add useProp useQuery useQueryObject useResourceContext useTableContext`.
 - A `useCategoriesStore()` Pinia store exposing the shared expense-category
   catalog (Travel, Meals & entertainment, Lodging, Rideshare & transit,
   Software & subscriptions, Office supplies, Fuel, Client entertainment).
@@ -111,15 +111,15 @@ ReceiptPaginator::make(...), 'tabCounts' => [...], 'readyCount' => ...])` —
 ## Page anatomy
 
 ```
-UploadCenter/
+resources/js/pages/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)
+	MerchantCell.vue        ← inline text edit, commit on blur/Enter (inline-editing table)
+	CategoryCell.vue        ← one-click badge → BbSelectPopover (one-click status cell)
 	AmountCell.vue           ← inline number edit with $ prefix
 	DateCell.vue             ← date picker cell, commit on pick
 	RowActions.vue           ← remove-from-queue / per-receipt "…" dropdown
@@ -134,35 +134,35 @@ Chrome assumed from the guides: [App Layout](../../guides/app-layout.md)
 
 ## Action inventory
 
-| #   | Action                            | Trigger                            | Mechanism                                                        |
-| --- | --------------------------------- | ---------------------------------- | ---------------------------------------------------------------- |
-| 1   | Upload receipts                   | dropzone (drag, click, Browse)     | `enqueueFiles()` → direct fetch/XHR 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)               |
+| #   | Action                            | Trigger                            | Mechanism                                                                        |
+| --- | --------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------- |
+| 1   | Upload receipts                   | dropzone (drag, click, Browse)     | `enqueueFiles()` → direct fetch/XHR 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 (inline-editing table) |
+| 9   | Change category one-click         | category badge in row & peek       | `BbSelectPopover` on the badge (one-click status cell) → 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
+// pages/UploadCenter/context.ts
 import {
 	computed,
 	inject,
@@ -175,7 +175,12 @@ import {
 } from 'vue';
 import { router } from '@inertiajs/vue3';
 import type { RequestPayload } from '@inertiajs/core';
-import { useConfirm, useToast, type BadgeVariantType } from 'bitboss-ui';
+import {
+	useConfirm,
+	useToast,
+	type BadgeVariantType,
+	type BbSelectPopoverItemsContext,
+} from 'bitboss-ui';
 import {
 	usePageShellContext,
 	type PageShellContext,
@@ -183,18 +188,22 @@ import {
 import {
 	useTableContext,
 	type TableContext,
-} from '@/composables/useTableContext';
-import { useQueryObject } from '@/composables/useQueryObject';
-import { useProp } from '@/composables/useProp';
-import { useQuery } from '@/composables/useQuery';
+} from '@/composables/inertia-helpers/useTableContext';
+import { useQueryObject } from '@/composables/inertia-helpers/useQueryObject';
+import { useProp } from '@/composables/inertia-helpers/useProp';
+import { useQuery } from '@/composables/inertia-helpers/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. */
+/**
+ * What the stacked sidebar can show. Clicking a name pushes one of these.
+ * `title` names the sidebar (`#sidebar-title`) before the record's own fetch
+ * has resolved: the caller passes the name it is rendering.
+ */
 export type PeekItem =
-	| { type: 'receipt'; id: string }
-	| { type: 'merchant'; name: string };
+	| { type: 'receipt'; id: string; title: string }
+	| { type: 'merchant'; name: string; title: string };
 
 export type UploadCenterTab = 'drafts' | 'submitted' | 'reimbursed';
 
@@ -237,7 +246,7 @@ 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.
+// accents (design-language.md § Using color), registered with the plugin's badgeVariants option.
 // draft = idle/neutral, submitted = pending approval, reimbursed = done.
 export const STATUS_LABEL: Record<ReceiptStatus, string> = {
 	draft: 'Draft',
@@ -270,10 +279,10 @@ export interface UploadCenterContext {
 	// -- Data --------------------------------------------------------------------
 	/** Drafts tab: queue rows first, then the fetched server page. */
 	rows: ComputedRef<UploadCenterRow[]>;
-	searchMerchants: (query: string) => Promise<string[]>;
+	searchMerchants: (context: BbSelectPopoverItemsContext) => Promise<string[]>;
 	// -- Peek grammar ----------------------------------------------------------
-	peekReceipt: (id: string) => void;
-	stackReceipt: (id: string) => void;
+	peekReceipt: (id: string, title: string) => void;
+	stackReceipt: (id: string, title: string) => void;
 	stackMerchant: (name: string) => void;
 	// -- Actions (complete: visit/reload + refresh + toast) ----------------------
 	clearFilters: () => void;
@@ -380,10 +389,21 @@ export function provideUploadCenter(): UploadCenterContext {
 			: serverRows;
 	});
 
-	const searchMerchants = (search: string): Promise<string[]> =>
-		fetch(`/merchants/search?q=${encodeURIComponent(search)}`).then((res) =>
-			res.json()
+	// The merchant pill's provider: one context object, `query` is the typed
+	// text and `signal` cancels a request a newer keystroke supersedes. `fetch`
+	// resolves on a 4xx/5xx too, hence the `res.ok` check: a failed search
+	// throws, so the popover shows its failed state.
+	const searchMerchants = async ({
+		query,
+		signal,
+	}: BbSelectPopoverItemsContext): Promise<string[]> => {
+		const res = await fetch(
+			`/merchants/search?q=${encodeURIComponent(query)}`,
+			{ signal }
 		);
+		if (!res.ok) throw new Error(`Merchant search failed (${res.status})`);
+		return res.json();
+	};
 
 	// -- Upload machinery ----------------------------------------------------------
 	// Inertia visits cannot stream per-file progress for a background queue, so
@@ -456,10 +476,12 @@ export function provideUploadCenter(): UploadCenterContext {
 
 	// -- 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 peekReceipt = (id: string, title: string) =>
+		shell.peek({ type: 'receipt', id, title });
+	const stackReceipt = (id: string, title: string) =>
+		shell.stackItem({ type: 'receipt', id, title });
 	const stackMerchant = (name: string) =>
-		shell.push({ type: 'merchant', name });
+		shell.stackItem({ type: 'merchant', name, title: name });
 
 	// -- Actions --------------------------------------------------------------------
 	const updateReceipt = async (receipt: Receipt, patch: ReceiptPatch) => {
@@ -471,6 +493,7 @@ export function provideUploadCenter(): UploadCenterContext {
 			toast({
 				title: `Could not save ${receipt.filename}. Changes were reverted.`,
 				variant: 'destructive',
+				icon: 'lucide:circle-x',
 			});
 		}
 	};
@@ -481,6 +504,7 @@ export function provideUploadCenter(): UploadCenterContext {
 		toast({
 			title: `${receipt.merchant ?? receipt.filename} submitted for approval.`,
 			variant: 'success',
+			icon: 'lucide:circle-check',
 		});
 	};
 
@@ -490,6 +514,7 @@ export function provideUploadCenter(): UploadCenterContext {
 		toast({
 			title: `${readyCount.value} receipts submitted for approval.`,
 			variant: 'success',
+			icon: 'lucide:circle-check',
 		});
 	};
 
@@ -504,7 +529,11 @@ export function provideUploadCenter(): UploadCenterContext {
 		if (!ok) return false;
 		await visit('delete', `/receipts/${receipt.id}`);
 		refresh();
-		toast({ title: `${receipt.filename} removed.`, variant: 'success' });
+		toast({
+			title: `${receipt.filename} removed.`,
+			variant: 'success',
+			icon: 'lucide:circle-check',
+		});
 		return true;
 	};
 
@@ -532,6 +561,7 @@ export function provideUploadCenter(): UploadCenterContext {
 		toast({
 			title: `${count} receipts filed under ${category?.name ?? 'the selected category'}.`,
 			variant: 'success',
+			icon: 'lucide:circle-check',
 		});
 	};
 
@@ -548,7 +578,11 @@ export function provideUploadCenter(): UploadCenterContext {
 		await visit('post', '/receipts/bulk/delete', bulkPayload());
 		table.resetSelection();
 		refresh();
-		toast({ title: `${count} receipts removed.`, variant: 'success' });
+		toast({
+			title: `${count} receipts removed.`,
+			variant: 'success',
+			icon: 'lucide:circle-check',
+		});
 	};
 
 	const ctx: UploadCenterContext = {
@@ -592,7 +626,7 @@ export function useUploadCenter(): UploadCenterContext {
 ### Index.vue — the assembly
 
 ```vue
-<!-- UploadCenter/Index.vue -->
+<!-- pages/UploadCenter/Index.vue -->
 <template>
 	<PageShell>
 		<!-- Topbar: breadcrumbs left, page search + submit-all right. -->
@@ -603,9 +637,9 @@ export function useUploadCenter(): UploadCenterContext {
 				<BbBreadcrumbs
 					class="min-w-0 flex-auto"
 					:items="[
-						{ key: 'dashboard', text: 'Dashboard', href: '/dashboard' },
-						{ key: 'expenses', text: 'Expenses', href: '/expenses' },
-						{ key: 'receipts', text: 'Receipts' },
+						{ value: 'dashboard', label: 'Dashboard', href: '/dashboard' },
+						{ value: 'expenses', label: 'Expenses', href: '/expenses' },
+						{ value: 'receipts', label: 'Receipts' },
 					]"
 				/>
 				<div class="flex shrink-0 items-center gap-2">
@@ -651,33 +685,33 @@ export function useUploadCenter(): UploadCenterContext {
 			<BbTabs
 				v-model="ctx.tab.value"
 				compact
-				navigation
-				preserve-scroll
-				preserve-state
-				replace
 				:items="[
 					{
-						key: 'drafts',
+						value: 'drafts',
 						label: `Drafts · ${ctx.tabCounts.value.drafts}`,
 						href: tabHref('drafts'),
 						server: true,
 						only: ['receipts', 'tabCounts', 'readyCount'],
 					},
 					{
-						key: 'submitted',
+						value: 'submitted',
 						label: `Submitted · ${ctx.tabCounts.value.submitted}`,
 						href: tabHref('submitted'),
 						server: true,
 						only: ['receipts', 'tabCounts', 'readyCount'],
 					},
 					{
-						key: 'reimbursed',
+						value: 'reimbursed',
 						label: `Reimbursed · ${ctx.tabCounts.value.reimbursed}`,
 						href: tabHref('reimbursed'),
 						server: true,
 						only: ['receipts', 'tabCounts', 'readyCount'],
 					},
 				]"
+				navigation
+				preserve-scroll
+				preserve-state
+				replace
 			/>
 
 			<!-- No dependencies/items-fn: `receipts` is a page prop, `rows` merges
@@ -687,7 +721,6 @@ export function useUploadCenter(): UploadCenterContext {
 				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
@@ -708,18 +741,18 @@ export function useUploadCenter(): UploadCenterContext {
 					<MerchantCell v-if="isDraft(item)" :receipt="item" />
 					<span
 						v-else-if="item.kind === 'upload'"
-						class="text-[color:var(--bb-text-muted)]"
+						class="text-(--bb-text-muted)"
 						>—</span
 					>
 					<span v-else>{{ item.merchant ?? '—' }}</span>
 				</template>
 
 				<!-- Slot names are normalized: `categoryId` → `#categoryid`. -->
-				<template #categoryid="{ item }">
+				<template #category-id="{ item }">
 					<CategoryCell v-if="isDraft(item)" :receipt="item" />
 					<span
 						v-else-if="item.kind === 'upload'"
-						class="text-[color:var(--bb-text-muted)]"
+						class="text-(--bb-text-muted)"
 						>—</span
 					>
 					<span v-else>{{ categoryName(item.categoryId) }}</span>
@@ -729,7 +762,7 @@ export function useUploadCenter(): UploadCenterContext {
 					<AmountCell v-if="isDraft(item)" :receipt="item" />
 					<span
 						v-else-if="item.kind === 'upload'"
-						class="text-[color:var(--bb-text-muted)]"
+						class="text-(--bb-text-muted)"
 						>—</span
 					>
 					<span v-else>{{
@@ -741,7 +774,7 @@ export function useUploadCenter(): UploadCenterContext {
 					<DateCell v-if="isDraft(item)" :receipt="item" />
 					<span
 						v-else-if="item.kind === 'upload'"
-						class="text-[color:var(--bb-text-muted)]"
+						class="text-(--bb-text-muted)"
 						>—</span
 					>
 					<span v-else>{{ item.date ? shortDate(item.date) : '—' }}</span>
@@ -759,11 +792,11 @@ export function useUploadCenter(): UploadCenterContext {
 					<RowActions :row="item" />
 				</template>
 
-				<template #no-data>
+				<template #empty>
 					<div class="flex flex-col items-center gap-2 p-8 text-center">
 						<BbIcon
 							aria-hidden="true"
-							class="text-[color:var(--bb-text-muted)]"
+							class="text-(--bb-text-muted)"
 							:icon="
 								ctx.hasActiveFilters.value
 									? 'lucide:search-x'
@@ -780,7 +813,7 @@ export function useUploadCenter(): UploadCenterContext {
 										: 'Nothing in this tab yet'
 							}}
 						</p>
-						<p class="text-xs text-[color:var(--bb-text-muted)]">
+						<p class="text-xs text-(--bb-text-muted)">
 							{{
 								ctx.hasActiveFilters.value
 									? 'Loosen a filter above, or switch tabs to widen the view.'
@@ -812,6 +845,7 @@ export function useUploadCenter(): UploadCenterContext {
 		<SelectionBar />
 
 		<!-- Stacked peek sidebar: the shell owns back/close; we render by type. -->
+		<template #sidebar-title>{{ ctx.shell.current.value?.title }}</template>
 		<template #sidebar>
 			<ReceiptPeek
 				v-if="ctx.shell.current.value?.type === 'receipt'"
@@ -839,7 +873,7 @@ import {
 } from 'bitboss-ui';
 import qs from 'query-string';
 import PageShell from '@/components/layout/PageShell.vue';
-import { useQuery } from '@/composables/useQuery';
+import { useQuery } from '@/composables/inertia-helpers/useQuery';
 import {
 	provideUploadCenter,
 	STATUS_LABEL,
@@ -920,7 +954,7 @@ const submitLabel = computed(() =>
 ### ReceiptDropzone.vue
 
 ```vue
-<!-- UploadCenter/ReceiptDropzone.vue -->
+<!-- pages/UploadCenter/ReceiptDropzone.vue -->
 <template>
 	<BbDropzone
 		v-model="pending"
@@ -933,21 +967,21 @@ const submitLabel = computed(() =>
 	>
 		<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="flex flex-col items-center gap-2 rounded-(--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' : '',
+					dragging ? 'border-(--bb-primary)' : 'border-(--bb-border)',
+					focused ? 'ring-2 ring-(--bb-primary) ring-offset-2' : '',
 				]"
 			>
 				<BbIcon
-					class="text-[color:var(--bb-text-muted)]"
+					class="text-(--bb-text-muted)"
 					icon="lucide:receipt"
 					size="lg"
 				/>
 				<p class="text-sm font-medium">
 					{{ dragging ? 'Drop to add receipts' : 'Drop receipts here' }}
 				</p>
-				<p class="text-xs text-[color:var(--bb-text-muted)]">
+				<p class="text-xs text-(--bb-text-muted)">
 					JPG, PNG, HEIC or PDF · up to 10 MB each · 20 files per drop
 				</p>
 				<BbButton
@@ -1018,7 +1052,7 @@ const onError = (error: DropZoneError) => {
 ### FilterRail.vue
 
 ```vue
-<!-- UploadCenter/FilterRail.vue -->
+<!-- pages/UploadCenter/FilterRail.vue -->
 <template>
 	<div class="flex flex-wrap items-center gap-2">
 		<!-- Category: multi-select pill over the coopted catalog. Searchable, so
@@ -1035,8 +1069,8 @@ const onError = (error: DropZoneError) => {
 			<template #activator="{ props }">
 				<BbButton
 					v-bind="props"
-					aria-label="Filter by category"
 					append:icon="lucide:chevron-down"
+					aria-label="Filter by category"
 					size="sm"
 					variant="outline"
 				>
@@ -1063,8 +1097,8 @@ const onError = (error: DropZoneError) => {
 			<template #activator="{ props }">
 				<BbButton
 					v-bind="props"
-					aria-label="Filter by merchant"
 					append:icon="lucide:chevron-down"
+					aria-label="Filter by merchant"
 					size="sm"
 					variant="outline"
 				>
@@ -1110,36 +1144,35 @@ const ctx = useUploadCenter();
 ### ReceiptFileCell.vue
 
 ```vue
-<!-- UploadCenter/ReceiptFileCell.vue -->
+<!-- pages/UploadCenter/ReceiptFileCell.vue -->
 <template>
 	<div class="flex items-center gap-2">
 		<BbIcon
-			class="shrink-0 text-[color:var(--bb-text-muted)]"
+			class="shrink-0 text-(--bb-text-muted)"
 			:icon="fileIcon"
 			size="16"
 		/>
 		<div class="flex min-w-0 flex-col">
-			<!-- Server receipts peek on click; queue rows are not peekable yet. -->
-			<BbButton
+			<!-- Server receipts peek on click; queue rows are not peekable yet.
+			     The filename is an inline link, not a button: `BbBaseButton` has
+			     no padding, so the name starts on the same edge as the size
+			     under it, and `.plain-link` keeps wrapped lines left-aligned. -->
+			<BbBaseButton
 				v-if="row.kind === 'receipt'"
-				class="justify-start"
-				size="sm"
-				variant="link"
-				@click="() => ctx.peekReceipt(row.id)"
+				class="plain-link text-sm"
+				@click="() => ctx.peekReceipt(row.id, row.filename)"
 			>
 				{{ row.filename }}
-			</BbButton>
+			</BbBaseButton>
 			<span v-else class="truncate text-sm">{{ row.filename }}</span>
-			<span class="text-xs text-[color:var(--bb-text-muted)]">{{
-				formattedSize
-			}}</span>
+			<span class="text-xs text-(--bb-text-muted)">{{ formattedSize }}</span>
 		</div>
 	</div>
 </template>
 
 <script setup lang="ts">
 import { computed } from 'vue';
-import { BbButton, BbIcon } from 'bitboss-ui';
+import { BbBaseButton, BbIcon } from 'bitboss-ui';
 import { useUploadCenter, type UploadCenterRow } from './context';
 
 const props = defineProps<{ row: UploadCenterRow }>();
@@ -1165,7 +1198,7 @@ const formattedSize = computed(() => {
 ### UploadProgressCell.vue
 
 ```vue
-<!-- UploadCenter/UploadProgressCell.vue -->
+<!-- pages/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. -->
@@ -1175,7 +1208,7 @@ const formattedSize = computed(() => {
 			class="flex-1"
 			:model-value="upload.progress"
 		/>
-		<span class="text-xs tabular-nums text-[color:var(--bb-text-muted)]"
+		<span class="text-xs text-(--bb-text-muted) tabular-nums"
 			>{{ upload.progress }}%</span
 		>
 	</div>
@@ -1210,7 +1243,7 @@ const ctx = useUploadCenter();
 ### MerchantCell.vue
 
 ```vue
-<!-- UploadCenter/MerchantCell.vue -->
+<!-- pages/UploadCenter/MerchantCell.vue -->
 <template>
 	<BbTextInput
 		v-model="draft"
@@ -1218,6 +1251,7 @@ const ctx = useUploadCenter();
 		hide-label
 		label="Merchant"
 		placeholder="Add merchant"
+		variant="ghost"
 		@change="commit"
 		@keydown.esc="revert"
 	/>
@@ -1233,7 +1267,7 @@ const props = defineProps<{ receipt: Receipt }>();
 
 const ctx = useUploadCenter();
 
-// Inline-edit doctrine (§6.3): a local draft, commit on @change — which
+// Inline-edit doctrine: a local draft, commit on @change — which
 // fires once for the whole blur/Enter sequence, unlike binding @blur AND
 // @keydown.enter separately (that double-fires: Enter commits, then the
 // field still blurs right after). Revert on Esc. The server value re-seeds
@@ -1261,7 +1295,7 @@ const revert = () => {
 ### CategoryCell.vue
 
 ```vue
-<!-- UploadCenter/CategoryCell.vue -->
+<!-- pages/UploadCenter/CategoryCell.vue -->
 <template>
 	<BbSelectPopover
 		compact
@@ -1273,8 +1307,8 @@ const revert = () => {
 		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 —
+		<template #activator="{ props: activatorProps }">
+			<!-- One-click pattern: 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
@@ -1283,7 +1317,6 @@ const revert = () => {
 			     quieter to-dos, not values. -->
 			<BbBadge
 				append:icon="lucide:chevron-down"
-				:class="{ 'category-cell--open': shown }"
 				:loading="saving"
 				:variant="receipt.categoryId ? 'secondary' : 'outline'"
 			>
@@ -1327,22 +1360,12 @@ const categoryName = computed(
 		)?.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 -->
+<!-- pages/UploadCenter/AmountCell.vue -->
 <template>
 	<BbNumberInput
 		v-model="draft"
@@ -1351,7 +1374,9 @@ const categoryName = computed(
 		label="Amount"
 		:max-precision="2"
 		:min="0"
+		:min-precision="2"
 		placeholder="0.00"
+		variant="ghost"
 		@change="commit"
 		@keydown.esc="revert"
 	>
@@ -1369,32 +1394,24 @@ 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 —
-// commit on @change, not @blur + @keydown.enter (see MerchantCell.vue).
-const draft = ref<number | string | null>(formatMoney(props.receipt.amount));
+// Money cells always show two decimals (`min-precision`), so the column
+// optically aligns. Same commit/revert contract as the merchant cell, on the
+// number model — commit on @change, not @blur + @keydown.enter (see
+// MerchantCell.vue).
+const draft = ref<number | null>(props.receipt.amount);
 watch(
 	() => props.receipt.amount,
 	(value) => {
-		draft.value = formatMoney(value);
+		draft.value = 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);
+	if (draft.value === props.receipt.amount) return;
+	void ctx.updateReceipt(props.receipt, { amount: draft.value });
 };
 const revert = () => {
-	draft.value = formatMoney(props.receipt.amount);
+	draft.value = props.receipt.amount;
 };
 </script>
 ```
@@ -1402,7 +1419,7 @@ const revert = () => {
 ### DateCell.vue
 
 ```vue
-<!-- UploadCenter/DateCell.vue -->
+<!-- pages/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. -->
@@ -1413,6 +1430,7 @@ const revert = () => {
 		label="Expense date"
 		:model-value="receipt.date"
 		placeholder="YYYY-MM-DD"
+		variant="ghost"
 		@update:model-value="commit"
 	/>
 </template>
@@ -1437,7 +1455,7 @@ const commit = (value: string | string[] | null) => {
 ### RowActions.vue
 
 ```vue
-<!-- UploadCenter/RowActions.vue -->
+<!-- pages/UploadCenter/RowActions.vue -->
 <template>
 	<!-- Queue rows: one explicit remove (aborts the transfer). -->
 	<BbButton
@@ -1476,8 +1494,8 @@ const items = computed(() => {
 		...(isDraft
 			? [
 					{
-						key: 'submit',
-						text: 'Submit for approval',
+						value: 'submit',
+						label: 'Submit for approval',
 						'prepend:icon': 'lucide:send',
 						onClick: () => ctx.submitReceipt(receipt),
 					},
@@ -1488,8 +1506,8 @@ const items = computed(() => {
 			// 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',
+			value: 'download',
+			label: 'Download original',
 			'prepend:icon': 'lucide:download',
 			href: `/receipts/${receipt.id}/file`,
 			target: '_blank',
@@ -1497,8 +1515,8 @@ const items = computed(() => {
 		...(isDraft
 			? [
 					{
-						key: 'remove',
-						text: 'Remove',
+						value: 'remove',
+						label: 'Remove',
 						'prepend:icon': 'lucide:trash-2',
 						variant: 'destructive' as const,
 						onClick: () => ctx.deleteReceipt(receipt),
@@ -1513,10 +1531,10 @@ const items = computed(() => {
 ### SelectionBar.vue
 
 ```vue
-<!-- UploadCenter/SelectionBar.vue -->
+<!-- pages/UploadCenter/SelectionBar.vue -->
 <template>
 	<FloatingBottomPanel :open="selectedCount > 0">
-		<span class="px-2 text-sm text-[color:var(--bb-text-muted)]">
+		<span class="px-2 text-sm text-(--bb-text-muted)">
 			<span class="font-semibold tabular-nums">{{ selectedCount }}</span>
 			selected
 		</span>
@@ -1585,7 +1603,7 @@ const selectedCount = computed(() =>
 ### ReceiptPeek.vue
 
 ```vue
-<!-- UploadCenter/ReceiptPeek.vue -->
+<!-- pages/UploadCenter/ReceiptPeek.vue -->
 <template>
 	<div v-if="receipt" class="flex flex-col gap-4 text-sm">
 		<!-- Header: merchant identity + amount + status. The merchant name
@@ -1600,9 +1618,7 @@ const selectedCount = computed(() =>
 				>
 					{{ receipt.merchant }}
 				</BbButton>
-				<span v-else class="text-[color:var(--bb-text-muted)]"
-					>No merchant yet</span
-				>
+				<span v-else class="text-(--bb-text-muted)">No merchant yet</span>
 				<BbBadge :variant="STATUS_VARIANT[receipt.status]">{{
 					STATUS_LABEL[receipt.status]
 				}}</BbBadge>
@@ -1614,7 +1630,7 @@ const selectedCount = computed(() =>
 						: currency.format(receipt.amount)
 				}}
 			</p>
-			<p class="text-xs text-[color:var(--bb-text-muted)]">
+			<p class="text-xs text-(--bb-text-muted)">
 				{{ receipt.filename }} · spent
 				{{ receipt.date ? longDate(receipt.date) : '—' }}
 			</p>
@@ -1622,7 +1638,7 @@ const selectedCount = computed(() =>
 
 		<!-- Preview placeholder: the real app renders the scanned image here. -->
 		<div
-			class="flex h-44 flex-col items-center justify-center gap-1 rounded-[var(--bb-radius)] border bg-[var(--bb-panel)] text-[color:var(--bb-text-muted)]"
+			class="flex h-44 flex-col items-center justify-center gap-1 rounded-(--bb-radius) border bg-(--bb-panel) text-(--bb-text-muted)"
 		>
 			<BbIcon icon="lucide:receipt" size="lg" />
 			<span class="text-xs">Receipt preview</span>
@@ -1632,7 +1648,7 @@ const selectedCount = computed(() =>
 		<section class="flex flex-col gap-1.5">
 			<div class="flex items-center justify-between">
 				<h3
-					class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
+					class="text-xs font-semibold tracking-wide text-(--bb-text-muted) uppercase"
 				>
 					Extracted fields
 				</h3>
@@ -1641,9 +1657,9 @@ const selectedCount = computed(() =>
 				}}</BbBadge>
 			</div>
 			<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
-				<dt class="text-[color:var(--bb-text-muted)]">Merchant</dt>
+				<dt class="text-(--bb-text-muted)">Merchant</dt>
 				<dd>{{ receipt.extracted.merchant ?? '—' }}</dd>
-				<dt class="text-[color:var(--bb-text-muted)]">Total</dt>
+				<dt class="text-(--bb-text-muted)">Total</dt>
 				<dd>
 					{{
 						receipt.extracted.total === null
@@ -1651,7 +1667,7 @@ const selectedCount = computed(() =>
 							: currency.format(receipt.extracted.total)
 					}}
 				</dd>
-				<dt class="text-[color:var(--bb-text-muted)]">Tax</dt>
+				<dt class="text-(--bb-text-muted)">Tax</dt>
 				<dd>
 					{{
 						receipt.extracted.tax === null
@@ -1659,11 +1675,11 @@ const selectedCount = computed(() =>
 							: currency.format(receipt.extracted.tax)
 					}}
 				</dd>
-				<dt class="text-[color:var(--bb-text-muted)]">Date</dt>
+				<dt class="text-(--bb-text-muted)">Date</dt>
 				<dd>
 					{{ receipt.extracted.date ? longDate(receipt.extracted.date) : '—' }}
 				</dd>
-				<dt class="text-[color:var(--bb-text-muted)]">Paid with</dt>
+				<dt class="text-(--bb-text-muted)">Paid with</dt>
 				<dd>{{ receipt.extracted.paymentMethod ?? '—' }}</dd>
 			</dl>
 		</section>
@@ -1672,16 +1688,16 @@ const selectedCount = computed(() =>
 		     one-click cell as in the table. -->
 		<section class="flex flex-col gap-1.5">
 			<h3
-				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
+				class="text-xs font-semibold tracking-wide text-(--bb-text-muted) uppercase"
 			>
 				Details
 			</h3>
 			<dl class="grid grid-cols-[auto_1fr] items-center gap-x-4 gap-y-1.5">
-				<dt class="text-[color:var(--bb-text-muted)]">Category</dt>
+				<dt class="text-(--bb-text-muted)">Category</dt>
 				<dd><CategoryCell :receipt="receipt" /></dd>
-				<dt class="text-[color:var(--bb-text-muted)]">Uploaded</dt>
+				<dt class="text-(--bb-text-muted)">Uploaded</dt>
 				<dd>{{ longDate(receipt.uploadedAt) }}</dd>
-				<dt class="text-[color:var(--bb-text-muted)]">Report</dt>
+				<dt class="text-(--bb-text-muted)">Report</dt>
 				<dd>{{ receipt.reportName ?? 'Not on a report yet' }}</dd>
 			</dl>
 		</section>
@@ -1689,7 +1705,7 @@ const selectedCount = computed(() =>
 		<!-- Activity feed. -->
 		<section class="flex flex-col gap-1.5">
 			<h3
-				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
+				class="text-xs font-semibold tracking-wide text-(--bb-text-muted) uppercase"
 			>
 				Activity
 			</h3>
@@ -1700,13 +1716,13 @@ const selectedCount = computed(() =>
 					class="flex gap-2"
 				>
 					<BbIcon
-						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
+						class="mt-0.5 shrink-0 text-(--bb-text-muted)"
 						:icon="entry.icon"
 						size="14"
 					/>
 					<div class="flex flex-col">
 						<span>{{ entry.text }}</span>
-						<span class="text-xs text-[color:var(--bb-text-muted)]"
+						<span class="text-xs text-(--bb-text-muted)"
 							>{{ entry.actor }} · {{ longDate(entry.at) }}</span
 						>
 					</div>
@@ -1757,7 +1773,7 @@ const selectedCount = computed(() =>
 <script setup lang="ts">
 import { watch } from 'vue';
 import { BbBadge, BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
-import { useResourceContext } from '@/composables/useResourceContext';
+import { useResourceContext } from '@/composables/inertia-helpers/useResourceContext';
 import CategoryCell from './CategoryCell.vue';
 import { STATUS_LABEL, STATUS_VARIANT, useUploadCenter } from './context';
 import type { ReceiptDetail } from '@/types';
@@ -1799,22 +1815,18 @@ const longDate = (value: string) =>
 ### MerchantPeek.vue
 
 ```vue
-<!-- UploadCenter/MerchantPeek.vue -->
+<!-- pages/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"
+				class="grid h-9 w-9 shrink-0 place-items-center rounded-(--bb-radius) border"
 			>
-				<BbIcon
-					class="text-[color:var(--bb-text-muted)]"
-					icon="lucide:store"
-					size="18"
-				/>
+				<BbIcon class="text-(--bb-text-muted)" icon="lucide:store" size="18" />
 			</div>
 			<div class="flex flex-col">
 				<h2 class="text-base font-semibold">{{ merchant.name }}</h2>
-				<p class="text-xs text-[color:var(--bb-text-muted)]">
+				<p class="text-xs text-(--bb-text-muted)">
 					{{ merchant.defaultCategoryName }} · this year
 				</p>
 			</div>
@@ -1822,16 +1834,16 @@ const longDate = (value: string) =>
 
 		<!-- Stat strip. -->
 		<div class="grid grid-cols-3 gap-2">
-			<div class="rounded-[var(--bb-radius)] border p-2">
-				<p class="text-xs text-[color:var(--bb-text-muted)]">Total spent</p>
+			<div class="rounded-(--bb-radius) border p-2">
+				<p class="text-xs text-(--bb-text-muted)">Total spent</p>
 				<p class="font-semibold">{{ currency.format(merchant.totalSpent) }}</p>
 			</div>
-			<div class="rounded-[var(--bb-radius)] border p-2">
-				<p class="text-xs text-[color:var(--bb-text-muted)]">Receipts</p>
+			<div class="rounded-(--bb-radius) border p-2">
+				<p class="text-xs text-(--bb-text-muted)">Receipts</p>
 				<p class="font-semibold">{{ merchant.receiptCount }}</p>
 			</div>
-			<div class="rounded-[var(--bb-radius)] border p-2">
-				<p class="text-xs text-[color:var(--bb-text-muted)]">Average</p>
+			<div class="rounded-(--bb-radius) border p-2">
+				<p class="text-xs text-(--bb-text-muted)">Average</p>
 				<p class="font-semibold">
 					{{ currency.format(merchant.averageAmount) }}
 				</p>
@@ -1841,7 +1853,7 @@ const longDate = (value: string) =>
 		<!-- Recent receipts: names drill down again — the stack keeps growing. -->
 		<section class="flex flex-col gap-1.5">
 			<h3
-				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
+				class="text-xs font-semibold tracking-wide text-(--bb-text-muted) uppercase"
 			>
 				Recent receipts
 			</h3>
@@ -1854,14 +1866,14 @@ const longDate = (value: string) =>
 					<BbButton
 						size="sm"
 						variant="link"
-						@click="() => ctx.stackReceipt(recent.id)"
+						@click="() => ctx.stackReceipt(recent.id, recent.filename)"
 					>
 						{{ recent.filename }}
 					</BbButton>
 					<BbBadge :variant="STATUS_VARIANT[recent.status]">{{
 						STATUS_LABEL[recent.status]
 					}}</BbBadge>
-					<span class="text-xs tabular-nums text-[color:var(--bb-text-muted)]">
+					<span class="text-xs text-(--bb-text-muted) tabular-nums">
 						{{ currency.format(recent.amount) }}
 					</span>
 				</li>
@@ -1870,7 +1882,7 @@ const longDate = (value: string) =>
 
 		<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. -->
+			     Inertia visit; no `target` needed here. -->
 			<BbButton
 				append:icon="lucide:arrow-up-right"
 				:href="`/expenses/receipts?merchant=${encodeURIComponent(merchant.name)}`"
@@ -1889,7 +1901,7 @@ const longDate = (value: string) =>
 
 <script setup lang="ts">
 import { BbBadge, BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
-import { useResourceContext } from '@/composables/useResourceContext';
+import { useResourceContext } from '@/composables/inertia-helpers/useResourceContext';
 import { STATUS_LABEL, STATUS_VARIANT, useUploadCenter } from './context';
 import type { MerchantSummary } from '@/types';
 
@@ -1976,7 +1988,7 @@ function` — identical call sites to the Vue/Nuxt recipes,
   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
+  — 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