swup 4.4.4 → 4.5.0

package/src/helpers/history.ts

@@ -0,0 +1,37 @@
+import { getCurrentUrl } from './getCurrentUrl.js';
+
+export interface HistoryState {
+	url: string;
+	source: 'swup';
+	random: number;
+	index?: number;
+	[key: string]: unknown;
+}
+
+type HistoryData = Record<string, unknown>;
+
+/** Create a new history record with a custom swup identifier. */
+export const createHistoryRecord = (url: string, data: HistoryData = {}): void => {
+	url = url || getCurrentUrl({ hash: true });
+	const state: HistoryState = {
+		url,
+		random: Math.random(),
+		source: 'swup',
+		...data
+	};
+	history.pushState(state, '', url);
+};
+
+/** Update the current history record with a custom swup identifier. */
+export const updateHistoryRecord = (url: string | null = null, data: HistoryData = {}): void => {
+	url = url || getCurrentUrl({ hash: true });
+	const currentState = (history.state as HistoryState) || {};
+	const state: HistoryState = {
+		...currentState,
+		url,
+		random: Math.random(),
+		source: 'swup',
+		...data
+	};
+	history.replaceState(state, '', url);
+};

package/src/helpers.ts

@@ -2,8 +2,7 @@
 // e.g. import { updateHistoryRecord } from 'swup'
 
 export { classify } from './helpers/classify.js';
-export { createHistoryRecord } from './helpers/createHistoryRecord.js';
-export { updateHistoryRecord } from './helpers/updateHistoryRecord.js';
+export { createHistoryRecord, updateHistoryRecord } from './helpers/history.js';
 export { delegateEvent } from './helpers/delegateEvent.js';
 export { getCurrentUrl } from './helpers/getCurrentUrl.js';
 export { Location } from './helpers/Location.js';

package/src/modules/Cache.ts

@@ -49,7 +49,7 @@ export class Cache {
 		url = this.resolve(url);
 		page = { ...page, url };
 		this.pages.set(url, page);
-		this.swup.hooks.callSync('cache:set', { page });
+		this.swup.hooks.callSync('cache:set', undefined, { page });
 	}
 
 	/** Update a cache record, overwriting or adding custom data. */
