ropav 0.3.1 → 0.5.0

package/dist/composables/use-virtualizer-scroll.js

@@ -1,5 +1,5 @@
 import { Point, Rect, Size } from "../utils/virtualizer-geometry.js";
-import { computed, onScopeDispose, toValue, watch } from "vue";
+import { computed, onScopeDispose, shallowRef, toValue, watch } from "vue";
 //#region src/composables/use-virtualizer-scroll.ts
 /**
 * Measuring the scroll container a virtualizer lives in, ported from React Aria's `useScrollView`.
@@ -30,8 +30,44 @@ var useVirtualizerScroll = (options) => {
 		viewportOffset: new Point(),
 		viewportSize: new Size()
 	};
+	const scrollOffset = shallowRef(new Point());
+	const scrollSize = shallowRef(new Size());
+	const scrollBox = shallowRef({
+		direction: "ltr",
+		paddingInlineStart: 0,
+		paddingTop: 0,
+		scrollsX: false,
+		scrollsY: false
+	});
 	let isMeasuring = false;
 	const getElement = () => toValue(options.element) ?? null;
+	/** Whether an overflow value is one the browser scrolls, rather than clips or lets out. */
+	const scrolls = (overflow) => overflow === "auto" || overflow === "scroll" || overflow === "overlay";
+	/** Reads what the container's style says about it, for the scrollbar drawn against it. */
+	const readBox = (element) => {
+		const style = getComputedStyle(element);
+		const next = {
+			direction: style.direction === "rtl" ? "rtl" : "ltr",
+			paddingInlineStart: Number.parseFloat(style.paddingInlineStart) || 0,
+			paddingTop: Number.parseFloat(style.paddingTop) || 0,
+			scrollsX: scrolls(style.overflowX),
+			scrollsY: scrolls(style.overflowY)
+		};
+		const current = scrollBox.value;
+		if (current.direction !== next.direction || current.paddingInlineStart !== next.paddingInlineStart || current.paddingTop !== next.paddingTop || current.scrollsX !== next.scrollsX || current.scrollsY !== next.scrollsY) scrollBox.value = next;
+	};
+	/** Reads where the element is scrolled to, and how far it could go. */
+	const readScroll = (element) => {
+		const scrollWidth = element.scrollWidth;
+		const scrollHeight = element.scrollHeight;
+		const left = element.scrollLeft;
+		const top = element.scrollTop;
+		state.scrollPosition = new Point(Math.max(0, Math.min(left, scrollWidth - state.size.width)), Math.max(0, Math.min(top, scrollHeight - state.size.height)));
+		if (scrollSize.value.width !== scrollWidth || scrollSize.value.height !== scrollHeight) scrollSize.value = new Size(scrollWidth, scrollHeight);
+		const inlineRange = Math.max(0, scrollWidth - state.size.width);
+		const offset = new Point(Math.sign(left) * Math.min(Math.abs(left), inlineRange), state.scrollPosition.y);
+		if (!scrollOffset.value.equals(offset)) scrollOffset.value = offset;
+	};
 	const updateVisibleRect = () => {
 		const visibleRect = new Rect(state.viewportOffset.x + state.scrollPosition.x, state.viewportOffset.y + state.scrollPosition.y, Math.max(0, Math.min(state.size.width - state.viewportOffset.x, state.viewportSize.width)), Math.max(0, Math.min(state.size.height - state.viewportOffset.y, state.viewportSize.height)));
 		if (visibleRect.area > 0 || state.lastVisibleRect.area > 0) {
@@ -51,14 +87,19 @@ var useVirtualizerScroll = (options) => {
 		if (state.scrollTimeout != null) clearTimeout(state.scrollTimeout);
 		state.scrollTimeout = setTimeout(endScrolling, SCROLL_END_DELAY);
 	};
+	const markScrolling = () => {
+		if (!state.isScrolling) {
+			state.isScrolling = true;
+			options.onScrollStart?.();
+		}
+		scheduleScrollEnd();
+	};
 	const onScroll = (event) => {
 		const element = getElement();
 		const target = event.target;
 		if (!element || !(target instanceof Node) || !target.contains(element)) return;
-		if (target === element) {
-			const contentSize = options.contentSize();
-			state.scrollPosition = new Point(Math.max(0, Math.min(element.scrollLeft, contentSize.width - state.size.width)), Math.max(0, Math.min(element.scrollTop, contentSize.height - state.size.height)));
-		} else {
+		if (target === element) readScroll(element);
+		else {
 			const bounds = element.getBoundingClientRect();
 			const x = bounds.x < 0 ? -bounds.x : 0;
 			const y = bounds.y < 0 ? -bounds.y : 0;
@@ -66,11 +107,16 @@ var useVirtualizerScroll = (options) => {
 			state.viewportOffset = new Point(x, y);
 		}
 		updateVisibleRect();
-		if (!state.isScrolling) {
-			state.isScrolling = true;
-			options.onScrollStart?.();
-		}
-		scheduleScrollEnd();
+		markScrolling();
+	};
+	const scrollTo = (offset) => {
+		const element = getElement();
+		if (!element) return;
+		if (offset.left != null) element.scrollLeft = offset.left;
+		if (offset.top != null) element.scrollTop = offset.top;
+		readScroll(element);
+		updateVisibleRect();
+		markScrolling();
 	};
 	/**
 	* Re-measures the container.
@@ -87,14 +133,17 @@ var useVirtualizerScroll = (options) => {
 		const viewportHeight = window.innerHeight;
 		const viewportChanged = state.viewportSize.width !== viewportWidth || state.viewportSize.height !== viewportHeight;
 		if (viewportChanged) state.viewportSize = new Size(viewportWidth, viewportHeight);
+		readBox(element);
 		const clientWidth = element.clientWidth;
 		const clientHeight = element.clientHeight;
 		if (state.size.width !== clientWidth || state.size.height !== clientHeight || viewportChanged) {
 			state.size = new Size(clientWidth, clientHeight);
+			readScroll(element);
 			updateVisibleRect();
 			options.onSizeChange(state.size);
 			if (element.clientWidth !== clientWidth || element.clientHeight !== clientHeight) {
 				state.size = new Size(element.clientWidth, element.clientHeight);
+				readScroll(element);
 				updateVisibleRect();
 				options.onSizeChange(state.size);
 			}
@@ -104,13 +153,16 @@ var useVirtualizerScroll = (options) => {
 	watch(() => getElement(), (element, _previous, onCleanup) => {
 		if (!element) return;
 		const document = element.ownerDocument;
-		document.addEventListener("scroll", onScroll, true);
+		document.addEventListener("scroll", onScroll, {
+			capture: true,
+			passive: true
+		});
 		window.addEventListener("resize", measure);
 		const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => measure());
 		observer?.observe(element, { box: "border-box" });
 		measure();
 		onCleanup(() => {
-			document.removeEventListener("scroll", onScroll, true);
+			document.removeEventListener("scroll", onScroll, { capture: true });
 			window.removeEventListener("resize", measure);
 			observer?.disconnect();
 		});
@@ -118,6 +170,16 @@ var useVirtualizerScroll = (options) => {
 		flush: "post",
 		immediate: true
 	});
+	watch(() => options.contentSize(), () => {
+		const element = getElement();
+		if (element) readScroll(element);
+	}, { flush: "post" });
+	watch(() => options.scrollAdjustment?.() ?? 0, (adjustment) => {
+		const element = getElement();
+		if (!element || adjustment === 0) return;
+		options.takeScrollAdjustment?.();
+		element.scrollTop += adjustment;
+	}, { flush: "post" });
 	onScopeDispose(() => {
 		if (state.scrollTimeout != null) clearTimeout(state.scrollTimeout);
 	});
@@ -131,7 +193,11 @@ var useVirtualizerScroll = (options) => {
 				width: px(contentSize.width)
 			};
 		}),
-		measure
+		measure,
+		scrollBox: computed(() => scrollBox.value),
+		scrollOffset: computed(() => scrollOffset.value),
+		scrollSize: computed(() => scrollSize.value),
+		scrollTo
 	};
 };
 //#endregion

package/dist/composables/use-virtualizer.d.ts

@@ -11,10 +11,12 @@ import { Rect, Size } from "../utils/virtualizer-geometry.js";
  *
  * Two pieces of upstream are deliberately gone:
  *
- * `ReusableView` and its recycling. React swaps the content of existing elements as they scroll
- * out of view, and defers reordering the DOM until scrolling stops because reordering is what
- * costs. A keyed `v-for` does the same swapping for free here, and it keeps the DOM in
- * collection order at every moment — which is what a screen reader walks.
+ * `ReusableView` as a class. Its idea is kept — see {@link VirtualizerView.slot} — because a
+ * keyed `v-for` on its own cannot spare a window that moved wholesale: every key in it is new, so
+ * every row mounts anew, and a scrollbar dragged across a long collection lands on nothing for as
+ * long as the mounting takes. Reordering is not deferred as React defers it: the rendered set is
+ * kept in collection order at every moment, which is what a screen reader walks, and moving an
+ * element is cheap next to mounting one.
  *
  * The scroll anchor. Upstream calls `UNSTABLE_getScrollAnchorInfo` on the layout, but no layout
  * implements it, so the whole tracker resolves to nothing for every collection in this build.
@@ -22,6 +24,15 @@ import { Rect, Size } from "../utils/virtualizer-geometry.js";
 /** One rendered element: a layout info, what it was built from, and anything nested inside it. */
 export interface VirtualizerView {
     key: VirtualizerKey;
+    /**
+     * The element this view is rendered into, as a number that outlives the key.
+     *
+     * A key that leaves the window frees its slot, and the next key to arrive takes it. A collection
+     * that keys its rendered items by this rather than by `key` keeps the element and its component
+     * when the window moves and changes what they show — which is what makes a window that moved
+     * wholesale cost a screenful of updates rather than a screenful of mounts.
+     */
+    slot: number;
     layoutInfo: LayoutInfo;
     parentKey: VirtualizerKey | null;
     node?: VirtualizerNode;
@@ -48,6 +59,15 @@ export interface UseVirtualizerReturn {
     endScrolling: () => void;
     /** Records a measured size, and lays out again when it moved anything. */
     updateItemSize: (key: VirtualizerKey, size: Size) => void;
+    /**
+     * How far the content under the window has been pushed by rows measured above it.
+     *
+     * Adding this to the scroll offset is what holds the collection still while the rows above it
+     * settle. Nothing here applies it — only whoever owns the scrolling element can.
+     */
+    scrollAdjustment: ComputedRef<number>;
+    /** Reads the accumulated shift and clears it, so it is applied once. */
+    takeScrollAdjustment: () => number;
     getLayoutInfo: (key: VirtualizerKey) => LayoutInfo | null;
     isPersistedKey: (key: VirtualizerKey) => boolean;
 }

package/dist/composables/use-virtualizer.js

@@ -1,5 +1,5 @@
 import { Rect, Size } from "../utils/virtualizer-geometry.js";
-import { OverscanManager } from "../utils/virtualizer-overscan.js";
+import { overscannedRect } from "../utils/virtualizer-overscan.js";
 import { computed, shallowRef } from "vue";
 //#region src/composables/use-virtualizer.ts
 var useVirtualizer = (options) => {
@@ -8,7 +8,7 @@ var useVirtualizer = (options) => {
 	const isScrolling = shallowRef(false);
 	/** Bumped when something outside the reactive inputs invalidates the layout. */
 	const revision = shallowRef(0);
-	const overscan = new OverscanManager();
+	const scrollAdjustment = shallowRef(0);
 	const persistedKeys = () => options.persistedKeys?.() ?? /* @__PURE__ */ new Set();
 	/**
 	* Whether a key, or anything containing it, must stay rendered.
@@ -91,9 +91,33 @@ var useVirtualizer = (options) => {
 		return {
 			contentSize: layout.getContentSize(),
 			layout,
-			layoutInfos: layout.getVisibleLayoutInfos(overscan.getOverscannedRect())
+			layoutInfos: layout.getVisibleLayoutInfos(overscannedRect(rect))
 		};
 	});
+	/** Which slot each key of the last pass held. Plain state: it is history, not something derived. */
+	let slotByKey = /* @__PURE__ */ new Map();
+	let nextSlot = 0;
+	/**
+	* Hands every key in the pass a slot, keeping the one it had.
+	*
+	* The slots of the keys that left are handed out in the order their keys were rendered, to the
+	* arriving keys in the order they will be: a window that moved wholesale therefore keeps every
+	* slot in place, and a window that moved by a row moves one element.
+	*/
+	const assignSlots = (layoutInfos) => {
+		const next = /* @__PURE__ */ new Map();
+		const arriving = [];
+		for (const { key } of layoutInfos) {
+			const slot = slotByKey.get(key);
+			if (slot == null) arriving.push(key);
+			else next.set(key, slot);
+		}
+		const freed = [];
+		for (const [key, slot] of slotByKey) if (!next.has(key)) freed.push(slot);
+		for (const key of arriving) next.set(key, freed.length > 0 ? freed.shift() : nextSlot++);
+		slotByKey = next;
+		return next;
+	};
 	/**
 	* The layout infos arrive parents first, so a child always finds its parent already built. One
 	* whose parent is not in the window is treated as a root rather than dropped — losing it would
@@ -104,13 +128,15 @@ var useVirtualizer = (options) => {
 		const collection = options.collection();
 		const views = /* @__PURE__ */ new Map();
 		const roots = [];
+		const slots = assignSlots(layoutInfos);
 		for (const layoutInfo of layoutInfos) {
 			const view = {
 				children: [],
 				key: layoutInfo.key,
 				layoutInfo,
 				node: collection.getNode(layoutInfo.key),
-				parentKey: layoutInfo.parentKey
+				parentKey: layoutInfo.parentKey,
+				slot: slots.get(layoutInfo.key)
 			};
 			views.set(view.key, view);
 			const parent = layoutInfo.parentKey != null ? views.get(layoutInfo.parentKey) : void 0;
@@ -127,20 +153,28 @@ var useVirtualizer = (options) => {
 		getLayoutInfo: (key) => pass.value.layout.getLayoutInfo(key),
 		isPersistedKey,
 		isScrolling: computed(() => isScrolling.value),
+		scrollAdjustment: computed(() => scrollAdjustment.value),
 		setSize: (next) => {
 			if (!size.value.equals(next)) size.value = next;
 		},
 		setVisibleRect: (rect) => {
 			if (visibleRect.value.equals(rect)) return;
-			overscan.setVisibleRect(rect);
 			visibleRect.value = rect;
 		},
 		size: computed(() => size.value),
 		startScrolling: () => {
 			isScrolling.value = true;
 		},
+		takeScrollAdjustment: () => {
+			const pending = scrollAdjustment.value;
+			scrollAdjustment.value = 0;
+			return pending;
+		},
 		updateItemSize: (key, measured) => {
-			if (!pass.value.layout.updateItemSize?.(key, measured)) return;
+			const layout = attachedLayout ?? pass.value.layout;
+			const placed = layout.getLayoutInfo(key)?.rect;
+			if (!layout.updateItemSize?.(key, measured)) return;
+			if (placed != null && placed.y < visibleRect.value.y) scrollAdjustment.value += measured.height - placed.height;
 			pendingItemSizeChange = true;
 			revision.value += 1;
 		},