swup 3.1.1 → 4.0.0-rc.20

package/src/modules/leavePage.ts

@@ -1,27 +1,33 @@
 import Swup from '../Swup.js';
-import { PageRenderOptions } from './renderPage.js';
+import { classify } from '../helpers.js';
 
-export const leavePage = function (this: Swup, { event, skipTransition }: PageRenderOptions = {}) {
-	const isHistoryVisit = event instanceof PopStateEvent;
-
-	if (skipTransition) {
-		this.triggerEvent('animationSkipped');
-		return [Promise.resolve()];
+/**
+ * Perform the out/leave animation of the current page.
+ * @returns Promise<void>
+ */
+export const leavePage = async function (this: Swup) {
+	if (!this.context.animation.animate) {
+		await this.hooks.trigger('animation:skip');
+		return;
 	}
 
-	this.triggerEvent('animationOutStart');
-
-	// handle classes
-	document.documentElement.classList.add('is-changing', 'is-leaving', 'is-animating');
-	if (isHistoryVisit) {
-		document.documentElement.classList.add('is-popstate');
-	}
-
-	// animation promise stuff
-	const animationPromises: Promise<void>[] = this.getAnimationPromises('out');
-	Promise.all(animationPromises).then(() => {
-		this.triggerEvent('animationOutDone');
+	await this.hooks.trigger('animation:out:start', undefined, () => {
+		this.classes.add('is-changing', 'is-leaving', 'is-animating');
+		if (this.context.history.popstate) {
+			this.classes.add('is-popstate');
+		}
+		if (this.context.animation.name) {
+			this.classes.add(`to-${classify(this.context.animation.name)}`);
+		}
 	});
 
-	return animationPromises;
+	await this.hooks.trigger(
+		'animation:await',
+		{ direction: 'out' },
+		async (context, { direction }) => {
+			await this.awaitAnimations({ selector: context.animation.selector, direction });
+		}
+	);
+
+	await this.hooks.trigger('animation:out:end');
 };

package/src/modules/plugins.ts

@@ -1,16 +1,21 @@
 import Swup from '../Swup.js';
 
 export type Plugin = {
+	/** Name of this plugin */
 	name: string;
+	/** Identify as a swup plugin */
 	isSwupPlugin: true;
+	/** Run on mount */
 	mount: () => void;
+	/** Run on unmount */
 	unmount: () => void;
 
-	// the instance is assigned later on after passing to swup
+	/** The swup instance that mounted this plugin */
 	swup?: Swup;
 
-	// these are possibly undefined for backward compatibility
+	/** Version of this plugin. Currently not in use, defined here for backward compatiblity. */
 	version?: string;
+	/** Version requirements of this plugin. Example: `{ swup: '>=4' }` */
 	requires?: Record<string, string>;
 	_beforeMount?: () => void;
 	_afterUnmount?: () => void;

package/src/modules/renderPage.ts

@@ -1,53 +1,72 @@
-import { Location, updateHistoryRecord, getCurrentUrl } from '../helpers.js';
+import { updateHistoryRecord, getCurrentUrl, classify } from '../helpers.js';
 import Swup from '../Swup.js';
-import { PageRecord } from './Cache.js';
+import { PageData } from './fetchPage.js';
 
-export type PageRenderOptions = {
-	event?: PopStateEvent;
-	skipTransition?: boolean;
-};
+/**
+ * Render the next page: replace the content and update scroll position.
+ * @returns Promise<void>
+ */
+export const renderPage = async function (this: Swup, requestedUrl: string, page: PageData) {
+	const { url, html } = page;
 
-export const renderPage = function (
-	this: Swup,
-	page: PageRecord,
-	{ event, skipTransition }: PageRenderOptions = {}
-) {
-	document.documentElement.classList.remove('is-leaving');
+	this.classes.remove('is-leaving');
 
 	// do nothing if another page was requested in the meantime
-	if (!this.isSameResolvedUrl(getCurrentUrl(), page.url)) {
+	if (!this.isSameResolvedUrl(getCurrentUrl(), requestedUrl)) {
 		return;
 	}
 
-	const { url } = Location.fromUrl(page.responseURL);
-
-	// update cache and state if the url was redirected
+	// update state if the url was redirected
 	if (!this.isSameResolvedUrl(getCurrentUrl(), url)) {
-		this.cache.cacheUrl({ ...page, url });
-		this.currentPageUrl = getCurrentUrl();
 		updateHistoryRecord(url);
+		this.currentPageUrl = getCurrentUrl();
+		this.context.to.url = this.currentPageUrl;
 	}
 
-	// only add for page loads with transitions
-	if (!skipTransition) {
-		document.documentElement.classList.add('is-rendering');
+	// only add for animated page loads
+	if (this.context.animation.animate) {
+		this.classes.add('is-rendering');
 	}
 
-	this.triggerEvent('willReplaceContent', event);
+	// save html into context for easier retrieval
+	this.context.to.html = html;
 
-	this.replaceContent(page).then(() => {
-		this.triggerEvent('contentReplaced', event);
-		this.triggerEvent('pageView', event);
+	// replace content: allow handlers and plugins to overwrite paga data and containers
+	await this.hooks.trigger('content:replace', { page }, (context, { page }) => {
+		const success = this.replaceContent(page, { containers: context.containers });
+		if (!success) {
+			throw new Error('[swup] Container mismatch, aborting');
+		}
+		if (this.context.animation.animate) {
+			// Make sure to add these classes to new containers as well
+			this.classes.add('is-animating', 'is-changing', 'is-rendering');
+			if (this.context.animation.name) {
+				this.classes.add(`to-${classify(this.context.animation.name)}`);
+			}
+		}
+	});
 
-		// empty cache if it's disabled (in case preload plugin filled it)
-		if (!this.options.cache) {
-			this.cache.empty();
+	await this.hooks.trigger(
+		'content:scroll',
+		{ options: { behavior: 'auto' } },
+		(context, { options }) => {
+			if (this.context.scroll.target) {
+				const target = this.getAnchorElement(this.context.scroll.target);
+				if (target) {
+					target.scrollIntoView(options);
+					return;
+				}
+			}
+			if (this.context.scroll.reset) {
+				window.scrollTo(0, 0);
+			}
 		}
+	);
 
-		// Perform in transition
-		this.enterPage({ event, skipTransition });
+	await this.hooks.trigger('page:view', { url: this.currentPageUrl, title: document.title });
 
-		// reset scroll-to element
-		this.scrollToElement = null;
-	});
+	// empty cache if it's disabled (in case preload plugin filled it)
+	if (!this.options.cache) {
+		this.cache.clear();
+	}
 };

package/src/modules/replaceContent.ts

@@ -1,26 +1,43 @@
+import Swup, { Options } from '../Swup.js';
+import { PageData } from './fetchPage.js';
+
 /**
  * Perform the replacement of content after loading a page.
  *
- * This method can be replaced or augmented by plugins to allow pausing.
- *
- * It takes an object with the page data as return from `getPageData` and has to
- * return a Promise that resolves once all content has been replaced and the
- * site is ready to start animating in the new page.
+ * It takes an object with the page data as returned from `fetchPage` and a list
+ * of container selectors to replace.
  *
- * @param {object} page The page object
- * @returns Promise
+ * @returns Whether all containers were replaced.
  */
-export const replaceContent = function ({ blocks, title }: { blocks: string[]; title: string }) {
-	// Replace content blocks
-	blocks.forEach((html, i) => {
-		// we know the block exists at this point
-		const block = document.body.querySelector(`[data-swup="${i}"]`)!;
-		block.outerHTML = html;
-	});
+export const replaceContent = function (
+	this: Swup,
+	{ html }: PageData,
+	{ containers }: { containers: Options['containers'] } = this.options
+): boolean {
+	const incomingDocument = new DOMParser().parseFromString(html, 'text/html');
 
 	// Update browser title
+	const title = incomingDocument.querySelector('title')?.innerText || '';
 	document.title = title;
 
-	// Return a Promise to allow plugins to defer
-	return Promise.resolve();
+	// Update content containers
+	const replaced = containers
+		.map((selector) => {
+			const currentEl = document.querySelector(selector);
+			const incomingEl = incomingDocument.querySelector(selector);
+			if (currentEl && incomingEl) {
+				currentEl.replaceWith(incomingEl);
+				return true;
+			}
+			if (!currentEl) {
+				console.warn(`[swup] Container missing in current document: ${selector}`);
+			}
+			if (!incomingEl) {
+				console.warn(`[swup] Container missing in incoming document: ${selector}`);
+			}
+			return false;
+		})
+		.filter(Boolean);
+
+	return replaced.length === containers.length;
 };

package/src/modules/visit.ts

@@ -0,0 +1,143 @@
+import Swup from '../Swup.js';
+import { createHistoryRecord, updateHistoryRecord, getCurrentUrl, Location } from '../helpers.js';
+import { FetchOptions } from './fetchPage.js';
+import { ContextInitOptions } from './Context.js';
+
+export type HistoryAction = 'push' | 'replace';
+export type HistoryDirection = 'forwards' | 'backwards';
+
+type VisitOptions = {
+	/** Whether this visit is animated. Default: `true` */
+	animate?: boolean;
+	/** Name of a custom animation to run. */
+	animation?: string;
+	/** History action to perform: `push` for creating a new history entry, `replace` for replacing the current entry. Default: `push` */
+	history?: HistoryAction;
+};
+
+/**
+ * Navigate to a new URL.
+ * @param url The URL to navigate to.
+ * @param options Options for how to perform this visit.
+ * @returns Promise<void>
+ */
+export function visit(
+	this: Swup,
+	url: string,
+	options: VisitOptions & FetchOptions = {},
+	context: Omit<ContextInitOptions, 'to'> = {}
+) {
+	// Check if the visit should be ignored
+	if (this.shouldIgnoreVisit(url)) {
+		window.location.href = url;
+		return;
+	}
+
+	const { url: to, hash } = Location.fromUrl(url);
+	this.context = this.createContext({ ...context, to, hash });
+	this.performVisit(to, options);
+}
+
+/**
+ * Start a visit to a new URL.
+ *
+ * Internal method that assumes the global context has already been set up.
+ *
+ * As a user, you should call `swup.visit(url)` instead.
+ *
+ * @param url The URL to navigate to.
+ * @param options Options for how to perform this visit.
+ * @returns Promise<void>
+ */
+export async function performVisit(
+	this: Swup,
+	url: string,
+	options: VisitOptions & FetchOptions = {}
+) {
+	if (typeof url !== 'string') {
+		throw new Error(`swup.visit() requires a URL parameter`);
+	}
+
+	this.context.to.url = Location.fromUrl(url).url;
+	const { animation, animate, history: historyAction } = options;
+	options.referrer = options.referrer || this.currentPageUrl;
+
+	if (animate === false) {
+		this.context.animation.animate = false;
+	}
+	if (historyAction) {
+		this.context.history.action = historyAction;
+	}
+
+	// Clean up old animation classes and set custom animation name
+	if (!this.context.animation.animate) {
+		this.classes.clear();
+	} else if (animation) {
+		this.context.animation.name = animation;
+	}
+
+	try {
+		await this.hooks.trigger('visit:start');
+
+		// Begin fetching page
+		const pagePromise = this.hooks.trigger(
+			'page:request',
+			{ url: this.context.to.url, options },
+			async (context, { options }) => await this.fetchPage(context.to.url as string, options)
+		);
+
+		// Create history record if this is not a popstate call (with or without anchor)
+		if (!this.context.history.popstate) {
+			const newUrl = url + (this.context.scroll.target || '');
+			if (this.context.history.action === 'replace') {
+				updateHistoryRecord(newUrl);
+			} else {
+				const index = this.currentHistoryIndex + 1;
+				createHistoryRecord(newUrl, { index });
+			}
+		}
+
+		this.currentPageUrl = getCurrentUrl();
+
+		// Wait for page before starting to animate out?
+		if (this.context.animation.wait) {
+			const { html } = await pagePromise;
+			this.context.to.html = html;
+		}
+
+		// Wait for page to load and leave animation to finish
+		const animationPromise = this.leavePage();
+		const [page] = await Promise.all([pagePromise, animationPromise]);
+
+		// Render page: replace content and scroll to top/fragment
+		await this.renderPage(this.context.to.url, page);
+
+		// Wait for enter animation
+		await this.enterPage();
+
+		// Finalize visit
+		await this.hooks.trigger('visit:end', undefined, () => this.classes.clear());
+
+		// Reset context after visit?
+		// if (this.context.to && this.isSameResolvedUrl(this.context.to.url, requestedUrl)) {
+		// 	this.createContext({ to: undefined });
+		// }
+	} catch (error: unknown) {
+		// Return early if error is undefined (probably aborted preload request)
+		if (!error) {
+			return;
+		}
+
+		// Log to console as we swallow almost all hook errors
+		console.error(error);
+
+		// Rewrite `skipPopStateHandling` to redirect manually when `history.go` is processed
+		this.options.skipPopStateHandling = () => {
+			window.location.href = this.context.to.url as string;
+			return true;
+		};
+
+		// Go back to the actual page we're still at
+		history.go(-1);
+	}
+}

package/src/utils/index.ts

@@ -9,21 +9,41 @@ export const queryAll = (
 	return Array.from(context.querySelectorAll(selector));
 };
 
-export const nextTick = (callback: () => void) => {
-	requestAnimationFrame(() => {
+export const nextTick = (): Promise<void> => {
+	return new Promise((resolve) => {
 		requestAnimationFrame(() => {
-			callback();
+			requestAnimationFrame(() => {
+				resolve();
+			});
 		});
 	});
 };
 
+export function isPromise<T>(obj: any): obj is PromiseLike<T> {
+	return (
+		!!obj &&
+		(typeof obj === 'object' || typeof obj === 'function') &&
+		typeof obj.then === 'function'
+	);
+}
+
+export function runAsPromise(func: Function, args: any[] = [], ctx: any = {}): Promise<any> {
+	return new Promise((resolve, reject) => {
+		const result = func.apply(ctx, args);
+		if (isPromise(result)) {
+			result.then(resolve, reject);
+		} else {
+			resolve(result);
+		}
+	});
+}
+
 export const escapeCssIdentifier = (ident: string) => {
 	// @ts-ignore this is for support check, so it's correct that TS complains
 	if (window.CSS && window.CSS.escape) {
 		return CSS.escape(ident);
-	} else {
-		return ident;
 	}
+	return ident;
 };
 
 // Fix for Chrome below v61 formatting CSS floats with comma in some locales

package/dist/types/helpers/cleanupAnimationClasses.d.ts

@@ -1,2 +0,0 @@
-export declare const isSwupClass: (className: string) => boolean;
-export declare const cleanupAnimationClasses: () => void;

package/dist/types/helpers/fetch.d.ts

@@ -1,5 +0,0 @@
-import { TransitionOptions } from '../modules/loadPage.js';
-import { Options } from '../Swup.js';
-export declare const fetch: (options: TransitionOptions & {
-    headers: Options['requestHeaders'];
-}, callback: (request: XMLHttpRequest) => void) => XMLHttpRequest;

package/dist/types/helpers/getDataFromHtml.d.ts

@@ -1,7 +0,0 @@
-export type PageHtmlData = {
-    title: string;
-    originalContent: string;
-    blocks: string[];
-    pageClass?: string;
-};
-export declare const getDataFromHtml: (html: string, containers: string[]) => PageHtmlData;

package/dist/types/helpers/markSwupElements.d.ts

@@ -1 +0,0 @@
-export declare const markSwupElements: (element: Element, containers: string[]) => void;

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

@@ -1,33 +0,0 @@
-import Swup from '../Swup.js';
-import { DelegateEvent } from 'delegate-it';
-type HandlersEventMap = {
-    animationInDone: undefined;
-    animationInStart: undefined;
-    animationOutDone: undefined;
-    animationOutStart: undefined;
-    animationSkipped: undefined;
-    clickLink: DelegateEvent<MouseEvent>;
-    contentReplaced: PopStateEvent | undefined;
-    disabled: undefined;
-    enabled: undefined;
-    openPageInNewTab: DelegateEvent<MouseEvent>;
-    pageLoaded: undefined;
-    pageRetrievedFromCache: undefined;
-    pageView: PopStateEvent | undefined;
-    popState: PopStateEvent;
-    samePage: DelegateEvent<MouseEvent>;
-    samePageWithHash: DelegateEvent<MouseEvent>;
-    serverError: undefined;
-    transitionStart: PopStateEvent | undefined;
-    transitionEnd: PopStateEvent | undefined;
-    willReplaceContent: PopStateEvent | undefined;
-};
-type AvailableEventNames = keyof HandlersEventMap;
-export type Handler<T extends keyof HandlersEventMap> = (event: HandlersEventMap[T]) => void;
-export type Handlers = {
-    [Key in keyof HandlersEventMap]: Handler<Key>[];
-};
-export declare function on<TEventType extends AvailableEventNames>(this: Swup, event: TEventType, handler: Handler<TEventType>): void;
-export declare function off<TEventType extends AvailableEventNames>(this: Swup, event?: TEventType, handler?: Handler<TEventType>): void;
-export declare function triggerEvent<TEventType extends AvailableEventNames>(this: Swup, eventName: TEventType, originalEvent?: HandlersEventMap[TEventType]): void;
-export {};

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

@@ -1,7 +0,0 @@
-import Swup from '../Swup.js';
-export declare function getAnimationPromises(this: Swup, animationType: 'in' | 'out'): Promise<void>[];
-export declare function getTransitionInfo(element: Element, expectedType?: 'animation' | 'transition' | null): {
-    type: string | null;
-    timeout: number;
-    propCount: number;
-};

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

@@ -1,6 +0,0 @@
-import Swup from '../Swup.js';
-import { PageHtmlData } from '../helpers/getDataFromHtml.js';
-export type PageData = PageHtmlData & {
-    responseURL: string;
-};
-export declare const getPageData: (this: Swup, request: XMLHttpRequest) => PageData | null;

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

@@ -1,15 +0,0 @@
-import Swup from '../Swup.js';
-export type HistoryAction = 'push' | 'replace';
-export type TransitionOptions = {
-    url: string;
-    customTransition?: string;
-    history?: HistoryAction;
-};
-export type PageLoadOptions = {
-    url: string;
-    customTransition?: string;
-    history?: HistoryAction;
-    event?: PopStateEvent;
-};
-export declare function loadPage(this: Swup, data: TransitionOptions): void;
-export declare function performPageLoad(this: Swup, data: PageLoadOptions): void;

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

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

package/readme.md

@@ -1,60 +0,0 @@
-<br>
-
-<p align="center">
-  <img width="280" alt="swup" src="https://swup.js.org/assets/images/swup-logo.svg">
-</p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/swup"><img src="https://img.shields.io/npm/v/swup.svg" alt="npm version"></a>
-  <a href="https://bundlephobia.com/package/swup"><img src="https://img.shields.io/bundlephobia/minzip/swup?label=size" alt="Bundle size"></a>
-  <a href="https://github.com/gmrchk/swup/blob/master/LICENSE"><img src="https://img.shields.io/github/license/gmrchk/swup.svg" alt="License"></a>
-  <a href="https://www.npmjs.com/package/swup"><img src="https://img.shields.io/npm/dt/swup.svg" alt="npm downloads"></a>
-  <a href="https://github.com/swup/swup/actions/workflows/e2e-tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/swup/swup/e2e-tests.yml?branch=master&label=tests" alt="Test status"></a>
-</p>
-
-<br>
-
-# Swup
-
-Complete, flexible, extensible, and easy-to-use page transition library for your server-side rendered website.
-
-[Features](#features) •
-[Documentation](https://swup.js.org/getting-started) •
-[Plugins](https://swup.js.org/plugins) •
-[Themes](https://swup.js.org/themes) •
-[Discussions](https://github.com/swup/swup/discussions)
-
-## 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.
-
-Its goal is to make adding transitions to a site as simple as possible, 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
-
-## Examples
-
-<img src="https://user-images.githubusercontent.com/9338324/49190360-50125480-f372-11e8-89e9-d2fb091a2240.gif" width="100%">
-
-Take a look at [Sites using swup](https://github.com/swup/swup/discussions/333) for more examples.
-
-## Having trouble?
-
-If you're having trouble implementing swup, check out the [Common Issues](https://swup.js.org/other/common-issues) section of the docs, look at [closed issues](https://github.com/gmrchk/swup/issues?q=is%3Aissue+is%3Aclosed) or create a [new discussion](https://github.com/swup/swup/discussions/new).
-
-## Want to Contribute?
-
-<a href="https://github.com/swup/swup/discussions/424">We're looking for maintainers!</a>   👀
-
-Become a sponsor on [Open Collective](https://opencollective.com/swup) or support development through
-[GitHub sponsors](https://github.com/sponsors/gmrchk).

package/src/helpers/cleanupAnimationClasses.ts

@@ -1,8 +0,0 @@
-export const isSwupClass = (className: string): boolean =>
-	/^to-/.test(className) || ['is-changing', 'is-rendering', 'is-popstate'].includes(className);
-
-export const cleanupAnimationClasses = (): void => {
-	const htmlClasses = document.documentElement.className.split(' ');
-	const removeClasses = htmlClasses.filter(isSwupClass);
-	document.documentElement.classList.remove(...removeClasses);
-};

package/src/helpers/fetch.ts

@@ -1,33 +0,0 @@
-import { TransitionOptions } from '../modules/loadPage.js';
-import { Options } from '../Swup.js';
-
-export const fetch = (
-	options: TransitionOptions & { headers: Options['requestHeaders'] },
-	callback: (request: XMLHttpRequest) => void
-): XMLHttpRequest => {
-	const defaults = {
-		url: window.location.pathname + window.location.search,
-		method: 'GET',
-		data: null,
-		headers: {}
-	};
-
-	const { url, method, headers, data } = { ...defaults, ...options };
-
-	const request = new XMLHttpRequest();
-
-	request.onreadystatechange = function () {
-		if (request.readyState === 4) {
-			// if (request.status === 500) {} else {}
-			callback(request);
-		}
-	};
-
-	request.open(method, url, true);
-	Object.entries(headers).forEach(([key, header]) => {
-		request.setRequestHeader(key, header);
-	});
-	request.send(data);
-
-	return request;
-};