@real-router/svelte 0.9.0 → 0.10.1

package/README.md

@@ -425,7 +425,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`. Lifecycle tied to the provider — created on mount, destroyed on unmount. 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`. Lifecycle tied to the provider — created on mount, destroyed on unmount. See [Scroll Restoration guide](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration) for details.
 
 ## View Transitions
 

package/dist/RouterProvider.svelte

@@ -42,16 +42,23 @@
   const srEnabled = $derived(scrollRestoration !== undefined);
   const srMode = $derived(scrollRestoration?.mode);
   const srAnchor = $derived(scrollRestoration?.anchorScrolling);
+  const srBehavior = $derived(scrollRestoration?.behavior);
+  const srStorageKey = $derived(scrollRestoration?.storageKey);
 
   $effect(() => {
     if (!srEnabled) return;
-    // scrollContainer is a function ref that naturally changes each render.
-    // Read it via `untrack` so this $effect does NOT depend on the parent
-    // `scrollRestoration` signal. Without this, a new inline options object
-    // would re-run the effect regardless of the primitive $derived memos.
+    // Read scrollRestoration object props via `untrack` for non-primitive
+    // refs that naturally change each render. Primitive $derived memos
+    // (mode/anchor/behavior/storageKey) drive re-runs.
+    void srMode;
+    void srAnchor;
+    void srBehavior;
+    void srStorageKey;
     const sr = createScrollRestoration(router, {
       mode: srMode,
       anchorScrolling: srAnchor,
+      behavior: srBehavior,
+      storageKey: srStorageKey,
       scrollContainer: untrack(() => scrollRestoration?.scrollContainer),
     });
     return () => sr.destroy();

package/dist/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/dom-utils/scroll-restore.js

@@ -1,4 +1,4 @@
-const STORAGE_KEY = "real-router:scroll";
+const DEFAULT_STORAGE_KEY = "real-router:scroll";
 const NOOP_INSTANCE = Object.freeze({
     destroy: () => {
         /* no-op */
@@ -9,14 +9,38 @@ export function createScrollRestoration(router, options) {
         return NOOP_INSTANCE;
     }
     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;
     }
     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";
@@ -34,10 +58,10 @@ export 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) => {
@@ -52,7 +76,7 @@ export 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;
                 }
             }
@@ -75,7 +99,7 @@ export 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;
             }
         }
@@ -140,25 +164,6 @@ export 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/svelte",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "type": "module",
   "description": "Svelte 5 integration for Real-Router",
   "svelte": "./dist/index.js",
@@ -44,9 +44,9 @@
   "license": "MIT",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.51.0",
+    "@real-router/core": "^0.52.0",
     "@real-router/route-utils": "^0.2.2",
-    "@real-router/sources": "^0.8.0"
+    "@real-router/sources": "^0.8.1"
   },
   "devDependencies": {
     "@sveltejs/package": "2.5.7",
@@ -58,7 +58,7 @@
     "svelte": "5.54.0",
     "svelte-check": "4.4.5",
     "svelte-eslint-parser": "1.6.0",
-    "@real-router/browser-plugin": "^0.17.0"
+    "@real-router/browser-plugin": "^0.17.1"
   },
   "peerDependencies": {
     "svelte": ">=5.7.0"

package/src/RouterProvider.svelte

@@ -42,16 +42,23 @@
   const srEnabled = $derived(scrollRestoration !== undefined);
   const srMode = $derived(scrollRestoration?.mode);
   const srAnchor = $derived(scrollRestoration?.anchorScrolling);
+  const srBehavior = $derived(scrollRestoration?.behavior);
+  const srStorageKey = $derived(scrollRestoration?.storageKey);
 
   $effect(() => {
     if (!srEnabled) return;
-    // scrollContainer is a function ref that naturally changes each render.
-    // Read it via `untrack` so this $effect does NOT depend on the parent
-    // `scrollRestoration` signal. Without this, a new inline options object
-    // would re-run the effect regardless of the primitive $derived memos.
+    // Read scrollRestoration object props via `untrack` for non-primitive
+    // refs that naturally change each render. Primitive $derived memos
+    // (mode/anchor/behavior/storageKey) drive re-runs.
+    void srMode;
+    void srAnchor;
+    void srBehavior;
+    void srStorageKey;
     const sr = createScrollRestoration(router, {
       mode: srMode,
       anchorScrolling: srAnchor,
+      behavior: srBehavior,
+      storageKey: srStorageKey,
       scrollContainer: untrack(() => scrollRestoration?.scrollContainer),
     });
     return () => sr.destroy();