swup 2.0.18 → 3.0.0-rc.1

package/src/index.ts

@@ -0,0 +1,369 @@
+import delegate 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 Cache from './modules/Cache.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 loadPage from './modules/loadPage.js';
+import replaceContent from './modules/replaceContent.js';
+import off from './modules/off.js';
+import on, { Handlers } from './modules/on.js';
+import { use, unuse, findPlugin, Plugin } from './modules/plugins.js';
+import renderPage from './modules/renderPage.js';
+import triggerEvent from './modules/triggerEvent.js';
+import updateTransition from './modules/updateTransition.js';
+
+import { queryAll } from './utils.js';
+
+export type Transition = {
+	from?: string;
+	to?: string;
+	custom?: string;
+};
+
+type DelegatedListeners = {
+	click?: Unsubscribe;
+};
+
+export type Options = {
+	animateHistoryBrowsing: boolean;
+	animationSelector: string | false;
+	linkSelector: string;
+	cache: boolean;
+	containers: string[];
+	requestHeaders: Record<string, string>;
+	plugins: Plugin[];
+	skipPopStateHandling: (event: any) => boolean;
+	ignoreVisit: (href: string, { el }: { el?: Element }) => boolean;
+	resolveUrl: (url: string) => string;
+};
+
+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
+	options: Options;
+	// running plugin instances
+	plugins: Plugin[] = [];
+	// variable for current transition info object
+	transition: Transition = {};
+	// cache instance
+	cache: Cache;
+	// allows us to compare the current and new path inside popStateHandler
+	currentPageUrl = getCurrentUrl();
+	// variable for keeping event listeners from "delegate"
+	delegatedListeners: DelegatedListeners = {};
+	// so we are able to remove the listener
+	boundPopStateHandler: (event: PopStateEvent) => void;
+
+	loadPage = loadPage;
+	leavePage = leavePage;
+	renderPage = renderPage;
+	replaceContent = replaceContent;
+	enterPage = enterPage;
+	triggerEvent = triggerEvent;
+	delegateEvent = delegateEvent;
+	on = on;
+	off = off;
+	updateTransition = updateTransition;
+	getAnimationPromises = getAnimationPromises;
+	getPageData = getPageData;
+	fetchPage = fetchPage;
+	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;
+
+	defaults: Options = {
+		animateHistoryBrowsing: false,
+		animationSelector: '[class*="transition-"]',
+		cache: true,
+		containers: ['#swup'],
+		ignoreVisit: (href, { el } = {}) => !!el?.closest('[data-no-swup]'),
+		linkSelector: 'a[href]',
+		plugins: [],
+		resolveUrl: (url) => url,
+		requestHeaders: {
+			'X-Requested-With': 'swup',
+			Accept: 'text/html, application/xhtml+xml'
+		},
+		skipPopStateHandling: (event) => event.state?.source !== 'swup'
+	};
+
+	constructor(options: Partial<Options> = {}) {
+		// Merge defaults and options
+		this.options = { ...this.defaults, ...options };
+
+		this.boundPopStateHandler = this.popStateHandler.bind(this);
+
+		this.cache = new Cache(this);
+
+		this.enable();
+	}
+
+	enable() {
+		// Check for Promise support
+		if (typeof Promise === 'undefined') {
+			console.warn('Promise is not supported');
+			return;
+		}
+
+		// Add event listeners
+		this.delegatedListeners.click = delegateEvent(
+			this.options.linkSelector,
+			'click',
+			this.linkClickHandler.bind(this)
+		);
+
+		window.addEventListener('popstate', this.boundPopStateHandler);
+
+		// Initial save to cache
+		if (this.options.cache) {
+			// Disabled to avoid caching modified dom state: logic moved to preload plugin
+			// 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();
+
+		// Trigger enabled event
+		this.triggerEvent('enabled');
+
+		// Add swup-enabled class to html tag
+		document.documentElement.classList.add('swup-enabled');
+
+		// Trigger page view event
+		this.triggerEvent('pageView');
+	}
+
+	destroy() {
+		// remove delegated listeners
+		this.delegatedListeners.click!.destroy();
+
+		// remove popstate listener
+		window.removeEventListener('popstate', this.boundPopStateHandler);
+
+		// empty cache
+		this.cache.empty();
+
+		// unmount plugins
+		this.options.plugins.forEach((plugin) => {
+			this.unuse(plugin);
+		});
+
+		// remove swup data atributes from blocks
+		queryAll('[data-swup]').forEach((element) => {
+			element.removeAttribute('data-swup');
+		});
+
+		// remove handlers
+		this.off();
+
+		// trigger disable event
+		this.triggerEvent('disabled');
+
+		// remove swup-enabled class from html tag
+		document.documentElement.classList.remove('swup-enabled');
+	}
+
+	shouldIgnoreVisit(href: string, { el }: { el?: Element } = {}) {
+		const { origin } = Location.fromUrl(href);
+
+		// Ignore if the new URL's origin doesn't match the current one
+		if (origin !== window.location.origin) {
+			return true;
+		}
+
+		// Ignore if the link/form would open a new window (or none at all)
+		if (el && this.triggerWillOpenNewWindow(el)) {
+			return true;
+		}
+
+		// Ignore if the visit should be ignored as per user options
+		if (this.options.ignoreVisit(href, { el })) {
+			return true;
+		}
+
+		// Finally, allow the visit
+		return false;
+	}
+
+	linkClickHandler(event: delegate.Event<MouseEvent>) {
+		const linkEl = event.delegateTarget;
+		const { href, url, hash } = Location.fromElement(linkEl as HTMLAnchorElement);
+
+		// Exit early if the link should be ignored
+		if (this.shouldIgnoreVisit(href, { el: linkEl })) {
+			return;
+		}
+
+		// Exit early if control key pressed
+		if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+			this.triggerEvent('openPageInNewTab', event);
+			return;
+		}
+
+		// Exit early if other than left mouse button
+		if (event.button !== 0) {
+			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;
+
+		// Get the custom transition name, if present
+		const customTransition = linkEl.getAttribute('data-swup-transition') || undefined;
+
+		// Finally, proceed with loading the page
+		this.loadPage({ url, customTransition }, null);
+	}
+
+	handleLinkToSamePage(url: string, hash: string, event: 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})`);
+		}
+
+		updateHistoryRecord(url + hash);
+	}
+
+	triggerWillOpenNewWindow(triggerEl: Element) {
+		if (triggerEl.matches('[download], [target="_blank"]')) {
+			return true;
+		}
+		return false;
+	}
+
+	popStateHandler(event: PopStateEvent) {
+		// Exit early if this event should be ignored
+		if (this.options.skipPopStateHandling(event)) {
+			return;
+		}
+
+		// Exit early if the resolved path hasn't changed
+		if (this.isSameResolvedUrl(getCurrentUrl(), this.currentPageUrl)) {
+			return;
+		}
+
+		const { url, hash } = Location.fromUrl(event.state?.url ?? location.href);
+
+		if (hash) {
+			this.scrollToElement = hash;
+		} else {
+			event.preventDefault();
+		}
+
+		this.triggerEvent('popState', event);
+
+		if (!this.options.animateHistoryBrowsing) {
+			document.documentElement.classList.remove('is-animating');
+			cleanupAnimationClasses();
+		}
+
+		this.loadPage({ url }, event);
+	}
+
+	/**
+	 * Utility function to validate and run the global option 'resolveUrl'
+	 * @param {string} url
+	 * @returns {string} the resolved url
+	 */
+	resolveUrl(url: string) {
+		if (typeof this.options.resolveUrl !== 'function') {
+			console.warn(`[swup] options.resolveUrl expects a callback function.`);
+			return url;
+		}
+		const result = this.options.resolveUrl(url);
+		if (!result || typeof result !== 'string') {
+			console.warn(`[swup] options.resolveUrl needs to return a url`);
+			return url;
+		}
+		if (result.startsWith('//') || result.startsWith('http')) {
+			console.warn(`[swup] options.resolveUrl needs to return a relative url`);
+			return url;
+		}
+		return result;
+	}
+
+	/**
+	 * Compares the resolved version of two paths and returns true if they are the same
+	 * @param {string} url1
+	 * @param {string} url2
+	 * @returns {boolean}
+	 */
+	isSameResolvedUrl(url1: string, url2: string) {
+		return this.resolveUrl(url1) === this.resolveUrl(url2);
+	}
+}

package/src/modules/Cache.ts

@@ -0,0 +1,57 @@
+import { getCurrentUrl, Location } from '../helpers.js';
+import Swup from '../index.js';
+import { PageData } from './getPageData.js';
+
+export interface PageRecord extends PageData {
+	url: string;
+	responseURL: string;
+}
+export class Cache {
+	pages: Record<string, PageRecord> = {};
+	last: PageRecord | null = null;
+	swup: Swup;
+
+	constructor(swup: Swup) {
+		this.swup = swup;
+	}
+
+	getCacheUrl(url: string): string {
+		return this.swup.resolveUrl(Location.fromUrl(url).url);
+	}
+
+	cacheUrl(page: PageRecord) {
+		page.url = this.getCacheUrl(page.url);
+		if (page.url in this.pages === false) {
+			this.pages[page.url] = page;
+		}
+		page.responseURL = this.getCacheUrl(page.responseURL);
+		this.last = this.pages[page.url];
+		this.swup.log(`Cache (${Object.keys(this.pages).length})`, this.pages);
+	}
+
+	getPage(url: string): PageRecord {
+		url = this.getCacheUrl(url);
+		return this.pages[url];
+	}
+
+	getCurrentPage(): PageRecord {
+		return this.getPage(getCurrentUrl());
+	}
+
+	exists(url: string): boolean {
+		url = this.getCacheUrl(url);
+		return url in this.pages;
+	}
+
+	empty(): void {
+		this.pages = {};
+		this.last = null;
+		this.swup.log('Cache cleared');
+	}
+
+	remove(url: string): void {
+		delete this.pages[this.getCacheUrl(url)];
+	}
+}
+
+export default Cache;

package/src/modules/enterPage.ts

@@ -0,0 +1,28 @@
+import { nextTick } from '../utils.js';
+import Swup from '../index.js';
+
+const enterPage = function(
+	this: Swup,
+	{ popstate, skipTransition }: { popstate?: PopStateEvent; skipTransition?: boolean }
+) {
+	if (skipTransition) {
+		this.triggerEvent('transitionEnd', popstate);
+		this.cleanupAnimationClasses();
+		return [Promise.resolve()];
+	}
+
+	nextTick(() => {
+		this.triggerEvent('animationInStart');
+		document.documentElement.classList.remove('is-animating');
+	});
+
+	const animationPromises = this.getAnimationPromises('in');
+	Promise.all(animationPromises).then(() => {
+		this.triggerEvent('animationInDone');
+		this.triggerEvent('transitionEnd', popstate);
+		this.cleanupAnimationClasses();
+	});
+	return animationPromises;
+};
+
+export default enterPage;

package/src/modules/fetchPage.ts

@@ -0,0 +1,35 @@
+import Swup from '../index.js';
+import { fetch } from '../helpers.js';
+import { TransitionOptions } from './loadPage.js';
+import { PageRecord } from './Cache.js';
+
+export default function fetchPage(this: Swup, data: TransitionOptions): Promise<PageRecord> {
+	const headers = this.options.requestHeaders;
+	const { url } = data;
+
+	if (this.cache.exists(url)) {
+		this.triggerEvent('pageRetrievedFromCache');
+		return Promise.resolve(this.cache.getPage(url));
+	}
+
+	return new Promise((resolve, reject) => {
+		fetch({ ...data, headers }, (response) => {
+			if (response.status === 500) {
+				this.triggerEvent('serverError');
+				reject(url);
+				return;
+			}
+			// get json data
+			const page = this.getPageData(response);
+			if (!page || !page.blocks.length) {
+				reject(url);
+				return;
+			}
+			// render page
+			const cacheablePageData = { ...page, url };
+			this.cache.cacheUrl(cacheablePageData);
+			this.triggerEvent('pageLoaded');
+			resolve(cacheablePageData);
+		});
+	});
+}

package/src/modules/getAnchorElement.ts

@@ -0,0 +1,19 @@
+import { escapeCssIdentifier, query } from '../utils.js';
+
+const getAnchorElement = (hash: string): Element | null => {
+	if (!hash) {
+		return null;
+	}
+
+	if (hash.charAt(0) === '#') {
+		hash = hash.substring(1);
+	}
+
+	hash = decodeURIComponent(hash);
+	hash = escapeCssIdentifier(hash);
+
+	// https://html.spec.whatwg.org/#find-a-potential-indicated-element
+	return query(`#${hash}`) || query(`a[name='${hash}']`);
+};
+
+export default getAnchorElement;

