@real-router/solid 0.10.0 → 0.11.0

package/README.md

@@ -372,7 +372,7 @@ Opt-in preservation of scroll position across navigations:
 </RouterProvider>
 ```
 
-Restores scroll on back/forward, scrolls to top (or `#hash`) on push. Three modes: `"restore"` (default), `"top"`, `"manual"`. Custom containers via `scrollContainer: () => HTMLElement | null`. Options are read once on mount — changing the prop at runtime does not reconfigure the utility (Solid `onMount` is non-reactive). See [Scroll Restoration guide](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration) for details.
+Restores scroll on back/forward, scrolls to top (or `#hash`) on push. Three modes: `"restore"` (default), `"top"`, `"native"`. Custom containers via `scrollContainer: () => HTMLElement | null`. Options are read once on mount — changing the prop at runtime does not reconfigure the utility (Solid `onMount` is non-reactive). See [Scroll Restoration guide](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration) for details.
 
 ## View Transitions
 

package/dist/cjs/index.d.ts

@@ -273,11 +273,32 @@ interface UseRouteEnterOptions {
  */
 declare function useRouteEnter(handler: RouteEnterHandler, options?: UseRouteEnterOptions): void;
 
-type ScrollRestorationMode = "restore" | "top" | "manual";
+type ScrollRestorationMode = "restore" | "top" | "native";
 interface ScrollRestorationOptions {
     mode?: ScrollRestorationMode | undefined;
     anchorScrolling?: boolean | undefined;
     scrollContainer?: (() => HTMLElement | null) | undefined;
+    /**
+     * Scroll behavior passed to `scrollTo({ behavior })` and
+     * `scrollIntoView({ behavior })`.
+     *
+     * - `"auto"` (default) — browser-defined, usually instant.
+     * - `"instant"` — explicit instant jump (no animation).
+     * - `"smooth"` — animated transition. Note: smooth restore on back/traverse
+     *   can feel disorienting if the user expects to land at the saved position
+     *   immediately. Recommended for `mode: "top"` or anchor scroll only.
+     *
+     * See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/ScrollToOptions/behavior).
+     */
+    behavior?: ScrollBehavior | undefined;
+    /**
+     * sessionStorage key used to persist saved scroll positions. Default:
+     * `"real-router:scroll"`. Override only when multiple independent
+     * `RouterProvider` instances share the same document and you need to
+     * isolate their scroll stores (e.g. micro-frontends, embedded widgets,
+     * or testing). For a single app with one provider the default is fine.
+     */
+    storageKey?: string | undefined;
 }
 
 interface RouteProviderProps {

package/dist/cjs/index.js

@@ -336,7 +336,7 @@ function manageFocus(h1) {
   });
 }
 
