feat: Adds scope prop to LocationProvider, limiting link intercep…

…ts (#42)

README.md

@@ -82,13 +82,17 @@ 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:
+
+-   `scope?: string | RegExp` - Sets a scope for the paths that the router will handle (intercept). If a path does not match the scope, 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
 import { LocationProvider } from 'preact-iso';
 
 const App = () => (
-    <LocationProvider>
+    <LocationProvider scope="/app">
         {/* Your app here */}
     </LocationProvider>
 );

src/router.d.ts

@@ -1,6 +1,9 @@
-import { AnyComponent, FunctionComponent, VNode } from 'preact';
+import { AnyComponent, ComponentChildren, FunctionComponent, VNode } from 'preact';
 
-export const LocationProvider: FunctionComponent;
+export function LocationProvider(props: {
+	scope?: string | RegExp;
+	children?: ComponentChildren;
+}): 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, scope;
 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) ||
+			scope && (typeof scope == 'string'
+				? !href.startsWith(scope)
+				: !scope.test(href)
+			)
 		) {
 			return state;
 		}
@@ -70,8 +75,13 @@ export const exec = (url, route, matches) => {
 	return matches;
 };
 
+/**
+ * @type {import('./router.d.ts').LocationProvider}
+ */
 export function LocationProvider(props) {
+	// @ts-expect-error - props.url is not implemented correctly & will be removed in the future
 	const [url, route] = useReducer(UPDATE, props.url || location.pathname + location.search);
+	if (props.scope) scope = props.scope;
 	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,129 @@ describe('Router', () => {
 		}
 	});
 
+	describe('intercepted VS external links with `scope`', () => {
+		const shouldIntercept = ['/app', '/app/deeper'];
+		const shouldNavigate = ['/site', '/site/deeper'];
+
+		const clickHandler = sinon.fake(e => e.preventDefault());
+
+		const Links = () => (
+			<>
+				<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>
+			</>
+		);
+
+		let pushState;
+
+		before(() => {
+			pushState = sinon.spy(history, 'pushState');
+			addEventListener('click', clickHandler);
+		});
+
+		after(() => {
+			pushState.restore();
+			removeEventListener('click', clickHandler);
+		});
+
+		beforeEach(async () => {
+			clickHandler.resetHistory();
+			pushState.resetHistory();
+		});
+
+		it('should intercept clicks on links matching the `scope` props (string)', async () => {
+			render(
+				<LocationProvider scope="/app">
+					<Links />
+					<ShallowLocation />
+				</LocationProvider>,
+				scratch
+			);
+			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(pushState).to.have.been.calledWith(null, '', url);
+				expect(clickHandler).to.have.been.called;
+
+				pushState.resetHistory();
+				clickHandler.resetHistory();
+			}
+		});
+
+		it('should allow default browser navigation for links not matching the `limit` props (string)', async () => {
+			render(
+				<LocationProvider scope="app">
+					<Links />
+					<ShallowLocation />
+				</LocationProvider>,
+				scratch
+			);
+			await sleep(10);
+
+			for (const url of shouldNavigate) {
+				const el = scratch.querySelector(`a[href="${url}"]`);
+				el.click();
+				await sleep(1);
+				expect(pushState).not.to.have.been.called;
+				expect(clickHandler).to.have.been.called;
+
+				pushState.resetHistory();
+				clickHandler.resetHistory();
+			}
+		});
+
+		it('should intercept clicks on links matching the `limit` props (regex)', async () => {
+			render(
+				<LocationProvider scope={/^\/app/}>
+					<Links />
+					<ShallowLocation />
+				</LocationProvider>,
+				scratch
+			);
+			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(pushState).to.have.been.calledWith(null, '', url);
+				expect(clickHandler).to.have.been.called;
+
+				pushState.resetHistory();
+				clickHandler.resetHistory();
+			}
+		});
+
+		it('should allow default browser navigation for links not matching the `limit` props (regex)', async () => {
+			render(
+				<LocationProvider scope={/^\/app/}>
+					<Links />
+					<ShallowLocation />
+				</LocationProvider>,
+				scratch
+			);
+			await sleep(10);
+
+			for (const url of shouldNavigate) {
+				const el = scratch.querySelector(`a[href="${url}"]`);
+				el.click();
+				await sleep(1);
+				expect(pushState).not.to.have.been.called;
+				expect(clickHandler).to.have.been.called;
+
+				pushState.resetHistory();
+				clickHandler.resetHistory();
+			}
+		});
+	});
+
 	it('should scroll to top when navigating forward', async () => {
 		const scrollTo = sinon.spy(window, 'scrollTo');