swup 2.0.19 → 3.0.0-rc.2

package/src/Swup.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/config/version.ts

@@ -0,0 +1,13 @@
+/**
+ * Import swup's current version from package.json
+ */
+
+// This will only work in webpack 4
+// export { version as default } from '../../package.json';
+
+// This will work in microbundle + webpack 5, but won't treeshake in webpack 4
+// Ignore next line in TypeScript as package.json is outside of rootDir
+// @ts-ignore
+import pckg from '../../package.json';
+
+export default pckg.version;

package/src/helpers/Location.ts

@@ -0,0 +1,44 @@
+/**
+ * A helper for creating a Location from either an element
+ * or a URL object/string
+ *
+ * Note: this could be implemented as a class inheriting from URL
+ * Except: Babel will add tons of boilerplate for ES6 classes + getters
+ * So for now it's implemented as an augmented URL object with custom getter
+ *
+ * class Location extends URL {
+ *   get url() {
+ *	 return this.pathname + this.search;
+ *   }
+ * }
+ *
+ */
+
+export default class Location extends URL {
+	constructor(url: string, base: string = document.baseURI) {
+		super(url.toString(), base);
+	}
+
+	get url() {
+		return this.pathname + this.search;
+	}
+
+	/**
+	 * Instantiate a Location from an element's href attribute
+	 * @param {Element} el
+	 * @return new Location instance
+	 */
+	static fromElement(el: HTMLAnchorElement): 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
+	 */
+	static fromUrl(url: string): Location {
+		return new Location(url);
+	}
+}

package/src/helpers/classify.ts

@@ -0,0 +1,13 @@
+const classify = (text: string, fallback?: string): string => {
+	const output = String(text)
+		.toLowerCase()
+		// .normalize('NFD') // split an accented letter in the base letter and the acent
+		// .replace(/[\u0300-\u036f]/g, '') // remove all previously split accents
+		.replace(/[\s/_.]+/g, '-') // replace spaces and _./ with '-'
+		.replace(/[^\w-]+/g, '') // remove all non-word chars
+		.replace(/--+/g, '-') // replace repeating '-' with single '-'
+		.replace(/^-+|-+$/, ''); // trim '-' from edges
+	return output || fallback || '';
+};
+
+export default classify;

package/src/helpers/cleanupAnimationClasses.ts

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

package/src/helpers/createHistoryRecord.ts

@@ -0,0 +1,14 @@
+import { default as getCurrentUrl } from './getCurrentUrl.js';
+
+const createHistoryRecord = (url: string, customData: Record<string, unknown> = {}): void => {
+	url = url || getCurrentUrl({ hash: true });
+	const data = {
+		url,
+		random: Math.random(),
+		source: 'swup',
+		...customData
+	};
+	history.pushState(data, '', url);
+};
+
+export default createHistoryRecord;

package/src/helpers/delegateEvent.ts

@@ -0,0 +1,23 @@
+import delegate, { EventType } from 'delegate-it';
+import { ParseSelector } from 'typed-query-selector/parser';
+
+export type Unsubscribe = {
+	destroy: () => void;
+};
+const delegateEvent = <Selector extends string, TEvent extends EventType>(
+	selector: Selector,
+	type: TEvent,
+	callback: delegate.EventHandler<GlobalEventHandlersEventMap[TEvent]>,
+	{ base = document, ...eventOptions } = {}
+): Unsubscribe => {
+	const delegation = delegate<string, ParseSelector<Selector, HTMLElement>, TEvent>(
+		base,
+		selector,
+		type,
+		callback,
+		eventOptions
+	);
+	return { destroy: () => delegation.destroy() };
+};
+
+export default delegateEvent;

package/src/helpers/fetch.ts

@@ -0,0 +1,35 @@
+import { TransitionOptions } from '../modules/loadPage.js';
+import { Options } from '../Swup.js';
+
+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;
+};
+
+export default fetch;

package/src/helpers/getCurrentUrl.ts

@@ -0,0 +1,5 @@
+const getCurrentUrl = ({ hash }: { hash?: boolean } = {}): string => {
+	return location.pathname + location.search + (hash ? location.hash : '');
+};
+
+export default getCurrentUrl;

package/src/helpers/getDataFromHtml.ts

@@ -0,0 +1,41 @@
+import { query, queryAll } from '../utils.js';
+
+export type PageHtmlData = {
+	title: string;
+	originalContent: string;
+	blocks: string[];
+	pageClass?: string;
+};
+
+const getDataFromHtml = (html: string, containers: string[]): PageHtmlData => {
+	let fakeDom = document.createElement('html');
+	fakeDom.innerHTML = html;
+	let blocks: string[] = [];
+
+	containers.forEach((selector) => {
+		if (query(selector, fakeDom) == null) {
+			console.warn(`[swup] Container ${selector} not found on page.`);
+			return null;
+		} else {
+			if (queryAll(selector).length !== queryAll(selector, fakeDom).length) {
+				console.warn(`[swup] Mismatched number of containers found on new page.`);
+			}
+			queryAll(selector).forEach((item, index) => {
+				queryAll(selector, fakeDom)[index].setAttribute('data-swup', String(blocks.length));
+				blocks.push(queryAll(selector, fakeDom)[index].outerHTML);
+			});
+		}
+	});
+
+	const title = query('title', fakeDom)?.innerText || '';
+	const pageClass = query('body', fakeDom)?.className;
+
+	// to prevent memory leaks
+	fakeDom.innerHTML = '';
+	// @ts-ignore don't want to type it as possible null, since it's created at the top of the function always
+	fakeDom = null;
+
+	return { title, pageClass, blocks, originalContent: html };
+};
+
+export default getDataFromHtml;

