ropav 0.4.0 → 0.5.0

package/dist/composables/use-slider-thumb.js

@@ -1,7 +1,7 @@
+import { useMove } from "./use-move.js";
 import { useFormReset } from "./use-form-reset.js";
 import { setFormValue } from "../utils/form-value.js";
 import { clamp } from "../utils/number.js";
-import { useMove } from "./use-move.js";
 import { computed, nextTick, onScopeDispose, toValue, watch, watchEffect } from "vue";
 //#region src/composables/use-slider-thumb.ts
 /**
@@ -110,7 +110,7 @@ var useSliderThumb = (options) => {
 		nextTick(() => {
 			setFormValue(inputEl.value, String(state.getThumbValue(index.value)));
 		});
-	});
+	}, options.form);
 	watch([inputEl, () => state.getThumbValue(index.value)], ([input, value]) => setFormValue(input, String(value)), {
 		flush: "post",
 		immediate: true

package/dist/composables/use-slider.js

@@ -1,6 +1,6 @@
 import { setInteractionModality } from "./use-interaction-states.js";
-import { clamp } from "../utils/number.js";
 import { useMove } from "./use-move.js";
+import { clamp } from "../utils/number.js";
 import { computed, onScopeDispose, toValue } from "vue";
 //#region src/composables/use-slider.ts
 /**

package/dist/composables/use-tab-list-state.d.ts

@@ -1,25 +1,11 @@
-import type { CollectionKey, UseCollectionReturn } from "./use-collection.js";
-import type { UseSelectionManagerReturn } from "./use-selection-manager.js";
+import type { CollectionKey } from "./use-collection.js";
+import type { UseSingleSelectListStateOptions, UseSingleSelectListStateReturn } from "./use-single-select-list-state.js";
 import type { ComputedRef, MaybeRefOrGetter } from "vue";
-export interface UseTabListStateOptions {
-    /** The selected tab, when the caller drives it. */
-    selectedKey?: MaybeRefOrGetter<CollectionKey | undefined>;
-    /** The initially selected tab. Falls back to the first tab that is not disabled. */
-    defaultSelectedKey?: CollectionKey;
-    onSelectionChange?: (key: CollectionKey) => void;
-    disabledKeys?: MaybeRefOrGetter<Iterable<CollectionKey> | undefined>;
-    /** Whether the whole tab list is disabled: a selection that exists but cannot be changed. */
-    isDisabled?: MaybeRefOrGetter<boolean | undefined>;
+export interface UseTabListStateOptions extends UseSingleSelectListStateOptions {
     /** A base the tab and panel ids are derived from. Generated when absent. */
     id?: MaybeRefOrGetter<string | undefined>;
 }
