swup 4.4.3 → 4.5.0

package/src/Swup.ts

@@ -21,7 +21,7 @@ import { renderPage } from './modules/renderPage.js';
 import { use, unuse, findPlugin, type Plugin } from './modules/plugins.js';
 import { isSameResolvedUrl, resolveUrl } from './modules/resolveUrl.js';
 import { nextTick } from './utils.js';
-import { type HistoryState } from './helpers/createHistoryRecord.js';
+import { type HistoryState } from './helpers/history.js';
 
 /** Options for customizing swup's behavior. */
 export type Options = {
@@ -41,6 +41,8 @@ export type Options = {
 	linkSelector: string;
 	/** How swup handles links to the same page. Default: `scroll` */
 	linkToSelf: NavigationToSelfAction;
+	/** Enable native animations using the View Transitions API. */
+	native: boolean;
 	/** Plugins to register on startup. */
 	plugins: Plugin[];
 	/** Custom headers sent along with fetch requests. */
@@ -62,6 +64,7 @@ const defaults: Options = {
 	ignoreVisit: (url, { el } = {}) => !!el?.closest('[data-no-swup]'),
 	linkSelector: 'a[href]',
 	linkToSelf: 'scroll',
+	native: false,
 	plugins: [],
 	resolveUrl: (url) => url,
 	requestHeaders: {
@@ -98,6 +101,8 @@ export default class Swup {
 	protected clickDelegate?: DelegateEventUnsubscribe;
 	/** Navigation status */
 	protected navigating: boolean = false;
+	/** Run anytime a visit ends */
+	protected onVisitEnd?: () => Promise<unknown>;
 
 	/** Install a plugin */
 	use = use;
@@ -185,6 +190,9 @@ export default class Swup {
 			// https://github.com/swup/swup/issues/475
 		}
 
+		// Sanitize/check native option
+		this.options.native = this.options.native && !!document.startViewTransition;
+
 		// Mount plugins
 		this.options.plugins.forEach((plugin) => this.use(plugin));
 
@@ -197,9 +205,10 @@ export default class Swup {
 		await nextTick();
 
 		// Trigger enable hook
-		await this.hooks.call('enable', undefined, () => {
-			// Add swup-enabled class to html tag
-			document.documentElement.classList.add('swup-enabled');
+		await this.hooks.call('enable', undefined, undefined, () => {
+			const html = document.documentElement;
+			html.classList.add('swup-enabled');
+			html.classList.toggle('swup-native', this.options.native);
 		});
 	}
 
@@ -218,9 +227,10 @@ export default class Swup {
 		this.options.plugins.forEach((plugin) => this.unuse(plugin));
 
 		// trigger disable hook
-		await this.hooks.call('disable', undefined, () => {
-			// remove swup-enabled class from html tag
-			document.documentElement.classList.remove('swup-enabled');
+		await this.hooks.call('disable', undefined, undefined, () => {
+			const html = document.documentElement;
+			html.classList.remove('swup-enabled');
+			html.classList.remove('swup-native');
 		});
 
 		// remove handlers
@@ -265,11 +275,11 @@ export default class Swup {
 			return;
 		}
 
-		this.visit = this.createVisit({ to: url, hash, el, event });
+		const visit = this.createVisit({ to: url, hash, el, event });
 
 		// Exit early if control key pressed
 		if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
-			this.hooks.call('link:newtab', { href });
+			this.hooks.callSync('link:newtab', visit, { href });
 			return;
 		}
 
@@ -278,8 +288,8 @@ export default class Swup {
 			return;
 		}
 
-		this.hooks.callSync('link:click', { el, event }, () => {
-			const from = this.visit.from.url ?? '';
+		this.hooks.callSync('link:click', visit, { el, event }, () => {
+			const from = visit.from.url ?? '';
 
 			event.preventDefault();
 
@@ -287,20 +297,18 @@ export default class Swup {
 			if (!url || url === from) {
 				if (hash) {
 					// With hash: scroll to anchor
-					this.hooks.callSync('link:anchor', { hash }, () => {
+					this.hooks.callSync('link:anchor', visit, { hash }, () => {
 						updateHistoryRecord(url + hash);
-						this.scrollToContent();
+						this.scrollToContent(visit);
 					});
 				} else {
 					// Without hash: scroll to top or load/reload page
-					this.hooks.callSync('link:self', undefined, () => {
-						switch (this.options.linkToSelf) {
-							case 'navigate':
-								return this.performNavigation();
-							case 'scroll':
-							default:
-								updateHistoryRecord(url);
-								return this.scrollToContent();
+					this.hooks.callSync('link:self', visit, undefined, () => {
+						if (this.options.linkToSelf === 'navigate') {
+							this.performNavigation(visit);
+						} else {
+							updateHistoryRecord(url);
+							this.scrollToContent(visit);
 						}
 					});
 				}
@@ -313,7 +321,7 @@ export default class Swup {
 			}
 
 			// Finally, proceed with loading the page
-			this.performNavigation();
+			this.performNavigation(visit);
 		});
 	}
 
@@ -332,37 +340,32 @@ export default class Swup {
 
 		const { url, hash } = Location.fromUrl(href);
 
-		this.visit = this.createVisit({ to: url, hash, event });
+		const visit = this.createVisit({ to: url, hash, event });
 
 		// Mark as history visit
-		this.visit.history.popstate = true;
+		visit.history.popstate = true;
 
 		// Determine direction of history visit
 		const index = (event.state as HistoryState)?.index ?? 0;
 		if (index && index !== this.currentHistoryIndex) {
 			const direction = index - this.currentHistoryIndex > 0 ? 'forwards' : 'backwards';
-			this.visit.history.direction = direction;
+			visit.history.direction = direction;
 			this.currentHistoryIndex = index;
 		}
 
 		// Disable animation & scrolling for history visits
-		this.visit.animation.animate = false;
-		this.visit.scroll.reset = false;
-		this.visit.scroll.target = false;
+		visit.animation.animate = false;
+		visit.scroll.reset = false;
+		visit.scroll.target = false;
 
 		// Animated history visit: re-enable animation & scroll reset
 		if (this.options.animateHistoryBrowsing) {
-			this.visit.animation.animate = true;
-			this.visit.scroll.reset = true;
+			visit.animation.animate = true;
+			visit.scroll.reset = true;
 		}
 
-		// Does this even do anything?
-		// if (!hash) {
-		// 	event.preventDefault();
-		// }
-
-		this.hooks.callSync('history:popstate', { event }, () => {
-			this.performNavigation();
+		this.hooks.callSync('history:popstate', visit, { event }, () => {
+			this.performNavigation(visit);
 		});
 	}
 

package/src/helpers/Location.ts

@@ -6,6 +6,7 @@
 export class Location extends URL {
 	constructor(url: URL | string, base: string = document.baseURI) {
 		super(url.toString(), base);
+		// Fix Safari bug with extending native classes
 		Object.setPrototypeOf(this, Location.prototype);
 	}
 

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/index.ts

@@ -21,7 +21,8 @@ import type {
 	HookHandler,
 	HookDefaultHandler,
 	HookOptions,
-	HookUnregister
+	HookUnregister,
+	HookEvent
 } from './modules/Hooks.js';
 import type { Plugin } from './modules/plugins.js';
 
@@ -50,6 +51,7 @@ export type {
 	HookDefaultHandler,
 	HookOptions,
 	HookUnregister,
+	HookEvent,
 	DelegateEvent,
 	DelegateEventHandler,
 	DelegateEventUnsubscribe

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];
@@ -96,6 +96,14 @@ export type HookRegistration<
 	defaultHandler?: HookDefaultHandler<T>;
 } & HookOptions;
 
+type HookEventDetail = {
+	hook: HookName;
+	args: unknown;
+	visit: Visit;
+};
+
+export type HookEvent = CustomEvent<HookEventDetail>;
+
 type HookLedger<T extends HookName> = Map<HookHandler<T>, HookRegistration<T>>;
 
 interface HookRegistry extends Map<HookName, HookLedger<HookName>> {
@@ -146,6 +154,7 @@ export class Hooks {
 		'scroll:anchor',
 		'visit:start',
 		'visit:transition',
+		'visit:abort',
 		'visit:end'
 	];
 
@@ -325,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;
 	}
 
@@ -346,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
@@ -370,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;
 	}
@@ -396,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(
@@ -414,9 +467,6 @@ export class Hooks {
 						`Swup will not wait for it to resolve.`
 				);
 			}
-			if (once) {
-				this.off(hook, handler);
-			}
 		}
 		return results;
 	}
@@ -492,8 +542,19 @@ 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 = { hook, args, visit: this.swup.visit };
-		document.dispatchEvent(new CustomEvent(`swup:${hook}`, { detail }));
+	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 })
+		);
+		document.dispatchEvent(
+			new CustomEvent<HookEventDetail>(`swup:${hook}`, { detail, bubbles: true })
+		);
 	}
 }