bitboss-ui 2.1.135 → 3.0.0-alpha.1

package/dist/ai/recipes/inertia/ownership-atlas.md

@@ -0,0 +1,1281 @@
+---
+title: Ownership Atlas (Inertia)
+summary: Nested-table ownership atlas for Laravel + Inertia — expandable owner rows whose holdings render as a child BbTable snapped onto the parent's column tracks (inherit-column-widths + per-column snap), select-all-across-pages bulk transfer, region-visit tabs, URL-mirrored filters, expand/collapse-all, and a row-highlight owner peek, all through one page context that coopts the Inertia Helpers toolkit.
+---
+
+# Recipe: Ownership Atlas (Inertia)
+
+A resource-ownership admin page for **Laravel + Inertia** — the "who owns
+what" screen every internal console grows (Okta's people → assigned
+resources, a cloud console's cost-by-owner rollup): a dense, server-paged
+table of owners where **expanding a row reveals a nested `BbTable` of the
+holdings that owner is responsible for, column-aligned under the parent's
+own tracks**. Around that signature move sits the full standard anatomy:
+breadcrumbs + page search, a holding-type filter pill, region tabs with live
+counts, expand/collapse-all controls, selection with a floating bulk
+**Transfer holdings** action, and an owner peek sidebar opened by row
+highlight. The list is a page prop, filters mirror into the URL through
+[`useQueryObject`](../../guides/inertia-helpers.md), selection and paging
+come from the keyed [`useTableContext`](../../guides/inertia-helpers.md),
+and the one 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/ownership-atlas.md) ·
+[Nuxt](../nuxt/ownership-atlas.md).
+
+## Prerequisites
+
+- `<BbToast />` mounted once in the app layout.
+- From the [Inertia Helpers](../../guides/inertia-helpers.md) toolkit:
+  `useTableContext`, `useQueryObject`, `useResourceContext` (plus the
+  `useProp` / `useQuery` prop-and-URL helpers).
+- Controller: `Inertia::render('OwnershipAtlas', ['owners' =>
+OwnerPaginator::make(...), 'tabCounts' => [...], 'ownerOptions' => [...]])` —
+  `owners` is a standard Laravel paginator (`PaginatedResponse<Owner>`) whose
+  rows **embed their holdings** (the expand row renders instantly, no
+  per-expand fetch), `tabCounts` a plain `{ all, americas, emea, apac }` map,
+  and `ownerOptions` the flat `{ id, name, team }` catalog the transfer
+  picker offers. All three are re-sent on the partial reloads the page
+  triggers. The `kinds` filter is applied to the holdings server-side: owners
+  with no matching holding drop out, and each surviving owner's
+  `holdingsCount` / `monthlyTotal` are recomputed over the filtered set.
+  Search matches owner name, email, team **and** holding names.
+- Mutation route: `PATCH /ownership/owners/bulk/transfer` (accepts the
+  select-all-across-pages payload `{ ids, all, unselected, toOwnerId }`,
+  redirects back). A small JSON endpoint
+  (`GET /ownership/owners/:id/peek`) backs the sidebar peek so opening it is
+  not a full-page visit.
+
+## Key ideas
+
+- **One coopting page context.** `provideOwnershipAtlas()` joins the
+  page-shell stack **and** the keyed `useTableContext('owners')` once, owns
+  filters/tab/expansion, and exposes complete actions. Every leaf calls
+  `useOwnershipAtlas()` and nothing else — zero prop drilling anywhere on
+  the page.
+- **The expand row is a real nested `BbTable` that inherits the parent's
+  column tracks.** `inherit-column-widths` snaps the holdings table onto the
+  owners table's grid; because the parent is `selectable`, every child
+  column carries an explicit `snap` starting at `1` (`snap: 1…4`), so
+  Resource sits exactly under Owner and the right-aligned $/mo columns share
+  one edge. This is the recipe's signature move — the full defense is in
+  "Why it is built this way" and in the
+  [BbTable guide](../../BbTable.md) ("Nested tables that align with the
+  parent").
+- **Page-level cell-padding overrides are scoped with direct-child
+  combinators.** The full-bleed treatment (`.table-flush`) pads the outer
+  table's first/last cells via `:deep(> table > thead > tr > th:first-child)`
+  — a bare descendant selector would also hit the nested table and clobber
+  the structural offset padding it computes to stay flush with the parent
+  grid.
+- **Expansion is page state, not table-internal state.** `expanded` (owner
+  ids) lives in the context and binds through `v-model:expanded-items`, so
+  the toolbar (expand-all/collapse-all), the bulk bar (expand selected) and
+  the peek footer (expand in table) all write the same array the table
+  reads.
+- **Row highlight IS the peek.** A two-way computed maps
+  `v-model:highlighted` onto the shell stack: clicking a row opens the owner
+  peek, clicking it again (or closing the sidebar) clears the highlight —
+  highlight and selection stay independent axes.
+- **The table has no client-side fetch at all.** `owners` arrives as a page
+  prop; `useTableContext('owners')` turns it into `items` +
+  `totalItems`/`page`/`perPage` (URL-backed) + `selected`/`unselected`/`all`
+  (select-all-across-pages), and `BbTable` binds directly to that handle.
+  Filters mirror into the URL with `useQueryObject`; tabs are real visits
+  (`href` + `server: true` with component-level `navigation`).
+- **The one mutation is a promise-wrapped `router.visit`.** A tiny local
+  `visit()` helper turns Inertia's callback API into a promise so
+  `bulkTransfer` stays an `async function` — identical call site to the
+  Vue/Nuxt versions.
+- **Buttons are `md` by default**; `sm`/`xs` only in the toolbar, the table
+  rows, the peek footer and the bottom bar — the dense surfaces the
+  doctrine allows.
+
+## Page anatomy
+
+```
+OwnershipAtlas/
+	Index.vue          ← assembly: PageShell slots, toolbar, owners table, pagination
+	context.ts         ← coopting page context (shell + useTableContext + filters + expansion + actions)
+	FilterRail.vue     ← holding-type pill + clear-all
+	HoldingsTable.vue  ← the nested BbTable, snapped onto the parent's tracks
+	SelectionBar.vue   ← expand-selected + bulk transfer in the floating bottom panel
+	OwnerPeek.vue      ← sidebar workbench for the highlighted owner
+```
+
+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                 | topbar right                         | `filters.search` → `useQueryObject` partial visit         |
+| 2   | Filter holding type         | filter rail pill                     | `BbSelectPopover` multiple over the kind catalog          |
+| 3   | Clear filters               | rail (only when active), empty state | context `clearFilters()`                                  |
+| 4   | Switch region tab           | server-visit tabs with counts        | `BbTabs` `href` + `server: true` visit                    |
+| 5   | Expand / collapse one owner | holdings-count control, actions col  | `expandProps` toggle → `v-model:expanded-items`           |
+| 6   | Expand all on this page     | toolbar icon button                  | `expandAllOnPage()` over the current page's rows          |
+| 7   | Collapse all                | toolbar icon button                  | `collapseAll()`                                           |
+| 8   | Peek owner                  | click anywhere on a row              | `v-model:highlighted` ↔ shell stack, JSON fetch           |
+| 9   | Expand in table             | peek footer                          | adds the peeked owner to `expanded`                       |
+| 10  | Select rows / select all    | table checkboxes                     | `useTableContext` selection (across pages)                |
+| 11  | Expand selected             | floating bottom panel                | `expandSelected()` resolves the selection payload         |
+| 12  | Bulk transfer holdings      | bottom panel one-shot popover        | `bulkTransfer(toOwnerId)` → promise-wrapped visit + toast |
+| 13  | Clear selection / paginate  | bottom panel ×, `BbPagination`       | `table.resetSelection()` / `table.page` v-model           |
+
+## The code
+
+### context.ts
+
+```ts
+// OwnershipAtlas/context.ts
+import {
+	computed,
+	inject,
+	provide,
+	reactive,
+	ref,
+	type ComputedRef,
+	type InjectionKey,
+	type Ref,
+} from 'vue';
+import { router } from '@inertiajs/vue3';
+import type { RequestPayload } from '@inertiajs/core';
+import { useToast, type BadgeVariantType } from 'bitboss-ui';
+import {
+	usePageShellContext,
+	type PageShellContext,
+} from '@/components/layout/usePageShellContext';
+import {
+	useTableContext,
+	type TableContext,
+} from '@/composables/useTableContext';
+import { useQueryObject } from '@/composables/useQueryObject';
+import { useProp } from '@/composables/useProp';
+import { useQuery } from '@/composables/useQuery';
+import type {
+	HoldingKind,
+	HoldingStatus,
+	Owner,
+	OwnerDetail,
+	OwnerOption,
+	OwnerRegion,
+} from '@/types';
+
+export type OwnershipTab = 'all' | OwnerRegion;
+
+/** What the sidebar can show. Row highlight pushes one of these. */
+export type PeekItem = { type: 'owner'; id: string };
+
+export interface OwnershipFilters {
+	search: string;
+	kinds: HoldingKind[];
+}
+
+// Shared label/variant catalogs: defined once beside the context, imported
+// by every leaf that renders a kind, status or region.
+export const KIND_LABEL: Record<HoldingKind, string> = {
+	workspace: 'Workspace',
+	project: 'Project',
+	domain: 'Domain',
+	database: 'Database',
+	vault: 'Vault',
+	device: 'Device',
+	'seat-pool': 'Seat pool',
+	bucket: 'Bucket',
+};
+
+export const STATUS_LABEL: Record<HoldingStatus, string> = {
+	active: 'Active',
+	paused: 'Paused',
+	provisioning: 'Provisioning',
+	retired: 'Retired',
+};
+
+export const STATUS_VARIANT: Record<HoldingStatus, BadgeVariantType> = {
+	active: 'soft-green',
+	paused: 'soft-amber',
+	provisioning: 'soft-blue',
+	retired: 'soft-gray',
+};
+
+export const REGION_LABEL: Record<OwnerRegion, string> = {
+	americas: 'Americas',
+	emea: 'EMEA',
+	apac: 'APAC',
+};
+
+const RELOAD_PROPS = ['owners', 'tabCounts', 'ownerOptions'] as const;
+
+/** Comma-joined query value → typed array (or [] when absent). */
+const toArray = <T = string>(value: unknown): T[] => {
+	if (Array.isArray(value)) return value as T[];
+	if (typeof value === 'string' && value.length) return value.split(',') as T[];
+	return [];
+};
+
+export interface OwnershipAtlasContext {
+	// -- Coopted contexts ------------------------------------------------------
+	shell: PageShellContext<PeekItem>;
+	table: TableContext<Owner, string>;
+	// -- Page-owned state ------------------------------------------------------
+	filters: OwnershipFilters;
+	hasActiveFilters: ComputedRef<boolean>;
+	tab: Ref<OwnershipTab>;
+	tabCounts: ComputedRef<Record<OwnershipTab, number>>;
+	/** Transfer-target catalog — every owner, not just the current page. */
+	ownerOptions: ComputedRef<OwnerOption[]>;
+	/** Owner ids currently expanded — drives the nested holdings tables. */
+	expanded: Ref<string[]>;
+	/** Bumped after every mutation — the peek watches it to re-fetch. */
+	refreshKey: Ref<number>;
+	// -- Data ------------------------------------------------------------------
+	fetchOwner: (id: string) => Promise<OwnerDetail>;
+	// -- Actions ---------------------------------------------------------------
+	clearFilters: () => void;
+	expandAllOnPage: () => void;
+	collapseAll: () => void;
+	expandSelected: () => void;
+	peekOwner: (id: string) => void;
+	bulkTransfer: (toOwnerId: string) => Promise<void>;
+}
+
+const key: InjectionKey<OwnershipAtlasContext> = Symbol('ownership-atlas');
+
+/** Inertia's callback-based visit, wrapped as a promise — so the 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.
+	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 provideOwnershipAtlas(): OwnershipAtlasContext {
+	const { toast } = useToast();
+
+	// -- Coopt the specific contexts: once, here, for the whole page. ----------
+	const shell = usePageShellContext<PeekItem>();
+	// `Owner, string`: BbTable's `item-value="id"` resolves selection to owner
+	// ids ('own_…'), matching the Vue/Nuxt `table.selected: string[]` shape.
+	const table = useTableContext<Owner, string>('owners');
+
+	// -- Filters: seeded from the current URL, mirrored back by useQueryObject. -
+	const query = useQuery();
+	const filters = reactive<OwnershipFilters>({
+		search: (query.search as string) ?? '',
+		kinds: toArray<HoldingKind>(query.kinds),
+	});
+	useQueryObject(filters, { only: [...RELOAD_PROPS] });
+
+	const hasActiveFilters = computed(
+		() => filters.search.trim().length > 0 || filters.kinds.length > 0
+	);
+	const clearFilters = () => {
+		filters.search = '';
+		filters.kinds = [];
+	};
+
+	// 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<OwnershipTab>((query.tab as OwnershipTab) ?? 'all');
+	const tabCounts = useProp<Record<OwnershipTab, number>>('tabCounts');
+	const ownerOptions = useProp<OwnerOption[]>('ownerOptions');
+
+	// -- Expansion: page state, one array, many writers. -----------------------
+	// The toolbar, the bulk bar and the peek all mutate this; the table binds
+	// it via `v-model:expanded-items`. Deliberately NOT in the URL: which rows
+	// are unfolded is working posture, not a shareable view.
+	const expanded = ref<string[]>([]);
+
+	const expandAllOnPage = () => {
+		expanded.value = table.items.value.map((owner) => owner.id);
+	};
+
+	const collapseAll = () => {
+		expanded.value = [];
+	};
+
+	// Bulk expand honors select-all-across-pages semantics, but can only unfold
+	// rows that are actually rendered — so it resolves against the current page.
+	const expandSelected = () => {
+		const ids = table.all.value
+			? table.items.value
+					.map((owner) => owner.id)
+					.filter((id) => !table.unselected.value.includes(id))
+			: [...table.selected.value];
+		expanded.value = [...new Set([...expanded.value, ...ids])];
+	};
+
+	const peekOwner = (id: string) => shell.push({ type: 'owner', id }, true);
+
+	const refreshKey = ref(0);
+
+	// Bulk payload carries the full select-all-across-pages triple — 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 bulkTransfer = async (toOwnerId: string) => {
+		const target = ownerOptions.value.find((owner) => owner.id === toOwnerId);
+		await visit('patch', '/ownership/owners/bulk/transfer', {
+			...bulkPayload(),
+			toOwnerId,
+		});
+		refreshKey.value++;
+		table.resetSelection();
+		toast({
+			title: `Holdings transferred to ${target?.name ?? 'the selected owner'}.`,
+			variant: 'success',
+		});
+	};
+
+	// A small JSON endpoint, not a page visit — opening the peek never
+	// re-renders the list underneath it.
+	const fetchOwner = (id: string): Promise<OwnerDetail> =>
+		fetch(`/ownership/owners/${id}/peek`).then((res) => res.json());
+
+	const ctx: OwnershipAtlasContext = {
+		shell,
+		table,
+		filters,
+		hasActiveFilters,
+		tab,
+		tabCounts,
+		ownerOptions,
+		expanded,
+		refreshKey,
+		fetchOwner,
+		clearFilters,
+		expandAllOnPage,
+		collapseAll,
+		expandSelected,
+		peekOwner,
+		bulkTransfer,
+	};
+	provide(key, ctx);
+	return ctx;
+}
+
+export function useOwnershipAtlas(): OwnershipAtlasContext {
+	const ctx = inject(key);
+	if (!ctx)
+		throw new Error('useOwnershipAtlas() called outside OwnershipAtlas');
+	return ctx;
+}
+```
+
+### Index.vue — the assembly
+
+```vue
+<!-- OwnershipAtlas/Index.vue -->
+<template>
+	<PageShell>
+		<!-- Topbar: breadcrumbs left, page search right. No creation action on
+		     this page, so no primary button anywhere. -->
+		<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: 'admin', text: 'Admin', href: '/admin' },
+						{ key: 'access', text: 'Access', href: '/access' },
+						{ key: 'ownership', text: 'Ownership' },
+					]"
+				/>
+				<BbTextInput
+					v-model="ctx.filters.search"
+					class="shrink-0"
+					clearable
+					compact
+					hide-label
+					label="Search owners or holdings"
+					placeholder="Search owner, team, or resource…"
+					prepend:icon="lucide:search"
+				/>
+			</div>
+		</template>
+
+		<div class="flex flex-col gap-3 p-4">
+			<FilterRail />
+
+			<!-- Toolbar row: region tabs share the line with the expansion
+			     controls — expansion is page furniture, not a row concern. -->
+			<div class="flex items-center gap-2">
+				<div class="min-w-0 flex-1 overflow-clip">
+					<!-- Tabs are real visits: href + server (component-level
+					     `navigation` is required alongside per-item `server`). The
+					     transfer catalog can't change with the tab, so `ownerOptions`
+					     stays out of the tab reload list. -->
+					<BbTabs
+						v-model="ctx.tab.value"
+						compact
+						:items="[
+							{
+								key: 'all',
+								label: `All · ${ctx.tabCounts.value.all}`,
+								href: '/ownership?tab=all',
+								server: true,
+								only: ['owners', 'tabCounts'],
+							},
+							{
+								key: 'americas',
+								label: `Americas · ${ctx.tabCounts.value.americas}`,
+								href: '/ownership?tab=americas',
+								server: true,
+								only: ['owners', 'tabCounts'],
+							},
+							{
+								key: 'emea',
+								label: `EMEA · ${ctx.tabCounts.value.emea}`,
+								href: '/ownership?tab=emea',
+								server: true,
+								only: ['owners', 'tabCounts'],
+							},
+							{
+								key: 'apac',
+								label: `APAC · ${ctx.tabCounts.value.apac}`,
+								href: '/ownership?tab=apac',
+								server: true,
+								only: ['owners', 'tabCounts'],
+							},
+						]"
+						navigation
+						preserve-scroll
+						preserve-state
+						replace
+					/>
+				</div>
+				<div class="flex shrink-0 items-center gap-0.5">
+					<BbButton
+						v-bb-tooltip="{ text: 'Expand all on this page', delay: 400 }"
+						aria-label="Expand all on this page"
+						icon="lucide:chevrons-down"
+						size="sm"
+						variant="ghost"
+						@click="ctx.expandAllOnPage"
+					/>
+					<BbButton
+						v-bb-tooltip="{ text: 'Collapse all', delay: 400 }"
+						aria-label="Collapse all"
+						icon="lucide:chevrons-up"
+						size="sm"
+						variant="ghost"
+						@click="ctx.collapseAll"
+					/>
+				</div>
+			</div>
+
+			<!-- No dependencies/items-fn: `owners` is a page prop, and selection
+			     (across pages) binds straight onto the keyed table context.
+			     `fixed` gives the parent equal-width tracks — a predictable grid
+			     for the nested table to snap onto. -->
+			<BbTable
+				v-model="ctx.table.selected.value"
+				v-model:expanded-items="ctx.expanded.value"
+				v-model:highlighted="highlightedOwner"
+				v-model:select-all="ctx.table.all.value"
+				v-model:unselected-items="ctx.table.unselected.value"
+				actions
+				actions-text="Holdings"
+				caption="Resource owners"
+				class="table-flush"
+				:columns="columns"
+				compact
+				fixed
+				item-value="id"
+				:items="ctx.table.items.value"
+				loading-text="Loading owners…"
+				:row-class="rowClass"
+				selectable
+			>
+				<template #name="{ item, content }">
+					<div class="flex min-w-0 flex-col leading-tight">
+						<span class="font-semibold">{{ content }}</span>
+						<span class="truncate text-xs text-gray-500">{{ item.email }}</span>
+					</div>
+				</template>
+
+				<template #team="{ item, content }">
+					<div class="flex min-w-0 flex-col leading-tight">
+						<span>{{ content }}</span>
+						<span class="truncate text-xs text-gray-500">{{ item.title }}</span>
+					</div>
+				</template>
+
+				<template #region="{ item }">
+					<span class="text-xs text-gray-500">{{
+						REGION_LABEL[item.region]
+					}}</span>
+				</template>
+
+				<template #monthlytotal="{ content }">
+					<span class="tabular-nums">{{ money(content) }}</span>
+				</template>
+
+				<!-- The actions column IS the expand control: the holdings count
+				     doubles as the toggle, `expandProps` wires aria + keyboard. -->
+				<template #actions="{ item, expanded: isOpen, expandProps }">
+					<BbButton
+						v-bind="expandProps"
+						:append:icon="isOpen ? 'lucide:chevron-up' : 'lucide:chevron-down'"
+						:aria-label="
+							isOpen
+								? `Collapse ${item.holdingsCount} holdings`
+								: `Expand ${item.holdingsCount} holdings`
+						"
+						size="xs"
+						variant="ghost"
+					>
+						<span class="tabular-nums">{{ item.holdingsCount }}</span>
+					</BbButton>
+				</template>
+
+				<!-- The signature move: a nested BbTable that inherits this
+				     table's column tracks. -->
+				<template #expand="{ item }">
+					<HoldingsTable :owner="item" />
+				</template>
+
+				<template #no-data>
+					<div
+						class="mx-auto flex max-w-sm flex-col items-center gap-3 px-6 py-12 text-center"
+					>
+						<BbIcon
+							class="text-gray-400"
+							:icon="
+								ctx.hasActiveFilters.value ? 'lucide:search-x' : 'lucide:layers'
+							"
+							size="2xl"
+						/>
+						<p class="text-sm font-semibold">
+							{{
+								ctx.hasActiveFilters.value
+									? 'No matching owners'
+									: 'No owners in this region'
+							}}
+						</p>
+						<p class="text-xs text-gray-500">
+							{{
+								ctx.hasActiveFilters.value
+									? 'Clear the holding-type filter, or widen search.'
+									: 'Switch tabs to another region.'
+							}}
+						</p>
+						<BbButton
+							v-if="ctx.hasActiveFilters.value"
+							prepend:icon="lucide:x"
+							size="sm"
+							variant="outline"
+							@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="Owners pagination"
+				:total-pages="ctx.table.totalPages.value"
+			/>
+		</div>
+
+		<SelectionBar />
+
+		<!-- The peek: rendered by type; row highlight drives the stack. -->
+		<template #sidebar>
+			<OwnerPeek
+				v-if="ctx.shell.current.value?.type === 'owner'"
+				:owner-id="ctx.shell.current.value.id"
+			/>
+		</template>
+	</PageShell>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import {
+	BbBreadcrumbs,
+	BbButton,
+	BbIcon,
+	BbPagination,
+	BbTable,
+	BbTabs,
+	BbTextInput,
+	vBbTooltip,
+	type BbTableColumn,
+} from 'bitboss-ui';
+import PageShell from '@/components/layout/PageShell.vue';
+import { provideOwnershipAtlas, REGION_LABEL } from './context';
+import FilterRail from './FilterRail.vue';
+import HoldingsTable from './HoldingsTable.vue';
+import OwnerPeek from './OwnerPeek.vue';
+import SelectionBar from './SelectionBar.vue';
+import type { Owner } from '@/types';
+
+const ctx = provideOwnershipAtlas();
+
+/** Row highlight IS the peek: clicking a row opens owner detail in the
+ * sidebar; clicking it again (BbTable clears the highlight) closes it. */
+const highlightedOwner = computed<string | null>({
+	get: () =>
+		ctx.shell.current.value?.type === 'owner'
+			? ctx.shell.current.value.id
+			: null,
+	set: (id) => {
+		if (id == null) ctx.shell.close();
+		else ctx.peekOwner(id);
+	},
+});
+
+/** Four data columns — the nested holdings table snaps onto them 1:1. The
+ * owner's title rides under Team; the holdings count lives on the expand
+ * control in the actions column. */
+const columns: Array<BbTableColumn<Owner>> = [
+	{ key: 'name', label: 'Owner' },
+	{ key: 'team', label: 'Team' },
+	{ key: 'region', label: 'Region' },
+	{ key: 'monthlyTotal', label: '$ / mo', align: 'right' },
+];
+
+const money = (value: number) =>
+	new Intl.NumberFormat('en-US', {
+		style: 'currency',
+		currency: 'USD',
+		maximumFractionDigits: 0,
+	}).format(value);
+
+// Public row-class API paints every row state: the base class carries the
+// pointer cursor (rows are click targets — highlight opens the peek), the
+// conditional classes carry the expanded / peek-open washes.
+const rowClass = (item: Owner) => {
+	const classes = ['owner-row'];
+	if (ctx.expanded.value.includes(item.id)) classes.push('row-expanded');
+	if (highlightedOwner.value === item.id) classes.push('row-peeked');
+	return classes.join(' ');
+};
+</script>
+
+<style scoped>
+/* Full-bleed table: mirror the content wrapper's `p-4` so row washes and the
+   nested table run edge to edge, while the outermost cells keep the optical
+   margin — content stays lined up with the filter rail and tabs above. */
+.table-flush {
+	--page-inset: 1rem;
+	margin-inline: calc(var(--page-inset) * -1);
+	width: calc(100% + var(--page-inset) * 2);
+}
+
+/* Direct-child combinators keep these overrides on the OWNER table's own
+   cells. A bare `:deep(tbody td:first-child)` would also match the nested
+   holdings table and clobber the structural offset padding it computes to
+   stay flush with the parent grid — the one selector mistake that silently
+   breaks nested-table alignment. */
+.table-flush :deep(> table > thead > tr > th:first-child),
+.table-flush
+	:deep(> table > tbody > tr > td:first-child:not(.bb-table-expand__cell)) {
+	padding-inline-start: var(--page-inset);
+}
+
+.table-flush :deep(> table > thead > tr > th:last-child),
+.table-flush
+	:deep(> table > tbody > tr > td:last-child:not(.bb-table-expand__cell)) {
+	padding-inline-end: var(--page-inset);
+}
+
+/* Expand rows stay edge-to-edge so the nested table can inherit the parent
+   tracks without an extra inset shifting everything sideways. */
+.table-flush :deep(> table > tbody > tr > td.bb-table-expand__cell) {
+	padding-inline: 0;
+}
+
+/* Row states, painted through the public row-class API. */
+:deep(.owner-row) {
+	cursor: pointer;
+}
+
+/* Expanded = hierarchy only: a quiet ink wash, no accent. */
+:deep(.row-expanded) {
+	background-color: color-mix(in oklab, var(--bb-text) 2.5%, transparent);
+}
+
+/* Peek-open = accent wash + a 1px lead pin on the row's start edge. */
+:deep(.row-peeked) {
+	background-color: color-mix(in oklab, var(--bb-primary) 6%, transparent);
+	box-shadow: inset 1px 0 0 0 var(--bb-primary);
+}
+</style>
+```
+
+### HoldingsTable.vue — the nested table
+
+```vue
+<!-- OwnershipAtlas/HoldingsTable.vue — nested BbTable snapped under the owner. -->
+<template>
+	<div class="holdings-nest">
+		<BbTable
+			:caption="`Holdings owned by ${owner.name}`"
+			class="w-full"
+			:columns="columns"
+			compact
+			inherit-column-widths
+			item-value="id"
+			:items="owner.holdings"
+		>
+			<template #name="{ item, content }">
+				<div class="flex min-w-0 flex-col leading-tight">
+					<span class="font-semibold">{{ content }}</span>
+					<span class="text-xs text-gray-500">
+						Since {{ monthLabel(item.since) }} · {{ item.region }}
+					</span>
+				</div>
+			</template>
+
+			<template #kind="{ item }">
+				<span class="text-xs text-gray-500">{{ KIND_LABEL[item.kind] }}</span>
+			</template>
+
+			<template #status="{ item }">
+				<BbBadge size="sm" :variant="STATUS_VARIANT[item.status]">
+					{{ STATUS_LABEL[item.status] }}
+				</BbBadge>
+			</template>
+
+			<template #monthlycost="{ content }">
+				<span class="tabular-nums">{{ money(content) }}</span>
+			</template>
+		</BbTable>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbBadge, BbTable, type BbTableColumn } from 'bitboss-ui';
+import { KIND_LABEL, STATUS_LABEL, STATUS_VARIANT } from './context';
+import type { Holding, Owner } from '@/types';
+
+defineProps<{ owner: Owner }>();
+
+/**
+ * Explicit snaps onto the parent grid. The parent is `selectable`, so its
+ * select column occupies tracks [0, 1] and the data columns sit at 1…4 —
+ * `snap` base is 1 (it would be 0 under a non-selectable parent). Every
+ * column defines a snap so none becomes the auto fill track: a width-free
+ * last column would absorb the parent's actions region, and right-aligned
+ * $/mo would land under the expand control instead of under the parent's
+ * $/mo. With all four snapped, the parent's select and actions tracks fold
+ * into the child's first/last cells as padding — the child starts flush with
+ * the parent's first data column, and that inset is what reads as hierarchy.
+ */
+const columns: Array<BbTableColumn<Holding>> = [
+	{ key: 'name', label: 'Resource', snap: 1 },
+	{ key: 'kind', label: 'Type', snap: 2 },
+	{ key: 'status', label: 'Status', snap: 3 },
+	{ key: 'monthlyCost', label: '$ / mo', align: 'right', snap: 4 },
+];
+
+const money = (value: number) =>
+	value === 0
+		? '—'
+		: new Intl.NumberFormat('en-US', {
+				style: 'currency',
+				currency: 'USD',
+				maximumFractionDigits: 0,
+			}).format(value);
+
+const monthLabel = (value: string) =>
+	new Date(value).toLocaleDateString('en-US', {
+		month: 'short',
+		year: 'numeric',
+	});
+</script>
+
+<style scoped>
+/* Full-bleed inside the expand cell — the inherited snaps keep Resource
+   under Owner. Hierarchy is the hairline + faint wash, NOT a padding inset:
+   an inset would shift the child's cells off the parent's tracks and make
+   the alignment lie. */
+.holdings-nest {
+	background: color-mix(in oklab, var(--bb-text) 1.5%, transparent);
+	border-block-start: 1px solid var(--bb-border);
+	width: 100%;
+}
+</style>
+```
+
+### FilterRail.vue
+
+```vue
+<!-- OwnershipAtlas/FilterRail.vue -->
+<template>
+	<div class="flex flex-wrap items-center gap-2">
+		<!-- Holding type: multi-select pill over the kind catalog. Filtering by
+		     kind reshapes the owners themselves (server-side): owners with no
+		     matching holding drop out, counts and totals recompute. -->
+		<BbSelectPopover
+			v-model="ctx.filters.kinds"
+			clearable
+			item-text="label"
+			item-value="value"
+			:items="kindOptions"
+			multiple
+		>
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					append:icon="lucide:chevron-down"
+					prepend:icon="lucide:layers"
+					size="sm"
+					variant="outline"
+				>
+					Holding type{{
+						ctx.filters.kinds.length ? ` · ${ctx.filters.kinds.length}` : ''
+					}}
+				</BbButton>
+			</template>
+		</BbSelectPopover>
+
+		<!-- Clear-all renders only while something is active. -->
+		<BbButton
+			v-if="ctx.hasActiveFilters.value"
+			prepend:icon="lucide:x"
+			size="sm"
+			variant="ghost"
+			@click="ctx.clearFilters"
+		>
+			Clear
+		</BbButton>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbButton, BbSelectPopover } from 'bitboss-ui';
+import { KIND_LABEL, useOwnershipAtlas } from './context';
+import type { HoldingKind } from '@/types';
+
+const ctx = useOwnershipAtlas();
+
+// The pill's options come straight from the shared label catalog.
+const kindOptions = (
+	Object.entries(KIND_LABEL) as Array<[HoldingKind, string]>
+).map(([value, label]) => ({ value, label }));
+</script>
+```
+
+### SelectionBar.vue
+
+```vue
+<!-- OwnershipAtlas/SelectionBar.vue -->
+<template>
+	<FloatingBottomPanel :open="selectedCount > 0">
+		<span class="px-2 text-sm text-gray-500">
+			<span class="font-semibold tabular-nums">{{ selectedCount }}</span>
+			selected
+		</span>
+
+		<BbButton
+			prepend:icon="lucide:chevrons-down"
+			size="sm"
+			variant="ghost"
+			@click="ctx.expandSelected"
+		>
+			Expand
+		</BbButton>
+
+		<!-- Bulk transfer: a one-shot popover (model stays null) whose pick IS
+		     the action. Targets exclude every selected owner — you cannot
+		     transfer holdings onto an owner you are emptying. -->
+		<BbSelectPopover
+			item-text="name"
+			item-value="id"
+			:items="transferTargets"
+			:model-value="null"
+			:offset="10"
+			placement="top"
+			width="240px"
+			@update:model-value="onTransfer"
+		>
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					append:icon="lucide:chevron-up"
+					prepend:icon="lucide:arrow-right-left"
+					size="sm"
+					variant="ghost"
+				>
+					Transfer holdings
+				</BbButton>
+			</template>
+		</BbSelectPopover>
+
+		<div class="floating-bottom-panel__right flex items-center gap-1">
+			<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, BbSelectPopover } from 'bitboss-ui';
+import FloatingBottomPanel from '@/components/layout/FloatingBottomPanel.vue';
+import { useOwnershipAtlas } from './context';
+
+const ctx = useOwnershipAtlas();
+
+// `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
+);
+
+/** Don't offer transferring onto an owner who is already in the selection. */
+const transferTargets = computed(() => {
+	const selected = new Set(
+		ctx.table.all.value
+			? ctx.ownerOptions.value
+					.map((owner) => owner.id)
+					.filter((id) => !ctx.table.unselected.value.includes(id))
+			: ctx.table.selected.value
+	);
+	return ctx.ownerOptions.value.filter((owner) => !selected.has(owner.id));
+});
+
+const onTransfer = (value: unknown) => {
+	if (typeof value !== 'string' || !value) return;
+	void ctx.bulkTransfer(value);
+};
+</script>
+```
+
+### OwnerPeek.vue
+
+```vue
+<!-- OwnershipAtlas/OwnerPeek.vue — sidebar workbench for the highlighted owner. -->
+<template>
+	<div v-if="owner" class="flex flex-col gap-4 text-sm">
+		<!-- Identity header. -->
+		<header class="flex flex-col gap-1">
+			<h2 class="text-base font-semibold tracking-tight">{{ owner.name }}</h2>
+			<p class="text-xs text-gray-500">{{ owner.email }}</p>
+			<p class="text-xs text-gray-500">
+				{{ owner.title }} · {{ owner.team }} ·
+				{{ REGION_LABEL[owner.region] }}
+			</p>
+		</header>
+
+		<!-- Properties. -->
+		<dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1.5">
+			<dt class="text-gray-500">Holdings</dt>
+			<dd class="text-right tabular-nums">{{ owner.holdingsCount }}</dd>
+			<dt class="text-gray-500">Monthly</dt>
+			<dd class="text-right font-medium tabular-nums">
+				{{ money(owner.monthlyTotal) }}
+			</dd>
+			<dt class="text-gray-500">Joined</dt>
+			<dd class="text-right">{{ longDate(owner.joinedAt) }}</dd>
+			<dt class="text-gray-500">Manager</dt>
+			<dd class="text-right">{{ owner.manager ?? '—' }}</dd>
+		</dl>
+
+		<section v-if="owner.notes" class="flex flex-col gap-1.5">
+			<h3 class="text-xs font-semibold uppercase tracking-wide text-gray-500">
+				Notes
+			</h3>
+			<p>{{ owner.notes }}</p>
+		</section>
+
+		<!-- Rollup by holding type. -->
+		<section class="flex flex-col gap-1.5">
+			<h3 class="text-xs font-semibold uppercase tracking-wide text-gray-500">
+				By type
+			</h3>
+			<ul class="flex flex-col gap-1.5">
+				<li
+					v-for="row in owner.kindBreakdown"
+					:key="row.kind"
+					class="grid grid-cols-[1fr_auto_auto] items-baseline gap-3"
+				>
+					<span class="min-w-0">{{ KIND_LABEL[row.kind] }}</span>
+					<span class="text-xs tabular-nums text-gray-500">{{
+						row.count
+					}}</span>
+					<span class="text-xs tabular-nums text-gray-500">{{
+						money(row.monthlyCost)
+					}}</span>
+				</li>
+			</ul>
+		</section>
+
+		<!-- The holdings themselves — a real list, not a summary sentence. -->
+		<section class="flex flex-col gap-1.5">
+			<h3 class="text-xs font-semibold uppercase tracking-wide text-gray-500">
+				Holdings
+			</h3>
+			<ul class="flex flex-col gap-2">
+				<li
+					v-for="holding in owner.holdings"
+					:key="holding.id"
+					class="flex items-start justify-between gap-3"
+				>
+					<div class="flex min-w-0 flex-1 flex-col gap-0.5">
+						<span class="font-medium">{{ holding.name }}</span>
+						<span class="text-xs text-gray-500"
+							>{{ KIND_LABEL[holding.kind] }} · {{ holding.region }}</span
+						>
+					</div>
+					<div class="flex flex-col items-end gap-1">
+						<BbBadge size="sm" :variant="STATUS_VARIANT[holding.status]">
+							{{ STATUS_LABEL[holding.status] }}
+						</BbBadge>
+						<span class="text-xs tabular-nums text-gray-500">{{
+							money(holding.monthlyCost)
+						}}</span>
+					</div>
+				</li>
+			</ul>
+		</section>
+
+		<!-- Workbench footer: act from the peek back into the table. -->
+		<footer class="mt-2 flex items-center gap-2 border-t pt-3">
+			<BbButton
+				prepend:icon="lucide:chevrons-down"
+				size="sm"
+				variant="secondary"
+				@click="onExpandInTable"
+			>
+				Expand in table
+			</BbButton>
+		</footer>
+	</div>
+
+	<div v-else class="flex justify-center p-8">
+		<BbSpinner />
+	</div>
+</template>
+
+<script setup lang="ts">
+import { watch } from 'vue';
+import { BbBadge, BbButton, BbSpinner } from 'bitboss-ui';
+import { useResourceContext } from '@/composables/useResourceContext';
+import {
+	KIND_LABEL,
+	REGION_LABEL,
+	STATUS_LABEL,
+	STATUS_VARIANT,
+	useOwnershipAtlas,
+} from './context';
+import type { OwnerDetail } from '@/types';
+
+const props = defineProps<{ ownerId: string }>();
+
+const ctx = useOwnershipAtlas();
+
+// A small JSON endpoint, not a page visit — opening the peek never
+// re-renders the list underneath it. Re-fetches whenever the highlight moves
+// to a different owner; `refreshKey` makes bulk transfers reflect here
+// immediately.
+const { data: owner, refresh } = useResourceContext<OwnerDetail, string>(
+	() => props.ownerId,
+	ctx.fetchOwner
+);
+watch(() => ctx.refreshKey.value, refresh);
+
+const money = (value: number) =>
+	value === 0
+		? '—'
+		: new Intl.NumberFormat('en-US', {
+				style: 'currency',
+				currency: 'USD',
+				maximumFractionDigits: 0,
+			}).format(value);
+
+const longDate = (value: string) =>
+	new Date(value).toLocaleDateString('en-US', {
+		month: 'short',
+		day: 'numeric',
+		year: 'numeric',
+	});
+
+// The peek writes the same expansion array the table reads — one rung-3
+// state, three writers (toolbar, bulk bar, peek).
+const onExpandInTable = () => {
+	if (!owner.value) return;
+	if (!ctx.expanded.value.includes(owner.value.id)) {
+		ctx.expanded.value = [...ctx.expanded.value, owner.value.id];
+	}
+};
+</script>
+```
+
+### The domain types (`@/types`)
+
+```ts
+export type HoldingKind =
+	| 'workspace'
+	| 'project'
+	| 'domain'
+	| 'database'
+	| 'vault'
+	| 'device'
+	| 'seat-pool'
+	| 'bucket';
+
+export type HoldingStatus = 'active' | 'paused' | 'provisioning' | 'retired';
+
+export type OwnerRegion = 'americas' | 'emea' | 'apac';
+
+/** A resource an owner is responsible for — one nested-table row. */
+export interface Holding {
+	id: string;
+	name: string;
+	kind: HoldingKind;
+	status: HoldingStatus;
+	/** `YYYY-MM-DD` — when ownership began. */
+	since: string;
+	monthlyCost: number;
+	region: string;
+}
+
+/** Parent row: a person with the holdings they own embedded. */
+export interface Owner {
+	id: string;
+	name: string;
+	email: string;
+	team: string;
+	title: string;
+	region: OwnerRegion;
+	holdingsCount: number;
+	monthlyTotal: number;
+	holdings: Holding[];
+}
+
+/** Transfer-picker option. */
+export type OwnerOption = { id: string; name: string; team: string };
+
+/** Rich owner detail for the sidebar peek. */
+export interface OwnerDetail extends Owner {
+	joinedAt: string;
+	manager: string | null;
+	notes: string;
+	kindBreakdown: Array<{
+		kind: HoldingKind;
+		count: number;
+		monthlyCost: number;
+	}>;
+}
+```
+
+## Why it is built this way
+
+- **The nested table inherits the parent's tracks — never eyeballed
+  widths.** `inherit-column-widths` is the whole alignment mechanism: the
+  holdings table reads the owners table's measured tracks, so Resource sits
+  under Owner and both $/mo columns share one right edge at every viewport
+  width. Two hand-maintained `<colgroup>`s (or two tables that merely look
+  similar) drift apart the first time a label changes; the inheritance
+  cannot.
+- **Every child column snaps, and the base is 1.** The parent is
+  `selectable`, so its select column occupies the region before the first
+  data track — child snaps start at `1` (`0` would put Resource under the
+  checkboxes). And no child column may be left width-free: the width-free
+  column becomes the fill track and absorbs the parent's **actions** region,
+  which visually parks right-aligned $/mo under the expand control. With
+  all four columns snapped, the select and actions tracks fold into the
+  child's first/last cells as padding, and the child starts flush with the
+  parent's first data column — that structural inset, plus a hairline and a
+  faint wash, is the entire hierarchy treatment. No extra padding inset:
+  an inset would make the alignment lie.
+- **Cell-padding overrides use direct-child combinators.** `.table-flush`
+  bleeds the owner table past the page padding and re-adds the inset on the
+  outermost cells — but only via
+  `:deep(> table > tbody > tr > td:first-child)`. A bare descendant
+  selector would also hit the nested table's cells and clobber the offset
+  padding it computes to stay on the parent grid. The expand cell itself is
+  excluded from the inset and zero-padded, so the nested table gets the full
+  row width to snap within.
+- **Expansion is rung-3 page state.** `expanded` lives in the context
+  because four surfaces touch it: the per-row control, the toolbar's
+  expand-all/collapse-all, the bulk bar's Expand, and the peek's "Expand in
+  table". Binding it through `v-model:expanded-items` (tracked by
+  `item-value`) means expansion survives the partial reloads that replace
+  the row objects. It stays out of the URL deliberately — unfolded rows are
+  working posture, not a shareable view.
+- **The actions column is the expand control.** This page's per-row action
+  _is_ "show me the holdings", so the holdings count doubles as the toggle
+  (`expandProps` wires `aria-expanded` and keyboard handling onto a real
+  button). No `…` dropdown padding out the inventory.
+- **Row highlight is the peek, via one two-way computed.** `get` derives the
+  highlighted id from the shell stack; `set` pushes or closes. Highlight and
+  selection remain independent axes — you can peek one owner while twelve
+  are selected for transfer.
+- **The context coopts, leaves consume.** `shell` and the keyed
+  `useTableContext('owners')` are joined once in `provideOwnershipAtlas()`;
+  five components share filters, selection, expansion, the peek and the
+  transfer action through one `useOwnershipAtlas()` call. Leaves receive
+  only the data they render (`owner`, `owner-id`).
+- **`owners` is a page prop, not a client fetch.** The server owns
+  filtering, search, tab scoping and pagination; `useQueryObject` (filters)
+  and `href` + `server: true` tabs are two doors into the same partial
+  reload. The `kinds` filter reshapes the owners themselves server-side —
+  the client never re-derives counts or totals.
+- **Bulk transfer carries the full select-all-across-pages payload**
+  (`ids`/`all`/`unselected` + `toOwnerId`), and the target list excludes the
+  current selection — the UI cannot express "transfer onto an owner being
+  emptied". The action is complete: visit, refresh bump, selection reset,
+  toast naming the target.
+- **Sizing:** the topbar search is `compact` (28px) per `md`-first; `sm`
+  appears only in the toolbar, rail pills, peek footer and bottom bar, and
+  the in-row expand control is `xs` — the densest surface on the page. This
+  page creates nothing, so no `variant="primary"` appears anywhere, and its
+  one mutation is not destructive, so there is no `useConfirm` — holdings
+  move, they are not lost.
+
+## Variations
+
+- **Per-holding actions**: give the nested table its own `actions` column
+  (a `…` dropdown with "Transfer this holding") calling the same context
+  action with a single id. Snap indices are unaffected — structural columns
+  are accounted for automatically.
+- **Divergent child columns**: if the holdings table needs columns that
+  should _not_ align (say, an audit-log expansion), drop
+  `inherit-column-widths` and let it lay out independently — inheritance is
+  for continuation, not for every nested table.
+- **Confirmed transfers**: if a transfer is heavyweight in your domain
+  (billing moves with it), wrap `bulkTransfer` in `useConfirm` with the
+  count and target in the message.
+- **Deep-linkable expansion**: mirror `expanded` into the URL alongside the
+  filters if support wants to share "look at this owner's holdings" links.
+- **Keyboard triage**: add `keyboard-navigation` to the owners table —
+  highlight already opens the peek, so arrows + Enter make the page
+  reviewable hands-on-keyboard; the approvals-inbox recipe is the full
+  treatment.