package/src/modules/getAnimationPromises.ts

@@ -0,0 +1,176 @@
+import { queryAll, toMs } from '../utils.js';
+import Swup from '../index.js';
+
+// Transition property/event sniffing
+let transitionProp = 'transition';
+let transitionEndEvent = 'transitionend';
+let animationProp = 'animation';
+let animationEndEvent = 'animationend';
+
+if (window.ontransitionend === undefined && window.onwebkittransitionend !== undefined) {
+	transitionProp = 'WebkitTransition';
+	transitionEndEvent = 'webkitTransitionEnd';
+}
+
+if (window.onanimationend === undefined && window.onwebkitanimationend !== undefined) {
+	animationProp = 'WebkitAnimation';
+	animationEndEvent = 'webkitAnimationEnd';
+}
+
+export default function getAnimationPromises(
+	this: Swup,
+	// we don't use this argument, but JS plugin depends on it with
+	// its own version of getAnimationPromises, so it must be specified when
+	// getAnimationPromises is being used
+	animationType: 'in' | 'out'
+): Promise<void>[] {
+	const selector = this.options.animationSelector;
+
+	// Allow usage of swup without animations
+	if (selector === false) {
+		// Use array of a single resolved promise instead of an empty array to allow
+		// possible future use with Promise.race() which requires an actual value
+		return [Promise.resolve()];
+	}
+
+	const animatedElements = queryAll(selector, document.body);
+
+	// Warn if no animated containers found on page, but keep things going
+	if (!animatedElements.length) {
+		console.warn(`[swup] No animated elements found by selector ${selector}`);
+		return [Promise.resolve()];
+	}
+
+	return animatedElements.map((element) => getAnimationPromiseForElement(element, selector));
+}
+
+const isTransitionOrAnimationEvent = (event: any): event is TransitionEvent | AnimationEvent =>
+	!!event.elapsedTime;
+
+function getAnimationPromiseForElement(
+	element: Element,
+	selector: string,
+	expectedType: 'animation' | 'transition' | null = null
+): Promise<void> {
+	const { type, timeout, propCount } = getTransitionInfo(element, expectedType);
+
+	// Resolve immediately if no transition defined
+	if (!type || !timeout) {
+		console.warn(
+			`[swup] No CSS transition duration defined for element of selector ${selector}`
+		);
+		return Promise.resolve();
+	}
+
+	return new Promise((resolve) => {
+		const endEvent = type === 'transition' ? transitionEndEvent : animationEndEvent;
+		const startTime = performance.now();
+		let propsTransitioned = 0;
+
+		const end = () => {
+			element.removeEventListener(endEvent, onEnd);
+			resolve();
+		};
+
+		const onEnd: EventListener = (event) => {
+			// Skip transitions on child elements
+			if (event.target !== element) {
+				return;
+			}
+
+			if (!isTransitionOrAnimationEvent(event)) {
+				throw new Error('Not a transition or animation event.');
+			}
+
+			// Skip transitions that happened before we started listening
+			const elapsedTime = (performance.now() - startTime) / 1000;
+			if (elapsedTime < event.elapsedTime) {
+				return;
+			}
+
+			// End if all properties have transitioned
+			if (++propsTransitioned >= propCount) {
+				end();
+			}
+		};
+
+		setTimeout(() => {
+			if (propsTransitioned < propCount) {
+				end();
+			}
+		}, timeout + 1);
+
+		element.addEventListener(endEvent, onEnd);
+	});
+}
+
+export function getTransitionInfo(
+	element: Element,
+	expectedType: 'animation' | 'transition' | null = null
+) {
+	const styles = window.getComputedStyle(element);
+
+	// not sure what to do about the below mess other than casting, but it's a mess
+	const transitionDelay = `${transitionProp}Delay` as keyof CSSStyleDeclaration;
+	const transitionDuration = `${transitionProp}Duration` as keyof CSSStyleDeclaration;
+	const animationDelay = `${animationProp}Delay` as keyof CSSStyleDeclaration;
+	const animationDuration = `${animationProp}Duration` as keyof CSSStyleDeclaration;
+
+	const transitionDelays = (styles[
+		transitionDelay
+	] as CSSStyleDeclaration['transitionDelay']).split(', ');
+	const transitionDurations = ((styles[transitionDuration] ||
+		'') as CSSStyleDeclaration['transitionDuration']).split(', ');
+	const transitionTimeout = calculateTimeout(transitionDelays, transitionDurations);
+
+	const animationDelays = ((styles[animationDelay] ||
+		'') as CSSStyleDeclaration['animationDelay']).split(', ');
+	const animationDurations = ((styles[animationDuration] ||
+		'') as CSSStyleDeclaration['animationDuration']).split(', ');
+	const animationTimeout = calculateTimeout(animationDelays, animationDurations);
+
+	let type: string | null = '';
+	let timeout = 0;
+	let propCount = 0;
+
+	if (expectedType === 'transition') {
+		if (transitionTimeout > 0) {
+			type = 'transition';
+			timeout = transitionTimeout;
+			propCount = transitionDurations.length;
+		}
+	} else if (expectedType === 'animation') {
+		if (animationTimeout > 0) {
+			type = 'animation';
+			timeout = animationTimeout;
+			propCount = animationDurations.length;
+		}
+	} else {
+		timeout = Math.max(transitionTimeout, animationTimeout);
+		type =
+			timeout > 0
+				? transitionTimeout > animationTimeout
+					? 'transition'
+					: 'animation'
+				: null;
+		propCount = type
+			? type === 'transition'
+				? transitionDurations.length
+				: animationDurations.length
+			: 0;
+	}
+
+	return {
+		type,
+		timeout,
+		propCount
+	};
+}
+
+function calculateTimeout(delays: string[], durations: string[]) {
+	while (delays.length < durations.length) {
+		delays = delays.concat(delays);
+	}
+
+	return Math.max(...durations.map((duration, i) => toMs(duration) + toMs(delays[i])));
+}