diff --git a/packages/web_ui/src/components/SiteLayout.tsx b/packages/web_ui/src/components/SiteLayout.tsx index ed03e0ad..8bd02e75 100644 --- a/packages/web_ui/src/components/SiteLayout.tsx +++ b/packages/web_ui/src/components/SiteLayout.tsx @@ -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(null); const screens = Grid.useBreakpoint(); // On phone screens the sidebar becomes an overlay drawer instead of a fixed sider. diff --git a/packages/web_ui/src/util/useScrollRestoration.ts b/packages/web_ui/src/util/useScrollRestoration.ts new file mode 100644 index 00000000..e13e63d7 --- /dev/null +++ b/packages/web_ui/src/util/useScrollRestoration.ts @@ -0,0 +1,147 @@ +import { useEffect, useLayoutEffect, useState } from "react"; +import { type Location, type NavigationType, 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): Map { + 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, 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, positions: Map) { + 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) { + 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. + */ +export 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; +} + +export class ScrollRestorer { + positions = loadScrollPositions(sessionStorage); + restoring = false; + + key: string; + pathname: string; + + constructor(key: string, pathname: string) { + this.key = key; + this.pathname = pathname; + } + + /** Start recording scroll positions, returns a function that stops it. */ + attach() { + window.history.scrollRestoration = "manual"; + const onScroll = () => { + if (!this.restoring) { + setScrollPosition(this.positions, this.key, window.scrollY); + } + }; + const persist = () => saveScrollPositions(sessionStorage, this.positions); + window.addEventListener("scroll", onScroll, { passive: true }); + window.addEventListener("pagehide", persist); + return () => { + window.removeEventListener("scroll", onScroll); + window.removeEventListener("pagehide", persist); + persist(); + }; + } + + /** Handle a location change, returns a function that cancels a pending restore. */ + navigate(key: string, pathname: string, navigationType: NavigationType) { + this.key = key; + saveScrollPositions(sessionStorage, this.positions); + const pathChanged = this.pathname !== pathname; + this.pathname = 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(this.positions, key, window.scrollY); + return undefined; + } + this.restoring = true; + return restoreScroll(this.positions.get(key) ?? 0, () => { this.restoring = false; }); + } +} + +/** + * 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 [restorer] = useState(() => new ScrollRestorer(key, location.pathname)); + useEffect(() => restorer.attach(), []); + useLayoutEffect(() => restorer.navigate(key, location.pathname, navigationType), [key]); +} diff --git a/test/web_ui/useScrollRestoration.js b/test/web_ui/useScrollRestoration.js new file mode 100644 index 00000000..dec3ad03 --- /dev/null +++ b/test/web_ui/useScrollRestoration.js @@ -0,0 +1,260 @@ +import assert from "node:assert/strict"; + +import { + ScrollRestorer, loadScrollPositions, restoreScroll, 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)); } +} + +class FakeWindow { + scrollY = 0; + maxScroll = 0; + listeners = new Map(); + history = { scrollRestoration: "auto" }; + scrollTo(_x, y) { + this.scrollY = Math.max(0, Math.min(y, this.maxScroll)); + this.emit("scroll"); + } + + addEventListener(type, listener) { + if (!this.listeners.has(type)) { + this.listeners.set(type, new Set()); + } + this.listeners.get(type).add(listener); + } + + removeEventListener(type, listener) { + this.listeners.get(type)?.delete(listener); + } + + emit(type) { + for (const listener of [...this.listeners.get(type) ?? []]) { + listener(); + } + } + + count(type) { + return this.listeners.get(type)?.size ?? 0; + } +} + +class FakeResizeObserver { + static observers = new Set(); + constructor(callback) { this.callback = callback; } + observe() { FakeResizeObserver.observers.add(this); } + disconnect() { FakeResizeObserver.observers.delete(this); } +} + +function resize(maxScroll) { + window.maxScroll = maxScroll; + for (const observer of [...FakeResizeObserver.observers]) { + observer.callback(); + } +} + +// Non-enumerable so mocha --check-leaks ignores them +function withDom() { + const names = ["window", "document", "sessionStorage", "ResizeObserver"]; + const saved = new Map(); + beforeEach(function() { + FakeResizeObserver.observers.clear(); + const fakes = { + window: new FakeWindow(), + document: { body: {} }, + sessionStorage: new MemoryStorage(), + ResizeObserver: FakeResizeObserver, + }; + for (const name of names) { + saved.set(name, Object.getOwnPropertyDescriptor(globalThis, name)); + Object.defineProperty(globalThis, name, { value: fakes[name], configurable: true, writable: true }); + } + }); + afterEach(function() { + for (const name of names) { + const descriptor = saved.get(name); + if (descriptor) { + Object.defineProperty(globalThis, name, descriptor); + } else { + delete globalThis[name]; + } + } + }); +} + +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"); + }); + }); + describe("restoreScroll()", function() { + withDom(); + + it("should scroll immediately when the page is tall enough", function() { + window.maxScroll = 2000; + let done = 0; + restoreScroll(1500, () => { done += 1; }); + assert.equal(window.scrollY, 1500); + assert.equal(done, 1); + assert.equal(FakeResizeObserver.observers.size, 0); + assert.equal(window.count("wheel"), 0); + }); + it("should retry as the page grows", function() { + let done = 0; + restoreScroll(1500, () => { done += 1; }); + assert.equal(window.scrollY, 0); + resize(800); + assert.equal(window.scrollY, 800); + assert.equal(done, 0); + resize(3000); + assert.equal(window.scrollY, 1500); + assert.equal(done, 1); + }); + it("should give up when the user scrolls", function() { + let done = 0; + restoreScroll(1500, () => { done += 1; }); + window.emit("wheel"); + assert.equal(done, 1); + resize(3000); + assert.equal(window.scrollY, 0); + }); + it("should give up after the timeout", function() { + const realSetTimeout = globalThis.setTimeout; + let fire; + globalThis.setTimeout = (callback, ms) => { + assert.equal(ms, 5000); + fire = callback; + return 0; + }; + let done = 0; + try { + restoreScroll(1500, () => { done += 1; }); + } finally { + globalThis.setTimeout = realSetTimeout; + } + fire(); + assert.equal(done, 1); + resize(3000); + assert.equal(window.scrollY, 0); + }); + it("should stop only once when cancelled", function() { + let done = 0; + const stop = restoreScroll(1500, () => { done += 1; }); + stop(); + stop(); + assert.equal(done, 1); + }); + }); + describe("class ScrollRestorer", function() { + withDom(); + + it("should record scroll positions per key and persist them", function() { + const restorer = new ScrollRestorer("a", "/users"); + const detach = restorer.attach(); + assert.equal(window.history.scrollRestoration, "manual"); + window.maxScroll = 2000; + window.scrollTo(0, 700); + window.emit("pagehide"); + assert.deepEqual([...loadScrollPositions(sessionStorage)], [["a", 700]]); + window.scrollTo(0, 900); + detach(); + assert.deepEqual([...loadScrollPositions(sessionStorage)], [["a", 900]]); + assert.equal(window.count("scroll"), 0); + assert.equal(window.count("pagehide"), 0); + }); + it("should scroll to the top when pushing another path", function() { + const restorer = new ScrollRestorer("a", "/users"); + restorer.attach(); + window.maxScroll = 2000; + window.scrollTo(0, 1500); + restorer.navigate("b", "/users/x/view", "PUSH"); + assert.equal(window.scrollY, 0); + assert.deepEqual([...loadScrollPositions(sessionStorage)], [["a", 1500]]); + }); + it("should keep the position when only the query changes", function() { + const restorer = new ScrollRestorer("a", "/users"); + restorer.attach(); + window.maxScroll = 2000; + window.scrollTo(0, 1500); + restorer.navigate("b", "/users", "PUSH"); + assert.equal(window.scrollY, 1500); + assert.equal(restorer.positions.get("b"), 1500); + restorer.navigate("c", "/users", "REPLACE"); + assert.equal(restorer.positions.get("c"), 1500); + }); + it("should restore the saved position on pop", function() { + saveScrollPositions(sessionStorage, new Map([["a", 1500], ["b", 0]])); + const restorer = new ScrollRestorer("b", "/users/x/view"); + restorer.attach(); + window.maxScroll = 2000; + window.scrollTo(0, 400); + assert.equal(restorer.positions.get("b"), 400); + restorer.navigate("a", "/users", "POP"); + assert.equal(window.scrollY, 1500); + restorer.navigate("b", "/users/x/view", "POP"); + assert.equal(window.scrollY, 400); + restorer.navigate("unknown", "/hosts", "POP"); + assert.equal(window.scrollY, 0); + }); + it("should not record positions while restoring", function() { + saveScrollPositions(sessionStorage, new Map([["a", 1500]])); + const restorer = new ScrollRestorer("a", "/users"); + restorer.attach(); + const cancel = restorer.navigate("a", "/users", "POP"); + resize(600); + assert.equal(window.scrollY, 600); + assert.equal(restorer.positions.get("a"), 1500); + cancel(); + window.scrollTo(0, 300); + assert.equal(restorer.positions.get("a"), 300); + }); + }); +});