bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/recipes/nuxt/inline-edit-workspace.md

@@ -0,0 +1,1703 @@
+---
+title: Inline-Edit Workspace (Nuxt)
+summary: Linear-style sprint backlog for Nuxt where every cell autosaves — optimistic per-field overlay with rollback, commit-on-blur text cells, spinner-in-the-chevron badge pickers, an async assignee search, bulk bar and peek workbench, filters URL-synced and data fetched with useAsyncData (the overlay retires in its transform), all through one coopting page context.
+---
+
+# Recipe: Inline-Edit Workspace (Nuxt)
+
+The flagship of pattern **§6.8 — autosave cells**, adapted for **Nuxt**: a
+Linear-grade sprint backlog where **every cell persists itself and the page
+has no Save button anywhere**. Change a status, retype a title, clear an
+estimate — it is already saved, or it has already rolled back and told you.
+Filters and the active tab live in the URL, the list loads through
+`useAsyncData` watching `route.query`, and the optimistic overlay retires in
+that fetch's `transform`; every mutation ends in `refresh()`. Anatomy,
+components, the context shape, copy and data are identical to the Vue
+recipe; only the data/URL/mutation layer changes.
+
+Domain: **Sprint 24** of a product team — fourteen issues (`BB-227` …
+`BB-241`), four statuses, three priorities, a six-member team (Sofia Reyes,
+Jonah Weiss, Priya Natarajan, Tom Okafor, Elif Demir, Marco Bianchi).
+Deliberately distinct from the invoices/members/expenses of the sibling
+recipes.
+
+## 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.
+  Components: [BbTable](../../BbTable.md) ·
+  [BbSelectPopover](../../BbSelectPopover.md) (§ One popover per table row is
+  load-bearing here) · [BbBadge](../../BbBadge.md) (the `loading` /
+  `append:icon` interplay).
+
+Guides: [Inline Edit Playbook](../../guides/inline-edit-playbook.md) (who owns
+the edit — this page is the autosave answer) ·
+[Design language](../../guides/design-language.md) (§ Using color, § Badges
+label state) · [Page Shell](../../guides/page-shell.md) ·
+[Floating Bottom Panel](../../guides/floating-bottom-panel.md).
+
+Siblings: [vue](../vue/inline-edit-workspace.md) ·
+[inertia](../inertia/inline-edit-workspace.md).
+
+Platform assumptions: `<BbConfirm />` and `<BbToast />` mounted once in
+`app.vue` — never in a page; the layout chrome from the guides copied into
+`src/components/layout/`. Server routes: `GET /api/issues` (accepts
+`search`, `status[]`, `priority[]`, `assignee`, `tab`, `page`, `perPage`;
+returns `{ data, total, tabCounts }`); `GET /api/members` (`search`; the
+team directory) and `GET /api/members/:id`; plus the mutation routes
+referenced below (`PATCH /api/issues/:id`, `POST /api/issues/:id/duplicate`,
+`POST /api/issues/move-to-next-sprint`, `PATCH /api/issues/bulk`,
+`DELETE /api/issues/:id`).
+
+## Key ideas
+
+- **No Save button anywhere.** Every cell commits itself through one context
+  action, `persistField(issue, key, value)` — optimistic write, single-field
+  PATCH, refetch; failure rolls back just that field and toasts. Nothing on
+  the page is ever "changed but unsaved", so there is no dirty ring and no
+  dirty-gated button — the only transient state is _saving_, and the spinner
+  carries it.
+- **The optimistic overlay is page state, not cell state.** `pending` maps
+  `issue.id → { field: value }` on **rung 3** of the state ladder: the grid
+  cells, the peek workbench _and the fetch itself_ all read it. This is the
+  deliberate contrast with the one-shot §6.1 status cell (see
+  `records-workspace`), whose `saving` flag is a rung-1 local ref — in an
+  autosave grid the fetch must also know what is in flight, so the flag
+  cannot live inside a cell.
+- **The overlay is retired in the fetch's `transform`, never when a save
+  resolves** — and only for fields the response actually confirms. Retiring
+  on save-resolve makes the cell flash new → old → new for the whole reload,
+  because the table still holds the stale row until the refetch lands.
+- **Typed inputs commit on `@change` (blur/Enter), never `v-model`.** A
+  `v-model` autosave is one request per keystroke. Pickers commit on pick —
+  the click already _is_ the commit.
+- **One coopting page context.** `provideBacklogWorkspace()` joins the
+  page-shell stack and the table context once, owns filters/tab/overlay, and
+  exposes complete actions. Eleven components share everything through one
+  `useBacklogWorkspace()` call — zero prop drilling.
+- **Filters and tab live in the URL, not in local-only refs.** They are
+  seeded from `route.query` at setup and every change mirrors back through
+  `navigateTo` (debounced for free text); `useAsyncData('issues', …)`
+  watching `route.query` is the single refetch trigger, and its own
+  `refresh()` is the one imperative reload every mutation calls. The page is
+  bookmarkable mid-triage and survives reload.
+- **Options resolve once, at page level.** Status and priority are static
+  module-level catalogs (fifty rows, zero requests); the assignee picker
+  shares **one** query provider across every row, so unopened rows cost
+  nothing.
+- **Status is color, per the soft palette.** The registered `soft-*` badge
+  variants label the closed status/priority sets; the internal trailing
+  chevron says "clickable", and the badge's `loading` swaps the spinner into
+  the chevron's place while that one field saves.
+- **Buttons are `md` by default**; `sm` appears only in row actions, the
+  filter pills, the peek footer and the bulk bar. Internal navigation
+  (`New issue`, the peek's `Open full page`) uses `to`, Nuxt's Vue Router
+  prop, instead of a raw `href`.
+
+## Page anatomy
+
+```
+BacklogWorkspace/
+	Index.vue               ← assembly: PageShell slots, table, tabs, pagination
+	context.ts              ← coopts shell + table ctx; owns URL-synced filters + the pending overlay + persistField
+	FilterRail.vue          ← status / priority / assignee filter pills + clear-all
+	EditableTitleCell.vue   ← commit-on-blur text (@change, never v-model)
+	EstimateCell.vue        ← commit-on-change number cell
+	StatusCell.vue          ← editable soft badge (chevron at rest, spinner in flight)
+	PriorityCell.vue        ← same grammar, its own leaf (§6.3: never one EditableCell with a type prop)
+	AssigneeCell.vue        ← provider-backed people picker badge (ONE shared query fn)
+	RowActions.vue          ← … dropdown: duplicate, move to next sprint, delete (confirm)
+	SelectionBar.vue        ← bulk status / bulk assign / bulk move (floating bottom panel)
+	IssuePeek.vue           ← peek workbench reusing the SAME Status/Priority/Assignee cells
+```
+
+Chrome assumed from the guides: `AppLayout` (left nav + fat footer),
+`PageShell`, `FloatingBottomPanel`. Note what is _missing_ compared to the
+records workspace: there is no dialog component and the shell's `#dialogs`
+slot stays empty — on an autosave page the grid _is_ the form, so nothing
+needs a modal to edit.
+
+## Action inventory
+
+| #   | Action                   | Trigger                            | Mechanism                                            |
+| --- | ------------------------ | ---------------------------------- | ---------------------------------------------------- |
+| 1   | New issue                | topbar, the page's one `primary`   | navigation (`to="/issues/new"`)                      |
+| 2   | Page search              | topbar right                       | `filters.search` → URL → `useAsyncData` refetch      |
+| 3   | Switch sprint tab        | href tabs with live counts         | URL + `useAsyncData` refetch                         |
+| 4   | Filter by status         | rail pill                          | `BbSelectPopover` multiple over the static catalog   |
+| 5   | Filter by priority       | rail pill                          | `BbSelectPopover` multiple over the static catalog   |
+| 6   | Filter by assignee       | rail pill                          | the shared people provider, single select            |
+| 7   | Clear filters            | rail right (only when active)      | context `clearFilters()`                             |
+| 8   | Rename issue             | title cell (grid)                  | commit-on-blur `@change` → `persistField('title')`   |
+| 9   | Re-estimate              | estimate cell (grid)               | commit-on-change number → `persistField('estimate')` |
+| 10  | Change status            | status badge (grid **and** peek)   | pick = commit; spinner in the chevron (§6.8)         |
+| 11  | Change priority          | priority badge (grid **and** peek) | same grammar, its own leaf                           |
+| 12  | Reassign                 | assignee badge (grid **and** peek) | async people search; one shared provider             |
+| 13  | Peek issue               | issue ref cell                     | `peekIssue(id)` → shell stack                        |
+| 14  | Duplicate                | row `…` dropdown                   | context action + toast                               |
+| 15  | Move to next sprint      | row `…` **and** bulk bar           | `moveToNextSprint` / `bulkMoveToNextSprint`          |
+| 16  | Delete                   | row `…`, peek footer               | destructive behind `useConfirm`                      |
+| 17  | Bulk set status          | bottom panel picker                | `bulkStatus` on `table.selected`                     |
+| 18  | Bulk assign              | bottom panel picker                | `bulkAssign` on `table.selected`                     |
+| 19  | Select rows / select all | table checkboxes                   | table context                                        |
+| 20  | Open full issue          | peek footer                        | navigation (`to="/issues/:id"`)                      |
+| 21  | Close peek               | shell chrome                       | shell stack close                                    |
+
+Rows 8–12 are the recipe's reason to exist: five editable fields of three
+different control kinds, each persisting itself, two of them able to be in
+flight **on the same row at the same time**.
+
+## The code
+
+### Project setup — the soft status palette
+
+Status and priority are small closed sets — the textbook case for the soft
+semantic accents. The names are registered in the Nuxt module (that makes
+them type-check as `BbBadge` variants); the CSS is the project's own,
+kept in a stylesheet separate from the library defaults:
+
+```ts
+// nuxt.config.ts — the names; the library ships no CSS for them.
+export default defineNuxtConfig({
+	modules: ['bitboss-ui/nuxt'],
+	css: ['~/assets/css/badge-variants.css'],
+	bitboss: {
+		iconDir: './assets/icons',
+		badgeVariants: [
+			'soft-gray',
+			'soft-blue',
+			'soft-green',
+			'soft-amber',
+			'soft-red',
+		],
+	},
+});
+```
+
+```css
+/* assets/css/badge-variants.css — trimmed. Canonical palette + the full
+   recipe (why the selectors are doubled, why the hue lives in a local
+   --accent): design-language.md § Using color. */
+.bb-badge.bb-badge--soft-gray {
+	--accent: #64748b;
+}
+.bb-badge.bb-badge--soft-blue {
+	--accent: #2563eb;
+}
+.bb-badge.bb-badge--soft-green {
+	--accent: #16a34a;
+}
+.bb-badge.bb-badge--soft-amber {
+	--accent: #d97706;
+}
+.bb-badge.bb-badge--soft-red {
+	--accent: #dc2626;
+}
+
+.bb-badge.bb-badge--soft-gray,
+.bb-badge.bb-badge--soft-blue,
+.bb-badge.bb-badge--soft-green,
+.bb-badge.bb-badge--soft-amber,
+.bb-badge.bb-badge--soft-red {
+	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
+	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
+	--border-width: 1px;
+	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
+	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
+}
+```
+
+### context.ts
+
+```ts
+// BacklogWorkspace/context.ts
+import {
+	computed,
+	inject,
+	provide,
+	reactive,
+	ref,
+	watch,
+	type ComputedRef,
+	type InjectionKey,
+	type Ref,
+} from 'vue';
+import {
+	useBbTableContext,
+	useConfirm,
+	useToast,
+	type BadgeVariantType,
+	type BbTableContext,
+} from 'bitboss-ui';
+import {
+	usePageShellContext,
+	type PageShellContext,
+} from '@/components/layout/usePageShellContext';
+import { watchDebounced } from '@vueuse/core';
+import type { Issue, IssuePriority, IssueStatus, Member } from '@/types';
+
+/** What the peek sidebar can show. Clicking an issue ref pushes one of these. */
+export type PeekItem = { type: 'issue'; id: string };
+
+export type SprintTab = 'backlog' | 'current' | 'done';
+
+/**
+ * Exactly what a save can carry: the subset of Issue the user edits inline.
+ * Five fields of three control kinds on purpose — the pattern only proves
+ * itself once a row can be PARTIALLY in flight (title saving while the same
+ * row's status saves), once a field is backed by a search (assignee), and
+ * once a field changes on every keystroke (title, estimate).
+ */
+export type IssuePatch = Partial<
+	Pick<Issue, 'title' | 'estimate' | 'status' | 'priority' | 'assignee'>
+>;
+export type EditableKey = keyof IssuePatch;
+
+export interface BacklogFilters {
+	search: string;
+	status: IssueStatus[];
+	priority: IssuePriority[];
+	/** The whole member, not an id — the pill labels itself with zero fetches. */
+	assignee: Member | null;
+}
+
+type IssueListResponse = {
+	data: Issue[];
+	total: number;
+	tabCounts: Record<SprintTab, number>;
+};
+
+// -- Option catalogs: resolved once, at module level, for the whole page. ----
+// Static arrays cost fifty rows zero requests; a per-row provider would cost
+// one request per opened row (BbSelectPopover § One popover per table row).
+export const STATUS_OPTIONS: { value: IssueStatus; label: string }[] = [
+	{ value: 'open', label: 'Open' },
+	{ value: 'in-progress', label: 'In progress' },
+	{ value: 'blocked', label: 'Blocked' },
+	{ value: 'done', label: 'Done' },
+];
+export const PRIORITY_OPTIONS: { value: IssuePriority; label: string }[] = [
+	{ value: 'high', label: 'High' },
+	{ value: 'normal', label: 'Normal' },
+	{ value: 'low', label: 'Low' },
+];
+
+// Status/priority are small closed sets — the textbook case for the soft
+// accents (design-language.md § Using color). Registered in nuxt.config.ts.
+export const STATUS_VARIANT: Record<IssueStatus, BadgeVariantType> = {
+	open: 'soft-gray',
+	'in-progress': 'soft-blue',
+	blocked: 'soft-red',
+	done: 'soft-green',
+};
+export const PRIORITY_VARIANT: Record<IssuePriority, BadgeVariantType> = {
+	high: 'soft-amber',
+	normal: 'secondary',
+	low: 'outline',
+};
+
+/**
+ * `id: null` is the real "Unassigned" option, not an absence. The assignee is
+ * stored on the row as the whole member, so a row's badge always labels
+ * itself from its own data — no client-side directory cache, and the trigger
+ * never depends on the picker having loaded.
+ */
+export const UNASSIGNED: Member = { id: null, name: 'Unassigned' };
+
+/**
+ * ONE query provider shared by every assignee picker on the page — each
+ * row's cell, the peek's cell, the rail pill and the bulk-assign picker.
+ * Providers are lazy, so a row nobody opens costs nothing. Contract
+ * (fetch-items-playbook): component-initiated calls (`prefill === true`) and
+ * an empty query return the whole team — six people, one cheap request — so
+ * the current selection always stays resolvable; typed queries search.
+ */
+export const searchMembers = async (
+	query: string,
+	prefill: boolean
+): Promise<Member[]> => {
+	const q = query.trim();
+	const members = await $fetch<Member[]>('/api/members', {
+		query: prefill || !q ? {} : { search: q },
+	});
+	return [UNASSIGNED, ...members];
+};
+
+export interface BacklogWorkspaceContext {
+	// -- Coopted contexts ------------------------------------------------------
+	shell: PageShellContext<PeekItem>;
+	table: BbTableContext;
+	// -- Page-owned state (URL-synced) -------------------------------------------
+	filters: BacklogFilters;
+	hasActiveFilters: ComputedRef<boolean>;
+	tab: Ref<SprintTab>;
+	tabCounts: ComputedRef<Record<SprintTab, number>>;
+	// -- The autosave overlay (§6.8) --------------------------------------------
+	/**
+	 * Optimistic values per row PER FIELD, held until the server's own data
+	 * carries them. Reactive. Rung 3 on purpose: the cells, the peek and
+	 * the fetch's transform all read it. Cells never touch it directly —
+	 * they go through `valueOf` / `isSaving`.
+	 */
+	pending: Record<string, IssuePatch>;
+	/** Fields whose last save failed, keyed `${id}:${field}`. */
+	failed: Readonly<Ref<Set<string>>>;
+	/** Read-through: the overlay wins, the row is the fallback. */
+	valueOf: <K extends EditableKey>(issue: Issue, key: K) => Issue[K];
+	/** Whether THIS field of THIS row has a save in flight. */
+	isSaving: (issue: Issue, key: EditableKey) => boolean;
+	/** The one write path every cell commits through. */
+	persistField: <K extends EditableKey>(
+		issue: Issue,
+		key: K,
+		value: Issue[K]
+	) => Promise<void>;
+	// -- Data (URL-driven; the fetch's transform retires the overlay) ------------
+	issues: ComputedRef<Issue[]>;
+	issuesPending: Ref<boolean>;
+	// -- Peek ------------------------------------------------------------------
+	peekIssue: (id: string) => void;
+	// -- Actions (complete: API + refresh + toast) ------------------------------
+	clearFilters: () => void;
+	duplicateIssue: (issue: Issue) => Promise<void>;
+	moveToNextSprint: (issue: Issue) => Promise<void>;
+	deleteIssue: (issue: Issue) => Promise<void>;
+	bulkStatus: (status: IssueStatus) => Promise<void>;
+	bulkAssign: (assignee: Member) => Promise<void>;
+	bulkMoveToNextSprint: () => Promise<void>;
+}
+
+const key: InjectionKey<BacklogWorkspaceContext> = Symbol('backlog-workspace');
+
+/** Comma-joined query value → string[] (or null when absent). */
+const toArray = (value: unknown): string[] | null => {
+	if (value == null || value === '') return null;
+	return Array.isArray(value) ? value.map(String) : String(value).split(',');
+};
+
+export function provideBacklogWorkspace(): BacklogWorkspaceContext {
+	const { toast } = useToast();
+	const { confirm } = useConfirm();
+	const route = useRoute();
+
+	// -- Coopt the specific contexts: once, here, for the whole page. ----------
+	const shell = usePageShellContext<PeekItem>();
+	const table = useBbTableContext('backlog-table', { perPage: 25 });
+
+	// -- Filters + tab: seeded from the URL, the single source of truth. -------
+	const filters = reactive<BacklogFilters>({
+		search: (route.query.search as string) ?? '',
+		status: (toArray(route.query.status) ?? []) as IssueStatus[],
+		priority: (toArray(route.query.priority) ?? []) as IssuePriority[],
+		assignee: null, // resolved from the URL just below
+	});
+	const tab = ref<SprintTab>((route.query.tab as SprintTab) ?? 'current');
+
+	// The URL carries the assignee as an id (`none` = the real Unassigned
+	// option, whose id is null). Rows store the whole member, so this one-time
+	// resolution exists only so a deep link into a filtered view can label the
+	// pill — nothing else on the page ever resolves an id to a name.
+	if (route.query.assignee === 'none') {
+		filters.assignee = UNASSIGNED;
+	} else if (route.query.assignee) {
+		$fetch<Member>(`/api/members/${route.query.assignee}`).then((member) => {
+			filters.assignee = member;
+		});
+	}
+
+	const hasActiveFilters = computed(
+		() =>
+			filters.search !== '' ||
+			filters.status.length > 0 ||
+			filters.priority.length > 0 ||
+			filters.assignee !== null
+	);
+
+	const clearFilters = () => {
+		filters.search = '';
+		filters.status = [];
+		filters.priority = [];
+		filters.assignee = null;
+	};
+
+	// Every filter/tab change mirrors into the query string; `useAsyncData`
+	// below watches `route.query`, so this is the whole refetch trigger.
+	const syncQuery = () =>
+		navigateTo({
+			query: {
+				search: filters.search || undefined,
+				status: filters.status.length ? filters.status.join(',') : undefined,
+				priority: filters.priority.length
+					? filters.priority.join(',')
+					: undefined,
+				assignee:
+					filters.assignee === null
+						? undefined
+						: (filters.assignee.id ?? 'none'),
+				tab: tab.value,
+			},
+		});
+	watchDebounced(filters, syncQuery, { deep: true, debounce: 300 });
+	watch(tab, () => {
+		table.page.value = 1;
+		syncQuery();
+	});
+
+	// -- The autosave overlay -----------------------------------------------------
+	const pending = reactive<Record<string, IssuePatch>>({});
+	const failed = ref(new Set<string>());
+
+	const valueOf = <K extends EditableKey>(issue: Issue, key: K): Issue[K] => {
+		const patch = pending[issue.id];
+		// `key in patch`, not `patch[key] ?? issue[key]`: null is a legitimate
+		// committed value here (a cleared estimate), and `??` would drop that
+		// overlay and show the stale row value while the save runs.
+		return patch && key in patch ? (patch[key] as Issue[K]) : issue[key];
+	};
+
+	const isSaving = (issue: Issue, key: EditableKey): boolean => {
+		const patch = pending[issue.id];
+		return patch !== undefined && key in patch;
+	};
+
+	// -- Data ---------------------------------------------------------------------
+	// The one place the list loads. `route.query` is the single watch source —
+	// filters, tab and page changes all funnel through the URL first. The
+	// overlay owns the name `pending` on this page, so the fetch's own flag
+	// lands as `issuesPending`.
+	const {
+		data,
+		pending: issuesPending,
+		refresh,
+	} = useAsyncData<IssueListResponse>(
+		'issues',
+		() =>
+			$fetch<IssueListResponse>('/api/issues', {
+				query: {
+					search: filters.search || undefined,
+					status: filters.status,
+					priority: filters.priority,
+					assignee:
+						filters.assignee === null
+							? undefined
+							: (filters.assignee.id ?? 'none'),
+					tab: tab.value,
+					page: table.page.value,
+					perPage: table.perPage.value,
+				},
+			}),
+		{
+			watch: [() => route.query, table.page],
+			// Retire the overlay HERE — in the transform, where the fresh rows
+			// materialize — not when a save resolves, and only the fields this
+			// response actually CONFIRMS. Between a save landing and this
+			// reload arriving, the table still holds the OLD row; clearing the
+			// overlay early makes the cell revert to the stale value for the
+			// whole reload — visibly, new → old → new. A field still in flight
+			// (the response doesn't carry its value yet) is left alone.
+			transform: (response: IssueListResponse) => {
+				for (const issue of response.data) {
+					const patch = pending[issue.id];
+					if (!patch) continue;
+					for (const field of Object.keys(patch) as EditableKey[]) {
+						if (JSON.stringify(patch[field]) === JSON.stringify(issue[field])) {
+							delete patch[field]; // the server's own data carries it now
+						}
+					}
+					if (!Object.keys(patch).length) delete pending[issue.id];
+				}
+				return response;
+			},
+		}
+	);
+	const issues = computed(() => data.value?.data ?? []);
+	const tabCounts = computed(
+		() => data.value?.tabCounts ?? { backlog: 0, current: 0, done: 0 }
+	);
+	// Paging totals come back on every fetch and land in the table context.
+	watch(
+		data,
+		(response) => {
+			if (response) table.total.value = response.total;
+		},
+		{ immediate: true }
+	);
+
+	/**
+	 * The complete autosave action, one per commit, for every control kind:
+	 * no-op guard → optimistic set → single-field PATCH → refetch. On failure
+	 * it deletes JUST this field from the overlay (the cell snaps back to the
+	 * row's value — a second field of the same row still in flight is
+	 * untouched) and toasts destructive. Success does NOT toast: a page where
+	 * every blur saves would toast constantly — the spinner resolving is the
+	 * confirmation, failure is the exception worth announcing.
+	 */
+	const persistField = async <K extends EditableKey>(
+		issue: Issue,
+		key: K,
+		value: Issue[K]
+	): Promise<void> => {
+		// No-op-commit guard — against what the user SEES (the overlay when one
+		// is in flight, the row otherwise): a blur without a change, or
+		// re-picking the on-screen value, must not fire a request.
+		if (JSON.stringify(value) === JSON.stringify(valueOf(issue, key))) return;
+
+		const flag = `${issue.id}:${key}`;
+		(pending[issue.id] ??= {})[key] = value; // optimistic: the UI moves NOW
+		failed.value.delete(flag);
+		try {
+			await $fetch(`/api/issues/${issue.id}`, {
+				method: 'PATCH',
+				body: { [key]: value } as IssuePatch,
+			});
+			// Reload — but do NOT retire the overlay here. The useAsyncData
+			// transform drops it once the server's own data carries the value
+			// (see above).
+			await refresh();
+		} catch {
+			// Rollback: drop just this field.
+			const patch = pending[issue.id];
+			if (patch) {
+				delete patch[key];
+				if (!Object.keys(patch).length) delete pending[issue.id];
+			}
+			failed.value.add(flag);
+			toast({
+				title: `Couldn't save the ${key} of ${issue.ref} — reverted.`,
+				variant: 'destructive',
+			});
+		}
+	};
+
+	// -- Peek ------------------------------------------------------------------------
+	// One record type on this page, so the grammar is one verb: fresh stack.
+	const peekIssue = (id: string) => shell.push({ type: 'issue', id }, true);
+
+	// -- Discrete actions (row `…`, bulk bar) -------------------------------------
+	// These are ordinary complete actions, records-workspace style: they
+	// mutate whole rows, not single fields, so they bypass the overlay and
+	// simply `refresh()` — and being discrete (not a blur), they DO toast
+	// success.
+	const duplicateIssue = async (issue: Issue) => {
+		const copy = await $fetch<Issue>(`/api/issues/${issue.id}/duplicate`, {
+			method: 'POST',
+		});
+		await refresh();
+		toast({ title: `Duplicated as ${copy.ref}.`, variant: 'success' });
+	};
+
+	const moveToNextSprint = async (issue: Issue) => {
+		await $fetch('/api/issues/move-to-next-sprint', {
+			method: 'POST',
+			body: { ids: [issue.id] },
+		});
+		await refresh();
+		toast({ title: `${issue.ref} moved to Sprint 25.`, variant: 'success' });
+	};
+
+	const deleteIssue = async (issue: Issue) => {
+		const ok = await confirm({
+			variant: 'destructive',
+			title: 'Delete issue',
+			text: `Delete ${issue.ref} — “${issue.title}”? This cannot be undone.`,
+			yes: 'Delete',
+			no: 'Cancel',
+		});
+		if (!ok) return;
+		await $fetch(`/api/issues/${issue.id}`, { method: 'DELETE' });
+		await refresh();
+		toast({ title: `${issue.ref} deleted.`, variant: 'success' });
+	};
+
+	// Bulk actions read and clear the coopted table context themselves.
+	const bulkIds = (): string[] => table.selected.value;
+	const clearSelection = () => {
+		table.selected.value = [];
+	};
+
+	const bulkStatus = async (status: IssueStatus) => {
+		const ids = bulkIds();
+		await $fetch('/api/issues/bulk', {
+			method: 'PATCH',
+			body: { ids, patch: { status } },
+		});
+		clearSelection();
+		await refresh();
+		const label = STATUS_OPTIONS.find((o) => o.value === status)?.label;
+		toast({
+			title: `${ids.length} issues moved to ${label}.`,
+			variant: 'success',
+		});
+	};
+
+	const bulkAssign = async (assignee: Member) => {
+		const ids = bulkIds();
+		await $fetch('/api/issues/bulk', {
+			method: 'PATCH',
+			body: { ids, patch: { assignee } },
+		});
+		clearSelection();
+		await refresh();
+		toast({
+			title: `${ids.length} issues assigned to ${assignee.name}.`,
+			variant: 'success',
+		});
+	};
+
+	const bulkMoveToNextSprint = async () => {
+		const ids = bulkIds();
+		await $fetch('/api/issues/move-to-next-sprint', {
+			method: 'POST',
+			body: { ids },
+		});
+		clearSelection();
+		await refresh();
+		toast({
+			title: `${ids.length} issues moved to Sprint 25.`,
+			variant: 'success',
+		});
+	};
+
+	const ctx: BacklogWorkspaceContext = {
+		shell,
+		table,
+		filters,
+		hasActiveFilters,
+		tab,
+		tabCounts,
+		pending,
+		failed,
+		valueOf,
+		isSaving,
+		persistField,
+		issues,
+		issuesPending,
+		peekIssue,
+		clearFilters,
+		duplicateIssue,
+		moveToNextSprint,
+		deleteIssue,
+		bulkStatus,
+		bulkAssign,
+		bulkMoveToNextSprint,
+	};
+	provide(key, ctx);
+	return ctx;
+}
+
+export function useBacklogWorkspace(): BacklogWorkspaceContext {
+	const ctx = inject(key);
+	if (!ctx)
+		throw new Error('useBacklogWorkspace() called outside BacklogWorkspace');
+	return ctx;
+}
+```
+
+### Index.vue — the assembly
+
+```vue
+<!-- BacklogWorkspace/Index.vue -->
+<template>
+	<PageShell>
+		<!-- Topbar: breadcrumbs left, page search + primary action 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: 'product', text: 'Product', to: '/product' },
+						{ key: 'sprints', text: 'Sprints', to: '/sprints' },
+						{ key: 'sprint-24', text: 'Sprint 24' },
+					]"
+				/>
+				<div class="flex shrink-0 items-center gap-2">
+					<!-- `label` is required across the input family; `hide-label`
+					     keeps the accessible name while hiding it visually. -->
+					<BbTextInput
+						v-model="ctx.filters.search"
+						autocomplete="off"
+						clearable
+						compact
+						hide-label
+						label="Search issues"
+						placeholder="Search ref or title…"
+						prepend:icon="lucide:search"
+					/>
+					<BbButton
+						prepend:icon="lucide:plus"
+						to="/issues/new"
+						variant="primary"
+					>
+						New issue
+					</BbButton>
+				</div>
+			</div>
+		</template>
+
+		<div class="flex flex-col gap-3 p-4">
+			<FilterRail />
+
+			<!-- Tabs as URL filters: href updates the query, the key feeds the
+			     fetch. Counts come back from the server on every fetch. -->
+			<BbTabs
+				v-model="ctx.tab.value"
+				compact
+				:items="[
+					{
+						key: 'backlog',
+						label: `Backlog · ${ctx.tabCounts.value.backlog}`,
+						href: '?tab=backlog',
+					},
+					{
+						key: 'current',
+						label: `Current sprint · ${ctx.tabCounts.value.current}`,
+						href: '?tab=current',
+					},
+					{
+						key: 'done',
+						label: `Done · ${ctx.tabCounts.value.done}`,
+						href: '?tab=done',
+					},
+				]"
+			/>
+
+			<BbTable
+				id="backlog-table"
+				v-model:highlighted="highlightedIssue"
+				actions
+				caption="Sprint 24 backlog"
+				:columns="columns"
+				compact
+				item-value="id"
+				:items="ctx.issues.value"
+				legend="Sprint 24 backlog issues"
+				:loading="ctx.issuesPending.value"
+				loading-text="Loading issues…"
+				:row-class="rowClass"
+				selectable
+			>
+				<!-- The ref is the peek handle — the title can't be, it's an input.
+				     `.plain-link` is the project-owned inline-link helper
+				     (design-language.md § Guide helper), not a BbButton variant. -->
+				<template #ref="{ item, content }">
+					<BbBaseButton
+						class="plain-link font-semibold"
+						@click="() => ctx.peekIssue(item.id)"
+					>
+						{{ content }}
+					</BbBaseButton>
+				</template>
+
+				<!-- Five self-persisting cells, three control kinds, one leaf each. -->
+				<template #title="{ item }">
+					<EditableTitleCell :issue="item" />
+				</template>
+
+				<template #estimate="{ item }">
+					<EstimateCell :issue="item" />
+				</template>
+
+				<template #status="{ item }">
+					<StatusCell :issue="item" />
+				</template>
+
+				<template #priority="{ item }">
+					<PriorityCell :issue="item" />
+				</template>
+
+				<template #assignee="{ item }">
+					<AssigneeCell :issue="item" />
+				</template>
+
+				<template #actions="{ item }">
+					<RowActions :issue="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 issues 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>
+
+			<!-- Joins the table context by id: no page/totalPages wiring at all. -->
+			<BbPagination table-id="backlog-table" />
+		</div>
+
+		<SelectionBar />
+
+		<!-- Peek sidebar: the shell owns close; we render by type. -->
+		<template #sidebar>
+			<IssuePeek
+				v-if="ctx.shell.current.value?.type === 'issue'"
+				:issue-id="ctx.shell.current.value.id"
+			/>
+		</template>
+
+		<!-- Deliberately no #dialogs content: every mutation on this page is
+		     inline. The grid is the form. -->
+	</PageShell>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import {
+	BbBaseButton,
+	BbBreadcrumbs,
+	BbButton,
+	BbPagination,
+	BbTable,
+	BbTabs,
+	BbTextInput,
+} from 'bitboss-ui';
+import PageShell from '@/components/layout/PageShell.vue';
+import { provideBacklogWorkspace } from './context';
+import AssigneeCell from './AssigneeCell.vue';
+import EditableTitleCell from './EditableTitleCell.vue';
+import EstimateCell from './EstimateCell.vue';
+import FilterRail from './FilterRail.vue';
+import IssuePeek from './IssuePeek.vue';
+import PriorityCell from './PriorityCell.vue';
+import RowActions from './RowActions.vue';
+import SelectionBar from './SelectionBar.vue';
+import StatusCell from './StatusCell.vue';
+import type { Issue } from '@/types';
+
+const ctx = provideBacklogWorkspace();
+
+// Row highlight tracks the open peek — the peeked row stays marked, and
+// highlighting a row opens its peek; clearing the highlight closes it.
+const highlightedIssue = computed<string | null>({
+	get: () =>
+		ctx.shell.current.value?.type === 'issue'
+			? ctx.shell.current.value.id
+			: null,
+	set: (id) => {
+		if (id == null) ctx.shell.close();
+		else ctx.peekIssue(id);
+	},
+});
+
+const columns = [
+	{ key: 'ref', label: 'Ref', width: 90 },
+	{ key: 'title', label: 'Title' },
+	{ key: 'estimate', label: 'Est.', width: 90 },
+	{ key: 'status', label: 'Status', width: 170 },
+	{ key: 'priority', label: 'Priority', width: 140 },
+	{ key: 'assignee', label: 'Assignee', width: 200 },
+];
+
+// Blocked rows get a tinted background — public row-class API, no internals.
+// Even the tint reads THROUGH the overlay: unblock an issue and the row
+// clears the moment the pick commits, not when the refetch lands.
+const rowClass = (item: Issue) =>
+	ctx.valueOf(item, 'status') === 'blocked'
+		? 'bg-red-50 dark:bg-red-950/20'
+		: undefined;
+</script>
+```
+
+### FilterRail.vue
+
+```vue
+<!-- BacklogWorkspace/FilterRail.vue -->
+<template>
+	<div class="flex flex-wrap items-center gap-2">
+		<!-- Status: multi-select pill over the same static catalog the cells use.
+		     `disable-writing` means there's no search field to host an in-popover
+		     clear, so these tiny fixed-list filters clear from a rail-level chip
+		     (×) instead — the searchable filter below clears from inside the
+		     popover. -->
+		<div class="inline-flex items-center gap-1">
+			<BbSelectPopover
+				v-model="ctx.filters.status"
+				disable-writing
+				item-text="label"
+				item-value="value"
+				:items="STATUS_OPTIONS"
+				multiple
+			>
+				<template #activator="{ props }">
+					<BbButton
+						v-bind="props"
+						append:icon="lucide:chevron-down"
+						size="sm"
+						variant="outline"
+					>
+						Status{{
+							ctx.filters.status.length ? ` · ${ctx.filters.status.length}` : ''
+						}}
+					</BbButton>
+				</template>
+			</BbSelectPopover>
+			<BbButton
+				v-if="ctx.filters.status.length"
+				aria-label="Clear status filter"
+				prepend:icon="lucide:x"
+				size="sm"
+				variant="ghost"
+				@click="ctx.filters.status = []"
+			/>
+		</div>
+
+		<!-- Priority: same shape, three options. -->
+		<div class="inline-flex items-center gap-1">
+			<BbSelectPopover
+				v-model="ctx.filters.priority"
+				disable-writing
+				item-text="label"
+				item-value="value"
+				:items="PRIORITY_OPTIONS"
+				multiple
+			>
+				<template #activator="{ props }">
+					<BbButton
+						v-bind="props"
+						append:icon="lucide:chevron-down"
+						size="sm"
+						variant="outline"
+					>
+						Priority{{
+							ctx.filters.priority.length
+								? ` · ${ctx.filters.priority.length}`
+								: ''
+						}}
+					</BbButton>
+				</template>
+			</BbSelectPopover>
+			<BbButton
+				v-if="ctx.filters.priority.length"
+				aria-label="Clear priority filter"
+				prepend:icon="lucide:x"
+				size="sm"
+				variant="ghost"
+				@click="ctx.filters.priority = []"
+			/>
+		</div>
+
+		<!-- Assignee: the SAME shared provider as every assignee cell. The whole
+		     member is the value, so the pill labels itself from page state with
+		     zero fetches — no watchEffect-to-resolve-a-name here. Query-aware
+		     (searchable), so the filter clears from inside the popover search. -->
+		<BbSelectPopover
+			v-model="ctx.filters.assignee"
+			clearable
+			item-text="name"
+			:items="searchMembers"
+		>
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					append:icon="lucide:chevron-down"
+					size="sm"
+					variant="outline"
+				>
+					{{ ctx.filters.assignee?.name ?? 'Assignee' }}
+				</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 { BbButton, BbSelectPopover } from 'bitboss-ui';
+import {
+	PRIORITY_OPTIONS,
+	STATUS_OPTIONS,
+	searchMembers,
+	useBacklogWorkspace,
+} from './context';
+
+const ctx = useBacklogWorkspace();
+</script>
+```
+
+### EditableTitleCell.vue
+
+```vue
+<!-- BacklogWorkspace/EditableTitleCell.vue -->
+<template>
+	<!-- Commit on @change (blur/Enter), NEVER v-model: a v-model autosave is
+	one request per keystroke. `:model-value` binds the read-through value
+	down; the user's in-progress typing lives in the DOM until blur commits
+	it. A failed save marks the field until the next commit attempt. -->
+	<BbTextInput
+		compact
+		:has-errors="ctx.failed.value.has(`${issue.id}:title`)"
+		hide-label
+		label="Issue title"
+		:loading="ctx.isSaving(issue, 'title')"
+		:model-value="ctx.valueOf(issue, 'title')"
+		@change="commit"
+	/>
+</template>
+
+<script setup lang="ts">
+import { BbTextInput } from 'bitboss-ui';
+import { useBacklogWorkspace } from './context';
+import type { Issue } from '@/types';
+
+const props = defineProps<{ issue: Issue }>();
+
+const ctx = useBacklogWorkspace();
+
+// `@change` is the native event; the committed text is on the target.
+const commit = (event: Event) =>
+	ctx.persistField(
+		props.issue,
+		'title',
+		(event.target as HTMLInputElement).value
+	);
+</script>
+```
+
+### EstimateCell.vue
+
+```vue
+<!-- BacklogWorkspace/EstimateCell.vue -->
+<template>
+	<BbNumberInput
+		compact
+		:has-errors="ctx.failed.value.has(`${issue.id}:estimate`)"
+		hide-label
+		label="Estimate"
+		:loading="ctx.isSaving(issue, 'estimate')"
+		:min="0"
+		:model-value="ctx.valueOf(issue, 'estimate')"
+		placeholder="—"
+		@change="commit"
+	/>
+</template>
+
+<script setup lang="ts">
+import { BbNumberInput } from 'bitboss-ui';
+import { useBacklogWorkspace } from './context';
+import type { Issue } from '@/types';
+
+const props = defineProps<{ issue: Issue }>();
+
+const ctx = useBacklogWorkspace();
+
+// A number input's `change` carries the RAW STRING; '' means cleared. A
+// cleared estimate is a real commit (estimate: null), not a no-op — which is
+// exactly why the context's valueOf checks `key in patch` instead of `??`.
+const commit = (event: Event) => {
+	const raw = (event.target as HTMLInputElement).value;
+	ctx.persistField(props.issue, 'estimate', raw === '' ? null : Number(raw));
+};
+</script>
+```
+
+### StatusCell.vue
+
+```vue
+<!-- BacklogWorkspace/StatusCell.vue -->
+<template>
+	<BbSelectPopover
+		compact
+		disable-writing
+		item-text="label"
+		item-value="value"
+		:items="STATUS_OPTIONS"
+		:model-value="status"
+		width="180px"
+		@update:model-value="
+			(next) => ctx.persistField(issue, 'status', next as IssueStatus)
+		"
+	>
+		<template #activator="{ props: activatorProps, shown }">
+			<!-- The badge IS the trigger: BbBadgeButton turns the badge's own
+			body into the button, so the pill is the hit target and draws its own
+			focus ring — no wrapper element, no chrome class. The internal
+			trailing chevron says "this can change" and sits inside the button
+			with the label; while THIS field's save runs the badge's `loading`
+			swaps the spinner into the chevron's place — same size, nothing
+			shifts. Unlike the one-shot §6.1 cell there is no local `saving` ref:
+			the flag comes from the context overlay, because in an autosave grid
+			the fetch must also know what's in flight. -->
+			<BbBadge
+				append:icon="lucide:chevron-down"
+				:class="{ 'status-cell--open': shown }"
+				:loading="ctx.isSaving(issue, 'status')"
+				:variant="STATUS_VARIANT[status]"
+			>
+				<BbBadgeButton v-bind="activatorProps">{{ label }}</BbBadgeButton>
+			</BbBadge>
+		</template>
+	</BbSelectPopover>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
+import { STATUS_OPTIONS, STATUS_VARIANT, useBacklogWorkspace } from './context';
+import type { Issue, IssueStatus } from '@/types';
+
+const props = defineProps<{ issue: Issue }>();
+
+const ctx = useBacklogWorkspace();
+
+// Read through the overlay, so the badge moves the instant a pick commits —
+// color and label both.
+const status = computed(() => ctx.valueOf(props.issue, 'status'));
+const label = computed(
+	() =>
+		STATUS_OPTIONS.find((option) => option.value === status.value)?.label ??
+		status.value
+);
+</script>
+
+<style scoped>
+/* Open = the badge's own hue, deepened, plus its variant ring — derived from
+   the badge's --color/--ring tokens so every status keeps its identity
+   instead of washing out to a neutral. */
+.status-cell--open {
+	--bg: color-mix(in oklab, var(--color) 24%, var(--bb-panel));
+	--border-color: color-mix(in oklab, var(--color) 45%, var(--bb-panel));
+	box-shadow: 0 0 0 var(--bb-ring-size) var(--ring);
+}
+</style>
+```
+
+### PriorityCell.vue
+
+```vue
+<!-- BacklogWorkspace/PriorityCell.vue -->
+<template>
+	<!-- Same grammar as StatusCell, its OWN leaf (§6.3): one `EditableCell`
+	with a `type` prop growing a renderer switch is the API-monster seed. The
+	sixty percent that repeats is cheaper than the prop that accumulates. -->
+	<BbSelectPopover
+		compact
+		disable-writing
+		item-text="label"
+		item-value="value"
+		:items="PRIORITY_OPTIONS"
+		:model-value="priority"
+		width="160px"
+		@update:model-value="
+			(next) => ctx.persistField(issue, 'priority', next as IssuePriority)
+		"
+	>
+		<template #activator="{ props: activatorProps, shown }">
+			<BbBadge
+				append:icon="lucide:chevron-down"
+				:class="{ 'priority-cell--open': shown }"
+				:loading="ctx.isSaving(issue, 'priority')"
+				:variant="PRIORITY_VARIANT[priority]"
+			>
+				<BbBadgeButton v-bind="activatorProps">{{ label }}</BbBadgeButton>
+			</BbBadge>
+		</template>
+	</BbSelectPopover>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
+import {
+	PRIORITY_OPTIONS,
+	PRIORITY_VARIANT,
+	useBacklogWorkspace,
+} from './context';
+import type { Issue, IssuePriority } from '@/types';
+
+const props = defineProps<{ issue: Issue }>();
+
+const ctx = useBacklogWorkspace();
+
+const priority = computed(() => ctx.valueOf(props.issue, 'priority'));
+const label = computed(
+	() =>
+		PRIORITY_OPTIONS.find((option) => option.value === priority.value)?.label ??
+		priority.value
+);
+</script>
+
+<style scoped>
+/* Open = the badge's own hue, deepened, plus its variant ring (see
+   StatusCell). */
+.priority-cell--open {
+	--bg: color-mix(in oklab, var(--color) 24%, var(--bb-panel));
+	--border-color: color-mix(in oklab, var(--color) 45%, var(--bb-panel));
+	box-shadow: 0 0 0 var(--bb-ring-size) var(--ring);
+}
+</style>
+```
+
+### AssigneeCell.vue
+
+```vue
+<!-- BacklogWorkspace/AssigneeCell.vue -->
+<template>
+	<!-- Provider-backed people picker. The provider is the ONE shared
+	`searchMembers` — lazy per instance, so a row nobody opens never fetches.
+	The whole member is the value (no item-value), matching how the row
+	stores it. -->
+	<BbSelectPopover
+		compact
+		item-text="name"
+		:items="searchMembers"
+		:model-value="assignee"
+		width="220px"
+		@update:model-value="
+			(next) => ctx.persistField(issue, 'assignee', next as Member)
+		"
+	>
+		<template #activator="{ props: activatorProps, shown }">
+			<!-- Labelled from the ROW (through the overlay), never from the
+			popover's `text`: a lazy provider has no items until first open, so
+			`text` is empty — and the rows nobody opens must still read right on
+			first paint. An assignee is a person, not a semantic status, so the
+			badge stays neutral (`secondary`), no soft accent. -->
+			<BbBadge
+				append:icon="lucide:chevron-down"
+				:class="{ 'assignee-cell--open': shown }"
+				:loading="ctx.isSaving(issue, 'assignee')"
+				variant="secondary"
+			>
+				<BbBadgeButton v-bind="activatorProps">{{
+					assignee.name
+				}}</BbBadgeButton>
+			</BbBadge>
+		</template>
+	</BbSelectPopover>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
+import { searchMembers, useBacklogWorkspace } from './context';
+import type { Issue, Member } from '@/types';
+
+const props = defineProps<{ issue: Issue }>();
+
+const ctx = useBacklogWorkspace();
+
+const assignee = computed(() => ctx.valueOf(props.issue, 'assignee'));
+</script>
+
+<style scoped>
+/* Open = the badge's own hue, deepened, plus its variant ring (see
+   StatusCell). */
+.assignee-cell--open {
+	--bg: color-mix(in oklab, var(--color) 24%, var(--bb-panel));
+	--border-color: color-mix(in oklab, var(--color) 45%, var(--bb-panel));
+	box-shadow: 0 0 0 var(--bb-ring-size) var(--ring);
+}
+</style>
+```
+
+### RowActions.vue
+
+```vue
+<!-- BacklogWorkspace/RowActions.vue -->
+<template>
+	<BbDropdown
+		:items="[
+			{
+				key: 'duplicate',
+				text: 'Duplicate',
+				'prepend:icon': 'lucide:copy',
+				onClick: () => ctx.duplicateIssue(issue),
+			},
+			{
+				key: 'next-sprint',
+				text: 'Move to next sprint',
+				'prepend:icon': 'lucide:arrow-right',
+				onClick: () => ctx.moveToNextSprint(issue),
+			},
+			{
+				key: 'delete',
+				text: 'Delete',
+				'prepend:icon': 'lucide:trash-2',
+				variant: 'destructive',
+				onClick: () => ctx.deleteIssue(issue),
+			},
+		]"
+	>
+		<template #activator="{ props }">
+			<BbButton v-bind="props" icon="lucide:ellipsis" size="sm" variant="ghost">
+				Issue actions
+			</BbButton>
+		</template>
+	</BbDropdown>
+</template>
+
+<script setup lang="ts">
+import { BbButton, BbDropdown } from 'bitboss-ui';
+import { useBacklogWorkspace } from './context';
+import type { Issue } from '@/types';
+
+defineProps<{ issue: Issue }>();
+
+const ctx = useBacklogWorkspace();
+</script>
+```
+
+### SelectionBar.vue
+
+```vue
+<!-- BacklogWorkspace/SelectionBar.vue -->
+<template>
+	<FloatingBottomPanel :open="selectedCount > 0">
+		<span class="px-2 text-sm">{{ selectedCount }} selected</span>
+
+		<!-- Bulk pickers are DISPATCHERS, not fields: model stays null, every
+		pick fires the bulk action and the popover closes. The bar holds no
+		state of its own. `placement="top"` because the bar hugs the viewport
+		bottom — open upward instead of flipping — with an 8px `offset` so the
+		menu clears the bar. -->
+		<BbSelectPopover
+			disable-writing
+			item-text="label"
+			item-value="value"
+			:items="STATUS_OPTIONS"
+			:model-value="null"
+			:offset="8"
+			placement="top"
+			width="180px"
+			@update:model-value="(next) => ctx.bulkStatus(next as IssueStatus)"
+		>
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					append:icon="lucide:chevron-up"
+					size="sm"
+					variant="ghost"
+				>
+					Set status
+				</BbButton>
+			</template>
+		</BbSelectPopover>
+
+		<BbSelectPopover
+			item-text="name"
+			:items="searchMembers"
+			:model-value="null"
+			:offset="8"
+			placement="top"
+			width="220px"
+			@update:model-value="(next) => ctx.bulkAssign(next as Member)"
+		>
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					append:icon="lucide:chevron-up"
+					size="sm"
+					variant="ghost"
+				>
+					Assign
+				</BbButton>
+			</template>
+		</BbSelectPopover>
+
+		<BbButton
+			prepend:icon="lucide:arrow-right"
+			size="sm"
+			variant="ghost"
+			@click="ctx.bulkMoveToNextSprint"
+		>
+			Next sprint
+		</BbButton>
+
+		<div class="floating-bottom-panel__right flex items-center gap-1">
+			<BbButton
+				aria-label="Clear selection"
+				icon="lucide:x"
+				size="sm"
+				variant="ghost"
+				@click="clearSelection"
+			/>
+		</div>
+	</FloatingBottomPanel>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbButton, BbSelectPopover } from 'bitboss-ui';
+import FloatingBottomPanel from '@/components/layout/FloatingBottomPanel.vue';
+import { STATUS_OPTIONS, searchMembers, useBacklogWorkspace } from './context';
+import type { IssueStatus, Member } from '@/types';
+
+const ctx = useBacklogWorkspace();
+
+const selectedCount = computed(() => ctx.table.selected.value?.length ?? 0);
+const clearSelection = () => {
+	ctx.table.selected.value = [];
+};
+</script>
+```
+
+### IssuePeek.vue
+
+```vue
+<!-- BacklogWorkspace/IssuePeek.vue -->
+<template>
+	<div v-if="issue" class="flex flex-col gap-4 text-sm">
+		<!-- Identity header. -->
+		<header class="flex flex-col gap-1">
+			<p class="text-xs font-medium text-[color:var(--bb-text-muted)]">
+				{{ issue.ref }}
+			</p>
+			<h2 class="text-base font-semibold">{{ issue.title }}</h2>
+		</header>
+
+		<!-- Properties: the SAME editable cells as the grid — one leaf, two
+		call sites. Change the status here and the grid's badge (and even the
+		blocked-row tint) moves in the same tick, because both surfaces read
+		the same overlay; the spinner shows in both places at once. -->
+		<dl class="grid grid-cols-[auto_1fr] items-center gap-x-4 gap-y-2">
+			<dt class="text-[color:var(--bb-text-muted)]">Status</dt>
+			<dd><StatusCell :issue="issue" /></dd>
+			<dt class="text-[color:var(--bb-text-muted)]">Priority</dt>
+			<dd><PriorityCell :issue="issue" /></dd>
+			<dt class="text-[color:var(--bb-text-muted)]">Assignee</dt>
+			<dd><AssigneeCell :issue="issue" /></dd>
+			<dt class="text-[color:var(--bb-text-muted)]">Estimate</dt>
+			<dd>
+				{{
+					ctx.valueOf(issue, 'estimate') === null
+						? 'Unestimated'
+						: `${ctx.valueOf(issue, 'estimate')} points`
+				}}
+			</dd>
+			<dt class="text-[color:var(--bb-text-muted)]">Sprint</dt>
+			<dd>{{ issue.sprint }}</dd>
+		</dl>
+
+		<!-- Description. -->
+		<section class="flex flex-col gap-1.5">
+			<h3
+				class="text-xs font-semibold uppercase tracking-wide text-[color:var(--bb-text-muted)]"
+			>
+				Description
+			</h3>
+			<p class="whitespace-pre-line text-[color:var(--bb-text-muted)]">
+				{{ issue.description }}
+			</p>
+		</section>
+
+		<!-- 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 issue.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: act here, or leave for the full page. -->
+		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
+			<BbButton
+				prepend:icon="lucide:arrow-right"
+				size="sm"
+				variant="secondary"
+				@click="() => ctx.moveToNextSprint(issue!)"
+			>
+				Next sprint
+			</BbButton>
+			<BbButton
+				size="sm"
+				variant="destructive"
+				@click="() => ctx.deleteIssue(issue!)"
+			>
+				Delete
+			</BbButton>
+			<BbButton
+				append:icon="lucide:arrow-up-right"
+				size="sm"
+				:to="`/issues/${issue.id}`"
+				variant="ghost"
+			>
+				Open full page
+			</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 { BbButton, BbIcon, BbSpinner } from 'bitboss-ui';
+import AssigneeCell from './AssigneeCell.vue';
+import PriorityCell from './PriorityCell.vue';
+import StatusCell from './StatusCell.vue';
+import { useBacklogWorkspace } from './context';
+import type { IssueDetail } from '@/types';
+
+const props = defineProps<{ issueId: string }>();
+
+const ctx = useBacklogWorkspace();
+
+// Re-fetches whenever the stack shows a different issue; reading `ctx.issues`
+// makes every commit (from the grid OR from this panel) — each of which ends
+// in the list's `refresh()` — reflect here immediately. The cells inside
+// don't flash across that reload either — they read the overlay, and the
+// overlay only retires when the fresh data confirms it.
+const issue = ref<IssueDetail | null>(null);
+watchEffect(async () => {
+	void ctx.issues.value;
+	issue.value = await $fetch<IssueDetail>(`/api/issues/${props.issueId}`);
+});
+
+const longDate = (value: string) =>
+	new Date(value).toLocaleDateString('en-US', {
+		month: 'short',
+		day: 'numeric',
+		year: 'numeric',
+	});
+</script>
+```
+
+## Why it is built this way
+
+- **`pending` sits on rung 3, and the recipe's whole shape follows from
+  that.** Three consumers force it up the ladder: the cells read it to render
+  optimistically, the peek reads it so the second call site of every cell
+  agrees with the first, and the `useAsyncData` transform reads it to retire
+  confirmed fields. Contrast the records workspace's §6.1 status cell, where
+  `saving` is a rung-1 local `ref` around one awaited action — correct
+  **there** because nothing but that one cell ever cares. Here the fetch must
+  know what's in flight, so a local flag physically cannot work; that is why
+  the picker cells bind `:loading="ctx.isSaving(issue, 'status')"` instead of
+  owning a `saving` ref.
+- **`persistField` is one complete action for every control kind.** Text,
+  number, and three pickers all commit through the same guard → optimistic
+  set → PATCH → refetch pipeline, so the failure story (drop one field,
+  destructive toast) and the no-op story (blur without change costs nothing)
+  are written once. The guard compares against `valueOf`, not the raw row —
+  what the user _sees_ is the value they are re-committing.
+- **Retirement lives in the fetch's `transform` because that is when the
+  truth changes.** A resolved PATCH proves the server accepted the value, not
+  that the table shows it — the rows in memory are still old until the
+  refetch lands. Retiring per-field (only values the response confirms) means
+  a slow title save survives a fast status save's reload untouched. The
+  comment on the `transform` ships with the recipe on purpose: this is the
+  §6.8 bug everyone writes once.
+- **The URL is the filter store, `useAsyncData` is the fetch.** Filters and
+  tab are seeded from `route.query` once at setup, mirrored back with
+  `navigateTo` on every change (debounced for free text), and
+  `useAsyncData('issues', …, { watch: [() => route.query, table.page] })` is
+  the single refetch trigger — there is exactly one place data loads, which
+  is also the only place the overlay retires. The assignee pill is the one
+  URL nuance: rows store the whole member, but a deep link carries only an
+  id, so the context resolves it to a member once at setup.
+- **`valueOf` checks `key in patch`, not `??`.** A cleared estimate commits
+  `null`, and `null ?? row.estimate` would silently un-render the overlay
+  while the save runs. The one-line comment in the context is load-bearing.
+- **No dirty ring anywhere, no success toasts for cell commits.** Autosave
+  has no "changed but unsaved" state, so the ring (the draft-map pattern's
+  grammar) would lie; and a page where every blur saves would toast
+  constantly. The spinner in the chevron's place is the feedback; failure is
+  the exception worth announcing (destructive toast + `has-errors` on the
+  text/number cells via the `failed` set; badge cells announce by visibly
+  snapping back). Discrete actions — duplicate, move, delete, bulk — _do_
+  toast success: they are events, not keystrokes.
+- **Five cells, five leaves.** `EditableTitleCell`, `EstimateCell`,
+  `StatusCell`, `PriorityCell`, `AssigneeCell` — never one `EditableCell`
+  with a `type` prop growing a renderer switch (§6.3/§4). Each takes exactly
+  one data prop (`issue`) and gets its behavior from the context.
+- **Typed inputs commit on `@change`; pickers commit on pick.** The text and
+  number cells bind `:model-value` down and read the committed value from the
+  native event (`event.target`); the number cell's change carries the raw
+  string where `''` means cleared. No debounce machinery — blur/Enter and
+  pick are natural commit points, so the request count equals the commit
+  count.
+- **Options resolve once.** Status and priority are module-level catalogs
+  shared by the cells, the rail pills and the bulk picker — zero requests.
+  The assignee is genuinely query-driven, so it gets the one exception: a
+  **single** shared provider (`searchMembers`), lazy per instance, keeping
+  unopened rows free; prefill calls return the whole six-person team so the
+  current selection always resolves. Rows store the whole member, so every
+  badge and the filter pill label themselves from data they already hold —
+  no `watchEffect`-to-resolve-a-name anywhere on this page; the only
+  directory lookup is the one-time deep-link resolution of `?assignee=` at
+  setup.
+- **Internal links use `to`, not `href`.** `to` renders a real Vue Router
+  link (client-side navigation); a raw `href` would force a full page reload.
+  The `New issue` primary and the peek's `Open full page` link use `to`; the
+  tabs keep `href` (`?tab=…`) because their client-side pushState is what
+  keeps `route.query.tab` in sync — the URL-filter grammar itself.
+- **The ref cell is the peek handle** because the title — the "name" of an
+  issue — is an input here, and a click that sometimes edits and sometimes
+  navigates is a broken affordance. One record type also collapses the stack
+  grammar to a single verb (`peekIssue`, fresh stack).
+- **The peek reuses the grid's cells verbatim** — one leaf, two call sites.
+  Both read the same overlay, so a status change made in the panel updates
+  the grid row (badge, tint, spinner) in the same tick, and vice versa.
+- **Sizing:** topbar follows `md`-first (`compact` inputs at 28px flush
+  beside the default buttons); `sm` appears exactly where the doctrine
+  allows — rail pills, row actions, the bulk bar, the peek footer. Cell
+  inputs are `compact`.
+- **One `variant="primary"`** (New issue). The only irreversible action
+  (delete — row menu and peek footer) rides `useConfirm`; moving between
+  sprints is reversible, so it deliberately does not.
+
+## Variations
+
+- **Keyboard triage**: add `keyboard-navigation` to the table —
+  `v-model:highlighted` already drives the peek — the approvals-inbox recipe
+  is the full treatment; the overlay needs no changes, since it never cared
+  how a commit was triggered.
+- **Review-before-save domains**: if the product wants a batch the user
+  confirms (accounting lines, permissions), swap the overlay for the
+  draft-map pattern — dirty ring, dirty-gated Save — per the
+  [Inline Edit Playbook](../../guides/inline-edit-playbook.md); the
+  record-form recipe's line-item editor assembles it. Never mix both
+  grammars on one table.
+- **Undo instead of confirm**: for softer destructive-ish moves (Done →
+  reopened), a success toast with an Undo action that PATCHes the old value
+  back is more Linear than a confirm dialog.
+- **Live board**: because refetches retire the overlay per confirmed field,
+  a polling `refresh()` call (or a websocket-triggered one) is safe — a
+  poll landing mid-save cannot destroy an in-flight edit, which is exactly
+  the property the write-back anti-pattern lacks.