swup 3.1.1 → 4.0.0-rc.20

package/src/modules/__test__/hooks.test.ts

@@ -0,0 +1,263 @@
+import { describe, expect, it, vi } from 'vitest';
+import Swup from '../../Swup.js';
+import { Handler, Hooks } from '../Hooks.js';
+import { Context } from '../Context.js';
+
+describe('Hook registry', () => {
+	it('should add handlers', () => {
+		const swup = new Swup();
+		const handler = vi.fn();
+
+		// Make private fields public for this test
+		const HooksWithAccess = class extends Hooks {
+			getRegistry() {
+				return this.registry;
+			}
+		};
+		const hooks = new HooksWithAccess(swup);
+
+		hooks.on('enable', handler);
+		const ledger = hooks.getRegistry().get('enable');
+
+		expect(ledger).toBeDefined();
+		expect(ledger).toBeInstanceOf(Map);
+		expect(ledger!.size).toBe(1);
+
+		const registrations = Array.from(ledger!.values());
+		const registration = registrations.find((reg) => reg.handler === handler);
+
+		expect(registration?.handler).toEqual(handler);
+	});
+
+	it('should remove handlers', async () => {
+		const swup = new Swup();
+		const handler1 = vi.fn();
+		const handler2 = vi.fn();
+
+		swup.hooks.on('enable', handler1);
+		swup.hooks.on('enable', handler2);
+
+		await swup.hooks.trigger('enable');
+
+		expect(handler1).toBeCalledTimes(1);
+		expect(handler2).toBeCalledTimes(1);
+
+		swup.hooks.off('enable', handler2);
+
+		await swup.hooks.trigger('enable');
+
+		expect(handler1).toBeCalledTimes(2);
+		expect(handler2).toBeCalledTimes(1);
+	});
+
+	it('should return a function to unregister the handler', async () => {
+		const swup = new Swup();
+		const handler1 = vi.fn();
+		const handler2 = vi.fn();
+
+		const unregister1 = swup.hooks.on('enable', handler1);
+		const unregister2 = swup.hooks.on('enable', handler2);
+
+		expect(unregister1).toBeTypeOf('function');
+
+		await swup.hooks.trigger('enable');
+
+		expect(handler1).toBeCalledTimes(1);
+		expect(handler2).toBeCalledTimes(1);
+
+		unregister2();
+
+		await swup.hooks.trigger('enable');
+
+		expect(handler1).toBeCalledTimes(2);
+		expect(handler2).toBeCalledTimes(1);
+	});
+
+	it('should trigger custom handlers', async () => {
+		const swup = new Swup();
+		const handler = vi.fn();
+
+		swup.hooks.on('enable', handler);
+
+		await swup.hooks.trigger('enable');
+
+		expect(handler).toBeCalledTimes(1);
+	});
+
+	it('should only trigger custom handlers once if requested', async () => {
+		const swup = new Swup();
+		const handler = vi.fn();
+
+		swup.hooks.on('enable', handler, { once: true });
+
+		await swup.hooks.trigger('enable', undefined, () => {});
+		await swup.hooks.trigger('enable', undefined, () => {});
+
+		expect(handler).toBeCalledTimes(1);
+	});
+
+	it('should only trigger custom handlers once if using alias', async () => {
+		const swup = new Swup();
+		const handler = vi.fn();
+
+		swup.hooks.once('enable', handler);
+
+		await swup.hooks.trigger('enable', undefined, () => {});
+		await swup.hooks.trigger('enable', undefined, () => {});
+
+		expect(handler).toBeCalledTimes(1);
+	});
+
+	it('should trigger original handlers', async () => {
+		const swup = new Swup();
+		const handler = vi.fn();
+
+		await swup.hooks.trigger('enable', undefined, handler);
+
+		expect(handler).toBeCalledTimes(1);
+	});
+
+	it('should allow triggering custom handlers before original handler', async () => {
+		const swup = new Swup();
+
+		let called: Array<string> = [];
+		const handlers = {
+			before: () => {
+				called.push('before');
+			},
+			original: () => {
+				called.push('original');
+			},
+			normal: () => {
+				called.push('normal');
+			},
+			after: () => {
+				called.push('after');
+			}
+		};
+
+		swup.hooks.on('disable', handlers.before, { before: true });
+		swup.hooks.on('disable', handlers.normal, {});
+		swup.hooks.on('disable', handlers.after, {});
+
+		await swup.hooks.trigger('disable', undefined, handlers.original);
+
+		expect(called).toEqual(['before', 'original', 'normal', 'after']);
+	});
+
+	it('should sort custom handlers by priority', async () => {
+		const swup = new Swup();
+
+		let called: Array<number> = [];
+		const handlers = {
+			1: () => {
+				called.push(1);
+			},
+			2: () => {
+				called.push(2);
+			},
+			3: () => {
+				called.push(3);
+			},
+			4: () => {
+				called.push(4);
+			},
+			5: () => {
+				called.push(5);
+			},
+			6: () => {
+				called.push(6);
+			},
+			7: () => {
+				called.push(7);
+			},
+			8: () => {
+				called.push(8);
+			}
+		};
+
+		swup.hooks.on('disable', handlers['1'], { priority: 2, before: true });
+		swup.hooks.on('disable', handlers['2'], { priority: -1, before: true });
+		swup.hooks.on('disable', handlers['3'], { priority: 1 });
+		swup.hooks.on('disable', handlers['4']);
+		swup.hooks.on('disable', handlers['8'], { priority: 4 });
+		swup.hooks.on('disable', handlers['7'], { priority: 4 });
+
+		await swup.hooks.trigger('disable', undefined, handlers['5']);
+
+		expect(called).toEqual([2, 1, 5, 4, 3, 8, 7]);
+	});
+
+	it('should allow replacing original handlers', async () => {
+		const swup = new Swup();
+		const customHandler = vi.fn();
+		const defaultHandler = vi.fn();
+
+		swup.hooks.on('enable', customHandler, { replace: true });
+
+		await swup.hooks.trigger('enable', undefined, defaultHandler);
+
+		expect(customHandler).toBeCalledTimes(1);
+		expect(defaultHandler).toBeCalledTimes(0);
+	});
+
+	it('should pass original handler into replacing handlers', async () => {
+		const swup = new Swup();
+		const customHandler = vi.fn();
+		const defaultHandler = vi.fn();
+		const ctx = swup.context;
+
+		swup.hooks.on('enable', customHandler, { replace: true });
+
+		await swup.hooks.trigger('enable', undefined, defaultHandler);
+
+		expect(customHandler).toBeCalledWith(ctx, undefined, defaultHandler);
+	});
+
+	it('should not pass original handler into normal handlers', async () => {
+		const swup = new Swup();
+		const listener = vi.fn();
+		const handler = vi.fn();
+		const ctx = swup.context;
+
+		swup.hooks.on('enable', listener);
+
+		await swup.hooks.trigger('enable', undefined, handler);
+
+		expect(listener).toBeCalledWith(ctx, undefined, undefined);
+	});
+
+	it('should trigger event handler with context and args', async () => {
+		const swup = new Swup();
+		const handler: Handler<'history:popstate'> = vi.fn();
+		const ctx = swup.context;
+		const args = { event: new PopStateEvent('') };
+
+		swup.hooks.on('history:popstate', handler);
+		await swup.hooks.trigger('history:popstate', args);
+
+		expect(handler).toBeCalledTimes(1);
+		expect(handler).toBeCalledWith(ctx, args, undefined);
+	});
+});
+
+describe('Types', () => {
+	it('error when necessary', async () => {
+		const swup = new Swup();
+
+		// @ts-expect-no-error
+		swup.hooks.on(
+			'history:popstate',
+			(ctx: Context, { event }: { event: PopStateEvent }) => {}
+		);
+		// @ts-expect-no-error
+		await swup.hooks.trigger('history:popstate', { event: new PopStateEvent('') });
+
+		// @ts-expect-error
+		swup.hooks.on('history:popstate', ({ event: MouseEvent }) => {});
+		// @ts-expect-error
+		swup.hooks.on('history:popstate', (ctx: Context, { event }: { event: MouseEvent }) => {});
+		// @ts-expect-error
+		await swup.hooks.trigger('history:popstate', { event: new MouseEvent('') });
+	});
+});

