@pyreon/virtual 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Vit Bokisch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# @pyreon/virtual
+
+Pyreon adapter for TanStack Virtual. Efficient rendering of large lists with reactive `virtualItems`, `totalSize`, and `isScrolling` signals.
+
+## Install
+
+```bash
+bun add @pyreon/virtual @tanstack/virtual-core
+```
+
+## Quick Start
+
+```tsx
+import { signal } from "@pyreon/reactivity"
+import { useVirtualizer } from "@pyreon/virtual"
+
+function VirtualList() {
+  const parentRef = signal<HTMLElement | null>(null)
+  const items = Array.from({ length: 10000 }, (_, i) => `Item ${i + 1}`)
+
+  const { virtualItems, totalSize } = useVirtualizer(() => ({
+    count: items.length,
+    getScrollElement: () => parentRef(),
+    estimateSize: () => 40,
+    overscan: 5,
+  }))
+
+  return () => (
+    <div ref={(el) => parentRef.set(el)} style="height: 400px; overflow-y: auto;">
+      <div style={`height: ${totalSize()}px; position: relative;`}>
+        {virtualItems().map((row) => (
+          <div
+            key={row.key}
+            style={`position: absolute; top: 0; width: 100%; height: ${row.size}px; transform: translateY(${row.start}px);`}
+          >
+            {items[row.index]}
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}
+```
+
+## API
+
+### `useVirtualizer(options)`
+
+Create a reactive virtualizer for element-based scrolling. Options are passed as a function so reactive signals can be read inside, and the virtualizer updates automatically when they change.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `() => UseVirtualizerOptions` | Function returning virtualizer config |
+
+Options extend `VirtualizerOptions` from `@tanstack/virtual-core` with `observeElementRect`, `observeElementOffset`, and `scrollToFn` pre-filled (overridable).
+
+**Returns:** `UseVirtualizerResult` with:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `instance` | `Virtualizer` | The underlying TanStack Virtualizer instance |
+| `virtualItems` | `Signal<VirtualItem[]>` | Currently visible virtual items |
+| `totalSize` | `Signal<number>` | Total scrollable size in pixels |
+| `isScrolling` | `Signal<boolean>` | Whether the user is currently scrolling |
+
+```ts
+const parentRef = signal<HTMLDivElement | null>(null)
+const count = signal(1000)
+
+const { virtualItems, totalSize, isScrolling, instance } = useVirtualizer(() => ({
+  count: count(),
+  getScrollElement: () => parentRef(),
+  estimateSize: () => 35,
+  overscan: 5,
+}))
+
+// Scroll programmatically:
+instance.scrollToIndex(500)
+```
+
+### `useWindowVirtualizer(options)`
+
+Create a reactive virtualizer for window-based scrolling. The scroll element is automatically set to `window`. SSR-safe — checks for `window` and `document` availability.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `() => UseWindowVirtualizerOptions` | Function returning config (no `getScrollElement` needed) |
+
+**Returns:** `UseWindowVirtualizerResult` — same shape as `UseVirtualizerResult` but typed with `Window` as the scroll element.
+
+```tsx
+function WindowList() {
+  const items = Array.from({ length: 50000 }, (_, i) => `Row ${i}`)
+
+  const { virtualItems, totalSize } = useWindowVirtualizer(() => ({
+    count: items.length,
+    estimateSize: () => 40,
+  }))
+
+  return () => (
+    <div style={`height: ${totalSize()}px; position: relative;`}>
+      {virtualItems().map((row) => (
+        <div
+          key={row.key}
+          style={`position: absolute; top: 0; width: 100%; height: ${row.size}px; transform: translateY(${row.start}px);`}
+        >
+          {items[row.index]}
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+## Patterns
+
+### Dynamic Item Sizes
+
+Use `measureElement` for variable-height items that are measured after render.
+
+```tsx
+import { measureElement } from "@pyreon/virtual"
+
+const { virtualItems, totalSize, instance } = useVirtualizer(() => ({
+  count: items.length,
+  getScrollElement: () => parentRef(),
+  estimateSize: () => 50,
+  measureElement,
+}))
+
+// In render, set the ref on each item:
+virtualItems().map((row) => (
+  <div
+    key={row.key}
+    ref={(el) => instance.measureElement(el)}
+    data-index={row.index}
+  >
+    {items[row.index]}
+  </div>
+))
+```
+
+### Horizontal Lists
+
+Set the `horizontal` option for horizontal virtualization.
+
+```ts
+const { virtualItems, totalSize } = useVirtualizer(() => ({
+  count: columns.length,
+  getScrollElement: () => parentRef(),
+  estimateSize: () => 120,
+  horizontal: true,
+}))
+```
+
+### Reactive Count
+
+Since options are a function, changing the count signal re-calculates virtual items automatically.
+
+```ts
+const filteredItems = signal(allItems)
+const { virtualItems } = useVirtualizer(() => ({
+  count: filteredItems().length,
+  getScrollElement: () => parentRef(),
+  estimateSize: () => 40,
+}))
+
+// Updating filteredItems triggers recalculation
+filteredItems.set(allItems.filter(i => i.includes(search())))
+```
+
+## Re-exports from `@tanstack/virtual-core`
+
+**Runtime:** `defaultKeyExtractor`, `defaultRangeExtractor`, `observeElementOffset`, `observeElementRect`, `observeWindowOffset`, `observeWindowRect`, `elementScroll`, `windowScroll`, `measureElement`, `Virtualizer`
+
+**Types:** `VirtualizerOptions`, `VirtualItem`, `Range`, `Rect`, `ScrollToOptions`
+
+## Gotchas
+
+- Options must be a function `() => opts` for reactive tracking. The virtualizer re-calculates when signals read inside the function change.
+- The `instance` is the raw TanStack Virtualizer — use it for imperative methods like `scrollToIndex()` and `scrollToOffset()`.
+- `virtualItems`, `totalSize`, and `isScrolling` are Pyreon signals updated via `batch()` for efficient reactive notifications.
+- The virtualizer's DOM observers are mounted via `onMount` and cleaned up via `onUnmount`. The component must be mounted for scroll observation to work.
+- `useWindowVirtualizer` checks for `window` availability and provides a safe fallback for SSR.