@yorozu/virtual-list 1.0.25

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan
+
+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,57 @@
+# @yorozu/virtual-list
+
+Framework-free id-window engine for absolute-row lists. You own the DOM: paint `top` from `rowTop`, size the sizer from `totalSize`, and iterate `viewportIds`. This package does not render, does not run FLIP, and does not own sortable.
+
+## Install
+
+```bash
+pnpm add @yorozu/virtual-list
+```
+
+## Slice + factory
+
+Use `createVirtualList` from a scroll handler. Number `itemSize` is O(1). Pass a function for two-height rows; the engine rebuilds a prefix on `sync` and lower-bounds it on scroll.
+
+`onVisibleRange` is the mounted window. `onPaintedRange` is the rows intersecting the viewport (use this for presence / warm). Edge growth is math-only. Idle trim recenters to ~2× `listSlice` after `DEFAULT_IDLE_TRIM_MS` (150). `listSliceForViewport` is applied on idle, not mid-fling.
+
+Pass `getFromTranslateY` through to `@yorozu/animations` `createListReorder`. Snap `itemSize` during a density tween; do not feed fractional height into `rowTop` until settle.
+
+`slotIndex` is a stable integer for a mounted id so a host can rebind a row without remounting. The engine does not pool components.
+
+History / variable-height bubbles are out of scope. Do not translate the window (`offsetY`). Absolute `top` is the layout.
+
+```ts
+import { createVirtualList } from "@yorozu/virtual-list"
+
+let items = Array.from({ length: 1000 }, (_, i) => `row-${i}`)
+let scroller = document.getElementById("scroller")!
+let sizer = document.getElementById("sizer")!
+let rowNodes = new Map<string, HTMLElement>()
+
+let list = createVirtualList({
+    getItems: () => items,
+    itemSize: 48,
+    onChange: () => paint(),
+})
+
+list.sync()
+
+scroller.addEventListener("scroll", () => {
+    list.onScroll({
+        scrollTop: scroller.scrollTop,
+        viewportHeight: scroller.clientHeight,
+    })
+})
+
+function paint(): void {
+    sizer.style.height = `${list.totalSize()}px`
+    let from = list.fromOffset()
+    let ids = list.viewportIds() ?? []
+    for (let i = 0; i < ids.length; i++) {
+        let id = ids[i]!
+        let node = rowNodes.get(id)
+        if (node === undefined) continue
+        node.style.top = `${list.rowTop(from + i)}px`
+    }
+}
+```

package/edge-scroll.d.ts

@@ -0,0 +1,37 @@
+import { LoadDirection } from './slice';
+export declare const DEFAULT_SENSITIVE_AREA_PX: number;
+export declare const DEFAULT_EDGE_DEBOUNCE_MS: number;
+export declare const DEFAULT_IDLE_TRIM_MS: number;
+export type EdgeScrollState = {
+    isScrollTopJustUpdated?: boolean;
+    lastScrollTop?: number;
+};
+export declare function leadingDebounce<A extends unknown[]>(fn: (...args: A) => void, ms: number): (...args: A) => void;
+export declare function createEdgeDebouncedLoaders(onLoadMore: (args: {
+    direction: LoadDirection;
+    noScroll?: boolean;
+}) => void, debounceMs?: number): {
+    loadMoreForwards: () => void;
+    loadMoreBackwards: (noScroll?: boolean) => void;
+};
+export declare function handleEdgeScroll(args: {
+    scrollTop: number;
+    viewportHeight: number;
+    itemHeight: number;
+    fromOffset: number;
+    mountedCount: number;
+    sensitiveArea: number;
+    state: EdgeScrollState;
+    loadMoreForwards: () => void;
+    loadMoreBackwards: (noScroll?: boolean) => void;
+    mountedTopPx?: number;
+    mountedBottomPx?: number;
+}): boolean;
+export declare function maybePreloadBackwards(args: {
+    itemCount: number;
+    preloadBackwards: number;
+    loadMoreBackwards: (noScroll?: boolean) => void;
+    itemHeight?: number;
+    viewportHeight?: number;
+    scrollContainer?: HTMLElement | null;
+}): boolean;

package/index.d.ts

