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

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/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;

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.60",
     "type": "module",
     "private": false,
     "exports": {
@@ -58,5 +58,5 @@
         "template",
         "public"
     ],
-    "gitHead": "d221aba2a43064b5666e714f42904ae80b2b57ad"
+    "gitHead": "615e91c617e0a58796c591643c6a2e1d2a1f0a76"
 }

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/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;