react-virtual-renderer 1.1.1 → 1.1.3

package/dist/hooks/useInfiniteScroll.js

@@ -1,37 +1,43 @@
-import { useCallback, useRef, useEffect, useState, } from 'react';
+import { useCallback, useEffect, useRef, useState, } from "react";
 /**
- * Infinite Scroll Hook
+ * useInfiniteScroll
  *
- * Automatically triggers `onLoadMore`
- * when user scrolls near the bottom.
+ * Automatically calls onLoadMore when the user
+ * scrolls near the bottom of a container.
  */
 export function useInfiniteScroll({ onLoadMore, threshold = 500, isLoading = false, enabled = true, }) {
     const containerRef = useRef(null);
     const [isAtBottom, setIsAtBottom] = useState(false);
-    const hasCalledRef = useRef(false);
+    const loadingRef = useRef(false);
     const onLoadMoreRef = useRef(onLoadMore);
     useEffect(() => {
         onLoadMoreRef.current = onLoadMore;
     }, [onLoadMore]);
     const checkIfAtBottom = useCallback(() => {
-        if (!enabled || isLoading)
+        if (!enabled)
             return;
         const container = containerRef.current;
         if (!container)
             return;
         const { scrollTop, scrollHeight, clientHeight, } = container;
-        const distanceFromBottom = scrollHeight - scrollTop - clientHeight;
-        const atBottom = distanceFromBottom <= threshold;
-        setIsAtBottom(atBottom);
-        if (atBottom &&
-            !hasCalledRef.current &&
+        const distanceFromBottom = scrollHeight -
+            scrollTop -
+            clientHeight;
+        const reachedBottom = distanceFromBottom <= threshold;
+        setIsAtBottom(reachedBottom);
+        if (reachedBottom &&
+            !loadingRef.current &&
             !isLoading) {
-            hasCalledRef.current = true;
+            loadingRef.current = true;
             Promise.resolve(onLoadMoreRef.current()).finally(() => {
-                hasCalledRef.current = false;
+                loadingRef.current = false;
             });
         }
-    }, [threshold, isLoading, enabled]);
+    }, [
+        threshold,
+        enabled,
+        isLoading,
+    ]);
     useEffect(() => {
         if (!enabled)
             return;
@@ -41,13 +47,16 @@ export function useInfiniteScroll({ onLoadMore, threshold = 500, isLoading = fal
         const handleScroll = () => {
             checkIfAtBottom();
         };
-        container.addEventListener('scroll', handleScroll, { passive: true });
+        container.addEventListener("scroll", handleScroll, { passive: true });
         // Initial check
         checkIfAtBottom();
         return () => {
-            container.removeEventListener('scroll', handleScroll);
+            container.removeEventListener("scroll", handleScroll);
         };
-    }, [checkIfAtBottom, enabled]);
+    }, [
+        enabled,
+        checkIfAtBottom,
+    ]);
     return {
         containerRef,
         isAtBottom,

package/dist/hooks/useInfiniteScroll.js.map

@@ -1 +1 @@
-{"version":3,"file":"useInfiniteScroll.js","sourceRoot":"","sources":["../../src/hooks/useInfiniteScroll.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,WAAW,EACX,MAAM,EACN,SAAS,EACT,QAAQ,GACX,MAAM,OAAO,CAAC;AAmCf;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAE/B,EACE,UAAU,EACV,SAAS,GAAG,GAAG,EACf,SAAS,GAAG,KAAK,EACjB,OAAO,GAAG,IAAI,GACQ;IACtB,MAAM,YAAY,GAAG,MAAM,CAAW,IAAI,CAAC,CAAC;IAE5C,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAEpD,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACnC,MAAM,aAAa,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IAEzC,SAAS,CAAC,GAAG,EAAE;QACX,aAAa,CAAC,OAAO,GAAG,UAAU,CAAC;IACvC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;IAEjB,MAAM,eAAe,GAAG,WAAW,CAAC,GAAG,EAAE;QACrC,IAAI,CAAC,OAAO,IAAI,SAAS;YAAE,OAAO;QAElC,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC;QAEvC,IAAI,CAAC,SAAS;YAAE,OAAO;QAEvB,MAAM,EACF,SAAS,EACT,YAAY,EACZ,YAAY,GACf,GAAG,SAAS,CAAC;QAEd,MAAM,kBAAkB,GACpB,YAAY,GAAG,SAAS,GAAG,YAAY,CAAC;QAE5C,MAAM,QAAQ,GAAG,kBAAkB,IAAI,SAAS,CAAC;QAEjD,aAAa,CAAC,QAAQ,CAAC,CAAC;QAExB,IACI,QAAQ;YACR,CAAC,YAAY,CAAC,OAAO;YACrB,CAAC,SAAS,EACZ,CAAC;YACC,YAAY,CAAC,OAAO,GAAG,IAAI,CAAC;YAE5B,OAAO,CAAC,OAAO,CACX,aAAa,CAAC,OAAO,EAAE,CAC1B,CAAC,OAAO,CAAC,GAAG,EAAE;gBACX,YAAY,CAAC,OAAO,GAAG,KAAK,CAAC;YACjC,CAAC,CAAC,CAAC;QACP,CAAC;IACL,CAAC,EAAE,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;IAEpC,SAAS,CAAC,GAAG,EAAE;QACX,IAAI,CAAC,OAAO;YAAE,OAAO;QAErB,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC;QAEvC,IAAI,CAAC,SAAS;YAAE,OAAO;QAEvB,MAAM,YAAY,GAAG,GAAG,EAAE;YACtB,eAAe,EAAE,CAAC;QACtB,CAAC,CAAC;QAEF,SAAS,CAAC,gBAAgB,CACtB,QAAQ,EACR,YAAY,EACZ,EAAE,OAAO,EAAE,IAAI,EAAE,CACpB,CAAC;QAEF,gBAAgB;QAChB,eAAe,EAAE,CAAC;QAElB,OAAO,GAAG,EAAE;YACR,SAAS,CAAC,mBAAmB,CACzB,QAAQ,EACR,YAAY,CACf,CAAC;QACN,CAAC,CAAC;IACN,CAAC,EAAE,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC;IAE/B,OAAO;QACH,YAAY;QACZ,UAAU;QACV,SAAS;QACT,eAAe;KAClB,CAAC;AACN,CAAC"}
+{"version":3,"file":"useInfiniteScroll.js","sourceRoot":"","sources":["../../src/hooks/useInfiniteScroll.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,WAAW,EACX,SAAS,EACT,MAAM,EACN,QAAQ,GACX,MAAM,OAAO,CAAC;AAkCf;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAE/B,EACE,UAAU,EACV,SAAS,GAAG,GAAG,EACf,SAAS,GAAG,KAAK,EACjB,OAAO,GAAG,IAAI,GACQ;IACtB,MAAM,YAAY,GAAG,MAAM,CAAW,IAAI,CAAC,CAAC;IAE5C,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,GAC7B,QAAQ,CAAC,KAAK,CAAC,CAAC;IAEpB,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAEjC,MAAM,aAAa,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IAEzC,SAAS,CAAC,GAAG,EAAE;QACX,aAAa,CAAC,OAAO,GAAG,UAAU,CAAC;IACvC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;IAEjB,MAAM,eAAe,GAAG,WAAW,CAAC,GAAG,EAAE;QACrC,IAAI,CAAC,OAAO;YAAE,OAAO;QAErB,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC;QAEvC,IAAI,CAAC,SAAS;YAAE,OAAO;QAEvB,MAAM,EACF,SAAS,EACT,YAAY,EACZ,YAAY,GACf,GAAG,SAAS,CAAC;QAEd,MAAM,kBAAkB,GACpB,YAAY;YACZ,SAAS;YACT,YAAY,CAAC;QAEjB,MAAM,aAAa,GACf,kBAAkB,IAAI,SAAS,CAAC;QAEpC,aAAa,CAAC,aAAa,CAAC,CAAC;QAE7B,IACI,aAAa;YACb,CAAC,UAAU,CAAC,OAAO;YACnB,CAAC,SAAS,EACZ,CAAC;YACC,UAAU,CAAC,OAAO,GAAG,IAAI,CAAC;YAE1B,OAAO,CAAC,OAAO,CACX,aAAa,CAAC,OAAO,EAAE,CAC1B,CAAC,OAAO,CAAC,GAAG,EAAE;gBACX,UAAU,CAAC,OAAO,GAAG,KAAK,CAAC;YAC/B,CAAC,CAAC,CAAC;QACP,CAAC;IACL,CAAC,EAAE;QACC,SAAS;QACT,OAAO;QACP,SAAS;KACZ,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACX,IAAI,CAAC,OAAO;YAAE,OAAO;QAErB,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC;QAEvC,IAAI,CAAC,SAAS;YAAE,OAAO;QAEvB,MAAM,YAAY,GAAG,GAAG,EAAE;YACtB,eAAe,EAAE,CAAC;QACtB,CAAC,CAAC;QAEF,SAAS,CAAC,gBAAgB,CACtB,QAAQ,EACR,YAAY,EACZ,EAAE,OAAO,EAAE,IAAI,EAAE,CACpB,CAAC;QAEF,gBAAgB;QAChB,eAAe,EAAE,CAAC;QAElB,OAAO,GAAG,EAAE;YACR,SAAS,CAAC,mBAAmB,CACzB,QAAQ,EACR,YAAY,CACf,CAAC;QACN,CAAC,CAAC;IACN,CAAC,EAAE;QACC,OAAO;QACP,eAAe;KAClB,CAAC,CAAC;IAEH,OAAO;QACH,YAAY;QACZ,UAAU;QACV,SAAS;QACT,eAAe;KAClB,CAAC;AACN,CAAC"}

package/dist/hooks/useVirtualList.d.ts

@@ -1,22 +1,80 @@
 import { CSSProperties, MutableRefObject } from 'react';
 import { VirtualItem, ScrollDirection } from '../types';
-interface UseVirtualListParams<T> {
+/**
+ * Axis the list scrolls along.
+ * 'vertical'   -> uses scrollTop / height / top offset (default, unchanged behavior)
+ * 'horizontal' -> uses scrollLeft / width / left offset
+ */
+export type ScrollAxis = 'vertical' | 'horizontal';
+export interface UseVirtualListParams<T> {
     items: T[];
+    /**
+     * Stable key extractor. Falls back to index if omitted.
+     * (Previously accepted but unused - now wired up via
+     * getItemKeyForIndex in the return value.)
+     */
     getItemKey?: (index: number, item: T) => string | number;
+    /**
+     * Size of the viewport along the scroll axis.
+     * 'vertical' (default): height. 'horizontal': width.
+     */
     containerHeight: number;
+    /**
+     * Size of the viewport along the cross axis.
+     * 'vertical': width (rarely needed). 'horizontal': height.
+     */
     containerWidth?: number;
+    /**
+     * Fixed size, or a function returning size per index. Note:
+     * the underlying VirtualizationEngine is measurement-driven
+     * (it learns sizes via ResizeObserver / ResizeObserver fallback
+     * rather than consulting a size function on every read). This
+     * value is used only as the *initial estimate* fed into the
+     * engine constructor when provided as a number; if provided as
+     * a function it is not yet consulted by the engine for offset
+     * math (kept for backward-compat / future engine support - do
+     * not rely on per-index function output overriding measured
+     * sizes today).
+     */
     itemSize?: number | ((index: number) => number);
     overscan?: number;
+    /**
+     * Scroll axis. Defaults to 'vertical' to preserve existing behavior.
+     */
+    axis?: ScrollAxis;
+    /**
+     * @deprecated No longer consulted. Direction is now derived
+     * internally from scroll deltas and exposed via the returned
+     * `scrollDirection` value. Kept only so existing callers don't
+     * break when passing this; has no effect.
+     */
     scrollDirection?: ScrollDirection;
     estimatedItemSize?: number;
     onScroll?: (offset: number, direction: ScrollDirection) => void;
     onScrollEnd?: () => void;
     stickyIndices?: number[];
+    /**
+     * Debounce (ms) before isScrolling flips back to false and
+     * onScrollEnd fires. Defaults to 150 (previous hardcoded value).
+     */
+    scrollEndDelay?: number;
+    /**
+     * If true (default), auto-measures the container's own
+     * clientHeight/clientWidth via ResizeObserver and uses that as
+     * a fallback whenever containerHeight/containerWidth are not
+     * provided or are <= 0.
+     */
+    autoMeasureContainer?: boolean;
 }
-interface UseVirtualListReturn {
+export interface UseVirtualListReturn {
     virtualItems: VirtualItem[];
     isScrolling: boolean;
     scrollOffset: number;
+    /**
+     * NEW: direction of the most recent scroll movement. Previously
+     * tracked internally via a ref but never exposed.
+     */
+    scrollDirection: ScrollDirection;
     totalSize: number;
     scrollToItem: (index: number, alignment?: 'start' | 'center' | 'end') => void;
     scrollToOffset: (offset: number) => void;
@@ -24,10 +82,30 @@ interface UseVirtualListReturn {
     containerRef: MutableRefObject<HTMLDivElement | null>;
     innerRef: MutableRefObject<HTMLDivElement | null>;
     getItemStyle: (index: number, size: number) => CSSProperties;
+    /**
+     * NEW: invalidates cached size measurements from the given
+     * index onward (or all items if omitted), forcing those indices
+     * to fall back to the estimated size until re-measured. Use
+     * when item content changes size after initial measurement
+     * (async image load, expand/collapse rows, etc).
+     *
+     * Backed by VirtualizationEngine.invalidateFrom().
+     */
+    recalculate: (fromIndex?: number) => void;
+    /**
+     * NEW: resolves the stable key for a rendered index, using
+     * `getItemKey` when provided and falling back to index.
+     */
+    getItemKeyForIndex: (index: number) => string | number;
 }
 /**
- * Virtualized list hook
+ * Virtualized list hook. Supports vertical or horizontal axes,
+ * sticky items, measured/estimated sizing, and imperative
+ * scroll/recalculate controls.
+ *
+ * Backward compatible: every field in the original return value
+ * keeps its original name, type, and behavior. New fields
+ * (scrollDirection, recalculate, getItemKeyForIndex) are additive.
  */
 export declare function useVirtualList<T = any>(params: UseVirtualListParams<T>): UseVirtualListReturn;
-export {};
 //# sourceMappingURL=useVirtualList.d.ts.map

package/dist/hooks/useVirtualList.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useVirtualList.d.ts","sourceRoot":"","sources":["../../src/hooks/useVirtualList.ts"],"names":[],"mappings":"AAAA,OAAO,EAKH,aAAa,EACb,gBAAgB,EACnB,MAAM,OAAO,CAAC;AAKf,OAAO,EACH,WAAW,EACX,eAAe,EAClB,MAAM,UAAU,CAAC;AAElB,UAAU,oBAAoB,CAAC,CAAC;IAC5B,KAAK,EAAE,CAAC,EAAE,CAAC;IAEX,UAAU,CAAC,EAAE,CACT,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,CAAC,KACN,MAAM,GAAG,MAAM,CAAC;IAErB,eAAe,EAAE,MAAM,CAAC;IAExB,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,QAAQ,CAAC,EACP,MAAM,GACN,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;IAE9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,eAAe,CAAC,EAAE,eAAe,CAAC;IAElC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,QAAQ,CAAC,EAAE,CACP,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,eAAe,KACzB,IAAI,CAAC;IAEV,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IAEzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,UAAU,oBAAoB;IAC1B,YAAY,EAAE,WAAW,EAAE,CAAC;IAE5B,WAAW,EAAE,OAAO,CAAC;IAErB,YAAY,EAAE,MAAM,CAAC;IAErB,SAAS,EAAE,MAAM,CAAC;IAElB,YAAY,EAAE,CACV,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EACJ,OAAO,GACP,QAAQ,GACR,KAAK,KACV,IAAI,CAAC;IAEV,cAAc,EAAE,CACZ,MAAM,EAAE,MAAM,KACb,IAAI,CAAC;IAEV,eAAe,EAAE,CACb,MAAM,EAAE,MAAM,KACb,IAAI,CAAC;IAEV,YAAY,EAAE,gBAAgB,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAEtD,QAAQ,EAAE,gBAAgB,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAElD,YAAY,EAAE,CACV,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,KACX,aAAa,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,GAAG,GAAG,EAClC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAChC,oBAAoB,CAuZtB"}
+{"version":3,"file":"useVirtualList.d.ts","sourceRoot":"","sources":["../../src/hooks/useVirtualList.ts"],"names":[],"mappings":"AAAA,OAAO,EAMH,aAAa,EACb,gBAAgB,EACnB,MAAM,OAAO,CAAC;AAKf,OAAO,EACH,WAAW,EACX,eAAe,EAClB,MAAM,UAAU,CAAC;AAElB;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,YAAY,CAAC;AAEnD,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACnC,KAAK,EAAE,CAAC,EAAE,CAAC;IAEX;;;;OAIG;IACH,UAAU,CAAC,EAAE,CACT,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,CAAC,KACN,MAAM,GAAG,MAAM,CAAC;IAErB;;;OAGG;IACH,eAAe,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EACP,MAAM,GACN,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;IAE9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAElB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAElC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,QAAQ,CAAC,EAAE,CACP,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,eAAe,KACzB,IAAI,CAAC;IAEV,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IAEzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,oBAAoB;IACjC,YAAY,EAAE,WAAW,EAAE,CAAC;IAE5B,WAAW,EAAE,OAAO,CAAC;IAErB,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,eAAe,EAAE,eAAe,CAAC;IAEjC,SAAS,EAAE,MAAM,CAAC;IAElB,YAAY,EAAE,CACV,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EACJ,OAAO,GACP,QAAQ,GACR,KAAK,KACV,IAAI,CAAC;IAEV,cAAc,EAAE,CACZ,MAAM,EAAE,MAAM,KACb,IAAI,CAAC;IAEV,eAAe,EAAE,CACb,MAAM,EAAE,MAAM,KACb,IAAI,CAAC;IAEV,YAAY,EAAE,gBAAgB,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAEtD,QAAQ,EAAE,gBAAgB,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAElD,YAAY,EAAE,CACV,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,KACX,aAAa,CAAC;IAEnB;;;;;;;;OAQG;IACH,WAAW,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAE1C;;;OAGG;IACH,kBAAkB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,CAAC;CAC1D;AAID;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,CAAC,GAAG,GAAG,EAClC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAChC,oBAAoB,CAwdtB"}

package/dist/hooks/useVirtualList.js

@@ -1,29 +1,102 @@
-import { useState, useCallback, useRef, useEffect, } from 'react';
+import { useState, useCallback, useRef, useEffect, useMemo, } from 'react';
 import { VirtualizationEngine } from '../core/VirtualizationEngine';
 import { MeasurementSystem } from '../core/MeasurementSystem';
+const noop = () => { };
 /**
- * Virtualized list hook
+ * Virtualized list hook. Supports vertical or horizontal axes,
+ * sticky items, measured/estimated sizing, and imperative
+ * scroll/recalculate controls.
+ *
+ * Backward compatible: every field in the original return value
+ * keeps its original name, type, and behavior. New fields
+ * (scrollDirection, recalculate, getItemKeyForIndex) are additive.
  */
 export function useVirtualList(params) {
-    const { items, containerHeight, overscan = 5, scrollDirection = 'forward', estimatedItemSize = 35, onScroll, onScrollEnd, stickyIndices = [], } = params;
+    const { items, getItemKey, containerHeight, containerWidth, overscan = 5, estimatedItemSize = 35, axis = 'vertical', onScroll = noop, onScrollEnd = noop, stickyIndices, scrollEndDelay = 150, autoMeasureContainer = true, } = params;
+    const isHorizontal = axis === 'horizontal';
     /**
-     * Core systems
+     * Stable ref for stickyIndices so effects don't re-run every
+     * render when the caller passes a fresh inline array literal.
      */
-    const engineRef = useRef(new VirtualizationEngine(estimatedItemSize));
-    const measurementRef = useRef(new MeasurementSystem());
+    const stickyIndicesRef = useRef(stickyIndices ?? []);
+    const stickyKey = stickyIndices ? stickyIndices.join(',') : '';
+    useEffect(() => {
+        stickyIndicesRef.current = stickyIndices ?? [];
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [stickyKey]);
+    /**
+     * Core systems - constructed exactly once per hook instance.
+     * Lazy-init via ref guard instead of useRef(new X()), which
+     * would otherwise construct a throwaway instance on every
+     * render even though only the first one is kept.
+     */
+    const engineRef = useRef(null);
+    if (engineRef.current === null) {
+        engineRef.current = new VirtualizationEngine(estimatedItemSize);
+    }
+    const measurementRef = useRef(null);
+    if (measurementRef.current === null) {
+        measurementRef.current = new MeasurementSystem();
+    }
     /**
      * DOM refs
      */
     const containerRef = useRef(null);
     const innerRef = useRef(null);
+    /**
+     * Auto-measured container size, used only as a fallback when
+     * containerHeight/containerWidth are not supplied or are <= 0.
+     */
+    const [measuredViewport, setMeasuredViewport] = useState({ height: 0, width: 0 });
+    useEffect(() => {
+        if (!autoMeasureContainer) {
+            return;
+        }
+        const node = containerRef.current;
+        if (!node || typeof ResizeObserver === 'undefined') {
+            return;
+        }
+        const observer = new ResizeObserver((entries) => {
+            const entry = entries[0];
+            if (!entry)
+                return;
+            const { height, width } = entry.contentRect;
+            setMeasuredViewport((prev) => {
+                if (prev.height === height && prev.width === width) {
+                    return prev;
+                }
+                return { height, width };
+            });
+        });
+        observer.observe(node);
+        return () => {
+            observer.disconnect();
+        };
+    }, [autoMeasureContainer]);
+    const resolvedViewportSize = containerHeight > 0
+        ? containerHeight
+        : measuredViewport.height;
+    const resolvedCrossAxisSize = containerWidth && containerWidth > 0
+        ? containerWidth
+        : measuredViewport.width;
     /**
      * Scroll state
      */
-    const [scrollOffset, setScrollOffset] = useState(0);
+    const [scrollOffset, setScrollOffsetState] = useState(0);
     const [isScrolling, setIsScrolling] = useState(false);
+    const [scrollDirection, setScrollDirection] = useState('forward');
     const scrollTimeoutRef = useRef(null);
     const lastScrollOffsetRef = useRef(0);
-    const scrollDirectionRef = useRef(scrollDirection);
+    /**
+     * Bumped whenever a measurement comes in (or invalidateFrom is
+     * called), so totalSize / virtualItems recompute even though
+     * scrollOffset/containerHeight haven't changed. This fixes a
+     * real bug in the original: totalSize was read once per render
+     * body with no dependency tracking, so it went stale after
+     * async ResizeObserver measurements landed until some unrelated
+     * state update happened to trigger a re-render.
+     */
+    const [measurementVersion, setMeasurementVersion] = useState(0);
     /**
      * Virtual items
      */
@@ -33,31 +106,31 @@ export function useVirtualList(params) {
      */
     useEffect(() => {
         const engine = engineRef.current;
-        const visibleItems = engine.getVisibleItems(scrollOffset, containerHeight, items.length, overscan);
+        if (!resolvedViewportSize || items.length === 0) {
+            setVirtualItems((prev) => (prev.length === 0 ? prev : []));
+            return;
+        }
+        const visibleItems = engine.getVisibleItems(scrollOffset, resolvedViewportSize, items.length, overscan);
+        const sticky = stickyIndicesRef.current;
         const nextVirtualItems = visibleItems.map((item) => ({
             index: item.index,
             offset: item.offset,
             size: item.size,
-            isSticky: stickyIndices.includes(item.index),
+            isSticky: sticky.includes(item.index),
         }));
         /**
-         * Prevent infinite re-renders
+         * Prevent unnecessary re-renders when content is unchanged
          */
         setVirtualItems((prev) => {
-            if (prev.length ===
-                nextVirtualItems.length) {
+            if (prev.length === nextVirtualItems.length) {
                 let changed = false;
                 for (let i = 0; i < prev.length; i++) {
                     const prevItem = prev[i];
                     const nextItem = nextVirtualItems[i];
-                    if (prevItem.index !==
-                        nextItem.index ||
-                        prevItem.offset !==
-                            nextItem.offset ||
-                        prevItem.size !==
-                            nextItem.size ||
-                        prevItem.isSticky !==
-                            nextItem.isSticky) {
+                    if (prevItem.index !== nextItem.index ||
+                        prevItem.offset !== nextItem.offset ||
+                        prevItem.size !== nextItem.size ||
+                        prevItem.isSticky !== nextItem.isSticky) {
                         changed = true;
                         break;
                     }
@@ -70,131 +143,179 @@ export function useVirtualList(params) {
         });
     }, [
         scrollOffset,
-        containerHeight,
+        resolvedViewportSize,
         items.length,
         overscan,
-        stickyIndices,
+        stickyKey,
+        measurementVersion,
     ]);
     /**
-     * Handle scrolling
+     * Handle scrolling (DOM-native handler, attached via effect below)
      */
-    const handleScroll = useCallback((e) => {
+    const handleScrollEvent = useCallback((e) => {
         const target = e.currentTarget;
-        const newScrollOffset = target.scrollTop;
-        /**
-         * Skip duplicate updates
-         */
-        if (newScrollOffset ===
-            lastScrollOffsetRef.current) {
+        const newScrollOffset = isHorizontal
+            ? target.scrollLeft
+            : target.scrollTop;
+        if (newScrollOffset === lastScrollOffsetRef.current) {
             return;
         }
-        /**
-         * Detect direction
-         */
-        const direction = newScrollOffset >
-            lastScrollOffsetRef.current
+        const direction = newScrollOffset > lastScrollOffsetRef.current
             ? 'forward'
             : 'reverse';
-        scrollDirectionRef.current =
-            direction;
-        lastScrollOffsetRef.current =
-            newScrollOffset;
-        setScrollOffset(newScrollOffset);
+        lastScrollOffsetRef.current = newScrollOffset;
+        setScrollDirection(direction);
+        setScrollOffsetState(newScrollOffset);
         setIsScrolling(true);
-        /**
-         * User callback
-         */
-        if (onScroll) {
-            onScroll(newScrollOffset, direction);
-        }
-        /**
-         * Debounce scroll end
-         */
+        onScroll(newScrollOffset, direction);
         if (scrollTimeoutRef.current) {
             clearTimeout(scrollTimeoutRef.current);
         }
-        scrollTimeoutRef.current =
-            setTimeout(() => {
-                setIsScrolling(false);
-                if (onScrollEnd) {
-                    onScrollEnd();
-                }
-            }, 150);
-    }, [onScroll, onScrollEnd]);
+        scrollTimeoutRef.current = setTimeout(() => {
+            setIsScrolling(false);
+            onScrollEnd();
+        }, scrollEndDelay);
+    }, [isHorizontal, onScroll, onScrollEnd, scrollEndDelay]);
     /**
-     * Attach scroll listener
+     * Attach scroll listener. Passive: we only read scrollTop/Left
+     * synchronously and never call preventDefault.
      */
     useEffect(() => {
         const container = containerRef.current;
         if (!container) {
             return;
         }
-        const listener = (e) => {
-            handleScroll(e);
-        };
-        container.addEventListener('scroll', listener);
+        container.addEventListener('scroll', handleScrollEvent, {
+            passive: true,
+        });
         return () => {
-            container.removeEventListener('scroll', listener);
+            container.removeEventListener('scroll', handleScrollEvent);
         };
-    }, [handleScroll]);
+    }, [handleScrollEvent]);
     /**
-     * Measure item sizes
+     * Measure item sizes (height axis -> engine size; width axis ->
+     * separate width measurement, tracked by MeasurementSystem but
+     * not fed into the engine, since the engine is a 1-D size
+     * model along whichever axis is "size" for this list).
      */
     const handleItemMeasure = useCallback((index, size) => {
         engineRef.current.recordItemSize(index, size);
+        setMeasurementVersion((v) => v + 1);
     }, []);
     /**
-     * Start measuring
+     * Start measuring. For horizontal lists, width is the "size"
+     * axis the engine should track, so we tell MeasurementSystem
+     * to report height/width based on the resolved axis - this is
+     * wired through observeItem's axis param, set up by consumers
+     * (e.g. VirtualList) when they call observeItem directly, or
+     * defaults to 'height' here for plain startMeasuring use,
+     * preserving original vertical-only behavior exactly.
      */
     useEffect(() => {
         const container = containerRef.current;
+        const measurement = measurementRef.current;
         if (container) {
-            measurementRef.current.startMeasuring(container, handleItemMeasure);
+            measurement.startMeasuring(container, handleItemMeasure);
         }
         return () => {
-            measurementRef.current.stopMeasuring();
+            measurement.stopMeasuring();
         };
     }, [handleItemMeasure]);
     /**
      * Scroll to item
      */
     const scrollToItem = useCallback((index, alignment = 'start') => {
-        const offset = engineRef.current.getScrollOffsetForIndex(index, containerHeight, alignment);
-        if (containerRef.current) {
-            containerRef.current.scrollTop =
-                offset;
+        if (!resolvedViewportSize) {
+            return;
         }
-    }, [containerHeight]);
+        const offset = engineRef.current.getScrollOffsetForIndex(index, resolvedViewportSize, alignment);
+        const container = containerRef.current;
+        if (!container) {
+            return;
+        }
+        if (isHorizontal) {
+            container.scrollLeft = offset;
+        }
+        else {
+            container.scrollTop = offset;
+        }
+    }, [resolvedViewportSize, isHorizontal]);
     /**
-     * Scroll to offset
+     * Scroll to offset (imperative). Also updates internal state
+     * immediately so consumers calling this don't see a stale
+     * scrollOffset until the next native scroll event fires.
      */
     const scrollToOffset = useCallback((offset) => {
-        if (containerRef.current) {
-            containerRef.current.scrollTop =
-                offset;
+        const container = containerRef.current;
+        if (container) {
+            if (isHorizontal) {
+                container.scrollLeft = offset;
+            }
+            else {
+                container.scrollTop = offset;
+            }
         }
+        lastScrollOffsetRef.current = offset;
+        setScrollOffsetState(offset);
+    }, [isHorizontal]);
+    /**
+     * Public setScrollOffset: state-only, mirrors original API
+     * exactly. Does not move the real scroll container - use
+     * scrollToOffset for that.
+     */
+    const setScrollOffset = useCallback((offset) => {
+        lastScrollOffsetRef.current = offset;
+        setScrollOffsetState(offset);
     }, []);
     /**
      * Get item style
      */
     const getItemStyle = useCallback((index, size) => {
         const offset = engineRef.current.getItemOffset(index);
-        const isStickyItem = stickyIndices.includes(index);
+        const isStickyItem = stickyIndicesRef.current.includes(index);
+        const base = {
+            position: isStickyItem ? 'sticky' : 'absolute',
+            zIndex: isStickyItem ? 10 : 0,
+        };
+        if (isHorizontal) {
+            return {
+                ...base,
+                top: 0,
+                left: isStickyItem ? 0 : offset,
+                height: resolvedCrossAxisSize
+                    ? resolvedCrossAxisSize
+                    : '100%',
+                width: size,
+            };
+        }
         return {
-            position: isStickyItem
-                ? 'sticky'
-                : 'absolute',
-            top: isStickyItem
-                ? 0
-                : offset,
+            ...base,
+            top: isStickyItem ? 0 : offset,
             left: 0,
             width: '100%',
             height: size,
-            zIndex: isStickyItem
-                ? 10
-                : 0,
         };
-    }, [stickyIndices]);
+    }, [isHorizontal, resolvedCrossAxisSize]);
+    /**
+     * Resolve a stable key for a given index
+     */
+    const getItemKeyForIndex = useCallback((index) => {
+        if (getItemKey) {
+            const item = items[index];
+            if (item !== undefined) {
+                return getItemKey(index, item);
+            }
+        }
+        return index;
+    }, [getItemKey, items]);
+    /**
+     * Invalidate cached measurements from a given index onward.
+     * Backed by VirtualizationEngine.invalidateFrom().
+     */
+    const recalculate = useCallback((fromIndex) => {
+        engineRef.current.invalidateFrom(fromIndex);
+        setMeasurementVersion((v) => v + 1);
+    }, []);
     /**
      * Cleanup
      */
@@ -203,17 +324,22 @@ export function useVirtualList(params) {
             if (scrollTimeoutRef.current) {
                 clearTimeout(scrollTimeoutRef.current);
             }
-            measurementRef.current.destroy();
+            measurementRef.current?.destroy();
         };
     }, []);
     /**
-     * Total size
+     * Total size - recomputed whenever item count, viewport, or
+     * measurements change (fixes the original bug where this was
+     * read once per render with no dependency tracking).
      */
-    const totalSize = engineRef.current.getTotalSize();
+    const totalSize = useMemo(() => engineRef.current.getTotalSize(), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [items.length, measurementVersion, resolvedViewportSize]);
     return {
         virtualItems,
         isScrolling,
         scrollOffset,
+        scrollDirection,
         totalSize,
         scrollToItem,
         scrollToOffset,
@@ -221,6 +347,8 @@ export function useVirtualList(params) {
         containerRef,
         innerRef,
         getItemStyle,
+        recalculate,
+        getItemKeyForIndex,
     };
 }
 //# sourceMappingURL=useVirtualList.js.map