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

package/dist/ai/helpers/inertia/useQueryObject.ts

@@ -1,95 +1,98 @@
 // inertia-helpers/useQueryObject.ts
 // requires: npm i query-string
-import { useQuery } from './useQuery';
-import { isEmpty, isNil } from './utils';
-import { router, usePage } from '@inertiajs/vue3';
-import qs, { type StringifyOptions } from 'query-string';
+import {
+	QUERY_ARRAY_FORMAT,
+	currentUrl,
+	parseQuery,
+	visitUrl,
+	withQuery,
+} from './useQuery';
+import type { VisitOptions } from '@inertiajs/core';
+import qs from 'query-string';
 import { onScopeDispose, toValue, watch, type MaybeRefOrGetter } from 'vue';
 
+/** A server visit's options; the URL, method and data are the helper's. */
+type ServerVisitOptions = Omit<VisitOptions, 'method' | 'data' | 'preserveUrl'>;
+/** A URL-only write (`server: false`) has no request to configure. */
+type ClientVisitOptions = Pick<
+	VisitOptions,
+	'preserveState' | 'preserveScroll' | 'replace'
+>;
+
 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. */
+	/**
+	 * Query keys removed on every change. Default `['page']`, so a filter
+	 * change never strands the list on a page past its new end. Passing it
+	 * REPLACES the default: name `page` too when it should still reset.
+	 */
 	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.
+	 * While it resolves to `true`, changes are tracked but no visit is sent.
+	 * When it goes back to `false`, the object's current state is sent once,
+	 * if the URL does not already hold it. See the guide for when to use it.
 	 */
-	shouldNavigate?: MaybeRefOrGetter<boolean>;
+	paused?: MaybeRefOrGetter<boolean>;
 	/**
 	 * Keys whose changes wait this many ms before the visit, e.g. a search
 	 * box: `{ search: 300 }`. A change to any other key visits at once and
 	 * carries the waiting value with it, so nothing typed is lost.
 	 */
 	debounce?: Partial<Record<keyof T & string, number>>;
-	arrayFormat?: StringifyOptions['arrayFormat'];
-	preserveState?: boolean;
-	preserveScroll?: boolean;
-	replace?: boolean;
-};
+} & (
+	| {
+			/** Default `true`: every change is an Inertia visit. */
+			server?: true;
+			/** Merged over `{ preserveState, preserveScroll, replace: true }`. */
+			visitOptions?: MaybeRefOrGetter<ServerVisitOptions>;
+	  }
+	| {
+			/** `false` writes the URL with no request (`router.replace` / `push`). */
+			server: false;
+			visitOptions?: MaybeRefOrGetter<ClientVisitOptions>;
+	  }
+);
 
 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,
+		resetKeys = ['page'],
+		paused = false,
 		debounce = {},
-		arrayFormat = 'comma',
+		server = true,
+		visitOptions,
 	} = 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) ?? {}));
 
-	const navigate = (newObject: T) => {
-		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;
-		});
+	/** A query in one canonical form, so encoding and key order never count. */
+	const canonical = (url: string) =>
+		qs.stringify(parseQuery(url), { arrayFormat: QUERY_ARRAY_FORMAT });
 
-		const stringified = qs.stringify(existingQuery, { arrayFormat });
-		const newUrl = stringified
-			? [window.location.pathname, stringified].join('?')
-			: window.location.pathname;
+	const navigate = (newObject: T) => {
+		if (toValue(paused)) return;
 
-		if (newUrl === usePage().url) return;
-		if (!toValue(shouldNavigate)) return;
+		// Only the reset keys and the keys this object owns change; every
+		// other parameter (a tab, a sort) stays as it is.
+		const changes: Record<string, unknown> = {};
+		resetKeys.forEach((key) => (changes[key] = null));
+		seenKeys.forEach((key) => (changes[key] = newObject[key]));
+		const from = currentUrl();
+		const url = withQuery(from, changes);
+		if (canonical(url) === canonical(from)) return;
 
-		router.visit(newUrl, {
-			preserveState,
-			preserveScroll,
-			only: toValue(onlyOption),
-			replace,
-		});
+		visitUrl(
+			url,
+			{
+				preserveState: true,
+				preserveScroll: true,
+				replace: true,
+				...toValue(visitOptions),
+			},
+			server
+		);
 	};
 
 	/** Each key's value as last seen, to tell which keys a change touched. */
