aberdeen 1.6.0 → 1.7.1

package/src/dispatcher.ts

@@ -1,20 +1,20 @@
 /**
  * Symbol to return when a custom {@link Dispatcher.addRoute} matcher cannot match a segment.
  */
-export const matchFailed: unique symbol = Symbol("matchFailed");
+export const MATCH_FAILED: unique symbol = Symbol("MATCH_FAILED");
 
 /**
  * Special {@link Dispatcher.addRoute} matcher that matches the rest of the segments as an array of strings.
  */
-export const matchRest: unique symbol = Symbol("matchRest");
+export const MATCH_REST: unique symbol = Symbol("MATCH_REST");
 
-type Matcher = string | ((segment: string) => any) | typeof matchRest;
+type Matcher = string | ((segment: string) => any) | typeof MATCH_REST;
 
 type ExtractParamType<M> =  M extends string
 ? never : (
     M extends ((segment: string) => infer R)
-    ? Exclude<R, typeof matchFailed>
-    : (M extends typeof matchRest ? string[] : never)
+    ? Exclude<R, typeof MATCH_FAILED>
+    : (M extends typeof MATCH_REST ? string[] : never)
 );
 
 type ParamsFromMatchers<T extends Matcher[]> = T extends [infer M1, ...infer Rest]