@@ -0,0 +1,7 @@
+export type { LoadDirection, ViewportSliceResult, ViewportIdSliceControllerOptions } from './slice';
+export { DEFAULT_LIST_SLICE, DEFAULT_MAX_MOUNTED_FACTOR, areIdArraysEqual, reuseIfEqual, getViewportSlice, ViewportIdSliceController, } from './slice';
+export type { EdgeScrollState } from './edge-scroll';
+export { DEFAULT_SENSITIVE_AREA_PX, DEFAULT_EDGE_DEBOUNCE_MS, DEFAULT_IDLE_TRIM_MS, leadingDebounce, createEdgeDebouncedLoaders, handleEdgeScroll, maybePreloadBackwards, } from './edge-scroll';
+export { LIST_SLICE_MIN, LIST_SLICE_MAX, LIST_SLICE_OVERSCAN_ROWS, heightPrefix, firstVisibleIndexFromPrefix, rowTopFromPrefix, paintedIndexRange, listSliceForViewport, } from './range';
+export type { VirtualListRange, VirtualListOptions, VirtualList } from './list';
+export { createVirtualList } from './list';

package/index.js

@@ -0,0 +1,551 @@
+//#region src/slice.ts
+var DEFAULT_LIST_SLICE = 30;
+var DEFAULT_MAX_MOUNTED_FACTOR = 3;
+function areIdArraysEqual(a, b) {
+	if (a === b) return true;
+	if (a === void 0 || b === void 0) return false;
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+	return true;
+}
+function reuseIfEqual(prev, next) {
+	return areIdArraysEqual(prev, next) && prev !== void 0 ? prev : next;
+}
+function getViewportSlice(sourceIds, direction, listSlice, offsetId) {
+	let length = sourceIds.length;
+	let index = offsetId !== void 0 ? sourceIds.indexOf(offsetId) : 0;
+	let indexForDirection = direction === "forwards" ? index : index + 1 || length;
+	let from = Math.max(0, indexForDirection - listSlice);
+	let to = indexForDirection + listSlice - 1;
+	let viewportIds = sourceIds.slice(from, to + 1);
+	let isOnTop = viewportIds[0] === sourceIds[0];
+	let areSomeLocal;
+	let areAllLocal;
+	if (direction === "forwards") {
+		areSomeLocal = indexForDirection >= 0;
+		areAllLocal = from >= 0;
+	} else {
+		areSomeLocal = indexForDirection < length;
+		areAllLocal = to <= length - 1;
+	}
+	return {
+		viewportIds,
+		fromOffset: from,
+		isOnTop,
+		areSomeLocal,
+		areAllLocal
+	};
+}
+function pickStillPresentOffset(sourceIds, viewportIds) {
+	if (viewportIds === void 0 || viewportIds.length === 0) return sourceIds[0];
+	let mid = viewportIds[Math.round(viewportIds.length / 2)];
+	if (mid !== void 0 && sourceIds.includes(mid)) return mid;
+	for (let id of viewportIds) if (sourceIds.includes(id)) return id;
+	return sourceIds[0];
+}
+var ViewportIdSliceController = class {
+	_listSlice;
+	_loadMoreBackwards;
+	_viewportIds;
+	_fromOffset = 0;
+	_isOnTop = true;
+	_isDisabled = false;
+	_sourceIds;
+	constructor(options) {
+		this._listSlice = options?.listSlice ?? 30;
+		this._loadMoreBackwards = options?.loadMoreBackwards;
+	}
+	get viewportIds() {
+		return this._viewportIds;
+	}
+	get fromOffset() {
+		return this._fromOffset;
+	}
+	get isOnTop() {
+		return this._isOnTop;
+	}
+	setListSlice(n) {
+		if (n <= 0) return;
+		this._listSlice = n;
+	}
+	sync(sourceIds, isDisabled = false) {
+		if (sourceIds === void 0) {
+			let changed = this._viewportIds !== void 0 || this._fromOffset !== 0 || this._isOnTop !== true;
+			this._viewportIds = void 0;
+			this._fromOffset = 0;
+			this._isOnTop = true;
+			this._isDisabled = false;
+			this._sourceIds = void 0;
+			return changed;
+		}
+		if (areIdArraysEqual(this._sourceIds, sourceIds) && this._isDisabled === isDisabled && this._viewportIds !== void 0) return false;
+		this._sourceIds = sourceIds;
+		this._isDisabled = isDisabled;
+		if (isDisabled) return this._commitWindow(sourceIds, 0, true);
+		let offsetId;
+		if (this._viewportIds === void 0) offsetId = sourceIds[0];
+		else offsetId = pickStillPresentOffset(sourceIds, this._viewportIds);
+		let result = getViewportSlice(sourceIds, "forwards", this._listSlice, offsetId);
+		return this._commitWindow(result.viewportIds, result.fromOffset, result.isOnTop);
+	}
+	getMore(sourceIds, args) {
+		if (sourceIds === void 0 || sourceIds.length === 0) {
+			this._loadMoreBackwards?.({ offsetId: void 0 });
+			return false;
+		}
+		this._sourceIds = sourceIds;
+		let from = this._fromOffset;
+		let end = from + (this._viewportIds?.length ?? 0);
+		let maxMounted = this._listSlice * 3;
+		let nextFrom = from;
+		let nextEnd = end;
+		let direction = args.direction;
+		if (direction === "backwards") {
+			nextEnd = Math.min(sourceIds.length, end + this._listSlice);
+			if (nextEnd - nextFrom > maxMounted) nextFrom = nextEnd - maxMounted;
+		} else {
+			nextFrom = Math.max(0, from - this._listSlice);
+			if (nextEnd - nextFrom > maxMounted) nextEnd = nextFrom + maxMounted;
+		}
+		nextFrom = Math.max(0, nextFrom);
+		nextEnd = Math.min(sourceIds.length, Math.max(nextFrom, nextEnd));
+		let nextIds = sourceIds.slice(nextFrom, nextEnd);
+		if (direction === "backwards" && end + this._listSlice > sourceIds.length) {
+			let offsetId = sourceIds[sourceIds.length - 1];
+			this._loadMoreBackwards?.({ offsetId });
+		}
+		return this._commitWindow(nextIds, nextFrom, nextIds[0] === sourceIds[0]);
+	}
+	reanchorAtIndex(sourceIds, index) {
+		let offsetId = sourceIds[Math.max(0, Math.min(index, sourceIds.length - 1))];
+		let result = getViewportSlice(sourceIds, "forwards", this._listSlice, offsetId);
+		this._sourceIds = sourceIds;
+		return this._commitWindow(result.viewportIds, result.fromOffset, result.isOnTop);
+	}
+	trimToSlice(sourceIds, firstVisibleIndex) {
+		return this.reanchorAtIndex(sourceIds, firstVisibleIndex);
+	}
+	resetToTop(sourceIds) {
+		let result = getViewportSlice(sourceIds, "forwards", this._listSlice, sourceIds[0]);
+		this._sourceIds = sourceIds;
+		this._commitWindow(result.viewportIds, result.fromOffset, result.isOnTop);
+	}
+	_commitWindow(ids, from, isOnTop) {
+		let prevIds = this._viewportIds;
+		let prevFrom = this._fromOffset;
+		let prevOnTop = this._isOnTop;
+		this._viewportIds = reuseIfEqual(prevIds, ids);
+		this._fromOffset = from;
+		this._isOnTop = isOnTop;
+		return !areIdArraysEqual(prevIds, this._viewportIds) || prevFrom !== from || prevOnTop !== isOnTop;
+	}
+};
+//#endregion
+//#region src/edge-scroll.ts
+var DEFAULT_SENSITIVE_AREA_PX = 800;
+var DEFAULT_EDGE_DEBOUNCE_MS = 150;
+var DEFAULT_IDLE_TRIM_MS = 150;
+function leadingDebounce(fn, ms) {
+	let lastCall;
+	return (...args) => {
+		let now = Date.now();
+		if (lastCall !== void 0 && now - lastCall < ms) return;
+		lastCall = now;
+		fn(...args);
+	};
+}
+function createEdgeDebouncedLoaders(onLoadMore, debounceMs = 150) {
+	return {
+		loadMoreForwards: leadingDebounce(() => {
+			onLoadMore({ direction: "forwards" });
+		}, debounceMs),
+		loadMoreBackwards: leadingDebounce((noScroll = false) => {
+			onLoadMore({
+				direction: "backwards",
+				noScroll
+			});
+		}, debounceMs)
+	};
+}
+function handleEdgeScroll(args) {
+	let { scrollTop, viewportHeight, itemHeight, fromOffset, mountedCount, sensitiveArea, state, loadMoreForwards, loadMoreBackwards, mountedTopPx, mountedBottomPx } = args;
+	if (state.isScrollTopJustUpdated) {
+		state.isScrollTopJustUpdated = false;
+		state.lastScrollTop = scrollTop;
+		return false;
+	}
+	if (mountedCount <= 0 || viewportHeight <= 0 || !(mountedTopPx !== void 0 && mountedBottomPx !== void 0) && itemHeight <= 0) {
+		state.lastScrollTop = scrollTop;
+		return false;
+	}
+	let lastScrollTop = state.lastScrollTop;
+	if (lastScrollTop === void 0) {
+		state.lastScrollTop = scrollTop;
+		return false;
+	}
+	let topPx = mountedTopPx ?? fromOffset * itemHeight;
+	let bottomPx = mountedBottomPx ?? (fromOffset + mountedCount) * itemHeight;
+	let nearTop = scrollTop <= topPx + sensitiveArea;
+	let nearBottom = bottomPx - (scrollTop + viewportHeight) <= sensitiveArea;
+	let movingUp = scrollTop < lastScrollTop;
+	let movingDown = scrollTop > lastScrollTop;
+	let fired = false;
+	if (movingUp && nearTop) {
+		loadMoreForwards();
+		fired = true;
+	} else if (movingDown && nearBottom) {
+		loadMoreBackwards();
+		fired = true;
+	}
+	state.lastScrollTop = scrollTop;
+	return fired;
+}
+function maybePreloadBackwards(args) {
+	let { itemCount, preloadBackwards, loadMoreBackwards, itemHeight, viewportHeight, scrollContainer } = args;
+	if (preloadBackwards > 0 && itemCount < preloadBackwards) {
+		loadMoreBackwards(true);
+		return true;
+	}
+	if (itemHeight !== void 0 && viewportHeight !== void 0 && itemHeight > 0 && viewportHeight > 0 && itemCount * itemHeight < viewportHeight) {
+		loadMoreBackwards();
+		return true;
+	}
+	if (scrollContainer != null) {
+		let { scrollHeight, clientHeight } = scrollContainer;
+		if (scrollHeight > 0 && clientHeight > 0 && scrollHeight < clientHeight) {
+			loadMoreBackwards();
+			return true;
+		}
+	}
+	return false;
+}
+//#endregion
+//#region src/range.ts
+var LIST_SLICE_MIN = 16;
+var LIST_SLICE_MAX = 48;
+var LIST_SLICE_OVERSCAN_ROWS = 4;
+function heightPrefix(count, heightAt) {
+	let prefix = new Array(count + 1);
+	prefix[0] = 0;
+	for (let i = 0; i < count; i++) prefix[i + 1] = prefix[i] + heightAt(i);
+	return prefix;
+}
+function firstVisibleIndexFromPrefix(prefix, scrollTop) {
+	let count = prefix.length - 1;
+	if (count <= 0 || scrollTop <= 0) return 0;
+	let lo = 0;
+	let hi = count - 1;
+	while (lo < hi) {
+		let mid = lo + hi >>> 1;
+		if (prefix[mid + 1] > scrollTop) hi = mid;
+		else lo = mid + 1;
+	}
+	return lo;
+}
+function rowTopFromPrefix(prefix, index) {
+	if (prefix.length === 0) return 0;
+	return prefix[Math.max(0, Math.min(index, prefix.length - 1))];
+}
+function paintedIndexRange(scrollTop, viewportHeight, itemHeight, count) {
+	if (itemHeight <= 0 || viewportHeight <= 0 || count <= 0) return {
+		start: 0,
+		end: 0
+	};
+	let start = Math.max(0, Math.floor(scrollTop / itemHeight));
+	let end = Math.min(count, Math.ceil((scrollTop + viewportHeight) / itemHeight));
+	if (start > count) start = count;
+	if (end < start) end = start;
+	return {
+		start,
+		end
+	};
+}
+function listSliceForViewport(viewportHeight, itemHeight, opts) {
+	let min = opts?.min ?? 16;
+	let max = opts?.max ?? 48;
+	let overscanRows = opts?.overscanRows ?? 4;
+	if (viewportHeight <= 0 || itemHeight <= 0) return min;
+	let raw = Math.ceil(viewportHeight / itemHeight) + overscanRows;
+	return Math.max(min, Math.min(max, raw));
+}
+//#endregion
+//#region src/list.ts
+var DEFAULT_NEAR_END_THRESHOLD = 10;
+function defaultScheduleIdle(fn, timeoutMs) {
+	let timer = setTimeout(fn, timeoutMs);
+	return { cancel() {
+		clearTimeout(timer);
+	} };
+}
+function exclusiveEndFromPrefix(prefix, viewportBottom) {
+	let count = prefix.length - 1;
+	if (count <= 0 || viewportBottom <= 0) return 0;
+	let lo = 0;
+	let hi = count;
+	while (lo < hi) {
+		let mid = lo + hi >>> 1;
+		if (prefix[mid] >= viewportBottom) hi = mid;
+		else lo = mid + 1;
+	}
+	return lo;
+}
+function createVirtualList(options) {
+	let listSlice = options.listSlice ?? 30;
+	let sensitiveArea = options.sensitiveArea ?? 800;
+	let idleTrimMs = options.idleTrimMs ?? 150;
+	let nearEndThreshold = options.nearEndThreshold ?? DEFAULT_NEAR_END_THRESHOLD;
+	let scheduleIdle = options.scheduleIdle ?? defaultScheduleIdle;
+	let controller = new ViewportIdSliceController({
+		listSlice: options.listSlice,
+		loadMoreBackwards: options.loadMoreBackwards
+	});
+	let slots = /* @__PURE__ */ new Map();
+	let freeSlots = [];
+	let nextSlot = 0;
+	let prefix;
+	let lastScrollTop = 0;
+	let lastViewportHeight;
+	let lastPainted;
+	let lastNearEndLength;
+	let idleHandle;
+	let edgeState = {};
+	let { loadMoreForwards, loadMoreBackwards } = createEdgeDebouncedLoaders((args) => {
+		getMore(args.direction, args.noScroll);
+	}, options.edgeDebounceMs ?? 150);
+	function sourceIds() {
+		return options.getItems().slice();
+	}
+	function viewportIds() {
+		return controller.viewportIds;
+	}
+	function fromOffset() {
+		return controller.fromOffset;
+	}
+	function isOnTop() {
+		return controller.isOnTop;
+	}
+	function totalSize() {
+		let itemSize = options.itemSize;
+		if (typeof itemSize === "number") return options.getItems().length * itemSize;
+		if (prefix === void 0 || prefix.length === 0) return 0;
+		return prefix[prefix.length - 1];
+	}
+	function rowTop(index) {
+		let itemSize = options.itemSize;
+		if (typeof itemSize === "number") return index * itemSize;
+		if (prefix === void 0) return 0;
+		return rowTopFromPrefix(prefix, index);
+	}
+	function rowHeight(index) {
+		let itemSize = options.itemSize;
+		if (typeof itemSize === "number") return itemSize;
+		if (prefix === void 0) return 0;
+		let top = prefix[index];
+		let next = prefix[index + 1];
+		if (top === void 0 || next === void 0) return 0;
+		return next - top;
+	}
+	function slotIndex(id) {
+		return slots.get(id);
+	}
+	function fromTranslateY(key) {
+		return options.getFromTranslateY?.(key);
+	}
+	function firstVisibleIndex() {
+		let count = options.getItems().length;
+		if (count <= 0) return 0;
+		let itemSize = options.itemSize;
+		if (typeof itemSize === "number") {
+			if (itemSize <= 0) return 0;
+			return Math.max(0, Math.min(count - 1, Math.floor(lastScrollTop / itemSize)));
+		}
+		if (prefix === void 0) return 0;
+		return firstVisibleIndexFromPrefix(prefix, lastScrollTop);
+	}
+	function reassignSlots() {
+		let ids = controller.viewportIds;
+		if (ids === void 0) {
+			slots.clear();
+			freeSlots = [];
+			nextSlot = 0;
+			return;
+		}
+		let mounted = new Set(ids);
+		for (let [id, slot] of [...slots.entries()]) {
+			if (mounted.has(id)) continue;
+			slots.delete(id);
+			freeSlots.push(slot);
+		}
+		if (freeSlots.length > 1) freeSlots.sort((a, b) => a - b);
+		for (let id of ids) {
+			if (slots.has(id)) continue;
+			let slot = freeSlots.length > 0 ? freeSlots.shift() : nextSlot++;
+			slots.set(id, slot);
+		}
+	}
+	function notify() {
+		reassignSlots();
+		let mountedCount = controller.viewportIds?.length ?? 0;
+		options.onVisibleRange?.({
+			start: controller.fromOffset,
+			end: controller.fromOffset + mountedCount
+		});
+		options.onChange?.();
+	}
+	function notifyIfChanged(changed) {
+		if (changed) notify();
+		return changed;
+	}
+	function preloadIfNeeded() {
+		if (lastViewportHeight === void 0 || lastViewportHeight <= 0) return;
+		let itemSize = options.itemSize;
+		let itemHeight = typeof itemSize === "number" ? itemSize : rowHeight(0);
+		maybePreloadBackwards({
+			itemCount: controller.viewportIds?.length ?? 0,
+			preloadBackwards: listSlice,
+			loadMoreBackwards,
+			itemHeight,
+			viewportHeight: lastViewportHeight
+		});
+	}
+	function cancelIdle() {
+		idleHandle?.cancel();
+		idleHandle = void 0;
+	}
+	function applyIdleTrim() {
+		let itemSize = options.itemSize;
+		if (typeof itemSize === "number" && lastViewportHeight !== void 0 && lastViewportHeight > 0) {
+			let nextSlice = listSliceForViewport(lastViewportHeight, itemSize);
+			listSlice = nextSlice;
+			controller.setListSlice(nextSlice);
+		}
+		notifyIfChanged(controller.trimToSlice(sourceIds(), firstVisibleIndex()));
+	}
+	function scheduleIdleTrim() {
+		cancelIdle();
+		idleHandle = scheduleIdle(() => {
+			idleHandle = void 0;
+			applyIdleTrim();
+		}, idleTrimMs);
+	}
+	function firePaintedRange(scrollTop, viewportHeight) {
+		let onPaintedRange = options.onPaintedRange;
+		if (onPaintedRange === void 0) return;
+		let count = options.getItems().length;
+		let itemSize = options.itemSize;
+		let range;
+		if (typeof itemSize === "number") range = paintedIndexRange(scrollTop, viewportHeight, itemSize, count);
+		else if (prefix === void 0 || viewportHeight <= 0 || count <= 0) range = {
+			start: 0,
+			end: 0
+		};
+		else range = {
+			start: firstVisibleIndexFromPrefix(prefix, scrollTop),
+			end: exclusiveEndFromPrefix(prefix, scrollTop + viewportHeight)
+		};
+		if (lastPainted !== void 0 && lastPainted.start === range.start && lastPainted.end === range.end) return;
+		lastPainted = range;
+		onPaintedRange(range);
+	}
+	function maybeFireNearEnd(count) {
+		let onNearEnd = options.onNearEnd;
+		if (onNearEnd === void 0) return;
+		if (controller.fromOffset + (controller.viewportIds?.length ?? 0) >= count - nearEndThreshold) {
+			if (lastNearEndLength !== count) {
+				lastNearEndLength = count;
+				onNearEnd();
+			}
+		} else lastNearEndLength = void 0;
+	}
+	function sync(isDisabled) {
+		let source = sourceIds();
+		let itemSize = options.itemSize;
+		if (typeof itemSize === "function") prefix = heightPrefix(source.length, itemSize);
+		let changed = controller.sync(source, isDisabled);
+		notifyIfChanged(changed);
+		preloadIfNeeded();
+		return changed;
+	}
+	function onScroll(metrics) {
+		lastScrollTop = metrics.scrollTop;
+		lastViewportHeight = metrics.viewportHeight;
+		firePaintedRange(metrics.scrollTop, metrics.viewportHeight);
+		let count = options.getItems().length;
+		let from = controller.fromOffset;
+		let mountedCount = controller.viewportIds?.length ?? 0;
+		let first = firstVisibleIndex();
+		if (first < from - 2 || first >= from + mountedCount + 2) {
+			let changed = controller.reanchorAtIndex(sourceIds(), first);
+			edgeState.lastScrollTop = void 0;
+			scheduleIdleTrim();
+			notifyIfChanged(changed);
+			return;
+		}
+		let windowEnd = from + mountedCount;
+		let itemSize = options.itemSize;
+		handleEdgeScroll({
+			scrollTop: metrics.scrollTop,
+			viewportHeight: metrics.viewportHeight,
+			itemHeight: typeof itemSize === "number" ? itemSize : rowHeight(0),
+			fromOffset: from,
+			mountedCount,
+			sensitiveArea,
+			state: edgeState,
+			loadMoreForwards,
+			loadMoreBackwards,
+			mountedTopPx: rowTop(from),
+			mountedBottomPx: windowEnd >= count ? totalSize() : rowTop(windowEnd)
+		});
+		scheduleIdleTrim();
+		maybeFireNearEnd(count);
+	}
+	function reanchor(index) {
+		notifyIfChanged(controller.reanchorAtIndex(sourceIds(), index));
+	}
+	function resetToTop() {
+		let prevIds = controller.viewportIds;
+		let prevFrom = controller.fromOffset;
+		let prevOnTop = controller.isOnTop;
+		controller.resetToTop(sourceIds());
+		edgeState.isScrollTopJustUpdated = true;
+		edgeState.lastScrollTop = void 0;
+		notifyIfChanged(!areIdArraysEqual(prevIds, controller.viewportIds) || prevFrom !== controller.fromOffset || prevOnTop !== controller.isOnTop);
+	}
+	function getMore(direction, noScroll) {
+		return notifyIfChanged(controller.getMore(sourceIds(), {
+			direction,
+			noScroll
+		}));
+	}
+	function trimIdle(firstVisible) {
+		return notifyIfChanged(controller.trimToSlice(sourceIds(), firstVisible));
+	}
+	function setListSlice(n) {
+		if (n <= 0) return;
+		listSlice = n;
+		controller.setListSlice(n);
+	}
+	function destroy() {
+		cancelIdle();
+	}
+	return {
+		viewportIds,
+		fromOffset,
+		isOnTop,
+		totalSize,
+		rowTop,
+		rowHeight,
+		slotIndex,
+		fromTranslateY,
+		sync,
+		onScroll,
+		reanchor,
+		resetToTop,
+		getMore,
+		trimIdle,
+		setListSlice,
+		destroy
+	};
+}
+//#endregion
+export { DEFAULT_EDGE_DEBOUNCE_MS, DEFAULT_IDLE_TRIM_MS, DEFAULT_LIST_SLICE, DEFAULT_MAX_MOUNTED_FACTOR, DEFAULT_SENSITIVE_AREA_PX, LIST_SLICE_MAX, LIST_SLICE_MIN, LIST_SLICE_OVERSCAN_ROWS, ViewportIdSliceController, areIdArraysEqual, createEdgeDebouncedLoaders, createVirtualList, firstVisibleIndexFromPrefix, getViewportSlice, handleEdgeScroll, heightPrefix, leadingDebounce, listSliceForViewport, maybePreloadBackwards, paintedIndexRange, reuseIfEqual, rowTopFromPrefix };

