@real-router/svelte 0.4.1 → 0.5.0

package/README.md

@@ -363,11 +363,23 @@ Enable screen reader announcements for route changes:
 
 When enabled, a visually hidden `aria-live` region announces each navigation. Focus moves to the first `<h1>` on the new page. See [Accessibility guide](https://github.com/greydragon888/real-router/wiki/Accessibility) for details.
 
+## Scroll Restoration
+
+Opt-in preservation of scroll position across navigations:
+
+```svelte
+<RouterProvider {router} scrollRestoration={{ mode: "restore" }}>
+  <!-- Your app -->
+</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.
+
 ## Documentation
 
 Full documentation: [Wiki](https://github.com/greydragon888/real-router/wiki)
 
-- [RouterProvider](https://github.com/greydragon888/real-router/wiki/RouterProvider) · [RouteView](https://github.com/greydragon888/real-router/wiki/RouteView) · [RouterErrorBoundary](https://github.com/greydragon888/real-router/wiki/RouterErrorBoundary) · [Link](https://github.com/greydragon888/real-router/wiki/Link)
+- [RouterProvider](https://github.com/greydragon888/real-router/wiki/RouterProvider) · [RouteView](https://github.com/greydragon888/real-router/wiki/RouteView) · [RouterErrorBoundary](https://github.com/greydragon888/real-router/wiki/RouterErrorBoundary) · [Link](https://github.com/greydragon888/real-router/wiki/Link) · [Scroll Restoration](https://github.com/greydragon888/real-router/wiki/Scroll-Restoration)
 - [useRouter](https://github.com/greydragon888/real-router/wiki/useRouter) · [useRoute](https://github.com/greydragon888/real-router/wiki/useRoute) · [useRouteNode](https://github.com/greydragon888/real-router/wiki/useRouteNode) · [useNavigator](https://github.com/greydragon888/real-router/wiki/useNavigator) · [useRouteUtils](https://github.com/greydragon888/real-router/wiki/useRouteUtils) · [useRouterTransition](https://github.com/greydragon888/real-router/wiki/useRouterTransition)
 
 ## Examples

package/dist/RouterProvider.svelte

@@ -1,13 +1,17 @@
 <script lang="ts">
   import { getNavigator } from "@real-router/core";
   import { createRouteSource } from "@real-router/sources";
-  import { createRouteAnnouncer } from "./dom-utils/index.js";
-  import { setContext } from "svelte";
+  import {
+    createRouteAnnouncer,
+    createScrollRestoration,
+  } from "./dom-utils";
+  import { setContext, untrack } from "svelte";
 
   import { createReactiveSource } from "./createReactiveSource.svelte";
   import { createRouteContext } from "./createRouteContext.svelte";
   import { NAVIGATOR_KEY, ROUTE_KEY, ROUTER_KEY } from "./context";
 
+  import type { ScrollRestorationOptions } from "./dom-utils";
   import type { Router } from "@real-router/core";
   import type { Snippet } from "svelte";
 
@@ -15,8 +19,13 @@
     router,
     children,
     announceNavigation,
-  }: { router: Router; children: Snippet; announceNavigation?: boolean } =
-    $props();
+    scrollRestoration,
+  }: {
+    router: Router;
+    children: Snippet;
+    announceNavigation?: boolean;
+    scrollRestoration?: ScrollRestorationOptions;
+  } = $props();
 
   $effect(() => {
     if (!announceNavigation) return;
@@ -24,6 +33,27 @@
     return () => announcer.destroy();
   });
 
+  // $derived memoizes by === so inline `{ mode: "restore" }` doesn't thrash:
+  // each parent re-render produces a new object ref, but .mode stays "restore"
+  // → $derived returns the same primitive → $effect doesn't re-run.
+  const srEnabled = $derived(scrollRestoration !== undefined);
+  const srMode = $derived(scrollRestoration?.mode);
+  const srAnchor = $derived(scrollRestoration?.anchorScrolling);
+
+  $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.
+    const sr = createScrollRestoration(router, {
+      mode: srMode,
+      anchorScrolling: srAnchor,
+      scrollContainer: untrack(() => scrollRestoration?.scrollContainer),
+    });
+    return () => sr.destroy();
+  });
+
   const navigator = getNavigator(router);
   const source = createRouteSource(router);
   const reactive = createReactiveSource(source);

package/dist/RouterProvider.svelte.d.ts

@@ -1,9 +1,11 @@
+import type { ScrollRestorationOptions } from "./dom-utils";
 import type { Router } from "@real-router/core";
 import type { Snippet } from "svelte";
 type $$ComponentProps = {
     router: Router;
     children: Snippet;
     announceNavigation?: boolean;
+    scrollRestoration?: ScrollRestorationOptions;
 };
 declare const RouterProvider: import("svelte").Component<$$ComponentProps, {}, "">;
 type RouterProvider = ReturnType<typeof RouterProvider>;

package/dist/actions/link.svelte.js

@@ -1,6 +1,6 @@
 import { ROUTER_KEY, getContextOrThrow } from "../context";
 import { EMPTY_OPTIONS, EMPTY_PARAMS, NOOP } from "../constants";
-import { shouldNavigate, applyLinkA11y } from "../dom-utils/index.js";
+import { shouldNavigate, applyLinkA11y } from "../dom-utils";
 /**
  * Factory function that captures router context during component initialization.
  * Must be called during component init (not inside event handlers or effects).

package/dist/components/Link.svelte

@@ -6,7 +6,7 @@
     shouldNavigate,
     buildHref,
     buildActiveClassName,
-  } from "../dom-utils/index.js";
+  } from "../dom-utils";
 
   import type { NavigationOptions, Params } from "@real-router/core";
   import type { Snippet } from "svelte";

package/dist/dom-utils/index.d.ts

@@ -1,3 +1,5 @@
 export { createRouteAnnouncer } from "./route-announcer.js";
+export { createScrollRestoration } from "./scroll-restore.js";
 export { shouldNavigate, buildHref, buildActiveClassName, shallowEqual, applyLinkA11y, } from "./link-utils.js";
 export type { RouteAnnouncerOptions } from "./route-announcer.js";
+export type { ScrollRestorationOptions, ScrollRestorationMode, } from "./scroll-restore.js";

package/dist/dom-utils/index.js

@@ -1,2 +1,3 @@
 export { createRouteAnnouncer } from "./route-announcer.js";
+export { createScrollRestoration } from "./scroll-restore.js";
 export { shouldNavigate, buildHref, buildActiveClassName, shallowEqual, applyLinkA11y, } from "./link-utils.js";

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

@@ -0,0 +1,10 @@
+import type { Router } from "@real-router/core";
+export type ScrollRestorationMode = "restore" | "top" | "manual";
+export interface ScrollRestorationOptions {
+    mode?: ScrollRestorationMode | undefined;
+    anchorScrolling?: boolean | undefined;
+    scrollContainer?: (() => HTMLElement | null) | undefined;
+}
+export declare function createScrollRestoration(router: Router, options?: ScrollRestorationOptions): {
+    destroy: () => void;
+};

package/dist/dom-utils/scroll-restore.js

@@ -0,0 +1,157 @@
+const STORAGE_KEY = "real-router:scroll";
+const NOOP_INSTANCE = Object.freeze({
+    destroy: () => {
+        /* no-op */
+    },
+});
+export function createScrollRestoration(router, options) {
+    if (typeof globalThis.window === "undefined") {
+        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") {
+        return NOOP_INSTANCE;
+    }
+    const anchorEnabled = options?.anchorScrolling ?? true;
+    const getContainer = options?.scrollContainer;
+    const prevScrollRestoration = history.scrollRestoration;
+    try {
+        history.scrollRestoration = "manual";
+    }
+    catch {
+        // Ignore — some embedded contexts may reject the assignment.
+    }
+    // Resolve the container lazily on every event so containers mounted AFTER
+    // the provider still get correct scroll handling. Falls back to window when
+    // the getter is absent or returns null (pre-mount).
+    const readPos = () => {
+        const element = getContainer?.();
+        return element ? element.scrollTop : globalThis.scrollY;
+    };
+    const writePos = (top) => {
+        const element = getContainer?.();
+        if (element) {
+            element.scrollTop = top;
+        }
+        else {
+            globalThis.scrollTo(0, top);
+        }
+    };
+    const scrollToHashOrTop = () => {
+        const hash = globalThis.location.hash;
+        if (anchorEnabled && hash.length > 1) {
+            // location.hash is percent-encoded; ids in the DOM are the raw string.
+            // Decode for the match. Fall back to the raw slice if the hash contains
+            // a malformed escape sequence (decodeURIComponent throws on those).
+            let id;
+            try {
+                id = decodeURIComponent(hash.slice(1));
+            }
+            catch {
+                id = hash.slice(1);
+            }
+            // eslint-disable-next-line unicorn/prefer-query-selector -- ids may contain CSS-unsafe chars
+            const element = document.getElementById(id);
+            if (element) {
+                element.scrollIntoView();
+                return;
+            }
+        }
+        writePos(0);
+    };
+    let destroyed = false;
+    const unsubscribe = router.subscribe(({ route, previousRoute }) => {
+        const nav = route.context
+            .navigation;
+        // Browsers dispatch reload as the initial navigation after refresh, so
+        // previousRoute is undefined and capture is naturally skipped. The
+        // pre-refresh position was already persisted via pagehide.
+        if (previousRoute) {
+            putPos(keyOf(previousRoute), readPos());
+        }
+        // Single rAF so DOM is committed before we read anchors / write scroll.
+        // Guard against destroy() racing with the callback.
+        requestAnimationFrame(() => {
+            if (destroyed) {
+                return;
+            }
+            if (mode === "top" || !nav) {
+                scrollToHashOrTop();
+                return;
+            }
+            if (nav.navigationType === "replace") {
+                return;
+            }
+            if (nav.direction === "back" ||
+                nav.navigationType === "traverse" ||
+                nav.navigationType === "reload") {
+                writePos(loadStore()[keyOf(route)] ?? 0);
+                return;
+            }
+            scrollToHashOrTop();
+        });
+    });
+    const onPageHide = () => {
+        const current = router.getState();
+        if (current) {
+            putPos(keyOf(current), readPos());
+        }
+    };
+    globalThis.addEventListener("pagehide", onPageHide);
+    return {
+        destroy: () => {
+            if (destroyed) {
+                return;
+            }
+            destroyed = true;
+            unsubscribe();
+            globalThis.removeEventListener("pagehide", onPageHide);
+            try {
+                history.scrollRestoration = prevScrollRestoration;
+            }
+            catch {
+                // Ignore.
+            }
+        },
+    };
+}
+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);
+}
+function canonicalReplacer(_key, val) {
+    if (val !== null && typeof val === "object" && !Array.isArray(val)) {
+        const sorted = {};
+        // eslint-disable-next-line unicorn/no-array-sort -- ng-packagr uses pre-ES2023 lib; toSorted unavailable
+        const keys = Object.keys(val).sort((left, right) => left.localeCompare(right));
+        for (const key of keys) {
+            sorted[key] = val[key];
+        }
+        return sorted;
+    }
+    return val;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/svelte",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "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.49.0",
+    "@real-router/core": "^0.50.0",
     "@real-router/route-utils": "^0.2.1",
-    "@real-router/sources": "^0.7.1"
+    "@real-router/sources": "^0.7.2"
   },
   "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.13.1"
+    "@real-router/browser-plugin": "^0.14.0"
   },
   "peerDependencies": {
     "svelte": ">=5.7.0"

package/src/RouterProvider.svelte

@@ -1,13 +1,17 @@
 <script lang="ts">
   import { getNavigator } from "@real-router/core";
   import { createRouteSource } from "@real-router/sources";
-  import { createRouteAnnouncer } from "./dom-utils/index.js";
-  import { setContext } from "svelte";
+  import {
+    createRouteAnnouncer,
+    createScrollRestoration,
+  } from "./dom-utils";
+  import { setContext, untrack } from "svelte";
 
   import { createReactiveSource } from "./createReactiveSource.svelte";
   import { createRouteContext } from "./createRouteContext.svelte";
   import { NAVIGATOR_KEY, ROUTE_KEY, ROUTER_KEY } from "./context";
 
+  import type { ScrollRestorationOptions } from "./dom-utils";
   import type { Router } from "@real-router/core";
   import type { Snippet } from "svelte";
 
@@ -15,8 +19,13 @@
     router,
     children,
     announceNavigation,
-  }: { router: Router; children: Snippet; announceNavigation?: boolean } =
-    $props();
+    scrollRestoration,
+  }: {
+    router: Router;
+    children: Snippet;
+    announceNavigation?: boolean;
+    scrollRestoration?: ScrollRestorationOptions;
+  } = $props();
 
   $effect(() => {
     if (!announceNavigation) return;
@@ -24,6 +33,27 @@
     return () => announcer.destroy();
   });
 
+  // $derived memoizes by === so inline `{ mode: "restore" }` doesn't thrash:
+  // each parent re-render produces a new object ref, but .mode stays "restore"
+  // → $derived returns the same primitive → $effect doesn't re-run.
+  const srEnabled = $derived(scrollRestoration !== undefined);
+  const srMode = $derived(scrollRestoration?.mode);
+  const srAnchor = $derived(scrollRestoration?.anchorScrolling);
+
+  $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.
+    const sr = createScrollRestoration(router, {
+      mode: srMode,
+      anchorScrolling: srAnchor,
+      scrollContainer: untrack(() => scrollRestoration?.scrollContainer),
+    });
+    return () => sr.destroy();
+  });
+
   const navigator = getNavigator(router);
   const source = createRouteSource(router);
   const reactive = createReactiveSource(source);

package/src/actions/link.svelte.ts

@@ -2,7 +2,7 @@ import type { ActionReturn } from "svelte/action";
 import type { Router, Params, NavigationOptions } from "@real-router/core";
 import { ROUTER_KEY, getContextOrThrow } from "../context";
 import { EMPTY_OPTIONS, EMPTY_PARAMS, NOOP } from "../constants";
-import { shouldNavigate, applyLinkA11y } from "../dom-utils/index.js";
+import { shouldNavigate, applyLinkA11y } from "../dom-utils";
 
 export interface LinkActionParams {
   name: string;

package/src/components/Link.svelte

@@ -6,7 +6,7 @@
     shouldNavigate,
     buildHref,
     buildActiveClassName,
-  } from "../dom-utils/index.js";
+  } from "../dom-utils";
 
   import type { NavigationOptions, Params } from "@real-router/core";
   import type { Snippet } from "svelte";