swup 3.1.0 → 4.0.0-rc.14

package/dist/types/modules/off.d.ts

@@ -0,0 +1,3 @@
+import Swup from '../Swup';
+import { EventType, Handler } from './on';
+export declare const off: (this: Swup, event?: EventType, handler?: Handler) => void;

package/dist/types/modules/on.d.ts

@@ -0,0 +1,5 @@
+import Swup from '../Swup';
+export type EventType = 'animationInDone' | 'animationInStart' | 'animationOutDone' | 'animationOutStart' | 'animationSkipped' | 'clickLink' | 'contentReplaced' | 'disabled' | 'enabled' | 'openPageInNewTab' | 'pageLoaded' | 'pageRetrievedFromCache' | 'pageView' | 'popState' | 'samePage' | 'samePageWithHash' | 'serverError' | 'transitionStart' | 'transitionEnd' | 'willReplaceContent';
+export type Handler = (event?: Event) => void;
+export type Handlers = Record<EventType, Handler[]>;
+export declare const on: (this: Swup, event: EventType, handler: Handler) => void;

package/dist/types/modules/plugins.d.ts

@@ -1,4 +1,4 @@
-import Swup from '../Swup.js';
+import Swup from '../Swup';
 export type Plugin = {
     name: string;
     isSwupPlugin: true;

package/dist/types/modules/popStateHandler.d.ts

@@ -0,0 +1,2 @@
+import { InternalSwup } from '../Swup';
+export declare const popStateHandler: (this: InternalSwup, event: PopStateEvent) => void;

package/dist/types/modules/renderPage.d.ts

@@ -1,5 +1,5 @@
-import Swup from '../Swup.js';
-import { PageRecord } from './Cache.js';
+import Swup from '../Swup';
+import { PageRecord } from './Cache';
 export type PageRenderOptions = {
     event?: PopStateEvent;
     skipTransition?: boolean;

package/dist/types/modules/resolveUrl.d.ts

@@ -0,0 +1,7 @@
+import { InternalSwup } from '../Swup';
+/**
+ * Utility function to validate and run the global option 'resolveUrl'
+ * @param {string} url
+ * @returns {string} the resolved url
+ */
+export declare const resolveUrl: (this: InternalSwup, url: string) => string;

package/dist/types/modules/shouldIgnoreVisit.d.ts

@@ -0,0 +1,4 @@
+import { InternalSwup } from '../Swup';
+export declare const shouldIgnoreVisit: (this: InternalSwup, href: string, { el }?: {
+    el?: Element | undefined;
+}) => boolean;

package/dist/types/modules/transitions.d.ts

@@ -1,4 +1,4 @@
-import Swup from '../Swup.js';
+import Swup from '../Swup';
 export declare function updateTransition(this: Swup, from: string, to: string, custom?: string): void;
 export declare function shouldSkipTransition(this: Swup, { event }: {
     url?: string;

package/dist/types/modules/triggerEvent.d.ts

@@ -0,0 +1,3 @@
+import { EventType } from './on';
+import Swup from '../Swup';
+export declare const triggerEvent: (this: Swup, eventName: EventType, originalEvent?: PopStateEvent | MouseEvent) => void;

package/dist/types/modules/triggerWillOpenNewWindow.d.ts

@@ -0,0 +1,2 @@
+import { InternalSwup } from '../Swup';
+export declare const triggerWillOpenNewWindow: (this: InternalSwup, triggerEl: Element) => boolean;

package/dist/types/modules/updateTransition.d.ts

@@ -0,0 +1,2 @@
+import Swup from '../Swup';
+export declare const updateTransition: (this: Swup, from: string, to: string, custom?: string) => void;

package/dist/types/utils.d.ts

@@ -1 +1 @@
-export * from './utils/index.js';
+export * from './utils/index';

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "swup",
   "amdName": "Swup",
-  "version": "3.1.0",
-  "description": "Complete, flexible, extensible, and easy-to-use page transition library for your server-side rendered website.",
+  "version": "4.0.0-rc.14",
+  "description": "Versatile and extensible page transition library for server-side rendered websites",
   "type": "module",
   "source": "./src/Swup.ts",
   "main": "./dist/Swup.cjs",
@@ -34,6 +34,7 @@
     "test": "npm run test:unit && npm run test:e2e",
     "test:ci": "npm run test:unit && npm run test:e2e:ci",
     "test:unit": "vitest run --config ./vitest/vitest.config.ts",
+    "test:unit:watch": "vitest --config ./vitest/vitest.config.ts",
     "test:e2e": "start-server-and-test test:e2e:start 8274 cy:run",
     "test:e2e:ci": "start-server-and-test test:e2e:start 8274 cy:run:record",
     "test:e2e:dev": "start-server-and-test test:e2e:start 8274 cy:open",
@@ -59,7 +60,8 @@
   ],
   "dependencies": {
     "delegate-it": "^6.0.0",
-    "opencollective-postinstall": "^2.0.2"
+    "opencollective-postinstall": "^2.0.2",
+    "path-to-regexp": "^6.2.1"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.18.6",
@@ -70,11 +72,12 @@
     "http-server": "^14.1.1",
     "husky": "^8.0.0",
     "istanbul-lib-coverage": "^3.2.0",
+    "jsdom": "^22.1.0",
     "microbundle": "^0.15.0",
     "nyc": "^15.1.0",
     "prettier": "^2.8.2",
-    "start-server-and-test": "^1.14.0",
-    "vitest": "^0.29.8"
+    "start-server-and-test": "^2.0.0",
+    "vitest": "^0.31.2"
   },
   "collective": {
     "type": "opencollective",

package/readme.md

@@ -16,7 +16,7 @@
 
 # Swup
 
-Complete, flexible, extensible, and easy-to-use page transition library for your server-side rendered website.
+Versatile and extensible page transition library for server-side rendered websites
 
 [Features](#features) •
 [Documentation](https://swup.js.org/getting-started) •
@@ -26,21 +26,39 @@ Complete, flexible, extensible, and easy-to-use page transition library for your
 
 ## Overview
 
-Swup is a library that helps you add page transitions to server-side rendered websites. It handles
-the complete lifecycle of a page visit by intercepting link clicks, loading the new page in the
-background, replacing the content and transitioning between the old and the new page.
+Swup adds page transitions to server-side rendered websites. It manages the complete lifecycle of a
+page visit by intercepting link clicks,  loading the new page in the background and smoothly
+transitioning between the old and new content.
 
-Its goal is to make adding transitions to a site as simple as possible, while providing lots of
-other quality-of-life improvements.
+Its goal is to make it effortless to add page transitions to a site, while providing lots of other
+quality-of-life improvements.
 
 ## Features
 
-- ✨ Auto-detects [CSS transitions](https://swup.js.org/getting-started/how-it-works) for perfect timing
-- 🔗 Updates URLs and preserves native browser history behavior
-- 📦 Uses a [cache](https://swup.js.org/api/cache) to speed up subsequent page loads
-- 💡 Offers [events](https://swup.js.org/events) for hooking into the lifecycle
-- 🔌 Has a powerful [plugin system](https://swup.js.org/plugins) and many official and third-party plugins
-- 🎨 Provides ready-to-go [themes](https://swup.js.org/themes) to get started quickly
+- ✏️ Works out of the box with [minimal markup](https://swup.js.org/getting-started/example/)
+- ✨ Auto-detects [CSS transitions](https://swup.js.org/getting-started/how-it-works/) for perfect timing
+- 🔗 Updates URLs and preserves native [browser history](https://swup.js.org/options/#animatehistorybrowsing)
+- 🏓 Manages scroll position between pages and anchor jump links
+- 🚀 Uses a [cache](https://swup.js.org/api/cache/) to speed up subsequent page loads
+- 📡 Offers [hooks](https://swup.js.org/hooks/) to customize and extend the page load lifecycle
+- 🔌 Has a powerful [plugin system](https://swup.js.org/plugins/) and many official and third-party plugins
+- 🎨 Provides ready-to-go [themes](https://swup.js.org/themes/) to get started quickly
+
+## Plugins
+
+Swup is small by design. Extended features can be added via [plugins](https://swup.js.org/plugins/):
+
+- Display a [progress bar](https://swup.js.org/plugins/progress-plugin/) while loading
+- Enable [smooth scrolling](https://swup.js.org/plugins/scroll-plugin/) between visits
+- Update [meta tags and stylesheets](https://swup.js.org/plugins/head-plugin/) after page loads
+- Add support for [preloading pages](https://swup.js.org/plugins/preload-plugin/) in the background
+- Improve [accessibility](https://swup.js.org/plugins/a11y-plugin/) for screen readers
+- Perform your [animations in JS](https://swup.js.org/plugins/js-plugin/) instead of CSS transitions
+- Animate [form submissions](https://swup.js.org/plugins/forms-plugin/)
+- Get help in [debug mode](https://swup.js.org/plugins/debug-plugin/)
+
+Check out the list of [all official plugins](https://swup.js.org/plugins/) as well as
+[third-party integrations](https://swup.js.org/third-party-integrations/).
 
 ## Examples
 

package/src/Swup.ts

@@ -7,26 +7,22 @@ import {
 	delegateEvent,
 	getCurrentUrl,
 	Location,
-	markSwupElements,
 	updateHistoryRecord
 } from './helpers.js';
 import { Unsubscribe } from './helpers/delegateEvent.js';
 
 import { Cache } from './modules/Cache.js';
+import { Context, createContext } from './modules/Context.js';
 import { enterPage } from './modules/enterPage.js';
 import { getAnchorElement } from './modules/getAnchorElement.js';
 import { getAnimationPromises } from './modules/getAnimationPromises.js';
-import { getPageData } from './modules/getPageData.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 { Handler, HookName, Hooks } from './modules/Hooks.js';
 import { use, unuse, findPlugin, Plugin } from './modules/plugins.js';
 import { renderPage } from './modules/renderPage.js';
-import { updateTransition, shouldSkipTransition } from './modules/transitions.js';
-
-import { queryAll } from './utils.js';
 
 export type Transition = {
 	from?: string;
@@ -52,47 +48,21 @@ export type Options = {
 };
 
 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;
+	version: string = version;
 	// variable for save options
 	options: Options;
 	// running plugin instances
 	plugins: Plugin[] = [];
-	// variable for current transition info object
-	transition: Transition = {};
+	// context data
+	context: Context;
 	// cache instance
 	cache: Cache;
-	// allows us to compare the current and new path inside popStateHandler
-	currentPageUrl = getCurrentUrl();
+	// hook registry
+	hooks: Hooks;
 	// variable for keeping event listeners from "delegate"
 	delegatedListeners: DelegatedListeners = {};
-	// so we are able to remove the listener
-	boundPopStateHandler: (event: PopStateEvent) => void;
+	// allows us to compare the current and new path inside popStateHandler
+	currentPageUrl = getCurrentUrl();
 
 	loadPage = loadPage;
 	performPageLoad = performPageLoad;
@@ -100,14 +70,8 @@ export default class Swup {
 	renderPage = renderPage;
 	replaceContent = replaceContent;
 	enterPage = enterPage;
-	triggerEvent = triggerEvent;
 	delegateEvent = delegateEvent;
-	on = on;
-	off = off;
-	updateTransition = updateTransition;
-	shouldSkipTransition = shouldSkipTransition;
 	getAnimationPromises = getAnimationPromises;
-	getPageData = getPageData;
 	fetchPage = fetchPage;
 	getAnchorElement = getAnchorElement;
 	log: (message: string, context?: any) => void = () => {}; // here so it can be used by plugins
@@ -116,6 +80,7 @@ export default class Swup {
 	findPlugin = findPlugin;
 	getCurrentUrl = getCurrentUrl;
 	cleanupAnimationClasses = cleanupAnimationClasses;
+	createContext = createContext;
 
 	defaults: Options = {
 		animateHistoryBrowsing: false,
@@ -137,28 +102,34 @@ 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.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;
+	}
 
+	async enable() {
 		// Add event listeners
-		this.delegatedListeners.click = delegateEvent(
-			this.options.linkSelector,
-			'click',
-			this.linkClickHandler.bind(this)
-		);
+		const { linkSelector } = this.options;
+		this.delegatedListeners.click = delegateEvent(linkSelector, 'click', this.linkClickHandler);
 
-		window.addEventListener('popstate', this.boundPopStateHandler);
+		window.addEventListener('popstate', this.popStateHandler);
 
 		// Initial save to cache
 		if (this.options.cache) {
@@ -166,9 +137,6 @@ 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));
 
@@ -176,43 +144,36 @@ export default class Swup {
 		updateHistoryRecord();
 
 		// Trigger enabled event
-		this.triggerEvent('enabled');
-
-		// Add swup-enabled class to html tag
-		document.documentElement.classList.add('swup-enabled');
+		await this.hooks.trigger('enabled', undefined, () => {
+			// Add swup-enabled class to html tag
+			document.documentElement.classList.add('swup-enabled');
+		});
 
 		// Trigger page view event
-		this.triggerEvent('pageView');
+		await this.hooks.trigger('pageView', { url: this.currentPageUrl, title: document.title });
 	}
 
-	destroy() {
+	async destroy() {
 		// remove delegated listeners
 		this.delegatedListeners.click!.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 event
+		await this.hooks.trigger('disabled', 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 +199,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 transition name, if specified
+		const transition = el.getAttribute('data-swup-transition') || 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,
+			transition,
+			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('openPageInNewTab', { href });
 			return;
 		}
 
@@ -257,53 +237,41 @@ 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;
-		}
+		this.hooks.triggerSync('clickLink', { el, event }, () => {
+			const from = this.context.from?.url ?? '';
 
-		// 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;
-
-		// 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(
+						'samePageWithHash',
+						{ hash, options: { behavior: 'auto' } },
+						(context, { hash, options }) => {
+							const target = this.getAnchorElement(hash);
+							if (target) {
+								target.scrollIntoView(options);
+							}
+						}
+					);
+				} else {
+					this.hooks.triggerSync('samePage', undefined, () => {
+						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.performPageLoad(url, { transition, history: historyAction });
+		});
 	}
 
 	triggerWillOpenNewWindow(triggerEl: Element) {
@@ -314,6 +282,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 +294,31 @@ 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,
+			popstate: true
+		});
 
-		if (hash) {
-			this.scrollToElement = hash;
-		} else {
-			event.preventDefault();
-		}
-
-		this.triggerEvent('popState', event);
-
-		if (!this.options.animateHistoryBrowsing) {
-			document.documentElement.classList.remove('is-animating');
-			cleanupAnimationClasses();
-		}
+		// Does this even do anything?
+		// if (!hash) {
+		// 	event.preventDefault();
+		// }
 
-		this.performPageLoad({ url, event });
+		this.hooks.triggerSync('popState', { event }, () => {
+			this.performPageLoad(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;
 
@@ -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', () => {
@@ -82,7 +87,7 @@ describe('ignoreVisit', () => {
 	it('should be called from loadPage method', () => {
 		const ignoreVisit = vi.fn(() => true);
 		const swup = new Swup({ ignoreVisit });
-		swup.loadPage({ url: '/path/' });
+		swup.loadPage('/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
+	 * @param el
 	 * @return 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
+	 * @param url
 	 * @return new Location instance
 	 */
-	static fromUrl(url: string): Location {
+	static fromUrl(url: URL | string): Location {
 		return new Location(url);
 	}
 }