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

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

@@ -1,4 +1,5 @@
 // inertia-helpers/useConfirmOnRouteLeave.ts
+import { useHelperMessages } from './messages';
 import { router } from '@inertiajs/vue3';
 import { useConfirm, type BbConfirmMessage } from 'bitboss-ui';
 import { onScopeDispose, toValue, type MaybeRefOrGetter } from 'vue';
@@ -12,7 +13,11 @@ type Visit = {
 };
 
 type Options = {
-	/** URLs that bypass the dialog (e.g. the form's own submit target). */
+	/**
+	 * Submit targets that bypass the dialog (the form's own save). Only a
+	 * submit (POST / PUT / PATCH / DELETE) passes: a link to the same path
+	 * (Cancel → the list) still asks.
+	 */
 	whitelist?: MaybeRefOrGetter<string[]>;
 	/** Disable the guard (bind to `!hasChanged` / `!form.isDirty`). */
 	disabled?: MaybeRefOrGetter<boolean>;
@@ -24,12 +29,14 @@ type Options = {
 	text?: string;
 	/**
 	 * The dialog's buttons and look, BbConfirm's own options: a label string
-	 * or a full button config. Defaults: `'Discard changes'` / `'Keep editing'`,
-	 * `variant: 'destructive'`. Pass translated labels in a non-English app.
+	 * or a full button config. Default words: `leave` in `messages.ts`, in the
+	 * library's `locale`; `variant: 'destructive'`.
 	 */
 	yes?: BbConfirmMessage['yes'];
 	no?: BbConfirmMessage['no'];
 	variant?: BbConfirmMessage['variant'];
+	/** The `BbDialog` stack the dialog joins (BbConfirm's `stack`). */
+	stack?: BbConfirmMessage['stack'];
 };
 
 const normalizeUrl = (value: string | URL) => {
@@ -56,24 +63,26 @@ export const useConfirmOnRouteLeave = ({
 	disabled = false,
 	onBefore = () => true,
 	onLeave = () => true,
-	title = 'Unsaved changes',
-	text = 'You have unsaved changes. Leave without saving?',
-	yes = 'Discard changes',
-	no = 'Keep editing',
+	title,
+	text,
+	yes,
+	no,
 	variant = 'destructive',
+	stack,
 }: 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();
+	const messages = useHelperMessages();
 	let bypassNextVisit = false;
 
 	const unbind = router.on('before', (event) => {
 		const visit = event.detail.visit as Visit;
 
 		// A hover / mount prefetch (`<Link prefetch>`, `<BbButton href prefetch>`)
-		// fires `before` too, but leaves nothing: no dialog, and it must not use up
-		// the bypass the re-sent visit below is waiting for.
-		if (visit.prefetch) return;
+		// fires `before` too, but leaves nothing: no dialog. A visit another
+		// guard on the page already stopped is that guard's to ask about.
+		if (visit.prefetch || event.defaultPrevented) return;
 
 		if (bypassNextVisit) {
 			bypassNextVisit = false;
@@ -85,32 +94,123 @@ export const useConfirmOnRouteLeave = ({
 
 		const nextPath = normalizeUrl(visit.url.href);
 		if (nextPath === normalizeUrl(window.location.href)) return;
-		if (toValue(whitelist).map(normalizeUrl).includes(nextPath)) return;
+		if (
+			visit.method !== 'get' &&
+			toValue(whitelist).map(normalizeUrl).includes(nextPath)
+		) {
+			// Marked: a save answered with a 409 redirect (a redirect with a
+			// #fragment) is re-sent by Inertia with these same headers, and that
+			// follow-up must not ask either.
+			visit.headers = { ...visit.headers, [WHITELIST_HEADER]: '1' };
+			return;
+		}
 
 		// `return`, not `return false`: an Inertia `before` listener that returns
 		// false CANCELS the visit, which is the opposite of what `onBefore`
 		// promises (false = let this visit through, no dialog).
 		if (onBefore(visit) === false) return;
 		event.preventDefault();
+		// Held, not refused: the dialog decides. `usePromiseForm` reads this
+		// flag and waits instead of answering `false` at once.
+		visit.awaitingConfirm = true;
 
 		void (async () => {
-			const confirmed = await confirm({ variant, title, text, yes, no });
-			if (!confirmed) return;
+			const words = messages.value.leave;
+			const confirmed = await confirm({
+				title: title ?? words.title,
+				text: text ?? words.text,
+				yes: yes ?? words.yes,
+				no: no ?? words.no,
+				variant,
+				...(stack && { stack }),
+			});
+			if (!confirmed) {
+				// "Keep editing" ends the held visit the way Inertia ends a
+				// cancelled one, so its own callbacks (a form's processing state,
+				// a pending promise) settle.
+				const callbacks = visit as {
+					onCancel?: () => void;
+					onFinish?: (visit: Visit) => void;
+				};
+				callbacks.onCancel?.();
+				callbacks.onFinish?.({ ...visit, cancelled: true });
+				return;
+			}
 
 			await onLeave(visit);
+			// Re-sent as a plain visit: never as a prefetch or a background one,
+			// and without the visit's own onBefore (its `confirm('Sure?')` was
+			// already answered).
+			const {
+				prefetch: _prefetch,
+				async: _async,
+				onBefore: _onBefore,
+				awaitingConfirm: _awaitingConfirm,
+				...rest
+			} = visit;
+			// `before` fires inside router.visit(): the bypass covers exactly
+			// that visit, and is never left armed for the next one (a re-send
+			// its own callbacks stop before `before`).
 			bypassNextVisit = true;
-			// Re-sent as a plain visit: never as a prefetch or a background one.
-			const { prefetch: _prefetch, async: _async, ...rest } = visit;
 			router.visit(visit.url, {
 				...(rest as Parameters<typeof router.visit>[1]),
 				headers: { ...visit.headers, [WHITELIST_HEADER]: '1' },
 			});
+			bypassNextVisit = false;
 		})();
 	});
 
+	// Leaving the app (closing the tab, reloading, a typed URL, a plain `<a>`)
+	// never reaches `before`: the browser's own prompt covers it. Not for a
+	// visit this guard let through: a save answered with `Inertia::location()`
+	// is a real unload with the form still dirty. Inertia sets
+	// `window.location` inside that visit, and WebKit asks only after the visit
+	// finished, so a let-through visit that completed with no answer (no page,
+	// no error bag, no error response: Inertia left) keeps it quiet until the
+	// next visit starts.
+	const released = new Set<unknown>();
+	let answered = false;
+	let leaving = false;
+	const marked = (visit: { headers?: Record<string, string> }) =>
+		getHeaderValue(visit.headers, WHITELIST_HEADER) === '1';
+	const unbindStart = router.on('start', ({ detail: { visit } }) => {
+		leaving = false;
+		answered = false;
+		if (marked(visit)) released.add(visit);
+	});
+	// Every way a visit gets an answer; the last two pairs are Inertia 3's
+	// names and Inertia 2's (each fires only on its own version).
+	const onRouterEvent = (name: string, listener: () => void) =>
+		router.on(name as 'start', listener);
+	const unbindAnswers = [
+		'success',
+		'error',
+		'httpException',
+		'invalid',
+		'networkError',
+		'exception',
+	].map((name) => onRouterEvent(name, () => void (answered = true)));
+	const unbindFinish = router.on('finish', ({ detail: { visit } }) => {
+		released.delete(visit);
+		if (marked(visit) && visit.completed && !answered) leaving = true;
+	});
+	const onBeforeUnload = (event: BeforeUnloadEvent) => {
+		if (toValue(disabled) || released.size || leaving) return;
+		event.preventDefault();
+		event.returnValue = '';
+	};
+	const inBrowser = typeof window !== 'undefined';
+	if (inBrowser) window.addEventListener('beforeunload', onBeforeUnload);
+
 	// `router.on` is a global bus that outlives this component: unbind it.
 	// `onScopeDispose` over `onUnmounted`: it fires on unmount too (`setup()`
 	// runs inside a component's own effect scope), but also works if this
 	// composable is ever called from outside one.
-	onScopeDispose(unbind);
+	onScopeDispose(() => {
+		unbind();
+		unbindStart();
+		unbindAnswers.forEach((unbindAnswer) => unbindAnswer());
+		unbindFinish();
+		if (inBrowser) window.removeEventListener('beforeunload', onBeforeUnload);
+	});
 };

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

@@ -1,36 +1,54 @@
 // inertia-helpers/useHasChanged.ts
-import { isEqual } from './utils';
+import { isPlainObject } from './utils';
+import { hash } from 'object-code';
 import { computed, ref, toValue, type WatchSource } from 'vue';
 
 export function useHasChanged<T extends WatchSource<unknown>[]>(
 	dependencies: T
 ) {
 	/*
-	 * Baselines are JSON round-trips, NOT `structuredClone`. This composable's
-	 * documented inputs are refs and reactive objects, and `structuredClone`
-	 * throws `DataCloneError` on every one of them — a Vue proxy is not a
-	 * structured-cloneable type. It took the page down at setup.
-	 *
-	 * The comparison needs no copy at all: `isEqual` is hash-based and reads
-	 * straight through a proxy, so the live value can be hashed as-is. Only the
-	 * BASELINE needs detaching from live state, which is what the round-trip is
-	 * for.
+	 * The baseline is a structural HASH, not a copy. A copy has to survive the
+	 * values a form holds: a JSON round-trip turns a Date into a string, a File,
+	 * Set or Map into `{}`, drops `undefined` (and throws on a bare one), so
+	 * an untouched form read as changed; `structuredClone` throws on Vue proxies.
+	 * `object-code` hashes straight through a proxy and keeps Dates (by time),
+	 * Sets / Maps (by entries), `undefined` and NaN apart, and a number is all
+	 * the baseline needs to hold. It hashes every File alike (no own keys), so
+	 * a File is read by name, size, type and date first: picking another file
+	 * over a picked one counts as a change.
 	 */
 	const snapshot = (dep: WatchSource<unknown>) =>
-		JSON.parse(JSON.stringify(toValue(dep)));
+		hash(withFileFingerprints(toValue(dep)));
 
-	const baselineValues = ref<unknown[]>(dependencies.map(snapshot));
+	const baselines = ref<number[]>(dependencies.map(snapshot));
 
 	/** Re-baseline (call after a successful save). */
 	const takeSnapshot = (): void => {
-		baselineValues.value = dependencies.map(snapshot);
+		baselines.value = dependencies.map(snapshot);
 	};
 
 	const hasChanged = computed(() =>
-		dependencies.some(
-			(dep, index) => !isEqual(toValue(dep), baselineValues.value[index])
-		)
+		dependencies.some((dep, index) => snapshot(dep) !== baselines.value[index])
 	);
 
 	return { hasChanged, takeSnapshot };
 }
+
+const withFileFingerprints = (value: unknown): unknown =>
+	value instanceof Blob
+		? [
+				value.size,
+				value.type,
+				(value as Partial<File>).name,
+				(value as Partial<File>).lastModified,
+			]
+		: Array.isArray(value)
+			? value.map(withFileFingerprints)
+			: isPlainObject(value)
+				? Object.fromEntries(
+						Object.entries(value).map(([key, item]) => [
+							key,
+							withFileFingerprints(item),
+						])
+					)
+				: value;

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

@@ -1,8 +1,16 @@
 // inertia-helpers/useLazyProp.ts
 import { isEqual, isNil, isNotNil } from './utils';
+import type { PageProps } from '@inertiajs/core';
 import { router, usePage } from '@inertiajs/vue3';
 import type { Ref } from 'vue';
-import { customRef, onBeforeUnmount, readonly, ref, watch } from 'vue';
+import {
+	customRef,
+	nextTick,
+	onBeforeUnmount,
+	readonly,
+	ref,
+	watch,
+} from 'vue';
 
 export type UseLazyPropOptions = {
 	/** Keep the last non-nil value across visits that reset the prop. Default true. */
@@ -34,7 +42,9 @@ export function useLazyProp<T>(
 	initialValue?: T,
 	options: UseLazyPropOptions = {}
 ): UseLazyProp<T | undefined> {
-	const page = usePage<{ [key: string]: T | undefined }>();
+	// `PageProps &` keeps usePage's constraint satisfied in an app that
+	// augments Inertia's `PageProps` (TS2344 otherwise).
+	const page = usePage<PageProps & { [key: string]: T | undefined }>();
 	const { cache = true } = options;
 	const loading = ref(false);
 	const loaded = ref(page.props[propName] !== undefined);
@@ -42,50 +52,107 @@ export function useLazyProp<T>(
 	let inFlightPromise: Promise<void> | null = null;
 	let isUnmounted = false;
 	let cached = page.props[propName];
+	// Settles a reload a navigation cancelled, once that navigation is over.
+	let resumeCancelled: (() => void) | null = null;
 
 	onBeforeUnmount(() => {
 		isUnmounted = true;
+		resumeCancelled?.();
 	});
 
 	const loadProp = (onSuccess: () => void): Promise<void> => {
 		if (inFlightPromise) return inFlightPromise;
 
 		error.value = null;
+		let started = false;
+		let succeeded = false;
+		let settle!: () => void;
+		const promise = new Promise<void>((resolve) => {
+			settle = () => {
+				if (!isUnmounted) loading.value = false;
+				if (inFlightPromise === promise) inFlightPromise = null;
+				resolve();
+			};
+		});
+		inFlightPromise = promise;
 
-		inFlightPromise = new Promise<void>((resolve) => {
-			router.reload({
-				only: [propName],
-				replace: true,
-				...(options.headers ? { 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();
-				},
-			});
+		router.reload({
+			only: [propName],
+			replace: true,
+			// Like Inertia's own deferred-props loader: keep the page's
+			// validation errors (Inertia 3; Inertia 2 has no such option).
+			...({ preserveErrors: true } as object),
+			...(options.headers ? { headers: options.headers } : {}),
+			onStart: () => {
+				started = true;
+				loading.value = true;
+			},
+			onSuccess: () => {
+				succeeded = true;
+				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: (visit) => {
+				// A visit to another page cancels this reload: no failure. Stay
+				// loading (a reader must not re-fire it at the outgoing URL) until
+				// that navigation is over, then retry if this page is still
+				// mounted (a same-component visit) or settle if it unmounted.
+				if (visit.cancelled) {
+					const cancelledOn = page.url;
+					const unbindFinish = router.on('finish', (event) => {
+						const next = event.detail.visit;
+						if (next.cancelled || next.interrupted) return;
+						// An async visit is over too (a mutation answered on another
+						// URL redirects back with no other visit), unless it is one
+						// of this page's own reloads (a poll, another lazy prop).
+						if (
+							next.async &&
+							next.url.href === new URL(cancelledOn, next.url).href
+						)
+							return;
+						resumeCancelled?.();
+					});
+					// Back / Forward swaps the page with no finish event.
+					const unbindNavigate = router.on('navigate', () =>
+						resumeCancelled?.()
+					);
+					resumeCancelled = () => {
+						resumeCancelled = null;
+						unbindFinish();
+						unbindNavigate();
+						void nextTick(() => {
+							inFlightPromise = null;
+							if (isUnmounted || loaded.value) settle();
+							else void loadProp(onSuccess).then(settle);
+						});
+					};
+					return;
+				}
+				// A network error or a non-Inertia response (Inertia's error
+				// dialog) reaches only onFinish: report it. The self-loading read
+				// does not retry a failed load; `execute()` does.
+				if (!succeeded && !error.value && !isUnmounted) {
+					error.value = new Error(`Failed to load lazy prop "${propName}"`);
+				}
+				settle();
+			},
 		});
+		// Refused before it started (a `before` listener cancelled it, or no
+		// `window` during SSR): no callback will ever come.
+		if (!started) settle();
 
-		return inFlightPromise;
+		return promise;
 	};
 
 	/** Self-loading ref: reading it while the prop is absent starts the fetch. */
@@ -94,8 +161,7 @@ export function useLazyProp<T>(
 			track();
 			const isMissing = page.props[propName] === undefined;
 
-			if (isMissing && !loaded.value && !loading.value) {
-				loading.value = true;
+			if (isMissing && !loaded.value && !loading.value && !error.value) {
 				void loadProp(trigger);
 			}
 

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

@@ -39,7 +39,9 @@ export function useLazyPropGetter<T, U = T>(
 		if (!loaded.value) {
 			await execute();
 		}
-		if (isNil(value.value)) {
+		// `loaded` first: reading `value` while unloaded would start a
+		// second, background reload.
+		if (!loaded.value || isNil(value.value)) {
 			throw new Error(`Could not load lazy prop "${propName}"`);
 		}
 		if (isNil(formatter)) return value.value as unknown as U;