swup 3.1.1 → 4.0.0-rc.20

package/src/Swup.ts

@@ -2,124 +2,93 @@ import { DelegateEvent } from 'delegate-it';
 
 import version from './config/version.js';
 
-import {
-	cleanupAnimationClasses,
-	delegateEvent,
-	getCurrentUrl,
-	Location,
-	markSwupElements,
-	updateHistoryRecord
-} from './helpers.js';
-import { Unsubscribe } from './helpers/delegateEvent.js';
+import { delegateEvent, getCurrentUrl, Location, updateHistoryRecord } from './helpers.js';
+import { DelegateEventUnsubscribe } from './helpers/delegateEvent.js';
 
 import { Cache } from './modules/Cache.js';
-import { enterPage } from './modules/enterPage.js';
+import { Classes } from './modules/Classes.js';
+import { Context, createContext } from './modules/Context.js';
+import { Hooks } from './modules/Hooks.js';
 import { getAnchorElement } from './modules/getAnchorElement.js';
-import { getAnimationPromises } from './modules/getAnimationPromises.js';
-import { getPageData } from './modules/getPageData.js';
+import { awaitAnimations } from './modules/awaitAnimations.js';
+import { visit, performVisit, HistoryAction } from './modules/visit.js';
 import { fetchPage } from './modules/fetchPage.js';
 import { leavePage } from './modules/leavePage.js';
-import { HistoryAction, loadPage, performPageLoad } from './modules/loadPage.js';
 import { replaceContent } from './modules/replaceContent.js';
-import { on, off, triggerEvent, Handlers } from './modules/events.js';
-import { use, unuse, findPlugin, Plugin } from './modules/plugins.js';
+import { enterPage } from './modules/enterPage.js';
 import { renderPage } from './modules/renderPage.js';
