bitboss-ui 3.0.0-beta.65 → 3.0.0-beta.67

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

@@ -52,9 +52,7 @@ label state) · [Page Shell](../../guides/page-shell.md) ·
 [Floating Bottom Panel](../../guides/floating-bottom-panel.md).
 
 From the [Inertia Helpers](../../guides/inertia-helpers.md) toolkit, installed
-with `npx bitboss-ui add useProp useQuery useQueryObject useResourceContext useTableContext`.
-`<BbHost />` mounted once in the
-`createInertiaApp` render root — never in a page.
+with `npx bitboss-ui add usePromiseRouter useProp useQuery useQueryObject useResourceContext useRouteQuery useTableContext`.
 
 Controller: `Inertia::render('BacklogWorkspace/Index', ['issues' => …, 'tabCounts'
 => …, 'team' => …])` — `issues` is a standard Laravel paginator
@@ -105,11 +103,11 @@ peek so opening it is never a page visit.
   prop; `useTableContext('issues')` 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.** Typing in a pill filter performs a partial Inertia visit
-  (`only: ['issues', 'tabCounts']`); `BbTabs` items carry `href` +
-  `server: true` with the same `only` list. The server is the single source
-  of filtered, paginated truth.
+- **Filters mirror into the URL with `useQueryObject`; the sprint strip is a
+  real visit.** Typing in a pill filter performs a partial Inertia visit
+  (`only: ['issues', 'tabCounts']`); the sprint strip (a `BbRadioGroup` with
+  the tabs look) is the `?tab=` query through `useRouteQuery`, with the same
+  `only` list. The server is the single source of filtered, paginated truth.
 - **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 — filtering the `team` page
@@ -151,7 +149,7 @@ needs a modal to edit.
 | --- | ------------------------ | ---------------------------------- | ------------------------------------------------------- |
 | 1   | New issue                | topbar, the page's one `primary`   | navigation (`/issues/new`)                              |
 | 2   | Page search              | topbar right                       | `filters.search` → `useQueryObject` partial visit       |
-| 3   | Switch sprint tab        | href tabs with live counts         | `BbTabs` `href` + `server: true` partial visit          |
+| 3   | Switch sprint tab        | status strip with live counts      | `useRouteQuery` partial visit                           |
 | 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               |
@@ -257,8 +255,7 @@ import {
 	type InjectionKey,
 	type Ref,
 } from 'vue';