@@ -67,7 +67,7 @@ export class Cache {
 	/** Empty the cache. */
 	clear(): void {
 		this.pages.clear();
-		this.swup.hooks.callSync('cache:clear', undefined);
+		this.swup.hooks.callSync('cache:clear', undefined, undefined);
 	}
 
 	/** Remove all cache entries that return true for a given predicate function.  */

package/src/modules/Classes.ts

@@ -3,7 +3,14 @@ import { queryAll } from '../utils.js';
 
 export class Classes {
 	protected swup: Swup;
-	protected swupClasses = ['to-', 'is-changing', 'is-rendering', 'is-popstate', 'is-animating'];
+	protected swupClasses = [
+		'to-',
+		'is-changing',
+		'is-rendering',
+		'is-popstate',
+		'is-animating',
+		'is-leaving'
+	];
 
 	constructor(swup: Swup) {
 		this.swup = swup;

package/src/modules/Hooks.ts

@@ -2,7 +2,7 @@ import type { DelegateEvent } from 'delegate-it';
 
 import type Swup from '../Swup.js';
 import { isPromise, runAsPromise } from '../utils.js';
-import type { Visit } from './Visit.js';
+import { Visit } from './Visit.js';
 import type { FetchOptions, PageData } from './fetchPage.js';
 
 export interface HookDefinitions {
@@ -33,16 +33,16 @@ export interface HookDefinitions {
 	'scroll:anchor': { hash: string; options: ScrollIntoViewOptions };
 	'visit:start': undefined;
 	'visit:transition': undefined;
+	'visit:abort': undefined;
 	'visit:end': undefined;
 }
 
 export interface HookReturnValues {
-	'content:scroll': Promise<boolean>;
+	'content:scroll': Promise<boolean> | boolean;
 	'fetch:request': Promise<Response>;
 	'page:load': Promise<PageData>;
 	'scroll:top': boolean;
 	'scroll:anchor': boolean;
-	'visit:transition': Promise<boolean>;
 }
 
 export type HookArguments<T extends HookName> = HookDefinitions[T];
@@ -154,6 +154,7 @@ export class Hooks {
 		'scroll:anchor',
 		'visit:start',
 		'visit:transition',
+		'visit:abort',
 		'visit:end'
 	];
 
@@ -333,20 +334,29 @@ export class Hooks {
 	 * Trigger a hook asynchronously, executing its default handler and all registered handlers.
 	 * Will execute all handlers in order and `await` any `Promise`s they return.
 	 * @param hook Name of the hook to trigger
+	 * @param visit The visit object this hook belongs to
 	 * @param args Arguments to pass to the handler
 	 * @param defaultHandler A default implementation of this hook to execute
 	 * @returns The resolved return value of the executed default handler
 	 */
+	// Overload: default order of arguments
+	async call<T extends HookName>(hook: T, visit: Visit | undefined, args: HookArguments<T>, defaultHandler?: HookDefaultHandler<T>): Promise<Awaited<ReturnType<HookDefaultHandler<T>>>>; // prettier-ignore
+	// Overload: legacy order of arguments, with visit missing
+	async call<T extends HookName>(hook: T, args: HookArguments<T>, defaultHandler?: HookDefaultHandler<T>): Promise<Awaited<ReturnType<HookDefaultHandler<T>>>>; // prettier-ignore
+	// Implementation
 	async call<T extends HookName>(
 		hook: T,
-		args: HookArguments<T>,
-		defaultHandler?: HookDefaultHandler<T>
+		arg1: Visit | HookArguments<T>,
+		arg2: HookArguments<T> | HookDefaultHandler<T>,
+		arg3?: HookDefaultHandler<T>
 	): Promise<Awaited<ReturnType<HookDefaultHandler<T>>>> {
+		const [visit, args, defaultHandler] = this.parseCallArgs(hook, arg1, arg2, arg3);
+
 		const { before, handler, after } = this.getHandlers(hook, defaultHandler);
-		await this.run(before, args);
-		const [result] = await this.run(handler, args);
-		await this.run(after, args);
-		this.dispatchDomEvent(hook, args);
+		await this.run(before, visit, args);
+		const [result] = await this.run(handler, visit, args);
+		await this.run(after, visit, args);
+		this.dispatchDomEvent(hook, visit, args);
 		return result;
 	}
 
@@ -354,23 +364,51 @@ export class Hooks {
 	 * Trigger a hook synchronously, executing its default handler and all registered handlers.
 	 * Will execute all handlers in order, but will **not** `await` any `Promise`s they return.
 	 * @param hook Name of the hook to trigger
+	 * @param visit The visit object this hook belongs to
 	 * @param args Arguments to pass to the handler
 	 * @param defaultHandler A default implementation of this hook to execute
 	 * @returns The (possibly unresolved) return value of the executed default handler
 	 */
+	// Overload: default order of arguments
+	callSync<T extends HookName>(hook: T, visit: Visit | undefined, args: HookArguments<T>, defaultHandler?: HookDefaultHandler<T>): ReturnType<HookDefaultHandler<T>>; // prettier-ignore
+	// Overload: legacy order of arguments, with visit missing
+	callSync<T extends HookName>(hook: T, args: HookArguments<T>, defaultHandler?: HookDefaultHandler<T>): ReturnType<HookDefaultHandler<T>>; // prettier-ignore
+	// Implementation
 	callSync<T extends HookName>(
 		hook: T,
-		args: HookArguments<T>,
-		defaultHandler?: HookDefaultHandler<T>
+		arg1: Visit | HookArguments<T>,
+		arg2: HookArguments<T> | HookDefaultHandler<T>,
+		arg3?: HookDefaultHandler<T>
 	): ReturnType<HookDefaultHandler<T>> {
+		const [visit, args, defaultHandler] = this.parseCallArgs(hook, arg1, arg2, arg3);
 		const { before, handler, after } = this.getHandlers(hook, defaultHandler);
-		this.runSync(before, args);
-		const [result] = this.runSync(handler, args);
-		this.runSync(after, args);
-		this.dispatchDomEvent(hook, args);
+		this.runSync(before, visit, args);
+		const [result] = this.runSync(handler, visit, args);
+		this.runSync(after, visit, args);
+		this.dispatchDomEvent(hook, visit, args);
 		return result;
 	}
 
+	/**
+	 * Parse the call arguments for call() and callSync() to allow legacy argument order.
+	 */
+	protected parseCallArgs<T extends HookName>(
+		hook: T,
+		arg1: Visit | HookArguments<T> | undefined,
+		arg2: HookArguments<T> | HookDefaultHandler<T>,
+		arg3?: HookDefaultHandler<T>
+	): [Visit | undefined, HookArguments<T>, HookDefaultHandler<T> | undefined] {
+		const isLegacyOrder =
+			!(arg1 instanceof Visit) && (typeof arg1 === 'object' || typeof arg2 === 'function');
+		if (isLegacyOrder) {
+			// Legacy positioning: arguments in second or handler passed in third place
+			return [undefined, arg1 as HookArguments<T>, arg2 as HookDefaultHandler<T>];
+		} else {
+			// Default positioning: visit passed in as first argument
+			return [arg1, arg2 as HookArguments<T>, arg3];
+		}
+	}
+
 	/**
 	 * Execute the handlers for a hook, in order, as `Promise`s that will be `await`ed.
 	 * @param registrations The registrations (handler + options) to execute
@@ -378,21 +416,25 @@ export class Hooks {
 	 */
 
 	// Overload: running HookDefaultHandler: expect HookDefaultHandler return type
-	protected async run<T extends HookName>(registrations: HookRegistration<T, HookDefaultHandler<T>>[], args: HookArguments<T>): Promise<Awaited<ReturnType<HookDefaultHandler<T>>>[]>; // prettier-ignore
+	protected async run<T extends HookName>(registrations: HookRegistration<T, HookDefaultHandler<T>>[], visit: Visit | undefined, args: HookArguments<T>): Promise<Awaited<ReturnType<HookDefaultHandler<T>>>[]>; // prettier-ignore
 	// Overload:  running user handler: expect no specific type
-	protected async run<T extends HookName>(registrations: HookRegistration<T>[], args: HookArguments<T>): Promise<unknown[]>; // prettier-ignore
+	protected async run<T extends HookName>(registrations: HookRegistration<T>[], visit: Visit | undefined, args: HookArguments<T>): Promise<unknown[]>; // prettier-ignore
 	// Implementation
 	protected async run<T extends HookName, R extends HookRegistration<T>[]>(
 		registrations: R,
+		visit: Visit | undefined,
 		args: HookArguments<T>
 	): Promise<Awaited<ReturnType<HookDefaultHandler<T>>> | unknown[]> {
 		const results = [];
 		for (const { hook, handler, defaultHandler, once } of registrations) {
-			const result = await runAsPromise(handler, [this.swup.visit, args, defaultHandler]);
+			if (visit?.done) continue;
+			if (once) this.off(hook, handler);
+			const result = await runAsPromise(handler, [
+				visit || this.swup.visit,
+				args,
+				defaultHandler
+			]);
 			results.push(result);
-			if (once) {
-				this.off(hook, handler);
-			}
 		}
 		return results;
 	}
@@ -404,17 +446,20 @@ export class Hooks {
 	 */
 
 	// Overload: running HookDefaultHandler: expect HookDefaultHandler return type
-	protected runSync<T extends HookName>(registrations: HookRegistration<T, HookDefaultHandler<T>>[], args: HookArguments<T> ): ReturnType<HookDefaultHandler<T>>[]; // prettier-ignore
+	protected runSync<T extends HookName>(registrations: HookRegistration<T, HookDefaultHandler<T>>[], visit: Visit | undefined, args: HookArguments<T> ): ReturnType<HookDefaultHandler<T>>[]; // prettier-ignore
 	// Overload: running user handler: expect no specific type
-	protected runSync<T extends HookName>(registrations: HookRegistration<T>[], args: HookArguments<T>): unknown[]; // prettier-ignore
+	protected runSync<T extends HookName>(registrations: HookRegistration<T>[], visit: Visit | undefined, args: HookArguments<T>): unknown[]; // prettier-ignore
 	// Implementation
 	protected runSync<T extends HookName, R extends HookRegistration<T>[]>(
 		registrations: R,
+		visit: Visit | undefined,
 		args: HookArguments<T>
 	): (ReturnType<HookDefaultHandler<T>> | unknown)[] {
 		const results = [];
 		for (const { hook, handler, defaultHandler, once } of registrations) {
-			const result = (handler as HookDefaultHandler<T>)(this.swup.visit, args, defaultHandler); // prettier-ignore
+			if (visit?.done) continue;
+			if (once) this.off(hook, handler);
+			const result = (handler as HookDefaultHandler<T>)(visit || this.swup.visit, args, defaultHandler); // prettier-ignore
 			results.push(result);
 			if (isPromise(result)) {
 				console.warn(
@@ -422,9 +467,6 @@ export class Hooks {
 						`Swup will not wait for it to resolve.`
 				);
 			}
-			if (once) {
-				this.off(hook, handler);
-			}
 		}
 		return results;
 	}
@@ -500,8 +542,14 @@ export class Hooks {
 	 * Dispatch a custom event on the `document` for a hook. Prefixed with `swup:`
 	 * @param hook Name of the hook.
 	 */
-	protected dispatchDomEvent<T extends HookName>(hook: T, args?: HookArguments<T>): void {
-		const detail: HookEventDetail = { hook, args, visit: this.swup.visit };
+	protected dispatchDomEvent<T extends HookName>(
+		hook: T,
+		visit: Visit | undefined,
+		args?: HookArguments<T>
+	): void {
+		if (visit?.done) return;
+
+		const detail: HookEventDetail = { hook, args, visit: visit || this.swup.visit };
 		document.dispatchEvent(
 			new CustomEvent<HookEventDetail>(`swup:any`, { detail, bubbles: true })
 		);

package/src/modules/Visit.ts

@@ -2,27 +2,8 @@ import type Swup from '../Swup.js';
 import type { Options } from '../Swup.js';
 import type { HistoryAction, HistoryDirection } from './navigate.js';
 
-/** An object holding details about the current visit. */
-export interface Visit {
-	/** A unique ID to identify this visit */
-	id: number;
-	/** The previous page, about to leave */
-	from: VisitFrom;
-	/** The next page, about to enter */
-	to: VisitTo;
-	/** The content containers, about to be replaced */
-	containers: Options['containers'];
-	/** Information about animated page transitions */
-	animation: VisitAnimation;
-	/** What triggered this visit */
-	trigger: VisitTrigger;
-	/** Cache behavior for this visit */
-	cache: VisitCache;
-	/** Browser history behavior on this visit */
-	history: VisitHistory;
-	/** Scroll behavior on this visit */
-	scroll: VisitScroll;
-}
+/** See below for the class Visit {} definition */
+// export interface Visit {}
 
 export interface VisitFrom {
 	/** The URL of the previous page */
@@ -45,6 +26,8 @@ export interface VisitAnimation {
 	wait: boolean;
 	/** Name of a custom animation to run. */
 	name?: string;
+	/** Whether this animation uses the native browser ViewTransition API. Default: `false` */
+	native: boolean;
 	/** Elements on which to add animation classes. Default: `html` element */
 	scope: 'html' | 'containers' | string[];
 	/** Selector for detecting animation timing. Default: `[class*="transition-"]` */
@@ -89,39 +72,95 @@ export interface VisitInitOptions {
 	event?: Event;
 }
 
-/** Create a new visit object. */
-export function createVisit(
-	this: Swup,
-	{ to, from = this.currentPageUrl, hash, el, event }: VisitInitOptions
-): Visit {
-	return {
-		id: Math.random(),
-		from: { url: from },
-		to: { url: to, hash },
-		containers: this.options.containers,
-		animation: {
+/** @internal */
+export const VisitState = {
+	CREATED: 1,
+	QUEUED: 2,
+	STARTED: 3,
+	LEAVING: 4,
+	LOADED: 5,
+	ENTERING: 6,
+	COMPLETED: 7,
+	ABORTED: 8,
+	FAILED: 9
+} as const;
+
+/** @internal */
+export type VisitState = (typeof VisitState)[keyof typeof VisitState];
+
+/** An object holding details about the current visit. */
+export class Visit {
+	/** A unique ID to identify this visit */
+	id: number;
+	/** The current state of this visit @internal */
+	state: VisitState;
+	/** The previous page, about to leave */
+	from: VisitFrom;
+	/** The next page, about to enter */
+	to: VisitTo;
+	/** The content containers, about to be replaced */
+	containers: Options['containers'];
+	/** Information about animated page transitions */
+	animation: VisitAnimation;
+	/** What triggered this visit */
+	trigger: VisitTrigger;
+	/** Cache behavior for this visit */
+	cache: VisitCache;
+	/** Browser history behavior on this visit */
+	history: VisitHistory;
+	/** Scroll behavior on this visit */
+	scroll: VisitScroll;
+
+	constructor(swup: Swup, options: VisitInitOptions) {
+		const { to, from = swup.currentPageUrl, hash, el, event } = options;
+
+		this.id = Math.random();
+		this.state = VisitState.CREATED;
+		this.from = { url: from };
+		this.to = { url: to, hash };
+		this.containers = swup.options.containers;
+		this.animation = {
 			animate: true,
 			wait: false,
 			name: undefined,
-			scope: this.options.animationScope,
-			selector: this.options.animationSelector
-		},
-		trigger: {
-			el,
-			event
-		},
-		cache: {
-			read: this.options.cache,
-			write: this.options.cache
-		},
-		history: {
+			native: swup.options.native,
+			scope: swup.options.animationScope,
+			selector: swup.options.animationSelector
+		};
+		this.trigger = { el, event };
+		this.cache = {
+			read: swup.options.cache,
+			write: swup.options.cache
+		};
+		this.history = {
 			action: 'push',
 			popstate: false,
 			direction: undefined
-		},
-		scroll: {
+		};
+		this.scroll = {
 			reset: true,
 			target: undefined
+		};
+	}
+	/** @internal */
+	advance(state: VisitState) {
+		if (this.state < state) {
+			this.state = state;
 		}
-	};
+	}
+
+	/** @internal */
+	abort() {
+		this.state = VisitState.ABORTED;
+	}
+
+	/** Is this visit done, i.e. completed, failed, or aborted? */
+	get done(): boolean {
+		return this.state >= VisitState.COMPLETED;
+	}
+}
+
+/** Create a new visit object. */
+export function createVisit(this: Swup, options: VisitInitOptions): Visit {
+	return new Visit(this, options);
 }

package/src/modules/animatePageIn.ts

@@ -1,31 +1,32 @@
 import type Swup from '../Swup.js';
 import { nextTick } from '../utils.js';
+import type { Visit } from './Visit.js';
 
 /**
  * Perform the in/enter animation of the next page.
  * @returns Promise<void>
  */
-export const animatePageIn = async function (this: Swup) {
-	if (!this.visit.animation.animate) {
-		return;
-	}
+export const animatePageIn = async function (this: Swup, visit: Visit) {
+	// Check if failed/aborted in the meantime
+	if (visit.done) return;
 
 	const animation = this.hooks.call(
 		'animation:in:await',
+		visit,
 		{ skip: false },
-		async (visit, { skip }) => {
+		(visit, { skip }) => {
 			if (skip) return;
-			await this.awaitAnimations({ selector: visit.animation.selector });
+			return this.awaitAnimations({ selector: visit.animation.selector });
 		}
 	);
 
 	await nextTick();
 
-	await this.hooks.call('animation:in:start', undefined, () => {
+	await this.hooks.call('animation:in:start', visit, undefined, () => {
 		this.classes.remove('is-animating');
 	});
 
 	await animation;
 
-	await this.hooks.call('animation:in:end', undefined);
+	await this.hooks.call('animation:in:end', visit, undefined);
 };

package/src/modules/animatePageOut.ts

@@ -1,30 +1,19 @@
 import type Swup from '../Swup.js';
-import { classify } from '../helpers.js';
+import type { Visit } from './Visit.js';
 
 /**
  * Perform the out/leave animation of the current page.
  * @returns Promise<void>
  */
-export const animatePageOut = async function (this: Swup) {
-	if (!this.visit.animation.animate) {
-		await this.hooks.call('animation:skip', undefined);
-		return;
-	}
-
-	await this.hooks.call('animation:out:start', undefined, (visit) => {
-		this.classes.add('is-changing', 'is-leaving', 'is-animating');
-		if (visit.history.popstate) {
-			this.classes.add('is-popstate');
-		}
-		if (visit.animation.name) {
-			this.classes.add(`to-${classify(visit.animation.name)}`);
-		}
+export const animatePageOut = async function (this: Swup, visit: Visit) {
+	await this.hooks.call('animation:out:start', visit, undefined, () => {
+		this.classes.add('is-changing', 'is-animating', 'is-leaving');
 	});
 
-	await this.hooks.call('animation:out:await', { skip: false }, async (visit, { skip }) => {
+	await this.hooks.call('animation:out:await', visit, { skip: false }, (visit, { skip }) => {
 		if (skip) return;
-		await this.awaitAnimations({ selector: visit.animation.selector });
+		return this.awaitAnimations({ selector: visit.animation.selector });
 	});
 
-	await this.hooks.call('animation:out:end', undefined);
+	await this.hooks.call('animation:out:end', visit, undefined);
 };

package/src/modules/fetchPage.ts

@@ -1,5 +1,6 @@
 import type Swup from '../Swup.js';
 import { Location } from '../helpers.js';
+import type { Visit } from './Visit.js';
 
 /** A page object as used by swup and its cache. */
 export interface PageData {
@@ -17,6 +18,8 @@ export interface FetchOptions extends Omit<RequestInit, 'cache'> {
 	body?: string | FormData | URLSearchParams;
 	/** The request timeout in milliseconds. */
 	timeout?: number;
+	/** Optional visit object with additional context. @internal */
+	visit?: Visit;
 }
 
 export class FetchError extends Error {
@@ -47,6 +50,7 @@ export async function fetchPage(
 ): Promise<PageData> {
 	url = Location.fromUrl(url).url;
 
+	const { visit = this.visit } = options;
 	const headers = { ...this.options.requestHeaders, ...options.headers };
 	const timeout = options.timeout ?? this.options.timeout;
 	const controller = new AbortController();
@@ -67,6 +71,7 @@ export async function fetchPage(
 	try {
 		response = await this.hooks.call(
 			'fetch:request',
+			visit,
 			{ url, options },
 			(visit, { url, options }) => fetch(url, options)
 		);
@@ -75,14 +80,11 @@ export async function fetchPage(
 		}
 	} catch (error) {
 		if (timedOut) {
-			this.hooks.call('fetch:timeout', { url });
+			this.hooks.call('fetch:timeout', visit, { url });
 			throw new FetchError(`Request timed out: ${url}`, { url, timedOut });
 		}
 		if ((error as Error)?.name === 'AbortError' || signal.aborted) {
-			throw new FetchError(`Request aborted: ${url}`, {
-				url: url,
-				aborted: true
-			});
+			throw new FetchError(`Request aborted: ${url}`, { url, aborted: true });
 		}
 		throw error;
 	}
@@ -91,7 +93,7 @@ export async function fetchPage(
 	const html = await response.text();
 
 	if (status === 500) {
-		this.hooks.call('fetch:error', { status, response, url: responseUrl });
+		this.hooks.call('fetch:error', visit, { status, response, url: responseUrl });
 		throw new FetchError(`Server error: ${responseUrl}`, { status, url: responseUrl });
 	}
 
@@ -104,11 +106,7 @@ export async function fetchPage(
 	const page = { url: finalUrl, html };
 
 	// Write to cache for safe methods and non-redirects
-	if (
-		this.visit.cache.write &&
-		(!options.method || options.method === 'GET') &&
-		url === finalUrl
-	) {
+	if (visit.cache.write && (!options.method || options.method === 'GET') && url === finalUrl) {
 		this.cache.set(page.url, page);
 	}