@@ -38,6 +38,9 @@ interface DispatcherRoute {
  * Example usage:
  * 
  * ```ts
+ * import * as route from 'aberdeen/route';
+ * import { Dispatcher, MATCH_REST } from 'aberdeen/dispatcher';
+ * 
  * const dispatcher = new Dispatcher();
  * 
  * dispatcher.addRoute("user", Number, "stream", String, (id, stream) => {
@@ -47,7 +50,7 @@ interface DispatcherRoute {
  * dispatcher.dispatch(["user", "42", "stream", "music"]);
  * // Logs: User 42, stream music
  * 
- * dispatcher.addRoute("search", matchRest, (terms: string[]) => {
+ * dispatcher.addRoute("search", MATCH_REST, (terms: string[]) => {
  *     console.log("Search terms:", terms);
  * });
  * 
@@ -62,8 +65,8 @@ export class Dispatcher {
      * Add a route with matchers and a handler function.
      * @param args An array of matchers followed by a handler function. Each matcher can be:
      * - A string: matches exactly that string.
-     * - A function: takes a string segment and returns a value (of any type) if it matches, or {@link matchFailed} if it doesn't match. The return value (if not `matchFailed` and not `NaN`) is passed as a parameter to the handler function. The built-in functions `Number` and `String` can be used to match numeric and string segments respectively.
-     * - The special {@link matchRest} symbol: matches the rest of the segments as an array of strings. Only one `matchRest` is allowed, and it must be the last matcher.
+     * - A function: takes a string segment and returns a value (of any type) if it matches, or {@link MATCH_FAILED} if it doesn't match. The return value (if not `MATCH_FAILED` and not `NaN`) is passed as a parameter to the handler function. The standard JavaScript functions `Number` and `String` can be used to match numeric and string segments respectively.
+     * - The special {@link MATCH_REST} symbol: matches the rest of the segments as an array of strings. Only one `MATCH_REST` is allowed.
      * @template T - Array of matcher types.
      * @template H - Handler function type, inferred from the matchers.
      */
@@ -75,9 +78,9 @@ export class Dispatcher {
             throw new Error("Last argument should be a handler function");
         }
         
-        const restCount = matchers.filter(m => m === matchRest).length;
+        const restCount = matchers.filter(m => m === MATCH_REST).length;
         if (restCount > 1) {
-            throw new Error("Only one matchRest is allowed");
+            throw new Error("Only one MATCH_REST is allowed");
         }
 
         this.routes.push({ matchers, handler });
@@ -105,7 +108,7 @@ function matchRoute(route: DispatcherRoute, segments: string[]): any[] | undefin
     let segmentIndex = 0;
 
     for (const matcher of route.matchers) {
-        if (matcher === matchRest) {
+        if (matcher === MATCH_REST) {
             const len = segments.length - (route.matchers.length - 1);
             if (len < 0) return;
             args.push(segments.slice(segmentIndex, segmentIndex + len));
@@ -120,11 +123,11 @@ function matchRoute(route: DispatcherRoute, segments: string[]): any[] | undefin
             if (segment !== matcher) return;
         } else if (typeof matcher === "function") {
             const result = matcher(segment);
-            if (result === matchFailed || (typeof result === 'number' && isNaN(result))) return;
+            if (result === MATCH_FAILED || (typeof result === 'number' && isNaN(result))) return;
             args.push(result);
         }
         
         segmentIndex++;
     }
-    return args; // success!
+    if (segmentIndex === segments.length) return args; // success!
 }

package/src/route.ts

@@ -1,4 +1,4 @@
-import {clean, getParentElement, $, proxy, runQueue, unproxy, copy, merge, clone, leakScope} from "./aberdeen.js";
+import {clean, $, proxy, runQueue, unproxy, copy, merge, clone, leakScope} from "./aberdeen.js";
 
 type NavType = "load" | "back" | "forward" | "go" | "push";
 
@@ -44,13 +44,18 @@ export function setLog(value: boolean | ((...args: any[]) => void)) {
 	}
 }
 
+declare const ABERDEEN_FAKE_WINDOW: Window | undefined;
+const windowE = typeof ABERDEEN_FAKE_WINDOW !== 'undefined'? ABERDEEN_FAKE_WINDOW : window;
+const locationE = windowE.location;
+const historyE = windowE.history;
+
 function getRouteFromBrowser(): Route {
 	return toCanonRoute({
-		path: location.pathname,
-		hash: location.hash,
-		search: Object.fromEntries(new URLSearchParams(location.search)),
-		state: history.state?.state || {},
-	}, "load", (history.state?.stack?.length || 0) + 1);
+		path: locationE.pathname,
+		hash: locationE.hash,
+		search: Object.fromEntries(new URLSearchParams(locationE.search)),
+		state: 	historyE.state?.state || {},
+	}, "load", (historyE.state?.stack?.length || 0) + 1);
 }
 
 /**
@@ -149,7 +154,7 @@ function targetToPartial(target: RouteTarget) {
 * ```
 */
 export function go(target: RouteTarget, nav: NavType = "go"): void {
-	const stack: string[] = history.state?.stack || [];
+	const stack: string[] = historyE.state?.stack || [];
 
 	prevStack = stack.concat(JSON.stringify(unproxy(current)));
 	
@@ -157,7 +162,7 @@ export function go(target: RouteTarget, nav: NavType = "go"): void {
 	copy(current, newRoute);
 	
 	log(nav, newRoute);
-	history.pushState({state: newRoute.state, stack: prevStack}, "", getUrl(newRoute));
+	historyE.pushState({state: newRoute.state, stack: prevStack}, "", getUrl(newRoute));
 	
 	runQueue();
 }
@@ -184,13 +189,13 @@ export function push(target: RouteTarget): void {
  */
 export function back(target: RouteTarget = {}): void {
 	const partial = targetToPartial(target);
-	const stack: string[] = history.state?.stack || [];
+	const stack: string[] = historyE.state?.stack || [];
 	for(let i = stack.length - 1; i >= 0; i--) {
 		const histRoute: Route = JSON.parse(stack[i]);
 		if (equal(histRoute, partial, true)) {
 			const pages = i - stack.length;
 			log(`back`, pages, histRoute);
-			history.go(pages);
+			historyE.go(pages);
 			return;
 		}
 	}
@@ -209,13 +214,13 @@ export function back(target: RouteTarget = {}): void {
 */
 export function up(stripCount: number = 1): void {
 	const currentP = unproxy(current).p;
-	const stack: string[] = history.state?.stack || [];
+	const stack: string[] = historyE.state?.stack || [];
 	for(let i = stack.length - 1; i >= 0; i--) {
 		const histRoute: Route = JSON.parse(stack[i]);
 		if (histRoute.p.length < currentP.length && equal(histRoute.p, currentP.slice(0, histRoute.p.length), false)) {
 			// This route is shorter and matches the start of the current path
 			log(`up to ${i+1} / ${stack.length}`, histRoute);
-			history.go(i - stack.length);
+			historyE.go(i - stack.length);
 			return;
 		}
 	}
@@ -235,7 +240,7 @@ export function up(stripCount: number = 1): void {
 * The scroll position will be persisted in `route.aux.scroll.<name>`.
 */
 export function persistScroll(name = "main") {
-	const el = getParentElement();
+	const el = $()!;
 	el.addEventListener("scroll", onScroll);
 	clean(() => el.removeEventListener("scroll", onScroll));
 	
@@ -253,6 +258,72 @@ export function persistScroll(name = "main") {
 	}
 }
 
+/**
+ * Intercept clicks and Enter key presses on links (`<a>` tags) and use Aberdeen routing
+ * instead of browser navigation for local paths (paths without a protocol or host).
+ * 
+ * This allows you to use regular HTML anchor tags for navigation without needing to
+ * manually attach click handlers to each link.
+ * 
+ * @example
+ * ```js
+ * // In your root component:
+ * route.interceptLinks();
+ * 
+ * // Now you can use regular anchor tags:
+ * $('a text=About href=/corporate/about');
+ * ```
+ */
+export function interceptLinks() {
+	$({
+		click: handleEvent,
+		keydown: handleKeyEvent,
+	});
+	
+	function handleKeyEvent(e: KeyboardEvent) {
+		if (e.key === "Enter") {
+			handleEvent(e);
+		}
+	}
+	
+	function handleEvent(e: Event) {
+		// Find the closest <a> tag
+		let target = e.target as HTMLElement | null;
+		while (target && target.tagName?.toUpperCase() !== "A") {
+			target = target.parentElement;
+		}
+		
+		if (!target) return;
+		
+		const anchor = target as HTMLAnchorElement;
+		const href = anchor.getAttribute("href");
+		
+		if (!href) return;
+		
+		// Skip hash-only links
+		if (href.startsWith("#")) return;
+		
+		// Skip if it has a protocol or is protocol-relative (// or contains : before any / ? #)
+		if (href.startsWith("//") || /^[^/?#]+:/.test(href)) return;
+		
+		// Skip if the link has target or download attribute
+		if (anchor.getAttribute("target") || anchor.getAttribute("download")) return;
+		
+		// Skip if modifier keys are pressed (Ctrl/Cmd click to open in new tab)
+		if (typeof MouseEvent !== 'undefined' && e instanceof MouseEvent && (e.ctrlKey || e.metaKey || e.shiftKey)) return;
+		
+		e.preventDefault();
+		
+		// Parse using URL to handle both absolute and relative paths correctly
+		const url = new URL(href, locationE.href);
+		go({
+			path: url.pathname,
+			search: Object.fromEntries(url.searchParams),
+			hash: url.hash,
+		});
+	}
+}
+
 let prevStack: string[];
 
 /**
@@ -265,7 +336,7 @@ export const current: Route = proxy({}) as Route;
  * @internal
  * */
 export function reset() {
-	prevStack = history.state?.stack || [];
+	prevStack = historyE.state?.stack || [];
 	const initRoute = getRouteFromBrowser();
 	log('initial', initRoute);
 	copy(unproxy(current), initRoute);
@@ -273,12 +344,12 @@ export function reset() {
 reset();
 
 // Handle browser history back and forward
-window.addEventListener("popstate", function(event: PopStateEvent) {
+windowE.addEventListener("popstate", function(event: PopStateEvent) {
 	const newRoute = getRouteFromBrowser();
 	
 	// If the stack length changes, and at least the top-most shared entry is the same,
 	// we'll interpret this as a "back" or "forward" navigation.
-	const stack: string[] = history.state?.stack || [];
+	const stack: string[] = historyE.state?.stack || [];
 	if (stack.length !== prevStack.length) {
 		const maxIndex = Math.min(prevStack.length, stack.length) - 1;
 		if (maxIndex < 0 || stack[maxIndex] === prevStack[maxIndex]) {
@@ -306,16 +377,16 @@ leakScope(() => {
 	$(() => {
 
 		// First normalize `route`
-		const stack = history.state?.stack || [];
+		const stack = historyE.state?.stack || [];
 		const newRoute = toCanonRoute(current, unproxy(current).nav, stack.length + 1);
 		copy(current, newRoute);
 		
 		// Then replace the current browser state if something actually changed
 		const state = {state: newRoute.state, stack};
 		const url = getUrl(newRoute);
-		if (url !== location.pathname + location.search + location.hash || !equal(history.state, state, false)) {
+		if (url !== locationE.pathname + locationE.search + locationE.hash || !equal(historyE.state, state, false)) {
 			log('replaceState', newRoute, state, url);
-			history.replaceState(state, "", url);
+			historyE.replaceState(state, "", url);
 		}
 	});
 });