🐛(frontend) preserve scroll position across renders (#578)

The thread list lost its scroll position when mailbox stats changed
(triggering a query invalidation) or when navigating between the thread
list and thread view pages (component unmount/remount).

Introduce a ScrollRestoreProvider in MainLayout that stores scroll
positions by identifier. The useScrollRestore hook saves the position
on scroll and restores it after mount or data-driven re-renders, only
when the contextKey (mailbox + search params) matches so that folder
or mailbox switches correctly start at the top.

Author: jbpenrath

src/frontend/src/features/layouts/components/main/index.tsx

@@ -6,19 +6,22 @@ import { NoMailbox } from "./no-mailbox";
 import { SentBoxProvider } from "@/features/providers/sent-box";
 import { LeftPanel } from "./left-panel";
 import { ModalStoreProvider } from "@/features/providers/modal-store";
+import { ScrollRestoreProvider } from "@/features/providers/scroll-restore";
 import { useTheme } from "@/features/providers/theme";
 import Link from "next/link";
 
 export const MainLayout = ({ children }: PropsWithChildren) => {
     return (
         <AuthenticatedView>
-            <MailboxProvider>
-                <SentBoxProvider>
-                    <ModalStoreProvider>
-                        <MainLayoutContent>{children}</MainLayoutContent>
-                    </ModalStoreProvider>
-                </SentBoxProvider>
-            </MailboxProvider>
+            <ScrollRestoreProvider>
+                <MailboxProvider>
+                    <SentBoxProvider>
+                        <ModalStoreProvider>
+                            <MainLayoutContent>{children}</MainLayoutContent>
+                        </ModalStoreProvider>
+                    </SentBoxProvider>
+                </MailboxProvider>
+            </ScrollRestoreProvider>
         </AuthenticatedView>
     )
 }

src/frontend/src/features/layouts/components/thread-panel/index.tsx

@@ -11,6 +11,7 @@ import Image from "next/image";
 import useAbility, { Abilities } from "@/hooks/use-ability";
 import ThreadPanelHeader from "./components/thread-panel-header";
 import { useThreadSelection } from "@/features/providers/thread-selection";
+import { useScrollRestore } from "@/features/providers/scroll-restore";
 
 export const ThreadPanel = () => {
     const { threads, queryStates, unselectThread, loadNextThreads, selectedThread, selectedMailbox } = useMailboxContext();
@@ -19,6 +20,10 @@ export const ThreadPanel = () => {
     const { t } = useTranslation();
     const loaderRef = useRef<HTMLDivElement>(null);
     const canImportMessages = useAbility(Abilities.CAN_IMPORT_MESSAGES, selectedMailbox);
+    const scrollContextKey = `${selectedMailbox?.id}:${searchParams.toString()}`;
+    const { containerRef: scrollContainerRef, onScroll: handleScroll } = useScrollRestore(
+        'thread-list', scrollContextKey, [threads],
+    );
 
     const {
         selectedThreadIds,
@@ -100,7 +105,7 @@ export const ThreadPanel = () => {
                 onEnableSelectionMode={enableSelectionMode}
                 onDisableSelectionMode={clearSelection}
             />
-            <div className="thread-panel__threads_list">
+            <div className="thread-panel__threads_list" ref={scrollContainerRef} onScroll={handleScroll}>
                 {threads?.results.map((thread) => (
                     <ThreadItem
                         key={thread.id}

src/frontend/src/features/providers/mailbox.tsx

@@ -31,12 +31,6 @@ type MessageQueryInvalidationSource = {
      * Messages after this date keep their current state.
      */
     readAt?: string | null;
-    /**
-     * Skip the threads query invalidation (refetch).
-     * Useful when optimistic updates are sufficient (e.g. read flag)
-     * to avoid scroll position reset in the thread list.
-     */
-    skipThreadsInvalidation?: boolean;
 }
 
 type MailboxContextType = {
@@ -377,7 +371,7 @@ export const MailboxProvider = ({ children }: PropsWithChildren) => {
             mailboxes: mailboxQuery.error,
             threads: threadsQuery.error,
             messages: messagesQuery.error,
-        }
+        },
     };
 
     useEffect(() => {

src/frontend/src/features/providers/scroll-restore.tsx

@@ -0,0 +1,79 @@
+import { createContext, PropsWithChildren, useCallback, useContext, useLayoutEffect, useRef } from "react";
+
+type ScrollState = { position: number; contextKey: string };
+
+type ScrollRestoreContextType = {
+    getScrollState: (scrollId: string) => ScrollState;
+    setScrollState: (scrollId: string, state: ScrollState) => void;
+};
+
+const ScrollRestoreContext = createContext<ScrollRestoreContextType | null>(null);
+
+export const ScrollRestoreProvider = ({ children }: PropsWithChildren) => {
+    const statesRef = useRef<Record<string, ScrollState>>({});
+
+    const getScrollState = (scrollId: string): ScrollState => {
+        return statesRef.current[scrollId] ?? { position: 0, contextKey: '' };
+    };
+
+    const setScrollState = (scrollId: string, state: ScrollState) => {
+        statesRef.current[scrollId] = state;
+    };
+
+    return (
+        <ScrollRestoreContext.Provider value={{ getScrollState, setScrollState }}>
+            {children}
+        </ScrollRestoreContext.Provider>
+    );
+};
+
+/**
+ * Persists and restores scroll position of a container across
+ * unmount/remount cycles (e.g. page navigations within the same layout).
+ * Must be used within a ScrollRestoreProvider.
+ *
+ * @param scrollId    A unique identifier for this scroll container.
+ * @param contextKey  Identifies the current view (e.g. mailbox + folder).
+ *                    Scroll is only restored when the saved contextKey matches.
+ * @param deps        Extra dependencies that should trigger a restore attempt
+ *                    (e.g. the data rendered inside the container).
+ */
+export const useScrollRestore = (
+    scrollId: string,
+    contextKey: string,
+    deps: unknown[] = [],
+) => {
+    const context = useContext(ScrollRestoreContext);
+    if (!context) {
+        throw new Error("`useScrollRestore` must be used within a `ScrollRestoreProvider`.");
+    }
+    const { getScrollState, setScrollState } = context;
+    const containerRef = useRef<HTMLDivElement>(null);
+
+    const onScroll = useCallback(() => {
+        if (containerRef.current) {
+            setScrollState(scrollId, {
+                position: containerRef.current.scrollTop,
+                contextKey,
+            });
+        }
+    }, [scrollId, contextKey, setScrollState]);
+
+    useLayoutEffect(() => {
+        const el = containerRef.current;
+        if (!el) return;
+        const saved = getScrollState(scrollId);
+        if (saved.contextKey === contextKey) {
+            // Same context: restore saved position (if any)
+            if (saved.position > 0 && el.scrollTop === 0) {
+                el.scrollTop = saved.position;
+            }
+        } else {
+            // Context changed (e.g. folder switch): reset to top
+            setScrollState(scrollId, { position: 0, contextKey });
+            el.scrollTop = 0;
+        }
+    }, [scrollId, contextKey, getScrollState, setScrollState, ...deps]); // eslint-disable-line react-hooks/exhaustive-deps
+
+    return { containerRef, onScroll };
+}