feat: Adds scope prop to LocationProvider, limiting link intercepts

README.md

@@ -82,6 +82,10 @@ export async function prerender(data) {
 
 A context provider that provides the current location to its children. This is required for the router to function.
 
+Props:
+
+-   `limit?: string | RegExp` - Sets a limit on the paths that the router will handle (intercept). If a path does not match the limit, either by starting with the provided string or matching the RegExp, the router will ignore it and default browser navigation will apply.
+
 Typically, you would wrap your entire app in this provider:
 
 ```js

src/router.d.ts

@@ -1,6 +1,9 @@
 import { AnyComponent, FunctionComponent, VNode } from 'preact';
 
-export const LocationProvider: FunctionComponent;
+export function LocationProvider(props: {
+	limit?: string | RegExp;
+	children?: VNode[];
+}): VNode;
 
 type NestedArray<T> = Array<T | NestedArray<T>>;
 

src/router.js

@@ -7,7 +7,7 @@ import { useContext, useMemo, useReducer, useLayoutEffect, useRef } from 'preact
  * @typedef {import('./internal.d.ts').VNode} VNode
  */
 
-let push;
+let push, limit;
 const UPDATE = (state, url) => {
 	push = undefined;
 	if (url && url.type === 'click') {
@@ -16,12 +16,17 @@ const UPDATE = (state, url) => {
 			return state;
 		}
 
-		const link = url.target.closest('a[href]');
+		const link = url.target.closest('a[href]'),
+			href = link.getAttribute('href');
 		if (
 			!link ||
 			link.origin != location.origin ||
-			/^#/.test(link.getAttribute('href')) ||
-			!/^(_?self)?$/i.test(link.target)
+			/^#/.test(href) ||
+			!/^(_?self)?$/i.test(link.target) ||
+			limit && (typeof limit == 'string'
+				? !href.startsWith(limit)
+				: !limit.test(href)
+			)
 		) {
 			return state;
 		}
@@ -72,6 +77,7 @@ export const exec = (url, route, matches) => {
 
 export function LocationProvider(props) {
 	const [url, route] = useReducer(UPDATE, props.url || location.pathname + location.search);
+	if (props.limit) limit = props.limit;
 	const wasPush = push === true;
 
 	const value = useMemo(() => {

test/router.test.js

@@ -505,7 +505,6 @@ describe('Router', () => {
 		const shouldIntercept = [null, '', '_self', 'self', '_SELF'];
 		const shouldNavigate = ['_top', '_parent', '_blank', 'custom', '_BLANK'];
 
-		// prevent actual navigations (not implemented in JSDOM)
 		const clickHandler = sinon.fake(e => e.preventDefault());
 
 		const Route = sinon.fake(
@@ -583,6 +582,152 @@ describe('Router', () => {
 		}
 	});
 
+	describe('intercepted VS external links with `limit`', () => {
+		const shouldIntercept = ['/app', '/app/deeper'];
+		const shouldNavigate = ['/site', '/site/deeper'];
+
+		const clickHandler = sinon.fake(e => e.preventDefault());
+
+		const Route = sinon.fake(
+			() => (
+				<div>
+					<a href="/app">Internal Link</a>
+					<a href="/app/deeper">Internal Deeper Link</a>
+					<a href="/site">External Link</a>
+					<a href="/site/deeper">External Deeper Link</a>
+				</div>
+			)
+		);
+
+		let pushState;
+
+		before(() => {
+			pushState = sinon.spy(history, 'pushState');
+			addEventListener('click', clickHandler);
+		});
+
+		after(() => {
+			pushState.restore();
+			removeEventListener('click', clickHandler);
+		});
+
+		beforeEach(async () => {
+			Route.resetHistory();
+			clickHandler.resetHistory();
+			pushState.resetHistory();
+		});
+
+		it('should intercept clicks on links matching the `limit` props (string)', async () => {
+			render(
+				<LocationProvider limit="/app">
+					<Router>
+						<Route default />
+					</Router>
+					<ShallowLocation />
+				</LocationProvider>,
+				scratch
+			);
+			Route.resetHistory();
+			await sleep(10);
+
+			for (const url of shouldIntercept) {
+				const el = scratch.querySelector(`a[href="${url}"]`);
+				el.click();
+				await sleep(1);
+				expect(loc).to.deep.include({ url });
+				expect(Route).to.have.been.calledOnce;
+				expect(pushState).to.have.been.calledWith(null, '', url);
+				expect(clickHandler).to.have.been.called;
+
+				Route.resetHistory();
+				pushState.resetHistory();
+				clickHandler.resetHistory();
+			}
+		});
+
+		it('should allow default browser navigation for links not matching the `limit` props (string)', async () => {
+			render(
+				<LocationProvider limit="app">
+					<Router>
+						<Route default />
+					</Router>
+					<ShallowLocation />
+				</LocationProvider>,
+				scratch
+			);
+			Route.resetHistory();
+			await sleep(10);
+
+			for (const url of shouldNavigate) {
+				const el = scratch.querySelector(`a[href="${url}"]`);
+				el.click();
+				await sleep(1);
+				expect(Route).not.to.have.been.called;
+				expect(pushState).not.to.have.been.called;
+				expect(clickHandler).to.have.been.called;
+
+				Route.resetHistory();
+				pushState.resetHistory();
+				clickHandler.resetHistory();
+			}
+		});
+
+		it('should intercept clicks on links matching the `limit` props (regex)', async () => {
+			render(
+				<LocationProvider limit={/^\/app/}>
+					<Router>
+						<Route default />
+					</Router>
+					<ShallowLocation />
+				</LocationProvider>,
+				scratch
+			);
+			Route.resetHistory();
+			await sleep(10);
+
+			for (const url of shouldIntercept) {
+				const el = scratch.querySelector(`a[href="${url}"]`);
+				el.click();
+				await sleep(1);
+				expect(loc).to.deep.include({ url });
+				expect(Route).to.have.been.calledOnce;
+				expect(pushState).to.have.been.calledWith(null, '', url);
+				expect(clickHandler).to.have.been.called;
+
+				Route.resetHistory();
+				pushState.resetHistory();
+				clickHandler.resetHistory();
+			}
+		});
+
+		it('should allow default browser navigation for links not matching the `limit` props (regex)', async () => {
+			render(
+				<LocationProvider limit={/^\/app/}>
+					<Router>
+						<Route default />
+					</Router>
+					<ShallowLocation />
+				</LocationProvider>,
+				scratch
+			);
+			Route.resetHistory();
+			await sleep(10);
+
+			for (const url of shouldNavigate) {
+				const el = scratch.querySelector(`a[href="${url}"]`);
+				el.click();
+				await sleep(1);
+				expect(Route).not.to.have.been.called;
+				expect(pushState).not.to.have.been.called;
+				expect(clickHandler).to.have.been.called;
+
+				Route.resetHistory();
+				pushState.resetHistory();
+				clickHandler.resetHistory();
+			}
+		});
+	});
+
 	it('should scroll to top when navigating forward', async () => {
 		const scrollTo = sinon.spy(window, 'scrollTo');