package/src/modules/__test__/replaceContent.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import Swup from '../../Swup.js';
+import type { PageData } from '../fetchPage.js';
+import { JSDOM } from 'jsdom';
+
+const getHtml = (body: string): string => {
+	return /*html*/ `
+		<!DOCTYPE html>
+		<body>
+			${body}
+		</body>
+	`;
+};
+
+const mockPage = (body: string): PageData => {
+	return {
+		url: '',
+		html: getHtml(body)
+	};
+};
+
+const stubGlobalDocument = (body: string): void => {
+	const dom = new JSDOM(getHtml(body));
+	vi.stubGlobal('document', dom.window.document);
+};
+
+describe('replaceContent', () => {
+	afterEach(() => {
+		vi.unstubAllGlobals();
+	});
+
+	it('should replace containers', () => {
+		stubGlobalDocument(/*html*/ `
+			<div id="container-1" data-from="current"></div>
+			<div id="container-2" data-from="current"></div>
+			<div id="container-3" data-from="current"></div>
+		`);
+
+		console.debug(document.documentElement.querySelector('#container-1'));
+		const page = mockPage(/*html*/ `
+			<div id="container-1" data-from="incoming"></div>
+			<div id="container-2" data-from="incoming"></div>`);
+		const swup = new Swup();
+
+		const result = swup.replaceContent(page, { containers: ['#container-1', '#container-2'] });
+
+		expect(result).toBe(true);
+		expect(document.querySelector('#container-1')?.getAttribute('data-from')).toBe('incoming');
+		expect(document.querySelector('#container-2')?.getAttribute('data-from')).toBe('incoming');
+		expect(document.querySelector('#container-3')?.getAttribute('data-from')).toBe('current');
+	});
+
+	it('should handle missing containers in current DOM', () => {
+		stubGlobalDocument(/*html*/ `
+			<div id="container-1" data-from="current"></div>
+		`);
+		const warn = vi.spyOn(console, 'warn');
+		const page = mockPage(/*html*/ `
+			<div id="container-1" data-from="incoming"></div>
+			<div id="container-2" data-from="incoming"></div>
+			`);
+
+		const swup = new Swup();
+		const result = swup.replaceContent(page, { containers: ['#container-1', '#missing'] });
+
+		expect(result).toBe(false);
+		expect(warn).not.toBeCalledWith(
+			'[swup] Container missing in current document: #container-1'
+		);
+		expect(warn).toBeCalledWith('[swup] Container missing in current document: #missing');
+	});
+
+	it('should handle missing containers in incoming DOM', () => {
+		stubGlobalDocument(/*html*/ `
+			<div id="container-1" data-from="current"></div>
+			<div id="container-2" data-from="current"></div>
+			<div id="container-3" data-from="current"></div>
+		`);
+		const warn = vi.spyOn(console, 'warn');
+		const page = mockPage(/*html*/ `
+			<div id="container-1" data-from="incoming"></div>`);
+
+		const swup = new Swup();
+		const result = swup.replaceContent(page, { containers: ['#container-1', '#missing'] });
+
+		expect(result).toBe(false);
+		expect(warn).not.toBeCalledWith(
+			'[swup] Container missing in incoming document: #container-1'
+		);
+		expect(warn).toBeCalledWith('[swup] Container missing in incoming document: #missing');
+	});
+});

