@octanejs/tanstack-virtual 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+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,81 @@
+# @octanejs/tanstack-virtual
+
+[TanStack Virtual](https://tanstack.com/virtual) for the [octane](https://github.com/octanejs/octane) UI framework.
+
+TanStack Virtual separates a framework-agnostic core (`@tanstack/virtual-core`:
+the `Virtualizer` + scroll/rect observers + all windowing math) from a small
+React adapter (`useVirtualizer`, `useWindowVirtualizer`). This package reuses
+the core unchanged (re-exported verbatim) and transcribes only the adapter onto
+octane's hooks, preserving upstream's exact shape — a force-update reducer
+wired into the instance's `onChange` (`flushSync` for sync scroll notifies), a
+create-once `Virtualizer`, options re-composed every render, and the
+`_didMount`/`_willUpdate` layout-effect lifecycle. The public surface matches
+`@tanstack/react-virtual` 1:1 — existing code works by changing the import.
+
+```tsx
+// before
+import { useVirtualizer } from '@tanstack/react-virtual';
+// after
+import { useVirtualizer } from '@octanejs/tanstack-virtual';
+
+function List() @{
+  const parentRef = useRef(null);
+  const virtualizer = useVirtualizer({
+    count: 10000,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 35,
+  });
+  <div ref={parentRef} style={{ height: '400px', overflow: 'auto' }}>
+    <div style={{ height: virtualizer.getTotalSize() + 'px', position: 'relative' }}>
+      @for (const item of virtualizer.getVirtualItems(); key item.key) {
+        <div
+          ref={virtualizer.measureElement}
+          data-index={item.index}
+          style={{
+            position: 'absolute',
+            top: '0px',
+            left: '0px',
+            width: '100%',
+            transform: 'translateY(' + item.start + 'px)',
+          }}
+        >
+          {'Row ' + item.index}
+        </div>
+      }
+    </div>
+  </div>
+}
+```
+
+## Entry points
+
+| import | what you get | notes |
+| --- | --- | --- |
+| `@octanejs/tanstack-virtual` | everything `@tanstack/virtual-core` exports + `useVirtualizer`, `useWindowVirtualizer` (+ `ReactVirtualizer`/`ReactVirtualizerOptions` types) | core verbatim + the octane-bound adapter (single entry, mirroring upstream) |
+
+## How it works
+
+`useVirtualizer` is a line-for-line transcription of the upstream adapter: the
+`Virtualizer` instance is created once, a force-update reducer is wired into
+its `onChange` (sync scroll notifies go through octane's `flushSync`), options
+are re-composed into the instance during every render, and the
+`_didMount`/`_willUpdate` lifecycle runs in layout effects. Dynamic measurement
+works React-19 style: `ref={virtualizer.measureElement}` on item elements (a
+member-expression callback ref). The experimental `directDomUpdates` surface is
+ported verbatim.
+
+One octane nuance (consumer-invisible, pinned by tests): octane's `flushSync`
+called while a flush is already on the stack — e.g. a scroll dispatched from
+inside a click handler — degrades to a plain call drained by the ambient
+flush, so the update lands at that flush's boundary instead of nested.
+
+octane keys hooks by a compiler-injected per-call-site `Symbol`, appended as
+the last argument of every `use*` call. The hooks here forward that slot into
+their composed base hooks, so two virtualizers in one component stay
+independent, exactly like in React.
+
+## Status
+
+Current scope, known divergences, and verification status are tracked in the
+generated [bindings status table](../../docs/bindings-status.md), sourced from
+this package's [`status.json`](./status.json).

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@octanejs/tanstack-virtual",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "description": "TanStack Virtual bindings for the octane renderer — reuses the framework-agnostic @tanstack/virtual-core and swaps the React adapter (useVirtualizer, useWindowVirtualizer) for an octane port.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/tanstack-virtual"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@tanstack/virtual-core": "3.17.3",
+    "octane": "0.1.3"
+  },
+  "devDependencies": {
+    "@tanstack/react-virtual": "3.14.5",
+    "@tsrx/react": "^0.2.37",
+    "esbuild": "^0.28.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,261 @@
+// @octanejs/tanstack-virtual — TanStack Virtual for the octane renderer.
+//
+// TanStack Virtual separates a framework-agnostic core (`@tanstack/virtual-core`:
+// the Virtualizer class + scroll/rect observers + windowing math) from a small
+// React adapter (`useVirtualizer`, `useWindowVirtualizer`). This package reuses
+// the core UNCHANGED (re-exported verbatim) and transcribes only the adapter
+// onto octane's hooks, preserving upstream's exact shape — a force-update
+// useReducer wired into the instance's onChange (flushSync for sync scroll
+// notifies), a create-once Virtualizer in useState, setOptions re-composed
+// every render, and three layout effects (_didMount once, _willUpdate every
+// render, direct-DOM style application every render). The public surface
+// matches @tanstack/react-virtual 1:1 — existing code works by changing the
+// import.
+//
+// The one octane-specific detail is hook slots: octane keys hooks by a
+// compiler-injected per-call-site Symbol, appended as the LAST argument of
+// every `use*` call. The hooks here forward that slot into their composed base
+// hooks (deriving a stable sub-slot each), so two virtualizers in one
+// component stay independent, just like in React.
+//
+// Note on flushSync: octane's flushSync called while a flush is already on the
+// stack degrades to a plain fn() and lets the ambient flush drain the work
+// (runtime.ts re-entrancy guard) — consumer-invisible at flush boundaries;
+// pinned by a conformance test.
+import { flushSync, useEffect, useLayoutEffect, useReducer, useRef, useState } from 'octane';
+import {
+	Virtualizer,
+	elementScroll,
+	observeElementOffset,
+	observeElementRect,
+	observeWindowOffset,
+	observeWindowRect,
+	windowScroll,
+} from '@tanstack/virtual-core';
+import type { PartialKeys, VirtualizerOptions } from '@tanstack/virtual-core';
+import { splitSlot, subSlot } from './internal';
+
+export * from '@tanstack/virtual-core';
+
+export type ReactVirtualizer<
+	TScrollElement extends Element | Window,
+	TItemElement extends Element,
+> = Virtualizer<TScrollElement, TItemElement> & {
+	/**
+	 * Ref callback for the inner size container element. Only meaningful when
+	 * `directDomUpdates: true` — the virtualizer writes the container's
+	 * main-axis size (`height` or `width`) directly to skip re-renders.
+	 */
+	containerRef: (node: HTMLElement | null) => void;
+};
+
+export type ReactVirtualizerOptions<
+	TScrollElement extends Element | Window,
+	TItemElement extends Element,
+> = VirtualizerOptions<TScrollElement, TItemElement> & {
+	useFlushSync?: boolean;
+	/**
+	 * Skip re-renders for scroll-only updates: the virtualizer writes item
+	 * positions and the container size directly to the DOM, and only
+	 * re-renders when the visible index range or `isScrolling` changes. See
+	 * upstream @tanstack/react-virtual docs for the layout requirements.
+	 */
+	directDomUpdates?: boolean;
+	/** How `directDomUpdates` positions items: `'transform'` (default) or `'position'`. */
+	directDomUpdatesMode?: 'position' | 'transform';
+};
+
+interface DirectDomState {
+	enabled: boolean;
+	mode: 'position' | 'transform';
+	container: HTMLElement | null;
+	lastSize: number | null;
+	// Keyed by the element itself so a remounted node (same key, new DOM
+	// node — e.g. when `enabled` is toggled off then on) is treated as fresh
+	// and gets its style written.
+	lastPositions: WeakMap<Element, number>;
+	prevRange: { startIndex: number; endIndex: number; isScrolling: boolean } | null;
+}
+
+function useVirtualizerBase<TScrollElement extends Element | Window, TItemElement extends Element>(
+	{
+		useFlushSync = true,
+		directDomUpdates = false,
+		directDomUpdatesMode = 'transform',
+		...options
+	}: VirtualizerOptions<TScrollElement, TItemElement> & {
+		useFlushSync?: boolean;
+		directDomUpdates?: boolean;
+		directDomUpdatesMode?: 'position' | 'transform';
+	},
+	slot: symbol | undefined,
+): ReactVirtualizer<TScrollElement, TItemElement> {
+	const rerender = useReducer<number, void, number>((x) => x + 1, 0, subSlot(slot, 'uvb:r'))[1];
+
+	const directRef = useRef<DirectDomState>(
+		{
+			enabled: directDomUpdates,
+			mode: directDomUpdatesMode,
+			container: null,
+			lastSize: null,
+			lastPositions: new WeakMap(),
+			prevRange: null,
+		},
+		subSlot(slot, 'uvb:d'),
+	);
+	directRef.current.enabled = directDomUpdates;
+	directRef.current.mode = directDomUpdatesMode;
+
+	const applyDirectStyles = (instance: Virtualizer<TScrollElement, TItemElement>) => {
+		const state = directRef.current;
+		if (!state.enabled || !state.container) return;
+		const totalSize = instance.getTotalSize();
+		if (totalSize !== state.lastSize) {
+			state.lastSize = totalSize;
+			const sizeAxis = instance.options.horizontal ? 'width' : 'height';
+			state.container.style[sizeAxis] = `${totalSize}px`;
+		}
+		const horizontal = !!instance.options.horizontal;
+		const useTransform = state.mode === 'transform';
+		const posAxis = horizontal ? 'left' : 'top';
+		const scrollMargin = instance.options.scrollMargin;
+		const items = instance.getVirtualItems();
+		for (const item of items) {
+			const next = item.start - scrollMargin;
+			const el = instance.elementsCache.get(item.key) as HTMLElement | undefined;
+			if (!el) continue;
+			if (state.lastPositions.get(el) === next) continue;
+			state.lastPositions.set(el, next);
+			if (useTransform) {
+				el.style.transform = horizontal
+					? `translate3d(${next}px, 0, 0)`
+					: `translate3d(0, ${next}px, 0)`;
+			} else {
+				el.style[posAxis] = `${next}px`;
+			}
+		}
+	};
+
+	const resolvedOptions: VirtualizerOptions<TScrollElement, TItemElement> = {
+		...options,
+		onChange: (instance, sync) => {
+			const state = directRef.current;
+			let shouldRerender = true;
+			if (state.enabled) {
+				applyDirectStyles(instance);
+				const range = instance.range;
+				const prev = state.prevRange;
+				shouldRerender =
+					!prev ||
+					prev.isScrolling !== instance.isScrolling ||
+					prev.startIndex !== range?.startIndex ||
+					prev.endIndex !== range?.endIndex;
+				if (shouldRerender) {
+					state.prevRange = range
+						? {
+								startIndex: range.startIndex,
+								endIndex: range.endIndex,
+								isScrolling: instance.isScrolling,
+							}
+						: null;
+				}
+			}
+			if (shouldRerender) {
+				if (useFlushSync && sync) {
+					flushSync(rerender);
+				} else {
+					rerender();
+				}
+			}
+			options.onChange?.(instance, sync);
+		},
+	};
+
+	const [instance] = useState(
+		() => {
+			const v = new Virtualizer<TScrollElement, TItemElement>(resolvedOptions);
+			return Object.assign(v, {
+				containerRef: (node: HTMLElement | null) => {
+					const state = directRef.current;
+					state.container = node;
+					state.lastSize = null;
+					if (node && state.enabled) {
+						const total = v.getTotalSize();
+						state.lastSize = total;
+						const axis = v.options.horizontal ? 'width' : 'height';
+						node.style[axis] = `${total}px`;
+					}
+				},
+			});
+		},
+		subSlot(slot, 'uvb:i'),
+	);
+
+	instance.setOptions(resolvedOptions);
+
+	useIsomorphicLayoutEffect(() => instance._didMount(), [], subSlot(slot, 'uvb:m'));
+	useIsomorphicLayoutEffect(() => instance._willUpdate(), undefined, subSlot(slot, 'uvb:w'));
+	useIsomorphicLayoutEffect(
+		() => {
+			applyDirectStyles(instance);
+		},
+		undefined,
+		subSlot(slot, 'uvb:s'),
+	);
+
+	return instance;
+}
+
+// SSR guard, ported as-is: on the server the layout-effect work (observer
+// wiring) is skipped and the first paint windows from initialRect/initialOffset.
+function useIsomorphicLayoutEffect(
+	fn: () => void | (() => void),
+	deps: unknown[] | undefined,
+	slot: symbol,
+): void {
+	if (typeof document !== 'undefined') {
+		useLayoutEffect(fn, deps, slot);
+	} else {
+		useEffect(fn, deps, slot);
+	}
+}
+
+export function useVirtualizer<TScrollElement extends Element, TItemElement extends Element>(
+	options: PartialKeys<
+		ReactVirtualizerOptions<TScrollElement, TItemElement>,
+		'observeElementRect' | 'observeElementOffset' | 'scrollToFn'
+	>,
+	...rest: unknown[]
+): ReactVirtualizer<TScrollElement, TItemElement> {
+	const [, slot] = splitSlot(rest);
+	return useVirtualizerBase<TScrollElement, TItemElement>(
+		{
+			observeElementRect,
+			observeElementOffset,
+			scrollToFn: elementScroll,
+			...options,
+		},
+		slot,
+	);
+}
+
+export function useWindowVirtualizer<TItemElement extends Element>(
+	options: PartialKeys<
+		ReactVirtualizerOptions<Window, TItemElement>,
+		'getScrollElement' | 'observeElementRect' | 'observeElementOffset' | 'scrollToFn'
+	>,
+	...rest: unknown[]
+): ReactVirtualizer<Window, TItemElement> {
+	const [, slot] = splitSlot(rest);
+	return useVirtualizerBase<Window, TItemElement>(
+		{
+			getScrollElement: () => (typeof document !== 'undefined' ? window : null),
+			observeElementRect: observeWindowRect,
+			observeElementOffset: observeWindowOffset,
+			scrollToFn: windowScroll,
+			initialOffset: () => (typeof document !== 'undefined' ? window.scrollY : 0),
+			...options,
+		},
+		slot,
+	);
+}

package/src/internal.ts

@@ -0,0 +1,37 @@
+// Slot mechanics shared by the binding's plain-`.ts` hooks (same helper as
+// @octanejs/tanstack-query). The octane compiler injects a per-call-site Symbol slot into
+// every hook call in compiled files; these binding files are NOT compiled, so a
+// hook here receives the caller's slot as its trailing argument and derives a
+// distinct sub-slot for each base hook it composes.
+
+// Memoized: subSlot runs on EVERY hook call every render; the cache returns the
+// identical Symbol.for-interned value without the concat + registry lookup.
+const subSlotCache = new Map<symbol, Map<string, symbol>>();
+// Tag-only symbols for the slotless-caller case (see below).
+const bareTagCache = new Map<string, symbol>();
+
+export function subSlot(slot: symbol | undefined, tag: string): symbol {
+	// No inherited slot (the caller was NOT compiled — e.g. a vendored wrapper
+	// hook): return a stable TAG-ONLY symbol rather than undefined. The runtime
+	// combines it with the ambient withSlot path, so sibling base hooks inside
+	// one composed hook stay DISTINCT per tag. Returning undefined here made
+	// them all resolve to the bare path — one shared slot, state collision.
+	if (slot === undefined) {
+		let bare = bareTagCache.get(tag);
+		if (bare === undefined) bareTagCache.set(tag, (bare = Symbol.for(':' + tag)));
+		return bare;
+	}
+	let byTag = subSlotCache.get(slot);
+	if (byTag === undefined) subSlotCache.set(slot, (byTag = new Map()));
+	let sym = byTag.get(tag);
+	if (sym === undefined) byTag.set(tag, (sym = Symbol.for((slot.description ?? '') + ':' + tag)));
+	return sym;
+}
+
+// Split the compiler-injected trailing slot off a hook's runtime args, returning
+// the user args (everything before it) and the slot.
+export function splitSlot(args: any[]): [any[], symbol | undefined] {
+	const tail = args[args.length - 1];
+	const slot = typeof tail === 'symbol' ? (tail as symbol) : undefined;
+	return [slot !== undefined ? args.slice(0, -1) : args, slot];
+}