@esmx/router 3.0.0-rc.25 → 3.0.0-rc.26

package/dist/navigation.d.ts

@@ -18,7 +18,9 @@ export declare class Navigation {
     replace(data: any, url?: string | URL | null): RouteState;
     pushHistoryState(data: any, url?: string | URL | null): void;
     replaceHistoryState(data: any, url?: string | URL | null): void;
-    go(index: number): Promise<NavigationGoResult>;
+    backHistoryState(): Promise<NavigationGoResult>;
+    private _go;
+    go(delta?: number): Promise<NavigationGoResult>;
     forward(): Promise<NavigationGoResult>;
     back(): Promise<NavigationGoResult>;
     destroy(): void;

package/dist/navigation.mjs

@@ -53,7 +53,10 @@ export class Navigation {
   replaceHistoryState(data, url) {
     this._replace(history, data, url);
   }
-  go(index) {
+  backHistoryState() {
+    return this._go(history, -1);
+  }
+  _go(history2, index) {
     if (this._promiseResolve) {
       return Promise.resolve(null);
     }
@@ -64,9 +67,12 @@ export class Navigation {
         resolve({ type: "success", url, state: state || {} });
       };
       setTimeout(this._promiseResolve, 80);
-      this._history.go(index);
+      history2.go(index);
     });
   }
+  go(delta) {
+    return this._go(this._history, delta || 0);
+  }
   forward() {
     return this.go(1);
   }

package/dist/router-link.mjs

@@ -18,9 +18,13 @@ function getEventTypeList(eventType) {
   return validEvents.length ? validEvents : ["click"];
 }
 function guardEvent(e) {
-  if (e.metaKey || e.altKey || e.ctrlKey || e.shiftKey) return false;
-  if (e.defaultPrevented) return false;
-  if (e.button !== void 0 && e.button !== 0) return false;
+  var _a, _b, _c;
+  if (!e) return;
+  if (e.metaKey || e.altKey || e.ctrlKey || e.shiftKey) return;
+  if (e.defaultPrevented) return;
+  if (e.button !== void 0 && e.button !== 0) return;
+  const target = (_c = (_b = (_a = e.currentTarget) == null ? void 0 : _a.getAttribute) == null ? void 0 : _b.call(_a, "target")) != null ? _c : "";
+  if (/\b_blank\b/i.test(target)) return;
   if (e.preventDefault) e.preventDefault();
   return true;
 }
@@ -50,9 +54,9 @@ async function executeNavigation(router, props, linkType) {
 }
 function createNavigateFunction(router, props, navigationType) {
   return async (e) => {
-    if (e && !guardEvent(e)) {
-      return;
-    }
+    var _a;
+    const eventHandler = (_a = props.eventHandler) != null ? _a : guardEvent;
+    if (!eventHandler(e)) return;
     await executeNavigation(router, props, navigationType);
   };
 }
@@ -88,7 +92,8 @@ function createEventHandlersGenerator(navigate, eventTypes) {
   return (nameTransform) => {
     const handlers = {};
     eventTypes.forEach((eventType) => {
-      const eventName = nameTransform ? nameTransform(eventType) : eventType.toLowerCase();
+      var _a;
+      const eventName = (_a = nameTransform == null ? void 0 : nameTransform(eventType)) != null ? _a : eventType.toLowerCase();
       handlers[eventName] = navigate;
     });
     return handlers;

package/dist/router.mjs

@@ -200,10 +200,10 @@ export class Router {
   }
   async createLayer(toInput) {
     var _a;
-    const layerOptions = (isPlainObject(toInput) ? toInput.layer : null) || {};
+    const layerOptions = isPlainObject(toInput) && toInput.layer || {};
     const zIndex = (_a = layerOptions.zIndex) != null ? _a : this.parsedOptions.zIndex + LAYER_ID.next();
     let promiseResolve;
-    const promise = new Promise((resolve) => {
+    let promise = new Promise((resolve) => {
       promiseResolve = resolve;
     });
     const router = new Router({
@@ -265,6 +265,18 @@ export class Router {
         router.route.state,
         router.route.url
       );
+      promise = promise.then(async (result) => {
+        await this.navigation.backHistoryState();
+        return result;
+      });
+    }
+    if (layerOptions.autoPush) {
+      promise = promise.then(async (result) => {
+        if (result.type === "push") {
+          await this.push(result.route.url.href);
+        }
+        return result;
+      });
     }
     return {
       promise,

package/dist/types.d.ts

@@ -214,6 +214,7 @@ export interface RouterLinkAttributes {
     target?: '_blank';
     rel?: string;
 }
+export type RouterLinkEventHandler = <E extends Event = MouseEvent>(event: E) => boolean | void;
 /**
  * Framework-agnostic link configuration interface
  */
@@ -229,6 +230,7 @@ export interface RouterLinkProps {
     event?: string | string[];
     tag?: string;
     layerOptions?: RouteLayerOptions;
+    eventHandler?: RouterLinkEventHandler;
 }
 /**
  * Framework-agnostic link resolution result
@@ -241,6 +243,6 @@ export interface RouterLinkResolved {
     isExternal: boolean;
     tag: string;
     attributes: RouterLinkAttributes;
-    navigate: (e?: MouseEvent) => Promise<void>;
-    getEventHandlers: (nameTransform?: (eventType: string) => string) => Record<string, (e: MouseEvent) => Promise<void>>;
+    navigate: (e?: Event) => Promise<void>;
+    getEventHandlers: (nameTransform?: (eventType: string) => string) => Record<string, (e: Event) => Promise<void> | undefined>;
 }

package/package.json

@@ -32,7 +32,7 @@
     },
     "devDependencies": {
         "@biomejs/biome": "1.9.4",
-        "@esmx/lint": "3.0.0-rc.25",
+        "@esmx/lint": "3.0.0-rc.26",
         "@types/node": "^24.0.10",
         "@vitest/coverage-v8": "3.2.4",
         "happy-dom": "^18.0.1",
@@ -41,7 +41,7 @@
         "unbuild": "3.5.0",
         "vitest": "3.2.4"
     },
-    "version": "3.0.0-rc.25",
+    "version": "3.0.0-rc.26",
     "type": "module",
     "private": false,
     "exports": {
@@ -60,5 +60,5 @@
         "template",
         "public"
     ],
-    "gitHead": "da6576d7505ad48cb78905b18e17940d43510250"
+    "gitHead": "2f52f94c8ac27aca32ef3148afd109d0f0470d52"
 }

package/src/navigation.ts

@@ -86,7 +86,11 @@ export class Navigation {
         this._replace(history, data, url);
     }
 
-    public go(index: number): Promise<NavigationGoResult> {
+    public backHistoryState() {
+        return this._go(history, -1);
+    }
+
+    private _go(history: History, index: number): Promise<NavigationGoResult> {
         if (this._promiseResolve) {
             return Promise.resolve(null);
         }
@@ -97,9 +101,12 @@ export class Navigation {
                 resolve({ type: 'success', url, state: state || {} });
             };
             setTimeout(this._promiseResolve, 80);
-            this._history.go(index);
+            history.go(index);
         });
     }
+    public go(delta?: number): Promise<NavigationGoResult> {
+        return this._go(this._history, delta || 0);
+    }
     public forward(): Promise<NavigationGoResult> {
         return this.go(1);
     }

package/src/router-link.ts

@@ -43,19 +43,24 @@ function getEventTypeList(eventType: unknown | unknown[]): string[] {
 /**
  * Event guard check - determines if the router should handle the navigation
  *
- * Returns false: Let browser handle default behavior (normal link navigation)
- * Returns true: Router takes over navigation, prevents default browser behavior
+ * Returns !0: Let browser handle default behavior (normal link navigation)
+ * Returns 0: Router takes over navigation, prevents default browser behavior
  *
  * This function intelligently decides when to let the browser handle clicks
  * (like Ctrl+click for new tabs) vs when to use SPA routing
  */
-function guardEvent(e: MouseEvent): boolean {
+function guardEvent(e?: Event & Partial<MouseEvent>): true | undefined {
+    if (!e) return;
     // don't redirect with control keys
-    if (e.metaKey || e.altKey || e.ctrlKey || e.shiftKey) return false;
+    if (e.metaKey || e.altKey || e.ctrlKey || e.shiftKey) return;
     // don't redirect when preventDefault called
-    if (e.defaultPrevented) return false;
+    if (e.defaultPrevented) return;
     // don't redirect on right click
-    if (e.button !== undefined && e.button !== 0) return false;
+    if (e.button !== undefined && e.button !== 0) return;
+    // don't redirect if `target="_blank"`
+    // @ts-expect-error getAttribute exists
+    const target = e.currentTarget?.getAttribute?.('target') ?? '';
+    if (/\b_blank\b/i.test(target)) return;
     // Prevent default browser navigation to enable SPA routing
     // Note: this may be a Weex event which doesn't have this method
     if (e.preventDefault) e.preventDefault();
@@ -107,11 +112,10 @@ function createNavigateFunction(
     router: Router,
     props: RouterLinkProps,
     navigationType: RouterLinkType
-): (e?: MouseEvent) => Promise<void> {
-    return async (e?: MouseEvent): Promise<void> => {
-        if (e && !guardEvent(e)) {
-            return;
-        }
+): (e?: Event) => Promise<void> {
+    return async (e?: Event): Promise<void> => {
+        const eventHandler = props.eventHandler ?? guardEvent;
+        if (!eventHandler(e!)) return;
 
         await executeNavigation(router, props, navigationType);
     };
@@ -169,18 +173,17 @@ function computeAttributes(
  * Create event handlers generator function
  */
 function createEventHandlersGenerator(
-    navigate: (e?: MouseEvent) => Promise<void>,
+    navigate: (e: Event) => Promise<void>,
     eventTypes: string[]
 ): (
     nameTransform?: (eventType: string) => string
-) => Record<string, (e: MouseEvent) => Promise<void>> {
+) => Record<string, (e: Event) => Promise<void>> {
     return (nameTransform?: (eventType: string) => string) => {
-        const handlers: Record<string, (e: MouseEvent) => Promise<void>> = {};
+        const handlers: Record<string, (e: Event) => Promise<void>> = {};
 
         eventTypes.forEach((eventType) => {
-            const eventName = nameTransform
-                ? nameTransform(eventType)
-                : eventType.toLowerCase();
+            const eventName =
+                nameTransform?.(eventType) ?? eventType.toLowerCase();
             handlers[eventName] = navigate;
         });
 

package/src/router.ts

@@ -227,13 +227,13 @@ export class Router {
         toInput: RouteLocationInput
     ): Promise<{ promise: Promise<RouteLayerResult>; router: Router }> {
         const layerOptions: RouteLayerOptions =
-            (isPlainObject(toInput) ? toInput.layer : null) || {};
+            (isPlainObject(toInput) && toInput.layer) || {};
 
         const zIndex =
             layerOptions.zIndex ?? this.parsedOptions.zIndex + LAYER_ID.next();
 
         let promiseResolve: (result: RouteLayerResult) => void;
-        const promise = new Promise<RouteLayerResult>((resolve) => {
+        let promise = new Promise<RouteLayerResult>((resolve) => {
             promiseResolve = resolve;
         });
 
@@ -297,6 +297,18 @@ export class Router {
                 router.route.state,
                 router.route.url
             );
+            promise = promise.then(async (result) => {
+                await this.navigation.backHistoryState();
+                return result;
+            });
+        }
+        if (layerOptions.autoPush) {
+            promise = promise.then(async (result) => {
+                if (result.type === 'push') {
+                    await this.push(result.route.url.href);
+                }
+                return result;
+            });
         }
         return {
             promise,

package/src/types.ts

@@ -299,6 +299,10 @@ export interface RouterLinkAttributes {
     rel?: string;
 }
 
+export type RouterLinkEventHandler = <E extends Event = MouseEvent>(
+    event: E
+) => boolean | void;
+
 /**
  * Framework-agnostic link configuration interface
  */
@@ -314,6 +318,7 @@ export interface RouterLinkProps {
     event?: string | string[];
     tag?: string;
     layerOptions?: RouteLayerOptions;
+    eventHandler?: RouterLinkEventHandler;
 }
 
 /**
@@ -332,10 +337,10 @@ export interface RouterLinkResolved {
     attributes: RouterLinkAttributes;
 
     // Navigation function
-    navigate: (e?: MouseEvent) => Promise<void>;
+    navigate: (e?: Event) => Promise<void>;
 
     // Event handling
     getEventHandlers: (
         nameTransform?: (eventType: string) => string
-    ) => Record<string, (e: MouseEvent) => Promise<void>>;
+    ) => Record<string, (e: Event) => Promise<void> | undefined>;
 }