fix(admin): reset scroll position on tab navigation (#3921)

rakdutta · web-flow · commit 23cecbfa2eaa · 2026-04-01T12:51:06.000+01:00
Closes #3748 Automatically scroll to the top of the main content area when switching between admin UI tabs, preventing users from landing mid-page on previously scrolled tabs. - Add requestAnimationFrame-based scroll reset in showTab() - Add data-scroll-container attribute to <main> element - Add Playwright E2E test for scroll reset behavior - Add vitest unit tests for scroll reset and fallback selector - Update fake timers config to include requestAnimationFrame Signed-off-by: Rakhi Dutta <rakhibiswas@yahoo.com> Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>
diff --git a/.secrets.baseline b/.secrets.baseline
@@ -9647,15 +9647,15 @@
       {
         "hashed_secret": "d3ecb0d890368d7659ee54010045b835dacb8efe",
         "is_verified": false,
-        "line_number": 20821,
+        "line_number": 20844,
         "type": "Secret Keyword",
         "verified_result": null,
         "is_secret": false
       },
       {
         "hashed_secret": "b4e44716dbbf57be3dae2f819d96795a85d06652",
         "is_verified": false,
-        "line_number": 33885,
+        "line_number": 33908,
         "type": "Secret Keyword",
         "verified_result": null,
         "is_secret": false
diff --git a/mcpgateway/static/admin.js b/mcpgateway/static/admin.js
@@ -8803,6 +8803,29 @@ function showTab(tabName) {
         const panel = safeGetElement(`${tabName}-panel`);
         if (panel) {
             panel.classList.remove("hidden");
+
+            // Reset scroll position on the main content area
+            // Use requestAnimationFrame to ensure DOM updates have completed
+            try {
+                requestAnimationFrame(() => {
+                    try {
+                        // Try data attribute first (most specific), fall back to class selector
+                        const mainContent =
+                            document.querySelector("[data-scroll-container]") ||
+                            document.querySelector("main.overflow-y-auto");
+                        if (mainContent) {
+                            mainContent.scrollTop = 0;
+                        }
+                    } catch (error) {
+                        console.debug(
+                            "Error resetting scroll position:",
+                            error,
+                        );
+                    }
+                });
+            } catch (error) {
+                console.debug("requestAnimationFrame not available:", error);
+            }
         } else {
             console.error(`Panel ${tabName}-panel not found`);
             const fallbackTab = getDefaultTabName();
diff --git a/mcpgateway/templates/admin.html b/mcpgateway/templates/admin.html
@@ -1003,7 +1003,7 @@ <h1 class="text-lg font-semibold text-gray-800 dark:text-gray-200 hidden sm:bloc
         </div>
 
         <!-- Tab Panels Container -->
-        <main class="flex-1 overflow-y-auto bg-gray-100 dark:bg-gray-900 p-4 lg:p-6">
+        <main data-scroll-container class="flex-1 overflow-y-auto bg-gray-100 dark:bg-gray-900 p-4 lg:p-6">
 
       {% if 'logs' not in hidden_sections %}
       <!-- Logs Panel -->
diff --git a/tests/js/admin-tabs.test.js b/tests/js/admin-tabs.test.js
@@ -2,7 +2,16 @@
  * Unit tests for tab visibility behavior in admin.js.
  */
 
-import { afterAll, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
+import {
+    afterAll,
+    afterEach,
+    beforeAll,
+    beforeEach,
+    describe,
+    expect,
+    test,
+    vi,
+} from "vitest";
 import { cleanupAdminJs, loadAdminJs } from "./helpers/admin-env.js";
 
 let win;
@@ -96,7 +105,8 @@ describe("showTab hidden tab fallback", () => {
 
 describe("showTab idempotency", () => {
     test("does not re-process a tab that is already visible", () => {
-        const { panel: overviewPanel, link: overviewLink } = createTab("overview");
+        const { panel: overviewPanel, link: overviewLink } =
+            createTab("overview");
         createTab("gateways");
 
         win.showTab("overview");
@@ -274,8 +284,14 @@ describe("renderGlobalSearchResults hidden section filtering", () => {
         win.renderGlobalSearchResults({
             groups: [
                 { entity_type: "tools", items: [{ id: "t1", name: "Tool 1" }] },
-                { entity_type: "gateways", items: [{ id: "g1", name: "GW 1" }] },
-                { entity_type: "prompts", items: [{ id: "p1", name: "Prompt 1" }] },
+                {
+                    entity_type: "gateways",
+                    items: [{ id: "g1", name: "GW 1" }],
+                },
+                {
+                    entity_type: "prompts",
+                    items: [{ id: "p1", name: "Prompt 1" }],
+                },
             ],
         });
 
@@ -311,17 +327,18 @@ describe("runGlobalSearch visible entity filtering", () => {
         win.ROOT_PATH = "";
         win.IS_ADMIN = true;
         win.UI_HIDDEN_SECTIONS = ["tools", "prompts", "teams"];
-        const fetchSpy = vi
-            .spyOn(win, "fetchWithAuth")
-            .mockResolvedValue({
-                ok: true,
-                json: async () => ({ groups: [] }),
-            });
+        const fetchSpy = vi.spyOn(win, "fetchWithAuth").mockResolvedValue({
+            ok: true,
+            json: async () => ({ groups: [] }),
+        });
 
         await win.runGlobalSearch("gateway");
 
         expect(fetchSpy).toHaveBeenCalledTimes(1);
-        const requestUrl = new URL(fetchSpy.mock.calls[0][0], "http://localhost");
+        const requestUrl = new URL(
+            fetchSpy.mock.calls[0][0],
+            "http://localhost",
+        );
         expect(requestUrl.searchParams.get("entity_types")).toBe(
             "servers,gateways,resources,agents,users",
         );
@@ -349,7 +366,9 @@ describe("runGlobalSearch visible entity filtering", () => {
         await win.runGlobalSearch("anything");
 
         expect(fetchSpy).not.toHaveBeenCalled();
-        expect(container.innerHTML).toContain("No searchable sections are visible");
+        expect(container.innerHTML).toContain(
+            "No searchable sections are visible",
+        );
     });
 });
 
@@ -421,8 +440,10 @@ describe("resolveTabForNavigation", () => {
 
 describe("showTab normal navigation", () => {
     test("shows the requested visible tab and hides others", () => {
-        const { panel: overviewPanel, link: overviewLink } = createTab("overview");
-        const { panel: gatewaysPanel, link: gatewaysLink } = createTab("gateways");
+        const { panel: overviewPanel, link: overviewLink } =
+            createTab("overview");
+        const { panel: gatewaysPanel, link: gatewaysLink } =
+            createTab("gateways");
 
         win.showTab("gateways");
 
@@ -433,6 +454,61 @@ describe("showTab normal navigation", () => {
     });
 });
 
+describe("showTab scroll reset (#3748)", () => {
+    let originalRAF;
+
+    beforeEach(() => {
+        // JSDOM does not provide requestAnimationFrame; install a synchronous
+        // shim on the JSDOM window so the production code path executes.
+        originalRAF = win.requestAnimationFrame;
+        win.requestAnimationFrame = (cb) => {
+            cb();
+            return 0;
+        };
+    });
+    afterEach(() => {
+        win.requestAnimationFrame = originalRAF;
+    });
+
+    test("resets scrollTop on the data-scroll-container element when switching tabs", () => {
+        createTab("overview");
+        createTab("gateways");
+
+        const scrollContainer = doc.createElement("main");
+        scrollContainer.setAttribute("data-scroll-container", "");
+        scrollContainer.className = "overflow-y-auto";
+        scrollContainer.scrollTop = 500;
+        doc.body.appendChild(scrollContainer);
+
+        win.showTab("gateways");
+
+        expect(scrollContainer.scrollTop).toBe(0);
+    });
+
+    test("falls back to main.overflow-y-auto when data-scroll-container is absent", () => {
+        createTab("overview");
+        createTab("gateways");
+
+        const mainEl = doc.createElement("main");
+        mainEl.className = "overflow-y-auto";
+        mainEl.scrollTop = 300;
+        doc.body.appendChild(mainEl);
+
+        win.showTab("gateways");
+
+        expect(mainEl.scrollTop).toBe(0);
+    });
+
+    test("does not throw when no scroll container exists", () => {
+        createTab("overview");
+        createTab("gateways");
+
+        expect(() => {
+            win.showTab("gateways");
+        }).not.toThrow();
+    });
+});
+
 describe("getDefaultTabName edge cases", () => {
     test("returns gateways fallback when all tabs are hidden and no panels exist", () => {
         // No tabs created, nothing available
diff --git a/tests/js/admin-tag-extraction.test.js b/tests/js/admin-tag-extraction.test.js
@@ -369,10 +369,10 @@ function buildLoadedServersTable() {
 describe("showTab catalog — restore filters from URL on return", () => {
     const showTab = () => win.showTab;
 
-    // showTab wraps content-loading logic in setTimeout; use fake timers
-    // so vi.runAllTimers() flushes the callback synchronously.
+    // showTab wraps content-loading logic in setTimeout and requestAnimationFrame;
+    // use fake timers so vi.runAllTimers() flushes the callbacks synchronously.
     beforeEach(() => {
-        vi.useFakeTimers();
+        vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'requestAnimationFrame'] });
     });
     afterEach(() => {
         vi.useRealTimers();
diff --git a/tests/playwright/test_admin_ui.py b/tests/playwright/test_admin_ui.py
@@ -147,3 +147,69 @@ def test_sidebar_visible_after_mobile_collapse_and_resize(self, admin_page: Admi
         admin_page.page.set_viewport_size({"width": 1280, "height": 800})
         admin_page.page.wait_for_timeout(300)
         expect(sidebar).to_be_visible()
+
+    def test_scroll_reset_on_tab_navigation(self, admin_page: AdminPage):
+        """Test that tab navigation resets scroll position to top (#3748)."""
+        admin_page.navigate()
+
+        admin_page.click_servers_tab()
+        admin_page.page.wait_for_selector("#catalog-panel", state="visible", timeout=10000)
+
+        main_container = admin_page.page.locator("[data-scroll-container]")
+        expect(main_container).to_be_attached()
+
+        # Inject a tall spacer so the container is guaranteed to be scrollable
+        # regardless of how much real content is loaded.
+        admin_page.page.evaluate(
+            """() => {
+                const container = document.querySelector('[data-scroll-container]');
+                if (container) {
+                    const spacer = document.createElement('div');
+                    spacer.id = '_scroll_test_spacer';
+                    spacer.style.height = '5000px';
+                    container.appendChild(spacer);
+                }
+            }"""
+        )
+
+        # Scroll down and wait for the browser to apply it
+        admin_page.page.evaluate(
+            """() => {
+                const container = document.querySelector('[data-scroll-container]');
+                if (container) { container.scrollTop = 500; }
+            }"""
+        )
+        admin_page.page.wait_for_function(
+            "document.querySelector('[data-scroll-container]').scrollTop > 0",
+            timeout=5000,
+        )
+
+        # Switch tab — showTab() should reset scroll via requestAnimationFrame
+        admin_page.click_tools_tab()
+        admin_page.page.wait_for_selector("#tools-panel", state="visible", timeout=10000)
+
+        # Wait for the RAF-driven scroll reset rather than a fixed sleep
+        admin_page.page.wait_for_function(
+            "document.querySelector('[data-scroll-container]').scrollTop === 0",
+            timeout=5000,
+        )
+
+        # Second round: verify consistency across another tab pair
+        admin_page.page.evaluate(
+            """() => {
+                const container = document.querySelector('[data-scroll-container]');
+                if (container) { container.scrollTop = 300; }
+            }"""
+        )
+        admin_page.page.wait_for_function(
+            "document.querySelector('[data-scroll-container]').scrollTop > 0",
+            timeout=5000,
+        )
+
+        admin_page.click_gateways_tab()
+        admin_page.page.wait_for_selector("#gateways-panel", state="visible", timeout=10000)
+
+        admin_page.page.wait_for_function(
+            "document.querySelector('[data-scroll-container]').scrollTop === 0",
+            timeout=5000,
+        )