package/list.d.ts

@@ -0,0 +1,47 @@
+import { LoadDirection } from './slice';
+export type VirtualListRange = {
+    start: number;
+    end: number;
+};
+export type VirtualListOptions<Id extends string | number> = {
+    getItems: () => readonly Id[];
+    itemSize: number | ((index: number) => number);
+    listSlice?: number;
+    sensitiveArea?: number;
+    edgeDebounceMs?: number;
+    idleTrimMs?: number;
+    nearEndThreshold?: number;
+    loadMoreBackwards?: (args: {
+        offsetId?: Id;
+    }) => void;
+    onNearEnd?: () => void;
+    onVisibleRange?: (range: VirtualListRange) => void;
+    onPaintedRange?: (range: VirtualListRange) => void;
+    onChange?: () => void;
+    getFromTranslateY?: (key: string | number) => number | undefined;
+    scheduleIdle?: (fn: () => void, timeoutMs: number) => {
+        cancel(): void;
+    };
+};
+export type VirtualList<Id extends string | number> = {
+    viewportIds: () => Id[] | undefined;
+    fromOffset: () => number;
+    isOnTop: () => boolean;
+    totalSize: () => number;
+    rowTop: (index: number) => number;
+    rowHeight: (index: number) => number;
+    slotIndex: (id: Id) => number | undefined;
+    fromTranslateY: (key: string | number) => number | undefined;
+    sync: (isDisabled?: boolean) => boolean;
+    onScroll: (metrics: {
+        scrollTop: number;
+        viewportHeight: number;
+    }) => void;
+    reanchor: (index: number) => void;
+    resetToTop: () => void;
+    getMore: (direction: LoadDirection, noScroll?: boolean) => boolean;
+    trimIdle: (firstVisibleIndex: number) => boolean;
+    setListSlice: (n: number) => void;
+    destroy: () => void;
+};
+export declare function createVirtualList<Id extends string | number>(options: VirtualListOptions<Id>): VirtualList<Id>;

