bitboss-ui 2.1.134 → 3.0.0-alpha.1

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

@@ -0,0 +1,1598 @@
+---
+title: Approvals Inbox (Inertia)
+summary: Keyboard-first expense-approvals triage for Laravel + Inertia — `keyboard-navigation` with highlight-opens-peek, one-click approve, reject-with-reason and snooze dialogs via promise-wrapped visits, bulk approve/reject with select-all-across-pages, and an `A`/`R`/`S` shortcut bar, all through one page context that coopts the Inertia Helpers toolkit.
+---
+
+# Recipe: Approvals Inbox (Inertia)
+
+The densest advanced-page recipe in the folder, adapted for **Laravel +
+Inertia**: the same Linear-triage × Expensify-approvals expense inbox —
+`keyboard-navigation` with the highlight driving the peek, one-click
+approve, reject-with-reason and snooze dialogs, a floating bulk-action bar
+with select-all-across-pages, and an `A`/`R`/`S` shortcut bar — but the list
+is a page prop via [`useTableContext`](../../guides/inertia-helpers.md),
+filters mirror into the URL through
+[`useQueryObject`](../../guides/inertia-helpers.md), tabs are real,
+partial-reloaded server visits, and every mutation is a promise-wrapped
+`router.visit`. 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/approvals-inbox.md) ·
+[Nuxt](../nuxt/approvals-inbox.md).
+
+## Prerequisites
+
+- `<BbConfirm />` and `<BbToast />` mounted once in the app layout.
+- From the [Inertia Helpers](../../guides/inertia-helpers.md) toolkit:
+  `useTableContext`, `useQueryObject`, `useResourceContext`, `useProp`,
+  `useQuery`.
+- Controller: `Inertia::render('Approvals/Index', ['expenses' =>
+ExpensePaginator::make(...), 'tabCounts' => [...]])` — `expenses` is a
+  standard Laravel paginator (`PaginatedResponse<Expense>`) and `tabCounts`
+  a plain `{ needsApproval, approved, rejected, all }` map. Both are re-sent
+  on every partial reload the page triggers
+  (`only: ['expenses', 'tabCounts']`). Mutation routes are plain Laravel
+  routes (`PATCH /expenses/:id/approve`, `POST /expenses/:id/reject`,
+  `PATCH /expenses/:id/snooze`, `PATCH /expenses/bulk/approve`,
+  `POST /expenses/bulk/reject`) that redirect back; small JSON GET
+  endpoints (`GET /expenses/:id/peek`, `GET /submitters/:id/peek`,
+  `GET /submitters/search`) back the sidebar peeks and the submitter filter
+  pill so opening one is not a full-page visit.
+
+## Key ideas
+
+- **Highlight drives the peek — but it is a plain local ref here.** The
+  Inertia data context (`useTableContext`) mirrors only what the server
+  sent (items, pagination, selection); it has no concept of "the row under
+  the roving tabindex" because the server never sends that. So
+  `ctx.highlighted` is a small local ref bound to `BbTable`'s own
+  `v-model:highlighted`, watched in `context.ts` exactly like the Vue/Nuxt
+  `table.highlighted` — every highlight change still replaces the
+  sidebar's stack with that expense, and `keyboard-navigation`'s
+  Enter/Space still shares the mouse's code path for free.
+- **One coopting page context.** `provideApprovalsInbox()` joins the
+  page-shell stack **and** the keyed `useTableContext('expenses')` once,
+  owns filters/tab/dialogs/highlight, and exposes complete actions. Every
+  leaf calls `useApprovalsInbox()` and nothing else.
+- **The table has no client-side fetch at all.** `expenses` arrives as a
+  page prop; `useTableContext('expenses')` turns it into `items` +
+  `totalItems`/`page`/`perPage` (URL-backed) + `selected`/`unselected`/`all`
+  (select-all-across-pages), and `BbTable` binds directly to that handle —
+  no `dependencies`, no items function.
+- **Filters mirror into the URL with `useQueryObject`.** Typing in a pill
+  filter performs a debounced partial Inertia visit
+  (`only: ['expenses', 'tabCounts']`); the server is the single source of
+  filtered, paginated truth.
+- **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.
+- **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.approve(...)` reads the same everywhere.
+- **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 visit, 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.
+- **Bulk actions carry the full select-all-across-pages payload**
+  (`ids`/`all`/`unselected`) so "select all, deselect three, approve" sends
+  the same semantics the table itself models.
+- **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`. This
+  code is byte-for-byte identical across all three platforms.
+- **Clicking a submitter's name always stacks**, fetched from a small JSON
+  endpoint via `useResourceContext` — not a full-page visit, so opening the
+  sidebar never replaces the list underneath it.
+- **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.
+
+## Page anatomy
+
+```
+ApprovalsInbox/
+	Index.vue            ← assembly: PageShell slots, table, tabs, pagination
+	context.ts            ← coopting page context (shell + useTableContext + filters + highlight + 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` → `useQueryObject` partial visit               |
+| 2   | Filter by submitter              | filter rail pill                                       | `BbSelectPopover` single, query-aware (small JSON endpoint)     |
+| 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                       | server-visit tabs with counts                          | `BbTabs` `href` + `server: true` visit                          |
+| 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.highlighted` watcher → `peekExpense` (replace), JSON fetch |
+| 9   | Approve (one click)              | row icon button, peek footer, key `A`                  | `approve(expense)` — promise-wrapped visit + 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                                       | `useTableContext` selection (across pages)                      |
+| 13  | Bulk approve                     | floating bottom panel                                  | `bulkApprove()` on `table.selected`/`all`/`unselected`          |
+| 14  | Bulk reject with reason          | floating bottom panel                                  | `BulkRejectDialog`, destructive                                 |
+| 15  | Stack a submitter                | submitter cell / peek property                         | `stackSubmitter(id)` → shell stack, JSON fetch                  |
+| 16  | Stack an expense from a profile  | recent-expense row inside `SubmitterPeek`              | `stackExpense(id)` → shell stack, JSON fetch                    |
+| 17  | View full-size receipt           | peek "View receipt" link                               | navigation (`href`, new tab)                                    |
+| 18  | Open full expense                | peek footer                                            | navigation (`href="/expenses/:id"`)                             |
+| 19  | Back / close peek                | shell chrome                                           | shell stack pop / close                                         |
+
+Nineteen distinct actions, spanning inline one-click mutation (9),
+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 { router } from '@inertiajs/vue3';
+import type { RequestPayload } from '@inertiajs/core';
+import { useMagicKeys, whenever } from '@vueuse/core';
+import { useConfirm, useToast } 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 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;
+}
+
+const RELOAD_PROPS = ['expenses', 'tabCounts'] as const;
+
+export interface ApprovalsInboxContext {
+	// -- Coopted contexts ------------------------------------------------------
+	shell: PageShellContext<PeekItem>;
+	table: TableContext<Expense, number>;
+	/**
+	 * The row under the roving tabindex. A plain local ref — the data context
+	 * above mirrors only what the server sent, and highlight is not server
+	 * data — bound to `BbTable`'s own `v-model:highlighted`.
+	 */
+	highlighted: Ref<number | null>;
+	// -- Page-owned state --------------------------------------------------------
+	filters: ApprovalsFilters;
+	hasActiveFilters: ComputedRef<boolean>;
+	tab: Ref<ApprovalsTab>;
+	tabCounts: ComputedRef<Record<ApprovalsTab, number>>;
+	dialogs: {
+		reject: Ref<Expense | null>;
+		bulkReject: Ref<boolean>;
+		snooze: Ref<Expense | null>;
+	};
+	/** Bumped after every mutation — peeks watch it to re-fetch their JSON detail. */
+	refreshKey: Ref<number>;
+	/** The expense under the roving tabindex, resolved from the current page's items. */
+	highlightedExpense: ComputedRef<Expense | null>;
+	// -- 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: visit + 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';
+};
+
+/** Comma-joined query value → typed array (or `[]` when absent). */
+const toArray = <T = string>(value: unknown): T[] => {
+	if (value == null || value === '') return [];
+	const raw = Array.isArray(value) ? value : String(value).split(',');
+	return raw as T[];
+};
+
+/** 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 provideApprovalsInbox(): ApprovalsInboxContext {
+	const { toast } = useToast();
+	const { confirm } = useConfirm();
+
+	// -- Coopt the specific contexts: once, here, for the whole page. ----------
+	const shell = usePageShellContext<PeekItem>();
+	// `Expense, number`: BbTable's `item-value="id"` resolves selection to
+	// expense ids, matching the Vue/Nuxt `table.selected: number[]` shape.
+	const table = useTableContext<Expense, number>('expenses');
+	// Highlight is not server data, so it does not live on `table` — a plain
+	// local ref bound to BbTable's own `v-model:highlighted`.
+	const highlighted = ref<number | null>(null);
+
+	// -- Filters: seeded from the current URL, mirrored back by useQueryObject. -
+	const query = useQuery();
+	const filters = reactive<ApprovalsFilters>({
+		search: (query.search as string) ?? '',
+		submitterId: query.submitterId ? Number(query.submitterId) : null,
+		categories: toArray<ExpenseCategory>(query.categories),
+		amountOver: query.amountOver ? Number(query.amountOver) : null,
+	});
+	useQueryObject(filters, { only: [...RELOAD_PROPS] });
+
+	const hasActiveFilters = computed(
+		() =>
+			filters.search !== '' ||
+			filters.submitterId !== null ||
+			filters.categories.length > 0 ||
+			filters.amountOver !== null
+	);
+	const clearFilters = () => {
+		filters.search = '';
+		filters.submitterId = null;
+		filters.categories = [];
+		filters.amountOver = null;
+	};
+
+	// 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<ApprovalsTab>((query.tab as ApprovalsTab) ?? 'needsApproval');
+	const tabCounts = useProp<Record<ApprovalsTab, number>>('tabCounts');
+
+	const refreshKey = ref(0);
+	const dialogs = {
+		reject: ref<Expense | null>(null),
+		bulkReject: ref(false),
+		snooze: ref<Expense | null>(null),
+	};
+
+	// -- 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.
+	watch(highlighted, (id) => {
+		if (id == null) {
+			shell.close();
+		} else {
+			peekExpense(id);
+		}
+	});
+
+	const highlightedExpense = computed<Expense | null>(
+		() =>
+			table.items.value.find((expense) => expense.id === highlighted.value) ??
+			null
+	);
+
+	// -- Actions ----------------------------------------------------------------------
+	const refresh = () => {
+		refreshKey.value++;
+	};
+	const clearSelection = () => {
+		table.resetSelection();
+	};
+
+	const approve = async (expense: Expense) => {
+		await visit('patch', `/expenses/${expense.id}/approve`);
+		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 visit('post', `/expenses/${expense.id}/reject`, { 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 visit('patch', `/expenses/${expense.id}/snooze`, { until });
+		dialogs.snooze.value = null;
+		refresh();
+		toast({ title: `${expense.merchant} snoozed.`, variant: 'success' });
+	};
+
+	// 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 bulkApprove = async () => {
+		const count = bulkCount();
+		await visit('patch', '/expenses/bulk/approve', bulkPayload());
+		clearSelection();
+		refresh();
+		toast({ title: `${count} expenses approved.`, variant: 'success' });
+	};
+
+	const openBulkReject = () => {
+		dialogs.bulkReject.value = true;
+	};
+	const bulkReject = async (reason: string) => {
+		const count = bulkCount();
+		const ok = await confirm({
+			variant: 'destructive',
+			title: 'Reject expenses',
+			text: `Reject ${count} expenses? The submitters are notified.`,
+			yes: 'Reject',
+			no: 'Cancel',
+		});
+		if (!ok) return;
+		await visit('post', '/expenses/bulk/reject', { ...bulkPayload(), reason });
+		dialogs.bulkReject.value = false;
+		clearSelection();
+		refresh();
+		toast({ title: `${count} 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,
+		highlighted,
+		filters,
+		hasActiveFilters,
+		tab,
+		tabCounts,
+		dialogs,
+		refreshKey,
+		highlightedExpense,
+		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', href: '/dashboard' },
+						{ key: 'finance', text: 'Finance', href: '/finance' },
+						{ key: 'approvals', text: 'Approvals' },
+					]"
+				/>
+				<BbTextInput
+					v-model="ctx.filters.search"
+					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 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: 'needsApproval',
+							label: `Needs approval · ${ctx.tabCounts.value.needsApproval}`,
+							href: '/approvals?tab=needsApproval',
+							server: true,
+							only: ['expenses', 'tabCounts'],
+						},
+						{
+							key: 'approved',
+							label: `Approved · ${ctx.tabCounts.value.approved}`,
+							href: '/approvals?tab=approved',
+							server: true,
+							only: ['expenses', 'tabCounts'],
+						},
+						{
+							key: 'rejected',
+							label: `Rejected · ${ctx.tabCounts.value.rejected}`,
+							href: '/approvals?tab=rejected',
+							server: true,
+							only: ['expenses', 'tabCounts'],
+						},
+						{
+							key: 'all',
+							label: `All · ${ctx.tabCounts.value.all}`,
+							href: '/approvals?tab=all',
+							server: true,
+							only: ['expenses', 'tabCounts'],
+						},
+					]"
+				/>
+				<ShortcutsHint />
+			</div>
+
+			<!-- No dependencies/items-fn: `expenses` is a page prop, selection
+			     (across pages) binds straight onto the keyed table context, and
+			     highlight is a plain local ref since the server never sends it. -->
+			<BbTable
+				v-model="ctx.table.selected.value"
+				v-model:highlighted="ctx.highlighted.value"
+				v-model:select-all="ctx.table.all.value"
+				v-model:unselected-items="ctx.table.unselected.value"
+				actions
+				caption="Expense approvals"
+				:columns="columns"
+				compact
+				item-value="id"
+				:items="ctx.table.items.value"
+				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-gray-500">
+							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>
+
+			<!-- No table-id: the keyed table context is the page count here. -->
+			<BbPagination
+				v-model="ctx.table.page.value"
+				label="Expense approvals pagination"
+				:total-pages="ctx.table.totalPages.value"
+			/>
+		</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.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 a small JSON endpoint. -->
+		<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 type { Submitter } from '@/types';
+
+const ctx = useApprovalsInbox();
+
+// Query-aware items function: BbSelectPopover calls it with the search text.
+// A small JSON endpoint, not an Inertia visit — searching a filter pill
+// must not re-render the page.
+const searchSubmitters = (query: string): Promise<Submitter[]> =>
+	fetch(`/submitters/search?q=${encodeURIComponent(query)}`).then((res) =>
+		res.json()
+	);
+
+// The trigger labels itself from page state (the popover is lazy by design
+// and cannot know the selected label before its first open).
+const selectedSubmitter = ref<Submitter | null>(null);
+watchEffect(async () => {
+	selectedSubmitter.value =
+		ctx.filters.submitterId == null
+			? null
+			: await fetch(`/submitters/${ctx.filters.submitterId}/peek`).then((res) =>
+					res.json()
+				);
+});
+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-gray-500">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-gray-200 object-cover dark:border-gray-700"
+		: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-gray-300 text-gray-400 dark:border-gray-600"
+	>
+		<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="ctx.table.resetSelection"
+			/>
+		</div>
+	</FloatingBottomPanel>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbButton } from 'bitboss-ui';
+import { useApprovalsInbox } from './context';
+import FloatingBottomPanel from '@/components/layout/FloatingBottomPanel.vue';
+
+const ctx = useApprovalsInbox();
+
+// `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>
+```
+
+### 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-gray-500">
+				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-gray-500">
+				Receipt
+			</h3>
+			<img
+				v-if="expense.receiptUrl"
+				:alt="`Receipt from ${expense.merchant}`"
+				class="h-40 w-full rounded-[var(--bb-radius)] border border-gray-200 object-cover dark:border-gray-700"
+				:src="expense.receiptUrl"
+			/>
+			<p v-else class="text-xs text-gray-500">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-gray-500">Submitter</dt>
+			<dd>
+				<BbButton
+					size="sm"
+					variant="link"
+					@click="() => ctx.stackSubmitter(expense!.submitter.id)"
+				>
+					{{ expense.submitter.name }}
+				</BbButton>
+			</dd>
+			<dt class="text-gray-500">Category</dt>
+			<dd class="capitalize">{{ expense.category }}</dd>
+			<dt class="text-gray-500">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-gray-500">
+				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-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>
+
+		<!-- 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"
+				:href="`/expenses/${expense.id}`"
+				size="sm"
+				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, watch } from 'vue';
+import { BbBadge, BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
+import { useResourceContext } from '@/composables/useResourceContext';
+import { useApprovalsInbox } from './context';
+import type { ExpenseDetail, ExpenseStatus } from '@/types';
+
+const props = defineProps<{ expenseId: number }>();
+
+const ctx = useApprovalsInbox();
+
+// A small JSON endpoint, not a page visit — opening the peek never
+// re-renders the list underneath it. Re-fetches whenever the stack shows a
+// different expense; `refreshKey` makes mutations (approve/reject/snooze)
+// reflect here immediately.
+const { data: expense, refresh } = useResourceContext<ExpenseDetail, number>(
+	() => props.expenseId,
+	(id) => fetch(`/expenses/${id}/peek`).then((res) => res.json())
+);
+watch(() => ctx.refreshKey.value, refresh);
+
+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-gray-500">
+					{{ 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-gray-500">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-gray-500">Pending</p>
+				<p class="font-semibold">{{ submitter.pendingCount }}</p>
+			</div>
+			<div class="rounded-[var(--bb-radius)] border p-2">
+				<p class="text-xs text-gray-500">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-gray-500">
+				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-gray-500">{{
+						currency.format(recent.amount)
+					}}</span>
+				</li>
+			</ul>
+		</section>
+
+		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
+			<BbButton
+				append:icon="lucide:arrow-up-right"
+				:href="`/people/${submitter.id}`"
+				size="sm"
+				variant="ghost"
+			>
+				Open profile
+			</BbButton>
+		</footer>
+	</div>
+
+	<div v-else class="flex justify-center p-8">
+		<BbSpinner />
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbAvatar, BbBadge, BbButton, BbSpinner } from 'bitboss-ui';
+import { useResourceContext } from '@/composables/useResourceContext';
+import { useApprovalsInbox } from './context';
+import type { SubmitterDetail } from '@/types';
+
+const props = defineProps<{ submitterId: number }>();
+
+const ctx = useApprovalsInbox();
+
+const { data: submitter } = useResourceContext<SubmitterDetail, number>(
+	() => props.submitterId,
+	(id) => fetch(`/submitters/${id}/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('expenses')` 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 a plain local ref, not part of the data context.** Per
+  the [Inertia Helpers](../../guides/inertia-helpers.md) rule of thumb, the
+  keyed data contexts "own what the server sent" — items, pagination,
+  selection — while anything the table widget does on its own (sort,
+  highlight) is not server data. `ctx.highlighted` is bound to `BbTable`'s
+  own `v-model:highlighted` and watched exactly like `table.highlighted`
+  in the Vue/Nuxt recipes, so the peek grammar and the keyboard dispatch
+  are unchanged.
+- **`expenses` 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 that handle 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.
+- **One watcher for filters, one visit mechanism for tabs.**
+  `useQueryObject(filters, { only: ['expenses', 'tabCounts'] })` 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**
+  called for by the base recipe's platform notes: it turns Inertia's
+  `onSuccess`/`onError` callbacks into a promise so every context action
+  (`approve`, `reject`, `snooze`, the bulk actions, …) stays an `async
+function` — identical call sites to the Vue/Nuxt recipes,
+  `await ctx.approve(...)`.
+- **Bulk actions carry the full select-all-across-pages payload**
+  (`ids`/`all`/`unselected`) so "select all, deselect three, approve" 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 bumps it) — opening or updating a
+  peek never re-renders the list page underneath it.
+- **`item-value="id"`** is what lets `table.selected`/`table.unselected`
+  and `ctx.highlighted` all hold plain ids instead of whole objects — the
+  keyboard handler and the peek both resolve the full `Expense` from
+  `table.items` (the current page's server-sent rows).
+- **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).
+- **Reason and date are dialogs, not confirms**, exactly as in the Vue
+  recipe: `ctx.dialogs.reject` holds the subject `Expense`, not a boolean,
+  so the row action and the peek's reject button both just assign it.
+- **The shortcut guard mirrors `useDeleteCmd`.** `isInteractiveElementFocused()`
+  is copied verbatim from the [Inertia Helpers](../../guides/inertia-helpers.md)
+  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. This is the natural home to promote the guard into
+  the shared toolkit as a reusable `useSingleLetterCmd`-shaped helper
+  (reported, not patched here — see Report below).
+- **`peekX` vs `stackX` is the whole stack grammar**, unchanged from the
+  Vue recipe: highlighting always **replaces** (`peekExpense`, `true`),
+  clicking a submitter's name always **pushes** (`stackSubmitter`), and the
+  shell renders the back arrow once depth > 1.
+- **Sizing:** topbar and rail follow `md`-first; `sm`/`xs` appear exactly
+  where the doctrine allows — table rows, the shortcut bar, the peek
+  footers and the bulk bar.
+- **No `variant="primary"` on this page.** Triage has no "create" action —
+  every action here is either a one-click mutation, a gated mutation via
+  dialog, a bulk mutation, 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, set
+  `ctx.highlighted.value = nextExpenseId` (the id following the acted-on
+  row in `table.items.value`) 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.
+- **Lazy tab counts**: if `tabCounts` is expensive to compute, share it as
+  `Inertia::lazy()` and read it with `useLazyProp` instead of a plain
+  prop — the tab labels resolve once it lands instead of blocking the
+  first render.