react-virtual-renderer 1.1.3 → 1.1.5

package/dist/core/VirtualizationEngine.js

@@ -1,10 +1,26 @@
+import { FenwickTree } from './FenwickTree';
+/**
+ * Core offset/range math shared by VirtualList and VirtualGrid.
+ *
+ * PERFORMANCE: previously this held a plain prefix-sum array and a
+ * `dirty` flag, rebuilding the WHOLE array (O(n)) the next time
+ * anything was read after any single item's size changed. Every read
+ * (getItemOffset, getTotalSize, the binary search for visible range)
+ * paid that O(n) cost whenever a measurement had landed since the last
+ * read - which, for a dynamic-height list, is essentially every scroll
+ * frame.
+ *
+ * This version is backed by a FenwickTree (see FenwickTree.ts). There
+ * is no dirty flag and no rebuild: every operation below is O(log n),
+ * full stop, regardless of how many items have been re-measured.
+ */
 export class VirtualizationEngine {
     constructor(estimatedItemSize = 35) {
-        Object.defineProperty(this, "itemSizeMap", {
+        Object.defineProperty(this, "tree", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: {}
+            value: void 0
         });
         Object.defineProperty(this, "estimatedItemSize", {
             enumerable: true,
@@ -18,117 +34,64 @@ export class VirtualizationEngine {
             writable: true,
             value: 0
         });
-        // prefix sum cache
-        Object.defineProperty(this, "prefix", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: [0]
-        });
-        Object.defineProperty(this, "dirty", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: true
-        });
         this.estimatedItemSize = estimatedItemSize;
+        this.tree = new FenwickTree(0);
     }
     setItemCount(count) {
-        /**
-         * FIX: previously this unconditionally set `dirty = true`
-         * on every call, even when the count hadn't changed. Since
-         * getVisibleRange() calls setItemCount() on every single
-         * invocation (i.e. every scroll frame), that forced a full
-         * O(n) prefix-sum rebuild every frame regardless of whether
-         * anything actually changed.
-         *
-         * Now we only mark dirty when the count actually differs.
-         * Measurement updates still mark dirty via recordItemSize(),
-         * so cache invalidation on real changes is unaffected.
-         */
-        if (this.itemCount === count) {
+        if (this.itemCount === count)
             return;
-        }
+        this.tree.resize(count, this.estimatedItemSize);
         this.itemCount = count;
-        this.dirty = true;
     }
     recordItemSize(index, size) {
-        if (this.itemSizeMap[index] === size)
+        if (index < 0 || index >= this.itemCount)
             return;
-        this.itemSizeMap[index] = size;
-        this.dirty = true;
+        this.tree.update(index, size);
     }
     /**
-     * NEW (additive): Invalidate cached measurements from `fromIndex`
-     * onward (inclusive), or all measurements if `fromIndex` is
-     * omitted. Affected indices fall back to `estimatedItemSize`
-     * until they are re-measured and recordItemSize() is called
-     * again for them.
+     * Invalidate cached measurements from `fromIndex` onward
+     * (inclusive), or everything if omitted. Affected indices fall
+     * back to `estimatedItemSize` until re-measured.
      *
-     * Does not remove items below fromIndex, and does not touch
-     * itemCount. Safe to call at any time; it only marks the
-     * prefix-sum cache dirty so the next read rebuilds it.
+     * Each reset index is a single O(log n) point update - so
+     * invalidating a suffix of k items is O(k log n), not a full
+     * array rebuild. A full invalidate (no fromIndex) is the one
+     * intentionally O(n) path in this class, reserved for "the whole
+     * dataset changed" situations, not the scroll hot path.
      */
     invalidateFrom(fromIndex) {
         if (fromIndex === undefined) {
-            this.itemSizeMap = {};
-            this.dirty = true;
+            this.tree.resetAll(this.estimatedItemSize);
             return;
         }
-        if (fromIndex < 0) {
-            fromIndex = 0;
-        }
-        for (const key of Object.keys(this.itemSizeMap)) {
-            const index = Number(key);
-            if (index >= fromIndex) {
-                delete this.itemSizeMap[index];
-            }
-        }
-        this.dirty = true;
-    }
-    rebuildPrefix() {
-        let sum = 0;
-        this.prefix = [0];
-        for (let i = 0; i < this.itemCount; i++) {
-            sum += this.itemSizeMap[i] ?? this.estimatedItemSize;
-            this.prefix[i + 1] = sum;
+        const start = Math.max(0, fromIndex);
+        for (let i = start; i < this.itemCount; i++) {
+            this.tree.update(i, this.estimatedItemSize);
         }
-        this.dirty = false;
     }
     getItemSize(index) {
-        return this.itemSizeMap[index] ?? this.estimatedItemSize;
+        if (index < 0 || index >= this.itemCount)
+            return this.estimatedItemSize;
+        return this.tree.getValue(index);
     }
     getItemOffset(index) {
-        if (this.dirty)
-            this.rebuildPrefix();
-        return this.prefix[index] ?? 0;
+        return this.tree.prefixSum(Math.max(0, index));
     }
     getTotalSize() {
-        if (this.dirty)
-            this.rebuildPrefix();
-        return this.prefix[this.itemCount] || 0;
-    }
-    binarySearch(offset) {
-        if (this.dirty)
-            this.rebuildPrefix();
-        let low = 0;
-        let high = this.itemCount - 1;
-        while (low <= high) {
-            const mid = (low + high) >> 1;
-            const value = this.prefix[mid];
-            if (value === offset)
-                return mid;
-            if (value < offset)
-                low = mid + 1;
-            else
-                high = mid - 1;
-        }
-        return Math.max(0, low - 1);
+        return this.tree.total();
     }
     getVisibleRange(scrollOffset, containerSize, itemCount, overscan = 5) {
         this.setItemCount(itemCount);
-        const start = this.binarySearch(scrollOffset);
-        const end = this.binarySearch(scrollOffset + containerSize);
+        if (itemCount === 0) {
+            return {
+                startIndex: 0,
+                endIndex: -1,
+                overscanStartIndex: 0,
+                overscanEndIndex: -1,
+            };
+        }
+        const start = this.tree.findIndexAtOffset(scrollOffset);
+        const end = this.tree.findIndexAtOffset(scrollOffset + containerSize);
         return {
             startIndex: Math.max(0, start - overscan),
             endIndex: Math.min(itemCount - 1, end + overscan),

package/dist/core/VirtualizationEngine.js.map

@@ -1 +1 @@
-{"version":3,"file":"VirtualizationEngine.js","sourceRoot":"","sources":["../../src/core/VirtualizationEngine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"VirtualizationEngine.js","sourceRoot":"","sources":["../../src/core/VirtualizationEngine.ts"],"names":[],"mappings":"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"}

package/dist/examples/DynamicHeightLists.d.ts

@@ -0,0 +1,2 @@
+export default function DynamicHeightListExample(): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=DynamicHeightLists.d.ts.map

package/dist/examples/DynamicHeightLists.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DynamicHeightLists.d.ts","sourceRoot":"","sources":["../../src/examples/DynamicHeightLists.tsx"],"names":[],"mappings":"AAqDA,MAAM,CAAC,OAAO,UAAU,wBAAwB,4CAyD/C"}

package/dist/examples/DynamicHeightLists.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from "react";
+import { VirtualList } from "../components/VirtualList";
+async function fetchRealComments(signal) {
+    const res = await fetch("https://jsonplaceholder.typicode.com/comments", { signal });
+    if (!res.ok)
+        throw new Error(`Failed to fetch comments: ${res.status}`);
+    return res.json();
+}
+function tileToTargetSize(source, targetCount) {
+    return Array.from({ length: targetCount }, (_, i) => {
+        const src = source[i % source.length];
+        return { id: i, author: src.email, body: src.body };
+    });
+}
+const TARGET_COUNT = 50000;
+export default function DynamicHeightListExample() {
+    const [comments, setComments] = React.useState(null);
+    const [error, setError] = React.useState(null);
+    const listRef = React.useRef(null);
+    React.useEffect(() => {
+        const controller = new AbortController();
+        fetchRealComments(controller.signal)
+            .then((raw) => setComments(tileToTargetSize(raw, TARGET_COUNT)))
+            .catch((err) => {
+            if (!controller.signal.aborted) {
+                setError(err instanceof Error ? err.message : "Failed to load comments");
+            }
+        });
+        return () => controller.abort();
+    }, []);
+    if (error) {
+        return _jsx("div", { style: { padding: 16, color: "#b91c1c" }, children: error });
+    }
+    if (!comments) {
+        return _jsx("div", { style: { padding: 16, color: "#888" }, children: "Loading real comment data\u2026" });
+    }
+    return (_jsxs("div", { children: [_jsx("div", { style: { marginBottom: 8 }, children: _jsx("button", { onClick: () => {
+                        listRef.current?.scrollTo({ top: 500000, behavior: "smooth" });
+                    }, children: "Jump deep into the list (tests offset math on unmeasured items)" }) }), _jsx(VirtualList, { ref: listRef, items: comments, height: 600, width: "100%", estimatedItemSize: 90, overscan: 6, itemKey: (_, item) => item.id, itemStyle: { borderBottom: "1px solid #eee", padding: "8px 12px" }, renderItem: ({ item }) => (_jsxs("div", { children: [_jsx("strong", { children: item.author }), _jsx("p", { style: { margin: "4px 0 0" }, children: item.body })] })) })] }));
+}
+//# sourceMappingURL=DynamicHeightLists.js.map

package/dist/examples/DynamicHeightLists.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DynamicHeightLists.js","sourceRoot":"","sources":["../../src/examples/DynamicHeightLists.tsx"],"names":[],"mappings":"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"}

package/dist/examples/FixedGrid.d.ts

@@ -0,0 +1,2 @@
+export default function FixedGridExample(): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=FixedGrid.d.ts.map

package/dist/examples/FixedGrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FixedGrid.d.ts","sourceRoot":"","sources":["../../src/examples/FixedGrid.tsx"],"names":[],"mappings":"AAoDA,MAAM,CAAC,OAAO,UAAU,gBAAgB,4CAwDvC"}

package/dist/examples/FixedGrid.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from "react";
+import { VirtualGrid } from "../components/VirtualGrid";
+async function fetchRealProducts(signal) {
+    const res = await fetch("https://dummyjson.com/products?limit=194", { signal });
+    if (!res.ok)
+        throw new Error(`Failed to fetch products: ${res.status}`);
+    const data = await res.json();
+    return data.products;
+}
+function tileToTargetSize(source, targetCount) {
+    return Array.from({ length: targetCount }, (_, i) => {
+        const src = source[i % source.length];
+        return { id: i, name: src.title, price: src.price, thumbnail: src.thumbnail };
+    });
+}
+const TARGET_COUNT = 200000;
+export default function FixedGridExample() {
+    const [products, setProducts] = React.useState(null);
+    const [error, setError] = React.useState(null);
+    React.useEffect(() => {
+        const controller = new AbortController();
+        fetchRealProducts(controller.signal)
+            .then((raw) => setProducts(tileToTargetSize(raw, TARGET_COUNT)))
+            .catch((err) => {
+            if (!controller.signal.aborted) {
+                setError(err instanceof Error ? err.message : "Failed to load products");
+            }
+        });
+        return () => controller.abort();
+    }, []);
+    if (error) {
+        return _jsx("div", { style: { padding: 16, color: "#b91c1c" }, children: error });
+    }
+    if (!products) {
+        return _jsx("div", { style: { padding: 16, color: "#888" }, children: "Loading real product data\u2026" });
+    }
+    return (_jsx(VirtualGrid, { items: products, layout: "grid", columnCount: "auto", rowHeight: 220, gap: 16, height: 700, width: "100%", overscan: 8, itemKey: (_, item) => item.id, itemStyle: { borderRadius: 8, overflow: "hidden", border: "1px solid #eee" }, renderItem: ({ item }) => (_jsxs("div", { style: { display: "flex", flexDirection: "column", height: "100%" }, children: [_jsx("img", { src: item.thumbnail, alt: item.name, loading: "lazy", style: { flex: 1, width: "100%", objectFit: "cover" } }), _jsxs("div", { style: { padding: 8 }, children: [_jsx("div", { style: { fontWeight: 600, whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }, children: item.name }), _jsxs("div", { style: { color: "#555" }, children: ["$", item.price.toFixed(2)] })] })] })) }));
+}
+//# sourceMappingURL=FixedGrid.js.map

package/dist/examples/FixedGrid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FixedGrid.js","sourceRoot":"","sources":["../../src/examples/FixedGrid.tsx"],"names":[],"mappings":"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"}

package/dist/examples/GroupedContactList.d.ts

@@ -0,0 +1,2 @@
+export default function GroupedContactListExample(): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=GroupedContactList.d.ts.map

package/dist/examples/GroupedContactList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GroupedContactList.d.ts","sourceRoot":"","sources":["../../src/examples/GroupedContactList.tsx"],"names":[],"mappings":"AAcA,MAAM,CAAC,OAAO,UAAU,yBAAyB,4CAkChD"}

package/dist/examples/GroupedContactList.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// examples/GroupedContactList.tsx
+import React from 'react';
+import { VirtualList } from '../components/VirtualList';
+import { flattenGroups } from '../core/GroupedListEngine';
+const FIRST_NAMES = [
+    'Amara', 'Beatrix', 'Cyrus', 'Dahlia', 'Elias', 'Farah', 'Gideon', 'Harlow',
+    'Ines', 'Jasper', 'Kira', 'Lior', 'Marisol', 'Noor', 'Otis', 'Priya',
+    'Quinn', 'Rosalind', 'Soren', 'Talia', 'Uma', 'Vance', 'Willa', 'Xiomara',
+    'Yusuf', 'Zara',
+];
+export default function GroupedContactListExample() {
+    const contacts = React.useMemo(() => Array.from({ length: 5000 }, (_, i) => {
+        const first = FIRST_NAMES[i % FIRST_NAMES.length];
+        return { id: i, name: `${first} ${String(i).padStart(4, '0')}` };
+    }).sort((a, b) => a.name.localeCompare(b.name)), []);
+    const { rows, stickyIndices } = React.useMemo(() => flattenGroups({ items: contacts, getGroupKey: (c) => c.name[0].toUpperCase() }), [contacts]);
+    return (_jsx(VirtualList, { items: rows, height: 600, width: "100%", estimatedItemSize: 44, stickyIndices: stickyIndices, itemKey: (_, row) => (row.type === 'header' ? `h-${row.groupKey}` : row.item.id), renderItem: ({ item: row }) => row.type === 'header' ? (_jsx("div", { style: { background: '#f8f9fa', fontWeight: 700, padding: '6px 12px' }, children: row.groupKey })) : (_jsx("div", { style: { padding: '10px 12px' }, children: row.item.name })) }));
+}
+//# sourceMappingURL=GroupedContactList.js.map

package/dist/examples/GroupedContactList.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GroupedContactList.js","sourceRoot":"","sources":["../../src/examples/GroupedContactList.tsx"],"names":[],"mappings":";AAAA,kCAAkC;AAClC,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAI1D,MAAM,WAAW,GAAG;IAChB,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ;IAC3E,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO;IACpE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS;IACzE,OAAO,EAAE,MAAM;CAClB,CAAC;AAEF,MAAM,CAAC,OAAO,UAAU,yBAAyB;IAC7C,MAAM,QAAQ,GAAc,KAAK,CAAC,OAAO,CACrC,GAAG,EAAE,CACD,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAClC,MAAM,KAAK,GAAG,WAAW,CAAC,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;QAClD,OAAO,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,GAAG,KAAK,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC;IACrE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,EACnD,EAAE,CACL,CAAC;IAEF,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,KAAK,CAAC,OAAO,CACzC,GAAG,EAAE,CAAC,aAAa,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,EACrF,CAAC,QAAQ,CAAC,CACb,CAAC;IAEF,OAAO,CACH,KAAC,WAAW,IACR,KAAK,EAAE,IAAI,EACX,MAAM,EAAE,GAAG,EACX,KAAK,EAAC,MAAM,EACZ,iBAAiB,EAAE,EAAE,EACrB,aAAa,EAAE,aAAa,EAC5B,OAAO,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,IAAK,CAAC,EAAE,CAAC,EACjF,UAAU,EAAE,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,CAC1B,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CACpB,cAAK,KAAK,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,YACtE,GAAG,CAAC,QAAQ,GACX,CACT,CAAC,CAAC,CAAC,CACA,cAAK,KAAK,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,YAAG,GAAG,CAAC,IAAK,CAAC,IAAI,GAAO,CAC/D,GAEP,CACL,CAAC;AACN,CAAC"}

package/dist/examples/InfiniteScrollLists.d.ts

@@ -0,0 +1,2 @@
+export default function InfiniteScrollExample(): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=InfiniteScrollLists.d.ts.map

package/dist/examples/InfiniteScrollLists.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InfiniteScrollLists.d.ts","sourceRoot":"","sources":["../../src/examples/InfiniteScrollLists.tsx"],"names":[],"mappings":"AA6EA,MAAM,CAAC,OAAO,UAAU,qBAAqB,4CA4H5C"}

package/dist/examples/InfiniteScrollLists.js

@@ -0,0 +1,93 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import React from "react";
+import { VirtualList } from "../components/VirtualList";
+import { useInfiniteScroll } from "../hooks/useInfiniteScroll";
+const PAGE_SIZE = 20;
+async function fetchPostsPage(skip, signal) {
+    const res = await fetch(`https://dummyjson.com/posts?limit=${PAGE_SIZE}&skip=${skip}`, { signal });
+    if (!res.ok)
+        throw new Error(`Failed to fetch posts: ${res.status}`);
+    return res.json();
+}
+function normalizePost(raw) {
+    const reactions = typeof raw.reactions === "number"
+        ? { likes: raw.reactions, dislikes: 0 }
+        : raw.reactions;
+    return {
+        id: raw.id,
+        title: raw.title,
+        body: raw.body,
+        tags: raw.tags,
+        likes: reactions.likes,
+        dislikes: reactions.dislikes,
+        views: raw.views,
+    };
+}
+export default function InfiniteScrollExample() {
+    const [items, setItems] = React.useState([]);
+    const [total, setTotal] = React.useState(null);
+    const [isLoading, setIsLoading] = React.useState(false);
+    const [error, setError] = React.useState(null);
+    const containerRef = React.useRef(null);
+    const abortRef = React.useRef(null);
+    const hasMore = total === null || items.length < total;
+    const loadMore = React.useCallback(async () => {
+        if (total !== null && items.length >= total)
+            return;
+        const controller = new AbortController();
+        abortRef.current = controller;
+        setIsLoading(true);
+        setError(null);
+        try {
+            const data = await fetchPostsPage(items.length, controller.signal);
+            setItems((prev) => [...prev, ...data.posts.map(normalizePost)]);
+            setTotal(data.total);
+        }
+        catch (err) {
+            if (!controller.signal.aborted) {
+                setError(err instanceof Error ? err.message : "Failed to load more posts");
+            }
+        }
+        finally {
+            if (!controller.signal.aborted)
+                setIsLoading(false);
+        }
+    }, [items.length, total]);
+    React.useEffect(() => {
+        loadMore();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    React.useEffect(() => {
+        return () => {
+            abortRef.current?.abort();
+        };
+    }, []);
+    const { sentinelRef } = useInfiniteScroll({
+        onLoadMore: loadMore,
+        isLoading,
+        enabled: hasMore,
+        root: containerRef,
+        rootMargin: "400px",
+    });
+    return (_jsxs("div", { children: [error && (_jsxs("div", { style: { padding: 8, color: "#b91c1c", fontSize: 13 }, children: [error, " \u2014", " ", _jsx("button", { onClick: () => loadMore(), style: { textDecoration: "underline" }, children: "retry" })] })), _jsx(VirtualList, { ref: containerRef, items: items, height: 600, width: "100%", estimatedItemSize: 140, itemKey: (_, item) => item.id, itemStyle: {
+                    display: "flex",
+                    flexDirection: "column",
+                    gap: 6,
+                    padding: "14px 16px",
+                    borderBottom: "1px solid #eee",
+                }, renderItem: ({ item }) => (_jsxs(_Fragment, { children: [_jsx("div", { style: { fontWeight: 600, fontSize: 15 }, children: item.title }), _jsx("p", { style: { margin: 0, color: "#555", lineHeight: 1.5 }, children: item.body }), _jsx("div", { style: { display: "flex", gap: 6, flexWrap: "wrap", marginTop: 4 }, children: item.tags.map((tag) => (_jsxs("span", { style: {
+                                    fontSize: 12,
+                                    padding: "2px 8px",
+                                    borderRadius: 999,
+                                    background: "#f1f3f5",
+                                    color: "#495057",
+                                }, children: ["#", tag] }, tag))) }), _jsxs("div", { style: { display: "flex", gap: 16, fontSize: 12, color: "#888", marginTop: 4 }, children: [_jsxs("span", { children: ["\uD83D\uDC4D ", item.likes] }), _jsxs("span", { children: ["\uD83D\uDC4E ", item.dislikes] }), _jsxs("span", { children: ["\uD83D\uDC41 ", item.views.toLocaleString(), " views"] })] })] })), 
+                // sentinel is now ALWAYS mounted, independent of virtualization -
+                // this is the actual fix, not the renderItem branch above
+                footer: hasMore ? (_jsx("div", { ref: sentinelRef, style: { height: 1, width: "100%" } })) : null }), _jsx("div", { style: { textAlign: "center", padding: 12, color: "#888", fontSize: 13 }, children: isLoading
+                    ? "Loading more…"
+                    : hasMore
+                        ? `Loaded ${items.length} of ${total ?? "…"} posts`
+                        : `That's everything (${items.length} posts)` })] }));
+}
+//# sourceMappingURL=InfiniteScrollLists.js.map

package/dist/examples/InfiniteScrollLists.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InfiniteScrollLists.js","sourceRoot":"","sources":["../../src/examples/InfiniteScrollLists.tsx"],"names":[],"mappings":"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"}

package/dist/examples/MasonaryGrid.d.ts

@@ -0,0 +1,2 @@
+export default function MasonryGridExample(): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=MasonaryGrid.d.ts.map

package/dist/examples/MasonaryGrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MasonaryGrid.d.ts","sourceRoot":"","sources":["../../src/examples/MasonaryGrid.tsx"],"names":[],"mappings":"AAoDA,MAAM,CAAC,OAAO,UAAU,kBAAkB,4CAiDzC"}

package/dist/examples/MasonaryGrid.js

@@ -0,0 +1,36 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import React from "react";
+import { VirtualGrid } from "../components/VirtualGrid";
+/**
+ * Plain data generator - NOT a component or hook, so it must not call
+ * useState/useEffect/etc. (that was the bug in the previous version:
+ * a bare `[images] = useState(...)` inside a regular function violates
+ * the Rules of Hooks and silently breaks - hooks only run inside a
+ * component body or another hook).
+ */
+function makePhotos(startId, count) {
+    return Array.from({ length: count }, (_, i) => {
+        const id = startId + i;
+        // deterministic pseudo-random height per id, stable across re-renders -
+        // matches picsum's own {width}/{height} path so the requested image
+        // dimensions always equal the space we've reserved for it
+        const height = 220 + (id % 6) * 60;
+        return {
+            id,
+            url: `https://picsum.photos/500/${height}?random=${id}`,
+            title: `Beautiful Image ${id + 1}`,
+            height,
+        };
+    });
+}
+export default function MasonryGridExample() {
+    const [photos, setPhotos] = React.useState(() => makePhotos(0, 200));
+    const rowHeightForIndex = React.useCallback((index) => photos[index]?.height ?? 220, [photos]);
+    return (_jsxs("div", { children: [_jsx("div", { style: { marginBottom: 8, display: "flex", gap: 8, alignItems: "center" }, children: _jsxs("button", { onClick: () => setPhotos((prev) => [...prev, ...makePhotos(prev.length, 20)]), children: ["Load 20 more (", photos.length, " total) - watch this stay fast even at 50k+"] }) }), _jsx(VirtualGrid, { items: photos, layout: "masonry", columnCount: 5, rowHeight: rowHeightForIndex, gap: 12, height: 700, width: "100%", overscan: 6, itemKey: (_, item) => item.id, itemStyle: { borderRadius: 8, overflow: "hidden", background: "#eee" }, renderItem: ({ item }) => (_jsx("img", { src: item.url, alt: item.title, loading: "lazy", width: 500, height: item.height, style: {
+                        width: "100%",
+                        height: "100%",
+                        objectFit: "cover",
+                        display: "block",
+                    } })) })] }));
+}
+//# sourceMappingURL=MasonaryGrid.js.map

package/dist/examples/MasonaryGrid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MasonaryGrid.js","sourceRoot":"","sources":["../../src/examples/MasonaryGrid.tsx"],"names":[],"mappings":";AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AA4BxD;;;;;;GAMG;AACH,SAAS,UAAU,CAAC,OAAe,EAAE,KAAa;IAC9C,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAC1C,MAAM,EAAE,GAAG,OAAO,GAAG,CAAC,CAAC;QACvB,wEAAwE;QACxE,oEAAoE;QACpE,0DAA0D;QAC1D,MAAM,MAAM,GAAG,GAAG,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;QACnC,OAAO;YACH,EAAE;YACF,GAAG,EAAE,6BAA6B,MAAM,WAAW,EAAE,EAAE;YACvD,KAAK,EAAE,mBAAmB,EAAE,GAAG,CAAC,EAAE;YAClC,MAAM;SACT,CAAC;IACN,CAAC,CAAC,CAAC;AACP,CAAC;AAED,MAAM,CAAC,OAAO,UAAU,kBAAkB;IACtC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAgB,GAAG,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAEpF,MAAM,iBAAiB,GAAG,KAAK,CAAC,WAAW,CACvC,CAAC,KAAa,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,GAAG,EAC/C,CAAC,MAAM,CAAC,CACX,CAAC;IAEF,OAAO,CACH,0BACI,cAAK,KAAK,EAAE,EAAE,YAAY,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,UAAU,EAAE,QAAQ,EAAE,YAC1E,kBACI,OAAO,EAAE,GAAG,EAAE,CACV,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,+BAGnD,MAAM,CAAC,MAAM,mDACvB,GACP,EAEN,KAAC,WAAW,IACR,KAAK,EAAE,MAAM,EACb,MAAM,EAAC,SAAS,EAChB,WAAW,EAAE,CAAC,EACd,SAAS,EAAE,iBAAiB,EAC5B,GAAG,EAAE,EAAE,EACP,MAAM,EAAE,GAAG,EACX,KAAK,EAAC,MAAM,EACZ,QAAQ,EAAE,CAAC,EACX,OAAO,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,EAC7B,SAAS,EAAE,EAAE,YAAY,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,EACtE,UAAU,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CACtB,cACI,GAAG,EAAE,IAAI,CAAC,GAAG,EACb,GAAG,EAAE,IAAI,CAAC,KAAK,EACf,OAAO,EAAC,MAAM,EACd,KAAK,EAAE,GAAG,EACV,MAAM,EAAE,IAAI,CAAC,MAAM,EACnB,KAAK,EAAE;wBACH,KAAK,EAAE,MAAM;wBACb,MAAM,EAAE,MAAM;wBACd,SAAS,EAAE,OAAO;wBAClB,OAAO,EAAE,OAAO;qBACnB,GACH,CACL,GACH,IACA,CACT,CAAC;AACN,CAAC"}

package/dist/examples/PerfHarness.d.ts

@@ -0,0 +1,2 @@
+export default function PerfHarnessExample(): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=PerfHarness.d.ts.map

package/dist/examples/PerfHarness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PerfHarness.d.ts","sourceRoot":"","sources":["../../src/examples/PerfHarness.tsx"],"names":[],"mappings":"AAkHA,MAAM,CAAC,OAAO,UAAU,kBAAkB,4CAmGzC"}