swup 4.0.0-rc.14 → 4.0.0-rc.21

package/src/Swup.ts

@@ -2,89 +2,93 @@ import { DelegateEvent } from 'delegate-it';
 
 import version from './config/version.js';
 
-import {
-	cleanupAnimationClasses,
-	delegateEvent,
-	getCurrentUrl,
-	Location,
-	updateHistoryRecord
-} from './helpers.js';
-import { Unsubscribe } from './helpers/delegateEvent.js';
+import { delegateEvent, getCurrentUrl, Location, updateHistoryRecord } from './helpers.js';
+import { DelegateEventUnsubscribe } from './helpers/delegateEvent.js';
 
 import { Cache } from './modules/Cache.js';
+import { Classes } from './modules/Classes.js';
 import { Context, createContext } from './modules/Context.js';
-import { enterPage } from './modules/enterPage.js';
+import { Hooks } from './modules/Hooks.js';
 import { getAnchorElement } from './modules/getAnchorElement.js';
-import { getAnimationPromises } from './modules/getAnimationPromises.js';
+import { awaitAnimations } from './modules/awaitAnimations.js';
+import { visit, performVisit, HistoryAction } from './modules/visit.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 { Handler, HookName, Hooks } from './modules/Hooks.js';
-import { use, unuse, findPlugin, Plugin } from './modules/plugins.js';
+import { enterPage } from './modules/enterPage.js';
 import { renderPage } from './modules/renderPage.js';
