clear-virtualizer 0.1.0 → 0.1.2

package/README.md

@@ -1,3 +1,5 @@
+[![npm version](https://img.shields.io/npm/v/clear-virtualizer.svg)](https://www.npmjs.com/package/clear-virtualizer)
+
 # clear-virtualizer
 
 One hook for vertical virtualized lists and tables with dynamic row heights. Rows are measured automatically via `ResizeObserver` — no manual measuring, no fixed heights. Works for an unlimited number of rows.
@@ -18,25 +20,25 @@ import { useVirtualizer, type Options, type ScrollAlign, type VirtualItem } from
 
 ```ts
 const { virtualItems, scrollHeight, scrollRef, getMeasureRef, scrollToIndex } = useVirtualizer({
-  count: 100000,
-  estimateSize: () => 44,
-  overscan: 10,
+	count: 100000,
+	estimateSize: () => 44,
+	overscan: 10,
 });
 ```
 
-| Option         | Type                                       | Description                                              |
-| -------------- |--------------------------------------------| -------------------------------------------------------- |
-| `count`        | `number`                                   | Total number of rows                                     |
+| Option         | Type                                       | Description                                                |
+| -------------- | ------------------------------------------ | ---------------------------------------------------------- |
+| `count`        | `number`                                   | Total number of rows                                       |
 | `estimateSize` | `((index: number) => number) \| undefined` | Approximate row height in px, used until a row is measured |
-| `overscan`     | `number \| undefined`                      | Extra rows rendered above/below the viewport (default: 3) |
+| `overscan`     | `number \| undefined`                      | Extra rows rendered above/below the viewport (default: 3)  |
 
-| Return value    | Type                                          | Description                                             |
-| --------------- | --------------------------------------------- | ------------------------------------------------------- |
-| `virtualItems`  | `VirtualItem[]`                               | Rows to render: `{ index, start, size, end }` (px)      |
-| `scrollHeight`  | `number`                                      | Total scrollable height (px)                            |
-| `scrollRef`     | `(el: HTMLElement \| null) => void`           | Callback ref — attach to the scroll container           |
-| `getMeasureRef` | `(index: number) => (el: HTMLElement \| null) => void` | Attach the returned ref to each row for measuring |
-| `scrollToIndex` | `(index: number, options?: { align?: ScrollAlign }) => void` | Scroll to a row |
+| Return value    | Type                                                         | Description                                        |
+| --------------- | ------------------------------------------------------------ | -------------------------------------------------- |
+| `virtualItems`  | `VirtualItem[]`                                              | Rows to render: `{ index, start, size, end }` (px) |
+| `scrollHeight`  | `number`                                                     | Total scrollable height (px)                       |
+| `scrollRef`     | `(el: HTMLElement \| null) => void`                          | Callback ref — attach to the scroll container      |
+| `getMeasureRef` | `(index: number) => (el: HTMLElement \| null) => void`       | Attach the returned ref to each row for measuring  |
+| `scrollToIndex` | `(index: number, options?: { align?: ScrollAlign }) => void` | Scroll to a row                                    |
 
 Do not set a fixed `height` on rows — let them size naturally so `getMeasureRef` measures the real height. Position rows with `transform: translateY(...)`.
 
@@ -131,9 +133,7 @@ const columns = [
 	columnHelper.display({
 		id: 'expand',
 		size: 40,
-		cell: ({ row }) => (
-			<button onClick={() => row.toggleExpanded()}>{row.getIsExpanded() ? '▼' : '▶'}</button>
-		),
+		cell: ({ row }) => <button onClick={() => row.toggleExpanded()}>{row.getIsExpanded() ? '▼' : '▶'}</button>,
 	}),
 	columnHelper.accessor('id', { header: 'ID', size: 60 }),
 	columnHelper.accessor('name', { header: 'Name', size: 150 }),
@@ -220,11 +220,11 @@ scrollToIndex(34567, { align: 'center' });
 scrollToIndex(34567, { align: 'end' });
 ```
 
-| `align`  | Positions the row...              |
-| -------- | --------------------------------- |
+| `align`  | Positions the row...                 |
+| -------- | ------------------------------------ |
 | `start`  | At the top of the viewport (default) |
-| `center` | In the middle of the viewport     |
-| `end`    | At the bottom of the viewport     |
+| `center` | In the middle of the viewport        |
+| `end`    | At the bottom of the viewport        |
 
 If the row is far away and its neighbors were never measured, the hook first jumps to the estimated position, measures the rows around the target, and corrects the position. A manual scroll during that correction cancels it and hands control back to the user.
 
@@ -232,11 +232,14 @@ If the row is far away and its neighbors were never measured, the hook first jum
 
 `estimateSize` is only a starting guess until real measurements arrive. The closer it is to reality, the less rows visually shift on fast scroll through unmeasured regions: underestimated rows overlap until measured, overestimated ones leave temporary gaps. Pass a value near your average row height.
 
+## SSR
+
+Server-side rendering is supported: on the server the hook renders an empty container (`virtualItems: []`, `scrollHeight: 0`) without touching browser APIs. Rows appear after hydration once the scroll container is attached and `ResizeObserver` reports real heights.
+
 ## Limitations
 
-- Vertical scrolling only — no horizontal virtualization, no sticky columns.
-- The internal offset tree keeps one `float64` per row (~8 MB per million rows).
-- Server-side rendering is not covered by tests.
+-   Vertical scrolling only — no horizontal virtualization, no sticky columns.
+-   The internal offset tree keeps one `float64` per row (~8 MB per million rows).
 
 ## License
 

package/lib/index.cjs

@@ -204,6 +204,8 @@ function useVirtualizer({ count, estimateSize, overscan = DEFAULT_OVERSCAN }) {
       existing.observer.disconnect();
       observersRef.current.delete(index);
     }
+    if (typeof ResizeObserver === "undefined")
+      return;
     const observer = new ResizeObserver(([entry]) => {
       const height = entry?.borderBoxSize[0]?.blockSize;
       if (height == null || !fenwickRef.current)
@@ -371,6 +373,21 @@ function useVirtualizer({ count, estimateSize, overscan = DEFAULT_OVERSCAN }) {
     },
     [handleScroll]
   );
+  react.useEffect(
+    () => () => {
+      if (rafRef.current !== null)
+        cancelAnimationFrame(rafRef.current);
+      if (tickRafRef.current !== null)
+        cancelAnimationFrame(tickRafRef.current);
+      observersRef.current.forEach((entry) => entry.observer.disconnect());
+      observersRef.current.clear();
+      containerObserverRef.current?.disconnect();
+      containerObserverRef.current = null;
+      scrollElementRef.current?.removeEventListener("scroll", handleScroll);
+      refCacheRef.current.clear();
+    },
+    [handleScroll]
+  );
   const { virtualItems, scrollHeight } = react.useMemo(
     () => computeItems(scrollOffset.value),
     [computeItems, scrollOffset]

package/lib/index.js

@@ -202,6 +202,8 @@ function useVirtualizer({ count, estimateSize, overscan = DEFAULT_OVERSCAN }) {
       existing.observer.disconnect();
       observersRef.current.delete(index);
     }
+    if (typeof ResizeObserver === "undefined")
+      return;
     const observer = new ResizeObserver(([entry]) => {
       const height = entry?.borderBoxSize[0]?.blockSize;
       if (height == null || !fenwickRef.current)
@@ -369,6 +371,21 @@ function useVirtualizer({ count, estimateSize, overscan = DEFAULT_OVERSCAN }) {
     },
     [handleScroll]
   );
+  useEffect(
+    () => () => {
+      if (rafRef.current !== null)
+        cancelAnimationFrame(rafRef.current);
+      if (tickRafRef.current !== null)
+        cancelAnimationFrame(tickRafRef.current);
+      observersRef.current.forEach((entry) => entry.observer.disconnect());
+      observersRef.current.clear();
+      containerObserverRef.current?.disconnect();
+      containerObserverRef.current = null;
+      scrollElementRef.current?.removeEventListener("scroll", handleScroll);
+      refCacheRef.current.clear();
+    },
+    [handleScroll]
+  );
   const { virtualItems, scrollHeight } = useMemo(
     () => computeItems(scrollOffset.value),
     [computeItems, scrollOffset]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clear-virtualizer",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A lightweight React hook for virtualized lists and tables with dynamic row heights, measured automatically",
   "type": "module",
   "main": "./lib/index.cjs",
@@ -85,7 +85,6 @@
     "eslint-plugin-react-hooks": "^4.6.0",
     "eslint-plugin-react-refresh": "^0.4.3",
     "jsdom": "^30.0.1",
-    "lorem-ipsum": "^2.0.8",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "typescript": "^5.0.2",