@solidjs/router 0.16.2 → 0.16.3

package/dist/index.js

@@ -1,5 +1,5 @@
 import { isServer, getRequestEvent, createComponent as createComponent$1, memo, delegateEvents, spread, mergeProps as mergeProps$1, template } from 'solid-js/web';
-import { getOwner, runWithOwner, createMemo, createContext, onCleanup, useContext, untrack, createSignal, createRenderEffect, on, startTransition, resetErrorBoundaries, batch, createComponent, children, mergeProps, Show, createRoot, sharedConfig, getListener, $TRACK, splitProps, createResource, catchError } from 'solid-js';
+import { getOwner, runWithOwner, createMemo, createContext, onCleanup, useContext, untrack, createSignal, createRenderEffect, on, startTransition, resetErrorBoundaries, batch, createComponent, children, mergeProps, Show, createRoot, sharedConfig, getListener, $TRACK, createEffect, splitProps, createResource, catchError } from 'solid-js';
 import { createStore, reconcile, unwrap } from 'solid-js/store';
 
 function createBeforeLeave() {
@@ -1550,8 +1550,105 @@ function setupNativeEvents({
   };
 }
 
+const STORAGE_KEY = "solid-router:scroll";
+
+/**
+ * Explicit scroll restoration for back/forward navigation. The browser's
+ * native same-document heuristic is unreliable for suspense-driven rendering:
+ * if the destination route forces a layout while the document is still short,
+ * the saved offset for the previous entry is clamped and lost (#577).
+ *
+ * Positions are captured continuously from the scroll event, keyed by the
+ * `_depth` the router already stamps on every history entry — capturing at
+ * scroll time (rather than at exit) stays correct through `useBeforeLeave`
+ * blocked/reverted traversals. The map persists to sessionStorage on pagehide
+ * so restoration survives reloads, which `scrollRestoration = "manual"`
+ * otherwise disables. Restoration runs once routing settles; if the document
+ * is still shorter than the target (a boundary below the fold hasn't
+ * resolved), a ResizeObserver retries as content grows, cancelled by the
+ * first user scroll.
+ */
+function createScrollRestoration() {
+  window.history.scrollRestoration = "manual";
+  // the current entry needs its depth stamp for captures to have a key, even
+  // if something replaced history.state after the lifecycle module loaded
+  saveCurrentDepth();
+  let positions = {};
+  try {
+    positions = JSON.parse(sessionStorage.getItem(STORAGE_KEY)) || {};
+  } catch {}
+  const depth = () => window.history.state && window.history.state._depth;
+  let programmatic = false;
+  let pending;
+  let disconnect;
+  const cancelGuard = () => {
+    disconnect && disconnect();
+    disconnect = undefined;
+  };
+  const unbind = [bindEvent(window, "scroll", () => {
+    const d = depth();
+    if (d != null) positions[d] = window.scrollY;
+    if (!programmatic) {
+      // the user took over — a pending or chasing restore would yank them
+      pending = undefined;
+      cancelGuard();
+    }
+  }), bindEvent(window, "pagehide", () => {
+    try {
+      sessionStorage.setItem(STORAGE_KEY, JSON.stringify(positions));
+    } catch {}
+  })];
+  const restore = () => {
+    if (pending == null) return;
+    const y = positions[pending];
+    pending = undefined;
+    if (y == null) return;
+    cancelGuard();
+    const attempt = () => {
+      programmatic = true;
+      window.scrollTo(0, y);
+      programmatic = false;
+      // reachable once the document is tall enough to hold the offset
+      return document.documentElement.scrollHeight - window.innerHeight >= y;
+    };
+    if (!attempt() && typeof ResizeObserver !== "undefined") {
+      const observer = new ResizeObserver(() => attempt() && cancelGuard());
+      observer.observe(document.documentElement);
+      disconnect = () => observer.disconnect();
+    }
+  };
+  return {
+    /** Before the router reacts to a popstate: mark the traversal target. */
+    onPop() {
+      pending = depth();
+    },
+    /** After a push: forward entries died, and this depth may be reused. */
+    onPush() {
+      const d = depth();
+      if (d != null) for (const k in positions) +k >= d && delete positions[k];
+    },
+    create(router) {
+      createEffect(on(router.isRouting, routing => routing || restore(), {
+        defer: true
+      }));
+      onCleanup(() => {
+        unbind.forEach(u => u());
+        cancelGuard();
+      });
+      // reload/back_forward document loads land on an existing entry; a fresh
+      // navigation starts a new one and belongs at the top
+      const [nav] = performance.getEntriesByType && performance.getEntriesByType("navigation");
+      if (nav && nav.type !== "navigate") {
+        pending = depth();
+        restore();
+      }
+    }
+  };
+}
+
 function Router(props) {
   if (isServer) return StaticRouter(props);
+  const restoration = props.scrollRestoration ? createScrollRestoration() : undefined;
   const getSource = () => {
     const url = window.location.pathname + window.location.search;
     const state = window.history.state && window.history.state._depth && Object.keys(window.history.state).length === 1 ? undefined : window.history.state;
@@ -1576,23 +1673,33 @@ function Router(props) {
       }
       scrollToHash(decodeURIComponent(window.location.hash.slice(1)), scroll);
       saveCurrentDepth();
+      restoration && !replace && restoration.onPush();
+    },
+    init: notify => {
+      const handler = notifyIfNotBlocked(notify, delta => {
+        if (delta) {
+          return !beforeLeave.confirm(delta);
+        } else {
+          const s = getSource();
+          return !beforeLeave.confirm(s.value, {
+            state: s.state
+          });
+        }
+      });
+      return bindEvent(window, "popstate", restoration ? () => {
+        restoration.onPop();
+        handler();
+      } : handler);
+    },
+    create: router => {
+      setupNativeEvents({
+        preload: props.preload,
+        explicitLinks: props.explicitLinks,
+        actionBase: props.actionBase,
+        transformUrl: props.transformUrl
+      })(router);
+      restoration && restoration.create(router);
     },
-    init: notify => bindEvent(window, "popstate", notifyIfNotBlocked(notify, delta => {
-      if (delta) {
-        return !beforeLeave.confirm(delta);
-      } else {
-        const s = getSource();
-        return !beforeLeave.confirm(s.value, {
-          state: s.state
-        });
-      }
-    })),
-    create: setupNativeEvents({
-      preload: props.preload,
-      explicitLinks: props.explicitLinks,
-      actionBase: props.actionBase,
-      transformUrl: props.transformUrl
-    }),
     utils: {
       go: delta => window.history.go(delta),
       beforeLeave

package/dist/routers/Router.d.ts

@@ -5,5 +5,13 @@ export type RouterProps = BaseRouterProps & {
     actionBase?: string;
     explicitLinks?: boolean;
     preload?: boolean;
+    /**
+     * Opt-in explicit scroll restoration for back/forward navigation (read
+     * once, not reactive). Sets `history.scrollRestoration = "manual"` and
+     * restores saved positions after the navigation settles, replacing the
+     * browser heuristic that loses offsets when the destination route forces
+     * a layout while rendering (#577).
+     */
+    scrollRestoration?: boolean;
 };
 export declare function Router(props: RouterProps): JSX.Element;

package/dist/routers/Router.js

@@ -3,9 +3,11 @@ import { createRouter, scrollToHash, bindEvent } from "./createRouter.js";
 import { StaticRouter } from "./StaticRouter.js";
 import { setupNativeEvents } from "../data/events.js";
 import { createBeforeLeave, keepDepth, notifyIfNotBlocked, saveCurrentDepth } from "../lifecycle.js";
+import { createScrollRestoration } from "./scrollRestoration.js";
 export function Router(props) {
     if (isServer)
         return StaticRouter(props);
+    const restoration = props.scrollRestoration ? createScrollRestoration() : undefined;
     const getSource = () => {
         const url = window.location.pathname + window.location.search;
         const state = window.history.state && window.history.state._depth && Object.keys(window.history.state).length === 1 ? undefined : window.history.state;
@@ -26,17 +28,29 @@ export function Router(props) {
             }
             scrollToHash(decodeURIComponent(window.location.hash.slice(1)), scroll);
             saveCurrentDepth();
+            restoration && !replace && restoration.onPush();
+        },
+        init: notify => {
+            const handler = notifyIfNotBlocked(notify, delta => {
+                if (delta) {
+                    return !beforeLeave.confirm(delta);
+                }
+                else {
+                    const s = getSource();
+                    return !beforeLeave.confirm(s.value, { state: s.state });
+                }
+            });
+            return bindEvent(window, "popstate", restoration
+                ? () => {
+                    restoration.onPop();
+                    handler();
+                }
+                : handler);
+        },
+        create: router => {
+            setupNativeEvents({ preload: props.preload, explicitLinks: props.explicitLinks, actionBase: props.actionBase, transformUrl: props.transformUrl })(router);
+            restoration && restoration.create(router);
         },
-        init: notify => bindEvent(window, "popstate", notifyIfNotBlocked(notify, delta => {
-            if (delta) {
-                return !beforeLeave.confirm(delta);
-            }
-            else {
-                const s = getSource();
-                return !beforeLeave.confirm(s.value, { state: s.state });
-            }
-        })),
-        create: setupNativeEvents({ preload: props.preload, explicitLinks: props.explicitLinks, actionBase: props.actionBase, transformUrl: props.transformUrl }),
         utils: {
             go: delta => window.history.go(delta),
             beforeLeave

package/dist/routers/scrollRestoration.d.ts

@@ -0,0 +1,24 @@
+import type { RouterContext } from "../types.js";
+/**
+ * Explicit scroll restoration for back/forward navigation. The browser's
+ * native same-document heuristic is unreliable for suspense-driven rendering:
+ * if the destination route forces a layout while the document is still short,
+ * the saved offset for the previous entry is clamped and lost (#577).
+ *
+ * Positions are captured continuously from the scroll event, keyed by the
+ * `_depth` the router already stamps on every history entry — capturing at
+ * scroll time (rather than at exit) stays correct through `useBeforeLeave`
+ * blocked/reverted traversals. The map persists to sessionStorage on pagehide
+ * so restoration survives reloads, which `scrollRestoration = "manual"`
+ * otherwise disables. Restoration runs once routing settles; if the document
+ * is still shorter than the target (a boundary below the fold hasn't
+ * resolved), a ResizeObserver retries as content grows, cancelled by the
+ * first user scroll.
+ */
+export declare function createScrollRestoration(): {
+    /** Before the router reacts to a popstate: mark the traversal target. */
+    onPop(): void;
+    /** After a push: forward entries died, and this depth may be reused. */
+    onPush(): void;
+    create(router: RouterContext): void;
+};

package/dist/routers/scrollRestoration.js

@@ -0,0 +1,106 @@
+import { createEffect, on, onCleanup } from "solid-js";
+import { saveCurrentDepth } from "../lifecycle.js";
+import { bindEvent } from "./createRouter.js";
+const STORAGE_KEY = "solid-router:scroll";
+/**
+ * Explicit scroll restoration for back/forward navigation. The browser's
+ * native same-document heuristic is unreliable for suspense-driven rendering:
+ * if the destination route forces a layout while the document is still short,
+ * the saved offset for the previous entry is clamped and lost (#577).
+ *
+ * Positions are captured continuously from the scroll event, keyed by the
+ * `_depth` the router already stamps on every history entry — capturing at
+ * scroll time (rather than at exit) stays correct through `useBeforeLeave`
+ * blocked/reverted traversals. The map persists to sessionStorage on pagehide
+ * so restoration survives reloads, which `scrollRestoration = "manual"`
+ * otherwise disables. Restoration runs once routing settles; if the document
+ * is still shorter than the target (a boundary below the fold hasn't
+ * resolved), a ResizeObserver retries as content grows, cancelled by the
+ * first user scroll.
+ */
+export function createScrollRestoration() {
+    window.history.scrollRestoration = "manual";
+    // the current entry needs its depth stamp for captures to have a key, even
+    // if something replaced history.state after the lifecycle module loaded
+    saveCurrentDepth();
+    let positions = {};
+    try {
+        positions = JSON.parse(sessionStorage.getItem(STORAGE_KEY)) || {};
+    }
+    catch { }
+    const depth = () => window.history.state && window.history.state._depth;
+    let programmatic = false;
+    let pending;
+    let disconnect;
+    const cancelGuard = () => {
+        disconnect && disconnect();
+        disconnect = undefined;
+    };
+    const unbind = [
+        bindEvent(window, "scroll", () => {
+            const d = depth();
+            if (d != null)
+                positions[d] = window.scrollY;
+            if (!programmatic) {
+                // the user took over — a pending or chasing restore would yank them
+                pending = undefined;
+                cancelGuard();
+            }
+        }),
+        bindEvent(window, "pagehide", () => {
+            try {
+                sessionStorage.setItem(STORAGE_KEY, JSON.stringify(positions));
+            }
+            catch { }
+        })
+    ];
+    const restore = () => {
+        if (pending == null)
+            return;
+        const y = positions[pending];
+        pending = undefined;
+        if (y == null)
+            return;
+        cancelGuard();
+        const attempt = () => {
+            programmatic = true;
+            window.scrollTo(0, y);
+            programmatic = false;
+            // reachable once the document is tall enough to hold the offset
+            return document.documentElement.scrollHeight - window.innerHeight >= y;
+        };
+        if (!attempt() && typeof ResizeObserver !== "undefined") {
+            const observer = new ResizeObserver(() => attempt() && cancelGuard());
+            observer.observe(document.documentElement);
+            disconnect = () => observer.disconnect();
+        }
+    };
+    return {
+        /** Before the router reacts to a popstate: mark the traversal target. */
+        onPop() {
+            pending = depth();
+        },
+        /** After a push: forward entries died, and this depth may be reused. */
+        onPush() {
+            const d = depth();
+            if (d != null)
+                for (const k in positions)
+                    +k >= d && delete positions[k];
+        },
+        create(router) {
+            createEffect(on(router.isRouting, routing => routing || restore(), { defer: true }));
+            onCleanup(() => {
+                unbind.forEach(u => u());
+                cancelGuard();
+            });
+            // reload/back_forward document loads land on an existing entry; a fresh
+            // navigation starts a new one and belongs at the top
+            const [nav] = (performance.getEntriesByType &&
+                performance.getEntriesByType("navigation"));
+            if (nav && nav.type !== "navigate") {
+                pending = depth();
+                restore();
+            }
+        }
+    };
+}

package/package.json

@@ -6,7 +6,7 @@
     "Ryan Turnquist"
   ],
   "license": "MIT",
-  "version": "0.16.2",
+  "version": "0.16.3",
   "homepage": "https://github.com/solidjs/solid-router#readme",
   "repository": {
     "type": "git",