-import { updateTransition, shouldSkipTransition } from './modules/transitions.js';
-
-import { queryAll } from './utils.js';
-
-export type Transition = {
-	from?: string;
-	to?: string;
-	custom?: string;
-};
-
-type DelegatedListeners = {
-	click?: Unsubscribe;
-};
+import { use, unuse, findPlugin, Plugin } from './modules/plugins.js';
+import { nextTick } from './utils.js';
 
 export type Options = {
+	/** Whether history visits are animated. Default: `false` */
 	animateHistoryBrowsing: boolean;
+	/** Selector for detecting animation timing. Default: `[class*="transition-"]` */
 	animationSelector: string | false;
-	linkSelector: string;
+	/** Elements on which to add animation classes. Default: `html` element */
+	animationScope: 'html' | 'containers';
+	/** Enable in-memory page cache. Default: `true` */
 	cache: boolean;
+	/** Content containers to be replaced on page visits. Default: `['#swup']` */
 	containers: string[];
-	requestHeaders: Record<string, string>;
-	plugins: Plugin[];
-	skipPopStateHandling: (event: any) => boolean;
+	/** Callback for ignoring visits. Receives the element and event that triggered the visit. */
 	ignoreVisit: (url: string, { el, event }: { el?: Element; event?: Event }) => boolean;
+	/** Selector for links that trigger visits. Default: `'a[href]'` */
+	linkSelector: string;
+	/** Plugins to register on startup. */
+	plugins: Plugin[];
+	/** Custom headers sent along with fetch requests. */
+	requestHeaders: Record<string, string>;
+	/** Rewrite URLs before loading them. */
 	resolveUrl: (url: string) => string;
+	/** Callback for telling swup to ignore certain popstate events.  */
+	skipPopStateHandling: (event: any) => boolean;
 };
 
 export default class Swup {
-	version = version;
-
-	_handlers: Handlers = {
-		animationInDone: [],
-		animationInStart: [],
-		animationOutDone: [],
-		animationOutStart: [],
-		animationSkipped: [],
-		clickLink: [],
-		contentReplaced: [],
-		disabled: [],
-		enabled: [],
-		openPageInNewTab: [],
-		pageLoaded: [],
-		pageRetrievedFromCache: [],
-		pageView: [],
-		popState: [],
-		samePage: [],
-		samePageWithHash: [],
-		serverError: [],
-		transitionStart: [],
-		transitionEnd: [],
-		willReplaceContent: []
-	};
-
-	// variable for anchor to scroll to after render
-	scrollToElement: string | null = null;
-	// variable for save options
+	/** Library version */
+	version: string = version;
+	/** Options passed into the instance */
 	options: Options;
-	// running plugin instances
+	/** Registered plugin instances */
 	plugins: Plugin[] = [];
-	// variable for current transition info object
-	transition: Transition = {};
-	// cache instance
+	/** Global context of the current visit */
+	context: Context;
+	/** Cache instance */
 	cache: Cache;
-	// allows us to compare the current and new path inside popStateHandler
+	/** Hook registry */
+	hooks: Hooks;
+	/** Animation class manager */
+	classes: Classes;
+	/** URL of the currently visible page */
 	currentPageUrl = getCurrentUrl();
-	// variable for keeping event listeners from "delegate"
-	delegatedListeners: DelegatedListeners = {};
-	// so we are able to remove the listener
-	boundPopStateHandler: (event: PopStateEvent) => void;
+	/** Index of the current history entry */
+	currentHistoryIndex = 1;
+	/** Delegated event subscription handle */
+	private clickDelegate?: DelegateEventUnsubscribe;
 
-	loadPage = loadPage;
-	performPageLoad = performPageLoad;
+	visit = visit;
+	performVisit = performVisit;
 	leavePage = leavePage;
 	renderPage = renderPage;
 	replaceContent = replaceContent;
 	enterPage = enterPage;
-	triggerEvent = triggerEvent;
 	delegateEvent = delegateEvent;
-	on = on;
-	off = off;
-	updateTransition = updateTransition;
-	shouldSkipTransition = shouldSkipTransition;
-	getAnimationPromises = getAnimationPromises;
-	getPageData = getPageData;
 	fetchPage = fetchPage;
+	awaitAnimations = awaitAnimations;
 	getAnchorElement = getAnchorElement;
-	log: (message: string, context?: any) => void = () => {}; // here so it can be used by plugins
 	use = use;
 	unuse = unuse;
 	findPlugin = findPlugin;
 	getCurrentUrl = getCurrentUrl;
-	cleanupAnimationClasses = cleanupAnimationClasses;
+	createContext = createContext;
+	log: (message: string, context?: any) => void = () => {}; // here so it can be used by plugins
 
+	/** Default options before merging user options */
 	defaults: Options = {
 		animateHistoryBrowsing: false,
 		animationSelector: '[class*="transition-"]',
+		animationScope: 'html',
 		cache: true,
 		containers: ['#swup'],
 		ignoreVisit: (url, { el, event } = {}) => !!el?.closest('[data-no-swup]'),
@@ -128,7 +97,7 @@ export default class Swup {
 		resolveUrl: (url) => url,
 		requestHeaders: {
 			'X-Requested-With': 'swup',
-			Accept: 'text/html, application/xhtml+xml'
+			'Accept': 'text/html, application/xhtml+xml'
 		},
 		skipPopStateHandling: (event) => event.state?.source !== 'swup'
 	};
@@ -137,28 +106,35 @@ export default class Swup {
 		// Merge defaults and options
 		this.options = { ...this.defaults, ...options };
 
-		this.boundPopStateHandler = this.popStateHandler.bind(this);
+		this.linkClickHandler = this.linkClickHandler.bind(this);
+		this.popStateHandler = this.popStateHandler.bind(this);
 
 		this.cache = new Cache(this);
+		this.classes = new Classes(this);
+		this.hooks = new Hooks(this);
+		this.context = this.createContext({ to: undefined });
+
+		if (!this.checkRequirements()) {
+			return;
+		}
 
 		this.enable();
 	}
 
-	enable() {
-		// Check for Promise support
+	checkRequirements() {
 		if (typeof Promise === 'undefined') {
 			console.warn('Promise is not supported');
-			return;
+			return false;
 		}
+		return true;
+	}
 
-		// Add event listeners
-		this.delegatedListeners.click = delegateEvent(
-			this.options.linkSelector,
-			'click',
-			this.linkClickHandler.bind(this)
-		);
+	async enable() {
+		// Add event listener
+		const { linkSelector } = this.options;
+		this.clickDelegate = this.delegateEvent(linkSelector, 'click', this.linkClickHandler);
 
-		window.addEventListener('popstate', this.boundPopStateHandler);
+		window.addEventListener('popstate', this.popStateHandler);
 
 		// Initial save to cache
 		if (this.options.cache) {
@@ -166,53 +142,45 @@ export default class Swup {
 			// https://github.com/swup/swup/issues/475
 		}
 
-		// Mark swup blocks in html
-		markSwupElements(document.documentElement, this.options.containers);
-
 		// Mount plugins
 		this.options.plugins.forEach((plugin) => this.use(plugin));
 
 		// Modify initial history record
-		updateHistoryRecord();
+		updateHistoryRecord(null, { index: 1 });
 
-		// Trigger enabled event
-		this.triggerEvent('enabled');
+		// Trigger enable hook
+		await this.hooks.trigger('enable', undefined, () => {
+			// Add swup-enabled class to html tag
+			document.documentElement.classList.add('swup-enabled');
+		});
 
-		// Add swup-enabled class to html tag
-		document.documentElement.classList.add('swup-enabled');
+		await nextTick();
 
-		// Trigger page view event
-		this.triggerEvent('pageView');
+		// Trigger page view hook
+		await this.hooks.trigger('page:view', { url: this.currentPageUrl, title: document.title });
 	}
 
-	destroy() {
-		// remove delegated listeners
-		this.delegatedListeners.click!.destroy();
+	async destroy() {
+		// remove delegated listener
+		this.clickDelegate!.destroy();
 
 		// remove popstate listener
-		window.removeEventListener('popstate', this.boundPopStateHandler);
+		window.removeEventListener('popstate', this.popStateHandler);
 
 		// empty cache
-		this.cache.empty();
+		this.cache.clear();
 
 		// unmount plugins
-		this.options.plugins.forEach((plugin) => {
-			this.unuse(plugin);
-		});
+		this.options.plugins.forEach((plugin) => this.unuse(plugin));
 
-		// remove swup data atributes from blocks
-		queryAll('[data-swup]').forEach((element) => {
-			element.removeAttribute('data-swup');
+		// trigger disable hook
+		await this.hooks.trigger('disable', undefined, () => {
+			// remove swup-enabled class from html tag
+			document.documentElement.classList.remove('swup-enabled');
 		});
 
 		// remove handlers
-		this.off();
-
-		// trigger disable event
-		this.triggerEvent('disabled');
-
-		// remove swup-enabled class from html tag
-		document.documentElement.classList.remove('swup-enabled');
+		this.hooks.clear();
 	}
 
 	shouldIgnoreVisit(href: string, { el, event }: { el?: Element; event?: Event } = {}) {
@@ -238,17 +206,36 @@ export default class Swup {
 	}
 
 	linkClickHandler(event: DelegateEvent<MouseEvent>) {
-		const linkEl = event.delegateTarget;
-		const { href, url, hash } = Location.fromElement(linkEl as HTMLAnchorElement);
+		const el = event.delegateTarget as HTMLAnchorElement;
+		const { href, url, hash } = Location.fromElement(el);
+
+		// Get the animation name, if specified
+		const animation = el.getAttribute('data-swup-animation') || undefined;
+
+		// Get the history action, if specified
+		let historyAction: HistoryAction | undefined;
+		const historyAttr = el.getAttribute('data-swup-history');
+		if (historyAttr && ['push', 'replace'].includes(historyAttr)) {
+			historyAction = historyAttr as HistoryAction;
+		}
 
 		// Exit early if the link should be ignored
-		if (this.shouldIgnoreVisit(href, { el: linkEl, event })) {
+		if (this.shouldIgnoreVisit(href, { el, event })) {
 			return;
 		}
 
+		this.context = this.createContext({
+			to: url,
+			hash,
+			animation,
+			el,
+			event,
+			action: historyAction
+		});
+
 		// Exit early if control key pressed
 		if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
-			this.triggerEvent('openPageInNewTab', event);
+			this.hooks.trigger('link:newtab', { href });
 			return;
 		}
 
@@ -257,53 +244,42 @@ export default class Swup {
 			return;
 		}
 
-		this.triggerEvent('clickLink', event);
-		event.preventDefault();
-
-		// Handle links to the same page and exit early, where applicable
-		if (!url || url === getCurrentUrl()) {
-			this.handleLinkToSamePage(url, hash, event);
-			return;
-		}
-
-		// Exit early if the resolved path hasn't changed
-		if (this.isSameResolvedUrl(url, getCurrentUrl())) return;
-
-		// Store the element that should be scrolled to after loading the next page
-		this.scrollToElement = hash || null;
+		this.hooks.triggerSync('link:click', { el, event }, () => {
+			const from = this.context.from.url ?? '';
 
-		// Get the custom transition name, if present
-		const customTransition = linkEl.getAttribute('data-swup-transition') || undefined;
-
-		// Get the history action, if set
-		let history: HistoryAction | undefined;
-		const historyAttr = linkEl.getAttribute('data-swup-history');
-		if (historyAttr && ['push', 'replace'].includes(historyAttr)) {
-			history = historyAttr as HistoryAction;
-		}
-
-		// Finally, proceed with loading the page
-		this.performPageLoad({ url, customTransition, history });
-	}
-
-	handleLinkToSamePage(url: string, hash: string, event: DelegateEvent<MouseEvent>) {
-		// Emit event and exit early if the url points to the same page without hash
-		if (!hash) {
-			this.triggerEvent('samePage', event);
-			return;
-		}
-
-		// link to the same URL with hash
-		this.triggerEvent('samePageWithHash', event);
-
-		const element = getAnchorElement(hash);
-
-		// Warn and exit early if no matching element was found for the hash
-		if (!element) {
-			return console.warn(`Element for offset not found (#${hash})`);
-		}
+			event.preventDefault();
 
-		updateHistoryRecord(url + hash);
+			// Handle links to the same page: with or without hash
+			if (!url || url === from) {
+				if (hash) {
+					updateHistoryRecord(url + hash);
+					this.hooks.triggerSync(
+						'link:anchor',
+						{ hash, options: { behavior: 'auto' } },
+						(context, { hash, options }) => {
+							const target = this.getAnchorElement(hash);
+							if (target) {
+								target.scrollIntoView(options);
+							}
+						}
+					);
+				} else {
+					this.hooks.triggerSync('link:self', undefined, (context) => {
+						if (!context.scroll.reset) return;
+						window.scroll({ top: 0, left: 0, behavior: 'auto' });
+					});
+				}
+				return;
+			}
+
+			// Exit early if the resolved path hasn't changed
+			if (this.isSameResolvedUrl(url, from)) {
+				return;
+			}
+
+			// Finally, proceed with loading the page
+			this.performVisit(url);
+		});
 	}
 
 	triggerWillOpenNewWindow(triggerEl: Element) {
@@ -314,6 +290,8 @@ export default class Swup {
 	}
 
 	popStateHandler(event: PopStateEvent) {
+		const href = event.state?.url ?? location.href;
+
 		// Exit early if this event should be ignored
 		if (this.options.skipPopStateHandling(event)) {
 			return;
@@ -324,29 +302,41 @@ export default class Swup {
 			return;
 		}
 
-		const href = event.state?.url ?? location.href;
-
 		// Exit early if the link should be ignored
 		if (this.shouldIgnoreVisit(href, { event })) {
 			return;
 		}
 
 		const { url, hash } = Location.fromUrl(href);
+		const animate = this.options.animateHistoryBrowsing;
+		const resetScroll = this.options.animateHistoryBrowsing;
+
+		this.context = this.createContext({
+			to: url,
+			hash,
+			event,
+			animate,
+			resetScroll
+		});
 
-		if (hash) {
-			this.scrollToElement = hash;
-		} else {
-			event.preventDefault();
-		}
-
-		this.triggerEvent('popState', event);
+		// Mark as popstate visit
+		this.context.history.popstate = true;
 
-		if (!this.options.animateHistoryBrowsing) {
-			document.documentElement.classList.remove('is-animating');
-			cleanupAnimationClasses();
+		// Determine direction of history visit
+		const index = Number(event.state?.index);
+		if (index) {
+			const direction = index - this.currentHistoryIndex > 0 ? 'forwards' : 'backwards';
+			this.context.history.direction = direction;
 		}
 
-		this.performPageLoad({ url, event });
+		// Does this even do anything?
+		// if (!hash) {
+		// 	event.preventDefault();
+		// }
+
+		this.hooks.triggerSync('history:popstate', { event }, () => {
+			this.performVisit(url);
+		});
 	}
 
 	/**

package/src/__test__/index.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, it, vi } from 'vitest';
 
 import pckg from '../../package.json';
 import Swup, { Options, Plugin } from '../index.js';
+import * as SwupTS from '../Swup.js';
 
 const baseUrl = window.location.origin;
 
@@ -37,7 +38,7 @@ describe('Exports', () => {
 			resolveUrl: (url) => url,
 			requestHeaders: {
 				'X-Requested-With': 'swup',
-				Accept: 'text/html, application/xhtml+xml'
+				'Accept': 'text/html, application/xhtml+xml'
 			},
 			skipPopStateHandling: (event) => event.state?.source !== 'swup'
 		};
@@ -51,6 +52,10 @@ describe('Exports', () => {
 		expect(swup.version).not.toBeUndefined();
 		expect(swup.version).toEqual(pckg.version);
 	});
+
+	it('UMD compatibility: Swup.ts should only have a default export', () => {
+		expect(Object.keys(SwupTS)).toEqual(['default']);
+	});
 });
 
 describe('ignoreVisit', () => {
@@ -79,10 +84,10 @@ describe('ignoreVisit', () => {
 		);
 	});
 
-	it('should be called from loadPage method', () => {
+	it('should be called from visit method', () => {
 		const ignoreVisit = vi.fn(() => true);
 		const swup = new Swup({ ignoreVisit });
-		swup.loadPage({ url: '/path/' });
+		swup.visit('/path/');
 
 		expect(ignoreVisit.mock.calls).toHaveLength(1);
 	});

package/src/helpers/Location.ts

@@ -5,30 +5,33 @@
  */
 
 export class Location extends URL {
-	constructor(url: string, base: string = document.baseURI) {
+	constructor(url: URL | string, base: string = document.baseURI) {
 		super(url.toString(), base);
 	}
 
-	get url() {
+	/**
+	 * The full local path including query params.
+	 */
+	get url(): string {
 		return this.pathname + this.search;
 	}
 
 	/**
 	 * Instantiate a Location from an element's href attribute
-	 * @param {Element} el
-	 * @return new Location instance
+	 * @param el
+	 * @returns new Location instance
 	 */
-	static fromElement(el: HTMLAnchorElement): Location {
-		const href = el.getAttribute('href') || el.getAttribute('xlink:href');
+	static fromElement(el: Element): Location {
+		const href = el.getAttribute('href') || el.getAttribute('xlink:href') || '';
 		return new Location(href!);
 	}
 
 	/**
 	 * Instantiate a Location from a URL object or string
-	 * @param {URL|string} url
-	 * @return new Location instance
+	 * @param url
+	 * @returns new Location instance
 	 */
-	static fromUrl(url: string): Location {
+	static fromUrl(url: URL | string): Location {
 		return new Location(url);
 	}
 }

package/src/helpers/__test__/matchPath.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+import { matchPath } from '../../index.js';
+import { pathToRegexp } from 'path-to-regexp';
+
+describe('matchPath', () => {
+	it('should return false if not matching', () => {
+		const urlMatch = matchPath('/users/:user');
+		const match = urlMatch('/posts/');
+		expect(match).toBe(false);
+	});
+
+	it('should return an object if matching', () => {
+		const urlMatch = matchPath('/users/:user');
+		const match = urlMatch('/users/bob');
+		expect(match).toEqual({
+			path: '/users/bob',
+			index: 0,
+			params: { user: 'bob' }
+		});
+	});
+
+	it('should work with primitive strings', () => {
+		const urlMatch = matchPath<{ user: string }>('/users/:user');
+		const match = urlMatch('/users/bob');
+		const params = !match ? false : match.params;
+		expect(params).toEqual({ user: 'bob' });
+	});
+
+	it('should work with an array of paths', () => {
+		const urlMatch = matchPath<{ user: string }>(['/users/', '/users/:user']);
+
+		const { params: withParams } = urlMatch('/users/bob') || {};
+		expect(withParams).toEqual({ user: 'bob' });
+
+		const { params: withoutParams } = urlMatch('/users/') || {};
+		expect(withoutParams).toEqual({});
+	});
+
+	/**
+	 * When passing a regex to `match`, the params in the response are sorted by appearance.
+	 * Only helpful for falsy/truthy detection
+	 */
+	it('should work with regex', () => {
+		const re = pathToRegexp('/users/:user');
+		const urlMatch = matchPath(re);
+		const { params } = urlMatch('/users/bob') || {};
+		expect(params).toEqual({ '0': 'bob' });
+	});
+
+	it('should throw with malformed paths', () => {
+		// prettier-ignore
+		expect(() => matchPath('/\?user=:user')).toThrowError('[swup] Error parsing path');
+	});
+});

package/src/helpers/delegateEvent.ts

@@ -1,7 +1,7 @@
 import delegate, { DelegateEventHandler, DelegateOptions, EventType } from 'delegate-it';
 import { ParseSelector } from 'typed-query-selector/parser.js';
 
-export type Unsubscribe = {
+export type DelegateEventUnsubscribe = {
 	destroy: () => void;
 };
 
@@ -10,8 +10,9 @@ export const delegateEvent = <Selector extends string, TEvent extends EventType>
 	type: TEvent,
 	callback: DelegateEventHandler<GlobalEventHandlersEventMap[TEvent]>,
 	options?: DelegateOptions
-): Unsubscribe => {
+): DelegateEventUnsubscribe => {
 	const controller = new AbortController();
+	options = { ...options, signal: controller.signal };
 	delegate<string, ParseSelector<Selector, HTMLElement>, TEvent>(
 		selector,
 		type,

package/src/helpers/matchPath.ts

@@ -0,0 +1,22 @@
+import { match } from 'path-to-regexp';
+
+import type {
+	Path,
+	ParseOptions,
+	TokensToRegexpOptions,
+	RegexpToFunctionOptions,
+	MatchFunction
+} from 'path-to-regexp';
+
+export { Path };
+
+export const matchPath = <P extends object = object>(
+	path: Path,
+	options?: ParseOptions & TokensToRegexpOptions & RegexpToFunctionOptions
+): MatchFunction<P> => {
+	try {
+		return match<P>(path, options);
+	} catch (error) {
+		throw new Error(`[swup] Error parsing path "${path}":\n${error}`);
+	}
+};