Merge pull request #58 from swup/feat/modify-rules

src/SwupFragmentPlugin.ts

@@ -5,9 +5,10 @@ import {
 	handlePageView,
 	cleanupFragmentElements,
 	getFirstMatchingRule,
-	getFragmentVisitContainers
+	getFragmentVisitContainers,
+	cloneRules
 } from './inc/functions.js';
-import type { Options, Route, FragmentVisit } from './inc/defs.js';
+import type { Options, Rule, Route, FragmentVisit } from './inc/defs.js';
 import * as handlers from './inc/handlers.js';
 import { __DEV__ } from './inc/env.js';
 
@@ -18,15 +19,19 @@ type InitOptions = RequireKeys<Options, 'rules'>;
  * The main plugin class
  */
 export default class SwupFragmentPlugin extends PluginBase {
-	name = 'SwupFragmentPlugin';
+	readonly name = 'SwupFragmentPlugin';
+	readonly requires = { swup: '>=4' };
 
-	requires = { swup: '>=4' };
+	protected _rawRules: Rule[] = [];
+	protected _parsedRules: ParsedRule[] = [];
 
-	rules: ParsedRule[] = [];
+	get parsedRules() {
+		return this._parsedRules;
+	}
 
 	options: Options;
 
-	defaults: Options = {
+	protected defaults: Options = {
 		rules: [],
 		debug: false
 	};
@@ -39,11 +44,7 @@ export default class SwupFragmentPlugin extends PluginBase {
 	 */
 	constructor(options: InitOptions) {
 		super();
-
 		this.options = { ...this.defaults, ...options };
-		if (__DEV__) {
-			if (this.options.debug) this.logger = new Logger();
-		}
 	}
 
 	/**
@@ -52,18 +53,10 @@ export default class SwupFragmentPlugin extends PluginBase {
 	mount() {
 		const swup = this.swup;
 
-		this.rules = this.options.rules.map(({ from, to, containers, name, scroll, focus }) => {
-			return new ParsedRule({
-				from,
-				to,
-				containers,
-				name,
-				scroll,
-				focus,
-				logger: this.logger,
-				swup: this.swup
-			});
-		});
+		this.setRules(this.options.rules);
+		if (__DEV__) {
+			if (this.options.debug) this.logger = new Logger();
+		}
 
 		this.before('link:self', handlers.onLinkToSelf);
 		this.on('visit:start', handlers.onVisitStart);
@@ -73,8 +66,6 @@ export default class SwupFragmentPlugin extends PluginBase {
 		this.on('content:replace', handlers.onContentReplace);
 		this.on('visit:end', handlers.onVisitEnd);
 
-		swup.getFragmentVisit = this.getFragmentVisit.bind(this);
-
 		if (__DEV__) {
 			this.logger?.warnIf(
 				!swup.options.cache,
@@ -90,16 +81,50 @@ export default class SwupFragmentPlugin extends PluginBase {
 	 */
 	unmount() {
 		super.unmount();
-		this.swup.getFragmentVisit = undefined;
-		this.rules = [];
 		cleanupFragmentElements();
 	}
 
+	setRules(rules: Rule[]) {
+		this._rawRules = cloneRules(rules);
+		this._parsedRules = rules.map((rule) => this.parseRule(rule));
+		if (__DEV__) this.logger?.log('Updated fragment rules', this.getRules());
+	}
+
+	getRules() {
+		return cloneRules(this._rawRules);
+	}
+
+	prependRule(rule: Rule) {
+		this.setRules([rule, ...this.getRules()]);
+	}
+
+	appendRule(rule: Rule) {
+		this.setRules([...this.getRules(), rule]);
+	}
+
+	/**
+	 * Add a fragment rule
+	 * @param {Rule} rule 			The rule options
+	 * @param {'start' | 'end'} at 	Should the rule be added to the beginning or end of the existing rules?
+	 */
+	parseRule({ from, to, containers, name, scroll, focus }: Rule): ParsedRule {
+		return new ParsedRule({
+			from,
+			to,
+			containers,
+			name,
+			scroll,
+			focus,
+			logger: this.logger,
+			swup: this.swup
+		});
+	}
+
 	/**
 	 * Get the fragment visit object for a given route
 	 */
 	getFragmentVisit(route: Route): FragmentVisit | undefined {
-		const rule = getFirstMatchingRule(route, this.rules);
+		const rule = getFirstMatchingRule(route, this.parsedRules);
 
 		// Bail early if no rule matched
 		if (!rule) return;

src/inc/functions.ts

@@ -1,7 +1,7 @@
 import { Location } from 'swup';
 import type { Swup, Visit, VisitScroll } from 'swup';
 import type { default as FragmentPlugin } from '../SwupFragmentPlugin.js';
-import type { Route, FragmentVisit, FragmentElement } from './defs.js';
+import type { Route, Rule, FragmentVisit, FragmentElement } from './defs.js';
 import type ParsedRule from './ParsedRule.js';
 import Logger, { highlight } from './Logger.js';
 
@@ -82,10 +82,10 @@ function handleLinksToFragments({ logger, swup }: FragmentPlugin): void {
 /**
  * Adds attributes and properties to fragment elements
  */
-function prepareFragmentElements({ rules, swup, logger }: FragmentPlugin): void {
+function prepareFragmentElements({ parsedRules, swup, logger }: FragmentPlugin): void {
 	const currentUrl = swup.getCurrentUrl();
 
-	rules
+	parsedRules
 		.filter((rule) => rule.matchesFrom(currentUrl) || rule.matchesTo(currentUrl))
 		.forEach((rule) => {
 			rule.containers.forEach((selector) => {
@@ -379,3 +379,17 @@ export function queryFragmentElement(
 	}
 	return;
 }
+
+/**
+ * Clone fragment rules (replacement for `structuredClone`)
+ */
+export function cloneRules(rules: Rule[]): Rule[] {
+	if (!Array.isArray(rules)) throw new Error(`cloneRules() expects an array of rules`);
+
+	return rules.map((rule) => ({
+		...rule,
+		from: Array.isArray(rule.from) ? [...rule.from] : rule.from,
+		to: Array.isArray(rule.to) ? [...rule.to] : rule.to,
+		containers: [...rule.containers]
+	}));
+}

src/inc/handlers.ts

@@ -22,7 +22,7 @@ export const onLinkToSelf: Handler<'link:self'> = function (this: FragmentPlugin
 	const route = getRoute(visit);
 	if (!route) return;
 
-	const rule = getFirstMatchingRule(route, this.rules);
+	const rule = getFirstMatchingRule(route, this.parsedRules);
 
 	if (rule) visit.scroll.reset = false;
 };

src/index.ts

@@ -6,6 +6,10 @@ export type { Options, Rule, FragmentElement, FragmentVisit } from './inc/defs.j
 declare module 'swup' {
 	export interface Swup {
 		getFragmentVisit?: FragmentPlugin['getFragmentVisit'];
+		getFragmentRules?: FragmentPlugin['getRules'];
+		setFragmentRules?: FragmentPlugin['setRules'];
+		prependFragmentRule?: FragmentPlugin['prependRule'];
+		appendFragmentRule?: FragmentPlugin['appendRule'];
 	}
 	export interface Visit {
 		fragmentVisit?: FragmentVisit;

tests/vitest/cloneRules.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { cloneRules } from '../../src/inc/functions.js';
+
+describe('cloneRules()', () => {
+	it('should clone rules', () => {
+		const original = [
+			{ from: 'foo', to: 'bar', containers: ['#foobar'] },
+			{ from: ['/', 'baz'], to: ['/', 'bat'], containers: ['#bazbat'] }
+		];
+		/** test equality with a reference */
+		const reference = original;
+		expect(original === reference).toEqual(true);
+
+		/** test shallow copy */
+		const shallowCopy = { ...original };
+		expect(original === shallowCopy).toEqual(false);
+		expect(original[0].containers === shallowCopy[0].containers).toEqual(true);
+		expect(original[1].from === shallowCopy[1].from).toEqual(true);
+
+		/** test deep clone */
+		const clone = cloneRules(original);
+		expect(original === clone).toEqual(false);
+		expect(original[0].containers === clone[0].containers).toEqual(false);
+		expect(original[1].from === clone[1].from).toEqual(false);
+	});
+});

tests/vitest/getFragmentVisit.test.ts

@@ -19,18 +19,14 @@ describe('getFragmentVisit()', () => {
 		vi.restoreAllMocks();
 	});
 	it('should be callable as public API', () => {
-		const fromPlugin = fragmentPlugin.getFragmentVisit({ from: '/page-1/', to: '/page-2/' });
-		const fromSwup = fragmentPlugin.swup.getFragmentVisit?.({ from: '/page-1/',to: '/page-2/' }); // prettier-ignore
+		const fragmentVisit = fragmentPlugin.getFragmentVisit({ from: '/page-1/', to: '/page-2/' });
 
-		expect(fromPlugin).toEqual({
+		expect(fragmentVisit).toEqual({
 			containers: ['#fragment-1'],
 			name: undefined,
 			scroll: false,
 			focus: undefined
 		});
-
-		/** make sure the method exists on swup as well */
-		expect(fromPlugin).toEqual(fromSwup);
 	});
 
 	it('should return undefined if there is no matching rule', () => {

tests/vitest/modifyRules.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { getMountedPluginInstance, spyOnConsole } from './inc/helpers.js';
+
+const defaultRule = {
+	from: '/page-1/',
+	to: '/page-2/',
+	containers: ['#default']
+};
+const fragmentPlugin = getMountedPluginInstance({
+	rules: [defaultRule]
+});
+
+describe('modify fragment rules', () => {
+	beforeEach(() => {
+		spyOnConsole();
+		/** Reset the rules */
+		fragmentPlugin.setRules([defaultRule]);
+	});
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it('should return unparsed raw rules', () => {
+		expect(fragmentPlugin.getRules()).toEqual([defaultRule]);
+	});
+
+	it('should provide API methods on the swup instance', () => {
+		expect(fragmentPlugin.getRules).toBeTypeOf('function');
+		expect(fragmentPlugin.setRules).toBeTypeOf('function');
+		expect(fragmentPlugin.prependRule).toBeTypeOf('function');
+		expect(fragmentPlugin.appendRule).toBeTypeOf('function');
+	});
+
+	it('should provide access to prependRule() and appendRule()', () => {
+		const prependRule = {
+			from: '/corge/',
+			to: '/grault/',
+			containers: ['#corgegrault']
+		};
+		const appendRule = {
+			from: '/garply/',
+			to: '/waldo/',
+			containers: ['#garplywaldo']
+		};
+
+		fragmentPlugin.prependRule(prependRule);
+		fragmentPlugin.appendRule(appendRule);
+
+		expect(fragmentPlugin.getRules()).toEqual([prependRule, defaultRule, appendRule]);
+	});
+
+	it('should provide access to getRules() and setRules()', () => {
+		/** Add a rule using the plugin's API, *after* the existing rules */
+		const appendRule = {
+			from: '/foo/',
+			to: '/bar/',
+			containers: ['#foobar'],
+			name: 'from-plugin'
+		};
+		fragmentPlugin.setRules([...fragmentPlugin.getRules(), appendRule]);
+
+		/** Add a rule using swup's API, *before* the existing rules */
+		const prependRule = {
+			from: '/baz/',
+			to: '/bat/',
+			containers: ['#bazbat'],
+			name: 'from-swup'
+		};
+		fragmentPlugin.setRules([prependRule, ...fragmentPlugin.getRules()]);
+
+		expect(fragmentPlugin.getRules()).toEqual([prependRule, defaultRule, appendRule]);
+	});
+
+	it('should remove rules', () => {
+		fragmentPlugin.appendRule({
+			from: '/foo/',
+			to: '/bar/',
+			containers: ['#foobar'],
+			name: 'remove-me'
+		});
+		const rules = fragmentPlugin.getRules();
+		fragmentPlugin.setRules(rules.filter((rule) => rule.name !== 'remove-me'));
+		expect(fragmentPlugin.getRules()).toEqual([defaultRule]);
+	});
+});