aberdeen 1.5.0 → 1.7.0

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();
 }
@@ -170,9 +175,9 @@ export function go(target: RouteTarget, nav: NavType = "go"): void {
  * @param target Same as for {@link go}, but merged into the current route instead deleting all state.
  */
 export function push(target: RouteTarget): void {
-	let copy = clone(unproxy(current));
-	merge(copy, targetToPartial(target));
-	go(copy);
+	const c = clone(unproxy(current));
+	merge(c, targetToPartial(target));
+	go(c);
 }
 
 /**
@@ -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);
 		}
 	});
 });

package/skill/references/prediction.md

@@ -1,45 +0,0 @@
-# Prediction (Optimistic UI)
-
-Apply UI changes immediately, auto-revert when server responds.
-
-## API
-
-```typescript
-import { applyPrediction, applyCanon } from 'aberdeen/prediction';
-```
-
-### `applyPrediction(func)`
-Runs function and records all proxy changes as a "prediction".
-Returns a `Patch` to use as `dropPatches` later, when the server responds.
-
-### `applyCanon(func?, dropPatches?)`
-1. Reverts all predictions
-2. Runs `func` (typically applies server data)
-3. Drops specified patches
-4. Re-applies remaining predictions that still apply cleanly
-
-## Example
-```typescript
-async function toggleTodo(todo: Todo) {
-    // Optimistic update
-    const patch = applyPrediction(() => {
-        todo.done = !todo.done;
-    });
-
-    try {
-        const data = await api.updateTodo(todo.id, { done: todo.done });
-        
-        // Server responded - apply canonical state
-        applyCanon(() => {
-            Object.assign(todo, data);
-        }, [patch]);
-    } catch {
-        // On error, just drop the prediction to revert
-        applyCanon(undefined, [patch]);
-    }
-}
-```
-
-## When to Use
-- When you want immediate UI feedback for user actions for which a server is authoritative.
-- As doing this manually for each such case is tedious, this should usually be integrated into the data updating/fetching layer.

package/skill/references/routing.md

@@ -1,81 +0,0 @@
-# Routing and Dispatching
-
-## Router (`aberdeen/route`)
-
-The `current` object is a reactive proxy of the current URL state.
-
-### Properties
-| Property | Type | Description |
-|----------|------|-------------|
-| `path` | `string` | Normalized path (e.g., `/users/123`) |
-| `p` | `string[]` | Path segments (e.g., `['users', '123']`) |
-| `search` | `Record<string,string>` | Query parameters |
-| `hash` | `string` | URL hash including `#` |
-| `state` | `Record<string,any>` | JSON-compatible state data |
-| `nav` | `NavType` | How we got here: `load`, `back`, `forward`, `go`, `push` |
-| `depth` | `number` | Navigation stack depth (starts at 1) |
-
-### Navigation Functions
-```typescript
-import * as route from 'aberdeen/route';
-
-route.go('/users/42');                    // Navigate to new URL
-route.go({ p: ['users', 42], hash: 'top' }); // Object form
-route.push({ search: { tab: 'feed' } });  // Merge into current route
-route.back();                             // Go back in history
-route.back({ path: '/home' });            // Back to matching entry, or replace
-route.up();                               // Go up one path level
-route.persistScroll();                    // Save/restore scroll position
-```
-
-### Reactive Routing Example
-```typescript
-import * as route from 'aberdeen/route';
-
-$(() => {
-    const [section, id] = route.current.p;
-    if (section === 'users') drawUser(id);
-    else if (section === 'settings') drawSettings();
-    else drawHome();
-});
-```
-
-## Dispatcher (`aberdeen/dispatcher`)
-
-Type-safe path segment matching for complex routing.
-
-```typescript
-import { Dispatcher, matchRest } from 'aberdeen/dispatcher';
-import * as route from 'aberdeen/route';
-
-const d = new Dispatcher();
-
-// Literal string match
-d.addRoute('home', () => drawHome());
-
-// Number extraction (uses built-in Number function)
-d.addRoute('user', Number, (id) => drawUser(id));
-
-// String extraction
-d.addRoute('user', Number, 'post', String, (userId, postId) => {
-    drawPost(userId, postId);
-});
-
-// Rest of path as array
-d.addRoute('search', matchRest, (terms: string[]) => {
-    performSearch(terms);
-});
-
-// Dispatch in reactive scope
-$(() => {
-    if (!d.dispatch(route.current.p)) {
-        draw404();
-    }
-});
-```
-
-### Custom Matchers
-```typescript
-const uuid = (s: string) => /^[0-9a-f-]{36}$/.test(s) ? s : matchFailed;
-d.addRoute('item', uuid, (id) => drawItem(id));
-```

package/skill/references/transitions.md

@@ -1,52 +0,0 @@
-# Transitions
-
-Animate elements entering/leaving the DOM via the `create` and `destroy` properties.
-
-**Important:** Transitions only trigger for **top-level** elements of a scope being (re-)run. Deeply nested elements drawn as part of a larger redraw do not trigger transitions.
-
-## Built-in Transitions
-
-```typescript
-import { grow, shrink } from 'aberdeen/transitions';
-
-// Apply to individual elements
-$('div create=', grow, 'destroy=', shrink, '#Animated');
-
-// Common with onEach for list animations
-onEach(items, item => {
-    $('li create=', grow, 'destroy=', shrink, `#${item.text}`);
-});
-```
-
-- `grow`: Scales element from 0 to full size with margin animation
-- `shrink`: Scales element to 0 and removes from DOM after animation
-
-Both detect horizontal flex containers and animate width instead of height.
-
-## CSS-Based Transitions
-
-For custom transitions, use CSS class strings (dot-separated):
-```typescript
-const fadeStyle = insertCss({
-    transition: 'all 0.3s ease-out',
-    '&.hidden': { opacity: 0, transform: 'translateY(-10px)' }
-});
-
-// Class added briefly on create (removed after layout)
-// Class added on destroy (element removed after 2s delay)
-$('div', fadeStyle, 'create=.hidden destroy=.hidden#Fading element');
-```
-
-## Custom Transition Functions
-
-For full control, pass functions. For `destroy`, your function must remove the element:
-```typescript
-$('div create=', (el: HTMLElement) => {
-    // Animate on mount - element already in DOM
-    el.animate([{ opacity: 0 }, { opacity: 1 }], 300);
-}, 'destroy=', (el: HTMLElement) => {
-    // YOU must remove the element when done
-    el.animate([{ opacity: 1 }, { opacity: 0 }], 300)
-        .finished.then(() => el.remove());
-}, '#Custom animated');
-```