package/src/modules/awaitAnimations.ts

@@ -0,0 +1,169 @@
+import { queryAll, toMs } from '../utils.js';
+import Swup, { Options } from '../Swup.js';
+
+const TRANSITION = 'transition';
+const ANIMATION = 'animation';
+
+type AnimationTypes = typeof TRANSITION | typeof ANIMATION;
+type AnimationProperties = 'Delay' | 'Duration';
+type AnimationStyleKeys = `${AnimationTypes}${AnimationProperties}` | 'transitionProperty';
+type AnimationStyleDeclarations = Pick<CSSStyleDeclaration, AnimationStyleKeys>;
+
+export type AnimationDirection = 'in' | 'out';
+
+/**
+ * Return a Promise that resolves when all animations are done on the page.
+ *
+ * @note We don't make use of the `direction` argument, but it's required by JS plugin
+ */
+export async function awaitAnimations(
+	this: Swup,
+	{
+		elements,
+		selector
+	}: {
+		selector: Options['animationSelector'];
+		elements?: NodeListOf<HTMLElement> | HTMLElement[];
+		direction?: AnimationDirection;
+	}
+): Promise<void> {
+	// Allow usage of swup without animations
+	if (selector === false && !elements) {
+		return;
+	}
+
+	// Allow passing in elements
+	let animatedElements: HTMLElement[] = [];
+	if (elements) {
+		animatedElements = Array.from(elements);
+	} else if (selector) {
+		animatedElements = queryAll(selector, document.body);
+		// Warn if no elements match the selector, but keep things going
+		if (!animatedElements.length) {
+			console.warn(`[swup] No elements found matching animationSelector \`${selector}\``);
+			return;
+		}
+	}
+
+	const awaitedAnimations = animatedElements.map((el) => awaitAnimationsOnElement(el));
+	const hasAnimations = awaitedAnimations.filter(Boolean).length > 0;
+	if (!hasAnimations) {
+		if (selector) {
+			console.warn(
+				`[swup] No CSS animation duration defined on elements matching \`${selector}\``
+			);
+		}
+		return;
+	}
+
+	await Promise.all(awaitedAnimations);
+}
+
+function awaitAnimationsOnElement(element: Element): Promise<void> | false {
+	const { type, timeout, propCount } = getTransitionInfo(element);
+
+	// Resolve immediately if no transition defined
+	if (!type || !timeout) {
+		return false;
+	}
+
+	return new Promise((resolve) => {
+		const endEvent = `${type}end`;
+		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?: AnimationTypes) {
+	const styles = window.getComputedStyle(element) as AnimationStyleDeclarations;
+
+	const transitionDelays = getStyleProperties(styles, `${TRANSITION}Delay`);
+	const transitionDurations = getStyleProperties(styles, `${TRANSITION}Duration`);
+	const transitionTimeout = calculateTimeout(transitionDelays, transitionDurations);
+	const animationDelays = getStyleProperties(styles, `${ANIMATION}Delay`);
+	const animationDurations = getStyleProperties(styles, `${ANIMATION}Duration`);
+	const animationTimeout = calculateTimeout(animationDelays, animationDurations);
+
+	let type: AnimationTypes | null = 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 isTransitionOrAnimationEvent(event: any): event is TransitionEvent | AnimationEvent {
+	return [`${TRANSITION}end`, `${ANIMATION}end`].includes(event.type);
+}
+
+function getStyleProperties(styles: AnimationStyleDeclarations, key: AnimationStyleKeys): string[] {
+	return (styles[key] || '').split(', ');
+}
+
+function calculateTimeout(delays: string[], durations: string[]): number {
+	while (delays.length < durations.length) {
+		delays = delays.concat(delays);
+	}
+
+	return Math.max(...durations.map((duration, i) => toMs(duration) + toMs(delays[i])));
+}

package/src/modules/enterPage.ts

@@ -1,24 +1,30 @@
-import { nextTick } from '../utils.js';
 import Swup from '../Swup.js';
-import { PageRenderOptions } from './renderPage.js';
+import { nextTick } from '../utils.js';
 
-export const enterPage = function (this: Swup, { event, skipTransition }: PageRenderOptions = {}) {
-	if (skipTransition) {
-		this.triggerEvent('transitionEnd', event);
-		this.cleanupAnimationClasses();
-		return [Promise.resolve()];
+/**
+ * Perform the in/enter animation of the next page.
+ * @returns Promise<void>
+ */
+export const enterPage = async function (this: Swup) {
+	if (!this.context.animation.animate) {
+		return;
 	}
 
-	nextTick(() => {
-		this.triggerEvent('animationInStart');
-		document.documentElement.classList.remove('is-animating');
-	});
+	const animation = this.hooks.trigger(
+		'animation:await',
+		{ direction: 'in' },
+		async (context, { direction }) => {
+			await this.awaitAnimations({ selector: context.animation.selector, direction });
+		}
+	);
 
-	const animationPromises = this.getAnimationPromises('in');
-	Promise.all(animationPromises).then(() => {
-		this.triggerEvent('animationInDone');
-		this.triggerEvent('transitionEnd', event);
-		this.cleanupAnimationClasses();
+	await nextTick();
+
+	await this.hooks.trigger('animation:in:start', undefined, () => {
+		this.classes.remove('is-animating');
 	});
-	return animationPromises;
+
+	await animation;
+
+	await this.hooks.trigger('animation:in:end');
 };

package/src/modules/fetchPage.ts

@@ -1,35 +1,80 @@
 import Swup from '../Swup.js';
-import { fetch } from '../helpers.js';
-import { TransitionOptions } from './loadPage.js';
-import { PageRecord } from './Cache.js';
+import { Location } from '../helpers.js';
 
-export function fetchPage(this: Swup, data: TransitionOptions): Promise<PageRecord> {
-	const headers = this.options.requestHeaders;
-	const { url } = data;
+export interface PageData {
+	url: string;
+	html: string;
+}
+
+export interface FetchOptions extends RequestInit {
+	method?: 'GET' | 'POST';
+	body?: string | FormData | URLSearchParams;
+	headers?: Record<string, string>;
+}
+
+export class FetchError extends Error {
+	url: string;
+	status: number;
+	constructor(message: string, details: { url: string; status: number }) {
+		super(message);
+		this.name = 'FetchError';
+		this.url = details.url;
+		this.status = details.status;
+	}
+}
+
+/**
+ * Fetch a page from the server, return it and cache it.
+ */
+export async function fetchPage(
+	this: Swup,
+	url: URL | string,
+	options: FetchOptions & { triggerHooks?: boolean } = {}
+): Promise<PageData> {
+	url = Location.fromUrl(url).url;
+
+	if (this.cache.has(url)) {
+		const page = this.cache.get(url) as PageData;
+		if (options.triggerHooks !== false) {
+			await this.hooks.trigger('page:load', { page, cache: true });
+		}
+		return page;
+	}
+
+	const headers = { ...this.options.requestHeaders, ...options.headers };
+	options = { ...options, headers };
+
+	// Allow hooking before this and returning a custom response-like object (e.g. custom fetch implementation)
+	const response: Response = await this.hooks.trigger(
+		'fetch:request',
+		{ url, options },
+		(context, { url, options }) => fetch(url, options)
+	);
+
+	const { status, url: responseUrl } = response;
+	const html = await response.text();
+
+	if (status === 500) {
+		this.hooks.trigger('fetch:error', { status, response, url: responseUrl });
+		throw new FetchError(`Server error: ${responseUrl}`, { status, url: responseUrl });
+	}
+
+	if (!html) {
+		throw new FetchError(`Empty response: ${responseUrl}`, { status, url: responseUrl });
+	}
+
+	// Resolve real url after potential redirect
+	const { url: finalUrl } = Location.fromUrl(responseUrl);
+	const page = { url: finalUrl, html };
+
+	// Only save cache entry for non-redirects
+	if (url === finalUrl) {
+		this.cache.set(page.url, page);
+	}
 
-	if (this.cache.exists(url)) {
-		this.triggerEvent('pageRetrievedFromCache');
-		return Promise.resolve(this.cache.getPage(url));
+	if (options.triggerHooks !== false) {
+		await this.hooks.trigger('page:load', { page, cache: false });
 	}
 
-	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);
-		});
-	});
+	return page;
 }

package/src/modules/getAnchorElement.ts

@@ -2,10 +2,11 @@ import { escapeCssIdentifier as escape, query } from '../utils.js';
 
 /**
  * Find the anchor element for a given hash.
- * @see https://html.spec.whatwg.org/#find-a-potential-indicated-element
  *
  * @param hash Hash with or without leading '#'
  * @returns The element, if found, or null.
+ *
+ * @see https://html.spec.whatwg.org/#find-a-potential-indicated-element
  */
 export const getAnchorElement = (hash: string): Element | null => {
 	if (hash && hash.charAt(0) === '#') {