ropav 0.3.1 → 0.5.0

package/dist/utils/virtualizer-list-layout.js

@@ -1,6 +1,7 @@
 import { Rect, Size } from "./virtualizer-geometry.js";
 import { LayoutInfo } from "./virtualizer-layout-info.js";
 import { Layout } from "./virtualizer-layout.js";
+import { RowOffsets } from "./virtualizer-offsets.js";
 //#region src/utils/virtualizer-list-layout.ts
 /**
 * A stack layout for the virtualizer, ported from React Aria's `ListLayout`.
@@ -9,14 +10,20 @@ import { Layout } from "./virtualizer-layout.js";
 * minus the padding. With `rowSize` given the geometry is arithmetic; without it each item is
 * placed at an estimate and corrected once it has been measured.
 *
-* The layout is lazy. It computes rows for the region it has been asked about — `requestedRect` —
-* and accounts for everything outside it arithmetically, so a thousand rows cost about as much as
-* a screenful. `validRect` records how much of that region is known-good, which is what lets a
-* measured row survive the next pass instead of being placed at an estimate again.
+* Only the rows a window covers are built, and this is where it parts company with upstream. React
+* Aria records a region it has computed — growing it to cover everywhere the window has been, and
+* walking from the first row to add up offsets on the way — which makes the rendered set a
+* function of where the window has *been* rather than of where it is, and makes a pass cost more
+* the further down the collection it lands.
 *
-* Two things are deliberately absent, both recorded as debt: the horizontal orientation, which no
-* collection in this library uses, and the `section`/`header`/`separator` node types, which cannot
-* reach a layout through the data-driven collection this build has.
+* Here a {@link RowOffsets} index holds a start and a size for every row, measured or estimated,
+* so an offset is a lookup and a window is a binary search. There is no region to be inside of, no
+* cache that can disagree with the current scroll offset, and no row a scrollbar can reach that
+* has no offset to answer with — which is what keeps a fast drag from landing on nothing.
+*
+* Two things are absent, both recorded as debt: the horizontal orientation, which no collection in
+* this library uses, and the `section`/`header`/`separator` node types, which cannot reach a
+* layout through the data-driven collection this build has.
 */
 /** The height React Aria falls back to when neither a fixed nor an estimated size is given. */
 var DEFAULT_ROW_SIZE = 48;