package/package.json

@@ -0,0 +1,21 @@
+{
+    "name": "@yorozu/virtual-list",
+    "type": "module",
+    "version": "1.0.25",
+    "description": "framework-agnostic absolute-row virtual list engine",
+    "license": "MIT",
+    "exports": {
+        ".": {
+            "import": {
+                "types": "./index.d.ts",
+                "default": "./index.js"
+            }
+        }
+    },
+    "sideEffects": false,
+    "author": "inshinrei",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/inshinrei/yorozu.git"
+    }
+}

package/range.d.ts

@@ -0,0 +1,15 @@
+export declare const LIST_SLICE_MIN: number;
+export declare const LIST_SLICE_MAX: number;
+export declare const LIST_SLICE_OVERSCAN_ROWS: number;
+export declare function heightPrefix(count: number, heightAt: (i: number) => number): number[];
+export declare function firstVisibleIndexFromPrefix(prefix: number[], scrollTop: number): number;
+export declare function rowTopFromPrefix(prefix: number[], index: number): number;
+export declare function paintedIndexRange(scrollTop: number, viewportHeight: number, itemHeight: number, count: number): {
+    start: number;
+    end: number;
+};
+export declare function listSliceForViewport(viewportHeight: number, itemHeight: number, opts?: {
+    min?: number;
+    max?: number;
+    overscanRows?: number;
+}): number;