-import { router, usePage } from '@inertiajs/vue3';
-import type { RequestPayload } from '@inertiajs/core';
+import { usePage } from '@inertiajs/vue3';
 import {
 	useConfirm,
 	useToast,
@@ -274,9 +271,11 @@ import {
 	type TableContext,
 } from '@/composables/inertia-helpers/useTableContext';
 import { useQueryObject } from '@/composables/inertia-helpers/useQueryObject';
+import { useRouteQuery } from '@/composables/inertia-helpers/useRouteQuery';
 import { useQuery } from '@/composables/inertia-helpers/useQuery';
 import { useProp } from '@/composables/inertia-helpers/useProp';
 import type { Issue, IssuePriority, IssueStatus, Member } from '@/types';
+import { usePromiseRouter } from '@/composables/inertia-helpers/usePromiseRouter';
 
 /**
  * What the peek sidebar can show. Clicking an issue ref pushes one of these.
@@ -300,7 +299,7 @@ export type IssuePatch = Partial<
 export type EditableKey = keyof IssuePatch;
 
 export interface BacklogFilters {
-	search: string;
+	search: string | null;
 	status: IssueStatus[];
 	priority: IssuePriority[];
 	/** The whole member, not an id — the pill labels itself with zero fetches. */
@@ -425,40 +424,27 @@ const toArray = (value: unknown): string[] | null => {
 	return Array.isArray(value) ? value.map(String) : String(value).split(',');
 };
 
-/**
- * Inertia's callback-based visit, wrapped as a promise — so every context
- * action stays `async`, exactly like the Vue/Nuxt versions. Always a
- * partial reload; field saves pass just `['issues']`, everything else
- * refreshes the tab counts too.
- */
-const visit = (
-	method: 'post' | 'patch' | 'delete',
-	url: string,
-	// Inertia's own payload type — strings/numbers/booleans/arrays/files.
-	// (`Record<string, unknown>` does not satisfy it.)
-	data: RequestPayload = {},
-	only: readonly string[] = RELOAD_PROPS
-): Promise<void> =>
-	new Promise((resolve, reject) => {
-		router.visit(url, {
-			method,
-			data,
-			only: [...only],
-			preserveScroll: true,
-			preserveState: true,
-			onSuccess: () => resolve(),
-			onError: (errors) => reject(errors),
-			// Cut short (cancelled, or interrupted by another visit): resolves,
-			// the caller moves on (a dialog closes). Ended with neither callback
-			// (a 500, a network error): rejects with no field errors. Both are
-			// no-ops once settled.
-			onFinish: (visit) =>
-				visit.cancelled || visit.interrupted ? resolve() : reject({}),
-		});
-	});
-
 export function provideBacklogWorkspace(): BacklogWorkspaceContext {
+	// Every write of the page: a promise the buttons spin on, reloading the
+	// page's props in place.
+	const { patch, post, remove } = usePromiseRouter({
+		only: [...RELOAD_PROPS],
+		preserveScroll: true,
+		preserveState: true,
+	});
 	const { toast } = useToast();
+	// A write that fails tells the user and reads as not done. The helpers
+	// reject (the error bag on a 422, an Error otherwise) instead of hiding a
+	// failure, so no caller sees an `Uncaught (in promise)` (Inertia helpers
+	// guide § usePromiseRouter).
+	const orToast = (write: Promise<boolean>) =>
+		write.catch(() => {
+			toast({
+				title: 'That did not go through. Try again.',
+				variant: 'destructive',
+			});
+			return false;
+		});
 	const { confirm } = useConfirm();
 
 	// -- Coopt the specific contexts: once, here, for the whole page. ----------
@@ -500,7 +486,7 @@ export function provideBacklogWorkspace(): BacklogWorkspaceContext {
 
 	const hasActiveFilters = computed(
 		() =>
-			filters.search !== '' ||
+			!!filters.search ||
 			filters.status.length > 0 ||
 			filters.priority.length > 0 ||
 			filters.assignee !== null
@@ -512,9 +498,13 @@ export function provideBacklogWorkspace(): BacklogWorkspaceContext {
 		filters.assignee = null;
 	};
 
-	// Tab: seeded from the URL; BbTabs' own `href` + `server` visit updates
-	// the URL, and its `v-model` write keeps this ref in sync with the click.
-	const tab = ref<SprintTab>((query.tab as SprintTab) ?? 'current');
+	// Tab: the `?tab=` query itself. A pick is a partial-reload visit
+	// (replace, preserveState / preserveScroll) that keeps the other query
+	// keys, and the value follows the URL, so it changes as the visit lands.
+	const tab = useRouteQuery('tab', 'current', {
+		transform: (value) => value as SprintTab,
+		visitOptions: { only: [...RELOAD_PROPS] },
+	});
 	const tabCounts = useProp<Record<SprintTab, number>>('tabCounts');
 
 	const refreshKey = ref(0);
@@ -524,16 +514,16 @@ export function provideBacklogWorkspace(): BacklogWorkspaceContext {
 	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
+		const overlay = pending[issue.id];
+		// `key in overlay`, not `overlay[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];
+		return overlay && key in overlay ? (overlay[key] as Issue[K]) : issue[key];
 	};
 
 	const isSaving = (issue: Issue, key: EditableKey): boolean => {
-		const patch = pending[issue.id];
-		return patch !== undefined && key in patch;
+		const overlay = pending[issue.id];
+		return overlay !== undefined && key in overlay;
 	};
 
 	/** Human labels for the editable fields — used in the autosave/undo toasts. */
@@ -573,11 +563,31 @@ export function provideBacklogWorkspace(): BacklogWorkspaceContext {
 		const flag = `${issue.id}:${key}`;
 		(pending[issue.id] ??= {})[key] = value; // optimistic: the UI moves NOW
 		failed.value.delete(flag);
+		// Rollback: drop just this field, the row shows the server's value.
+		const drop = () => {
+			const overlay = pending[issue.id];
+			if (overlay) {
+				delete overlay[key];
+				if (!Object.keys(overlay).length) delete pending[issue.id];
+			}
+		};
 		try {
 			// One visit is both the PATCH and the reload — the redirect back
 			// re-renders `issues`. Do NOT retire the overlay here: the watcher
 			// below drops it once the server's own data carries the value.
-			await visit('patch', `/issues/${issue.id}`, { [key]: value }, ['issues']);
+			if (
+				!(await patch(
+					`/issues/${issue.id}`,
+					{ [key]: value },
+					{ only: ['issues'] }
+				))
+			) {
+				// Not confirmed (a newer edit interrupted it): show what the
+				// server holds rather than a value nothing will confirm.
+				drop();
+				refreshKey.value++;
+				return;
+			}
 			refreshKey.value++; // the peek re-fetches its JSON detail
 			// Auto-undo: soft confirmation the edit can reverse in one click.
 			toast({
@@ -596,12 +606,7 @@ export function provideBacklogWorkspace(): BacklogWorkspaceContext {
 				],
 			});
 		} 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];
-			}
+			drop();
 			failed.value.add(flag);
 			toast({
 				title: `Couldn't save the ${key} of ${issue.ref} — reverted.`,
@@ -624,14 +629,14 @@ export function provideBacklogWorkspace(): BacklogWorkspaceContext {
 	// arrival path. A field still in flight is left alone.
 	watch(table.items, (rows) => {
 		for (const issue of rows) {
-			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
+			const overlay = pending[issue.id];
+			if (!overlay) continue;
+			for (const field of Object.keys(overlay) as EditableKey[]) {
+				if (JSON.stringify(overlay[field]) === JSON.stringify(issue[field])) {
+					delete overlay[field]; // the server's own data carries it now
 				}
 			}
-			if (!Object.keys(patch).length) delete pending[issue.id];
+			if (!Object.keys(overlay).length) delete pending[issue.id];
 		}
 	});
 
@@ -655,7 +660,7 @@ export function provideBacklogWorkspace(): BacklogWorkspaceContext {
 	};
 
 	const duplicateIssue = async (issue: Issue) => {
-		await visit('post', `/issues/${issue.id}/duplicate`);
+		if (!(await orToast(post(`/issues/${issue.id}/duplicate`)))) return;
 		refresh();
 		toast({
 			title: `${issue.ref} duplicated.`,
@@ -664,7 +669,7 @@ export function provideBacklogWorkspace(): BacklogWorkspaceContext {
 	};
 
 	const moveToNextSprint = async (issue: Issue) => {
-		await visit('post', `/issues/${issue.id}/next-sprint`);
+		if (!(await orToast(post(`/issues/${issue.id}/next-sprint`)))) return;
 		refresh();
 		toast({
 			title: `${issue.ref} moved to Sprint 25.`,
@@ -681,7 +686,7 @@ export function provideBacklogWorkspace(): BacklogWorkspaceContext {
 			no: 'Cancel',
 		});
 		if (!ok) return;
-		await visit('delete', `/issues/${issue.id}`);
+		if (!(await orToast(remove(`/issues/${issue.id}`)))) return;
 		refresh();
 		toast({
 			title: `${issue.ref} deleted.`,
@@ -705,7 +710,12 @@ export function provideBacklogWorkspace(): BacklogWorkspaceContext {
 
 	const bulkStatus = async (status: IssueStatus) => {
 		const count = selectedCount.value;
-		await visit('patch', '/issues/bulk/status', { ...bulkPayload(), status });
+		if (
+			!(await orToast(
+				patch('/issues/bulk/status', { ...bulkPayload(), status })
+			))
+		)
+			return;
 		table.resetSelection();
 		refresh();
 		const label = STATUS_OPTIONS.find((o) => o.value === status)?.label;
@@ -717,10 +727,15 @@ export function provideBacklogWorkspace(): BacklogWorkspaceContext {
 
 	const bulkAssign = async (assignee: Member) => {
 		const count = selectedCount.value;
-		await visit('patch', '/issues/bulk/assign', {
-			...bulkPayload(),
-			assignee: assignee.id,
-		});
+		if (
+			!(await orToast(
+				patch('/issues/bulk/assign', {
+					...bulkPayload(),
+					assignee: assignee.id,
+				})
+			))
+		)
+			return;
 		table.resetSelection();
 		refresh();
 		toast({
@@ -731,7 +746,8 @@ export function provideBacklogWorkspace(): BacklogWorkspaceContext {
 
 	const bulkMoveToNextSprint = async () => {
 		const count = selectedCount.value;
-		await visit('post', '/issues/bulk/next-sprint', bulkPayload());
+		if (!(await orToast(post('/issues/bulk/next-sprint', bulkPayload()))))
+			return;
 		table.resetSelection();
 		refresh();
 		toast({
@@ -822,45 +838,30 @@ export function useBacklogWorkspace(): BacklogWorkspaceContext {
 		<div class="flex flex-col gap-3 p-4">
 			<FilterRail />
 
-			<!-- Tabs are real visits: href + server (component-level `navigation`
-			     is required alongside per-item `server`), each carrying the same
-			     partial-reload prop list as the filter watcher. Counts come back
-			     from the server on every reload. Each href is built from
-			     `tabHref()`, NOT a bare `?tab=` literal: `preserve-state` keeps
-			     `ctx.filters` alive across the visit, so if the href dropped the
-			     filter query keys the server would render an unfiltered page
-			     while the (unchanged) filter chips kept claiming the old
-			     filters still applied. -->
-			<BbTabs
+			<!-- The sprint filter: one value over one table, so a radio group
+			     with the tabs look (a tablist would promise panels). `ctx.tab` is
+			     the `?tab=` query (useRouteQuery): a pick is a partial-reload visit
+			     with the filters' prop list, keeping the other query keys. -->
+			<BbRadioGroup
 				v-model="ctx.tab.value"
 				compact
+				hide-legend
 				:items="[
 					{
 						value: 'backlog',
 						label: `Backlog · ${ctx.tabCounts.value.backlog}`,
-						href: tabHref('backlog'),
-						server: true,
-						only: ['issues', 'tabCounts'],
 					},
 					{
 						value: 'current',
 						label: `Current sprint · ${ctx.tabCounts.value.current}`,
-						href: tabHref('current'),
-						server: true,
-						only: ['issues', 'tabCounts'],
 					},
 					{
 						value: 'done',
 						label: `Done · ${ctx.tabCounts.value.done}`,
-						href: tabHref('done'),
-						server: true,
-						only: ['issues', 'tabCounts'],
 					},
 				]"
-				navigation
-				preserve-scroll
-				preserve-state
-				replace
+				legend="Sprint"
+				variant="pill"
 			/>
 
 			<!-- No dependencies/items-fn: `issues` is a page prop, and selection
@@ -997,14 +998,12 @@ import {
 	BbIcon,
 	BbButton,
 	BbPagination,
+	BbRadioGroup,
 	BbTable,
-	BbTabs,
 	BbTextInput,
 } from 'bitboss-ui';
-import qs from 'query-string';
 import PageShell from '@/components/layout/PageShell.vue';
-import { useQuery } from '@/composables/inertia-helpers/useQuery';
-import { provideBacklogWorkspace, type SprintTab } from './context';
+import { provideBacklogWorkspace } from './context';
 import AssigneeCell from './AssigneeCell.vue';
 import EditableTitleCell from './EditableTitleCell.vue';
 import EstimateCell from './EstimateCell.vue';
@@ -1018,13 +1017,6 @@ import type { Issue } from '@/types';
 
 const ctx = provideBacklogWorkspace();
 
-// Merge `tab` into the *current* query instead of replacing it: `useQuery()`
-// reads the live URL, which already carries every filter `useQueryObject`
-// mirrored there, so switching tabs keeps `search`/`status`/`priority`/
-// `assignee` intact instead of silently resetting the results to unfiltered.
-const tabHref = (tab: SprintTab): string =>
-	`/sprints/24?${qs.stringify({ ...useQuery(), tab }, { arrayFormat: 'comma' })}`;
-
 // 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>({
@@ -1778,23 +1770,23 @@ const longDate = (value: string) =>
   ingested rows is the choke point for every arrival path. The comment above
   it ships with the recipe on purpose: this is the autosave bug everyone writes
   once.
-- **The `visit()` helper is the promise-wrapped router-visit pattern** from
+- **`usePromiseRouter` is the promise-wrapped router-visit pattern** from
   the records workspace: it turns Inertia's `onSuccess`/`onError` callbacks
   into a promise so `persistField` and every discrete action stay `async`
   functions — identical call sites to the Vue/Nuxt recipes. Field saves
   reload only `['issues']` (the hottest path on the page); discrete and bulk
   actions reload `tabCounts` too, because they move issues between tabs.
-- **One watcher for filters, one visit mechanism for tabs.**
+- **One watcher for filters, one query ref for the tab.**
   `useQueryObject(..., { only: ['issues', 'tabCounts'] })` over a URL-shaped
-  projection of `filters` is the entire filter-to-URL wiring; `BbTabs`'
-  `href` + `server: true` items (with the required component-level
-  `navigation`) make tab switches real partial visits with the same `only`
-  list — one source of server truth, reached two ways. Each `href` is built
-  by `tabHref()`, which merges `tab` into the current query rather than
-  replacing it — `href: '/sprints/24?tab=backlog'` alone would drop every
-  active filter, and because `preserve-state` keeps this page instance (and
-  `ctx.filters`) alive across the visit, the chips would keep showing the
-  old filters as active over an unfiltered result set.
+  projection of `filters` is the
+  entire filter-to-URL wiring; the tab is `useRouteQuery('tab', …)` with
+  the same `only: ['issues', 'tabCounts']`, so a pick is a
+  partial-reloaded visit too — one source of server truth, reached two
+  ways. `useRouteQuery` writes `tab` into the current query rather than
+  replacing it, so the active filters ride along (`preserve-state` keeps
+  this page instance and `ctx.filters` alive across the visit, and a
+  dropped filter key would leave the chips claiming filters the result no
+  longer has).
 - **Bulk actions carry the full select-all-across-pages payload**
   (`ids`/`all`/`unselected`) — never just an enumerated id list that
   silently drops rows outside the current page.

package/dist/ai/recipes/inertia/layout-scaffold.md

@@ -514,6 +514,11 @@ menu while free space sits unused in the middle. Give the trail
 `shrink-0` to its siblings so they stay content-sized — the same contract
 the `BbBreadcrumbs` guide documents for exactly this row.
 
+**The page owns one `<h1>`.** When the topbar's breadcrumb is the visible
+title, the page still names itself: put `<h1 class="sr-only">Invoices</h1>`
+first in the page body, so a screen reader's heading list starts with the
+page, not with a section.
+
 ```vue
 <template>
 	<PageShell>
@@ -530,7 +535,8 @@ the `BbBreadcrumbs` guide documents for exactly this row.
 			</div>
 		</template>
 
-		<!-- default slot: the page body -->
+		<!-- default slot: the page body, its one h1 first -->
+		<h1 class="sr-only">Invoices</h1>
 		<!-- The shipped `--highlighted` tint already marks the current row;
          `row-class` is how this page says WHY it is current (the open peek)
          and how you override the look. See the BbTable guide's Row highlight
@@ -711,9 +717,12 @@ from the app entry (`import '@/components/layout/workspace-surfaces.css'` in
 }
 .plain-link:hover,
 .plain-link:focus-visible {
-	outline: none;
 	text-decoration-color: currentColor;
 }
+/* BbBaseButton draws a transparent outline: the keyboard focus colours it. */
+.plain-link:focus-visible {
+	outline-color: var(--bb-ring);
+}
 
 .row-danger {
 	background: color-mix(in oklab, var(--bb-danger) 6%, var(--bb-panel));
@@ -781,5 +790,7 @@ scrolling away" symptom.
 
 The `#sidebar` slot **is** the drawer. Putting a `BbOffCanvas` inside it gives
 you two stacked drawers with two close buttons. Pick one: the PageShell stack
-for in-page detail, or a standalone `BbOffCanvas` for chrome that is not about
-the current page (mobile nav, global filters).
+for a record whose detail fits the narrow column (it does not cover the page,
+and moving between records stays smooth), or a standalone `BbOffCanvas` for a
+detail that needs more room (a wide form, a table, a long editor) and for
+chrome that is not about the current page (mobile nav, global filters).