@botiverse/raft-ui 0.51.0 → 0.52.0

package/dist/components/virtual-list/VirtualList.mjs

@@ -0,0 +1,1401 @@
+import { cn } from "../../cn.mjs";
+import { useMergedRef } from "../../lib/use-merged-ref.mjs";
+import { EMPTY_ARRAY, ITEM_KEY_ATTR, NON_VIRTUAL_VISIBLE_ITEMS_STYLE, RENDER_THRASHING_WINDOW_MS, VIRTUAL_VISIBLE_ITEMS_STYLE } from "./utils/constants.mjs";
+import { FenwickTree } from "./utils/fenwick-tree.mjs";
+import { findItemsAnchor, getAnchoredRange } from "./utils/items-anchor.mjs";
+import { useEventCallback } from "./hooks/use-event-callback.mjs";
+import { useLatestRef } from "./hooks/use-latest-ref.mjs";
+import { useLayoutEffectWithPrevious } from "./hooks/use-layout-effect-with-previous.mjs";
+import { useMemoWithPrevious } from "./hooks/use-memo-with-previous.mjs";
+import { useNonPassiveWheel } from "./hooks/use-non-passive-wheel.mjs";
+import { ColumnsContext, ItemColumns } from "./ItemColumns.mjs";
+import { createLatestInNextFrame, getWheelDeltaScale, isCoarsePointer, isIOS } from "./utils/platform.mjs";
+import { getAlignedScrollTop } from "./utils/align.mjs";
+import { measureRowSpans, measureRowStart } from "./utils/measure.mjs";
+import { createTypicalSizeCache, getTypicalSize, recordMeasuredSize } from "./utils/size-cache.mjs";
+import { getHorizontalRange, getNeededEnd, getOverscannedRange, getVerticalRange, haveSameKeys, isHiddenByDisplayNone, px } from "./utils/range.mjs";
+import { getResizeObserverDelegate } from "./resize-observer/resize-observer-delegate.mjs";
+import { ResizeObserverWrapper } from "./resize-observer/ResizeObserverWrapper.mjs";
+import { useIosMomentumCompensation } from "./hooks/use-ios-momentum-compensation.mjs";
+import { useKeyboardScroll } from "./hooks/use-keyboard-scroll.mjs";
+import { useNonVirtualContentResize } from "./hooks/use-non-virtual-content-resize.mjs";
+import { useScrollAnchor } from "./hooks/use-scroll-anchor.mjs";
+import { VirtualListContext } from "./VirtualListContext.mjs";
+import { createElement, useCallback, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { flushSync } from "react-dom";
+//#region src/components/virtual-list/VirtualList.tsx
+/**
+* The most range updates one aligned jump goes through before it stops (each one mounts and measures the
+* rows the previous position brought into view; it is usually stable after 2-3).
+*/
+const MAX_ALIGN_STEPS = 10;
+function VirtualList(props) {
+	const { virtual = true, sessionId, showScrollbar = false, columns = EMPTY_ARRAY, renderCol, renderItemWithCols, items = EMPTY_ARRAY, itemMinSize, itemEstimatedSize, itemResizable = false, itemsStyle, visibleItemsTag = "div", visibleItemsProps, ignoreItemResize = false, onScroll, onWheel, onResize, defaultScrollKey, defaultScrollIndex, getKey, paddingTop = 0, paddingBottom = 0, children: renderItemChild, ItemComponent, empty, emptyAlign = "start", className, style, itemsClassName, footer, footerAfterBottomPadding, header, domRef, ref: _ref, onContentResize, onTransformChange, componentRef, printable, catchWheel = false, onRenderAnomaly, keyboardPageBottomOcclusion = 0, focusable = true, keepAnchorOnItemsChange = false, canAnchorItem, onKeyDown: onNativeKeyDown, ...nativeProps } = props;
+	const listElRef = useRef(null);
+	const [mergedListRefSetter] = useMergedRef(domRef, listElRef);
+	const itemsElRef = useRef(null);
+	const getVisibleItemsEl = useCallback(() => itemsElRef.current?.children[0] || null, []);
+	const [[renderReason, renderCallback, renderVersion], setRenderState] = useState([
+		null,
+		null,
+		0
+	]);
+	const viewportRef = useRef({
+		listHeight: void 0,
+		scrollTop: 0,
+		scrollLeft: 0,
+		listWidth: 0
+	});
+	const rangeRef = useRef({
+		prependIndexes: [],
+		verticalStartIndex: 0,
+		verticalEndIndex: -1,
+		horizontalStartIndex: 0,
+		horizontalEndIndex: -1
+	});
+	/**
+	* The rows kept mounted outside the range (absolutely positioned at their offsets): the rows holding
+	* the text selection and the row holding focus (`focusedKeyRef`).
+	*/
+	const keptKeysRef = useRef([]);
+	/** The key of the row that holds focus (`document.activeElement` is in it), tracked by focusin / focusout. */
+	const focusedKeyRef = useRef(null);
+	/** The measured rows' sizes, by key (see `utils/size-cache.ts`). */
+	const keyToHeightOffsetRef = useRef(/* @__PURE__ */ new Map());
+	/** Bumped whenever `keyToHeightOffsetRef` changes (see `getTypicalSize`). */
+	const measuredVersionRef = useRef(0);
+	const typicalSizeRef = useRef(createTypicalSizeCache());
+	const leadingMarginRef = useRef(0);
+	/**
+	* Where the first mounted row in flow starts in the visible-items element (its top margin there,
+	* since nothing above it is mounted), as last written by `applyLayoutStyles`.
+	*/
+	const firstRowStartRef = useRef(0);
+	const pendingScrollTaskRef = useRef(null);
+	const pendingScrollTaskTimeoutRef = useRef(null);
+	const pendingScrollTaskRafRef = useRef(null);
+	const wheelScrollingRef = useRef(false);
+	/** Whether the view last moved up (see `updateRange`). */
+	const scrollingUpRef = useRef(false);
+	/** Clears `wheelScrollingRef` in the next frame; this list's own, so other lists cannot replace it. */
+	const [runLatestInNextFrame] = useState(createLatestInNextFrame);
+	/** The wheel is only taken over (catchWheel) where the pointer is not coarse. */
+	const mayUseWheelRef = useRef(typeof document === "undefined" || !isCoarsePointer());
+	const reportRenderAnomaly = useEventCallback((anomaly) => {
+		onRenderAnomaly?.(anomaly);
+	});
+	const forcedRenderTimesRef = useRef([]);
+	/**
+	* The offset applied by the iOS compensation, created here (not in its hook) because
+	* `keepAnchorOnItemsChange` reads it while rendering, before the hook is called.
+	*/
+	const compensationYRef = useRef(0);
+	/** The items, Fenwick tree and session of the last commit (the tree is updated in place by measurements). */
+	const committedLayoutRef = useRef(null);
+	const itemsAnchor = useMemo(() => {
+		const committed = committedLayoutRef.current;
+		const listEl = listElRef.current;
+		if (!keepAnchorOnItemsChange || !virtual || committed === null || listEl === null || committed.items === items || committed.sessionId !== sessionId) return null;
+		return findItemsAnchor({
+			prevItems: committed.items,
+			prevTree: committed.tree,
+			prevPrependIndexes: rangeRef.current.prependIndexes,
+			nextItems: items,
+			getKey,
+			canAnchor: canAnchorItem,
+			top: listEl.scrollTop + compensationYRef.current - paddingTop - leadingMarginRef.current
+		});
+	}, [items]);
+	/** The anchor whose range has been committed to `rangeRef` (so it is applied once). */
+	const appliedItemsAnchorRef = useRef(null);
+	const pendingItemsAnchor = itemsAnchor !== null && itemsAnchor !== appliedItemsAnchorRef.current ? itemsAnchor : null;
+	let renderedRange = rangeRef.current;
+	if (pendingItemsAnchor !== null) {
+		const [verticalStartIndex, verticalEndIndex] = getAnchoredRange(renderedRange.verticalStartIndex, renderedRange.verticalEndIndex, pendingItemsAnchor.index, items.length);
+		renderedRange = {
+			...renderedRange,
+			prependIndexes: pendingItemsAnchor.prependIndexes,
+			verticalStartIndex,
+			verticalEndIndex
+		};
+	}
+	const { prependIndexes, verticalStartIndex: startIndex, verticalEndIndex: endIndex, horizontalStartIndex: colStartIndex, horizontalEndIndex: colEndIndex } = renderedRange;
+	const keyToIndexRef = useRef(void 0);
+	const prevSessionIdRef = useRef(sessionId);
+	const sessionChangedRef = useRef(false);
+	const lastTransformSignatureRef = useRef(null);
+	const clearPendingScrollTask = useCallback(() => {
+		if (pendingScrollTaskTimeoutRef.current !== null) {
+			window.clearTimeout(pendingScrollTaskTimeoutRef.current);
+			pendingScrollTaskTimeoutRef.current = null;
+		}
+		if (pendingScrollTaskRafRef.current != null) {
+			window.cancelAnimationFrame(pendingScrollTaskRafRef.current);
+			pendingScrollTaskRafRef.current = null;
+		}
+		pendingScrollTaskRef.current = null;
+	}, []);
+	useMemo(() => {
+		if (prevSessionIdRef.current === sessionId) return;
+		prevSessionIdRef.current = sessionId;
+		sessionChangedRef.current = true;
+		clearPendingScrollTask();
+		wheelScrollingRef.current = false;
+		keptKeysRef.current = [];
+		focusedKeyRef.current = null;
+		keyToHeightOffsetRef.current.clear();
+		measuredVersionRef.current += 1;
+		leadingMarginRef.current = 0;
+		keyToIndexRef.current = /* @__PURE__ */ new Map();
+		rangeRef.current = {
+			prependIndexes: [],
+			verticalStartIndex: 0,
+			verticalEndIndex: -1,
+			horizontalStartIndex: 0,
+			horizontalEndIndex: -1
+		};
+		const viewport = viewportRef.current;
+		viewport.scrollTop = 0;
+		viewport.scrollLeft = 0;
+		const listEl = listElRef.current;
+		if (listEl != null) {
+			listEl.scrollTop = 0;
+			listEl.scrollLeft = 0;
+		}
+	}, [sessionId, clearPendingScrollTask]);
+	useMemo(() => {
+		lastTransformSignatureRef.current = null;
+	}, [sessionId]);
+	useMemo(() => {
+		const keyToIndex = /* @__PURE__ */ new Map();
+		items.forEach((item, index) => {
+			keyToIndex.set(getKey(item), index);
+		});
+		keyToIndexRef.current = keyToIndex;
+		const keptKeys = [];
+		keptKeysRef.current.forEach((key) => {
+			if (keyToIndexRef.current.has(key)) keptKeys.push(key);
+		});
+		keptKeysRef.current = keptKeys;
+	}, [
+		sessionId,
+		items,
+		getKey
+	]);
+	const totalColumnsWidth = useMemo(() => {
+		if (renderCol == null && renderItemWithCols == null || columns.length === 0) return;
+		let width = 0;
+		columns.forEach((column) => {
+			width += column.width;
+		});
+		return width;
+	}, [
+		sessionId,
+		renderCol,
+		renderItemWithCols,
+		columns
+	]);
+	/**
+	* Rebuilt whenever the items or the session change: `itemEstimatedSize` for every item plus the
+	* measured offsets cached by key, so measurements survive re-renders and reordering.
+	*/
+	const fenwickTree = useMemo(() => {
+		if (!virtual) return new FenwickTree(0, 0);
+		const tree = new FenwickTree(items.length, itemEstimatedSize);
+		const heightOffsets = keyToHeightOffsetRef.current;
+		items.forEach((item, index) => {
+			const key = getKey(item);
+			const offset = heightOffsets.get(key);
+			if (offset !== void 0) tree.add(index, offset);
+		});
+		return tree;
+	}, [
+		sessionId,
+		items,
+		itemEstimatedSize,
+		getKey,
+		virtual
+	]);
+	const visibleItems = useMemo(() => {
+		if (!virtual) return items;
+		if (endIndex < startIndex) return [];
+		const visible = [];
+		const lastIndex = Math.min(endIndex, items.length - 1);
+		for (let i = startIndex; i <= lastIndex; ++i) visible.push(items[i]);
+		return visible;
+	}, [
+		sessionId,
+		startIndex,
+		endIndex,
+		items,
+		virtual
+	]);
+	const xFenwickTree = useMemo(() => {
+		if (columns.length === 0) return null;
+		const tree = new FenwickTree(columns.length, 0);
+		columns.forEach((column, index) => {
+			tree.add(index, column.width);
+		});
+		return tree;
+	}, [sessionId, columns]);
+	const getColumnLeft = useEventCallback((index) => xFenwickTree !== null ? xFenwickTree.sum(index) : 0);
+	const columnsContextValue = useMemo(() => ({
+		startIndex: colStartIndex,
+		endIndex: colEndIndex,
+		columns,
+		renderCol,
+		renderItemWithCols,
+		getLeft: getColumnLeft
+	}), [
+		colStartIndex,
+		colEndIndex,
+		columns,
+		renderCol,
+		renderItemWithCols,
+		getColumnLeft
+	]);
+	/** Where the rows start in the spacer's content: `paddingTop` plus the first row's top margin. */
+	const getRowsTop = useEventCallback(() => paddingTop + leadingMarginRef.current);
+	/**
+	* The mounted rows in flow, in order: the measured elements of the rendered range. Kept rows (outside
+	* the range, absolutely positioned) are left out: they take no space in the flow.
+	*/
+	const getFlowRows = useEventCallback(() => {
+		const rows = [];
+		const visibleItemsEl = getVisibleItemsEl();
+		if (visibleItemsEl === null) return rows;
+		for (const el of Array.from(visibleItemsEl.children)) {
+			const key = el.getAttribute(ITEM_KEY_ATTR);
+			const index = key === null ? void 0 : keyToIndexRef.current.get(key);
+			if (key !== null && index !== void 0 && index >= startIndex && index <= endIndex && el instanceof HTMLElement) rows.push({
+				el,
+				key,
+				index
+			});
+		}
+		return rows;
+	});
+	/**
+	* Writes the layout without a render: the spacer height (the total size plus the first row's top
+	* margin; a min-height with itemResizable, so the real content may exceed it) and the visible items'
+	* translateY. It writes no CSS variable on the visible items: custom properties inherit, so one
+	* written there on every scroll restyles every row. Content that must follow the rows' offset uses
+	* `onTransformChange`.
+	*
+	* Unlike the reference implementation (DeepSeek web): the translateY puts the border box of the first
+	* mounted row at its offset (`firstIndex`, or the first row in the DOM), not the element's top. The visible-items element is a
+	* block formatting context, so the first mounted row's top margin is inside it, above the row, and
+	* does not collapse with the row before it (not mounted): the element starts that margin higher. The
+	* collapsed gap above that row is already in the size of the row before it (see `leadingMarginRef`),
+	* so the rows sit exactly where the tree has them whichever row is first, and moving the window's top
+	* edge moves no row. Read before anything is written, so it forces no extra layout.
+	*/
+	const applyLayoutStyles = useEventCallback((firstIndex) => {
+		if (!virtual) return;
+		let index = Math.min(firstIndex, items.length);
+		let firstRowStart = 0;
+		const itemsEl = itemsElRef.current;
+		const visibleItemsEl = itemsEl?.children[0];
+		const firstRow = itemResizable ? getFlowRows()[0] : void 0;
+		if (firstRow !== void 0 && visibleItemsEl instanceof HTMLElement) {
+			index = firstRow.index;
+			firstRowStart = measureRowStart(visibleItemsEl, firstRow.el);
+		}
+		firstRowStartRef.current = firstRowStart;
+		const leadingMargin = leadingMarginRef.current;
+		if (itemsEl) {
+			const height = px(fenwickTree.sum() + leadingMargin) || "";
+			if (itemResizable) {
+				itemsEl.style.height = "";
+				itemsEl.style.minHeight = height;
+			} else {
+				const changed = itemsEl.style.height !== height || itemsEl.style.minHeight !== "";
+				itemsEl.style.height = height;
+				itemsEl.style.minHeight = "";
+				if (changed) onContentResize?.();
+			}
+		}
+		if (visibleItemsEl instanceof HTMLElement) {
+			const offset = px(leadingMargin + fenwickTree.sum(index) - firstRowStart);
+			visibleItemsEl.style.transform = `translateY(${offset})`;
+			const signature = `${index}|${offset}`;
+			if (lastTransformSignatureRef.current !== signature) {
+				lastTransformSignatureRef.current = signature;
+				onTransformChange?.();
+			}
+		}
+	});
+	useLayoutEffect(() => {
+		if (!virtual) {
+			const itemsEl = itemsElRef.current;
+			if (itemsEl) {
+				itemsEl.style.height = "";
+				itemsEl.style.minHeight = "";
+			}
+		}
+	}, [virtual]);
+	/** The size rows typically are: the mean of the measured rows (`getTypicalSize`). */
+	const getTypicalRowSize = useEventCallback(() => getTypicalSize(typicalSizeRef.current, keyToHeightOffsetRef.current, measuredVersionRef.current, itemEstimatedSize, itemMinSize));
+	/**
+	* The viewport sync. The range starts at the item at `scrollTop + compensation - paddingTop` and
+	* holds as many items as fit at `itemMinSize`, plus one, and is overscanned in batches
+	* (`getOverscannedRange`). Items holding the text selection, and the item
+	* holding focus, stay
+	* mounted ("kept"). When the new range is inside the old one, only the layout styles are written;
+	* otherwise the items entering above the old start are recorded (`prependIndexes`) and the range is
+	* rendered with flushSync, now or in a microtask (`deferRenderToMicrotask`). At 120 forced renders
+	* within a second a "renderThrashing" anomaly is reported. `afterRender` runs after the layout styles
+	* of the new range are applied.
+	*/
+	const updateRange = useEventCallback((reason, deferRenderToMicrotask, afterRender) => {
+		if (!virtual) return;
+		const listEl = listElRef.current;
+		if (listEl == null) return;
+		const viewport = viewportRef.current;
+		if (viewport.listHeight === void 0) {
+			applyLayoutStyles(startIndex);
+			afterRender?.();
+			return;
+		}
+		const scrollTop = listEl.scrollTop;
+		const effectiveScrollTop = scrollTop + compensationYRef.current;
+		const scrollLeft = listEl.scrollLeft;
+		const range = rangeRef.current;
+		const prevRange = {
+			startIndex: range.verticalStartIndex,
+			endIndex: range.verticalEndIndex
+		};
+		const viewRange = getVerticalRange({
+			fenwickTree,
+			scrollTop: effectiveScrollTop,
+			listHeight: viewport.listHeight,
+			itemMinSize,
+			itemCount: items.length,
+			paddingTop: getRowsTop()
+		});
+		const overscanned = viewport.listHeight > 0;
+		if (scrollTop !== viewport.scrollTop) scrollingUpRef.current = scrollTop < viewport.scrollTop;
+		const nextRange = overscanned ? getOverscannedRange({
+			fenwickTree,
+			view: viewRange,
+			prev: prevRange,
+			neededEnd: getNeededEnd({
+				fenwickTree,
+				startIndex: viewRange.startIndex,
+				viewTop: effectiveScrollTop - getRowsTop(),
+				listHeight: viewport.listHeight,
+				itemMinSize,
+				itemCount: items.length,
+				isMeasured: (index) => {
+					const item = items[index];
+					return item !== void 0 && keyToHeightOffsetRef.current.has(getKey(item));
+				}
+			}),
+			viewTop: effectiveScrollTop - getRowsTop(),
+			moved: Math.abs(scrollTop - viewport.scrollTop),
+			movingUp: scrollingUpRef.current,
+			settling: pendingScrollTaskRef.current !== null,
+			plannedSize: (index) => {
+				const item = items[index];
+				return item !== void 0 && keyToHeightOffsetRef.current.has(getKey(item)) ? fenwickTree.get(index) : getTypicalRowSize();
+			},
+			listHeight: viewport.listHeight,
+			itemCount: items.length
+		}) : viewRange;
+		const rangeChanged = prevRange.startIndex !== nextRange.startIndex || prevRange.endIndex !== nextRange.endIndex;
+		const nextInsidePrev = !overscanned && nextRange.startIndex >= prevRange.startIndex && prevRange.endIndex >= nextRange.endIndex;
+		const prevColRange = {
+			startIndex: range.horizontalStartIndex,
+			endIndex: range.horizontalEndIndex
+		};
+		const nextColRange = getHorizontalRange({
+			xFenwickTree,
+			scrollLeft,
+			listWidth: viewport.listWidth,
+			columnCount: columns.length
+		});
+		const colRangeChanged = prevColRange.startIndex !== nextColRange.startIndex || prevColRange.endIndex !== nextColRange.endIndex;
+		viewport.scrollTop = scrollTop;
+		viewport.scrollLeft = scrollLeft;
+		let keptKeysChanged = false;
+		if (typeof window !== "undefined" && reason !== "sessionChanged") {
+			const { startIndex: nextStart, endIndex: nextEnd } = nextRange;
+			const keptKeys = [];
+			const keep = (key) => {
+				const index = keyToIndexRef.current.get(key);
+				if (index !== void 0 && (!(index >= nextStart) || !(index <= nextEnd)) && !keptKeys.includes(key)) keptKeys.push(key);
+			};
+			const focusedKey = focusedKeyRef.current;
+			if (focusedKey !== null) {
+				const active = document.activeElement;
+				if (active !== null && listEl.contains(active)) keep(focusedKey);
+				else focusedKeyRef.current = null;
+			}
+			const selection = window.getSelection();
+			if (selection != null && !selection.isCollapsed && selection.rangeCount > 0) listEl.querySelectorAll(`[${ITEM_KEY_ATTR}]`).forEach((itemEl) => {
+				if (!selection.containsNode(itemEl, true) && itemEl.getElementsByTagName("input").length !== 0) return;
+				const key = itemEl.getAttribute(ITEM_KEY_ATTR);
+				if (key !== null) keep(key);
+			});
+			if (!haveSameKeys(keptKeys, keptKeysRef.current)) {
+				keptKeysRef.current = keptKeys;
+				keptKeysChanged = true;
+			}
+		}
+		if (reason !== "sessionChanged" && !keptKeysChanged && (!rangeChanged || nextInsidePrev) && !colRangeChanged) {
+			if (nextInsidePrev) applyLayoutStyles(prevRange.startIndex);
+			else applyLayoutStyles(nextRange.startIndex);
+			afterRender?.();
+			return;
+		}
+		if (reason !== "sessionChanged") {
+			const entering = [];
+			if (pendingScrollTaskRef.current?.type === void 0 && nextRange.endIndex >= prevRange.startIndex) for (let i = nextRange.startIndex; i < prevRange.startIndex; ++i) entering.push(i);
+			range.prependIndexes = entering;
+		} else range.prependIndexes = [];
+		range.verticalStartIndex = nextRange.startIndex;
+		range.verticalEndIndex = nextRange.endIndex;
+		range.horizontalStartIndex = nextColRange.startIndex;
+		range.horizontalEndIndex = nextColRange.endIndex;
+		const now = Date.now();
+		const renderTimes = forcedRenderTimesRef.current;
+		renderTimes.push(now);
+		const windowStart = now - RENDER_THRASHING_WINDOW_MS;
+		while (renderTimes.length > 0 && renderTimes[0] < windowStart) renderTimes.shift();
+		if (renderTimes.length >= 120) {
+			reportRenderAnomaly({
+				type: "renderThrashing",
+				message: `${renderTimes.length} forced renders within ${RENDER_THRASHING_WINDOW_MS}ms`,
+				payload: {
+					renderCount: renderTimes.length,
+					windowMs: RENDER_THRASHING_WINDOW_MS,
+					triggerReason: reason,
+					itemCount: items.length
+				}
+			});
+			renderTimes.length = 0;
+		}
+		if (deferRenderToMicrotask) Promise.resolve().then(() => {
+			flushSync(() => {
+				setRenderState((state) => [
+					reason,
+					afterRender,
+					state[2] + 1
+				]);
+			});
+		});
+		else flushSync(() => {
+			setRenderState((state) => [
+				reason,
+				afterRender,
+				state[2] + 1
+			]);
+		});
+	});
+	/**
+	* A pending scroll task (to the top, the bottom, an index, or a custom task) stays armed for one
+	* animation frame plus one task, so that item sizes measured right after the jump replay it instead
+	* of being compensated.
+	*/
+	const schedulePendingScrollTaskExpiry = useCallback(() => {
+		pendingScrollTaskRafRef.current = requestAnimationFrame(() => {
+			pendingScrollTaskRafRef.current = null;
+			pendingScrollTaskTimeoutRef.current = window.setTimeout(() => {
+				pendingScrollTaskRef.current = null;
+				pendingScrollTaskTimeoutRef.current = null;
+			});
+		});
+	}, []);
+	const scrollToPosition = useEventCallback((left, top, behavior) => {
+		listElRef.current?.scrollTo({
+			left,
+			top,
+			behavior
+		});
+	});
+	/**
+	* Scrolls to the offset of `index` in the Fenwick tree (an estimate for items not measured yet);
+	* an "instant" jump is armed as the pending task, to be replayed after measurements. `ensureVisibleOnly`
+	* (the `debounce` option) scrolls only as far as needed to show the item. With virtualization off the
+	* offset is read from the DOM (`getBoundingClientRect` of the index-th child).
+	*/
+	const scrollToIndex = useEventCallback((index, behavior, ensureVisibleOnly, isReplay, scrollMarginTop = 0, scrollMarginBottom = 0) => {
+		if (!virtual) {
+			const listEl = listElRef.current;
+			const itemsEl = itemsElRef.current;
+			if (!itemsEl || !listEl) return;
+			const visibleItemsEl = itemsEl.firstElementChild;
+			if (!visibleItemsEl) return;
+			const itemEl = visibleItemsEl.children.item(index);
+			if (!(itemEl instanceof HTMLElement)) return;
+			const listRect = listEl.getBoundingClientRect();
+			const itemRect = itemEl.getBoundingClientRect();
+			const itemTop = itemRect.top - listRect.top + listEl.scrollTop;
+			if (ensureVisibleOnly) {
+				const { scrollTop, offsetHeight } = listEl;
+				const itemHeight = itemRect.height;
+				if (itemTop > scrollTop) {
+					if (!(itemTop + itemHeight <= scrollTop + offsetHeight)) listEl.scrollTo({
+						left: 0,
+						top: itemTop + itemHeight - offsetHeight + scrollMarginBottom,
+						behavior
+					});
+				} else listEl.scrollTo({
+					left: 0,
+					top: itemTop - scrollMarginTop,
+					behavior
+				});
+			} else listEl.scrollTo({
+				left: 0,
+				top: itemTop,
+				behavior
+			});
+			return;
+		}
+		const targetTop = fenwickTree.sum(index) + getRowsTop();
+		if (!isReplay) {
+			clearPendingScrollTask();
+			if (behavior === "instant") {
+				const item = items[index];
+				pendingScrollTaskRef.current = {
+					type: "index",
+					key: item === void 0 ? void 0 : getKey(item),
+					index,
+					debounce: ensureVisibleOnly
+				};
+				schedulePendingScrollTaskExpiry();
+			}
+		}
+		if (ensureVisibleOnly) {
+			const listEl = listElRef.current;
+			if (listEl) {
+				const { scrollTop, offsetHeight } = listEl;
+				if (targetTop > scrollTop) {
+					const itemSize = fenwickTree.get(index);
+					if (!(targetTop + itemSize <= scrollTop + offsetHeight)) {
+						listEl.scrollTo({
+							left: 0,
+							top: targetTop + itemSize - offsetHeight + scrollMarginBottom,
+							behavior
+						});
+						updateRange("listScroll", true, null);
+					}
+				} else {
+					listEl.scrollTo({
+						left: 0,
+						top: targetTop - scrollMarginTop,
+						behavior
+					});
+					updateRange("listScroll", true, null);
+				}
+			}
+		} else {
+			listElRef.current?.scrollTo({
+				left: 0,
+				top: targetTop,
+				behavior
+			});
+			updateRange("listScroll", true, null);
+		}
+	});
+	/**
+	* Measures the mounted rows in flow from layout, synchronously, and writes the sizes that changed into
+	* the Fenwick tree and the key -> offset cache, and the first row's top margin when the first row is
+	* mounted (`leadingMarginRef`). Reads everything first (`measureRowSpans`), then writes: no layout is
+	* forced in between. O(mounted rows).
+	*
+	* Unlike the reference implementation (DeepSeek web): it measured each row's own `offsetHeight`,
+	* which in block flow misses the margins between rows and a child's margins that collapse through a row, so the rows drifted from
+	* their offsets. A row's size here is the space it takes in the flow: from where its border box starts
+	* to where the next row's starts (the last mounted row: to the end of the rows), so collapsed margins
+	* are counted once, in the row above them, and the sizes add up to the laid-out height. A row's size
+	* depends on the next row's top margin, so every measurement measures the whole run, not the row that
+	* resized. The last mounted row's bottom margin does not collapse with the next row (not mounted): its
+	* size is provisional until the next row mounts, which corrects it without moving any mounted row
+	* (they are laid out by the browser, positioned by the first row's offset alone). Kept rows are not
+	* measured: absolutely positioned, they take no space in the flow, and keep the size they were
+	* measured at in it.
+	*/
+	const measureFlowRun = useEventCallback(() => {
+		const resizes = [];
+		const visibleItemsEl = getVisibleItemsEl();
+		if (!virtual || ignoreItemResize || !itemResizable || !(visibleItemsEl instanceof HTMLElement)) return {
+			resizes,
+			leadingMarginDelta: 0
+		};
+		const rows = getFlowRows();
+		if (rows.length === 0) return {
+			resizes,
+			leadingMarginDelta: 0
+		};
+		const { spans, firstStart } = measureRowSpans(visibleItemsEl, rows.map((row) => row.el));
+		let leadingMarginDelta = 0;
+		if (rows[0].index === 0 && firstStart !== leadingMarginRef.current) {
+			leadingMarginDelta = firstStart - leadingMarginRef.current;
+			leadingMarginRef.current = firstStart;
+		}
+		rows.forEach(({ key, index }, i) => {
+			const size = spans[i];
+			const previousSize = fenwickTree.get(index);
+			if (recordMeasuredSize(keyToHeightOffsetRef.current, key, size, itemEstimatedSize)) measuredVersionRef.current += 1;
+			if (size === previousSize) return;
+			fenwickTree.add(index, size - previousSize);
+			resizes.push({
+				index,
+				key,
+				delta: size - previousSize
+			});
+		});
+		return {
+			resizes,
+			leadingMarginDelta
+		};
+	});
+	/**
+	* Measures the mounted rows now (`measureFlowRun`) and applies the layout; returns whether any size
+	* changed. Used by the aligned jump, which cannot wait for the batch (a microtask) or the
+	* ResizeObserver (after layout, possibly a frame later) to learn the sizes.
+	*/
+	const measureMountedItems = useEventCallback(() => {
+		const { resizes, leadingMarginDelta } = measureFlowRun();
+		const changed = resizes.length !== 0 || leadingMarginDelta !== 0;
+		if (changed) {
+			applyLayoutStyles(startIndex);
+			onContentResize?.();
+		}
+		return changed;
+	});
+	/**
+	* Where item `index` is, in the list's scroll coordinates: read from the DOM when
+	* it is mounted (exact), else its offset in the Fenwick tree (estimates for unmeasured items).
+	*/
+	const getItemExtent = useEventCallback((index) => {
+		const listEl = listElRef.current;
+		const item = items[index];
+		const visibleItemsEl = getVisibleItemsEl();
+		if (listEl && item !== void 0 && visibleItemsEl && itemResizable) {
+			const key = getKey(item);
+			for (const itemEl of Array.from(visibleItemsEl.children)) if (itemEl.getAttribute("data-virtual-list-item-key") === key) {
+				const rect = itemEl.getBoundingClientRect();
+				const listTop = listEl.getBoundingClientRect().top + listEl.clientTop;
+				return {
+					top: rect.top - listTop + listEl.scrollTop,
+					size: rect.height,
+					measured: true
+				};
+			}
+		}
+		return {
+			top: fenwickTree.sum(index) + getRowsTop(),
+			size: fenwickTree.get(index),
+			measured: !itemResizable
+		};
+	});
+	/** Bumped by every aligned jump: a chain of steps stops when a newer jump has started. */
+	const alignRunRef = useRef(0);
+	/**
+	* One step of an aligned jump: measure the mounted items, work out the exact
+	* `scrollTop` for the item from the DOM, set it, and update the range. If the range changes, the rows it
+	* brings into view are rendered (in a microtask, still before the browser paints) and the next step runs
+	* from the render callback (a layout effect) to measure them; the jump is done when a step finds the item
+	* mounted, no size changed and `scrollTop` already right. Bounded by `MAX_ALIGN_STEPS`. The item is
+	* found by its key at every step: rows inserted above it in between move its index.
+	*/
+	const alignStep = useEventCallback((run, key, align, scrollMarginTop, scrollMarginBottom, remaining) => {
+		const listEl = listElRef.current;
+		const index = keyToIndexRef.current.get(key);
+		if (listEl == null || run !== alignRunRef.current || index === void 0) return;
+		const sizesChanged = measureMountedItems();
+		const { top: itemTop, size: itemSize, measured } = getItemExtent(index);
+		const viewportHeight = listEl.clientHeight;
+		const target = Math.round(getAlignedScrollTop({
+			itemTop,
+			itemSize,
+			viewportHeight,
+			align,
+			scrollMarginTop,
+			scrollMarginBottom,
+			maxScrollTop: listEl.scrollHeight - viewportHeight
+		}));
+		const moved = Math.abs(listEl.scrollTop - target) >= .5;
+		if (moved) listEl.scrollTo({
+			left: listEl.scrollLeft,
+			top: target,
+			behavior: "instant"
+		});
+		viewportRef.current.scrollTop = listEl.scrollTop;
+		if (!moved && !sizesChanged && measured || remaining <= 0) return;
+		updateRange("listScroll", true, () => {
+			alignStep(run, key, align, scrollMarginTop, scrollMarginBottom, remaining - 1);
+		});
+	});
+	/**
+	* `scrollTo({ index | key, align })`. Instant (or "auto"): the aligned steps above, armed as the pending
+	* task like the other instant jumps (item sizes reported after the jump replay it, for one frame plus one
+	* task). Smooth: one scroll to the position worked out from the current layout (estimates for rows not
+	* measured yet), like the smooth index jump. Virtualization off: read from the DOM.
+	*/
+	const scrollToAligned = useEventCallback((index, align, behavior, isReplay, scrollMarginTop, scrollMarginBottom) => {
+		const listEl = listElRef.current;
+		if (listEl == null) return;
+		if (!virtual) {
+			const itemEl = getVisibleItemsEl()?.children.item(index);
+			if (!itemEl) return;
+			const rect = itemEl.getBoundingClientRect();
+			const listTop = listEl.getBoundingClientRect().top + listEl.clientTop;
+			const top = getAlignedScrollTop({
+				itemTop: rect.top - listTop + listEl.scrollTop,
+				itemSize: rect.height,
+				viewportHeight: listEl.clientHeight,
+				align,
+				scrollMarginTop,
+				scrollMarginBottom,
+				maxScrollTop: listEl.scrollHeight - listEl.clientHeight
+			});
+			listEl.scrollTo({
+				left: 0,
+				top: Math.round(top),
+				behavior
+			});
+			return;
+		}
+		const item = items[index];
+		if (item === void 0) return;
+		const key = getKey(item);
+		const smooth = behavior === "smooth";
+		if (!isReplay) {
+			clearPendingScrollTask();
+			if (!smooth) {
+				pendingScrollTaskRef.current = {
+					type: "align",
+					key,
+					align,
+					scrollMarginTop,
+					scrollMarginBottom
+				};
+				schedulePendingScrollTaskExpiry();
+			}
+		}
+		const run = ++alignRunRef.current;
+		if (smooth) {
+			const { top: itemTop, size: itemSize } = getItemExtent(index);
+			const top = getAlignedScrollTop({
+				itemTop,
+				itemSize,
+				viewportHeight: listEl.clientHeight,
+				align,
+				scrollMarginTop,
+				scrollMarginBottom,
+				maxScrollTop: listEl.scrollHeight - listEl.clientHeight
+			});
+			listEl.scrollTo({
+				left: 0,
+				top: Math.round(top),
+				behavior
+			});
+			updateRange("listScroll", true, null);
+			return;
+		}
+		alignStep(run, key, align, scrollMarginTop, scrollMarginBottom, MAX_ALIGN_STEPS);
+	});
+	const scrollTo = useEventCallback((options, topIfNumber) => {
+		if (typeof options == "number") {
+			scrollToPosition(options, topIfNumber, "instant");
+			return;
+		}
+		const { left, top, index, key, position, behavior = "instant", debounce = true, scrollMarginTop = 0, scrollMarginBottom = 0, align } = options;
+		if (left !== void 0 || top !== void 0) scrollToPosition(left, top, behavior);
+		else if (align !== void 0 && (index !== void 0 || key !== void 0)) {
+			const alignIndex = index ?? keyToIndexRef.current.get(key);
+			if (alignIndex !== void 0) scrollToAligned(alignIndex, align, behavior, false, scrollMarginTop, scrollMarginBottom);
+		} else if (index !== void 0) scrollToIndex(index, behavior, debounce, false, scrollMarginTop, scrollMarginBottom);
+		else if (key !== void 0) {
+			const keyIndex = keyToIndexRef.current.get(key);
+			if (keyIndex !== void 0) scrollToIndex(keyIndex, behavior, debounce, false, scrollMarginTop, scrollMarginBottom);
+		} else if (position) {
+			if (virtual) {
+				clearPendingScrollTask();
+				if (behavior === "instant") {
+					pendingScrollTaskRef.current = { type: position };
+					schedulePendingScrollTaskExpiry();
+				}
+			}
+			if (position === "bottom") {
+				scrollToPosition(0, listElRef.current?.scrollHeight || 2e9, behavior);
+				if (virtual) updateRange("listScroll", true, null);
+			} else if (position === "top") scrollToPosition(0, 0, behavior);
+		}
+	});
+	const replayPendingScrollTask = useEventCallback(() => {
+		const task = pendingScrollTaskRef.current;
+		if (task) {
+			if (task.type === "top") scrollToPosition(0, 0, "instant");
+			else if (task.type === "bottom") scrollToPosition(0, listElRef.current?.scrollHeight || 2e9, "instant");
+			else if (task.type === "index") {
+				const index = task.key === void 0 ? task.index : keyToIndexRef.current.get(task.key);
+				if (index !== void 0) scrollToIndex(index, "instant", task.debounce, true);
+			} else if (task.type === "align") {
+				const index = keyToIndexRef.current.get(task.key);
+				if (index === void 0) return;
+				scrollToAligned(index, task.align, "instant", true, task.scrollMarginTop, task.scrollMarginBottom);
+			} else if (task.type === "custom") task.task();
+		}
+	});
+	/**
+	* Runs `task` now (after a range update) and again after every batch of item resizes while it is
+	* armed (one frame plus one task).
+	*/
+	const submitScrollAdjustingTask = useCallback((task) => {
+		clearPendingScrollTask();
+		pendingScrollTaskRef.current = {
+			type: "custom",
+			task
+		};
+		schedulePendingScrollTaskExpiry();
+		updateRange("listScroll", true, replayPendingScrollTask);
+	}, [
+		replayPendingScrollTask,
+		clearPendingScrollTask,
+		schedulePendingScrollTaskExpiry,
+		updateRange
+	]);
+	const syncViewport = useCallback(() => {
+		updateRange("listScroll", false, null);
+	}, [updateRange]);
+	const restoreItemsAnchor = useEventCallback((anchor) => {
+		appliedItemsAnchorRef.current = anchor;
+		rangeRef.current = renderedRange;
+		const listEl = listElRef.current;
+		const index = keyToIndexRef.current.get(anchor.key);
+		const pendingType = pendingScrollTaskRef.current?.type;
+		if (listEl == null || index === void 0 || pendingType !== void 0 && pendingType !== "index" && pendingType !== "align") return;
+		applyLayoutStyles(startIndex);
+		const diff = fenwickTree.sum(index) + anchor.delta + getRowsTop() - (listEl.scrollTop + compensationYRef.current);
+		if (diff !== 0 && !addCompensation(diff)) listEl.scrollBy(0, diff);
+		viewportRef.current.scrollTop = listEl.scrollTop;
+	});
+	useLayoutEffect(() => {
+		if (pendingItemsAnchor !== null && !sessionChangedRef.current) restoreItemsAnchor(pendingItemsAnchor);
+		if (sessionChangedRef.current) {
+			updateRange("sessionChanged", true, replayPendingScrollTask);
+			sessionChangedRef.current = false;
+		} else if (itemResizable) {
+			const heightBefore = listElRef.current?.offsetHeight;
+			applyLayoutStyles(startIndex);
+			if (heightBefore === listElRef.current?.offsetHeight) updateRange("itemsChanged", true, replayPendingScrollTask);
+		} else updateRange("itemsChanged", true, replayPendingScrollTask);
+	}, [
+		sessionId,
+		items,
+		replayPendingScrollTask,
+		updateRange,
+		itemResizable,
+		applyLayoutStyles
+	]);
+	useLayoutEffect(() => {
+		committedLayoutRef.current = {
+			items,
+			tree: fenwickTree,
+			sessionId
+		};
+	});
+	useLayoutEffect(() => {
+		applyLayoutStyles(startIndex);
+		renderCallback?.();
+	}, [
+		renderReason,
+		renderCallback,
+		renderVersion,
+		applyLayoutStyles
+	]);
+	const getOffsetTopOfKey = useEventCallback((key) => {
+		const index = keyToIndexRef.current.get(key);
+		if (index !== void 0) return fenwickTree.sum(index) + getRowsTop();
+	});
+	const refreshListWidth = useCallback(() => {
+		const listEl = listElRef.current;
+		if (listEl) listEl.style.setProperty("--virtual-list-width", `${listEl.offsetWidth}px`);
+	}, [listElRef]);
+	const imperativeApi = useMemo(() => ({
+		listElRef,
+		itemsElRef,
+		scrollTo,
+		syncViewport,
+		getOffsetTopOfKey,
+		submitScrollAdjustingTask,
+		refreshListWidth
+	}), [
+		getOffsetTopOfKey,
+		scrollTo,
+		syncViewport,
+		submitScrollAdjustingTask,
+		refreshListWidth
+	]);
+	useImperativeHandle(componentRef, () => imperativeApi, [imperativeApi]);
+	const itemResizeQueueRef = useRef([]);
+	const enqueueItemResize = useEventCallback((entry) => {
+		itemResizeQueueRef.current.push(entry);
+	});
+	const clearItemResizeQueue = useEventCallback(() => {
+		itemResizeQueueRef.current = [];
+	});
+	const batchResizeScheduledRef = useRef(false);
+	/**
+	* Applies the queued item measurements (in place of the browser's scroll anchoring): the mounted rows
+	* are measured (`measureFlowRun`: all of them, since a row's size depends on its neighbour) and each
+	* size change goes into the Fenwick tree and the key -> offset cache. With no pending scroll task,
+	* the size changes of items measured for the FIRST time among those that entered above the old start
+	* of the range (`prependIndexes`), and of rows above the view, are scrolled away (`scrollBy`, or
+	* through the iOS compensation during a touch scroll); with a pending task, the task is replayed.
+	*/
+	const handleItemBatchResize = useEventCallback(() => {
+		if (!virtual) return;
+		const queue = itemResizeQueueRef.current;
+		if (ignoreItemResize) return;
+		const listElBefore = listElRef.current;
+		const viewTop = listElBefore == null ? 0 : listElBefore.scrollTop + compensationYRef.current - getRowsTop();
+		const viewTopIndex = listElBefore == null ? 0 : fenwickTree.getBound(viewTop);
+		const isFirstOfKey = /* @__PURE__ */ new Map();
+		for (const { key, isFirst } of queue) if (!isFirstOfKey.has(key)) isFirstOfKey.set(key, isFirst);
+		const { resizes, leadingMarginDelta } = measureFlowRun();
+		if (resizes.length === 0 && leadingMarginDelta === 0 && pendingScrollTaskRef.current === null) {
+			clearItemResizeQueue();
+			return;
+		}
+		const scrollTopBefore = listElBefore == null ? 0 : listElBefore.scrollTop;
+		const effectiveTopBefore = scrollTopBefore + compensationYRef.current;
+		applyLayoutStyles(startIndex);
+		const listEl = listElRef.current;
+		let contentMoved = true;
+		if (listEl != null) {
+			const pendingTask = pendingScrollTaskRef.current;
+			if (pendingTask?.type === void 0) {
+				const compensates = (index, key) => key !== void 0 && isFirstOfKey.get(key) === true && prependIndexes.includes(index) || index < viewTopIndex;
+				let compensation = 0;
+				let uncompensated = false;
+				for (const { index, key, delta } of resizes) if (compensates(index, key)) compensation += delta;
+				else if (delta !== 0) uncompensated = true;
+				const firstItem = items[0];
+				if (leadingMarginDelta !== 0 && (viewTop > 0 || compensates(0, firstItem === void 0 ? void 0 : getKey(firstItem)))) compensation += leadingMarginDelta;
+				else if (leadingMarginDelta !== 0) uncompensated = true;
+				if (compensation !== 0) {
+					const remaining = compensation - (listEl.scrollTop - scrollTopBefore);
+					if (remaining !== 0 && !addCompensation(remaining)) listEl.scrollBy(0, remaining);
+				}
+				const effectiveTop = listEl.scrollTop + compensationYRef.current;
+				contentMoved = uncompensated || Math.abs(effectiveTop - (effectiveTopBefore + compensation)) >= 1;
+			} else {
+				onContentResize?.();
+				replayPendingScrollTask();
+			}
+			const viewport = viewportRef.current;
+			viewport.scrollTop = listEl.scrollTop;
+			viewport.scrollLeft = listEl.scrollLeft;
+			if (pendingTask?.type === void 0 && contentMoved) onContentResize?.();
+		} else if (contentMoved) onContentResize?.();
+		clearItemResizeQueue();
+		updateRange("batchItemResize", false, null);
+	});
+	/** Measurements of items that just mounted are applied together, in one microtask. */
+	const scheduleItemBatchResize = useEventCallback(() => {
+		if (!batchResizeScheduledRef.current) {
+			Promise.resolve().then(() => {
+				handleItemBatchResize();
+				batchResizeScheduledRef.current = false;
+			});
+			batchResizeScheduledRef.current = true;
+		}
+	});
+	/**
+	* Ignores scroll events while a flush of the iOS compensation suppresses them; otherwise updates
+	* the range (replaying a pending task) and calls `onScroll`.
+	*/
+	const handleListScroll = useEventCallback((event) => {
+		const scrollTop = event.target.scrollTop;
+		if (!isScrollSuppressedWithForceRestore(scrollTop)) {
+			if (!wheelScrollingRef.current) updateRange("listScroll", false, pendingScrollTaskRef.current ? replayPendingScrollTask : null);
+			onScroll?.(event.nativeEvent);
+		}
+	});
+	/**
+	* With `catchWheel` (and a fine pointer): scrolls by the wheel itself (`preventDefault`, then
+	* `scrollTop +=`) and updates the range at once, so the rows are rendered in the same frame.
+	*/
+	const handleWheel = useEventCallback((wheelEvent) => {
+		if (catchWheel) {
+			if (mayUseWheelRef.current) {
+				const listEl = listElRef.current;
+				if (listEl != null) {
+					const scale = getWheelDeltaScale();
+					const deltaX = wheelEvent.deltaX / scale;
+					const deltaY = wheelEvent.deltaY / scale;
+					if (deltaX === 0 && (listEl.scrollTop === 0 && deltaY <= 0 || listEl.scrollTop + listEl.offsetHeight >= listEl.scrollHeight && deltaY >= 0)) return;
+					wheelEvent.preventDefault();
+					listEl.scrollTop += deltaY;
+					listEl.scrollLeft += deltaX;
+					syncViewport();
+					wheelScrollingRef.current = true;
+					runLatestInNextFrame(() => {
+						wheelScrollingRef.current = false;
+					});
+				}
+			}
+			onWheel?.(wheelEvent);
+		}
+	});
+	useNonPassiveWheel(useCallback(() => listElRef.current, []), handleWheel, catchWheel);
+	const iosCompensationEnabled = isIOS && virtual;
+	const { addCompensation, isScrollSuppressedWithForceRestore } = useIosMomentumCompensation({
+		enabled: iosCompensationEnabled,
+		listElRef,
+		itemsElRef,
+		syncViewport,
+		compensationYRef
+	});
+	/**
+	* The list's own resize: stores its height and width, sets `--virtual-list-width` and updates
+	* the range. Skipped while the list is hidden with `display: none`.
+	*/
+	const handleListResize = useEventCallback((listEl, deferRender) => {
+		if (isHiddenByDisplayNone(listEl)) return;
+		const height = listEl.offsetHeight;
+		const width = listEl.offsetWidth;
+		const viewport = viewportRef.current;
+		if (listElRef.current) listElRef.current.style.setProperty("--virtual-list-width", `${width}px`);
+		if (renderCol == null && renderItemWithCols == null) {
+			if (height === viewport.listHeight) return;
+		} else if (height === viewport.listHeight && width === viewport.listWidth) return;
+		viewport.listHeight = height;
+		viewport.listWidth = width;
+		updateRange("listResize", deferRender, replayPendingScrollTask);
+	});
+	const onListResizeObserved = useEventCallback(({ entry }) => {
+		handleListResize(entry.target, false);
+		onResize?.(entry);
+	});
+	const onListRefUpdated = useEventCallback((el) => {
+		if (el) handleListResize(el, true);
+	});
+	/**
+	* Tracks the row holding focus: focusin finds the row the target is in (the visible-items element's
+	* child it is inside); focusout to an element outside the list releases it, and the range is updated so
+	* the row unmounts if it is out of the range. A focusout to nowhere (`relatedTarget` null) does not
+	* release it: switching to another window or tab fires one while the element keeps focus, and the row
+	* must still be there when the person comes back. When focus did go to the page instead (a click on
+	* nothing focusable), the next range update finds `document.activeElement` outside the list and
+	* releases the row then.
+	*/
+	const handleFocusIn = useEventCallback((event) => {
+		const visibleItemsEl = getVisibleItemsEl();
+		let el = event.target instanceof Element ? event.target : null;
+		while (el !== null && el.parentElement !== visibleItemsEl) el = el.parentElement;
+		focusedKeyRef.current = el?.getAttribute("data-virtual-list-item-key") ?? null;
+	});
+	const handleFocusOut = useEventCallback((event) => {
+		const listEl = listElRef.current;
+		const next = event.relatedTarget;
+		if (listEl === null || next === null || next instanceof Node && listEl.contains(next)) return;
+		if (focusedKeyRef.current !== null) {
+			focusedKeyRef.current = null;
+			updateRange("listScroll", true, null);
+		}
+	});
+	useLayoutEffect(() => {
+		const listEl = listElRef.current;
+		if (listEl === null) return;
+		listEl.addEventListener("focusin", handleFocusIn);
+		listEl.addEventListener("focusout", handleFocusOut);
+		return () => {
+			listEl.removeEventListener("focusin", handleFocusIn);
+			listEl.removeEventListener("focusout", handleFocusOut);
+		};
+	}, [handleFocusIn, handleFocusOut]);
+	useLayoutEffect(() => {
+		if (defaultScrollIndex != null) scrollTo({ index: defaultScrollIndex });
+		else if (defaultScrollKey != null) scrollTo({ key: defaultScrollKey });
+	}, [sessionId]);
+	const itemsContainerStyle = useMemo(() => ({
+		boxSizing: "content-box",
+		width: px(totalColumnsWidth) ?? void 0,
+		paddingTop: px(paddingTop) ?? void 0,
+		...typeof itemsStyle == "object" ? itemsStyle : {}
+	}), [
+		totalColumnsWidth,
+		paddingTop,
+		itemsStyle
+	]);
+	const [keptItemsBefore, keptItemsAfter] = useMemo(() => {
+		if (!virtual) return [EMPTY_ARRAY, EMPTY_ARRAY];
+		const before = [];
+		const after = [];
+		keptKeysRef.current.forEach((key) => {
+			const index = keyToIndexRef.current.get(key);
+			if (index === void 0) return;
+			const item = items[index];
+			if (item !== void 0) {
+				if (index < startIndex) before.push(item);
+				else if (index > endIndex) after.push(item);
+			}
+		});
+		return [before, after];
+	}, [
+		virtual,
+		keptKeysRef.current,
+		items,
+		startIndex,
+		endIndex
+	]);
+	/**
+	* Renders one item. With `itemResizable` it is wrapped in a ResizeObserverWrapper: when the ref is
+	* set the item gets `data-virtual-list-item-key` and is measured in the next microtask batch
+	* (`isFirst`); later sizes come from the ResizeObserver. The React key is `sessionId:key`, so a new
+	* session remounts every item.
+	*/
+	const renderItem = useCallback((item, absolute) => {
+		const key = getKey(item);
+		const index = keyToIndexRef.current.get(key);
+		const reactKey = sessionId !== void 0 ? `${sessionId}:${key}` : key;
+		const absoluteStyle = absolute ? {
+			position: "absolute",
+			top: px(fenwickTree.sum(index) - fenwickTree.sum(startIndex) + firstRowStartRef.current),
+			left: 0,
+			right: 0
+		} : void 0;
+		const colsNode = renderCol != null ? /* @__PURE__ */ jsx(ItemColumns, {
+			index,
+			item
+		}) : void 0;
+		const itemWithColsNode = renderItemWithCols != null ? /* @__PURE__ */ jsx(ItemColumns, {
+			index,
+			item
+		}) : void 0;
+		if (itemResizable) return /* @__PURE__ */ jsx(ResizeObserverWrapper, {
+			simulateRefUpdateTrigger: sessionId,
+			disabled: !virtual,
+			onRefUpdate: (el) => {
+				if (el) {
+					el.setAttribute(ITEM_KEY_ATTR, key);
+					if (!ignoreItemResize && virtual) {
+						enqueueItemResize({
+							key,
+							target: el,
+							isFirst: true
+						});
+						scheduleItemBatchResize();
+					}
+				}
+			},
+			onResize: ({ entry, isFirst }) => {
+				if (!ignoreItemResize) {
+					enqueueItemResize({
+						key,
+						target: entry.target,
+						isFirst
+					});
+					getResizeObserverDelegate().runAfterEntries(handleItemBatchResize);
+				}
+			},
+			children: ({ ref }) => {
+				if (ItemComponent) return /* @__PURE__ */ jsx(ItemComponent, {
+					domRef: ref,
+					item,
+					index,
+					renderedCols: colsNode,
+					renderedItemWithCols: itemWithColsNode,
+					style: absoluteStyle
+				});
+				else if (renderItemChild == null) return;
+				else return renderItemChild({
+					key: void 0,
+					domRef: ref,
+					item,
+					index,
+					renderedCols: colsNode,
+					renderedItemWithCols: itemWithColsNode,
+					style: absoluteStyle
+				});
+			}
+		}, reactKey);
+		else if (ItemComponent) return /* @__PURE__ */ jsx(ItemComponent, {
+			domRef: null,
+			item,
+			index,
+			renderedCols: colsNode,
+			renderedItemWithCols: itemWithColsNode,
+			style: absoluteStyle
+		}, reactKey);
+		else if (renderItemChild == null) return;
+		else return renderItemChild({
+			key: reactKey,
+			domRef: null,
+			item,
+			index,
+			renderedCols: colsNode,
+			renderedItemWithCols: itemWithColsNode,
+			style: absoluteStyle
+		});
+	}, [
+		virtual,
+		getKey,
+		fenwickTree,
+		startIndex,
+		renderCol,
+		renderItemWithCols,
+		itemResizable,
+		sessionId,
+		ignoreItemResize,
+		enqueueItemResize,
+		scheduleItemBatchResize,
+		handleItemBatchResize,
+		ItemComponent,
+		renderItemChild
+	]);
+	const renderInputs = useMemo(() => ({}), [
+		virtual,
+		getKey,
+		renderCol,
+		renderItemWithCols,
+		itemResizable,
+		sessionId,
+		ignoreItemResize,
+		ItemComponent,
+		renderItemChild
+	]);
+	const [flowElements] = useState(() => /* @__PURE__ */ new Map());
+	const renderedVisibleItems = useMemo(() => {
+		const nodes = visibleItems.map((item) => {
+			const key = getKey(item);
+			const index = keyToIndexRef.current.get(key);
+			const cached = flowElements.get(key);
+			if (cached !== void 0 && cached.item === item && cached.index === index && cached.inputs === renderInputs) return cached.node;
+			const node = renderItem(item, false);
+			flowElements.set(key, {
+				item,
+				index,
+				inputs: renderInputs,
+				node
+			});
+			return node;
+		});
+		if (flowElements.size > visibleItems.length) {
+			const inRange = new Set(visibleItems.map(getKey));
+			for (const key of flowElements.keys()) if (!inRange.has(key)) flowElements.delete(key);
+		}
+		return nodes;
+	}, [
+		renderItem,
+		visibleItems,
+		getKey,
+		flowElements,
+		renderInputs
+	]);
+	const renderedKeptBefore = useMemo(() => keptItemsBefore.map((item) => renderItem(item, true)), [renderItem, keptItemsBefore]);
+	const renderedKeptAfter = useMemo(() => keptItemsAfter.map((item) => renderItem(item, true)), [renderItem, keptItemsAfter]);
+	useNonVirtualContentResize(itemsElRef, onContentResize, !virtual);
+	const onContentResizeRef = useLatestRef(onContentResize);
+	const hasItems = items.length !== 0;
+	const footerNode = useMemo(() => typeof footer != "function" ? footer : /* @__PURE__ */ jsx(ResizeObserverWrapper, {
+		onResize: () => {
+			onContentResizeRef.current?.();
+		},
+		onUnmounted: () => {
+			onContentResizeRef.current?.();
+		},
+		children: ({ ref }) => footer({ domRef: ref })
+	}), [footer, onContentResizeRef]);
+	const emptyNode = useMemo(() => typeof empty != "function" ? empty : /* @__PURE__ */ jsx(ResizeObserverWrapper, {
+		onResize: () => {
+			onContentResizeRef.current?.();
+		},
+		onUnmounted: () => {
+			onContentResizeRef.current?.();
+		},
+		children: ({ ref }) => empty({ domRef: ref })
+	}), [empty, onContentResizeRef]);
+	const { snapshotAnchorElementStateAndSaveToRef, restoreScrollStateFromAnchor, clearAnchor } = useScrollAnchor(listElRef, getVisibleItemsEl);
+	useMemoWithPrevious((previous) => {
+		if (!previous || !itemResizable) return;
+		const [wasVirtual, previousSessionId] = previous;
+		if (previousSessionId === sessionId) {
+			if (wasVirtual && !virtual) snapshotAnchorElementStateAndSaveToRef();
+			else {
+				const visibleItemsEl = getVisibleItemsEl();
+				if (!(visibleItemsEl instanceof HTMLElement)) return;
+				const rows = [];
+				for (const el of Array.from(visibleItemsEl.children)) {
+					const key = el.getAttribute(ITEM_KEY_ATTR);
+					if (key !== null && el instanceof HTMLElement) rows.push({
+						el,
+						key
+					});
+				}
+				const { spans, firstStart } = measureRowSpans(visibleItemsEl, rows.map((row) => row.el));
+				if (rows[0] !== void 0 && keyToIndexRef.current.get(rows[0].key) === 0) leadingMarginRef.current = firstStart;
+				rows.forEach(({ key }, i) => {
+					if (recordMeasuredSize(keyToHeightOffsetRef.current, key, spans[i], itemEstimatedSize)) measuredVersionRef.current += 1;
+				});
+			}
+		}
+	}, [virtual, sessionId]);
+	useLayoutEffectWithPrevious((previous) => {
+		if (!itemResizable || !previous) return;
+		const [wasVirtual, previousSessionId] = previous;
+		if (previousSessionId === sessionId && wasVirtual && !virtual) {
+			restoreScrollStateFromAnchor();
+			clearAnchor();
+		}
+	}, [virtual, sessionId]);
+	const { onKeyDown: onKeyboardScroll } = useKeyboardScroll(scrollTo, { pageBottomOcclusion: keyboardPageBottomOcclusion });
+	/** The consumer's `onKeyDown` first: a key it takes (`preventDefault`) does not scroll the list. */
+	const onKeyDown = useCallback((event) => {
+		onNativeKeyDown?.(event);
+		onKeyboardScroll(event);
+	}, [onNativeKeyDown, onKeyboardScroll]);
+	const emptyCentered = items.length === 0 && emptyAlign === "center";
+	const rootClassName = cn("r-virtual-list", columns.length !== 0 && "r-virtual-list--x-scrollable", showScrollbar && "r-virtual-list--show-scrollbar", printable === true && "r-virtual-list--printable", emptyCentered && "r-virtual-list--empty-centered", iosCompensationEnabled && "r-virtual-list--ios-compensation-enabled", className);
+	return /* @__PURE__ */ jsx(ResizeObserverWrapper, {
+		forwardedRef: mergedListRefSetter,
+		onRefUpdate: onListRefUpdated,
+		onResize: onListResizeObserved,
+		children: ({ ref }) => /* @__PURE__ */ jsxs("div", {
+			...nativeProps,
+			"data-slot": "virtual-list",
+			className: rootClassName,
+			style,
+			onScroll: handleListScroll,
+			ref,
+			onKeyDown,
+			tabIndex: focusable ? 0 : -1,
+			children: [
+				header,
+				hasItems ? /* @__PURE__ */ jsx("div", {
+					"data-slot": "virtual-list-items",
+					ref: itemsElRef,
+					className: itemsClassName,
+					style: itemsContainerStyle,
+					children: /* @__PURE__ */ jsx(VirtualListContext.Provider, {
+						value: imperativeApi,
+						children: /* @__PURE__ */ jsx(ColumnsContext.Provider, {
+							value: columnsContextValue,
+							children: createElement(visibleItemsTag, {
+								"data-slot": "virtual-list-visible-items",
+								style: virtual ? VIRTUAL_VISIBLE_ITEMS_STYLE : NON_VIRTUAL_VISIBLE_ITEMS_STYLE,
+								...visibleItemsProps
+							}, ...renderedKeptBefore, ...renderedVisibleItems, ...renderedKeptAfter)
+						})
+					})
+				}, "items") : /* @__PURE__ */ jsx("div", {
+					"data-slot": "virtual-list-empty",
+					className: cn("r-virtual-list__empty", emptyCentered && "r-virtual-list__empty--center"),
+					children: emptyNode
+				}, "empty"),
+				footerNode,
+				paddingBottom ? /* @__PURE__ */ jsx("div", { style: { paddingBottom } }) : null,
+				footerAfterBottomPadding
+			]
+		})
+	});
+}
+//#endregion
+export { VirtualList };