package/src/helpers/index.ts

@@ -0,0 +1,11 @@
+export { default as classify } from './classify.js';
+export { default as createHistoryRecord } from './createHistoryRecord.js';
+export { default as updateHistoryRecord } from './updateHistoryRecord.js';
+export { default as delegateEvent } from './delegateEvent.js';
+export { default as getDataFromHtml } from './getDataFromHtml.js';
+export { default as fetch } from './fetch.js';
+export { default as getCurrentUrl } from './getCurrentUrl.js';
+export { default as Location } from './Location.js';
+export { default as markSwupElements } from './markSwupElements.js';
+export { default as cleanupAnimationClasses } from './cleanupAnimationClasses.js';
+export { default as versionSatisfies } from './versionSatisfies.js';

package/src/helpers/markSwupElements.ts

@@ -0,0 +1,18 @@
+import { query, queryAll } from '../utils.js';
+
+const markSwupElements = (element: Element, containers: string[]): void => {
+	let blocks = 0;
+
+	containers.forEach((selector) => {
+		if (query(selector, element) == null) {
+			console.warn(`[swup] Container ${selector} not found on page.`);
+		} else {
+			queryAll(selector).forEach((item: Element, index: number) => {
+				queryAll(selector, element)[index].setAttribute('data-swup', String(blocks));
+				blocks++;
+			});
+		}
+	});
+};
+
+export default markSwupElements;

package/src/helpers/updateHistoryRecord.ts

@@ -0,0 +1,18 @@
+import { default as getCurrentUrl } from './getCurrentUrl.js';
+
+const updateHistoryRecord = (
+	url: string | null = null,
+	customData: Record<string, unknown> = {}
+): void => {
+	url = url || getCurrentUrl({ hash: true });
+	const data = {
+		...history.state,
+		url,
+		random: Math.random(),
+		source: 'swup',
+		...customData
+	};
+	history.replaceState(data, '', url);
+};
+
+export default updateHistoryRecord;

package/src/helpers/versionSatisfies.ts

@@ -0,0 +1,46 @@
+type Comparator = '>' | '>=' | '<' | '<=';
+
+// Fill versions to exactly 3 decimals
+const normalizeVersion = (version: string): string => {
+	return String(version).split('.').concat(['0', '0']).slice(0, 3).join('.');
+};
+
+// Numerically compare version strings after normalizing them
+const compareVersion = (a: string, b: string): number => {
+	a = normalizeVersion(a);
+	b = normalizeVersion(b);
+	return a.localeCompare(b, undefined, { numeric: true });
+};
+
+// Apply a comparator (equals, greater-than, etc) by its symbol to a sort comparison
+const applyComparator = (comparisonResult: number, comparator: Comparator) => {
+	const comparators = {
+		'': (r: number) => r === 0,
+		'>': (r: number) => r > 0,
+		'>=': (r: number) => r >= 0,
+		'<': (r: number) => r < 0,
+		'<=': (r: number) => r <= 0
+	};
+	const comparatorFn = comparators[comparator] || comparators[''];
+	return comparatorFn(comparisonResult);
+};
+
+/**
+ * Check if a version satisfies all given version requirements
+ *
+ * versionSatisfies('2.1.0', ['>=2', '<4']) // true
+ * versionSatisfies('2.1.0', ['5']) // false
+ *
+ * @param {string} installed Installed version
+ * @param {Array.<string>} requirements Array of requirements that must be satisfied
+ * @returns boolean
+ */
+export const versionSatisfies = (installed: string, requirements: string[]) => {
+	return requirements.every((required) => {
+		const [, comparator, version] = required.match(/^([\D]+)?(.*)$/) || [];
+		const comparisonResult = compareVersion(installed, version);
+		return applyComparator(comparisonResult, (comparator as Comparator) || '>=');
+	});
+};
+
+export default versionSatisfies;

package/src/helpers.ts

@@ -0,0 +1,4 @@
+// Re-export all helpers to allow custom package export path
+// e.g. import { getPageData } from 'swup/helpers'
+
+export * from './helpers/index.js';

package/src/index.ts

@@ -0,0 +1,8 @@
+import Swup, { Options } from './Swup.js';
+
+export default Swup;
+
+export * from './helpers.js';
+export * from './utils.js';
+
+export type { Options };