feat: enhance useArrayVirtualizer to include listContextParams and update ListPage to utilize new scroll state management

Author: arv

apps/zbugs/src/array-test-app.tsx

@@ -176,11 +176,12 @@ function ArrayTestAppContent() {
     permalinkNotFound,
     estimatedTotal,
     total,
-  } = useArrayVirtualizer<RowData, IssueRowSort>({
+  } = useArrayVirtualizer<RowData, IssueRowSort, string>({
     getPageQuery,
     getSingleQuery,
     toStartRow,
     permalinkID,
+    listContextParams: 'test-list',
     scrollState,
     onScrollStateChange,
 

apps/zbugs/src/hooks/use-array-virtualizer.ts

@@ -24,12 +24,14 @@ type TanstackUseVirtualizerOptions<
  *
  * @typeParam TRow - The type of row data returned from queries
  * @typeParam TSort - The type of data needed to anchor pagination (typically a subset of T)
+ * @typeParam TListContextParams - The type of parameters that define the list's query context
  * @typeParam TScrollElement - The type of the scrollable container element
  * @typeParam TItemElement - The type of the individual item elements
  */
 export interface UseArrayVirtualizerOptions<
   TRow,
   TSort,
+  TListContextParams,
   TScrollElement extends Element = HTMLElement,
   TItemElement extends Element = Element,
 > extends Omit<
@@ -56,6 +58,8 @@ export interface UseArrayVirtualizerOptions<
   toStartRow: (row: TRow) => TSort;
   /** Optional ID to highlight/scroll to a specific row (permalink functionality) */
   permalinkID?: string | undefined;
+  /** Parameters that define the list's query context (filters, sort order, etc.) */
+  listContextParams: TListContextParams;
   /**
    * Controlled scroll state. When the consumer provides a new value that
    * differs from what the hook last reported via `onScrollStateChange`, the
@@ -212,6 +216,7 @@ const POSITIONING_SETTLE_DELAY_MS = 50;
 export function useArrayVirtualizer<
   T,
   TSort,
+  TListContextParams,
   TScrollElement extends Element = HTMLElement,
   TItemElement extends Element = Element,
 >({
@@ -221,6 +226,7 @@ export function useArrayVirtualizer<
   getSingleQuery,
   toStartRow,
   permalinkID,
+  listContextParams,
   scrollState: externalScrollState,
   onScrollStateChange,
   debug = false,
@@ -229,6 +235,7 @@ export function useArrayVirtualizer<
 }: UseArrayVirtualizerOptions<
   T,
   TSort,
+  TListContextParams,
   TScrollElement,
   TItemElement
 >): UseArrayVirtualizerReturn<T, TScrollElement, TItemElement> {
@@ -253,6 +260,22 @@ export function useArrayVirtualizer<
   const [hasReachedStart, setHasReachedStart] = useState(false);
   const [hasReachedEnd, setHasReachedEnd] = useState(false);
 
+  // Track the last listContextParams to detect context changes
+  const prevListContextParamsRef = useRef(listContextParams);
+  const isListContextCurrent =
+    prevListContextParamsRef.current === listContextParams;
+
+  // Reset pagination state when list context changes
+  useEffect(() => {
+    if (!isListContextCurrent) {
+      prevListContextParamsRef.current = listContextParams;
+      setMinIndexSeen(null);
+      setMaxIndexSeen(null);
+      setHasReachedStart(false);
+      setHasReachedEnd(false);
+    }
+  }, [isListContextCurrent, listContextParams]);
+
   const scrollInternalRef = useRef({
     pendingScroll: null as number | null,
     pendingScrollIsRelative: false,

apps/zbugs/src/pages/list/list-page.tsx

@@ -1,4 +1,4 @@
-import {useQuery, useZero, useZeroVirtualizer} from '@rocicorp/zero/react';
+import {useQuery, useZero} from '@rocicorp/zero/react';
 import classNames from 'classnames';
 import Cookies from 'js-cookie';
 import React, {
@@ -13,6 +13,7 @@ import React, {
 import {toast} from 'react-toastify';
 import {useDebouncedCallback} from 'use-debounce';
 import {useParams, useSearch} from 'wouter';
+import {useHistoryState} from 'wouter/use-browser-location';
 import {must} from '../../../../../packages/shared/src/must.ts';
 import {
   queries,
@@ -26,16 +27,18 @@ import {IssueLink} from '../../components/issue-link.tsx';
 import {Link} from '../../components/link.tsx';
 import {OnboardingModal} from '../../components/onboarding-modal.tsx';
 import {RelativeTime} from '../../components/relative-time.tsx';
+import {
+  useArrayVirtualizer,
+  type ScrollRestorationState,
+} from '../../hooks/use-array-virtualizer.ts';
 import {useClickOutside} from '../../hooks/use-click-outside.ts';
 import {useElementSize} from '../../hooks/use-element-size.ts';
 import {useHash} from '../../hooks/use-hash.ts';
 import {useKeypress} from '../../hooks/use-keypress.ts';
 import {useLogin} from '../../hooks/use-login.tsx';
-import {useWouterPermalinkState} from '../../hooks/use-wouter-permalink-state.ts';
 import {appendParam, navigate, removeParam, setParam} from '../../navigate.ts';
 import {recordPageLoad} from '../../page-load-stats.ts';
 import {mark} from '../../perf-log.ts';
-import {CACHE_NAV, CACHE_NONE} from '../../query-cache-policy.ts';
 import {isGigabugs, links, useListContext} from '../../routes.tsx';
 import {preload} from '../../zero-preload.ts';
 import {getIDFromString} from '../issue/get-id.tsx';
@@ -109,7 +112,6 @@ export function ListPage({onReady}: {onReady: () => void}) {
         labels,
         open,
         textFilter,
-        permalinkID,
       }) as const,
     [
       projectName,
@@ -120,7 +122,6 @@ export function ListPage({onReady}: {onReady: () => void}) {
       open,
       textFilter,
       labels,
-      permalinkID,
     ],
   );
 
@@ -162,30 +163,31 @@ export function ListPage({onReady}: {onReady: () => void}) {
     navigate(`#issue-${id}`);
   };
 
-  const [permalinkState, setPermalinkState] =
-    useWouterPermalinkState<IssueRowSort>();
+  const scrollStateFromHistory =
+    useHistoryState<ScrollRestorationState | null>();
 
-  const {
-    virtualizer,
-    rowAt,
-    complete,
-    rowsEmpty,
-    permalinkNotFound,
-    estimatedTotal,
-    total,
-  } = useZeroVirtualizer({
-    estimateSize: () => ITEM_SIZE,
-    getScrollElement: () => listRef.current,
-    getRowKey: row => row.id,
+  const scrollState = useMemo(
+    () => scrollStateFromHistory,
+    [
+      scrollStateFromHistory?.scrollAnchorID,
+      scrollStateFromHistory?.index,
+      scrollStateFromHistory?.scrollOffset,
+    ],
+  );
 
-    listContextParams,
-    permalinkID,
+  const handleScrollStateChange = useCallback(
+    (state: ScrollRestorationState) => {
+      window.history.replaceState(state, '', window.location.href);
+    },
+    [],
+  );
 
-    getPageQuery: (
-      limit: number,
-      start: IssueRowSort | null,
-      dir: 'forward' | 'backward',
-    ) =>
+  const estimateRowSize = useCallback(() => ITEM_SIZE, []);
+
+  const getScrollElement = useCallback(() => listRef.current, []);
+
+  const getPageQuery = useCallback(
+    (limit: number, start: IssueRowSort | null, dir: 'forward' | 'backward') =>
       queries.issueListV2({
         listContext: listContextParams,
         userID: z.userID,
@@ -194,8 +196,11 @@ export function ListPage({onReady}: {onReady: () => void}) {
         dir,
         inclusive: start === null,
       }),
+    [listContextParams, z.userID],
+  );
 
-    getSingleQuery: (id: string) => {
+  const getSingleQuery = useCallback(
+    (id: string) => {
       // Allow short ID too.
       const {idField, idValue} = getIDFromString(id);
       return queries.listIssueByID({
@@ -204,17 +209,36 @@ export function ListPage({onReady}: {onReady: () => void}) {
         listContext: listContextParams,
       });
     },
+    [listContextParams],
+  );
 
-    toStartRow: row => ({
+  const toStartRow = useCallback(
+    (row: {id: string; modified: number; created: number}) => ({
       id: row.id,
       modified: row.modified,
       created: row.created,
     }),
+    [],
+  );
 
-    options: textFilterQuery === textFilter ? CACHE_NAV : CACHE_NONE,
-
-    permalinkState,
-    onPermalinkStateChange: setPermalinkState,
+  const {
+    virtualizer,
+    rowAt,
+    complete,
+    rowsEmpty,
+    permalinkNotFound,
+    estimatedTotal,
+    total,
+  } = useArrayVirtualizer({
+    estimateRowSize,
+    getScrollElement,
+    permalinkID: permalinkID ?? undefined,
+    listContextParams,
+    getPageQuery,
+    getSingleQuery,
+    toStartRow,
+    scrollState: scrollState ?? undefined,
+    onScrollStateChange: handleScrollStateChange,
   });
 
   useEffect(() => {