@esmx/router 3.0.0-rc.59 → 3.0.0-rc.61

package/dist/options.mjs

@@ -30,7 +30,7 @@ function getBaseUrl(options) {
   return base;
 }
 export function parsedOptions(options = {}) {
-  var _a, _b, _c, _d, _e, _f;
+  var _a, _b, _c, _d, _e, _f, _g;
   const base = getBaseUrl(options);
   const routes = (_a = options.routes) != null ? _a : [];
   const compiledRoutes = createRouteMatches(routes);
@@ -50,9 +50,11 @@ export function parsedOptions(options = {}) {
     matcher: createMatcher(routes, compiledRoutes),
     normalizeURL: (_c = options.normalizeURL) != null ? _c : (url) => url,
     fallback: (_d = options.fallback) != null ? _d : fallback,
-    handleBackBoundary: (_e = options.handleBackBoundary) != null ? _e : () => {
+    nextTick: (_e = options.nextTick) != null ? _e : () => {
     },
-    handleLayerClose: (_f = options.handleLayerClose) != null ? _f : () => {
+    handleBackBoundary: (_f = options.handleBackBoundary) != null ? _f : () => {
+    },
+    handleLayerClose: (_g = options.handleLayerClose) != null ? _g : () => {
     }
   });
 }

package/dist/route-task.mjs

@@ -20,10 +20,7 @@ export class RouteTaskController {
     this._aborted = true;
   }
   shouldCancel(name) {
-    if (this._aborted) {
-      return true;
-    }
-    return false;
+    return this._aborted;
   }
 }
 export async function createRouteTask(opts) {

package/dist/route-transition.mjs

@@ -6,8 +6,14 @@ import {
   RouteTaskController,
   createRouteTask
 } from "./route-task.mjs";
+import {
+  getSavedScrollPosition,
+  saveScrollPosition,
+  scrollToPosition
+} from "./scroll.mjs";
 import { RouteType } from "./types.mjs";
 import {
+  isBrowser,
   isRouteMatched,
   isUrlEqual,
   isValidConfirmHookResult,
@@ -106,6 +112,44 @@ export const ROUTE_TRANSITION_HOOKS = {
         return result;
       }
     }
+    if (isBrowser && "scrollRestoration" in window.history)
+      window.history.scrollRestoration = "manual";
+    if (from && isBrowser && !router.isLayer)
+      switch (to.type) {
+        case RouteType.push:
+        case RouteType.replace: {
+          if (!to.keepScrollPosition) {
+            saveScrollPosition(from.url.href);
+            scrollToPosition({ left: 0, top: 0 });
+          } else {
+            to.applyNavigationState({
+              __keepScrollPosition: to.keepScrollPosition
+            });
+          }
+          break;
+        }
+        case RouteType.go:
+        case RouteType.forward:
+        case RouteType.back:
+        // for popstate
+        case RouteType.unknown: {
+          saveScrollPosition(from.url.href);
+          setTimeout(async () => {
+            const state = window.history.state;
+            if (state == null ? void 0 : state.__keepScrollPosition) {
+              return;
+            }
+            const savedPosition = getSavedScrollPosition(
+              to.url.href,
+              { left: 0, top: 0 }
+            );
+            if (!savedPosition) return;
+            await router.parsedOptions.nextTick();
+            scrollToPosition(savedPosition);
+          });
+          break;
+        }
+      }
     switch (to.type) {
       case RouteType.push:
         return ROUTE_TYPE_HANDLERS.push;

package/dist/router-link.mjs

@@ -17,15 +17,14 @@ function getEventTypeList(eventType) {
   const validEvents = events.filter((type) => typeof type === "string").map((type) => type.trim()).filter(Boolean);
   return validEvents.length ? validEvents : ["click"];
 }
-function guardEvent(e) {
-  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();
+function shouldHandleNavigation(e) {
+  var _a;
+  if (e.defaultPrevented) return false;
+  if (e instanceof MouseEvent) {
+    if (e.metaKey || e.altKey || e.ctrlKey || e.shiftKey) return false;
+    if (e.button !== void 0 && e.button !== 0) return false;
+  }
+  (_a = e.preventDefault) == null ? void 0 : _a.call(e);
   return true;
 }
 async function executeNavigation(router, props, linkType) {
@@ -54,10 +53,9 @@ async function executeNavigation(router, props, linkType) {
 }
 function createNavigateFunction(router, props, navigationType) {
   return async (e) => {
-    var _a;
-    const eventHandler = (_a = props.eventHandler) != null ? _a : guardEvent;
-    if (!eventHandler(e)) return;
-    await executeNavigation(router, props, navigationType);
+    if (shouldHandleNavigation(e)) {
+      await executeNavigation(router, props, navigationType);
+    }
   };
 }
 function computeAttributes(href, navigationType, isExternal, isActive, isExactActive, activeClass) {
@@ -88,13 +86,18 @@ function computeAttributes(href, navigationType, isExternal, isActive, isExactAc
   }
   return attributes;
 }
-function createEventHandlersGenerator(navigate, eventTypes) {
-  return (nameTransform) => {
+function createEventHandlersGenerator(router, props, navigationType, eventTypes) {
+  return (format) => {
     const handlers = {};
+    const navigate = createNavigateFunction(router, props, navigationType);
     eventTypes.forEach((eventType) => {
       var _a;
-      const eventName = (_a = nameTransform == null ? void 0 : nameTransform(eventType)) != null ? _a : eventType.toLowerCase();
-      handlers[eventName] = navigate;
+      const eventName = (_a = format == null ? void 0 : format(eventType)) != null ? _a : eventType.toLowerCase();
+      handlers[eventName] = (event) => {
+        var _a2;
+        (_a2 = props.beforeNavigate) == null ? void 0 : _a2.call(props, event, eventType);
+        return navigate(event);
+      };
     });
     return handlers;
   };
@@ -106,7 +109,6 @@ export function createLinkResolver(router, props) {
   const isActive = router.isRouteMatched(route, props.exact);
   const isExactActive = router.isRouteMatched(route, "exact");
   const isExternal = route.url.origin !== router.route.url.origin;
-  const navigate = createNavigateFunction(router, props, type);
   const attributes = computeAttributes(
     href,
     type,
@@ -116,7 +118,13 @@ export function createLinkResolver(router, props) {
     props.activeClass
   );
   const eventTypes = getEventTypeList(props.event || "click");
-  const getEventHandlers = createEventHandlersGenerator(navigate, eventTypes);
+  const createEventHandlers = createEventHandlersGenerator(
+    router,
+    props,
+    type,
+    eventTypes
+  );
+  const navigate = createNavigateFunction(router, props, type);
   return {
     route,
     type,
@@ -126,6 +134,6 @@ export function createLinkResolver(router, props) {
     tag: props.tag || "a",
     attributes,
     navigate,
-    getEventHandlers
+    createEventHandlers
   };
 }

package/dist/router.d.ts

@@ -103,7 +103,7 @@ export declare class Router {
      * linkData.navigate(); // Programmatic navigation
      *
      * // Get event handlers for React
-     * const handlers = linkData.getEventHandlers(name => `on${name.charAt(0).toUpperCase() + name.slice(1)}`);
+     * const handlers = linkData.createEventHandlers(name => `on${name.charAt(0).toUpperCase() + name.slice(1)}`);
      * // handlers.onClick for React
      * ```
      */

package/dist/router.mjs

@@ -200,7 +200,7 @@ export class Router {
    * linkData.navigate(); // Programmatic navigation
    *
    * // Get event handlers for React
-   * const handlers = linkData.getEventHandlers(name => `on${name.charAt(0).toUpperCase() + name.slice(1)}`);
+   * const handlers = linkData.createEventHandlers(name => `on${name.charAt(0).toUpperCase() + name.slice(1)}`);
    * // handlers.onClick for React
    * ```
    */

package/dist/scroll.d.ts

@@ -0,0 +1,33 @@
+/** Internal {@link ScrollToOptions | `ScrollToOptions`}: `left` and `top` properties always have values */
+interface _ScrollPosition extends ScrollToOptions {
+    left: number;
+    top: number;
+}
+export interface ScrollPositionElement extends ScrollToOptions {
+    /**
+     * A valid CSS selector. Some special characters need to be escaped (https://mathiasbynens.be/notes/css-escapes).
+     * @example
+     * Here are some examples:
+     *
+     * - `.title`
+     * - `.content:first-child`
+     * - `#marker`
+     * - `#marker\~with\~symbols`
+     * - `#marker.with.dot`: Selects `class="with dot" id="marker"`, not `id="marker.with.dot"`
+     *
+     */
+    el: string | Element;
+}
+/** Scroll parameters */
+export type ScrollPosition = ScrollToOptions | ScrollPositionElement;
+/** Get current window scroll position */
+export declare const winScrollPos: () => _ScrollPosition;
+/** Scroll to specified position */
+export declare function scrollToPosition(position: ScrollPosition): void;
+/** Stored scroll positions */
+export declare const scrollPositions: Map<string, _ScrollPosition>;
+/** Save scroll position */
+export declare function saveScrollPosition(key: string, scrollPosition?: _ScrollPosition): void;
+/** Get saved scroll position */
+export declare function getSavedScrollPosition(key: string, defaultValue?: _ScrollPosition | null): _ScrollPosition | null;
+export {};

package/dist/scroll.mjs

@@ -0,0 +1,49 @@
+export const winScrollPos = () => ({
+  left: window.scrollX,
+  top: window.scrollY
+});
+function getElementPosition(el, offset) {
+  const docRect = document.documentElement.getBoundingClientRect();
+  const elRect = el.getBoundingClientRect();
+  return {
+    behavior: offset.behavior,
+    left: elRect.left - docRect.left - (offset.left || 0),
+    top: elRect.top - docRect.top - (offset.top || 0)
+  };
+}
+export function scrollToPosition(position) {
+  if ("el" in position) {
+    const positionEl = position.el;
+    const el = typeof positionEl === "string" ? document.querySelector(positionEl) : positionEl;
+    if (!el) return;
+    position = getElementPosition(el, position);
+  }
+  if ("scrollBehavior" in document.documentElement.style) {
+    window.scrollTo(position);
+  } else {
+    window.scrollTo(
+      Number.isFinite(position.left) ? position.left : window.scrollX,
+      Number.isFinite(position.top) ? position.top : window.scrollY
+    );
+  }
+}
+export const scrollPositions = /* @__PURE__ */ new Map();
+const POSITION_KEY = "__scroll_position_key";
+export function saveScrollPosition(key, scrollPosition = winScrollPos()) {
+  scrollPosition = { ...scrollPosition };
+  scrollPositions.set(key, scrollPosition);
+  try {
+    if (location.href !== key) return;
+    const stateCopy = {
+      ...history.state || {},
+      [POSITION_KEY]: scrollPosition
+    };
+    history.replaceState(stateCopy, "");
+  } catch (error) {
+  }
+}
+export function getSavedScrollPosition(key, defaultValue = null) {
+  const scroll = scrollPositions.get(key) || history.state[POSITION_KEY];
+  scrollPositions.delete(key);
+  return scroll || defaultValue;
+}

package/dist/types.d.ts

@@ -43,6 +43,7 @@ export interface RouteLocation {
     queryArray?: Record<string, string[] | undefined>;
     hash?: string;
     state?: RouteState;
+    /** When `true`, maintains current scroll position after navigation (default behavior scrolls to top) */
     keepScrollPosition?: boolean;
     statusCode?: number | null;
     layer?: RouteLayerOptions | null;
@@ -194,6 +195,7 @@ export interface RouterOptions {
     apps?: RouterMicroApp;
     normalizeURL?: (to: URL, from: URL | null) => URL;
     fallback?: RouteHandleHook;
+    nextTick?: () => Awaitable<void>;
     rootStyle?: Partial<CSSStyleDeclaration> | false | null;
     layer?: boolean;
     zIndex?: number;
@@ -217,7 +219,6 @@ export interface RouterLinkAttributes {
     target?: '_blank';
     rel?: string;
 }
-export type RouterLinkEventHandler = <E extends Event = MouseEvent>(event: E) => boolean | void;
 /**
  * Framework-agnostic link configuration interface
  */
@@ -233,7 +234,15 @@ export interface RouterLinkProps {
     event?: string | string[];
     tag?: string;
     layerOptions?: RouteLayerOptions;
-    eventHandler?: RouterLinkEventHandler;
+    /**
+     * Hook function called before navigation occurs
+     * @param event - The DOM event that triggered the navigation
+     * @param eventName - The name of the event that triggered navigation
+     *
+     * Can prevent default event to block the default navigation handling logic.
+     * Call event.preventDefault() to stop the navigation from proceeding.
+     */
+    beforeNavigate?: (event: Event, eventName: string) => void;
 }
 /**
  * Framework-agnostic link resolution result
@@ -246,6 +255,6 @@ export interface RouterLinkResolved {
     isExternal: boolean;
     tag: string;
     attributes: RouterLinkAttributes;
-    navigate: (e?: Event) => Promise<void>;
-    getEventHandlers: (nameTransform?: (eventType: string) => string) => Record<string, (e: Event) => Promise<void> | undefined>;
+    navigate: (e: Event) => Promise<void>;
+    createEventHandlers: (format?: (eventType: string) => string) => Record<string, (e: Event) => Promise<void>>;
 }

package/package.json

@@ -39,7 +39,7 @@
         "unbuild": "3.6.0",
         "vitest": "3.2.4"
     },
-    "version": "3.0.0-rc.59",
+    "version": "3.0.0-rc.61",
     "type": "module",
     "private": false,
     "exports": {
@@ -58,5 +58,5 @@
         "template",
         "public"
     ],
-    "gitHead": "d221aba2a43064b5666e714f42904ae80b2b57ad"
+    "gitHead": "cce4468980071fe7a0a1e5f4941f1750cacc5215"
 }

package/src/options.ts

@@ -83,6 +83,7 @@ export function parsedOptions(
         matcher: createMatcher(routes, compiledRoutes),
         normalizeURL: options.normalizeURL ?? ((url) => url),
         fallback: options.fallback ?? fallback,
+        nextTick: options.nextTick ?? (() => {}),
         handleBackBoundary: options.handleBackBoundary ?? (() => {}),
         handleLayerClose: options.handleLayerClose ?? (() => {})
     });

package/src/route-task.ts

@@ -23,10 +23,7 @@ export class RouteTaskController {
     }
 
     shouldCancel(name: string): boolean {
-        if (this._aborted) {
-            return true;
-        }
-        return false;
+        return this._aborted;
     }
 }
 

package/src/route-transition.ts

@@ -5,6 +5,12 @@ import {
     createRouteTask
 } from './route-task';
 import type { Router } from './router';
+import {
+    getSavedScrollPosition,
+    saveScrollPosition,
+    scrollToPosition,
+    winScrollPos
+} from './scroll';
 import { RouteType } from './types';
 
 import type {
@@ -15,6 +21,7 @@ import type {
     RouteNotifyHook
 } from './types';
 import {
+    isBrowser,
     isRouteMatched,
     isUrlEqual,
     isValidConfirmHookResult,
@@ -174,6 +181,46 @@ export const ROUTE_TRANSITION_HOOKS = {
             }
         }
 
+        if (isBrowser && 'scrollRestoration' in window.history)
+            window.history.scrollRestoration = 'manual';
+        // handle scroll position
+        if (from && isBrowser && !router.isLayer)
+            switch (to.type) {
+                case RouteType.push:
+                case RouteType.replace: {
+                    if (!to.keepScrollPosition) {
+                        saveScrollPosition(from.url.href);
+                        scrollToPosition({ left: 0, top: 0 });
+                    } else {
+                        to.applyNavigationState({
+                            __keepScrollPosition: to.keepScrollPosition
+                        });
+                    }
+                    break;
+                }
+                case RouteType.go:
+                case RouteType.forward:
+                case RouteType.back:
+                // for popstate
+                case RouteType.unknown: {
+                    saveScrollPosition(from.url.href);
+                    setTimeout(async () => {
+                        const state = window.history.state;
+                        if (state?.__keepScrollPosition) {
+                            return;
+                        }
+                        const savedPosition = getSavedScrollPosition(
+                            to.url.href,
+                            { left: 0, top: 0 }
+                        );
+                        if (!savedPosition) return;
+                        await router.parsedOptions.nextTick();
+                        scrollToPosition(savedPosition);
+                    });
+                    break;
+                }
+            }
+
         switch (to.type) {
             case RouteType.push:
                 return ROUTE_TYPE_HANDLERS.push;

package/src/router-link.ts

@@ -41,29 +41,22 @@ function getEventTypeList(eventType: unknown | unknown[]): string[] {
 }
 
 /**
- * Event guard check - determines if the router should handle the navigation
+ * Navigation event handler called before navigation - determines if the router should handle the navigation
  *
- * Returns !0: Let browser handle default behavior (normal link navigation)
- * Returns 0: Router takes over navigation, prevents default browser behavior
+ * Returns false: Let browser handle default behavior (normal link navigation)
+ * Returns true: 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?: Event & Partial<MouseEvent>): true | undefined {
-    if (!e) return;
-    // don't redirect with control keys
-    if (e.metaKey || e.altKey || e.ctrlKey || e.shiftKey) return;
-    // don't redirect when preventDefault called
-    if (e.defaultPrevented) return;
-    // don't redirect on right click
-    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();
+function shouldHandleNavigation(e: Event): boolean {
+    if (e.defaultPrevented) return false;
+    if (e instanceof MouseEvent) {
+        if (e.metaKey || e.altKey || e.ctrlKey || e.shiftKey) return false;
+        if (e.button !== undefined && e.button !== 0) return false;
+    }
+
+    e.preventDefault?.();
 
     return true;
 }
@@ -112,12 +105,11 @@ function createNavigateFunction(
     router: Router,
     props: RouterLinkProps,
     navigationType: RouterLinkType
-): (e?: Event) => Promise<void> {
-    return async (e?: Event): Promise<void> => {
-        const eventHandler = props.eventHandler ?? guardEvent;
-        if (!eventHandler(e!)) return;
-
-        await executeNavigation(router, props, navigationType);
+): RouterLinkResolved['navigate'] {
+    return async (e: Event): Promise<void> => {
+        if (shouldHandleNavigation(e)) {
+            await executeNavigation(router, props, navigationType);
+        }
     };
 }
 
@@ -173,18 +165,21 @@ function computeAttributes(
  * Create event handlers generator function
  */
 function createEventHandlersGenerator(
-    navigate: (e: Event) => Promise<void>,
+    router: Router,
+    props: RouterLinkProps,
+    navigationType: RouterLinkType,
     eventTypes: string[]
-): (
-    nameTransform?: (eventType: string) => string
-) => Record<string, (e: Event) => Promise<void>> {
-    return (nameTransform?: (eventType: string) => string) => {
+): RouterLinkResolved['createEventHandlers'] {
+    return (format?: (eventType: string) => string) => {
         const handlers: Record<string, (e: Event) => Promise<void>> = {};
+        const navigate = createNavigateFunction(router, props, navigationType);
 
         eventTypes.forEach((eventType) => {
-            const eventName =
-                nameTransform?.(eventType) ?? eventType.toLowerCase();
-            handlers[eventName] = navigate;
+            const eventName = format?.(eventType) ?? eventType.toLowerCase();
+            handlers[eventName] = (event) => {
+                props.beforeNavigate?.(event, eventType);
+                return navigate(event);
+            };
         });
 
         return handlers;
@@ -210,8 +205,6 @@ export function createLinkResolver(
     const isExactActive = router.isRouteMatched(route, 'exact');
     const isExternal = route.url.origin !== router.route.url.origin;
 
-    const navigate = createNavigateFunction(router, props, type);
-
     const attributes = computeAttributes(
         href,
         type,
@@ -222,7 +215,14 @@ export function createLinkResolver(
     );
 
     const eventTypes = getEventTypeList(props.event || 'click');
-    const getEventHandlers = createEventHandlersGenerator(navigate, eventTypes);
+    const createEventHandlers = createEventHandlersGenerator(
+        router,
+        props,
+        type,
+        eventTypes
+    );
+
+    const navigate = createNavigateFunction(router, props, type);
 
     return {
         route,
@@ -233,6 +233,6 @@ export function createLinkResolver(
         tag: props.tag || 'a',
         attributes,
         navigate,
-        getEventHandlers
+        createEventHandlers
     };
 }

package/src/router.ts

@@ -225,7 +225,7 @@ export class Router {
      * linkData.navigate(); // Programmatic navigation
      *
      * // Get event handlers for React
-     * const handlers = linkData.getEventHandlers(name => `on${name.charAt(0).toUpperCase() + name.slice(1)}`);
+     * const handlers = linkData.createEventHandlers(name => `on${name.charAt(0).toUpperCase() + name.slice(1)}`);
      * // handlers.onClick for React
      * ```
      */

package/src/scroll.ts

@@ -0,0 +1,108 @@
+import { isBrowser } from './util';
+
+/** Internal {@link ScrollToOptions | `ScrollToOptions`}: `left` and `top` properties always have values */
+interface _ScrollPosition extends ScrollToOptions {
+    left: number;
+    top: number;
+}
+
+export interface ScrollPositionElement extends ScrollToOptions {
+    /**
+     * A valid CSS selector. Some special characters need to be escaped (https://mathiasbynens.be/notes/css-escapes).
+     * @example
+     * Here are some examples:
+     *
+     * - `.title`
+     * - `.content:first-child`
+     * - `#marker`
+     * - `#marker\~with\~symbols`
+     * - `#marker.with.dot`: Selects `class="with dot" id="marker"`, not `id="marker.with.dot"`
+     *
+     */
+    el: string | Element;
+}
+
+/** Scroll parameters */
+export type ScrollPosition = ScrollToOptions | ScrollPositionElement;
+
+/** Get current window scroll position */
+export const winScrollPos = (): _ScrollPosition => ({
+    left: window.scrollX,
+    top: window.scrollY
+});
+
+/** Get element position for scrolling in document */
+function getElementPosition(
+    el: Element,
+    offset: ScrollToOptions
+): _ScrollPosition {
+    const docRect = document.documentElement.getBoundingClientRect();
+    const elRect = el.getBoundingClientRect();
+
+    return {
+        behavior: offset.behavior,
+        left: elRect.left - docRect.left - (offset.left || 0),
+        top: elRect.top - docRect.top - (offset.top || 0)
+    };
+}
+
+/** Scroll to specified position */
+export function scrollToPosition(position: ScrollPosition): void {
+    if ('el' in position) {
+        const positionEl = position.el;
+
+        const el =
+            typeof positionEl === 'string'
+                ? document.querySelector(positionEl)
+                : positionEl;
+
+        if (!el) return;
+
+        position = getElementPosition(el, position);
+    }
+
+    if ('scrollBehavior' in document.documentElement.style) {
+        window.scrollTo(position);
+    } else {
+        window.scrollTo(
+            Number.isFinite(position.left) ? position.left! : window.scrollX,
+            Number.isFinite(position.top) ? position.top! : window.scrollY
+        );
+    }
+}
+
+/** Stored scroll positions */
+export const scrollPositions = new Map<string, _ScrollPosition>();
+
+const POSITION_KEY = '__scroll_position_key';
+
+/** Save scroll position */
+export function saveScrollPosition(
+    key: string,
+    scrollPosition = winScrollPos()
+) {
+    scrollPosition = { ...scrollPosition };
+    scrollPositions.set(key, scrollPosition);
+
+    try {
+        if (location.href !== key) return;
+        // preserve the existing history state as it could be overridden by the user
+        const stateCopy = {
+            ...(history.state || {}),
+            [POSITION_KEY]: scrollPosition
+        };
+        history.replaceState(stateCopy, '');
+    } catch (error) {}
+}
+
+/** Get saved scroll position */
+export function getSavedScrollPosition(
+    key: string,
+    defaultValue: _ScrollPosition | null = null
+): _ScrollPosition | null {
+    const scroll = scrollPositions.get(key) || history.state[POSITION_KEY];
+
+    // Saved scroll position should not be used multiple times, next time should use newly saved position
+    scrollPositions.delete(key);
+    return scroll || defaultValue;
+}

package/src/types.ts

@@ -91,6 +91,7 @@ export interface RouteLocation {
     queryArray?: Record<string, string[] | undefined>;
     hash?: string;
     state?: RouteState;
+    /** When `true`, maintains current scroll position after navigation (default behavior scrolls to top) */
     keepScrollPosition?: boolean;
     statusCode?: number | null;
     layer?: RouteLayerOptions | null;
@@ -266,6 +267,7 @@ export interface RouterOptions {
     apps?: RouterMicroApp;
     normalizeURL?: (to: URL, from: URL | null) => URL;
     fallback?: RouteHandleHook;
+    nextTick?: () => Awaitable<void>;
 
     rootStyle?: Partial<CSSStyleDeclaration> | false | null;
     layer?: boolean;
@@ -306,10 +308,6 @@ export interface RouterLinkAttributes {
     rel?: string;
 }
 
-export type RouterLinkEventHandler = <E extends Event = MouseEvent>(
-    event: E
-) => boolean | void;
-
 /**
  * Framework-agnostic link configuration interface
  */
@@ -325,7 +323,15 @@ export interface RouterLinkProps {
     event?: string | string[];
     tag?: string;
     layerOptions?: RouteLayerOptions;
-    eventHandler?: RouterLinkEventHandler;
+    /**
+     * Hook function called before navigation occurs
+     * @param event - The DOM event that triggered the navigation
+     * @param eventName - The name of the event that triggered navigation
+     *
+     * Can prevent default event to block the default navigation handling logic.
+     * Call event.preventDefault() to stop the navigation from proceeding.
+     */
+    beforeNavigate?: (event: Event, eventName: string) => void;
 }
 
 /**
@@ -344,10 +350,10 @@ export interface RouterLinkResolved {
     attributes: RouterLinkAttributes;
 
     // Navigation function
-    navigate: (e?: Event) => Promise<void>;
+    navigate: (e: Event) => Promise<void>;
 
     // Event handling
-    getEventHandlers: (
-        nameTransform?: (eventType: string) => string
-    ) => Record<string, (e: Event) => Promise<void> | undefined>;
+    createEventHandlers: (
+        format?: (eventType: string) => string
+    ) => Record<string, (e: Event) => Promise<void>>;
 }