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

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

@@ -1,16 +1,22 @@
 // inertia-helpers/usePaginatedResponseContext.ts
-import { useRouteQuery } from './useRouteQuery';
+// requires: npm i query-string
+import { currentUrl, visitUrl, withQuery } from './useQuery';
 import type { PaginatedResponse } from './types';
-import { isNotNil } from './utils';
-import type { PageProps } from '@inertiajs/core';
-import { usePage } from '@inertiajs/vue3';
+import { cloneDeep, isEqual, isNotNil } from './utils';
+import type { PageProps, VisitOptions } from '@inertiajs/core';
+import { router, usePage } from '@inertiajs/vue3';
 import { injectLocal, provideLocal } from '@vueuse/core';
 import {
 	computed,
+	onMounted,
+	onScopeDispose,
 	ref,
+	shallowRef,
+	toValue,
 	watch,
 	watchEffect,
 	type ComputedRef,
+	type MaybeRefOrGetter,
 	type Ref,
 } from 'vue';
 
@@ -19,10 +25,21 @@ export type PaginatedResponseContext<T> = {
 	perPage: Ref<number>;
 	page: Ref<number>;
 	totalPages: ComputedRef<number>;
-	/** Current page items. Writable for optimistic edits; resets on navigation. */
+	/** Current page items, a deep copy: edit it freely; resets on a new answer. */
 	items: Ref<T[]>;
 };
 
+export type PaginatedResponseOptions = {
+	/** The query key the server reads the page from (Laravel's `pageName`). Default `'page'`. */
+	pageQueryKey?: string;
+	/** The query key the server reads the page size from. Default `'per_page'`. */
+	perPageQueryKey?: string;
+	/** Merged over `{ preserveState, preserveScroll }` and the history default (a page pushes, a size replaces). */
+	visitOptions?: MaybeRefOrGetter<
+		Omit<VisitOptions, 'method' | 'data' | 'preserveUrl'>
+	>;
+};
+
 const toContextKey = (key: string): string => `${key}:paginatedResponse`;
 
 /**
@@ -30,30 +47,40 @@ const toContextKey = (key: string): string => `${key}:paginatedResponse`;
  * fields under `meta` (a resource collection, a hand-built shape) or at the
  * top level (`->paginate()`, `->simplePaginate()`). `simplePaginate()` knows
  * no total: the count is the rows so far, and the last page is the next one
- * while a next page exists.
+ * while a next page exists, or the one before an empty page past the end.
  */
 export const readPagination = (paginated: PaginatedResponse<unknown>) => {
 	const fields = paginated.meta ?? paginated;
 	const current = fields.current_page ?? 1;
 	const perPage = fields.per_page ?? 10;
+	const rows = paginated.data?.length ?? 0;
 	const links = paginated.links as { next?: string | null } | undefined;
 	const hasNext = !!(
 		fields.next_page_url ?? (Array.isArray(links) ? null : links?.next)
 	);
+	const pastEnd = !rows && !hasNext && current > 1;
 	return {
 		current,
 		perPage,
-		lastPage: fields.last_page ?? (hasNext ? current + 1 : current),
+		lastPage:
+			fields.last_page ??
+			(hasNext ? current + 1 : pastEnd ? current - 1 : current),
 		total:
 			fields.total ??
-			(current - 1) * perPage +
-				(paginated.data?.length ?? 0) +
-				(hasNext ? 1 : 0),
+			(pastEnd ? 0 : (current - 1) * perPage + rows + (hasNext ? 1 : 0)),
 	};
 };
 