@@ -102,8 +105,8 @@ export function useQueryObject<T extends Record<string, unknown>>(
 	onScopeDispose(() => clearTimeout(pending));
 
 	watch(
-		() => toValue(object),
-		(newObject) => {
+		[() => toValue(object), () => toValue(paused)],
+		([newObject, isPaused], [, wasPaused]) => {
 			if (!newObject) return;
 
 			Object.keys(newObject).forEach((key) => {
@@ -122,12 +125,15 @@ export function useQueryObject<T extends Record<string, unknown>>(
 			);
 			lastSeen = now;
 			clearTimeout(pending);
+			if (isPaused) return;
+			// Resuming sends what changed while paused, without waiting.
+			const resumed = wasPaused && !isPaused;
 			const waits = changed.map(
 				(key) => (debounce as Record<string, number | undefined>)[key] ?? 0
 			);
 			// Only debounced keys changed: wait for the typing to settle, then
 			// visit with whatever the object holds by then.
-			if (changed.length && waits.every((ms) => ms > 0)) {
+			if (!resumed && changed.length && waits.every((ms) => ms > 0)) {
 				pending = setTimeout(
 					() => navigate(toValue(object)),
 					Math.max(...waits)
@@ -141,7 +147,8 @@ export function useQueryObject<T extends Record<string, unknown>>(
 		 * into one watcher run, so a `clearFilters()` that blanks three keys
 		 * fires ONE visit instead of three (measured: 3 writes → 3 runs under
 		 * `sync`, 1 under the default). The two it saves used to self-cancel,
-		 * but they were still sent.
+		 * but they were still sent. Watching `paused` in the same source means
+		 * resuming and the change that comes with it are one run, one visit.
 		 *
 		 * This does NOT make typing cheap on its own — one visit per settled
 		 * keystroke is still one visit per keystroke. `debounce` is for that.

package/dist/ai/helpers/inertia/useResourceContext.ts

@@ -1,7 +1,14 @@
 // inertia-helpers/useResourceContext.ts
 import { useLoading } from './useLoading';
 import { noop } from './utils';
-import { ref, toValue, watch, type MaybeRefOrGetter, type Ref } from 'vue';
+import {
+	onScopeDispose,
+	ref,
+	toValue,
+	watch,
+	type MaybeRefOrGetter,
+	type Ref,
+} from 'vue';
 
 type UseResourceContextOptions<T, ID> = {
 	immediate?: boolean;
@@ -14,7 +21,8 @@ type UseResourceContextOptions<T, ID> = {
 
 export function useResourceContext<T, ID = string>(
 	id: MaybeRefOrGetter<ID | null | undefined>,
-	fn: (id: ID) => Promise<T>,
+	/** `signal` aborts when the load goes stale: pass it to `fetch` / axios. */
+	fn: (id: ID, signal: AbortSignal) => Promise<T>,
 	options: UseResourceContextOptions<T, ID> = {}
 ) {
 	const data = ref<T | null>(null) as Ref<T | null>;
@@ -28,31 +36,69 @@ export function useResourceContext<T, ID = string>(
 		onFinish = noop,
 	} = options;
 
-	const { loading, fn: fetch } = useLoading((resourceId: ID) => fn(resourceId));
+	const { loading, fn: fetch } = useLoading(
+		(resourceId: ID, signal: AbortSignal) => fn(resourceId, signal)
+	);
+
+	// Each load takes a ticket; a newer load, an id change or the scope's end
+	// makes older tickets stale, and a stale response is dropped (no data, no
+	// callbacks): a slow answer for the row the user left never lands. Going
+	// stale also aborts its request.
+	let ticket = 0;
+	let controller: AbortController | null = null;
+	const stale = () => {
+		ticket++;
+		controller?.abort();
+	};
+	let loadedId: ID | null = null;
+	const clear = () => {
+		stale();
+		data.value = null;
+		loadedId = null;
+	};
+	onScopeDispose(stale);
 
 	const load = async (resourceId: ID) => {
+		stale();
+		const own = ticket;
+		controller = new AbortController();
+		const outcome = await fetch(resourceId, controller.signal).then(
+			(result) => ({ ok: true as const, result }),
+			(error: unknown) => ({ ok: false as const, error })
+		);
+		if (own !== ticket) return;
 		try {
-			const result = await fetch(resourceId);
-			data.value = result;
-			await onSuccess(result, resourceId);
-		} catch (error) {
-			data.value = null;
-			await onError(error, resourceId);
+			if (outcome.ok) {
+				data.value = outcome.result;
+				loadedId = resourceId;
+				// Outside the fetch's catch: a throwing onSuccess is the
+				// caller's bug, not a failed fetch.
+				await onSuccess(outcome.result, resourceId);
+			} else {
+				clear();
+				await onError(outcome.error, resourceId);
+			}
 		} finally {
 			await onFinish(resourceId);
 		}
 	};
 
+	// Per-item sources: a re-run that yields the same id and flag (a partial
+	// reload handing a new row object with the same id) does not refetch.
 	watch(
-		() => ({ resourceId: toValue(id), isDisabled: toValue(disabled) }),
-		async ({ resourceId, isDisabled }) => {
+		[() => toValue(id), () => toValue(disabled)],
+		async ([resourceId, isDisabled]) => {
 			if (!resourceId) {
-				data.value = null;
+				clear();
 				await options.onReset?.();
 				return;
 			}
-			// Keep already-loaded data while disabled.
-			if (isDisabled) return;
+			// Keep already-loaded data while disabled, but only for the id it
+			// was loaded for: never show row a's resource under row b.
+			if (isDisabled) {
+				if (resourceId !== loadedId) clear();
+				return;
+			}
 			await load(resourceId as ID);
 		},
 		{ immediate }

package/dist/ai/helpers/inertia/useRouteQuery.ts

@@ -1,6 +1,7 @@
 // inertia-helpers/useRouteQuery.ts
 // requires: npm i query-string
-import { router, usePage } from '@inertiajs/vue3';
+import { currentUrl, splitUrl, visitUrl, withQuery } from './useQuery';
+import type { VisitOptions } from '@inertiajs/core';
 import qs from 'query-string';
 import {
 	computed,
@@ -12,8 +13,15 @@ import {
 type Options<T> = {
 	/** Parse the raw string (e.g. `Number`). Defaults to identity. */
 	transform?: (value: string) => T;
-	preserveScroll?: boolean;
-	preserveState?: boolean;
+	/** `false` writes the URL with no request. Default `true`. */
+	server?: boolean;
+	/**
+	 * Merged over `{ preserveState, preserveScroll, replace: true }`. With
+	 * `server: false` only those three apply.
+	 */
+	visitOptions?: MaybeRefOrGetter<
+		Omit<VisitOptions, 'method' | 'data' | 'preserveUrl'>
+	>;
 };
 
 export function useRouteQuery<T = string>(
@@ -24,37 +32,34 @@ export function useRouteQuery<T = string>(
 ): WritableComputedRef<T> {
 	const {
 		transform = (value) => value as unknown as T,
-		preserveScroll = true,
-		preserveState = true,
+		server = true,
+		visitOptions,
 	} = 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;
+		const raw = qs.parse(splitUrl(currentUrl()).query)[key];
+		// A repeated key reads its last value, as PHP does.
+		const single = Array.isArray(raw) ? raw.at(-1) : raw;
 		return single != null ? String(single) : toValue(defaultValue);
 	};
 
 	return computed<T>({
 		get: () => transform(readRaw()),
 		set: (next) => {
-			const nextRaw = String(next);
+			// `null` / `undefined` mean "no value": the key leaves the URL.
+			const nextRaw = next == null ? toValue(defaultValue) : String(next);
 			if (nextRaw === readRaw()) return;
-
-			const [path = '', queryString = ''] = page.url.split('?');
-			const query = qs.parse(queryString);
-			if (nextRaw === toValue(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,
-			});
+			const value = nextRaw === toValue(defaultValue) ? null : nextRaw; // keep URLs clean at the default
+			visitUrl(
+				withQuery(currentUrl(), { [key]: value }),
+				{
+					preserveScroll: true,
+					preserveState: true,
+					replace: true,
+					...toValue(visitOptions),
+				},
+				server
+			);
 		},
 	});
 }

package/dist/ai/helpers/inertia/useScreenSizes.ts

@@ -1,21 +1,23 @@
 // inertia-helpers/useScreenSizes.ts
 import { createSharedComposable, useWindowSize } from '@vueuse/core';
+import { useMobile } from 'bitboss-ui';
 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. */
+/** Tailwind lg breakpoint (px). Tablet from the library's mobile cut up to here. */
 export const SCREEN_BREAKPOINT_LG = 1024;
 
 const useScreenSizesImpl = () => {
 	const { width } = useWindowSize();
+	// The library's own signal (below the plugin's `mobileMaxWidth`), so a page
+	// and the components on it never disagree about "mobile".
+	const { isMobile } = useMobile();
 
-	const isMobile = computed(() => width.value < SCREEN_BREAKPOINT_MD);
 	const isTablet = computed(
-		() =>
-			width.value >= SCREEN_BREAKPOINT_MD && width.value < SCREEN_BREAKPOINT_LG
+		() => !isMobile.value && width.value < SCREEN_BREAKPOINT_LG
+	);
+	const isDesktop = computed(
+		() => !isMobile.value && width.value >= SCREEN_BREAKPOINT_LG
 	);
-	const isDesktop = computed(() => width.value >= SCREEN_BREAKPOINT_LG);
 
 	return { width, isMobile, isTablet, isDesktop };
 };

package/dist/ai/helpers/inertia/useTableContext.ts

@@ -2,6 +2,7 @@
 import {
 	usePaginatedResponseContext,
 	type PaginatedResponseContext,
+	type PaginatedResponseOptions,
 } from './usePaginatedResponseContext';
 import {
 	useTableSelectionContext,
@@ -16,7 +17,9 @@ export type TableContext<T, U> = TableSelectionContext<U> &
 const toTableKey = (key: string): string => `${key}:table`;
 
 export const useTableContext = <T = object, U = T>(
-	dataKey: string
+	dataKey: string,
+	/** For the paginated half: query keys and pager visit options. */
+	options?: PaginatedResponseOptions
 ): TableContext<T, U> => {
 	const existing = injectLocal<TableContext<T, U> | null>(
 		toTableKey(dataKey),
@@ -26,7 +29,7 @@ export const useTableContext = <T = object, U = T>(
 
 	const context: TableContext<T, U> = {
 		...useTableSelectionContext<U>(dataKey),
-		...usePaginatedResponseContext<T>(dataKey),
+		...usePaginatedResponseContext<T>(dataKey, options),
 	};
 
 	provideLocal(toTableKey(dataKey), context);

package/dist/ai/helpers/inertia/utils.ts

@@ -22,3 +22,17 @@ export const isPlainObject = (
 	typeof value === 'object' &&
 	value !== null &&
 	Object.getPrototypeOf(value) === Object.prototype;
+
+/**
+ * Deep copy of server data (arrays and plain objects; anything else, e.g. a
+ * Date an app put there, is shared). Reads through Vue proxies, which
+ * `structuredClone` refuses.
+ */
+export const cloneDeep = <T>(value: T): T =>
+	(Array.isArray(value)
+		? value.map(cloneDeep)
+		: isPlainObject(value)
+			? Object.fromEntries(
+					Object.entries(value).map(([key, item]) => [key, cloneDeep(item)])
+				)
+			: value) as T;

package/dist/ai/manifest/index.json

@@ -1,8 +1,8 @@
 {
 	"schemaVersion": 1,
 	"library": "bitboss-ui",
-	"version": "3.0.0-beta.64",
-	"generatedAt": "2026-10-26T22:25:55.188Z",
+	"version": "3.0.0-beta.65",
+	"generatedAt": "2026-10-27T14:11:46.011Z",
 	"about": "The bitboss-ui API for agents: open components/<Name>.json for one component (every prop, event, slot, v-model, pt part and state, and the public types its API uses; one member per line; a row or pt part written { name, common: true } is whole once in common.json, read it once). components/<Name>.tree.json has its component tree and CSS internals; files.removed the old names. The machine file with everything in one place is ../components.json.",
 	"reading": {
 		"components[]": "one row per component; description = its first sentence. Its API file is files.component with <Name> = name; its components/<Name>.tree.json (component tree, css classes, CSS custom properties) exists unless the row says tree: false.",

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

@@ -351,7 +351,7 @@ export function provideApprovalsInbox(): ApprovalsInboxContext {
 	});
 	// The search waits for typing to settle; every other filter visits at once.
 	useQueryObject(filters, {
-		only: [...RELOAD_PROPS],
+		visitOptions: { only: [...RELOAD_PROPS] },
 		debounce: { search: 300 },
 	});
 

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

@@ -495,7 +495,7 @@ export function provideBacklogWorkspace(): BacklogWorkspaceContext {
 					: String(filters.assignee.id ?? 'none'),
 		}),
 		// The search waits for typing to settle; every other filter visits at once.
-		{ only: [...RELOAD_PROPS], debounce: { search: 300 } }
+		{ visitOptions: { only: [...RELOAD_PROPS] }, debounce: { search: 300 } }
 	);
 
 	const hasActiveFilters = computed(

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

@@ -334,7 +334,7 @@ export function provideOwnershipAtlas(): OwnershipAtlasContext {
 	});
 	// The search waits for typing to settle; every other filter visits at once.
 	useQueryObject(filters, {
-		only: [...RELOAD_PROPS],
+		visitOptions: { only: [...RELOAD_PROPS] },
 		debounce: { search: 300 },
 	});
 

package/dist/ai/recipes/inertia/records-workspace.md

@@ -346,7 +346,7 @@ export function provideInvoicesWorkspace(): InvoicesWorkspaceContext {
 	});
 	// The search waits for typing to settle; every other filter visits at once.
 	useQueryObject(filters, {
-		only: [...RELOAD_PROPS],
+		visitOptions: { only: [...RELOAD_PROPS] },
 		debounce: { search: 300 },
 	});
 

package/dist/ai/recipes/inertia/upload-center.md

@@ -361,7 +361,7 @@ export function provideUploadCenter(): UploadCenterContext {
 	});
 	// The search waits for typing to settle; every other filter visits at once.
 	useQueryObject(filters, {
-		only: [...RELOAD_PROPS],
+		visitOptions: { only: [...RELOAD_PROPS] },
 		debounce: { search: 300 },
 	});
 

package/dist/ai/source/BbSelectPopover.md

@@ -988,8 +988,32 @@ const typeahead = useTypeahead<BaseOption<Item>>({
 	},
 	locale: () => config.locale,
 });
+/**
+ * A key typed while a keyboard open is still placing focus belongs to the
+ * search field it is about to reach: it waits for the open, then is written
+ * there as an input, so typing straight after Enter is not lost (MW-106).
+ */
+const typeIntoSearchAfterOpen = async (event: KeyboardEvent) => {
+	event.preventDefault();
+	await afterKeyboardOpen();
+	const input = searchInput.value;
+	if (!(input instanceof HTMLInputElement)) return;
+	if (document.activeElement !== input) return;
+	const end = input.value.length;
+	input.setRangeText(
+		event.key,
+		input.selectionStart ?? end,
+		input.selectionEnd ?? end,
+		'end'
+	);
+	input.dispatchEvent(new Event('input', { bubbles: true }));
+};
 const onTypeaheadKey = async (event: KeyboardEvent) => {
-	if (computedAllowWriting.value || !isPrintableTypeaheadKey(event)) return;
+	if (!isPrintableTypeaheadKey(event)) return;
+	if (computedAllowWriting.value) {
+		if (keyboardOpen) await typeIntoSearchAfterOpen(event);
+		return;
+	}
 	if (!canProcessKeyboardBindings.value) return;
 	event.preventDefault();
 	if (!shown.value) {