bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/recipes/vue/approvals-inbox.md

@@ -0,0 +1,1496 @@
+---
+title: Approvals Inbox (Vue)
+summary: Keyboard-first expense-approvals triage for a vue-router SPA — `keyboard-navigation` with highlight-opens-peek, one-click approve, reject-with-reason and snooze dialogs, bulk approve/reject, and an `A`/`R`/`S` shortcut bar, all through one coopting page context.
+---
+
+# Recipe: Approvals Inbox (Vue)
+
+The densest advanced-page recipe in the folder: a Linear-triage ×
+Expensify-approvals expense inbox for a **plain Vue SPA with vue-router**.
+`keyboard-navigation` turns the table into a single tab stop; the row under
+the roving tabindex drives the peek sidebar directly (no click handler);
+approve, reject-with-reason and snooze are each reachable from the row, the
+peek footer, and an `A`/`R`/`S` shortcut bar — three dispatch surfaces
+calling the exact same context actions; and a floating bottom panel adds
+bulk approve/reject on top of the selection axis, fully independent of
+highlight. All of it is wired through one coopting page context so every
+leaf component takes zero props beyond the record it renders.
+
+Sibling recipes: [Nuxt](../nuxt/approvals-inbox.md) ·
+[Inertia](../inertia/approvals-inbox.md).
+
+## Prerequisites
+
+- **[Layout Scaffold](./layout-scaffold.md) — build it first.** This recipe
+  imports `PageShell`, `usePageShellContext` and `FloatingBottomPanel` from your own app.
+  They are not package exports; the scaffold recipe is their source. Copy
+  those files before anything below, and do not hand-roll replacements —
+  the peek stack, the close semantics and the sidebar's out-of-flow
+  behaviour are all load-bearing here.
+- `<BbConfirm />` and `<BbToast />` mounted once in the app root (`App.vue`) — never in a page.
+- [App Layout](../../guides/app-layout.md), [Page Shell](../../guides/page-shell.md)
+  and [Floating Bottom Panel](../../guides/floating-bottom-panel.md) copied
+  into `src/components/layout/` per their guides — every recipe page assumes
+  this chrome exists and renders inside it.
+
+## Key ideas
+
+- **Highlight drives the peek, not a click handler.** The table gets
+  `keyboard-navigation`; `ctx.table.highlighted` (the coopted table
+  context) is watched in `context.ts`, and every highlight change
+  replaces the sidebar's stack with that expense — arrowing through rows
+  previews each one with zero markup in `Index.vue`. Selection stays a
+  fully independent axis, free for the bulk bar.
+- **One coopting page context.** `provideApprovalsInbox()` joins the
+  page-shell stack and the table context once, owns filters/tab/dialogs,
+  and exposes complete actions. Every leaf calls `useApprovalsInbox()` and
+  nothing else.
+- **Three dispatch surfaces, one set of actions.** Approve / reject /
+  snooze are reachable from the row, from inside the peek, and from the
+  `A`/`R`/`S` keyboard shortcuts — all three call the exact same context
+  functions (`approve`, `openReject`, `openSnooze`), so there is exactly
+  one place each action's API call, refresh and toast live.
+- **Reason and date are dialogs, not confirms.** Reject needs a typed
+  reason and snooze needs a date, so both open a small `BbDialog` (the
+  dialog itself is the confirmation gate) — a plain `useConfirm` is
+  reserved for actions that need no input.
+- **The shortcut bar mirrors `useDeleteCmd`'s guard.** A small keydown
+  handler in the context checks `isInteractiveElementFocused()` before
+  firing — typing "reason" in the reject textarea never triggers `R`.
+- **Clicking a submitter's name always stacks**, from a row or from inside
+  the expense peek — the back arrow appears once the stack is two deep,
+  exactly the "peek vs stack" grammar of the flagship.
+- **Tabs are URL filters with live counts** (`Needs approval` / `Approved`
+  / `Rejected` / `All`), same shape as every other workspace in the
+  folder.
+- **Buttons are `md` by default**; `sm`/`xs` apply only where the doctrine
+  allows it — table rows, the peek footers, the bulk bar, the shortcut
+  bar.
+
+- **Spread the filters object into `dependencies`.** `BbTable` hash-compares
+  `dependencies`; it does not deep-watch them. Passing the reactive `filters`
+  proxy itself tracks only its identity — which never changes — so the table
+  never refetches. `{ ...ctx.filters }` reads every field during render, so any
+  field change yields a new, differently-hashed array. Read `.value` off the
+  refs for the same reason: context members are not auto-unwrapped in a template.
+
+## Page anatomy
+
+```
+ApprovalsInbox/
+	Index.vue            ← assembly: PageShell slots, table, tabs, pagination
+	context.ts            ← coopting page context (shell + table + filters + shortcuts + actions)
+	FilterRail.vue         ← pill filters + clear-all
+	ShortcutsHint.vue       ← A / R / S icon buttons, tooltip-labelled, act on the highlighted row
+	ReceiptThumbnail.vue   ← receipt image/placeholder cell
+	RowActions.vue         ← per-row approve / reject / snooze icon buttons
+	SelectionBar.vue       ← bulk approve / reject in the floating bottom panel
+	RejectDialog.vue       ← single-row reject, required reason
+	BulkRejectDialog.vue   ← bulk reject, required reason
+	SnoozeDialog.vue       ← single-row snooze, date picker
+	ExpensePeek.vue        ← sidebar workbench, stack level 1 (opens from highlight)
+	SubmitterPeek.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   | Page search (merchant/submitter) | topbar right                                           | `filters.search` → fetch dependency                       |
+| 2   | Filter by submitter              | filter rail pill                                       | `BbSelectPopover` single, query-aware                     |
+| 3   | Filter by category               | filter rail pill                                       | `BbSelectPopover` multiple                                |
+| 4   | Quick filter: amount over        | filter rail pill                                       | `BbSelectPopover` single, preset thresholds               |
+| 5   | Clear filters                    | rail right (only when active)                          | context `clearFilters()`                                  |
+| 6   | Switch tab                       | href tabs with counts                                  | URL + fetch dependency                                    |
+| 7   | Arrow through rows               | `keyboard-navigation` roving tabindex                  | table's own Arrow/Home/End                                |
+| 8   | Preview an expense               | highlight a row (click, Enter/Space, arrow-then-Enter) | `ctx.table.highlighted` watcher → `peekExpense` (replace) |
+| 9   | Approve (one click)              | row icon button, peek footer, key `A`                  | `approve(expense)` — API + refresh + toast                |
+| 10  | Reject with reason               | row icon button, peek footer, key `R`                  | `openReject` → `RejectDialog` (required `BbTextarea`)     |
+| 11  | Snooze                           | row icon button, peek footer, key `S`                  | `openSnooze` → `SnoozeDialog` (`BbDatePickerInput`)       |
+| 12  | Select rows / select all         | table checkboxes                                       | table context                                             |
+| 13  | Bulk approve                     | floating bottom panel                                  | `bulkApprove()` on `table.selected`                       |
+| 14  | Bulk reject with reason          | floating bottom panel                                  | `BulkRejectDialog`, destructive                           |
+| 15  | Stack a submitter                | submitter cell / peek property                         | `stackSubmitter(id)` → shell stack, back arrow            |
+| 16  | Stack an expense from a profile  | recent-expense row inside `SubmitterPeek`              | `stackExpense(id)` → shell stack                          |
+| 17  | View full-size receipt           | peek "View receipt" link                               | navigation (`href`, new tab)                              |
+| 18  | Open full expense                | peek footer                                            | navigation (`/expenses/:id`)                              |
+| 19  | Back / close peek                | shell chrome                                           | shell stack pop / close                                   |
+
+Nineteen distinct actions, spanning inline one-click mutation (8),
+input-gated mutation via dialog (10, 11, 14), bulk mutation (13, 14),
+keyboard dispatch (7, 9, 10, 11), navigation (17, 18, 19) and contextual
+drill-down (15, 16) — well past the ≥ 12 bar.
+
+## The code
+
+### context.ts
+
+```ts
+// ApprovalsInbox/context.ts
+import {
+	computed,
+	inject,
+	provide,
+	reactive,
+	ref,
+	watch,
+	type ComputedRef,
+	type InjectionKey,
+	type Ref,
+} from 'vue';
+import { useMagicKeys, whenever } from '@vueuse/core';
+import {
+	useBbTableContext,
+	useConfirm,
+	useToast,
+	type BbTableContext,
+} from 'bitboss-ui';
+import {
+	usePageShellContext,
+	type PageShellContext,
+} from '@/components/layout/usePageShellContext';
+import { api } from '@/api';
+import type { Expense, ExpenseCategory } from '@/types';
+
+/** What the stacked sidebar can show. Clicking a name pushes one of these. */
+export type PeekItem =
+	| { type: 'expense'; id: number }
+	| { type: 'submitter'; id: number };
+
+export type ApprovalsTab = 'needsApproval' | 'approved' | 'rejected' | 'all';
+
+export interface ApprovalsFilters {
+	search: string;
+	submitterId: number | null;
+	categories: ExpenseCategory[];
+	/** Preset threshold from the quick filter (`50`, `100`, `250`…), or `null`. */
+	amountOver: number | null;
+}
+
+export interface ApprovalsInboxContext {
+	// -- Coopted contexts ------------------------------------------------------
+	shell: PageShellContext<PeekItem>;
+	table: BbTableContext;
+	// -- Page-owned state --------------------------------------------------------
+	filters: ApprovalsFilters;
+	hasActiveFilters: ComputedRef<boolean>;
+	tab: Ref<ApprovalsTab>;
+	tabCounts: Ref<Record<ApprovalsTab, number>>;
+	refreshKey: Ref<number>;
+	dialogs: {
+		reject: Ref<Expense | null>;
+		bulkReject: Ref<boolean>;
+		snooze: Ref<Expense | null>;
+	};
+	/** The expense under the roving tabindex, resolved from the last fetch. */
+	highlightedExpense: ComputedRef<Expense | null>;
+	// -- Data ----------------------------------------------------------------
+	fetchExpenses: () => Promise<Expense[]>;
+	// -- Peek grammar ----------------------------------------------------------
+	// (peekExpense — the highlight-driven replace — is internal to the watcher
+	// below, not part of the public surface: leaves never open the peek
+	// directly, only highlight drives it.)
+	stackExpense: (id: number) => void;
+	stackSubmitter: (id: number) => void;
+	// -- Actions (complete: API + refresh + toast) ------------------------------
+	clearFilters: () => void;
+	approve: (expense: Expense) => Promise<void>;
+	openReject: (expense: Expense) => void;
+	reject: (expense: Expense, reason: string) => Promise<void>;
+	openSnooze: (expense: Expense) => void;
+	snooze: (expense: Expense, until: string) => Promise<void>;
+	bulkApprove: () => Promise<void>;
+	openBulkReject: () => void;
+	bulkReject: (reason: string) => Promise<void>;
+	// -- Keyboard-shortcut dispatch (mirrors the row/peek buttons) --------------
+	approveHighlighted: () => void;
+	rejectHighlighted: () => void;
+	snoozeHighlighted: () => void;
+}
+
+const key: InjectionKey<ApprovalsInboxContext> = Symbol('approvals-inbox');
+
+/** Mirrors `useDeleteCmd`'s guard: skip shortcuts while the user is typing. */
+const isInteractiveElementFocused = (): boolean => {
+	const active = document.activeElement;
+	if (!active) return false;
+	const tag = active.tagName.toLowerCase();
+	if (tag === 'input' || tag === 'textarea' || tag === 'select') return true;
+	return active.getAttribute('contenteditable') === 'true';
+};
+
+export function provideApprovalsInbox(): ApprovalsInboxContext {
+	const { toast } = useToast();
+	const { confirm } = useConfirm();
+
+	// -- Coopt the specific contexts: once, here, for the whole page. ----------
+	const shell = usePageShellContext<PeekItem>();
+	const table = useBbTableContext('approvals-table', { perPage: 25 });
+
+	// -- Page state ---------------------------------------------------------------
+	const filters = reactive<ApprovalsFilters>({
+		search: '',
+		submitterId: null,
+		categories: [],
+		amountOver: null,
+	});
+	const hasActiveFilters = computed(
+		() =>
+			filters.search !== '' ||
+			filters.submitterId !== null ||
+			filters.categories.length > 0 ||
+			filters.amountOver !== null
+	);
+	const tab = ref<ApprovalsTab>('needsApproval');
+	const tabCounts = ref<Record<ApprovalsTab, number>>({
+		needsApproval: 0,
+		approved: 0,
+		rejected: 0,
+		all: 0,
+	});
+	const refreshKey = ref(0);
+	const dialogs = {
+		reject: ref<Expense | null>(null),
+		bulkReject: ref(false),
+		snooze: ref<Expense | null>(null),
+	};
+
+	const clearFilters = () => {
+		filters.search = '';
+		filters.submitterId = null;
+		filters.categories = [];
+		filters.amountOver = null;
+	};
+
+	// -- Data -----------------------------------------------------------------------
+	// Cached so the keyboard shortcuts and the peek watcher can resolve a full
+	// expense from the id the table context reports.
+	const lastItems = ref<Expense[]>([]);
+	const fetchExpenses = async (): Promise<Expense[]> => {
+		const response = await api.expenses.list({
+			...filters,
+			tab: tab.value,
+			page: table.page.value,
+			perPage: table.perPage.value,
+		});
+		table.total.value = response.total;
+		tabCounts.value = response.tabCounts;
+		lastItems.value = response.data;
+		return response.data;
+	};
+
+	// -- Peek grammar -----------------------------------------------------------------
+	// peekX replaces the stack (from the list / highlight); stackX drills down.
+	const peekExpense = (id: number) => shell.push({ type: 'expense', id }, true);
+	const stackExpense = (id: number) => shell.push({ type: 'expense', id });
+	const stackSubmitter = (id: number) => shell.push({ type: 'submitter', id });
+
+	// Highlighting IS the peek trigger: arrowing (or clicking) a row opens it,
+	// clearing the highlight closes it. `item-value="id"` on the table means
+	// `table.highlighted` already holds the plain id.
+	watch(table.highlighted, (id) => {
+		if (id == null) {
+			shell.close();
+		} else {
+			peekExpense(id as number);
+		}
+	});
+
+	const highlightedExpense = computed<Expense | null>(
+		() =>
+			lastItems.value.find(
+				(expense) => expense.id === table.highlighted.value
+			) ?? null
+	);
+
+	// -- Actions ----------------------------------------------------------------------
+	const refresh = () => {
+		refreshKey.value++;
+	};
+	const clearSelection = () => {
+		table.selected.value = [];
+	};
+
+	const approve = async (expense: Expense) => {
+		await api.expenses.approve(expense.id);
+		refresh();
+		toast({
+			title: `Approved ${expense.merchant} — $${expense.amount.toFixed(2)}.`,
+			variant: 'success',
+		});
+	};
+
+	const openReject = (expense: Expense) => {
+		dialogs.reject.value = expense;
+	};
+	const reject = async (expense: Expense, reason: string) => {
+		await api.expenses.reject(expense.id, reason);
+		dialogs.reject.value = null;
+		refresh();
+		toast({ title: `Rejected ${expense.merchant}.`, variant: 'success' });
+	};
+
+	const openSnooze = (expense: Expense) => {
+		dialogs.snooze.value = expense;
+	};
+	const snooze = async (expense: Expense, until: string) => {
+		await api.expenses.snooze(expense.id, until);
+		dialogs.snooze.value = null;
+		refresh();
+		toast({ title: `${expense.merchant} snoozed.`, variant: 'success' });
+	};
+
+	const bulkApprove = async () => {
+		const ids = table.selected.value as number[];
+		await api.expenses.approveMany(ids);
+		clearSelection();
+		refresh();
+		toast({ title: `${ids.length} expenses approved.`, variant: 'success' });
+	};
+
+	const openBulkReject = () => {
+		dialogs.bulkReject.value = true;
+	};
+	const bulkReject = async (reason: string) => {
+		const ids = table.selected.value as number[];
+		const ok = await confirm({
+			variant: 'destructive',
+			title: 'Reject expenses',
+			text: `Reject ${ids.length} expenses? The submitters are notified.`,
+			yes: 'Reject',
+			no: 'Cancel',
+		});
+		if (!ok) return;
+		await api.expenses.rejectMany(ids, reason);
+		dialogs.bulkReject.value = false;
+		clearSelection();
+		refresh();
+		toast({ title: `${ids.length} expenses rejected.`, variant: 'success' });
+	};
+
+	// -- Keyboard-shortcut dispatch: same actions, resolved against the row
+	// under the roving tabindex. Guarded exactly like `useDeleteCmd`.
+	const keys = useMagicKeys();
+	const withHighlighted = (run: (expense: Expense) => void) => {
+		if (isInteractiveElementFocused()) return;
+		if (
+			dialogs.reject.value ||
+			dialogs.bulkReject.value ||
+			dialogs.snooze.value
+		)
+			return;
+		const expense = highlightedExpense.value;
+		if (expense) run(expense);
+	};
+	const approveHighlighted = () =>
+		withHighlighted((expense) => void approve(expense));
+	const rejectHighlighted = () => withHighlighted(openReject);
+	const snoozeHighlighted = () => withHighlighted(openSnooze);
+
+	whenever(keys['a'], approveHighlighted);
+	whenever(keys['r'], rejectHighlighted);
+	whenever(keys['s'], snoozeHighlighted);
+
+	const ctx: ApprovalsInboxContext = {
+		shell,
+		table,
+		filters,
+		hasActiveFilters,
+		tab,
+		tabCounts,
+		refreshKey,
+		dialogs,
+		highlightedExpense,
+		fetchExpenses,
+		stackExpense,
+		stackSubmitter,
+		clearFilters,
+		approve,
+		openReject,
+		reject,
+		openSnooze,
+		snooze,
+		bulkApprove,
+		openBulkReject,
+		bulkReject,
+		approveHighlighted,
+		rejectHighlighted,
+		snoozeHighlighted,
+	};
+	provide(key, ctx);
+	return ctx;
+}
+
+export function useApprovalsInbox(): ApprovalsInboxContext {
+	const ctx = inject(key);
+	if (!ctx)
+		throw new Error('useApprovalsInbox() called outside ApprovalsInbox');
+	return ctx;
+}
+```
+
+### Index.vue — the assembly
+
+```vue
+<!-- ApprovalsInbox/Index.vue -->
+<template>
+	<PageShell>
+		<!-- Topbar: breadcrumbs left, page search right. -->
+		<template #topbar>
+			<div class="flex items-center justify-between gap-4 border-b px-4 py-2">
+				<!-- Breadcrumbs take the row's slack on a stable basis (min-w-0 flex-auto);
+				     without it their overflow recompute fights the flex layout every frame. -->
+				<BbBreadcrumbs
+					class="min-w-0 flex-auto"
+					:items="[
+						{ key: 'dashboard', text: 'Dashboard', to: '/dashboard' },
+						{ key: 'finance', text: 'Finance', to: '/finance' },
+						{ key: 'approvals', text: 'Approvals' },
+					]"
+				/>
+				<BbTextInput
+					v-model="ctx.filters.search"
+					autocomplete="off"
+					class="shrink-0"
+					clearable
+					compact
+					hide-label
+					label="Search expenses"
+					placeholder="Search merchant or submitter…"
+					prepend:icon="lucide:search"
+				/>
+			</div>
+		</template>
+
+		<div class="flex flex-col gap-3 p-4">
+			<FilterRail />
+
+			<div class="flex items-center justify-between gap-2">
+				<!-- Tabs as URL filters: counts come from the server on every fetch. -->
+				<BbTabs
+					v-model="ctx.tab.value"
+					compact
+					:items="[
+						{
+							key: 'needsApproval',
+							label: `Needs approval · ${ctx.tabCounts.value.needsApproval}`,
+							href: '?tab=needsApproval',
+						},
+						{
+							key: 'approved',
+							label: `Approved · ${ctx.tabCounts.value.approved}`,
+							href: '?tab=approved',
+						},
+						{
+							key: 'rejected',
+							label: `Rejected · ${ctx.tabCounts.value.rejected}`,
+							href: '?tab=rejected',
+						},
+						{
+							key: 'all',
+							label: `All · ${ctx.tabCounts.value.all}`,
+							href: '?tab=all',
+						},
+					]"
+				/>
+				<ShortcutsHint />
+			</div>
+
+			<BbTable
+				id="approvals-table"
+				actions
+				caption="Expense approvals"
+				:columns="columns"
+				compact
+				:dependencies="[
+					{ ...ctx.filters },
+					ctx.tab.value,
+					ctx.refreshKey.value,
+				]"
+				:deps-debounce-time="300"
+				item-value="id"
+				:items="ctx.fetchExpenses"
+				keyboard-navigation
+				loading-text="Loading expenses…"
+				:row-class="rowClass"
+				selectable
+			>
+				<template #receipt="{ item }">
+					<ReceiptThumbnail :expense="item" />
+				</template>
+
+				<template #merchant="{ content }">
+					<span class="font-medium">{{ content }}</span>
+				</template>
+
+				<template #submitter_name="{ item }">
+					<BbButton
+						size="sm"
+						variant="ghost"
+						@click="() => ctx.stackSubmitter(item.submitter.id)"
+					>
+						{{ item.submitter.name }}
+					</BbButton>
+				</template>
+
+				<template #category="{ item }">
+					<BbBadge variant="outline">{{ item.category }}</BbBadge>
+				</template>
+
+				<template #status="{ item }">
+					<BbBadge variant="outline">{{ statusLabel(item.status) }}</BbBadge>
+				</template>
+
+				<template #actions="{ item }">
+					<RowActions :expense="item" />
+				</template>
+
+				<template #no-data>
+					<div class="flex flex-col items-center gap-2 p-6 text-center">
+						<p class="text-sm text-[color:var(--bb-text-muted)]">
+							No expenses match
+							{{
+								ctx.hasActiveFilters.value ? 'the current filters' : 'this tab'
+							}}.
+						</p>
+						<BbButton
+							v-if="ctx.hasActiveFilters.value"
+							variant="ghost"
+							@click="ctx.clearFilters"
+						>
+							Clear filters
+						</BbButton>
+					</div>
+				</template>
+			</BbTable>
+
+			<BbPagination table-id="approvals-table" />
+		</div>
+
+		<SelectionBar />
+
+		<!-- Stacked peek sidebar: highlight opens the expense; names drill down. -->
+		<template #sidebar>
+			<ExpensePeek
+				v-if="ctx.shell.current.value?.type === 'expense'"
+				:expense-id="ctx.shell.current.value.id"
+			/>
+			<SubmitterPeek
+				v-else-if="ctx.shell.current.value?.type === 'submitter'"
+				:submitter-id="ctx.shell.current.value.id"
+			/>
+		</template>
+
+		<template #dialogs>
+			<RejectDialog />
+			<BulkRejectDialog />
+			<SnoozeDialog />
+		</template>
+	</PageShell>
+</template>
+
+<script setup lang="ts">
+import {
+	BbBadge,
+	BbBreadcrumbs,
+	BbButton,
+	BbPagination,
+	BbTable,
+	BbTabs,
+	BbTextInput,
+} from 'bitboss-ui';
+import PageShell from '@/components/layout/PageShell.vue';
+import { provideApprovalsInbox } from './context';
+import BulkRejectDialog from './BulkRejectDialog.vue';
+import ExpensePeek from './ExpensePeek.vue';
+import FilterRail from './FilterRail.vue';
+import ReceiptThumbnail from './ReceiptThumbnail.vue';
+import RejectDialog from './RejectDialog.vue';
+import RowActions from './RowActions.vue';
+import SelectionBar from './SelectionBar.vue';
+import ShortcutsHint from './ShortcutsHint.vue';
+import SnoozeDialog from './SnoozeDialog.vue';
+import SubmitterPeek from './SubmitterPeek.vue';
+import type { Expense, ExpenseStatus } from '@/types';
+
+const ctx = provideApprovalsInbox();
+
+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',
+	});
+const statusLabel = (status: ExpenseStatus) =>
+	({
+		needsApproval: 'Needs approval',
+		approved: 'Approved',
+		rejected: 'Rejected',
+		snoozed: 'Snoozed',
+	})[status];
+
+const columns = [
+	{ key: 'receipt', label: 'Receipt', width: 48 },
+	{ key: 'merchant', label: 'Merchant' },
+	{ key: 'submitter.name', label: 'Submitter' },
+	{ key: 'category', label: 'Category' },
+	{
+		key: 'amount',
+		label: 'Amount',
+		align: 'right' as const,
+		formatter: (value: number) => currency.format(value),
+	},
+	{ key: 'submittedAt', label: 'Submitted', formatter: shortDate },
+	{ key: 'status', label: 'Status' },
+];
+
+// Highlight ships unstyled — paint it via the public row-class API.
+const rowClass = (item: Expense) =>
+	ctx.table.highlighted.value === item.id
+		? 'bg-indigo-50 dark:bg-indigo-950/20'
+		: undefined;
+</script>
+```
+
+### FilterRail.vue
+
+```vue
+<!-- ApprovalsInbox/FilterRail.vue -->
+<template>
+	<div class="flex flex-wrap items-center gap-2">
+		<!-- Submitter: single, query-aware search against the API. -->
+		<BbSelectPopover
+			v-model="ctx.filters.submitterId"
+			item-text="name"
+			item-value="id"
+			:items="searchSubmitters"
+		>
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					append:icon="lucide:chevron-down"
+					size="sm"
+					variant="outline"
+				>
+					{{ submitterLabel }}
+				</BbButton>
+			</template>
+		</BbSelectPopover>
+
+		<!-- Category: multi-select pill. -->
+		<BbSelectPopover
+			v-model="ctx.filters.categories"
+			:items="['travel', 'meals', 'software', 'office', 'client', 'other']"
+			multiple
+		>
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					append:icon="lucide:chevron-down"
+					size="sm"
+					variant="outline"
+				>
+					Category{{
+						ctx.filters.categories.length
+							? ` · ${ctx.filters.categories.length}`
+							: ''
+					}}
+				</BbButton>
+			</template>
+		</BbSelectPopover>
+
+		<!-- Amount over: a quick-filter pill from preset thresholds. -->
+		<BbSelectPopover
+			v-model="ctx.filters.amountOver"
+			disable-writing
+			:items="[50, 100, 250, 500, 1000]"
+			width="160px"
+		>
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					append:icon="lucide:chevron-down"
+					size="sm"
+					variant="outline"
+				>
+					{{
+						ctx.filters.amountOver
+							? `Over $${ctx.filters.amountOver}`
+							: 'Amount'
+					}}
+				</BbButton>
+			</template>
+		</BbSelectPopover>
+
+		<!-- 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 { computed, ref, watchEffect } from 'vue';
+import { BbButton, BbSelectPopover } from 'bitboss-ui';
+import { useApprovalsInbox } from './context';
+import { api } from '@/api';
+import type { Submitter } from '@/types';
+
+const ctx = useApprovalsInbox();
+
+const searchSubmitters = (query: string): Promise<Submitter[]> =>
+	api.submitters.list({ search: query });
+
+// The trigger labels itself from page state (a standalone popover with a
+// seeded model stays lazy and has no resolvable `text` before first open).
+const selectedSubmitter = ref<Submitter | null>(null);
+watchEffect(async () => {
+	selectedSubmitter.value =
+		ctx.filters.submitterId == null
+			? null
+			: await api.submitters.get(ctx.filters.submitterId);
+});
+const submitterLabel = computed(
+	() => selectedSubmitter.value?.name ?? 'Submitter'
+);
+</script>
+```
+
+### ShortcutsHint.vue
+
+```vue
+<!-- ApprovalsInbox/ShortcutsHint.vue -->
+<template>
+	<div class="flex items-center gap-1">
+		<span class="mr-1 text-xs text-[color:var(--bb-text-muted)]"
+			>Shortcuts</span
+		>
+		<BbTooltip>
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					aria-label="Approve highlighted expense"
+					:disabled="!ctx.highlightedExpense.value"
+					icon="lucide:check"
+					size="xs"
+					variant="ghost"
+					@click="ctx.approveHighlighted"
+				/>
+			</template>
+			<span class="flex items-center gap-1.5">
+				Approve
+				<kbd
+					class="rounded border border-current px-1 font-mono text-[10px] leading-4 opacity-75"
+					>A</kbd
+				>
+			</span>
+		</BbTooltip>
+		<BbTooltip>
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					aria-label="Reject highlighted expense"
+					:disabled="!ctx.highlightedExpense.value"
+					icon="lucide:x"
+					size="xs"
+					variant="ghost"
+					@click="ctx.rejectHighlighted"
+				/>
+			</template>
+			<span class="flex items-center gap-1.5">
+				Reject
+				<kbd
+					class="rounded border border-current px-1 font-mono text-[10px] leading-4 opacity-75"
+					>R</kbd
+				>
+			</span>
+		</BbTooltip>
+		<BbTooltip>
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					aria-label="Snooze highlighted expense"
+					:disabled="!ctx.highlightedExpense.value"
+					icon="lucide:clock"
+					size="xs"
+					variant="ghost"
+					@click="ctx.snoozeHighlighted"
+				/>
+			</template>
+			<span class="flex items-center gap-1.5">
+				Snooze
+				<kbd
+					class="rounded border border-current px-1 font-mono text-[10px] leading-4 opacity-75"
+					>S</kbd
+				>
+			</span>
+		</BbTooltip>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbButton, BbTooltip } from 'bitboss-ui';
+import { useApprovalsInbox } from './context';
+
+const ctx = useApprovalsInbox();
+</script>
+```
+
+### ReceiptThumbnail.vue
+
+```vue
+<!-- ApprovalsInbox/ReceiptThumbnail.vue -->
+<template>
+	<img
+		v-if="expense.receiptUrl"
+		:alt="`Receipt from ${expense.merchant}`"
+		class="h-8 w-8 rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] object-cover"
+		:src="expense.receiptUrl"
+	/>
+	<div
+		v-else
+		aria-hidden="true"
+		class="flex h-8 w-8 items-center justify-center rounded-[var(--bb-radius)] border border-dashed border-[color:var(--bb-border)] text-[color:var(--bb-text-muted)]"
+	>
+		<BbIcon icon="lucide:receipt" size="14" />
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbIcon } from 'bitboss-ui';
+import type { Expense } from '@/types';
+
+defineProps<{ expense: Expense }>();
+</script>
+```
+
+### RowActions.vue
+
+```vue
+<!-- ApprovalsInbox/RowActions.vue -->
+<template>
+	<div class="flex items-center gap-1">
+		<BbTooltip text="Approve">
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					aria-label="Approve"
+					:disabled="resolved"
+					icon="lucide:check"
+					size="xs"
+					variant="ghost"
+					@click="() => ctx.approve(expense)"
+				/>
+			</template>
+		</BbTooltip>
+		<BbTooltip text="Reject">
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					aria-label="Reject"
+					:disabled="resolved"
+					icon="lucide:x"
+					size="xs"
+					variant="ghost"
+					@click="() => ctx.openReject(expense)"
+				/>
+			</template>
+		</BbTooltip>
+		<BbTooltip text="Snooze">
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					aria-label="Snooze"
+					:disabled="resolved"
+					icon="lucide:clock"
+					size="xs"
+					variant="ghost"
+					@click="() => ctx.openSnooze(expense)"
+				/>
+			</template>
+		</BbTooltip>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbButton, BbTooltip } from 'bitboss-ui';
+import { useApprovalsInbox } from './context';
+import type { Expense } from '@/types';
+
+const props = defineProps<{ expense: Expense }>();
+
+const ctx = useApprovalsInbox();
+
+const resolved = computed(
+	() =>
+		props.expense.status === 'approved' || props.expense.status === 'rejected'
+);
+</script>
+```
+
+### RejectDialog.vue
+
+```vue
+<!-- ApprovalsInbox/RejectDialog.vue -->
+<template>
+	<BbDialog
+		:model-value="expense !== null"
+		size="sm"
+		:title="expense ? `Reject — ${expense.merchant}` : ''"
+		@show="reason = ''"
+		@update:model-value="close"
+	>
+		<form
+			v-if="expense"
+			class="flex flex-col gap-3"
+			novalidate
+			@submit.prevent="submit"
+		>
+			<BbTextarea
+				v-model="reason"
+				label="Reason"
+				label-mode="outside"
+				placeholder="Why is this expense being rejected?"
+				rows="3"
+			/>
+			<div class="mt-1 flex justify-end gap-2">
+				<BbButton type="button" variant="ghost" @click="close">Cancel</BbButton>
+				<BbButton
+					:disabled="reason.trim().length < 3"
+					type="submit"
+					variant="destructive"
+				>
+					Reject expense
+				</BbButton>
+			</div>
+		</form>
+	</BbDialog>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbButton, BbDialog, BbTextarea } from 'bitboss-ui';
+import { useApprovalsInbox } from './context';
+
+const ctx = useApprovalsInbox();
+
+// The dialog's subject lives in the page context — the row action and the
+// peek's reject button both just assign it.
+const expense = computed(() => ctx.dialogs.reject.value);
+const close = () => {
+	ctx.dialogs.reject.value = null;
+};
+
+const reason = ref('');
+const submit = () =>
+	expense.value ? ctx.reject(expense.value, reason.value.trim()) : undefined;
+</script>
+```
+
+### BulkRejectDialog.vue
+
+```vue
+<!-- ApprovalsInbox/BulkRejectDialog.vue -->
+<template>
+	<BbDialog
+		:model-value="ctx.dialogs.bulkReject.value"
+		size="sm"
+		:title="`Reject ${count} expenses`"
+		@show="reason = ''"
+		@update:model-value="close"
+	>
+		<form class="flex flex-col gap-3" novalidate @submit.prevent="submit">
+			<BbTextarea
+				v-model="reason"
+				label="Reason"
+				label-mode="outside"
+				placeholder="Applied to every selected expense."
+				rows="3"
+			/>
+			<div class="mt-1 flex justify-end gap-2">
+				<BbButton type="button" variant="ghost" @click="close">Cancel</BbButton>
+				<BbButton
+					:disabled="reason.trim().length < 3"
+					type="submit"
+					variant="destructive"
+				>
+					Reject {{ count }} expenses
+				</BbButton>
+			</div>
+		</form>
+	</BbDialog>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbButton, BbDialog, BbTextarea } from 'bitboss-ui';
+import { useApprovalsInbox } from './context';
+
+const ctx = useApprovalsInbox();
+
+const count = computed(() => (ctx.table.selected.value as number[]).length);
+const close = () => {
+	ctx.dialogs.bulkReject.value = false;
+};
+
+const reason = ref('');
+const submit = () => ctx.bulkReject(reason.value.trim());
+</script>
+```
+
+### SnoozeDialog.vue
+
+```vue
+<!-- ApprovalsInbox/SnoozeDialog.vue -->
+<template>
+	<BbDialog
+		:model-value="expense !== null"
+		size="xs"
+		:title="expense ? `Snooze — ${expense.merchant}` : ''"
+		@show="until = tomorrow"
+		@update:model-value="close"
+	>
+		<form
+			v-if="expense"
+			class="flex flex-col gap-3"
+			novalidate
+			@submit.prevent="submit"
+		>
+			<BbDatePickerInput
+				v-model="until"
+				floating
+				label="Snooze until"
+				label-mode="outside"
+				:min="tomorrow"
+			/>
+			<div class="mt-1 flex justify-end gap-2">
+				<BbButton type="button" variant="ghost" @click="close">Cancel</BbButton>
+				<BbButton type="submit" variant="secondary">Snooze</BbButton>
+			</div>
+		</form>
+	</BbDialog>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbButton, BbDatePickerInput, BbDialog } from 'bitboss-ui';
+import { useApprovalsInbox } from './context';
+
+const ctx = useApprovalsInbox();
+
+const expense = computed(() => ctx.dialogs.snooze.value);
+const close = () => {
+	ctx.dialogs.snooze.value = null;
+};
+
+const tomorrow = new Date(Date.now() + 86_400_000).toISOString().slice(0, 10);
+const until = ref(tomorrow);
+const submit = () =>
+	expense.value ? ctx.snooze(expense.value, until.value) : undefined;
+</script>
+```
+
+### SelectionBar.vue
+
+```vue
+<!-- ApprovalsInbox/SelectionBar.vue -->
+<template>
+	<FloatingBottomPanel :open="selectedCount > 0">
+		<span class="px-2 text-sm">{{ selectedCount }} selected</span>
+		<BbButton
+			prepend:icon="lucide:check"
+			size="sm"
+			variant="ghost"
+			@click="ctx.bulkApprove"
+		>
+			Approve
+		</BbButton>
+		<div class="floating-bottom-panel__right flex items-center gap-1">
+			<BbButton size="sm" variant="destructive" @click="ctx.openBulkReject">
+				Reject
+			</BbButton>
+			<BbButton
+				aria-label="Clear selection"
+				icon="lucide:x"
+				size="sm"
+				variant="ghost"
+				@click="clearSelection"
+			/>
+		</div>
+	</FloatingBottomPanel>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbButton } from 'bitboss-ui';
+import FloatingBottomPanel from '@/components/layout/FloatingBottomPanel.vue';
+import { useApprovalsInbox } from './context';
+
+const ctx = useApprovalsInbox();
+
+const selectedCount = computed(() => ctx.table.selected.value?.length ?? 0);
+const clearSelection = () => {
+	ctx.table.selected.value = [];
+};
+</script>
+```
+
+### ExpensePeek.vue
+
+```vue
+<!-- ApprovalsInbox/ExpensePeek.vue -->
+<template>
+	<div v-if="expense" class="flex flex-col gap-4 text-sm">
+		<!-- Header: identity + amount + status. -->
+		<header class="flex flex-col gap-1.5">
+			<div class="flex items-center justify-between gap-2">
+				<h2 class="text-base font-semibold">{{ expense.merchant }}</h2>
+				<BbBadge variant="outline">{{ statusLabel(expense.status) }}</BbBadge>
+			</div>
+			<p class="text-xl font-semibold">{{ currency.format(expense.amount) }}</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Submitted {{ longDate(expense.submittedAt) }}
+			</p>
+		</header>
+
+		<!-- Receipt: bigger than the row thumbnail, with a full-size link out. -->
+		<section class="flex flex-col gap-1.5">
+			<h3
+				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
+			>
+				Receipt
+			</h3>
+			<img
+				v-if="expense.receiptUrl"
+				:alt="`Receipt from ${expense.merchant}`"
+				class="h-40 w-full rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] object-cover"
+				:src="expense.receiptUrl"
+			/>
+			<p v-else class="text-xs text-[color:var(--bb-text-muted)]">
+				No receipt attached.
+			</p>
+			<BbButton
+				v-if="expense.receiptUrl"
+				append:icon="lucide:arrow-up-right"
+				:href="expense.receiptUrl"
+				size="sm"
+				target="_blank"
+				variant="ghost"
+			>
+				View full-size receipt
+			</BbButton>
+		</section>
+
+		<!-- Properties: submitter name drills DOWN — stacked peek, back arrow. -->
+		<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
+			<dt class="text-[color:var(--bb-text-muted)]">Submitter</dt>
+			<dd>
+				<BbButton
+					size="sm"
+					variant="link"
+					@click="() => ctx.stackSubmitter(expense!.submitter.id)"
+				>
+					{{ expense.submitter.name }}
+				</BbButton>
+			</dd>
+			<dt class="text-[color:var(--bb-text-muted)]">Category</dt>
+			<dd class="capitalize">{{ expense.category }}</dd>
+			<dt class="text-[color:var(--bb-text-muted)]">Memo</dt>
+			<dd>{{ expense.memo ?? '—' }}</dd>
+		</dl>
+
+		<!-- Activity feed. -->
+		<section class="flex flex-col gap-1.5">
+			<h3
+				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
+			>
+				Activity
+			</h3>
+			<ul class="flex flex-col gap-2">
+				<li
+					v-for="entry in expense.activity"
+					:key="entry.id"
+					class="flex gap-2"
+				>
+					<BbIcon
+						class="mt-0.5 shrink-0 text-[color:var(--bb-text-muted)]"
+						:icon="entry.icon"
+						size="14"
+					/>
+					<div class="flex flex-col">
+						<span>{{ entry.text }}</span>
+						<span class="text-xs text-[color:var(--bb-text-muted)]"
+							>{{ entry.actor }} · {{ longDate(entry.at) }}</span
+						>
+					</div>
+				</li>
+			</ul>
+		</section>
+
+		<!-- Peek is a workbench: the same three actions as the row, plus the real page. -->
+		<footer class="mt-2 flex flex-wrap items-center gap-2 border-t pt-3">
+			<BbButton
+				:disabled="resolved"
+				prepend:icon="lucide:check"
+				size="sm"
+				variant="secondary"
+				@click="() => ctx.approve(expense!)"
+			>
+				Approve
+			</BbButton>
+			<BbButton
+				:disabled="resolved"
+				prepend:icon="lucide:x"
+				size="sm"
+				variant="destructive"
+				@click="() => ctx.openReject(expense!)"
+			>
+				Reject
+			</BbButton>
+			<BbButton
+				:disabled="resolved"
+				prepend:icon="lucide:clock"
+				size="sm"
+				variant="outline"
+				@click="() => ctx.openSnooze(expense!)"
+			>
+				Snooze
+			</BbButton>
+			<BbButton
+				append:icon="lucide:arrow-up-right"
+				class="ml-auto"
+				size="sm"
+				:to="`/expenses/${expense.id}`"
+				variant="ghost"
+			>
+				Open full expense
+			</BbButton>
+		</footer>
+	</div>
+
+	<div v-else class="flex justify-center p-8">
+		<BbSpinner />
+	</div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref, watchEffect } from 'vue';
+import { BbBadge, BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
+import { useApprovalsInbox } from './context';
+import { api } from '@/api';
+import type { ExpenseDetail, ExpenseStatus } from '@/types';
+
+const props = defineProps<{ expenseId: number }>();
+
+const ctx = useApprovalsInbox();
+
+// Re-fetches whenever the stack shows a different expense; refreshKey makes
+// approve/reject/snooze reflect here immediately.
+const expense = ref<ExpenseDetail | null>(null);
+watchEffect(async () => {
+	void ctx.refreshKey.value;
+	expense.value = await api.expenses.get(props.expenseId);
+});
+
+const resolved = computed(
+	() =>
+		expense.value?.status === 'approved' || expense.value?.status === 'rejected'
+);
+
+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',
+	});
+const statusLabel = (status: ExpenseStatus) =>
+	({
+		needsApproval: 'Needs approval',
+		approved: 'Approved',
+		rejected: 'Rejected',
+		snoozed: 'Snoozed',
+	})[status];
+</script>
+```
+
+### SubmitterPeek.vue
+
+```vue
+<!-- ApprovalsInbox/SubmitterPeek.vue -->
+<template>
+	<div v-if="submitter" class="flex flex-col gap-4 text-sm">
+		<header class="flex items-center gap-3">
+			<BbAvatar :alt="submitter.name" :src="submitter.avatarUrl" />
+			<div class="flex flex-col">
+				<h2 class="text-base font-semibold">{{ submitter.name }}</h2>
+				<p class="text-xs text-[color:var(--bb-text-muted)]">
+					{{ submitter.email }} · {{ submitter.team }}
+				</p>
+			</div>
+		</header>
+
+		<!-- Stat strip. -->
+		<div class="grid grid-cols-3 gap-2">
+			<div class="rounded-[var(--bb-radius)] border p-2">
+				<p class="text-xs text-[color:var(--bb-text-muted)]">Submitted (YTD)</p>
+				<p class="font-semibold">
+					{{ currency.format(submitter.totalSubmitted) }}
+				</p>
+			</div>
+			<div class="rounded-[var(--bb-radius)] border p-2">
+				<p class="text-xs text-[color:var(--bb-text-muted)]">Pending</p>
+				<p class="font-semibold">{{ submitter.pendingCount }}</p>
+			</div>
+			<div class="rounded-[var(--bb-radius)] border p-2">
+				<p class="text-xs text-[color:var(--bb-text-muted)]">Approval rate</p>
+				<p class="font-semibold">{{ submitter.approvalRate }}%</p>
+			</div>
+		</div>
+
+		<!-- Recent expenses: names drill down again — the stack keeps growing. -->
+		<section class="flex flex-col gap-1.5">
+			<h3
+				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
+			>
+				Recent expenses
+			</h3>
+			<ul class="flex flex-col">
+				<li
+					v-for="recent in submitter.recentExpenses"
+					: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.stackExpense(recent.id)"
+					>
+						{{ recent.merchant }}
+					</BbButton>
+					<BbBadge variant="outline">{{ recent.status }}</BbBadge>
+					<span class="text-xs text-[color:var(--bb-text-muted)]">{{
+						currency.format(recent.amount)
+					}}</span>
+				</li>
+			</ul>
+		</section>
+
+		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
+			<BbButton
+				append:icon="lucide:arrow-up-right"
+				size="sm"
+				:to="`/people/${submitter.id}`"
+				variant="ghost"
+			>
+				Open profile
+			</BbButton>
+		</footer>
+	</div>
+
+	<div v-else class="flex justify-center p-8">
+		<BbSpinner />
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref, watchEffect } from 'vue';
+import { BbAvatar, BbBadge, BbButton, BbSpinner } from 'bitboss-ui';
+import { useApprovalsInbox } from './context';
+import { api } from '@/api';
+import type { SubmitterDetail } from '@/types';
+
+const props = defineProps<{ submitterId: number }>();
+
+const ctx = useApprovalsInbox();
+
+const submitter = ref<SubmitterDetail | null>(null);
+watchEffect(async () => {
+	submitter.value = await api.submitters.getDetail(props.submitterId);
+});
+
+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 `table` are joined
+  once in `provideApprovalsInbox()`; twelve components share filters,
+  selection, highlight, the peek stack, the keyboard shortcuts and every
+  action through one `useApprovalsInbox()` call.
+- **Highlight is the trigger, not a bespoke click handler.** Per the
+  `BbTable` guide, `highlighted` is "a parallel, UI-intent state…
+  independent of selection" that ships unstyled — this recipe is exactly
+  the case the guide's Row Highlight section describes: a `watch` on
+  `table.highlighted` is the entire wiring between "arrow to a row" and
+  "the peek is open", and `keyboard-navigation`'s Enter/Space "activate…
+  through the same path as a mouse click" means the mouse and the keyboard
+  share one code path for free.
+- **`item-value="id"`** is what lets `table.highlighted` (and
+  `table.selected`) hold plain ids instead of whole objects — the keyboard
+  handler and the peek both resolve the full `Expense` from a small
+  `lastItems` cache populated by `fetchExpenses`, never from the table's
+  internal row wrapper.
+- **One dispatch path per action, three entry points.** `approve`,
+  `openReject` and `openSnooze` are called identically from `RowActions`,
+  `ExpensePeek`'s footer, and the `A`/`R`/`S` keyboard handlers
+  (`approveHighlighted` etc. are the same functions, resolved against
+  `highlightedExpense` instead of a row prop) — there is exactly one place
+  each action's API call, refresh and toast live.
+- **Reason and date are dialogs, not confirms.** Per the pattern catalog
+  (§6.2), "anything needing input opens a `BbDialog`" — reject needs a
+  typed reason, snooze needs a date, so both get a small dialog whose
+  open-state is the subject itself (`ctx.dialogs.reject` holds the
+  `Expense`, not a boolean), exactly like the flagship's
+  `RecordPaymentDialog`. Bulk reject is destructive **and** needs input,
+  so it layers a `useConfirm` on top of the dialog's own submit.
+- **The shortcut guard mirrors `useDeleteCmd`.** `isInteractiveElementFocused()`
+  is copied verbatim from the Inertia Helpers guide's `useDeleteCmd` (which
+  the guide notes "works on any platform") so typing a rejection reason
+  never fires `R`; the handler also bails while any dialog is open.
+- **`peekX` vs `stackX` is the whole stack grammar**, unchanged from the
+  flagship: highlighting always **replaces** (`peekExpense`, `true`),
+  clicking a submitter's name always **pushes** (`stackSubmitter`), and the
+  shell renders the back arrow once depth > 1 — from a row, from inside
+  the expense peek, or drilling back from the submitter peek's own recent
+  expenses.
+- **Sizing:** topbar and rail follow `md`-first; `sm`/`xs` appear exactly
+  where the doctrine allows — table rows (`xs`, the densest surface), the
+  shortcut bar (`xs`), the peek footers and the bulk bar (`sm`).
+- **No `variant="primary"` on this page.** Triage has no "create" action —
+  the one-primary-action rule is satisfied vacuously; every action here is
+  either a one-click mutation, a gated mutation via dialog, or navigation.
+
+## Variations
+
+- **No snooze**: drop `SnoozeDialog.vue`, the `S` shortcut, and the
+  `snoozed` tab state — the remaining approve/reject pair still clears the
+  ≥ 12 action bar on its own via the bulk/keyboard/peek spread.
+- **Auto-advance after action**: after `approve`/`reject` resolves, call
+  `table.highlighted.value = nextExpenseId` (the id following the acted-on
+  row in `lastItems`) so triage keeps moving without a re-highlight —
+  the classic "Superhuman" flow.
+- **Per-category routing**: seed `filters.categories` from a saved view
+  per approver role (a store-backed default) instead of starting empty.