@@ -32,19 +39,19 @@ var ListLayout = class extends Layout {
 	layoutNodes = /* @__PURE__ */ new Map();
 	rootNodes = [];
 	contentSize = new Size();
-	/** The region rows have been computed for. Everything outside it is only accounted for. */
-	requestedRect = new Rect();
-	/** The part of `requestedRect` whose rows are known-good. */
-	validRect = new Rect();
+	/** Where every root sits, whether or not it has ever been built. */
+	offsets = new RowOffsets();
+	/** The window the rendered set was built for, in content coordinates. */
+	window = new Rect();
 	lastCollection = null;
 	invalidateEverything = false;
 	constructor(options = {}) {
 		super();
-		this.rowSize = options.rowSize ?? options.rowHeight ?? null;
-		this.estimatedRowSize = options.estimatedRowSize ?? options.estimatedRowHeight ?? null;
-		this.headingSize = options.headingSize ?? options.headingHeight ?? null;
-		this.estimatedHeadingSize = options.estimatedHeadingSize ?? options.estimatedHeadingHeight ?? null;
-		this.loaderSize = options.loaderSize ?? options.loaderHeight ?? null;
+		this.rowSize = options.rowSize ?? null;
+		this.estimatedRowSize = options.estimatedRowSize ?? null;
+		this.headingSize = options.headingSize ?? null;
+		this.estimatedHeadingSize = options.estimatedHeadingSize ?? null;
+		this.loaderSize = options.loaderSize ?? null;
 		this.gap = options.gap ?? 0;
 		this.padding = options.padding ?? 0;
 		this.dropIndicatorThickness = options.dropIndicatorThickness ?? 2;
@@ -56,12 +63,20 @@ var ListLayout = class extends Layout {
 		this.ensureLayoutInfo(key);
 		return this.layoutNodes.get(key)?.layoutInfo ?? null;
 	}
+	/** Where every root sits, for a caller that needs an offset rather than a rendered node. */
+	getRowOffsets() {
+		return this.offsets;
+	}
 	/**
 	* The rectangle grown to whole rows.
 	*
 	* Without this a one-pixel scroll would change which rows fall inside the rectangle, and the set
-	* of rendered elements would churn on every frame. A table snaps differently — its own row
-	* stride ignores the gap — so this is the one part of the walk a subclass replaces.
+	* of rendered elements would churn on every frame.
+	*
+	* The stride has to be the one rows are actually placed at, gap included, and the height has to
+	* absorb however far the top edge moved. Upstream's table snaps by the bare row height and lets
+	* the bottom edge fall wherever it lands, which costs a gap of coverage per screen — so a window
+	* arrived at by scrolling ends one gap short of where it was asked to reach.
 	*/
 	snapVisibleRect(rect) {
 		if (rect.height <= 1) return rect;
@@ -76,7 +91,7 @@ var ListLayout = class extends Layout {
 	/** Every layout info inside `rect`, snapped to whole rows, parents before children. */
 	getVisibleLayoutInfos(rect) {
 		const searchRect = this.snapVisibleRect(rect);
-		this.layoutIfNeeded(searchRect);
+		this.layoutFor(searchRect);
 		const result = [];
 		const addNodes = (nodes) => {
 			for (const node of nodes) {
@@ -92,47 +107,47 @@ var ListLayout = class extends Layout {
 		const collection = this.host.collection;
 		this.invalidateEverything = this.shouldInvalidateEverything(context);
 		if (this.invalidateEverything) {
-			this.requestedRect = this.host.visibleRect.copy();
 			this.layoutNodes.clear();
+			this.offsets.reset();
 		}
 		const options = context.layoutOptions;
-		this.rowSize = options?.rowSize ?? options?.rowHeight ?? this.rowSize;
-		this.estimatedRowSize = options?.estimatedRowSize ?? options?.estimatedRowHeight ?? this.estimatedRowSize;
-		this.headingSize = options?.headingSize ?? options?.headingHeight ?? this.headingSize;
-		this.estimatedHeadingSize = options?.estimatedHeadingSize ?? options?.estimatedHeadingHeight ?? this.estimatedHeadingSize;
-		this.loaderSize = options?.loaderSize ?? options?.loaderHeight ?? this.loaderSize;
+		this.rowSize = options?.rowSize ?? this.rowSize;
+		this.estimatedRowSize = options?.estimatedRowSize ?? this.estimatedRowSize;
+		this.headingSize = options?.headingSize ?? this.headingSize;
+		this.estimatedHeadingSize = options?.estimatedHeadingSize ?? this.estimatedHeadingSize;
+		this.loaderSize = options?.loaderSize ?? this.loaderSize;
 		this.gap = options?.gap ?? this.gap;
 		this.padding = options?.padding ?? this.padding;
 		this.dropIndicatorThickness = options?.dropIndicatorThickness ?? this.dropIndicatorThickness;
+		if (this.window.area <= 0) this.window = this.host.visibleRect.copy();
 		this.rootNodes = this.buildCollection();
-		if (this.lastCollection && collection !== this.lastCollection) {
-			for (const key of this.lastCollection.keys) if (!collection.getNode(key)) this.layoutNodes.delete(key);
+		if (this.lastCollection && collection !== this.lastCollection) for (const [key, layoutNode] of this.layoutNodes) {
+			const owner = layoutNode.layoutInfo.type === "cell" ? layoutNode.layoutInfo.parentKey : key;
+			if (owner == null || !collection.getNode(owner)) this.layoutNodes.delete(key);
 		}
 		this.lastCollection = collection;
 		this.invalidateEverything = false;
-		this.validRect = this.requestedRect.copy();
 	}
 	shouldInvalidateLayoutOptions(newOptions, oldOptions) {
-		return (newOptions?.rowSize ?? newOptions?.rowHeight) !== (oldOptions?.rowSize ?? oldOptions?.rowHeight) || (newOptions?.estimatedRowSize ?? newOptions?.estimatedRowHeight) !== (oldOptions?.estimatedRowSize ?? oldOptions?.estimatedRowHeight) || (newOptions?.headingSize ?? newOptions?.headingHeight) !== (oldOptions?.headingSize ?? oldOptions?.headingHeight) || (newOptions?.estimatedHeadingSize ?? newOptions?.estimatedHeadingHeight) !== (oldOptions?.estimatedHeadingSize ?? oldOptions?.estimatedHeadingHeight) || (newOptions?.loaderSize ?? newOptions?.loaderHeight) !== (oldOptions?.loaderSize ?? oldOptions?.loaderHeight) || newOptions?.gap !== oldOptions?.gap || newOptions?.padding !== oldOptions?.padding;
+		return newOptions?.rowSize !== oldOptions?.rowSize || newOptions?.estimatedRowSize !== oldOptions?.estimatedRowSize || newOptions?.headingSize !== oldOptions?.headingSize || newOptions?.estimatedHeadingSize !== oldOptions?.estimatedHeadingSize || newOptions?.loaderSize !== oldOptions?.loaderSize || newOptions?.gap !== oldOptions?.gap || newOptions?.padding !== oldOptions?.padding;
 	}
 	/**
 	* Records a row's measured size.
 	*
-	* Returns whether anything moved, which is the virtualizer's cue to lay out again. The rows
-	* below this one are the ones that moved, so the valid region is cut off at this row's offset
-	* rather than thrown away entirely.
+	* Returns whether anything moved, which is the virtualizer's cue to lay out again. The size goes
+	* to the index rather than only onto the rendered node, so the rows below it move even though
+	* none of them is in the window, and so the row keeps its height when the window comes back.
 	*/
 	updateItemSize(key, size) {
 		const layoutNode = this.layoutNodes.get(key);
-		if (!layoutNode) return false;
+		if (!layoutNode || this.rowSize != null) return false;
 		const layoutInfo = layoutNode.layoutInfo;
 		layoutInfo.estimatedSize = false;
 		if (layoutInfo.rect.height === size.height) return false;
 		const measured = layoutInfo.copy();
 		measured.rect.height = size.height;
 		layoutNode.layoutInfo = measured;
-		this.validRect.height = Math.min(this.validRect.height, layoutInfo.rect.y - this.validRect.y);
-		if (layoutNode.node?.type === "item" || layoutNode.node?.type === "row") this.requestedRect.height += measured.rect.height - layoutInfo.rect.height;
+		this.recordMeasuredSize(layoutNode, size.height);
 		this.replaceLayoutInfo(key, layoutInfo, measured);
 		let parentKey = layoutInfo.parentKey;
 		while (parentKey != null) {
@@ -141,36 +156,138 @@ var ListLayout = class extends Layout {
 		}
 		return true;
 	}
+	/**
+	* Hands a measurement to the index, when it is a root that the index places.
+	*
+	* A table's cell is measured too, but a cell does not sit among the roots — its row does, and
+	* the row is measured by its tallest cell, so the row's own measurement is the one that lands.
+	*/
+	recordMeasuredSize(layoutNode, height) {
+		const node = layoutNode.node;
+		if (!node || node.parentKey != null) return;
+		this.offsets.measure(node.key, height, node.index);
+	}
 	shouldInvalidateEverything(context) {
 		const options = context.layoutOptions;
-		return Boolean(context.sizeChanged || this.rowSize !== (options?.rowSize ?? options?.rowHeight ?? this.rowSize) || this.headingSize !== (options?.headingSize ?? options?.headingHeight ?? this.headingSize) || this.loaderSize !== (options?.loaderSize ?? options?.loaderHeight ?? this.loaderSize) || this.gap !== (options?.gap ?? this.gap) || this.padding !== (options?.padding ?? this.padding));
+		return Boolean(context.sizeChanged || this.rowSize !== (options?.rowSize ?? this.rowSize) || this.headingSize !== (options?.headingSize ?? this.headingSize) || this.loaderSize !== (options?.loaderSize ?? this.loaderSize) || this.gap !== (options?.gap ?? this.gap) || this.padding !== (options?.padding ?? this.padding));
+	}
+	/**
+	* The estimated size of a root, which is what the index places it at until it is measured.
+	*/
+	estimatedSizeAt(index) {
+		if (this.host.collection.getNode(this.host.collection.rootKeys[index])?.type === "loader") return this.loaderSize ?? this.rowSize ?? this.estimatedRowSize ?? DEFAULT_ROW_SIZE;
+		return this.rowSize ?? this.estimatedRowSize ?? DEFAULT_ROW_SIZE;
+	}
+	/** How many things the index places. The roots for a list; the body's children for a table. */
+	get placedCount() {
+		return this.host.collection.rootKeys.length;
+	}
+	/** Points the index at the collection as it stands, which is what makes every offset answerable. */
+	configureOffsets(start = this.padding) {
+		const collection = this.host.collection;
+		const rootKeys = collection.rootKeys;
+		this.offsets.configure({
+			collection,
+			count: rootKeys.length,
+			estimate: (index) => this.estimatedSizeAt(index),
+			gap: this.gap,
+			keyAt: (index) => rootKeys[index],
+			start
+		});
+	}
+	/**
+	* The roots that are rendered wherever the window is.
+	*
+	* Loaders, because a sentinel that is not in the DOM can never report that it came into view,
+	* so the next page would never be asked for. Persisted keys, because the roving tab stop lives
+	* on the focused row and losing its element drops focus to the document.
+	*/
+	indicesPlacedOutsideTheWindow() {
+		const collection = this.host.collection;
+		const indices = this.persistedIndices(collection.rootKeys);
+		collection.rootKeys.forEach((key, index) => {
+			if (collection.getNode(key)?.type === "loader") indices.add(index);
+		});
+		return indices;
+	}
+	/**
+	* Where the persisted keys sit among `keys`.
+	*
+	* A persisted key can be a cell as easily as a row — the roving tab stop lives on whichever
+	* element holds focus — and a cell needs its row placed or it has nowhere to live. So a key
+	* that is not one of these walks up until it finds the ancestor that is.
+	*/
+	persistedIndices(keys) {
+		const collection = this.host.collection;
+		const indices = /* @__PURE__ */ new Set();
+		for (const key of this.host.persistedKeys) {
+			let node = collection.getNode(key);
+			while (node && keys[node.index] !== node.key) node = node.parentKey == null ? void 0 : collection.getNode(node.parentKey);
+			if (node) indices.add(node.index);
+		}
+		return indices;
+	}
+	/** Where the row at `index` sits. A lookup, for a row nobody has rendered as much as for one. */
+	rowOffset(index) {
+		return this.offsets.startOf(index);
 	}
-	/** Extends the computed region to cover `rect`, and to cover every persisted key. */
-	layoutIfNeeded(rect) {
+	/**
+	* The root indices the pass places, in order.
+	*
+	* The window plus whatever has to exist outside it. There is nothing to walk to and nothing to
+	* account for afterwards: a row's offset is a lookup, so the rows above and below the window
+	* cost the pass nothing at all.
+	*/
+	windowedIndices(rect) {
+		const indices = this.indicesPlacedOutsideTheWindow();
+		if (rect.area > 0) {
+			const { first, last } = this.offsets.rangeFor(rect.y, rect.height);
+			for (let index = first; index <= last; index += 1) indices.add(index);
+		}
+		return [...indices].filter((index) => index >= 0 && index < this.placedCount).sort((a, b) => a - b);
+	}
+	/** Builds the rendered set for a window, and drops what that window has left behind. */
+	layoutFor(rect) {
 		if (!this.lastCollection) return;
-		if (!this.requestedRect.containsRect(rect)) {
-			this.requestedRect = this.requestedRect.union(rect);
-			this.rootNodes = this.buildCollection();
+		this.window = rect.copy();
+		this.rootNodes = this.buildCollection();
+		this.pruneLayoutNodes();
+	}
+	/**
+	* Drops the rows the window has moved away from.
+	*
+	* Only rows and their cells: a table's header, its columns and its body are placed once and
+	* read by everything else, and a row that something still depends on — the one holding the
+	* roving tab stop — has to keep its element.
+	*/
+	pruneLayoutNodes() {
+		for (const [key, layoutNode] of this.layoutNodes) {
+			const type = layoutNode.node?.type ?? layoutNode.layoutInfo.type;
+			if (type !== "item" && type !== "row" && type !== "cell") continue;
+			if (layoutNode.layoutInfo.rect.intersects(this.window) || this.host.persistedKeys.has(key) || layoutNode.layoutInfo.parentKey != null && this.host.persistedKeys.has(layoutNode.layoutInfo.parentKey)) continue;
+			this.layoutNodes.delete(key);
 		}
-		for (const key of this.host.persistedKeys) if (this.ensureLayoutInfo(key)) return;
 	}
 	/**
-	* Computes the whole layout when a key is asked about that the lazy pass never reached.
+	* Places a key the windowed pass never reached.
 	*
-	* Pressing End, or restoring focus to a selected row, asks about a key at an arbitrary offset;
-	* there is no way to know where it sits without laying out everything above it.
+	* Pressing End, or restoring focus to a selected row, asks about a key at an arbitrary offset.
+	* That offset is a lookup whatever the rows are, so the one row is placed and nothing else is.
 	*/
 	ensureLayoutInfo(key) {
-		if (this.layoutNodes.has(key) || !this.lastCollection || this.requestedRect.area >= this.contentSize.area) return false;
-		this.requestedRect = new Rect(0, 0, Infinity, Infinity);
-		this.rootNodes = this.buildCollection();
-		this.requestedRect = new Rect(0, 0, this.contentSize.width, this.contentSize.height);
-		return true;
+		if (this.layoutNodes.has(key) || !this.lastCollection) return;
+		const node = this.lastCollection.getNode(key);
+		const offset = node == null ? null : this.indexedOffset(node);
+		if (node == null || offset == null) return;
+		this.buildChild(node, this.padding, offset, node.parentKey);
+	}
+	/** Where the index puts a node, or `null` for one it does not place. */
+	indexedOffset(node) {
+		return node.parentKey == null ? this.rowOffset(node.index) : null;
 	}
 	replaceLayoutInfo(key, oldLayoutInfo, newLayoutInfo) {
 		const layoutNode = this.layoutNodes.get(key);
 		if (!layoutNode) return;
-		layoutNode.validRect = layoutNode.validRect.intersection(this.validRect);
 		if (layoutNode.layoutInfo === oldLayoutInfo) layoutNode.layoutInfo = newLayoutInfo;
 	}
 	buildCollection(offset = this.padding) {
@@ -178,39 +295,12 @@ var ListLayout = class extends Layout {
 		const rootKeys = collection.rootKeys;
 		const nodes = [];
 		const isEmpty = collection.itemCount === 0;
-		const rowStride = (this.rowSize ?? this.estimatedRowSize ?? DEFAULT_ROW_SIZE) + this.gap;
-		const pendingLoaderKeys = rootKeys.filter((key) => collection.getNode(key)?.type === "loader");
-		let y = isEmpty ? 0 : offset;
-		for (const [index, key] of rootKeys.entries()) {
-			const node = collection.getNode(key);
-			if (!node) continue;
-			const isRow = node.type === "item" || node.type === "row";
-			if (isRow && y + rowStride < this.requestedRect.y && !this.isValid(node, y)) {
-				y += rowStride;
-				continue;
-			}
-			const layoutNode = this.buildChild(node, this.padding, y, null);
-			y = layoutNode.layoutInfo.rect.maxY + this.gap;
-			nodes.push(layoutNode);
-			if (node.type === "loader") pendingLoaderKeys.splice(pendingLoaderKeys.indexOf(key), 1);
-			if (!(isRow || node.type === "loader") || y <= this.requestedRect.maxY) continue;
-			let lastIndex = index;
-			for (const loaderKey of pendingLoaderKeys) {
-				const loaderNode = collection.getNode(loaderKey);
-				if (!loaderNode) continue;
-				const loaderIndex = rootKeys.indexOf(loaderKey);
-				y += (loaderIndex - lastIndex - 1) * rowStride;
-				const loader = this.buildChild(loaderNode, this.padding, y, null);
-				nodes.push(loader);
-				y = loader.layoutInfo.rect.maxY;
-				lastIndex = loaderIndex;
-			}
-			y += (rootKeys.length - lastIndex - 1) * rowStride;
-			break;
+		this.configureOffsets(offset);
+		for (const index of this.windowedIndices(this.window)) {
+			const node = collection.getNode(rootKeys[index]);
+			if (node) nodes.push(this.buildChild(node, this.padding, this.offsets.startOf(index), null));
 		}
-		y = Math.max(y - this.gap, 0);
-		y += isEmpty ? 0 : this.padding;
-		this.contentSize = new Size(this.host.size.width, y);
+		this.contentSize = new Size(this.host.size.width, isEmpty ? 0 : this.offsets.total() + this.padding);
 		return nodes;
 	}
 	buildChild(node, x, y, parentKey) {
@@ -231,37 +321,31 @@ var ListLayout = class extends Layout {
 	}
 	buildItem(node, x, y) {
 		const width = this.host.size.width - this.padding - x;
+		const previous = this.layoutNodes.get(node.key);
 		let height = this.rowSize;
 		let isEstimated = false;
 		if (height == null) {
-			const previous = this.layoutNodes.get(node.key);
-			if (previous) {
-				height = previous.layoutInfo.rect.height;
-				isEstimated = width !== previous.layoutInfo.rect.width || node !== previous.node || previous.layoutInfo.estimatedSize;
-			} else {
-				height = this.estimatedRowSize;
-				isEstimated = true;
-			}
+			height = this.offsets.size(node.index);
+			isEstimated = !this.offsets.isMeasured(node.index) || previous != null && (width !== previous.layoutInfo.rect.width || node !== previous.node);
 		}
 		const layoutInfo = new LayoutInfo(node.type, node.key, new Rect(x, y, width, height ?? DEFAULT_ROW_SIZE));
 		layoutInfo.estimatedSize = isEstimated;
 		return {
 			children: [],
 			layoutInfo,
-			node,
-			validRect: layoutInfo.rect.intersection(this.requestedRect)
+			node
 		};
 	}
 	/**
 	* Whether a cached row can be reused as it stands.
 	*
-	* Everything here has to hold: nothing global was invalidated, the datum is the same object,
-	* the row is at the same offset, it sits inside the known-good region, and the part of it that
-	* was computed covers the part now being asked about.
+	* Three things: nothing global was invalidated, the datum is the same object, and the row is
+	* still at the same offset. There is no region to be inside of any more — a row's offset comes
+	* from the index, so being at the offset the index gives it *is* the whole of being current.
 	*/
 	isValid(node, y) {
 		const cached = this.layoutNodes.get(node.key);
-		return !this.invalidateEverything && !!cached && cached.node === node && cached.layoutInfo.rect.y === y && cached.layoutInfo.rect.intersects(this.validRect) && cached.validRect.containsRect(cached.layoutInfo.rect.intersection(this.requestedRect));
+		return !this.invalidateEverything && !!cached && cached.node === node && cached.layoutInfo.rect.y === y;
 	}
 	buildLoader(node, x, y) {
 		const width = this.host.size.width - this.padding - x;
@@ -271,8 +355,7 @@ var ListLayout = class extends Layout {
 		return {
 			children: [],
 			layoutInfo,
-			node,
-			validRect: layoutInfo.rect.intersection(this.requestedRect)
+			node
 		};
 	}
 	/**

package/dist/utils/virtualizer-offsets.d.ts

@@ -0,0 +1,111 @@
+import type { VirtualizerKey } from "./virtualizer-layout-info.js";
+/**
+ * Where every row of a collection sits, whether or not anyone has rendered it.
+ *
+ * A windowed layout has to answer two questions on every scroll — which rows the window covers,
+ * and how tall the whole collection is — and both have to be answerable for a row that has never
+ * been in the DOM. React Aria answers them by walking: a row's offset is the total of the rows
+ * above it, so the pass adds that total up from the top, and a region records how far it got. That
+ * makes what is rendered a function of where the window has *been* rather than of where it is, and
+ * it makes a pass cost more the further down it lands.
+ *
+ * This is the other way round. Every row gets a start and a size in one flat array, taking the
+ * measured size where there is one and the estimate where there is not — so an index always has an
+ * offset, an offset always has an index, and the window is a binary search rather than a walk.
+ * There is no region, nothing to invalidate, and nothing that can disagree with the current scroll
+ * offset.
+ *
+ * The array is rebuilt from the lowest index a measurement disturbed, because a row's start is the
+ * previous row's end: everything above the change is still right, everything below it moved.
+ */
+export interface RowOffsetsOptions {
+    /** How many rows there are. */
+    count: number;
+    /** The key of the row at an index. A measurement is held by key, so it survives a reorder. */
+    keyAt: (index: number) => VirtualizerKey;
+    /** How tall the row at an index is before anything has measured it. */
+    estimate: (index: number) => number;
+    /**
+     * What the rows came from. Anything at all, compared by identity: two collections of the same
+     * length can hold different rows, and a size held by key would then be read for the wrong index.
+     */
+    collection?: unknown;
+    /** Where the first row starts — the padding, or whatever is stacked above the rows. */
+    start?: number;
+    /** The space between two rows, which sits between them and not after the last. */
+    gap?: number;
+}
+/** The rows a window covers, as a closed range of indices. */
+export interface RowRange {
+    first: number;
+    last: number;
+}
+export declare class RowOffsets {
+    private count;
+    private keyAt;
+    private estimate;
+    private start;
+    private gap;
+    /** The measured sizes, by key rather than by index so a reorder keeps them. */
+    private sizes;
+    /** `[start, size]` per row. Longer than `count` when the collection has shrunk. */
+    private flat;
+    /** The lowest index whose start may have moved, or `count` when nothing has. */
+    private dirtyFrom;
+    private collection;
+    /**
+     * Takes the shape of the collection.
+     *
+     * The measurements survive as long as the keys can still be asked for — a row that scrolled out
+     * of the window and back in is the same row, and re-measuring it would place it at an estimate
+     * for a frame first.
+     */
+    configure(options: RowOffsetsOptions): void;
+    /** Forgets every measurement, which is what a resize does — a row's height follows its width. */
+    reset(): void;
+    /**
+     * Records a measured size.
+     *
+     * Returns whether anything moved, which is the caller's cue to lay out again. Measuring the same
+     * height twice moves nothing, and that is what keeps measurement from looping.
+     */
+    measure(key: VirtualizerKey, size: number, index?: number): boolean;
+    /** Whether the row at an index has been measured, rather than placed at its estimate. */
+    isMeasured(index: number): boolean;
+    /** Marks the row at an index, and everything below it, as sitting somewhere new. */
+    invalidateFrom(index: number): void;
+    size(index: number): number;
+    /** Where the row at an index starts. Answers for a row nobody has rendered. */
+    startOf(index: number): number;
+    endOf(index: number): number;
+    /** How tall every row together comes to, the gaps between them included. */
+    total(): number;
+    /**
+     * The row whose band contains an offset, clamped to the collection.
+     *
+     * A row ending exactly on the offset counts as being above it, which is the edge rule the whole
+     * window turns on: a rectangle snapped to a row boundary would otherwise take in the row above.
+     */
+    indexAt(offset: number): number;
+    /**
+     * The rows a window covers, plus `overscan` of them either side.
+     *
+     * Closed at both ends: `last` is a row, not the one past it.
+     *
+     * Both ends are clamped into the collection, so a window that outran the data comes back with
+     * the rows nearest to it rather than with nothing. That is the property the whole thing turns
+     * on: there is no offset a scrollbar can reach that has no rows to answer with.
+     *
+     * An empty collection is the one range that holds nothing, and it says so with `last` below
+     * `first` rather than by naming a row that is not there.
+     */
+    rangeFor(offset: number, length: number, overscan?: number): RowRange;
+    /**
+     * Fills in the starts from the lowest one a measurement disturbed.
+     *
+     * Every row below a size that changed sits somewhere new, so there is no shortcut past them —
+     * but this is a loop over a typed array with no allocation in it, which is why a hundred thousand
+     * rows can afford to be re-added on the frame a row is measured.
+     */
+    private build;
+}