package/slice.d.ts

@@ -0,0 +1,44 @@
+export type LoadDirection = "forwards" | "backwards";
+export declare const DEFAULT_LIST_SLICE: number;
+export declare const DEFAULT_MAX_MOUNTED_FACTOR: number;
+export type ViewportSliceResult<Id extends string | number> = {
+    viewportIds: Id[];
+    fromOffset: number;
+    isOnTop: boolean;
+    areSomeLocal: boolean;
+    areAllLocal: boolean;
+};
+export declare function areIdArraysEqual<Id extends string | number>(a: Id[] | undefined, b: Id[] | undefined): boolean;
+export declare function reuseIfEqual<Id extends string | number>(prev: Id[] | undefined, next: Id[]): Id[];
+export declare function getViewportSlice<Id extends string | number>(sourceIds: Id[], direction: LoadDirection, listSlice: number, offsetId?: Id): ViewportSliceResult<Id>;
+export type ViewportIdSliceControllerOptions<Id extends string | number> = {
+    listSlice?: number;
+    loadMoreBackwards?: (args: {
+        offsetId?: Id;
+    }) => void;
+};
+export declare class ViewportIdSliceController<Id extends string | number> {
+    protected _listSlice: number;
+    protected _loadMoreBackwards: ((args: {
+        offsetId?: Id;
+    }) => void) | undefined;
+    protected _viewportIds: Id[] | undefined;
+    protected _fromOffset: number;
+    protected _isOnTop: boolean;
+    protected _isDisabled: boolean;
+    protected _sourceIds: Id[] | undefined;
+    constructor(options?: ViewportIdSliceControllerOptions<Id>);
+    get viewportIds(): Id[] | undefined;
+    get fromOffset(): number;
+    get isOnTop(): boolean;
+    setListSlice(n: number): void;
+    sync(sourceIds: Id[] | undefined, isDisabled?: boolean): boolean;
+    getMore(sourceIds: Id[] | undefined, args: {
+        direction: LoadDirection;
+        noScroll?: boolean;
+    }): boolean;
+    reanchorAtIndex(sourceIds: Id[], index: number): boolean;
+    trimToSlice(sourceIds: Id[], firstVisibleIndex: number): boolean;
+    resetToTop(sourceIds: Id[]): void;
+    protected _commitWindow(ids: Id[], from: number, isOnTop: boolean): boolean;
+}