Support automatic start offset calculation

README.md

@@ -99,7 +99,7 @@ export const App = () => {
   return (
     <div style={{ overflowY: "auto", height: 800 }}>
       <div style={{ height: 40 }}>header</div>
-      <Virtualizer startMargin={40}>
+      <Virtualizer startOffset="static">
         {Array.from({ length: 1000 }).map((_, i) => (
           <div
             key={i}

src/core/scroller.ts

@@ -15,7 +15,7 @@ import {
   ACTION_BEFORE_MANUAL_SMOOTH_SCROLL,
   ACTION_START_OFFSET_CHANGE,
 } from "./store";
-import { type ScrollToIndexOpts } from "./types";
+import { type ScrollToIndexOpts, StartOffsetType } from "./types";
 import { debounce, timeout, clamp, microtask } from "./utils";
 
 /**
@@ -34,6 +34,32 @@ const normalizeOffset = (offset: number, isHorizontal: boolean): number => {
   }
 };
 
+const calcOffsetToViewport = (
+  node: HTMLElement,
+  viewport: HTMLElement,
+  isHorizontal: boolean,
+  offset: number = 0
+): number => {
+  // TODO calc offset only when it changes (maybe impossible)
+  const offsetSum =
+    offset +
+    (isHorizontal && isRTLDocument()
+      ? viewport.offsetWidth - node.offsetLeft - node.offsetWidth
+      : node[isHorizontal ? "offsetLeft" : "offsetTop"]);
+
+  const parent = node.offsetParent;
+  if (node === viewport || !parent) {
+    return offsetSum;
+  }
+
+  return calcOffsetToViewport(
+    parent as HTMLElement,
+    viewport,
+    isHorizontal,
+    offsetSum
+  );
+};
+
 const createScrollObserver = (
   store: VirtualStore,
   viewport: HTMLElement | Window,
@@ -121,6 +147,10 @@ const createScrollObserver = (
     }
   };
 
+  if (getStartOffset) {
+    store._update(ACTION_START_OFFSET_CHANGE, getStartOffset());
+  }
+
   viewport.addEventListener("scroll", onScroll);
   viewport.addEventListener("wheel", onWheel, { passive: true });
   viewport.addEventListener("touchstart", onTouchStart, { passive: true });
@@ -159,7 +189,10 @@ type ScrollObserver = ReturnType<typeof createScrollObserver>;
  * @internal
  */
 export type Scroller = {
-  _observe: (viewportElement: HTMLElement) => void;
+  _observe: (
+    viewportElement: HTMLElement,
+    containerElement: HTMLElement
+  ) => void;
   _dispose(): void;
   _scrollTo: (offset: number) => void;
   _scrollBy: (offset: number) => void;
@@ -172,7 +205,8 @@ export type Scroller = {
  */
 export const createScroller = (
   store: VirtualStore,
-  isHorizontal: boolean
+  isHorizontal: boolean,
+  startOffset?: StartOffsetType
 ): Scroller => {
   let viewportElement: HTMLElement | undefined;
   let scrollObserver: ScrollObserver | undefined;
@@ -264,9 +298,24 @@ export const createScroller = (
   };
 
   return {
-    _observe(viewport) {
+    _observe(viewport, container) {
       viewportElement = viewport;
 
+      let getStartOffset: (() => number) | undefined;
+      if (startOffset === "dynamic") {
+        getStartOffset = () =>
+          calcOffsetToViewport(container, viewport, isHorizontal);
+      } else if (startOffset === "static") {
+        const staticStartOffset = calcOffsetToViewport(
+          container,
+          viewport,
+          isHorizontal
+        );
+        getStartOffset = () => staticStartOffset;
+      } else if (typeof startOffset === "number") {
+        getStartOffset = () => startOffset;
+      }
+
       scrollObserver = createScrollObserver(
         store,
         viewport,
@@ -293,7 +342,8 @@ export const createScroller = (
           } else {
             viewport[scrollOffsetKey] += jump;
           }
-        }
+        },
+        getStartOffset
       );
     },
     _dispose() {
@@ -371,33 +421,6 @@ export const createWindowScroller = (
       const window = getCurrentWindow(document);
       const documentBody = document.body;
 
-      const calcOffsetToViewport = (
-        node: HTMLElement,
-        viewport: HTMLElement,
-        isHorizontal: boolean,
-        offset: number = 0
-      ): number => {
-        // TODO calc offset only when it changes (maybe impossible)
-        const offsetKey = isHorizontal ? "offsetLeft" : "offsetTop";
-        const offsetSum =
-          offset +
-          (isHorizontal && isRTLDocument()
-            ? window.innerWidth - node[offsetKey] - node.offsetWidth
-            : node[offsetKey]);
-
-        const parent = node.offsetParent;
-        if (node === viewport || !parent) {
-          return offsetSum;
-        }
-
-        return calcOffsetToViewport(
-          parent as HTMLElement,
-          viewport,
-          isHorizontal,
-          offsetSum
-        );
-      };
-
       scrollObserver = createScrollObserver(
         store,
         window,
@@ -429,7 +452,10 @@ export const createWindowScroller = (
  * @internal
  */
 export type GridScroller = {
-  _observe: (viewportElement: HTMLElement) => void;
+  _observe: (
+    viewportElement: HTMLElement,
+    containerElement: HTMLElement
+  ) => void;
   _dispose(): void;
   _scrollTo: (offsetX: number, offsetY: number) => void;
   _scrollBy: (offsetX: number, offsetY: number) => void;
@@ -447,9 +473,9 @@ export const createGridScroller = (
   const vScroller = createScroller(vStore, false);
   const hScroller = createScroller(hStore, true);
   return {
-    _observe(viewportElement) {
-      vScroller._observe(viewportElement);
-      hScroller._observe(viewportElement);
+    _observe(viewportElement, containerElement) {
+      vScroller._observe(viewportElement, containerElement);
+      hScroller._observe(viewportElement, containerElement);
     },
     _dispose() {
       vScroller._dispose();

src/core/store.ts

@@ -140,13 +140,13 @@ export const createVirtualStore = (
   itemSize: number = 40,
   ssrCount: number = 0,
   cacheSnapshot?: CacheSnapshot | undefined,
-  shouldAutoEstimateItemSize: boolean = false,
-  startSpacerSize: number = 0
+  shouldAutoEstimateItemSize: boolean = false
 ): VirtualStore => {
   let isSSR = !!ssrCount;
   let stateVersion: StateVersion = [];
   let viewportSize = 0;
   let scrollOffset = 0;
+  let startOffset = 0;
   let jumpCount = 0;
   let jump = 0;
   let pendingJump = 0;
@@ -165,7 +165,7 @@ export const createVirtualStore = (
     cacheSnapshot as unknown as InternalCacheSnapshot | undefined
   );
   const subscribers = new Set<[number, Subscriber]>();
-  const getRelativeScrollOffset = () => scrollOffset - startSpacerSize;
+  const getRelativeScrollOffset = () => scrollOffset - startOffset;
   const getRange = (offset: number) => {
     return computeRange(cache, offset, _prevRange[0], viewportSize);
   };
@@ -240,7 +240,7 @@ export const createVirtualStore = (
       return viewportSize;
     },
     _getStartSpacerSize() {
-      return startSpacerSize;
+      return startOffset;
     },
     _getTotalSize: getTotalSize,
     _getJumpCount() {
@@ -418,7 +418,7 @@ export const createVirtualStore = (
           break;
         }
         case ACTION_START_OFFSET_CHANGE: {
-          startSpacerSize = payload;
+          startOffset = payload;
           break;
         }
         case ACTION_MANUAL_SCROLL: {

src/core/types.ts

@@ -42,3 +42,5 @@ export interface ScrollToIndexOpts {
    */
   offset?: number;
 }
+
+export type StartOffsetType = "dynamic" | "static" | number;

src/react/VGrid.tsx

@@ -25,6 +25,7 @@ import { ViewportComponentAttributes } from "./types";
 import { flushSync } from "react-dom";
 import { isRTLDocument } from "../core/environment";
 import { useRerender } from "./useRerender";
+
 const genKey = (i: number, j: number) => `${i}-${j}`;
 
 /**
@@ -250,9 +251,11 @@ export const VGrid = forwardRef<VGridHandle, VGridProps>(
     const height = getScrollSize(vStore);
     const width = getScrollSize(hStore);
     const rootRef = useRef<HTMLDivElement>(null);
+    const containerRef = useRef<HTMLDivElement>(null);
 
     useIsomorphicLayoutEffect(() => {
       const root = rootRef[refKey]!;
+      const container = containerRef[refKey]!;
       // store must be subscribed first because others may dispatch update on init depending on implementation
       const unsubscribeVStore = vStore._subscribe(
         UPDATE_VIRTUAL_STATE,
@@ -275,7 +278,7 @@ export const VGrid = forwardRef<VGridHandle, VGridProps>(
         }
       );
       resizer._observeRoot(root);
-      scroller._observe(root);
+      scroller._observe(root, container);
       return () => {
         unsubscribeVStore();
         unsubscribeHStore();

src/react/Virtualizer.tsx

@@ -24,7 +24,11 @@ import { useStatic } from "./useStatic";
 import { useLatestRef } from "./useLatestRef";
 import { createResizer } from "../core/resizer";
 import { ListItem } from "./ListItem";
-import { CacheSnapshot, ScrollToIndexOpts } from "../core/types";
+import {
+  CacheSnapshot,
+  ScrollToIndexOpts,
+  StartOffsetType,
+} from "../core/types";
 import { flushSync } from "react-dom";
 import { useRerender } from "./useRerender";
 import { useChildren } from "./useChildren";
@@ -120,8 +124,10 @@ export interface VirtualizerProps {
   cache?: CacheSnapshot;
   /**
    * If you put an element before virtualizer, you have to define its height with this prop.
+   *
+   * TODO
    */
-  startMargin?: number;
+  startOffset?: StartOffsetType;
   /**
    * A prop for SSR. If set, the specified amount of items will be mounted in the initial rendering regardless of the container size until hydrated.
    */
@@ -178,7 +184,7 @@ export const Virtualizer = forwardRef<VirtualizerHandle, VirtualizerProps>(
       shift,
       horizontal: horizontalProp,
       cache,
-      startMargin,
+      startOffset,
       ssrCount,
       as: Element = "div",
       item: ItemElement = "div",
@@ -207,13 +213,12 @@ export const Virtualizer = forwardRef<VirtualizerHandle, VirtualizerProps>(
         itemSize,
         ssrCount,
         cache,
-        !itemSize,
-        startMargin
+        !itemSize
       );
       return [
         _store,
         createResizer(_store, _isHorizontal),
-        createScroller(_store, _isHorizontal),
+        createScroller(_store, _isHorizontal, startOffset),
         _isHorizontal,
       ];
     });
@@ -281,15 +286,16 @@ export const Virtualizer = forwardRef<VirtualizerHandle, VirtualizerProps>(
           onScrollEnd[refKey] && onScrollEnd[refKey]();
         }
       );
+      const container = containerRef[refKey]!;
       const assignScrollableElement = (e: HTMLElement) => {
         resizer._observeRoot(e);
-        scroller._observe(e);
+        scroller._observe(e, container);
       };
       if (scrollRef) {
         // parent's ref doesn't exist when useLayoutEffect is called
         microtask(() => assignScrollableElement(scrollRef[refKey]!));
       } else {
-        assignScrollableElement(containerRef[refKey]!.parentElement!);
+        assignScrollableElement(container.parentElement!);
       }
 
       return () => {

src/solid/Virtualizer.tsx

@@ -225,7 +225,7 @@ export const Virtualizer = <T,>(props: VirtualizerProps<T>): JSX.Element => {
 
     const scrollable = containerRef!.parentElement!;
     resizer._observeRoot(scrollable);
-    scroller._observe(scrollable);
+    scroller._observe(scrollable, containerRef!);
 
     onCleanup(() => {
       if (props.ref) {

src/svelte/VList.svelte

@@ -123,8 +123,9 @@
   );
 
   onMount(() => {
+    const container = containerRef!;
     const root = containerRef.parentElement!;
-    virtualizer[ON_MOUNT](root);
+    virtualizer[ON_MOUNT](root, container);
   });
   onDestroy(() => {
     virtualizer[ON_UN_MOUNT]();

src/svelte/core.ts

@@ -73,9 +73,9 @@ export const createVirtualizer = (
   );
 
   return {
-    [ON_MOUNT]: (scrollable: HTMLElement) => {
+    [ON_MOUNT]: (scrollable: HTMLElement, container: HTMLElement) => {
       resizer._observeRoot(scrollable);
-      scroller._observe(scrollable);
+      scroller._observe(scrollable, container);
     },
     [ON_UN_MOUNT]: () => {
       unsubscribeStore();