+const isCount = (value: number): boolean =>
+	Number.isInteger(value) && value > 0;
+
 export const usePaginatedResponseContext = <T = object>(
-	dataKey: string
+	dataKey: string,
+	{
+		pageQueryKey = 'page',
+		perPageQueryKey = 'per_page',
+		visitOptions,
+	}: PaginatedResponseOptions = {}
 ): PaginatedResponseContext<T> => {
 	const existing = injectLocal<PaginatedResponseContext<T> | null>(
 		toContextKey(dataKey),
@@ -72,18 +99,46 @@ export const usePaginatedResponseContext = <T = object>(
 	const inertiaPage = usePage<
 		PageProps & Record<string, PaginatedResponse<T>>
 	>();
+	// A deferred, optional or not-yet-reloaded prop reads as an empty page.
 	const paginated = computed(
-		() => inertiaPage.props[dataKey] as PaginatedResponse<T>
+		(): PaginatedResponse<T> => inertiaPage.props[dataKey] ?? { data: [] }
 	);
 
 	const pagination = computed(() => readPagination(paginated.value));
-	const items = ref<T[]>(paginated.value.data ?? []) as Ref<T[]>;
+	// A deep copy: inline edits (`v-model` on a row's field) stay off the page
+	// prop, so the "rows really changed" check below compares two things.
+	const items = ref<T[]>(cloneDeep(paginated.value.data ?? [])) as Ref<T[]>;
 	const totalItems = computed(() => pagination.value.total);
 	const totalPages = computed(() => pagination.value.lastPage);
 
-	// A new prop is a new answer (a visit, Back / Forward); a partial reload of
-	// another prop keeps this one, and the edits made to `items`.
-	watch(paginated, (fresh) => (items.value = fresh.data ?? []));
+	// Server visits in flight that ask for this prop (a pager click, a filter,
+	// `router.reload({ only: [dataKey] })`).
+	const asking = new Set<unknown>();
+	const asks = ({ only, except }: { only: string[]; except: string[] }) =>
+		only.length ? only.includes(dataKey) : !except.includes(dataKey);
+	const unbindStart = router.on('start', ({ detail: { visit } }) => {
+		if (asks(visit)) asking.add(visit);
+	});
+	const unbindFinish = router.on('finish', ({ detail: { visit } }) => {
+		asking.delete(visit);
+	});
+	onScopeDispose(() => {
+		unbindStart();
+		unbindFinish();
+	});
+
+	// A visit that asked for this prop is a new answer: fresh rows, the edits
+	// made to `items` go. Anything else that swaps the prop (`appendToProp` on
+	// another prop rebuilds them all, Back / Forward) keeps the edits unless the
+	// rows really changed. `sync`: the answer lands before its visit finishes.
+	watch(
+		paginated,
+		(fresh, old) => {
+			if (!asking.size && isEqual(fresh.data, old.data)) return;
+			items.value = cloneDeep(fresh.data ?? []);
+		},
+		{ flush: 'sync' }
+	);
 
 	// The server's default page size is what it answers a URL without
 	// `per_page`. Until such an answer arrives it is unknown (`''` matches no
@@ -92,24 +147,74 @@ export const usePaginatedResponseContext = <T = object>(
 	const defaultPerPage = ref('');
 	watchEffect(() => {
 		const [, queryString = ''] = inertiaPage.url.split('?');
-		if (!new URLSearchParams(queryString).has('per_page'))
+		if (!new URLSearchParams(queryString).has(perPageQueryKey))
 			defaultPerPage.value = `${pagination.value.perPage}`;
 	});
-	const pageQuery = useRouteQuery('page', '1');
-	const perPageQuery = useRouteQuery('per_page', defaultPerPage);
+
+	// Where the last pager write is going, while its visit is in flight: a
+	// second click before the answer builds on it ("next" twice is page 3).
+	const target = shallowRef<{ url: string; page: number; perPage: number }>();
+	const inFlight = () => {
+		const write = target.value;
+		return write?.url === currentUrl() && write.url !== inertiaPage.url
+			? write
+			: undefined;
+	};
+	const go = (to: number, size?: number, extra?: { replace: true }) => {
+		const url = withQuery(currentUrl(), {
+			[pageQueryKey]: to === 1 ? null : to,
+			...(isNotNil(size) && {
+				[perPageQueryKey]: `${size}` === defaultPerPage.value ? null : size,
+			}),
+		});
+		target.value = { url, page: to, perPage: size ?? perPage.value };
+		visitUrl(url, {
+			preserveScroll: true,
+			preserveState: true,
+			// A page is a history entry (Back goes to the previous page); a new
+			// size is a setting and replaces.
+			replace: isNotNil(size),
+			...toValue(visitOptions),
+			...extra,
+		});
+	};
 
 	// Both read the server's answer, not the URL: a clamped `?page=99`, a
 	// capped `?per_page=500` or a redirect to the bare URL shows what the
-	// server sent. Writing one visits, and only when the URL changes.
+	// server sent. Writing one visits when it changes what they show; a size
+	// starts again from page 1. Junk (0, NaN, 2.5, past a known last page) is
+	// ignored.
 	const page = computed({
-		get: () => pagination.value.current,
-		set: (next: number) => (pageQuery.value = `${next}`),
+		get: () => inFlight()?.page ?? pagination.value.current,
+		set: (next: number) => {
+			const last = (paginated.value.meta ?? paginated.value).last_page;
+			if (!isCount(next) || (isNotNil(last) && next > last)) return;
+			if (next !== page.value) go(next);
+		},
 	});
 	const perPage = computed({
-		get: () => pagination.value.perPage,
-		set: (next: number) => (perPageQuery.value = `${next}`),
+		get: () => inFlight()?.perPage ?? pagination.value.perPage,
+		set: (next: number) => {
+			if (isCount(next) && next !== perPage.value) go(1, next);
+		},
 	});
 
+	// Laravel's `paginate()` does not clamp: `?page=3` after page 3's last row
+	// went answers an empty page 3 of 2. Go to the last page, once per answer.
+	let clampedFrom = '';
+	onMounted(() =>
+		watch(
+			pagination,
+			({ current, lastPage }) => {
+				if (current <= lastPage || lastPage < 1) return;
+				if (clampedFrom === inertiaPage.url) return;
+				clampedFrom = inertiaPage.url;
+				go(lastPage, undefined, { replace: true });
+			},
+			{ immediate: true }
+		)
+	);
+
 	const context: PaginatedResponseContext<T> = {
 		totalItems,
 		perPage,

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

@@ -1,6 +1,7 @@
 // inertia-helpers/usePromiseForm.ts
 import { useLoading } from './useLoading';
 import {
+	router,
 	useForm,
 	type InertiaForm,
 	type InertiaFormProps,
@@ -18,6 +19,17 @@ type FormValue =
 
 type Options = Parameters<InertiaFormProps<object>['get']>[1];
 
+// Inertia 3's per-visit failure callbacks. Inertia 2 has none (it ignores
+// them), only the global `invalid` / `exception` events, heard below.
+type FailureCallbacks = {
+	onHttpException?: (response: { status: number }) => boolean | void;
+	onNetworkError?: (error: unknown) => boolean | void;
+};
+const onRouterEvent = (
+	name: string,
+	listener: (event: CustomEvent) => void
+): (() => void) => router.on(name as 'start', listener as never);
+
 export const usePromiseForm = <T extends Record<string, FormValue>>(
 	initialData: T
 ) => {
@@ -32,34 +44,129 @@ export const usePromiseForm = <T extends Record<string, FormValue>>(
 		): Promise<boolean> =>
 			// true: the server answered and the save went through. false: the
 			// visit was cancelled or interrupted, nothing to report. Rejects with
-			// the error bag, or for a response that is not Inertia's.
-			new Promise<boolean>((resolve, reject) => {
-				const { onFinish: userOnFinish, ...visitOptions } = options;
+			// the error bag, or for an error page / a response that is not Inertia's.
+			new Promise<boolean>((resolvePromise, rejectPromise) => {
+				const {
+					onBefore,
+					onSuccess,
+					onError,
+					onHttpException,
+					onNetworkError,
+					onFinish,
+					...visitOptions
+				} = options as NonNullable<Options> & FailureCallbacks;
+				// Visits sent with these callbacks, and how many finished: a save
+				// answered with a 409 redirect (a redirect with a #fragment) is
+				// re-sent by Inertia itself with the same callbacks, and that
+				// follow-up interrupts the first visit. The last one settles.
+				let sent = 0;
+				let finished = 0;
+				let awaitingBefore = false;
+				let failedStatus: number | null = null;
+				// Inertia 2: a non-Inertia response or a network error is a global
+				// event only, fired before the visit finishes. Heard while this
+				// promise is open (an async reload failing meanwhile counts too).
+				const unbindFailures = [
+					onRouterEvent('invalid', ({ detail }) => {
+						failedStatus = (detail as { response: { status: number } }).response
+							.status;
+					}),
+					onRouterEvent('exception', () => void (failedStatus = 0)),
+				];
+				const settle = () => {
+					unbind();
+					unbindFailures.forEach((unbindFailure) => unbindFailure());
+				};
+				const resolve = (value: boolean) => {
+					settle();
+					resolvePromise(value);
+				};
+				const reject = (error: unknown) => {
+					settle();
+					rejectPromise(error);
+				};
+				// A visit stopped before it starts (its own onBefore returning
+				// false, below, or a `before` listener that refuses it) fires no
+				// callback at all: no save, resolve false. Registered last, this
+				// listener sees what the ones before it decided.
+				const unbind = router.on('before', (event) => {
+					if (!awaitingBefore) return;
+					awaitingBefore = false;
+					if (!event.defaultPrevented) return;
+					// Held by useConfirmOnRouteLeave's dialog: "Discard changes"
+					// re-sends it with these callbacks, "Keep editing" finishes it
+					// as cancelled. Either one settles this promise.
+					if (
+						(event.detail.visit as { awaitingConfirm?: boolean })
+							.awaitingConfirm
+					)
+						return;
+					if (--sent === finished) resolve(false);
+				});
 
 				form[method](url, {
 					...visitOptions,
-					onSuccess: () => resolve(true),
-					onError: (errors: unknown) => reject(errors),
+					onBefore: (visit) => {
+						const answer = onBefore?.(visit);
+						if (answer === false) {
+							if (sent === finished) resolve(false);
+						} else {
+							sent++;
+							awaitingBefore = true;
+						}
+						return answer;
+					},
+					onSuccess: (page) => {
+						onSuccess?.(page);
+						// An error page Inertia renders (a 403 / 500 with `x-inertia`)
+						// lands like a success: it is not a save.
+						if (failedStatus === null) resolve(true);
+						else reject(new Error(`Inertia visit answered ${failedStatus}.`));
+					},
+					onError: (errors) => {
+						onError?.(errors);
+						reject(errors);
+					},
+					...({
+						onHttpException: (response) => {
+							failedStatus = response.status;
+							return onHttpException?.(response);
+						},
+						onNetworkError: (error) => {
+							failedStatus = 0;
+							return onNetworkError?.(error);
+						},
+					} satisfies FailureCallbacks),
 					onFinish: (
 						...args: Parameters<NonNullable<NonNullable<Options>['onFinish']>>
 					) => {
-						userOnFinish?.(...args);
-						// A cancelled visit (`cancel()`, a `before` listener such as
-						// useConfirmOnRouteLeave's "Keep editing") or one a newer visit
+						onFinish?.(...args);
+						finished++;
+						// A cancelled visit (`cancel()`) or one a newer visit
 						// interrupted is no failure, and no save either: it reaches
-						// only onFinish. Resolve false.
+						// only onFinish. Resolve false, unless it is Inertia's own
+						// 409 follow-up that interrupted it: that one settles.
 						const [visit] = args as unknown as [
 							{ cancelled?: boolean; interrupted?: boolean } | undefined,
 						];
 						if (visit?.cancelled || visit?.interrupted) {
-							resolve(false);
+							if (sent <= finished) resolve(false);
 							return;
 						}
 						// 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.'));
+						// CSRF mismatch) or a network error fires neither onSuccess
+						// nor onError, only onFinish. Settle here so isSubmitting is
+						// released instead of hanging the form forever. No-op once
+						// already settled.
+						if (failedStatus !== null) {
+							reject(
+								new Error('Inertia visit did not return a valid response.')
+							);
+							return;
+						}
+						// `Inertia::location()` (an external redirect after the save)
+						// fires only onFinish too, while the browser leaves.
+						resolve(true);
 					},
 				});
 			})

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

@@ -1,19 +1,141 @@
 // inertia-helpers/useQuery.ts
 // requires: npm i query-string
-import { usePage } from '@inertiajs/vue3';
+import type { VisitOptions } from '@inertiajs/core';
+import { router, usePage } from '@inertiajs/vue3';
 import qs, { type StringifyOptions } from 'query-string';
+import { shallowRef } from 'vue';
+
+/**
+ * How arrays sit in the query string, for every helper that reads or writes
+ * it: `tags=a,b`, what Spatie QueryBuilder parses. Change it here, once —
+ * a reader and a writer that disagree turn an array into a string.
+ */
+export const QUERY_ARRAY_FORMAT = 'comma';
+
+/** A URL's parts. The first `?` starts the query; a `#` ends it. */
+export const splitUrl = (url: string) => {
+	const hashAt = url.indexOf('#');
+	const hash = hashAt < 0 ? '' : url.slice(hashAt);
+	const rest = hashAt < 0 ? url : url.slice(0, hashAt);
+	const queryAt = rest.indexOf('?');
+	return queryAt < 0
+		? { path: rest, query: '', hash }
+		: { path: rest.slice(0, queryAt), query: rest.slice(queryAt + 1), hash };
+};
+
+/**
+ * The URL the last write is heading to, while its visit is in flight. Every
+ * reader and writer builds on it, so two writes before the server answers
+ * both land, and a write reads back at once. It counts only while `page.url`
+ * is still the one it was built on: any visit that lands supersedes it.
+ */
+const pending = shallowRef<{ from: string; url: string } | null>(null);
+
+/** `page.url`, or where the write in flight is taking it. */
+export const currentUrl = (): string => {
+	const { url } = usePage();
+	return pending.value?.from === url ? pending.value.url : url;
+};
+
+const decodeKey = (raw: string): string => {
+	try {
+		return decodeURIComponent(raw.replace(/\+/g, ' '));
+	} catch {
+		return raw;
+	}
+};
+
+/**
+ * `url` with `changes` written in. A nullish, empty-string or empty-array
+ * value removes its key. Every other parameter is kept as it was written, in
+ * its place: a write never re-encodes or re-orders what it does not own.
+ */
+export const withQuery = (
+	url: string,
+	changes: Record<string, unknown>
+): string => {
+	const { path, query, hash } = splitUrl(url);
+	const encoded = (key: string): string[] => {
+		const value = changes[key];
+		if (value == null || value === '') return [];
+		if (Array.isArray(value) && value.length === 0) return [];
+		return [
+			qs.stringify({ [key]: value }, { arrayFormat: QUERY_ARRAY_FORMAT }),
+		];
+	};
+	const written = new Set<string>();
+	const parts = query
+		.split('&')
+		.filter(Boolean)
+		.flatMap((part) => {
+			const key = decodeKey(part.split('=')[0] ?? '');
+			if (!(key in changes)) return [part];
+			if (written.has(key)) return [];
+			written.add(key);
+			return encoded(key);
+		});
+	Object.keys(changes)
+		.filter((key) => !written.has(key))
+		.forEach((key) => parts.push(...encoded(key)));
+	return `${path}${parts.length ? `?${parts.join('&')}` : ''}${hash}`;
+};
+
+/**
+ * Takes the page to `url`: an Inertia visit, or with `server: false` a URL
+ * write with no request. Readers see `url` from now until the visit finishes.
+ */
+export const visitUrl = (
+	url: string,
+	options: Omit<VisitOptions, 'method' | 'data' | 'preserveUrl'>,
+	server = true
+): void => {
+	const from = usePage().url;
+	const write = { from, url };
+	pending.value = write;
+	const settle = () => {
+		if (pending.value === write) pending.value = null;
+	};
+	if (server) {
+		let started = false;
+		router.visit(url, {
+			...options,
+			onStart: (visit) => {
+				started = true;
+				options.onStart?.(visit);
+			},
+			onFinish: (visit) => {
+				settle();
+				options.onFinish?.(visit);
+			},
+		});
+		// A visit a `before` listener refused never starts, and never finishes.
+		if (!started) settle();
+		return;
+	}
+	const { preserveState, preserveScroll, replace } = options;
+	const client = { url, preserveState, preserveScroll, onFinish: settle };
+	if (replace) router.replace(client);
+	else router.push(client);
+};
+
+/** The query of `url` as an object, the way the server reads it. */
+export const parseQuery = (
+	url: string,
+	arrayFormat: StringifyOptions['arrayFormat'] = QUERY_ARRAY_FORMAT
+): Record<string, unknown> => {
+	const { query } = splitUrl(url);
+	if (!query) return {};
+	// `qs.parse` decodes once. An encoded comma separates too: Laravel's pager
+	// links write `a%2Cb`, which PHP decodes to `a,b` before Spatie splits it.
+	return qs.parse(
+		arrayFormat === 'comma' ? query.replace(/%2C/gi, ',') : query,
+		{ arrayFormat }
+	);
+};
 
 export const useQuery = ({
-	arrayFormat = 'comma',
+	arrayFormat = QUERY_ARRAY_FORMAT,
 }: { arrayFormat?: StringifyOptions['arrayFormat'] } = {}): Record<
 	string,
 	unknown
-> => {
-	const { url } = usePage();
-	const [, queryString] = url.split('?');
-	if (!queryString) return {};
-	return qs.parse(decodeURIComponent(queryString), {
-		arrayFormat,
-		decode: true,
-	});
-};
+> => parseQuery(currentUrl(), arrayFormat);