-const STORAGE_KEY = "real-router:scroll";
+const DEFAULT_STORAGE_KEY = "real-router:scroll";
 const NOOP_INSTANCE$1 = Object.freeze({
   destroy: () => {
     /* no-op */
@@ -348,14 +348,36 @@ function createScrollRestoration(router, options) {
   }
   const mode = options?.mode ?? "restore";
 
-  // mode "manual" = utility does nothing. Don't flip history.scrollRestoration,
-  // don't subscribe, don't register pagehide — leave the browser's native
-  // auto-restore intact for the app to override if it wants to.
-  if (mode === "manual") {
+  // mode "native" = utility does nothing. Don't flip history.scrollRestoration,
+  // don't subscribe, don't register pagehide — `history.scrollRestoration`
+  // stays at the browser default ("auto") so the browser handles scroll
+  // restore natively. (Note: this is the OPPOSITE of `history.scrollRestoration
+  // === "manual"` — utility's "native" leaves the DOM property at "auto" so
+  // the browser is in charge.)
+  if (mode === "native") {
     return NOOP_INSTANCE$1;
   }
   const anchorEnabled = options?.anchorScrolling ?? true;
   const getContainer = options?.scrollContainer;
+  const behavior = options?.behavior ?? "auto";
+  const storageKey = options?.storageKey ?? DEFAULT_STORAGE_KEY;
+  const loadStore = () => {
+    try {
+      const raw = sessionStorage.getItem(storageKey);
+      return raw ? JSON.parse(raw) : {};
+    } catch {
+      return {};
+    }
+  };
+  const putPos = (key, pos) => {
+    try {
+      const store = loadStore();
+      store[key] = pos;
+      sessionStorage.setItem(storageKey, JSON.stringify(store));
+    } catch {
+      // Ignore quota / security errors.
+    }
+  };
   const prevScrollRestoration = history.scrollRestoration;
   try {
     history.scrollRestoration = "manual";
@@ -373,9 +395,17 @@ function createScrollRestoration(router, options) {
   const writePos = top => {
     const element = getContainer?.();
     if (element) {
-      element.scrollTop = top;
+      element.scrollTo({
+        top,
+        left: 0,
+        behavior
+      });
     } else {
-      globalThis.scrollTo(0, top);
+      globalThis.scrollTo({
+        top,
+        left: 0,
+        behavior
+      });
     }
   };
   const scrollToHashOrTop = route => {
@@ -389,7 +419,9 @@ function createScrollRestoration(router, options) {
         // eslint-disable-next-line unicorn/prefer-query-selector -- ids may contain CSS-unsafe chars
         const element = document.getElementById(ctxHash);
         if (element) {
-          element.scrollIntoView();
+          element.scrollIntoView({
+            behavior
+          });
           return;
         }
       }
@@ -413,7 +445,9 @@ function createScrollRestoration(router, options) {
       // eslint-disable-next-line unicorn/prefer-query-selector -- ids may contain CSS-unsafe chars
       const element = document.getElementById(id);
       if (element) {
-        element.scrollIntoView();
+        element.scrollIntoView({
+          behavior
+        });
         return;
       }
     }
@@ -479,23 +513,6 @@ function createScrollRestoration(router, options) {
 function keyOf(state) {
   return `${state.name}:${canonicalJson(state.params)}`;
 }
-function loadStore() {
-  try {
-    const raw = sessionStorage.getItem(STORAGE_KEY);
-    return raw ? JSON.parse(raw) : {};
-  } catch {
-    return {};
-  }
-}
-function putPos(key, pos) {
-  try {
-    const store = loadStore();
-    store[key] = pos;
-    sessionStorage.setItem(STORAGE_KEY, JSON.stringify(store));
-  } catch {
-    // Ignore quota / security errors.
-  }
-}
 function canonicalJson(value) {
   return JSON.stringify(value, canonicalReplacer);
 }

package/dist/esm/index.d.mts

@@ -273,11 +273,32 @@ interface UseRouteEnterOptions {
  */
 declare function useRouteEnter(handler: RouteEnterHandler, options?: UseRouteEnterOptions): void;
 
-type ScrollRestorationMode = "restore" | "top" | "manual";
+type ScrollRestorationMode = "restore" | "top" | "native";
 interface ScrollRestorationOptions {
     mode?: ScrollRestorationMode | undefined;
     anchorScrolling?: boolean | undefined;
     scrollContainer?: (() => HTMLElement | null) | undefined;
+    /**
+     * Scroll behavior passed to `scrollTo({ behavior })` and
+     * `scrollIntoView({ behavior })`.
+     *
+     * - `"auto"` (default) — browser-defined, usually instant.
+     * - `"instant"` — explicit instant jump (no animation).
+     * - `"smooth"` — animated transition. Note: smooth restore on back/traverse
+     *   can feel disorienting if the user expects to land at the saved position
+     *   immediately. Recommended for `mode: "top"` or anchor scroll only.
+     *
+     * See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/ScrollToOptions/behavior).
+     */
+    behavior?: ScrollBehavior | undefined;
+    /**
+     * sessionStorage key used to persist saved scroll positions. Default:
+     * `"real-router:scroll"`. Override only when multiple independent
+     * `RouterProvider` instances share the same document and you need to
+     * isolate their scroll stores (e.g. micro-frontends, embedded widgets,
+     * or testing). For a single app with one provider the default is fine.
+     */
+    storageKey?: string | undefined;
 }
 
 interface RouteProviderProps {

package/dist/esm/index.mjs

@@ -334,7 +334,7 @@ function manageFocus(h1) {
   });
 }
 
-const STORAGE_KEY = "real-router:scroll";
+const DEFAULT_STORAGE_KEY = "real-router:scroll";
 const NOOP_INSTANCE$1 = Object.freeze({
   destroy: () => {
     /* no-op */
@@ -346,14 +346,36 @@ function createScrollRestoration(router, options) {
   }
   const mode = options?.mode ?? "restore";
 
-  // mode "manual" = utility does nothing. Don't flip history.scrollRestoration,
-  // don't subscribe, don't register pagehide — leave the browser's native
-  // auto-restore intact for the app to override if it wants to.
-  if (mode === "manual") {
+  // mode "native" = utility does nothing. Don't flip history.scrollRestoration,
+  // don't subscribe, don't register pagehide — `history.scrollRestoration`
+  // stays at the browser default ("auto") so the browser handles scroll
+  // restore natively. (Note: this is the OPPOSITE of `history.scrollRestoration
+  // === "manual"` — utility's "native" leaves the DOM property at "auto" so
+  // the browser is in charge.)
+  if (mode === "native") {
     return NOOP_INSTANCE$1;
   }
   const anchorEnabled = options?.anchorScrolling ?? true;
   const getContainer = options?.scrollContainer;
+  const behavior = options?.behavior ?? "auto";
+  const storageKey = options?.storageKey ?? DEFAULT_STORAGE_KEY;
+  const loadStore = () => {
+    try {
+      const raw = sessionStorage.getItem(storageKey);
+      return raw ? JSON.parse(raw) : {};
+    } catch {
+      return {};
+    }
+  };
+  const putPos = (key, pos) => {
+    try {
+      const store = loadStore();
+      store[key] = pos;
+      sessionStorage.setItem(storageKey, JSON.stringify(store));
+    } catch {
+      // Ignore quota / security errors.
+    }
+  };
   const prevScrollRestoration = history.scrollRestoration;
   try {
     history.scrollRestoration = "manual";
@@ -371,9 +393,17 @@ function createScrollRestoration(router, options) {
   const writePos = top => {
     const element = getContainer?.();
     if (element) {
-      element.scrollTop = top;
+      element.scrollTo({
+        top,
+        left: 0,
+        behavior
+      });
     } else {
-      globalThis.scrollTo(0, top);
+      globalThis.scrollTo({
+        top,
+        left: 0,
+        behavior
+      });
     }
   };
   const scrollToHashOrTop = route => {
@@ -387,7 +417,9 @@ function createScrollRestoration(router, options) {
         // eslint-disable-next-line unicorn/prefer-query-selector -- ids may contain CSS-unsafe chars
         const element = document.getElementById(ctxHash);
         if (element) {
-          element.scrollIntoView();
+          element.scrollIntoView({
+            behavior
+          });
           return;
         }
       }
@@ -411,7 +443,9 @@ function createScrollRestoration(router, options) {
       // eslint-disable-next-line unicorn/prefer-query-selector -- ids may contain CSS-unsafe chars
       const element = document.getElementById(id);
       if (element) {
-        element.scrollIntoView();
+        element.scrollIntoView({
+          behavior
+        });
         return;
       }
     }
@@ -477,23 +511,6 @@ function createScrollRestoration(router, options) {
 function keyOf(state) {
   return `${state.name}:${canonicalJson(state.params)}`;
 }
-function loadStore() {
-  try {
-    const raw = sessionStorage.getItem(STORAGE_KEY);
-    return raw ? JSON.parse(raw) : {};
-  } catch {
-    return {};
-  }
-}
-function putPos(key, pos) {
-  try {
-    const store = loadStore();
-    store[key] = pos;
-    sessionStorage.setItem(STORAGE_KEY, JSON.stringify(store));
-  } catch {
-    // Ignore quota / security errors.
-  }
-}
 function canonicalJson(value) {
   return JSON.stringify(value, canonicalReplacer);
 }

package/dist/types/dom-utils/scroll-restore.d.ts

@@ -1,9 +1,30 @@
 import type { Router } from "@real-router/core";
-export type ScrollRestorationMode = "restore" | "top" | "manual";
+export type ScrollRestorationMode = "restore" | "top" | "native";
 export interface ScrollRestorationOptions {
     mode?: ScrollRestorationMode | undefined;
     anchorScrolling?: boolean | undefined;
     scrollContainer?: (() => HTMLElement | null) | undefined;
+    /**
+     * Scroll behavior passed to `scrollTo({ behavior })` and
+     * `scrollIntoView({ behavior })`.
+     *
+     * - `"auto"` (default) — browser-defined, usually instant.
+     * - `"instant"` — explicit instant jump (no animation).
+     * - `"smooth"` — animated transition. Note: smooth restore on back/traverse
+     *   can feel disorienting if the user expects to land at the saved position
+     *   immediately. Recommended for `mode: "top"` or anchor scroll only.
+     *
+     * See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/ScrollToOptions/behavior).
+     */
+    behavior?: ScrollBehavior | undefined;
+    /**
+     * sessionStorage key used to persist saved scroll positions. Default:
+     * `"real-router:scroll"`. Override only when multiple independent
+     * `RouterProvider` instances share the same document and you need to
+     * isolate their scroll stores (e.g. micro-frontends, embedded widgets,
+     * or testing). For a single app with one provider the default is fine.
+     */
+    storageKey?: string | undefined;
 }
 export declare function createScrollRestoration(router: Router, options?: ScrollRestorationOptions): {
     destroy: () => void;

package/dist/types/dom-utils/scroll-restore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scroll-restore.d.ts","sourceRoot":"","sources":["../../../src/dom-utils/scroll-restore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAS,MAAM,mBAAmB,CAAC;AAUvD,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEjE,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;IACzC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,eAAe,CAAC,EAAE,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,SAAS,CAAC;CAC1D;AAOD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,wBAAwB,GACjC;IAAE,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAwKzB"}
+{"version":3,"file":"scroll-restore.d.ts","sourceRoot":"","sources":["../../../src/dom-utils/scroll-restore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAS,MAAM,mBAAmB,CAAC;AAUvD,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEjE,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;IACzC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,eAAe,CAAC,EAAE,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,SAAS,CAAC;IACzD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;IACtC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAOD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,wBAAwB,GACjC;IAAE,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAkMzB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/solid",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "commonjs",
   "description": "Solid.js integration for Real-Router",
   "main": "./dist/cjs/index.js",