-
-export type Transition = {
-	from?: string;
-	to?: string;
-	custom?: string;
-};
-
-type DelegatedListeners = {
-	click?: Unsubscribe;
-};
+import { use, unuse, findPlugin, Plugin } from './modules/plugins.js';
+import { nextTick } from './utils.js';
 
 export type Options = {
+	/** Whether history visits are animated. Default: `false` */
 	animateHistoryBrowsing: boolean;
+	/** Selector for detecting animation timing. Default: `[class*="transition-"]` */
 	animationSelector: string | false;
-	linkSelector: string;
+	/** Elements on which to add animation classes. Default: `html` element */
+	animationScope: 'html' | 'containers';
+	/** Enable in-memory page cache. Default: `true` */
 	cache: boolean;
+	/** Content containers to be replaced on page visits. Default: `['#swup']` */
 	containers: string[];
-	requestHeaders: Record<string, string>;
-	plugins: Plugin[];
-	skipPopStateHandling: (event: any) => boolean;
+	/** Callback for ignoring visits. Receives the element and event that triggered the visit. */
 	ignoreVisit: (url: string, { el, event }: { el?: Element; event?: Event }) => boolean;
+	/** Selector for links that trigger visits. Default: `'a[href]'` */
+	linkSelector: string;
+	/** Plugins to register on startup. */
+	plugins: Plugin[];
+	/** Custom headers sent along with fetch requests. */
+	requestHeaders: Record<string, string>;
+	/** Rewrite URLs before loading them. */
 	resolveUrl: (url: string) => string;
+	/** Callback for telling swup to ignore certain popstate events.  */
+	skipPopStateHandling: (event: any) => boolean;
 };
 
 export default class Swup {
+	/** Library version */
 	version: string = version;
-	// variable for save options
+	/** Options passed into the instance */
 	options: Options;
-	// running plugin instances
+	/** Registered plugin instances */
 	plugins: Plugin[] = [];
-	// context data
+	/** Global context of the current visit */
 	context: Context;
-	// cache instance
+	/** Cache instance */
 	cache: Cache;
-	// hook registry
+	/** Hook registry */
 	hooks: Hooks;
-	// variable for keeping event listeners from "delegate"
-	delegatedListeners: DelegatedListeners = {};
-	// allows us to compare the current and new path inside popStateHandler
+	/** Animation class manager */
+	classes: Classes;
+	/** URL of the currently visible page */
 	currentPageUrl = getCurrentUrl();
+	/** Index of the current history entry */
+	currentHistoryIndex = 1;
+	/** Delegated event subscription handle */
+	private clickDelegate?: DelegateEventUnsubscribe;
 
-	loadPage = loadPage;
-	performPageLoad = performPageLoad;
+	visit = visit;
+	performVisit = performVisit;
 	leavePage = leavePage;
 	renderPage = renderPage;
 	replaceContent = replaceContent;
 	enterPage = enterPage;
 	delegateEvent = delegateEvent;
-	getAnimationPromises = getAnimationPromises;
 	fetchPage = fetchPage;
+	awaitAnimations = awaitAnimations;
 	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;
 	createContext = createContext;
+	log: (message: string, context?: any) => void = () => {}; // here so it can be used by plugins
 
+	/** Default options before merging user options */
 	defaults: Options = {
 		animateHistoryBrowsing: false,
 		animationSelector: '[class*="transition-"]',
+		animationScope: 'html',
 		cache: true,
 		containers: ['#swup'],
 		ignoreVisit: (url, { el, event } = {}) => !!el?.closest('[data-no-swup]'),
@@ -93,7 +97,7 @@ export default class Swup {
 		resolveUrl: (url) => url,
 		requestHeaders: {
 			'X-Requested-With': 'swup',
-			Accept: 'text/html, application/xhtml+xml'
+			'Accept': 'text/html, application/xhtml+xml'
 		},
 		skipPopStateHandling: (event) => event.state?.source !== 'swup'
 	};
@@ -106,6 +110,7 @@ export default class Swup {
 		this.popStateHandler = this.popStateHandler.bind(this);
 
 		this.cache = new Cache(this);
+		this.classes = new Classes(this);
 		this.hooks = new Hooks(this);
 		this.context = this.createContext({ to: undefined });
 
@@ -125,9 +130,9 @@ export default class Swup {
 	}
 
 	async enable() {
-		// Add event listeners
+		// Add event listener
 		const { linkSelector } = this.options;
-		this.delegatedListeners.click = delegateEvent(linkSelector, 'click', this.linkClickHandler);
+		this.clickDelegate = this.delegateEvent(linkSelector, 'click', this.linkClickHandler);
 
 		window.addEventListener('popstate', this.popStateHandler);
 
@@ -141,21 +146,23 @@ export default class Swup {
 		this.options.plugins.forEach((plugin) => this.use(plugin));
 
 		// Modify initial history record
-		updateHistoryRecord();
+		updateHistoryRecord(null, { index: 1 });
 
-		// Trigger enabled event
-		await this.hooks.trigger('enabled', undefined, () => {
+		// Trigger enable hook
+		await this.hooks.trigger('enable', undefined, () => {
 			// Add swup-enabled class to html tag
 			document.documentElement.classList.add('swup-enabled');
 		});
 
-		// Trigger page view event
-		await this.hooks.trigger('pageView', { url: this.currentPageUrl, title: document.title });
+		await nextTick();
+
+		// Trigger page view hook
+		await this.hooks.trigger('page:view', { url: this.currentPageUrl, title: document.title });
 	}
 
 	async destroy() {
-		// remove delegated listeners
-		this.delegatedListeners.click!.destroy();
+		// remove delegated listener
+		this.clickDelegate!.destroy();
 
 		// remove popstate listener
 		window.removeEventListener('popstate', this.popStateHandler);
@@ -166,8 +173,8 @@ export default class Swup {
 		// unmount plugins
 		this.options.plugins.forEach((plugin) => this.unuse(plugin));
 
-		// trigger disable event
-		await this.hooks.trigger('disabled', undefined, () => {
+		// trigger disable hook
+		await this.hooks.trigger('disable', undefined, () => {
 			// remove swup-enabled class from html tag
 			document.documentElement.classList.remove('swup-enabled');
 		});
@@ -202,8 +209,8 @@ export default class Swup {
 		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 animation name, if specified
+		const animation = el.getAttribute('data-swup-animation') || undefined;
 
 		// Get the history action, if specified
 		let historyAction: HistoryAction | undefined;
@@ -220,7 +227,7 @@ export default class Swup {
 		this.context = this.createContext({
 			to: url,
 			hash,
-			transition,
+			animation,
 			el,
 			event,
 			action: historyAction
@@ -228,7 +235,7 @@ export default class Swup {
 
 		// Exit early if control key pressed
 		if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
-			this.hooks.trigger('openPageInNewTab', { href });
+			this.hooks.trigger('link:newtab', { href });
 			return;
 		}
 
@@ -237,8 +244,8 @@ export default class Swup {
 			return;
 		}
 
-		this.hooks.triggerSync('clickLink', { el, event }, () => {
-			const from = this.context.from?.url ?? '';
+		this.hooks.triggerSync('link:click', { el, event }, () => {
+			const from = this.context.from.url ?? '';
 
 			event.preventDefault();
 
@@ -247,7 +254,7 @@ export default class Swup {
 				if (hash) {
 					updateHistoryRecord(url + hash);
 					this.hooks.triggerSync(
-						'samePageWithHash',
+						'link:anchor',
 						{ hash, options: { behavior: 'auto' } },
 						(context, { hash, options }) => {
 							const target = this.getAnchorElement(hash);
@@ -257,7 +264,8 @@ export default class Swup {
 						}
 					);
 				} else {
-					this.hooks.triggerSync('samePage', undefined, () => {
+					this.hooks.triggerSync('link:self', undefined, (context) => {
+						if (!context.scroll.reset) return;
 						window.scroll({ top: 0, left: 0, behavior: 'auto' });
 					});
 				}
@@ -270,7 +278,7 @@ export default class Swup {
 			}
 
 			// Finally, proceed with loading the page
-			this.performPageLoad(url, { transition, history: historyAction });
+			this.performVisit(url);
 		});
 	}
 
@@ -302,22 +310,32 @@ export default class Swup {
 		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
+			resetScroll
 		});
 
+		// Mark as popstate visit
+		this.context.history.popstate = true;
+
+		// Determine direction of history visit
+		const index = Number(event.state?.index);
+		if (index) {
+			const direction = index - this.currentHistoryIndex > 0 ? 'forwards' : 'backwards';
+			this.context.history.direction = direction;
+		}
+
 		// Does this even do anything?
 		// if (!hash) {
 		// 	event.preventDefault();
 		// }
 
-		this.hooks.triggerSync('popState', { event }, () => {
-			this.performPageLoad(url);
+		this.hooks.triggerSync('history:popstate', { event }, () => {
+			this.performVisit(url);
 		});
 	}
 

package/src/__test__/index.test.ts

@@ -38,7 +38,7 @@ describe('Exports', () => {
 			resolveUrl: (url) => url,
 			requestHeaders: {
 				'X-Requested-With': 'swup',
-				Accept: 'text/html, application/xhtml+xml'
+				'Accept': 'text/html, application/xhtml+xml'
 			},
 			skipPopStateHandling: (event) => event.state?.source !== 'swup'
 		};
@@ -84,10 +84,10 @@ describe('ignoreVisit', () => {
 		);
 	});
 
-	it('should be called from loadPage method', () => {
+	it('should be called from visit method', () => {
 		const ignoreVisit = vi.fn(() => true);
 		const swup = new Swup({ ignoreVisit });
-		swup.loadPage('/path/');
+		swup.visit('/path/');
 
 		expect(ignoreVisit.mock.calls).toHaveLength(1);
 	});

package/src/helpers/Location.ts

@@ -19,7 +19,7 @@ export class Location extends URL {
 	/**
 	 * Instantiate a Location from an element's href attribute
 	 * @param el
-	 * @return new Location instance
+	 * @returns new Location instance
 	 */
 	static fromElement(el: Element): Location {
 		const href = el.getAttribute('href') || el.getAttribute('xlink:href') || '';
@@ -29,7 +29,7 @@ export class Location extends URL {
 	/**
 	 * Instantiate a Location from a URL object or string
 	 * @param url
-	 * @return new Location instance
+	 * @returns new Location instance
 	 */
 	static fromUrl(url: URL | string): Location {
 		return new Location(url);

package/src/helpers/delegateEvent.ts

@@ -1,7 +1,7 @@
 import delegate, { DelegateEventHandler, DelegateOptions, EventType } from 'delegate-it';
 import { ParseSelector } from 'typed-query-selector/parser.js';
 
-export type Unsubscribe = {
+export type DelegateEventUnsubscribe = {
 	destroy: () => void;
 };
 
@@ -10,7 +10,7 @@ export const delegateEvent = <Selector extends string, TEvent extends EventType>
 	type: TEvent,
 	callback: DelegateEventHandler<GlobalEventHandlersEventMap[TEvent]>,
 	options?: DelegateOptions
-): Unsubscribe => {
+): DelegateEventUnsubscribe => {
 	const controller = new AbortController();
 	options = { ...options, signal: controller.signal };
 	delegate<string, ParseSelector<Selector, HTMLElement>, TEvent>(

package/src/helpers.ts

@@ -7,5 +7,4 @@ export { updateHistoryRecord } from './helpers/updateHistoryRecord.js';
 export { delegateEvent } from './helpers/delegateEvent.js';
 export { getCurrentUrl } from './helpers/getCurrentUrl.js';
 export { Location } from './helpers/Location.js';
-export { cleanupAnimationClasses } from './helpers/cleanupAnimationClasses.js';
 export { matchPath } from './helpers/matchPath.js';

package/src/index.ts

@@ -1,13 +1,43 @@
+import type { Path } from 'path-to-regexp';
+
 import Swup, { type Options } from './Swup.js';
 import type { CacheData } from './modules/Cache.js';
-import type { Context, PageContext } from './modules/Context.js';
+import type {
+	Context,
+	FromContext,
+	ToContext,
+	AnimationContext,
+	ScrollContext,
+	HistoryContext
+} from './modules/Context.js';
+import type {
+	HookDefinitions,
+	HookName,
+	HookOptions,
+	HookUnregister,
+	Handler
+} from './modules/Hooks.js';
 import type { Plugin } from './modules/plugins.js';
-import type { HookDefinitions, Handler } from './modules/Hooks.js';
-import type { Path } from 'path-to-regexp';
 
 export default Swup;
 
 export * from './helpers.js';
 export * from './utils.js';
 
-export type { Options, Plugin, CacheData, Context, PageContext, HookDefinitions, Handler, Path };
+export type {
+	Options,
+	Plugin,
+	CacheData,
+	Context,
+	FromContext,
+	ToContext,
+	AnimationContext,
+	ScrollContext,
+	HistoryContext,
+	HookDefinitions,
+	HookName,
+	HookOptions,
+	HookUnregister,
+	Handler,
+	Path
+};

package/src/modules/Cache.ts

@@ -32,7 +32,7 @@ export class Cache {
 		url = this.resolve(url);
 		page = { ...page, url };
 		this.pages.set(url, page);
-		this.swup.hooks.triggerSync('pageCached', { page });
+		this.swup.hooks.triggerSync('cache:set', { page });
 	}
 
 	public update(url: string, page: CacheData) {
@@ -47,7 +47,7 @@ export class Cache {
 
 	public clear(): void {
 		this.pages.clear();
-		this.swup.hooks.triggerSync('cacheCleared');
+		this.swup.hooks.triggerSync('cache:clear');
 	}
 
 	public prune(predicate: (url: string, page: CacheData) => boolean): void {

package/src/modules/Classes.ts

@@ -0,0 +1,48 @@
+import Swup from '../Swup.js';
+import { queryAll } from '../utils.js';
+
+export class Classes {
+	public swup: Swup;
+
+	swupClasses = ['to-', 'is-changing', 'is-rendering', 'is-popstate', 'is-animating'];
+
+	constructor(swup: Swup) {
+		this.swup = swup;
+	}
+
+	get selectors(): string[] {
+		const { scope } = this.swup.context.animation;
+		if (scope === 'containers') return this.swup.context.containers;
+		if (scope === 'html') return ['html'];
+		if (Array.isArray(scope)) return scope;
+		return [];
+	}
+
+	get selector(): string {
+		return this.selectors.join(',');
+	}
+
+	get targets(): HTMLElement[] {
+		if (!this.selector.trim()) return [];
+		return queryAll(this.selector) as HTMLElement[];
+	}
+
+	public add(...classes: string[]): void {
+		this.targets.forEach((target) => target.classList.add(...classes));
+	}
+
+	public remove(...classes: string[]): void {
+		this.targets.forEach((target) => target.classList.remove(...classes));
+	}
+
+	public clear(): void {
+		this.targets.forEach((target) => {
+			const remove = target.className.split(' ').filter((c) => this.isSwupClass(c));
+			target.classList.remove(...remove);
+		});
+	}
+
+	private isSwupClass(className: string): boolean {
+		return this.swupClasses.some((c) => className.startsWith(c));
+	}
+}

package/src/modules/Context.ts

@@ -1,51 +1,80 @@
 import Swup, { Options } from '../Swup.js';
-import { HistoryAction } from './loadPage.js';
+import { HistoryAction, HistoryDirection } from './visit.js';
 
 export interface Context<TEvent = Event> {
-	from: PageContext;
-	to?: PageContext;
+	/** The previous page, about to leave */
+	from: FromContext;
+	/** The next page, about to enter */
+	to: ToContext;
+	/** The content containers, about to be replaced */
 	containers: Options['containers'];
-	transition: TransitionContext;
+	/** Information about animated page transitions */
+	animation: AnimationContext;
+	/** What triggered this visit */
 	trigger: TriggerContext<TEvent>;
+	/** Browser history behavior on this visit */
 	history: HistoryContext;
+	/** Scroll behavior on this visit */
 	scroll: ScrollContext;
 }
 
-export interface PageContext {
+export interface FromContext {
+	/** The URL of the previous page */
 	url: string;
 }
 
-export interface TransitionContext {
+export interface ToContext {
+	/** The URL of the next page */
+	url?: string;
+	/** The HTML content of the next page */
+	html?: string;
+}
+
+export interface AnimationContext {
+	/** Whether this visit is animated. Default: `true` */
 	animate: boolean;
+	/** Whether to wait for the next page to load before starting the animation. Default: `false` */
+	wait: boolean;
+	/** Name of a custom animation to run. */
 	name?: string;
+	/** Elements on which to add animation classes. Default: `html` element */
+	scope: 'html' | 'containers' | string[];
+	/** Selector for detecting animation timing. Default: `[class*="transition-"]` */
+	selector: Options['animationSelector'];
 }
 
 export interface ScrollContext {
+	/** Whether to reset the scroll position after the visit. Default: `true` */
 	reset: boolean;
+	/** Anchor element to scroll to on the next page. */
 	target?: string;
 }
 
 export interface TriggerContext<TEvent = Event> {
+	/** DOM element that triggered this visit. */
 	el?: Element;
+	/** DOM event that triggered this visit. */
 	event?: TEvent;
 }
 
 export interface HistoryContext {
+	/** History action to perform: `push` for creating a new history entry, `replace` for replacing the current entry. Default: `push` */
 	action: HistoryAction;
+	/** Whether this visit was triggered by a browser history navigation. */
 	popstate: boolean;
-	// direction: 'forward' | 'backward' | undefined
+	/** The direction of travel in case of a browser history navigation: backward or forward. */
+	direction: HistoryDirection | undefined;
 }
 
 export interface ContextInitOptions {
 	to: string | undefined;
 	from?: string;
 	hash?: string;
-	containers?: Options['containers'];
 	animate?: boolean;
-	transition?: string;
+	animation?: string;
+	targets?: string[];
 	el?: Element;
 	event?: Event;
-	popstate?: boolean;
 	action?: HistoryAction;
 	resetScroll?: boolean;
 }
@@ -56,23 +85,24 @@ export function createContext(
 		to,
 		from = this.currentPageUrl,
 		hash: target,
-		containers = this.options.containers,
 		animate = true,
-		transition,
+		animation: name,
 		el,
 		event,
-		popstate = false,
 		action = 'push',
 		resetScroll: reset = true
 	}: ContextInitOptions
 ): Context {
 	return {
 		from: { url: from },
-		to: to !== undefined ? { url: to } : undefined,
-		containers,
-		transition: {
+		to: { url: to },
+		containers: this.options.containers,
+		animation: {
 			animate,
-			name: transition
+			wait: false,
+			name,
+			scope: this.options.animationScope,
+			selector: this.options.animationSelector
 		},
 		trigger: {
 			el,
@@ -80,8 +110,8 @@ export function createContext(
 		},
 		history: {
 			action,
-			popstate
-			// direction: undefined
+			popstate: false,
+			direction: undefined
 		},
 		scroll: {
 			reset,