bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/guides/inertia-helpers.md

@@ -0,0 +1,1394 @@
+---
+title: Inertia Helpers
+summary: App-side toolkit for Laravel + Inertia apps — typed page props, lazy props, URL-driven filters, paginated/selection page contexts, promise forms, and navigation guards that pair with bitboss-ui pages.
+---
+
+# Inertia Helpers
+
+A curated toolkit of composables for **Laravel + Inertia (Vue 3)** apps built
+on bitboss-ui. These are _app-side_ code: copy the ones you need into your
+project (conventionally `src/composables/`) — they are not exported by the
+`bitboss-ui` package. The [Inertia recipes](../recipes/inertia/crud-listing-page.md)
+assume this toolkit.
+
+Why it exists: in Inertia there is no client data layer — data arrives as
+**page props** and changes through **visits**. These helpers give that model
+a clean, typed API so pages stay thin: props read through one surface,
+filters live in the URL, paginated data and selection are shared through
+keyed contexts instead of prop drilling, and forms return promises that
+bitboss-ui buttons and dialogs can await.
+
+Dependencies: `@inertiajs/vue3`, `@vueuse/core`, `query-string`, and
+`object-code` (powering the `isEqual` hash-comparison utility). A few tiny
+utilities are assumed under `@/utils` and defined below.
+
+## Shared types and utilities
+
+```ts
+// src/types/index.ts — the Laravel paginator shape and base page props
+export type PaginatedResponse<T> = {
+	data: T[];
+	meta: {
+		total: number;
+		per_page: number;
+		current_page: number;
+		last_page: number;
+	};
+};
+
+export type BasePageProps = {
+	[key: string]: unknown;
+};
+```
+
+```ts
+// src/utils/index.ts — micro-utilities the helpers share
+import { hash } from 'object-code';
+
+export const isNil = (value: unknown): value is null | undefined =>
+	value === null || value === undefined;
+
+export const isNotNil = <T>(value: T | null | undefined): value is T =>
+	!isNil(value);
+
+export const isEmpty = (value: unknown): boolean =>
+	isNil(value) || value === '' || (Array.isArray(value) && value.length === 0);
+
+export const noop = (): void => undefined;
+
+/** Deep equality by structural hash — cheap and dependency-light. */
+export const isEqual = (a: unknown, b: unknown): boolean => hash(a) === hash(b);
+
+export const isPlainObject = (
+	value: unknown
+): value is Record<string, unknown> =>
+	typeof value === 'object' &&
+	value !== null &&
+	Object.getPrototypeOf(value) === Object.prototype;
+```
+
+---
+
+## Page props
+
+### useProp / useOptionalProp
+
+Typed, reactive access to a page prop by path. `useProp` throws when the
+path is missing (a controller contract violation should fail loudly);
+`useOptionalProp` returns `undefined` instead.
+
+```ts
+// src/composables/useProp.ts
+import { usePage } from '@inertiajs/vue3';
+import { computed, type ComputedRef } from 'vue';
+
+const walk = <T>(
+	source: unknown,
+	path: string[]
+): { found: boolean; value: T | undefined } => {
+	let current: unknown = source;
+	for (const segment of path) {
+		if (
+			current === null ||
+			typeof current !== 'object' ||
+			!(segment in current)
+		) {
+			return { found: false, value: undefined };
+		}
+		current = (current as Record<string, unknown>)[segment];
+	}
+	return { found: true, value: current as T };
+};
+
+const toPath = (propPath: string | string[]): string[] =>
+	typeof propPath === 'string' ? propPath.split('.') : propPath;
+
+/** Reactive page prop by path. Throws when the path is not present. */
+export const useProp = <T>(propPath: string | string[]): ComputedRef<T> => {
+	const page = usePage();
+	const path = toPath(propPath);
+
+	return computed(() => {
+		const { found, value } = walk<T>(page.props, path);
+		if (!found) {
+			throw new Error(`Page prop "${path.join('.')}" is missing.`);
+		}
+		return value as T;
+	});
+};
+
+/** Like useProp, but resolves to `undefined` when the path is missing. */
+export const useOptionalProp = <T>(
+	propPath: string | string[]
+): ComputedRef<T | undefined> => {
+	const page = usePage();
+	const path = toPath(propPath);
+
+	return computed(() => walk<T>(page.props, path).value);
+};
+```
+
+### useLazyProp
+
+Reads a prop the server marked lazy (`Inertia::lazy()` / `optional()`).
+The returned `value` is self-loading: the first template or computed that
+reads it triggers a partial reload (`only: [propName]`) and the ref updates
+when the data lands. `loading`/`loaded`/`error` expose the fetch state;
+`execute()` forces the load imperatively.
+
+```ts
+// src/composables/useLazyProp.ts
+import { isEqual, isNil, isNotNil } from '@/utils';
+import { router, usePage } from '@inertiajs/vue3';
+import type { Ref } from 'vue';
+import { customRef, onBeforeUnmount, readonly, ref, watch } from 'vue';
+
+export type UseLazyPropOptions = {
+	/** Keep the last non-nil value across visits that reset the prop. Default true. */
+	cache?: boolean;
+	headers?: Record<string, string>;
+};
+
+export function useLazyProp<T>(
+	propName: string,
+	initialValue?: T,
+	options: UseLazyPropOptions = {}
+): {
+	value: Ref<T | undefined>;
+	loaded: Readonly<Ref<boolean>>;
+	loading: Readonly<Ref<boolean>>;
+	error: Readonly<Ref<Error | null>>;
+	execute: () => Promise<void>;
+} {
+	const page = usePage<{ [key: string]: T | undefined }>();
+	const { cache = true } = options;
+	const loading = ref(false);
+	const loaded = ref(page.props[propName] !== undefined);
+	const error = ref<Error | null>(null);
+	let inFlightPromise: Promise<void> | null = null;
+	let isUnmounted = false;
+	let cached = page.props[propName];
+
+	onBeforeUnmount(() => {
+		isUnmounted = true;
+	});
+
+	const loadProp = (onSuccess: () => void): Promise<void> => {
+		if (inFlightPromise) return inFlightPromise;
+
+		error.value = null;
+
+		inFlightPromise = new Promise<void>((resolve) => {
+			router.reload({
+				only: [propName],
+				replace: true,
+				headers: options.headers,
+				onStart: () => {
+					loading.value = true;
+				},
+				onSuccess: () => {
+					if (!isUnmounted) {
+						loaded.value = true;
+						cached = page.props[propName];
+						onSuccess();
+					}
+				},
+				onError: (errors) => {
+					if (!isUnmounted) {
+						error.value =
+							errors instanceof Error
+								? errors
+								: new Error(`Failed to load lazy prop "${propName}"`);
+					}
+				},
+				onFinish: () => {
+					if (!isUnmounted) {
+						loading.value = false;
+					}
+					inFlightPromise = null;
+					resolve();
+				},
+			});
+		});
+
+		return inFlightPromise;
+	};
+
+	/** Self-loading ref: reading it while the prop is absent starts the fetch. */
+	const value = customRef<T | undefined>((track, trigger) => ({
+		get() {
+			track();
+			const isMissing = page.props[propName] === undefined;
+
+			if (isMissing && !loaded.value && !loading.value) {
+				loading.value = true;
+				void loadProp(trigger);
+			}
+
+			if (isMissing && !loaded.value) {
+				return initialValue;
+			}
+			if (cache && cached !== undefined) {
+				return cached;
+			}
+			return page.props[propName];
+		},
+		set() {
+			throw new Error(`Lazy prop "${propName}" is read-only.`);
+		},
+	}));
+
+	const execute = () => loadProp(noopTrigger);
+
+	watch(
+		() => page.props[propName],
+		(newVal, oldVal) => {
+			if (isUnmounted) return;
+			// Persist shape changes into the cache…
+			if (isNotNil(newVal) && !isEqual(newVal, oldVal) && cache) {
+				cached = newVal;
+			}
+			// …reset state when a navigation clears the prop (uncached mode)…
+			if (isNil(newVal) && isNotNil(oldVal) && !cache) {
+				loaded.value = false;
+				loading.value = false;
+				error.value = null;
+			} else if (isNotNil(newVal) && isNil(oldVal)) {
+				// …and mark loaded when the value first arrives.
+				loaded.value = true;
+				loading.value = false;
+				error.value = null;
+			}
+		}
+	);
+
+	return {
+		value,
+		loaded: readonly(loaded),
+		loading: readonly(loading),
+		error: readonly(error),
+		execute,
+	};
+}
+
+const noopTrigger = () => undefined;
+```
+
+Gotchas:
+
+- Inertia partial reloads only target **top-level** props — you cannot lazy
+  load `stats.revenue`, only `stats`.
+- Filter navigations reset lazy props server-side; with `cache: true`
+  (default) the last value keeps rendering while the fresh one loads.
+
+### useLazyPropGetter
+
+Adapts a lazy prop into an **async getter** — exactly the items-provider
+shape `BbSelect` / `BbSelectPopover` / `BbCheckboxGroup` accept. The prop
+loads on first demand (e.g. when the select opens) instead of inflating the
+initial page load.
+
+```ts
+// src/composables/useLazyPropGetter.ts
+import {
+	useLazyProp,
+	type UseLazyPropOptions,
+} from '@/composables/useLazyProp';
+import { isNil } from '@/utils';
+import type { Ref } from 'vue';
+
+export function useLazyPropGetter<T, U = T>(
+	propName: string,
+	formatter?: (value: T) => U,
+	options?: UseLazyPropOptions
+): {
+	getter: () => Promise<U>;
+	loaded: Readonly<Ref<boolean>>;
+	loading: Readonly<Ref<boolean>>;
+} {
+	const { value, loaded, loading, execute } = useLazyProp<T>(
+		propName,
+		undefined,
+		options
+	);
+
+	const getter = async (): Promise<U> => {
+		if (!loaded.value) {
+			await execute();
+		}
+		if (isNil(value.value)) {
+			throw new Error(`Could not load lazy prop "${propName}"`);
+		}
+		if (isNil(formatter)) return value.value as unknown as U;
+		return formatter(value.value);
+	};
+
+	return { getter, loaded, loading };
+}
+```
+
+```vue
+<!-- The controller shares `roles` as a lazy prop; the select loads it on open. -->
+<script setup lang="ts">
+const { getter: fetchRoles } = useLazyPropGetter<Role[]>('roles');
+</script>
+
+<template>
+	<BbSelect
+		v-model="role"
+		item-text="name"
+		item-value="id"
+		:items="fetchRoles"
+		label="Role"
+	/>
+</template>
+```
+
+---
+
+## URL state
+
+In Inertia the URL is the only client state that survives a visit — filters,
+page numbers and sort orders belong there, not in refs that reset on
+navigation.
+
+### useQuery
+
+Parses the current page URL's query string into an object. Snapshot, not
+reactive — used by the writers below.
+
+```ts
+// src/composables/useQuery.ts
+import { usePage } from '@inertiajs/vue3';
+import qs, { type StringifyOptions } from 'query-string';
+
+export const useQuery = ({
+	arrayFormat = 'comma',
+}: { arrayFormat?: StringifyOptions['arrayFormat'] } = {}): Record<
+	string,
+	unknown
+> => {
+	const { url } = usePage();
+	const [, queryString] = url.split('?');
+	if (!queryString) return {};
+	return qs.parse(decodeURIComponent(queryString), {
+		arrayFormat,
+		decode: true,
+	});
+};
+```
+
+### useRouteQuery
+
+A single query parameter as a **writable ref**. Reading tracks the current
+URL; writing merges the parameter and performs a (replace) visit, so the
+server re-renders with the new value. Writing the current value is a no-op —
+safe to sync from server responses without visit loops.
+
+```ts
+// src/composables/useRouteQuery.ts
+import { router, usePage } from '@inertiajs/vue3';
+import qs from 'query-string';
+import { computed, type WritableComputedRef } from 'vue';
+
+type Options<T> = {
+	/** Parse the raw string (e.g. `Number`). Defaults to identity. */
+	transform?: (value: string) => T;
+	preserveScroll?: boolean;
+	preserveState?: boolean;
+};
+
+export function useRouteQuery<T = string>(
+	key: string,
+	defaultValue: string,
+	options: Options<T> = {}
+): WritableComputedRef<T> {
+	const {
+		transform = (value) => value as unknown as T,
+		preserveScroll = true,
+		preserveState = true,
+	} = options;
+	const page = usePage();
+
+	const readRaw = (): string => {
+		const [, queryString = ''] = page.url.split('?');
+		const raw = qs.parse(queryString)[key];
+		const single = Array.isArray(raw) ? raw[0] : raw;
+		return single != null ? String(single) : defaultValue;
+	};
+
+	return computed<T>({
+		get: () => transform(readRaw()),
+		set: (next) => {
+			const nextRaw = String(next);
+			if (nextRaw === readRaw()) return;
+
+			const [path, queryString = ''] = page.url.split('?');
+			const query = qs.parse(queryString);
+			if (nextRaw === defaultValue) {
+				delete query[key]; // keep URLs clean at the default
+			} else {
+				query[key] = nextRaw;
+			}
+			const stringified = qs.stringify(query);
+			router.visit(stringified ? `${path}?${stringified}` : path, {
+				preserveScroll,
+				preserveState,
+				replace: true,
+			});
+		},
+	});
+}
+```
+
+### useQueryObject
+
+The **filter engine**: watch a filters object and mirror its non-empty
+values into the query string with an Inertia visit per change. Keys it has
+seen are cleaned up when they empty out; the `page` parameter resets on
+every filter change so results are never hidden on an out-of-range page.
+
+```ts
+// src/composables/useQueryObject.ts
+import { useQuery } from '@/composables/useQuery';
+import { isEmpty, isNil } from '@/utils';
+import { router, usePage } from '@inertiajs/vue3';
+import qs, { type StringifyOptions } from 'query-string';
+import { toValue, watch, type MaybeRefOrGetter } from 'vue';
+
+type Options<T> = {
+	transform?: (value: Partial<T>) => Partial<T>;
+	/** Reset the `page` parameter on change. Default true. */
+	resetPage?: boolean;
+	/** Additional query keys removed whenever the object changes. */
+	resetKeys?: string[];
+	/** Inertia partial reload prop names (supports reactive getter). */
+	only?: MaybeRefOrGetter<string[]>;
+	/**
+	 * When it resolves to `false` the watcher keeps tracking keys but skips
+	 * the navigation — use it when another owner performs the visit during a
+	 * programmatic transition, to avoid competing self-cancelling requests.
+	 */
+	shouldNavigate?: MaybeRefOrGetter<boolean>;
+	arrayFormat?: StringifyOptions['arrayFormat'];
+	preserveState?: boolean;
+	preserveScroll?: boolean;
+	replace?: boolean;
+};
+
+export function useQueryObject<T extends Record<string, unknown>>(
+	object: MaybeRefOrGetter<T>,
+	options: Options<T> = {}
+): void {
+	const {
+		transform,
+		resetPage = true,
+		resetKeys = [],
+		preserveState = true,
+		preserveScroll = true,
+		replace = true,
+		only: onlyOption = [],
+		shouldNavigate = true,
+		arrayFormat = 'comma',
+	} = options;
+
+	const filterValidValues = (obj: T): Partial<T> => {
+		const filtered: Partial<T> = {};
+		Object.entries(obj).forEach(([key, val]) => {
+			if (!isNil(val) && val !== '') {
+				(filtered as Record<string, unknown>)[key] = val;
+			}
+		});
+		return filtered;
+	};
+
+	/** Every key this composable has ever managed, for stable URL cleanup. */
+	const seenKeys = new Set<string>(Object.keys(toValue(object) ?? {}));
+
+	watch(
+		() => toValue(object),
+		(newObject) => {
+			if (!newObject) return;
+
+			Object.keys(newObject).forEach((key) => {
+				if (!seenKeys.has(key)) {
+					console.warn(
+						`[useQueryObject] Key "${key}" appeared after initialization. ` +
+							`Initialize the object with all possible keys for stable URL cleanup.`
+					);
+				}
+				seenKeys.add(key);
+			});
+
+			const validValues = filterValidValues(newObject);
+			const transformedValues = transform
+				? transform(validValues)
+				: validValues;
+
+			// Start from the existing query to preserve keys owned elsewhere.
+			const existingQuery = useQuery({ arrayFormat });
+			seenKeys.forEach((key) => delete existingQuery[key]);
+			if (resetPage) delete existingQuery.page;
+			resetKeys.forEach((key) => delete existingQuery[key]);
+
+			Object.entries(transformedValues).forEach(([key, val]) => {
+				if (!isEmpty(val)) existingQuery[key] = val;
+			});
+
+			const stringified = qs.stringify(existingQuery, { arrayFormat });
+			const newUrl = stringified
+				? [window.location.pathname, stringified].join('?')
+				: window.location.pathname;
+
+			if (newUrl === usePage().url) return;
+			if (!toValue(shouldNavigate)) return;
+
+			router.visit(newUrl, {
+				preserveState,
+				preserveScroll,
+				only: toValue(onlyOption),
+				replace,
+			});
+		},
+		{ deep: true, flush: 'sync' }
+	);
+}
+```
+
+```ts
+// A listing page's whole filter wiring:
+const filters = reactive({ search: '', status: null as string | null });
+useQueryObject(filters, { only: ['invoices'] });
+// Bind BbTextInput / BbSelectPopover to `filters.*` — every change becomes a
+// partial reload and the server re-renders the `invoices` prop.
+```
+
+---
+
+## Shared page data (contexts)
+
+These share **server data** across a page by string key — the Inertia
+counterpart of the component-state context
+[`useBbTableContext`](../composables/useBbTableContext.md). Rule of thumb:
+`useBbTableContext` mirrors what the _table widget_ is doing (selection,
+sort, highlight); these contexts own what the _server sent_ (items, meta)
+and survive being read from any component on the page. First caller creates
+the context, later callers join it — no provider component required.
+
+### usePaginatedResponseContext
+
+Wraps a Laravel paginated prop (`PaginatedResponse<T>`) into a shared
+context: `items` (editable until next navigation), `totalItems`,
+`totalPages`, and URL-backed `page` / `perPage` refs. On every successful
+visit the context re-syncs from the fresh prop.
+
+```ts
+// src/composables/usePaginatedResponseContext.ts
+import { useRouteQuery } from '@/composables/useRouteQuery';
+import type { PaginatedResponse } from '@/types';
+import { isNotNil } from '@/utils';
+import { router, usePage } from '@inertiajs/vue3';
+import { injectLocal, provideLocal } from '@vueuse/core';
+import { computed, onScopeDispose, ref, type ComputedRef, type Ref } from 'vue';
+
+export type PaginatedResponseContext<T> = {
+	totalItems: ComputedRef<number>;
+	perPage: Ref<number>;
+	page: Ref<number>;
+	totalPages: ComputedRef<number>;
+	/** Current page items. Writable for optimistic edits; resets on navigation. */
+	items: Ref<T[]>;
+};
+
+const toContextKey = (key: string): string => `${key}:paginatedResponse`;
+
+export const usePaginatedResponseContext = <T = object>(
+	dataKey: string
+): PaginatedResponseContext<T> => {
+	const existing = injectLocal<PaginatedResponseContext<T> | null>(
+		toContextKey(dataKey),
+		null
+	);
+	if (isNotNil(existing)) return existing;
+
+	const paginated = computed(
+		() => usePage<{ [key: string]: PaginatedResponse<T> }>().props[dataKey]
+	);
+
+	const items = ref<T[]>(paginated.value.data ?? []) as Ref<T[]>;
+	const totalItems = computed(() => paginated.value.meta.total ?? 0);
+	const totalPages = computed(() => paginated.value.meta.last_page ?? 0);
+
+	const perPage = useRouteQuery(
+		'per_page',
+		`${paginated.value.meta.per_page ?? 10}`,
+		{
+			transform: Number,
+		}
+	);
+	const page = useRouteQuery(
+		'page',
+		`${paginated.value.meta.current_page ?? 1}`,
+		{
+			transform: Number,
+		}
+	);
+
+	const context: PaginatedResponseContext<T> = {
+		totalItems,
+		perPage,
+		page,
+		totalPages,
+		items,
+	};
+
+	// Re-sync from the fresh prop after every successful visit.
+	const unbind = router.on('success', (event) => {
+		const props = event.detail.page.props as {
+			[key: string]: PaginatedResponse<T> | undefined;
+		};
+		const data = props[dataKey];
+		if (!data) return;
+		items.value = data.data ?? [];
+		page.value = data.meta?.current_page ?? 1;
+		perPage.value = data.meta?.per_page ?? 10;
+	});
+	onScopeDispose(unbind);
+
+	provideLocal(toContextKey(dataKey), context);
+
+	return context;
+};
+```
+
+### useTableSelectionContext
+
+Shared selection state by key, in server terms: `selected` and `unselected`
+item lists plus the `all` flag ("select-all across pages" semantics — when
+`all` is true, `selected` does **not** enumerate every row; the server
+combines `all` + `unselected` instead). Bind these to `BbTable`'s
+`v-model`, `v-model:unselected-items` and `v-model:select-all`.
+
+```ts
+// src/composables/useTableSelectionContext.ts
+import { isNotNil } from '@/utils';
+import { injectLocal, provideLocal } from '@vueuse/core';
+import { ref, type Ref } from 'vue';
+
+export type TableSelectionContext<U> = {
+	/** The select-all checkbox state. Does not enumerate items. */
+	all: Ref<boolean>;
+	/** Items manually selected. NOT the full list when `all` is true. */
+	selected: Ref<U[]>;
+	/** Items manually unselected while `all` is true. */
+	unselected: Ref<U[]>;
+	resetSelection: () => void;
+};
+
+const toSelectionKey = (key: string): string => `${key}:selection`;
+
+/** Bare selection state, no provide/inject — for callers that own sharing. */
+export const createSelectionContext = <
+	U = unknown,
+>(): TableSelectionContext<U> => {
+	const all = ref(false);
+	const selected = ref<U[]>([]) as Ref<U[]>;
+	const unselected = ref<U[]>([]) as Ref<U[]>;
+
+	const resetSelection = (): void => {
+		all.value = false;
+		selected.value = [];
+		unselected.value = [];
+	};
+
+	return { all, selected, unselected, resetSelection };
+};
+
+export const useTableSelectionContext = <U = unknown>(
+	key: string
+): TableSelectionContext<U> => {
+	const selectionKey = toSelectionKey(key);
+	const existing = injectLocal<TableSelectionContext<U> | null>(
+		selectionKey,
+		null
+	);
+	if (isNotNil(existing)) return existing;
+
+	const context = createSelectionContext<U>();
+	provideLocal(selectionKey, context);
+	return context;
+};
+```
+
+### useTableContext
+
+The composition of the two above — one keyed context carrying a listing
+page's whole server-data spine: items, pagination, and selection. This is
+what the [Inertia CRUD listing recipe](../recipes/inertia/crud-listing-page.md)
+builds on.
+
+```ts
+// src/composables/useTableContext.ts
+import {
+	usePaginatedResponseContext,
+	type PaginatedResponseContext,
+} from '@/composables/usePaginatedResponseContext';
+import {
+	useTableSelectionContext,
+	type TableSelectionContext,
+} from '@/composables/useTableSelectionContext';
+import { isNotNil } from '@/utils';
+import { injectLocal, provideLocal } from '@vueuse/core';
+
+export type TableContext<T, U> = TableSelectionContext<U> &
+	PaginatedResponseContext<T>;
+
+const toTableKey = (key: string): string => `${key}:table`;
+
+export const useTableContext = <T = object, U = T>(
+	dataKey: string
+): TableContext<T, U> => {
+	const existing = injectLocal<TableContext<T, U> | null>(
+		toTableKey(dataKey),
+		null
+	);
+	if (isNotNil(existing)) return existing;
+
+	const context: TableContext<T, U> = {
+		...useTableSelectionContext<U>(dataKey),
+		...usePaginatedResponseContext<T>(dataKey),
+	};
+
+	provideLocal(toTableKey(dataKey), context);
+	return context;
+};
+```
+
+Gotchas:
+
+- The key is a rendezvous string (use the page-prop name, e.g.
+  `'invoices'`). Like the library's table context, a typo doesn't error —
+  it silently creates a second, orphan context.
+- Each composite context provides under a namespaced key
+  (`invoices:table`, `invoices:selection`, `invoices:paginatedResponse`),
+  so the pieces can also be joined individually.
+
+---
+
+## Forms and guards
+
+### usePromiseForm
+
+Inertia's `useForm` with **promise semantics**: `post/put/patch/remove`
+resolve on success and reject on validation errors, so you can `await` a
+submit, chain a toast, or hand the promise to a `BbButton` `@click` /
+`useConfirm` `onClick` for automatic busy states. `form` is the underlying
+Inertia form — `form.errors`, `form.isDirty`, `form.reset()` all work.
+
+**Declare the draft shape as a `type` alias, not an `interface`.** The generic
+is constrained to `Record<string, FormValue>` (what Inertia can serialize), and
+TypeScript gives an implicit index signature to object _type aliases_ only — an
+`interface` never satisfies that constraint, however form-encodable its fields
+are. The same applies to any nested shape (a line-item row, say). It is a
+TypeScript quirk, not a statement about your data.
+
+```ts
+// src/composables/usePromiseForm.ts
+import { useLoading } from '@/composables/useLoading';
+import {
+	useForm,
+	type InertiaForm,
+	type InertiaFormProps,
+} from '@inertiajs/vue3';
+
+type FormValue =
+	| string
+	| number
+	| boolean
+	| null
+	| File
+	| undefined
+	| FormValue[]
+	| { [key: string]: FormValue };
+
+type Options = Parameters<InertiaFormProps<object>['get']>[1];
+
+export const usePromiseForm = <T extends Record<string, FormValue>>(
+	initialData: T
+) => {
+	// @ts-expect-error - typed as InertiaForm<T> to avoid fighting the type system
+	const form = useForm(initialData) as InertiaForm<T>;
+
+	const { fn: submit, loading: isSubmitting } = useLoading(
+		(
+			url: string,
+			method: 'get' | 'post' | 'put' | 'patch' | 'delete' = 'post',
+			options: Options = {}
+		): Promise<void> =>
+			new Promise<void>((resolve, reject) => {
+				const { onFinish: userOnFinish, ...visitOptions } = options;
+
+				form[method](url, {
+					...visitOptions,
+					onSuccess: () => resolve(),
+					onError: (errors: unknown) => reject(errors),
+					onFinish: (
+						...args: Parameters<NonNullable<NonNullable<Options>['onFinish']>>
+					) => {
+						userOnFinish?.(...args);
+						// A non-Inertia response (e.g. a 423 entity lock or a 419
+						// CSRF mismatch) fires neither onSuccess nor onError, only
+						// onFinish. Settle here so isSubmitting is released instead
+						// of hanging the form forever. No-op once already settled.
+						reject(new Error('Inertia visit did not return a valid response.'));
+					},
+				});
+			})
+	);
+
+	const post = (url: string, options?: Options) => submit(url, 'post', options);
+	const put = (url: string, options?: Options) => submit(url, 'put', options);
+	const patch = (url: string, options?: Options) =>
+		submit(url, 'patch', options);
+	const remove = (url: string, options?: Options) =>
+		submit(url, 'delete', options);
+
+	return { form, submit, post, put, patch, remove, isSubmitting };
+};
+```
+
+### useHasChanged
+
+Deep dirty-checking against a snapshot baseline — for edit screens whose
+state is not a single Inertia form (multiple forms, ad-hoc refs). For a
+single `usePromiseForm`, prefer the built-in `form.isDirty`.
+
+```ts
+// src/composables/useHasChanged.ts
+import { isEqual } from '@/utils';
+import { computed, ref, toValue, type WatchSource } from 'vue';
+
+export function useHasChanged<T extends WatchSource<unknown>[]>(
+	dependencies: T
+) {
+	// Deep-copied baselines avoid reference entanglement with live state.
+	const baselineValues = ref<unknown[]>(
+		dependencies.map((dep) => structuredClone(toValue(dep)))
+	);
+
+	/** Re-baseline (call after a successful save). */
+	const takeSnapshot = (): void => {
+		baselineValues.value = dependencies.map((dep) =>
+			structuredClone(toValue(dep))
+		);
+	};
+
+	const hasChanged = computed(() =>
+		dependencies.some(
+			(dep, index) =>
+				!isEqual(structuredClone(toValue(dep)), baselineValues.value[index])
+		)
+	);
+
+	return { hasChanged, takeSnapshot };
+}
+```
+
+### useConfirmOnRouteLeave
+
+A dirty-state navigation guard: intercepts Inertia visits and asks through
+[`useConfirm`](../composables/useConfirm.md) before leaving. Requires
+`<BbConfirm />` mounted in the app root. Server redirects after a
+whitelisted action carry the `X-Whitelisted-Action` header so a saving
+visit's redirect is never blocked by its own guard.
+
+```ts
+// src/composables/useConfirmOnRouteLeave.ts
+import { router } from '@inertiajs/vue3';
+import { useConfirm } from 'bitboss-ui';
+import { onUnmounted, toValue, type MaybeRefOrGetter } from 'vue';
+
+type Visit = {
+	url: URL;
+	headers?: Record<string, string>;
+	[key: string]: unknown;
+};
+
+type Options = {
+	/** URLs that bypass the dialog (e.g. the form's own submit target). */
+	whitelist?: MaybeRefOrGetter<string[]>;
+	/** Disable the guard (bind to `!hasChanged` / `!form.isDirty`). */
+	disabled?: MaybeRefOrGetter<boolean>;
+	/** Runs synchronously before the dialog; return false to allow the visit. */
+	onBefore?: (visit: Visit) => unknown;
+	/** Runs after the user confirms leaving. */
+	onLeave?: (visit: Visit) => unknown;
+	title?: string;
+	text?: string;
+};
+
+const normalizeUrl = (value: string | URL) => {
+	const url = new URL(value.toString(), window.location.origin);
+	return url.pathname.replace(/\/+$/, '') || '/';
+};
+
+const getHeaderValue = (
+	headers: Record<string, string> | undefined,
+	headerName: string
+) => {
+	if (!headers) return undefined;
+	const normalized = headerName.toLowerCase();
+	const matched = Object.keys(headers).find(
+		(key) => key.toLowerCase() === normalized
+	);
+	return matched ? headers[matched] : undefined;
+};
+
+export const WHITELIST_HEADER = 'X-Whitelisted-Action';
+
+export const useConfirmOnRouteLeave = ({
+	whitelist = [],
+	disabled = false,
+	onBefore = () => true,
+	onLeave = () => true,
+	title = 'Unsaved changes',
+	text = 'You have unsaved changes. Leave without saving?',
+}: Options = {}) => {
+	// Captured in setup so the built-in dialog is owned by the guarded page:
+	// if the page unmounts anyway, the dialog dismisses itself quietly.
+	const { confirm } = useConfirm();
+	let bypassNextVisit = false;
+
+	const unbind = router.on('before', (event) => {
+		const visit = event.detail.visit as Visit;
+
+		if (bypassNextVisit) {
+			bypassNextVisit = false;
+			return;
+		}
+
+		if (toValue(disabled)) return;
+		if (getHeaderValue(visit.headers, WHITELIST_HEADER) === '1') return;
+
+		const nextPath = normalizeUrl(visit.url.href);
+		if (nextPath === normalizeUrl(window.location.href)) return;
+		if (toValue(whitelist).map(normalizeUrl).includes(nextPath)) return;
+
+		if (onBefore(visit) === false) return false;
+		event.preventDefault();
+
+		void (async () => {
+			const confirmed = await confirm({
+				variant: 'destructive',
+				title,
+				text,
+				yes: 'Discard changes',
+				no: 'Keep editing',
+			});
+			if (!confirmed) return;
+
+			await onLeave(visit);
+			bypassNextVisit = true;
+			router.visit(visit.url, {
+				...(visit as Parameters<typeof router.visit>[1]),
+				headers: { ...(visit.headers ?? {}), [WHITELIST_HEADER]: '1' },
+			});
+		})();
+	});
+
+	onUnmounted(unbind);
+};
+```
+
+---
+
+## Async utilities
+
+### useLoading
+
+Wraps any async function with a concurrent-safe `loading` flag (a counter,
+so overlapping calls don't flicker it off early).
+
+```ts
+// src/composables/useLoading.ts
+import { computed, ref } from 'vue';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const useLoading = <T extends (...args: any[]) => any>(fn: T) => {
+	const counter = ref(0);
+	const loading = computed(() => counter.value > 0);
+
+	const fnWithLoading = async (...args: Parameters<T>) => {
+		counter.value++;
+		try {
+			return await fn(...args);
+		} finally {
+			counter.value--;
+		}
+	};
+
+	return { loading, fn: fnWithLoading };
+};
+```
+
+### useAsyncFn
+
+A full async-state engine for **non-Inertia** requests (JSON endpoints,
+exports): `data` / `error` / `loading` / `aborted` state, an `AbortSignal`
+per run, auto-abort of the previous run on re-execute, and abort on
+unmount.
+
+```ts
+// src/composables/useAsyncFn.ts
+import { isPlainObject } from '@/utils';
+import {
+	onBeforeMount,
+	onBeforeUnmount,
+	shallowRef,
+	type ShallowRef,
+} from 'vue';
+
+type BaseOptions = {
+	/** Run on mount. Default true. */
+	immediate?: boolean;
+	/** Swallow AbortError instead of exposing it on `error`. Default true. */
+	abortSilently?: boolean;
+};
+
+type AsyncFnParams = {
+	setError: (err: string) => void;
+	setErrorData: (err: Record<string, unknown>) => void;
+	signal: AbortSignal;
+};
+
+type AsyncFnReturn<D> = {
+	data: ShallowRef<D>;
+	error: ShallowRef<Error | null>;
+	errorData: ShallowRef<Record<string, unknown> | null>;
+	loading: ShallowRef<boolean>;
+	aborted: ShallowRef<boolean>;
+	execute: () => Promise<D>;
+	stop: () => void;
+};
+
+type AsyncFn<T> = (params: AsyncFnParams) => Promise<T> | T;
+
+export function useAsyncFn<T>(
+	fn: AsyncFn<T>,
+	options: BaseOptions & { defaultValue: T }
+): AsyncFnReturn<T>;
+export function useAsyncFn<T>(
+	fn: AsyncFn<T>,
+	options?: BaseOptions & { defaultValue?: undefined }
+): AsyncFnReturn<T | null>;
+export function useAsyncFn<T>(
+	fn: AsyncFn<T>,
+	{
+		immediate = true,
+		abortSilently = true,
+		defaultValue,
+	}: BaseOptions & { defaultValue?: T } = {}
+) {
+	const data = shallowRef(defaultValue ?? null);
+	const error = shallowRef<Error | null>(null);
+	const errorData = shallowRef<Record<string, unknown> | null>(null);
+	const loading = shallowRef(false);
+	const aborted = shallowRef(false);
+	let abortController: AbortController | null = null;
+
+	const setError = (err: string) => {
+		error.value = new Error(err);
+	};
+	const setErrorData = (err: Record<string, unknown>) => {
+		errorData.value = err;
+	};
+
+	const isAbortError = (err: unknown): boolean =>
+		err instanceof DOMException && err.name === 'AbortError';
+
+	const execute = async () => {
+		abortController?.abort();
+		abortController = new AbortController();
+		loading.value = true;
+		aborted.value = false;
+		error.value = null;
+		errorData.value = null;
+
+		try {
+			data.value = await fn({
+				setError,
+				setErrorData,
+				signal: abortController.signal,
+			});
+		} catch (err) {
+			if (isAbortError(err)) {
+				aborted.value = true;
+				if (!abortSilently) error.value = err as Error;
+			} else if (err instanceof Error) {
+				error.value = err;
+			} else if (typeof err === 'string') {
+				error.value = new Error(err);
+			} else if (isPlainObject(err)) {
+				// Laravel validation bag: surface the first message.
+				const firstKey = Object.keys(err)[0];
+				error.value = new Error(String(err[firstKey]));
+			}
+		} finally {
+			loading.value = false;
+		}
+
+		return data.value;
+	};
+
+	if (immediate) onBeforeMount(execute);
+
+	const stop = () => {
+		abortController?.abort();
+		abortController = null;
+	};
+	onBeforeUnmount(stop);
+
+	return { data, error, errorData, loading, aborted, execute, stop };
+}
+```
+
+### useResourceContext
+
+"Given an id, keep its resource loaded": re-fetches whenever the id
+changes, resets to `null` when the id clears, exposes `loading` and
+`refresh()`. The natural engine for a detail sidebar or peek panel — feed
+it the highlighted row's id.
+
+```ts
+// src/composables/useResourceContext.ts
+import { useLoading } from '@/composables/useLoading';
+import { noop } from '@/utils';
+import { ref, toValue, watch, type MaybeRefOrGetter, type Ref } from 'vue';
+
+type UseResourceContextOptions<T, ID> = {
+	immediate?: boolean;
+	disabled?: MaybeRefOrGetter<boolean>;
+	onReset?: () => void | Promise<void>;
+	onSuccess?: (data: T, resourceId: ID) => void | Promise<void>;
+	onError?: (error: unknown, resourceId: ID) => void | Promise<void>;
+	onFinish?: (resourceId: ID) => void | Promise<void>;
+};
+
+export function useResourceContext<T, ID = string>(
+	id: MaybeRefOrGetter<ID | null | undefined>,
+	fn: (id: ID) => Promise<T>,
+	options: UseResourceContextOptions<T, ID> = {}
+) {
+	const data = ref<T | null>(null) as Ref<T | null>;
+	const {
+		immediate = true,
+		disabled = false,
+		onSuccess = noop,
+		onError = (error: unknown) => {
+			console.error('Failed to fetch resource:', error);
+		},
+		onReset = noop,
+		onFinish = noop,
+	} = options;
+
+	const { loading, fn: fetch } = useLoading((resourceId: ID) => fn(resourceId));
+
+	const load = async (resourceId: ID) => {
+		try {
+			const result = await fetch(resourceId);
+			data.value = result;
+			await onSuccess(result, resourceId);
+		} catch (error) {
+			data.value = null;
+			await onError(error, resourceId);
+		} finally {
+			await onFinish(resourceId);
+		}
+	};
+
+	watch(
+		() => ({ resourceId: toValue(id), isDisabled: toValue(disabled) }),
+		async ({ resourceId, isDisabled }) => {
+			if (!resourceId) {
+				data.value = null;
+				await onReset();
+				return;
+			}
+			// Keep already-loaded data while disabled.
+			if (isDisabled) return;
+			await load(resourceId as ID);
+		},
+		{ immediate }
+	);
+
+	const refresh = async () => {
+		const currentId = toValue(id);
+		if (toValue(disabled) || !currentId) return;
+		await load(currentId as ID);
+	};
+
+	return { data, loading, refresh };
+}
+```
+
+---
+
+## UI utilities
+
+### useDeleteCmd
+
+Fires a callback on Delete/Backspace — unless an input, textarea, select or
+contenteditable is focused. Pairs with table selection: select rows, hit
+Delete, dispatch the same confirm-guarded bulk action as the button.
+
+```ts
+// src/composables/useDeleteCmd.ts
+import { useMagicKeys, whenever } from '@vueuse/core';
+import { toValue, type MaybeRefOrGetter } from 'vue';
+
+export type UseDeleteCmdOptions = {
+	disabled?: MaybeRefOrGetter<boolean>;
+};
+
+const isInteractiveElementFocused = (): boolean => {
+	const active = document.activeElement;
+	if (!active) return false;
+	const tag = active.tagName.toLowerCase();
+	if (tag === 'input' || tag === 'textarea' || tag === 'select') return true;
+	return active.getAttribute('contenteditable') === 'true';
+};
+
+export function useDeleteCmd(
+	onDelete: () => void,
+	options: UseDeleteCmdOptions = {}
+) {
+	const keys = useMagicKeys();
+
+	const handleDelete = () => {
+		if (isInteractiveElementFocused()) return;
+		if (!toValue(options.disabled)) onDelete();
+	};
+
+	whenever(keys['delete'], handleDelete);
+	whenever(keys['backspace'], handleDelete);
+}
+```
+
+### useScreenSizes
+
+Shared reactive breakpoints aligned with Tailwind `md`/`lg` — one window
+listener for the whole app via `createSharedComposable`.
+
+```ts
+// src/composables/useScreenSizes.ts
+import { useWindowSize } from '@vueuse/core';
+import { createSharedComposable } from '@vueuse/shared';
+import { computed } from 'vue';
+
+/** Tailwind md breakpoint (px). Mobile when width < 768. */
+export const SCREEN_BREAKPOINT_MD = 768;
+/** Tailwind lg breakpoint (px). Tablet when 768 <= width < 1024. */
+export const SCREEN_BREAKPOINT_LG = 1024;
+
+const useScreenSizesImpl = () => {
+	const { width } = useWindowSize();
+
+	const isMobile = computed(() => width.value < SCREEN_BREAKPOINT_MD);
+	const isTablet = computed(
+		() =>
+			width.value >= SCREEN_BREAKPOINT_MD && width.value < SCREEN_BREAKPOINT_LG
+	);
+	const isDesktop = computed(() => width.value >= SCREEN_BREAKPOINT_LG);
+
+	return { width, isMobile, isTablet, isDesktop };
+};
+
+export const useScreenSizes = createSharedComposable(useScreenSizesImpl);
+```
+
+### useIndexById
+
+Index an item list by key for O(1) lookups — e.g. mapping the ids in a
+selection context back to full rows for a bulk-action payload.
+
+```ts
+// src/composables/useIndexById.ts
+import { computed, unref, type MaybeRef } from 'vue';
+
+type Options<TItem> = {
+	items: MaybeRef<readonly TItem[]>;
+	/** The item property holding the id (e.g. 'id'). */
+	key: keyof TItem & string;
+};
+
+export const useIndexById = <TItem>({ items, key }: Options<TItem>) => {
+	const data = computed<Record<string, TItem>>(() => {
+		const map: Record<string, TItem> = {};
+		for (const item of unref(items)) {
+			map[String(item[key])] = item;
+		}
+		return map;
+	});
+
+	const get = (id: string | number): TItem | undefined =>
+		data.value[String(id)];
+
+	return { data, get };
+};
+```
+
+### useUntil
+
+A ref that flips once, the first time a condition becomes true, then stops
+watching — for one-shot reveals ("has ever loaded", onboarding hints).
+
+```ts
+// src/composables/useUntil.ts
+import { noop } from '@/utils';
+import { ref, toValue, watch, type MaybeRefOrGetter } from 'vue';
+
+type Options<T, U> = {
+	initialValue?: T;
+	nextValue?: U;
+	onChange?: VoidFunction;
+};
+
+export const useUntil = <T = boolean, U = boolean>(
+	condition: MaybeRefOrGetter<boolean>,
+	{
+		initialValue = false as T,
+		nextValue = true as U,
+		onChange = noop,
+	}: Options<T, U> = {}
+) => {
+	const value = ref<T | U>(initialValue);
+
+	const stopWatching = watch(
+		() => toValue(condition),
+		(met) => {
+			if (met) {
+				onChange();
+				value.value = nextValue;
+				stopWatching();
+			}
+		}
+	);
+
+	return value;
+};
+```
+
+---
+
+## Related
+
+- [Recipe: CRUD Listing Page (Inertia)](../recipes/inertia/crud-listing-page.md) —
+  these helpers assembled into a full page.
+- [Recipe: Record Form (Inertia)](../recipes/inertia/record-form.md) —
+  `usePromiseForm` + `useConfirmOnRouteLeave` in practice.
+- [Page Shell](./page-shell.md) and
+  [Floating Bottom Panel](./floating-bottom-panel.md) — the app-side layout
+  components these pages sit in.
+- [useBbTableContext](../composables/useBbTableContext.md) — the library's
+  by-id context for table _widget_ state; complements, not replaces, the
+  keyed data contexts here.