-export interface UseTabListStateReturn {
-    collection: UseCollectionReturn;
-    selection: UseSelectionManagerReturn;
-    /** The selected tab, with the default resolved against the collection. */
-    selectedKey: ComputedRef<CollectionKey | null>;
-    setSelectedKey: (key: CollectionKey) => void;
-    isDisabled: ComputedRef<boolean>;
+export interface UseTabListStateReturn extends UseSingleSelectListStateReturn {
     /** The tab list's own id, which the tab and panel ids hang off. */
     tabsId: ComputedRef<string>;
     /** `undefined` for a key that does not exist, so no attribute points at nothing. */
@@ -39,17 +25,12 @@ export interface UseTabListStateReturn {
 /**
  * Which tab is selected, and the ids that tie each tab to its panel.
  *
- * Ported from React Stately's `useTabListState` and the `useSingleSelectListState` layer beneath
- * it (`react-stately/src/tabs/useTabListState.ts`, react-stately 3.49.0), together with the id
- * scheme from `react-aria/src/tabs/utils.ts` (react-aria 3.51.0).
+ * Ported from React Stately's `useTabListState` (`react-stately/src/tabs/useTabListState.ts`,
+ * react-stately 3.49.0), together with the id scheme from `react-aria/src/tabs/utils.ts`
+ * (react-aria 3.51.0).
  *
- * A tab list always has exactly one tab selected, which is `disallowEmptySelection` plus a
- * fallback for the case where nothing says which. The selection behaviour is deliberately left at
- * toggle: whether the arrow keys choose is a question about how activation works, asked by the
- * caller through `selectOnFocus`, not a question about what a press means.
- *
- * The three pieces have to be built in one order — the collection, then the fallback that reads
- * it, then the selection manager the fallback feeds — which is the reason this is a composable
- * rather than a few lines in the root component.
+ * The selection itself is {@link useSingleSelectListState}, the layer React Stately builds this
+ * one on. What is left here is what makes a tab list a tab list rather than any other list with
+ * one selection: the ids, and the panels they point at.
  */
 export declare const useTabListState: (options?: UseTabListStateOptions) => UseTabListStateReturn;

package/dist/composables/use-tab-list-state.js

@@ -1,113 +1,27 @@
 import { useId as useId$1 } from "./use-id.js";
-import { useControllableState } from "./use-controllable-state.js";
-import { useCollection } from "./use-collection.js";
-import { useSelectionManager } from "./use-selection-manager.js";
-import { computed, shallowRef, toValue, watch } from "vue";
+import { useSingleSelectListState } from "./use-single-select-list-state.js";
+import { shallowRef, toValue } from "vue";
 //#region src/composables/use-tab-list-state.ts
 /**
 * Which tab is selected, and the ids that tie each tab to its panel.
 *
-* Ported from React Stately's `useTabListState` and the `useSingleSelectListState` layer beneath
-* it (`react-stately/src/tabs/useTabListState.ts`, react-stately 3.49.0), together with the id
-* scheme from `react-aria/src/tabs/utils.ts` (react-aria 3.51.0).
+* Ported from React Stately's `useTabListState` (`react-stately/src/tabs/useTabListState.ts`,
+* react-stately 3.49.0), together with the id scheme from `react-aria/src/tabs/utils.ts`
+* (react-aria 3.51.0).
 *
-* A tab list always has exactly one tab selected, which is `disallowEmptySelection` plus a
-* fallback for the case where nothing says which. The selection behaviour is deliberately left at
-* toggle: whether the arrow keys choose is a question about how activation works, asked by the
-* caller through `selectOnFocus`, not a question about what a press means.
-*
-* The three pieces have to be built in one order — the collection, then the fallback that reads
-* it, then the selection manager the fallback feeds — which is the reason this is a composable
-* rather than a few lines in the root component.
+* The selection itself is {@link useSingleSelectListState}, the layer React Stately builds this
+* one on. What is left here is what makes a tab list a tab list rather than any other list with
+* one selection: the ids, and the panels they point at.
 */
 var useTabListState = (options = {}) => {
-	const collection = useCollection();
-	const disabledKeySet = computed(() => new Set(toValue(options.disabledKeys) ?? []));
-	/**
-	* Whether a tab can be selected, asked of the collection rather than of the selection manager.
-	*
-	* Two reasons, and either alone would be enough: the fallback below runs before the manager
-	* exists, and React Stately asks the same question the same way — an item's own disabled state
-	* or the group's disabled keys, with no `disabledBehavior` in it.
-	*/
-	const isKeyDisabled = (key) => disabledKeySet.value.has(key) || Boolean(collection.getItem(key)?.isDisabled());
-	/** The first tab that can be selected, or the first tab when none of them can. */
-	const findDefaultSelectedKey = () => {
-		let key = collection.getFirstKey();
-		while (key != null && isKeyDisabled(key) && key !== collection.getLastKey()) key = collection.getKeyAfter(key);
-		if (key != null && isKeyDisabled(key) && key === collection.getLastKey()) key = collection.getFirstKey();
-		return key;
-	};
-	const stored = useControllableState({
-		defaultValue: options.defaultSelectedKey ?? null,
-		onValueChange: (key) => {
-			if (key != null) options.onSelectionChange?.(key);
-		},
-		value: () => toValue(options.selectedKey)
-	});
-	/**
-	* The selected tab, with the fallback resolved as a read rather than written back.
-	*
-	* React Stately can resolve it before the first render, because the collection is built by a
-	* pass that runs before it. Rendering is what creates the collection here, so writing the
-	* fallback into the selection would report a selection change nobody made, on every mount of
-	* every uncontrolled tab list.
-	*
-	* `collection.size` is read for its own sake: the fallback walks the collection through
-	* calls that stay outside reactivity on purpose, so without it this would resolve against the
-	* empty collection of the first render and keep that answer.
-	*/
-	const selectedKey = computed(() => {
-		const key = stored.state.value;
-		if (stored.isControlled.value) return key ?? null;
-		if (key != null && collection.getItem(key)) return key;
-		return findDefaultSelectedKey();
-	});
-	const selection = useSelectionManager({
-		collection,
-		disabledKeys: () => toValue(options.disabledKeys),
-		disallowEmptySelection: true,
-		onSelectionChange: (keys) => {
-			if (keys === "all") return;
-			const [key] = [...keys];
-			if (key != null) stored.setState(key);
-		},
-		selectedKeys: () => selectedKey.value != null ? [selectedKey.value] : [],
-		selectionMode: "single"
-	});
-	let lastSelectedKey = selectedKey.value;
-	/**
-	* The selection places focus, because on a tab list it is the only thing that can.
-	*
-	* React Aria's tab list element ends up with no tab index of its own, so the roving index on
-	* the selected tab is the only way in — and with no focused key nothing inside is tabbable
-	* either, which would put the whole tab list out of the tab order.
-	*
-	* Post-flush and keyed on the collection's size, because setting a focused key the collection
-	* does not hold is refused: the first attempt runs before the tabs have registered, and the
-	* registration is what makes the retry land.
-	*/
-	watch([
-		selectedKey,
-		collection.size,
-		() => selection.focusedKey.value == null
-	], () => {
-		const key = selectedKey.value;
-		if (key == null) return;
-		if (selection.focusedKey.value == null || !selection.isFocused.value && key !== lastSelectedKey) selection.setFocusedKey(key);
-		lastSelectedKey = key;
-	}, {
-		flush: "post",
-		immediate: true
-	});
+	const list = useSingleSelectListState(options);
 	const tabsId = useId$1(() => toValue(options.id));
 	/** React Aria strips whitespace out of a string key so the id stays a single token. */
 	const idFor = (key, role) => key == null ? void 0 : `${tabsId.value}-${role}-${String(key).replace(/\s+/g, "")}`;
 	const panelKeys = shallowRef(/* @__PURE__ */ new Set());
 	return {
-		collection,
+		...list,
 		hasPanel: (key) => key != null && panelKeys.value.has(key),
-		isDisabled: computed(() => Boolean(toValue(options.isDisabled))),
 		registerPanel: (key) => {
 			panelKeys.value = new Set(panelKeys.value).add(key);
 			return () => {
@@ -116,9 +30,6 @@ var useTabListState = (options = {}) => {
 				panelKeys.value = next;
 			};
 		},
-		selectedKey,
-		selection,
-		setSelectedKey: (key) => stored.setState(key),
 		tabId: (key) => idFor(key, "tab"),
 		tabPanelId: (key) => idFor(key, "tabpanel"),
 		tabsId

package/dist/composables/use-text-field.js

@@ -91,7 +91,7 @@ var useTextField = (options = {}) => {
 		reassert();
 	};
 	const initialValue = value.value;
-	if (!options.skipFormReset) useFormReset(element, () => toValue(options.defaultValue) ?? initialValue, setState);
+	if (!options.skipFormReset) useFormReset(element, () => toValue(options.defaultValue) ?? initialValue, setState, options.form);
 	useFormValidation(element, validation, { commitOnBlur: () => toValue(options.commitOnBlur) });
 	watch(element, (control, previous) => {
 		if (control && !previous && toValue(options.autoFocus)) control.focus();

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

@@ -1,22 +1,72 @@
 import type { Size } from "../utils/virtualizer-geometry.js";
 import type { ComputedRef, MaybeRefOrGetter } from "vue";
-import { Rect } from "../utils/virtualizer-geometry.js";
+import { Point, Rect } from "../utils/virtualizer-geometry.js";
 export interface UseVirtualizerScrollOptions {
     /** The element that scrolls — the collection itself. */
     element: MaybeRefOrGetter<HTMLElement | null | undefined>;
-    /** The size of everything the layout produced, used to clamp an over-scroll. */
+    /** The size of everything the layout produced, which is what gives the container its scroll. */
     contentSize: () => Size;
     /** Whether the collection is mid-scroll, which the content wrapper turns off pointers for. */
     isScrolling: () => boolean;
     onVisibleRectChange: (rect: Rect) => void;
     onSizeChange: (size: Size) => void;
+    /**
+     * How far rows measured above the window have pushed the content under it, and a way to say the
+     * shift has been applied.
+     *
+     * Rows of a height nobody declared are placed at an estimate and corrected once they are in the
+     * DOM. A correction above the window moves everything below it — so without putting the shift
+     * back into the scroll offset, the collection slides under the pointer while it is read.
+     */
+    scrollAdjustment?: () => number;
+    takeScrollAdjustment?: () => number;
     onScrollStart?: () => void;
     onScrollEnd?: () => void;
 }
+/** Where to scroll the container to. An axis left out stays where it is. */
+export interface ScrollToOffset {
+    left?: number;
+    top?: number;
+}
+/** What the container's own style says about it, as far as a scrollbar drawn for it has to know. */
+export interface ScrollBoxInfo {
+    /** Which way the inline axis runs, which decides which edge the content starts at. */
+    direction: "ltr" | "rtl";
+    /** How far the content sits in from the container's top edge. */
+    paddingTop: number;
+    /** How far the content sits in from the container's inline start edge. */
+    paddingInlineStart: number;
+    /** Whether the container scrolls along the inline axis, rather than clipping or letting content out. */
+    scrollsX: boolean;
+    /** Whether the container scrolls along the block axis. */
+    scrollsY: boolean;
+}
 export interface UseVirtualizerScrollReturn {
     /** The style for the wrapper that gives the container something to scroll. */
     contentStyle: ComputedRef<Record<string, string | undefined>>;
     /** Re-measures the container. Called on mount, on resize, and by tests. */
     measure: () => void;
+    /** The container's padding and which of its axes scroll, read whenever it is measured. */
+    scrollBox: ComputedRef<ScrollBoxInfo>;
+    /**
+     * How far the container is scrolled, as the element reports it.
+     *
+     * Along the block axis the offset is clamped into the content, as the visible rectangle is.
+     * Along the inline axis it keeps its sign: a right-to-left box scrolls into negative offsets,
+     * and a scrollbar drawn for it has to know which way the content ran.
+     */
+    scrollOffset: ComputedRef<Point>;
+    /** The container's scrollable overflow, per axis — what the offset runs up to, less the box. */
+    scrollSize: ComputedRef<Size>;
+    /**
+     * Scrolls the container from here, and moves the window in the same task.
+     *
+     * A scroll the browser makes on its own reaches this composable a frame after the offset moved,
+     * and the compositor has already drawn that frame with the rows built for the old offset. A
+     * scroll made here is read back at once, so the offset and the rows it calls for are committed
+     * by the same frame — which is what lets a scrollbar the collection draws itself never show an
+     * empty window.
+     */
+    scrollTo: (offset: ScrollToOffset) => void;
 }
 export declare const useVirtualizerScroll: (options: UseVirtualizerScrollOptions) => UseVirtualizerScrollReturn;

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;
 		},