Remember scroll position on back/forward and reload

BrowserRouter has no scroll handling and the browser's own restoration
runs before the page has loaded its data, so it lands short. Track the
window scroll per history entry in sessionStorage and restore it on POP,
retrying as the page grows until it fits, the user scrolls or 5 s pass.
Pushing a new pathname scrolls to the top; query-only pushes (table sort,
filter, page) keep the position.

Closes #1247

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
bbassieandClaude Opus 5.5 committed 2026-11-21 02:43:57 +00:00
1 parent 8692ea3941
commit 33817bbe42
3 files changed
+203

No files matched your search

@@ -11,6 +11,7 @@ import AboutModal from "./AboutModal";
import Link from "./Link";
import { saveJson } from "../util/save_file";
import useScrollRestoration from "../util/useScrollRestoration";
import { useAccount } from "../model/account";
import { DraggingContext } from "../model/is_dragging";
import webUiPackage from "../../package.json";
@@ -50,6 +51,7 @@ function isActiveDropzone(element: HTMLElement | null): boolean {
export default function SiteLayout() {
let navigate = useNavigate();
useScrollRestoration();
let [currentSidebarPath, setCurrentSidebarPath] = useState<string | null>(null);
const screens = Grid.useBreakpoint();
// On phone screens the sidebar becomes an overlay drawer instead of a fixed sider.
@@ -0,0 +1,138 @@
import { useEffect, useLayoutEffect, useRef } from "react";
import { type Location, useLocation, useNavigationType } from "react-router-dom";
const storageKey = "scroll_positions";
const maxEntries = 100;
const restoreTimeoutMs = 5000;
/** Read saved scroll positions, oldest first. */
export function loadScrollPositions(storage: Pick<Storage, "getItem">): Map<string, number> {
try {
const stored = JSON.parse(storage.getItem(storageKey) ?? "[]");
if (Array.isArray(stored)) {
return new Map(stored.filter(
(entry): entry is [string, number] => typeof entry[0] === "string" && typeof entry[1] === "number"
));
}
} catch {
// Fall through to an empty map on corrupt data.
}
return new Map();
}
/** Record a position as the newest entry, dropping the oldest past the limit. */
export function setScrollPosition(positions: Map<string, number>, key: string, y: number) {
positions.delete(key);
positions.set(key, y);
for (const oldest of positions.keys()) {
if (positions.size <= maxEntries) {
break;
}
positions.delete(oldest);
}
}
export function saveScrollPositions(storage: Pick<Storage, "setItem">, positions: Map<string, number>) {
try {
storage.setItem(storageKey, JSON.stringify([...positions]));
} catch {
// Ignore storage errors (e.g. quota exceeded or storage disabled).
}
}
/** History entries created outside the router all share the key "default". */
export function scrollKey(location: Pick<Location, "key" | "pathname" | "search">) {
return location.key === "default" ? `${location.pathname}${location.search}` : location.key;
}
/**
* Scroll to y, retrying as the page grows while its data loads. Gives up after
* a timeout or when the user scrolls.
*/
function restoreScroll(y: number, onDone: () => void) {
const inputEvents = ["wheel", "touchstart", "keydown", "pointerdown"];
const observer = new ResizeObserver(attempt);
const timeout = setTimeout(stop, restoreTimeoutMs);
let stopped = false;
function stop() {
if (stopped) {
return;
}
stopped = true;
observer.disconnect();
clearTimeout(timeout);
for (const event of inputEvents) {
window.removeEventListener(event, stop, true);
}
onDone();
}
function attempt() {
window.scrollTo(0, y);
if (window.scrollY >= y - 1) {
stop();
}
}
for (const event of inputEvents) {
window.addEventListener(event, stop, { capture: true, passive: true });
}
observer.observe(document.body);
attempt();
return stop;
}
/**
* Restore the window scroll position on back/forward and page reload, and
* scroll to the top when navigating to another page.
*/
export default function useScrollRestoration() {
const location = useLocation();
const navigationType = useNavigationType();
const key = scrollKey(location);
const positions = useRef<Map<string, number> | null>(null);
const currentKey = useRef(key);
const restoring = useRef(false);
const pathname = useRef(location.pathname);
if (!positions.current) {
positions.current = loadScrollPositions(sessionStorage);
}
useEffect(() => {
window.history.scrollRestoration = "manual";
function onScroll() {
if (!restoring.current) {
setScrollPosition(positions.current!, currentKey.current, window.scrollY);
}
}
function persist() {
saveScrollPositions(sessionStorage, positions.current!);
}
window.addEventListener("scroll", onScroll, { passive: true });
window.addEventListener("pagehide", persist);
return () => {
window.removeEventListener("scroll", onScroll);
window.removeEventListener("pagehide", persist);
persist();
};
}, []);
useLayoutEffect(() => {
currentKey.current = key;
saveScrollPositions(sessionStorage, positions.current!);
const pathChanged = pathname.current !== location.pathname;
pathname.current = location.pathname;
// Table sort, filter and page changes only change the query
if (navigationType === "PUSH" && pathChanged) {
window.scrollTo(0, 0);
return undefined;
}
if (navigationType !== "POP") {
setScrollPosition(positions.current!, key, window.scrollY);
return undefined;
}
restoring.current = true;
return restoreScroll(positions.current!.get(key) ?? 0, () => { restoring.current = false; });
}, [key]);
}
+63
View File
@@ -0,0 +1,63 @@
import assert from "node:assert/strict";
import {
loadScrollPositions, saveScrollPositions, scrollKey, setScrollPosition,
} from "../../packages/web_ui/src/util/useScrollRestoration.ts";
class MemoryStorage {
items = new Map();
getItem(key) { return this.items.get(key) ?? null; }
setItem(key, value) { this.items.set(key, String(value)); }
}
describe("web_ui/util/useScrollRestoration", function() {
describe("loadScrollPositions()", function() {
it("should round trip through saveScrollPositions", function() {
const storage = new MemoryStorage();
saveScrollPositions(storage, new Map([["a", 10], ["b", 20.5]]));
assert.deepEqual([...loadScrollPositions(storage)], [["a", 10], ["b", 20.5]]);
});
it("should return an empty map when nothing is stored", function() {
assert.equal(loadScrollPositions(new MemoryStorage()).size, 0);
});
it("should ignore corrupt data", function() {
const storage = new MemoryStorage();
storage.setItem("scroll_positions", "{not json");
assert.equal(loadScrollPositions(storage).size, 0);
storage.setItem("scroll_positions", JSON.stringify({ a: 1 }));
assert.equal(loadScrollPositions(storage).size, 0);
storage.setItem("scroll_positions", JSON.stringify([["a", 1], ["b", "x"], [2, 3]]));
assert.deepEqual([...loadScrollPositions(storage)], [["a", 1]]);
});
});
describe("saveScrollPositions()", function() {
it("should ignore storage errors", function() {
saveScrollPositions({ setItem() { throw new Error("QuotaExceededError"); } }, new Map([["a", 1]]));
});
});
describe("setScrollPosition()", function() {
it("should move an updated key to the newest position", function() {
const positions = new Map([["a", 1], ["b", 2]]);
setScrollPosition(positions, "a", 3);
assert.deepEqual([...positions], [["b", 2], ["a", 3]]);
});
it("should drop the oldest entries past 100", function() {
const positions = new Map();
for (let i = 0; i < 105; i++) {
setScrollPosition(positions, `k${i}`, i);
}
assert.equal(positions.size, 100);
assert.equal(positions.has("k4"), false);
assert.equal(positions.get("k5"), 5);
assert.equal(positions.get("k104"), 104);
});
});
describe("scrollKey()", function() {
it("should use the location key", function() {
assert.equal(scrollKey({ key: "abc123", pathname: "/users", search: "" }), "abc123");
});
it("should fall back to the path for entries created outside the router", function() {
assert.equal(scrollKey({ key: "default", pathname: "/users", search: "?q=a" }), "/users?q=a");
});
});
});