ropav 0.3.1 → 0.5.0

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

@@ -7,6 +7,14 @@ export interface UseMenuOptions {
     id?: MaybeRefOrGetter<string | undefined>;
     /** The id of the element naming the menu, normally the trigger. */
     labelledBy?: MaybeRefOrGetter<string | undefined>;
+    /**
+     * Names the menu when there is no element to point `labelledBy` at.
+     *
+     * A menu inside a trigger is named by it and never needs this; a menu standing on its own has
+     * nothing to borrow a name from, and a name is not something axe checks for `role="menu"` — so
+     * without a string to pass, a standalone menu ships unnamed and nothing says so.
+     */
+    label?: MaybeRefOrGetter<string | undefined>;
     selectionMode?: MaybeRefOrGetter<SelectionMode | undefined>;
     selectionBehavior?: MaybeRefOrGetter<SelectionBehavior | undefined>;
     selectedKeys?: MaybeRefOrGetter<"all" | Iterable<CollectionKey> | undefined>;
@@ -33,6 +41,8 @@ export interface UseMenuReturn {
     collectionId: ComputedRef<string>;
     /** Attributes the menu element renders, beside its own class and `data-slot`. */
     menuAttributes: ComputedRef<Record<string, string | number | boolean | undefined>>;
+    /** Attributes the wrapper around the empty slot renders. */
+    emptyAttributes: ComputedRef<Record<string, string | number | boolean | undefined>>;
     onKeydown: (event: KeyboardEvent) => void;
     onKeydownCapture: (event: KeyboardEvent) => void;
     onFocusin: (event: FocusEvent) => void;

package/dist/composables/use-menu.js

@@ -84,8 +84,30 @@ var useMenu = (options = {}) => {
 	return {
 		collectionId,
 		element,
+		/**
+		* The empty slot is a disabled item of the menu, not a bare wrapper inside it.
+		*
+		* `role="menu"` may only own `menuitem`, `menuitemradio`, `menuitemcheckbox` or `group`, and
+		* the empty state's content is the caller's, carrying no role at all. A `presentation` wrapper
+		* does not help: it flattens out of the tree, so what the menu ends up owning is that content
+		* — which is why the virtualizer's `presentation` wrapper is fine and this one was not. It
+		* holds real items; this holds prose.
+		*
+		* Measured against axe: `presentation`, `none`, `status`, `group` alone and a bare `div` all
+		* fail, while a disabled `menuitem` passes — and so does a menu with no children whatsoever. It
+		* is the unallowed child that breaks it rather than the missing item.
+		*
+		* A disabled item is also the truer reading. The menu still is a menu, it has one thing in it,
+		* and that thing says there is nothing to choose and cannot be chosen. It never registers with
+		* the collection, so the keyboard never reaches it either.
+		*/
+		emptyAttributes: computed(() => ({
+			"aria-disabled": true,
+			role: "menuitem"
+		})),
 		isEmpty: computed(() => collection.size.value === 0),
 		menuAttributes: computed(() => ({
+			"aria-label": toValue(options.label),
 			"aria-labelledby": toValue(options.labelledBy),
 			"data-collection": collectionId.value,
 			"data-empty": collection.size.value === 0 ? "true" : void 0,

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

@@ -128,7 +128,7 @@ var useNumberField = (options = {}) => {
 		setInputValue: state.setInputValue,
 		validate: state.validate
 	});
-	useFormReset(element, () => state.defaultNumberValue.value, state.setNumberValue);
+	useFormReset(element, () => state.defaultNumberValue.value, state.setNumberValue, options.form);
 	/**
 	* Range validation borrowed from a real number input.
 	*

package/dist/composables/use-select.js

@@ -46,7 +46,7 @@ var useSelect = (options, state) => {
 		sensitivity: "base",
 		usage: "search"
 	});
-	const getKeyForSearch = (search, fromKey) => {
+	const getKeyForSearch = (search, fromKey) => state.collection.withOrder(() => {
 		let key = fromKey ?? state.collection.getFirstKey();
 		while (key != null) {
 			const item = state.collection.getItem(key);
@@ -56,7 +56,7 @@ var useSelect = (options, state) => {
 			key = state.collection.getKeyAfter(key);
 		}
 		return null;
-	};
+	});
 	const typeahead = useTypeahead({
 		focusedKey: () => state.selectedKey.value,
 		getKeyForSearch,
@@ -120,7 +120,6 @@ var useSelect = (options, state) => {
 			"aria-invalid": isInvalid.value || void 0,
 			"aria-label": toValue(options.ariaLabel),
 			"aria-labelledby": [valueId.value, toValue(options.ariaLabelledby) ?? fieldIds.labelId.value].filter(Boolean).join(" "),
-			"aria-required": toValue(options.isRequired) || void 0,
 			disabled: toValue(options.isDisabled) || void 0,
 			id: trigger.triggerId.value,
 			type: "button"

package/dist/composables/use-selection-manager.js

@@ -73,13 +73,13 @@ var useSelectionManager = (options) => {
 		commit(next);
 	};
 	/** The keys from `from` to `to` inclusive, in document order whichever way round they are. */
-	const keyRange = (from, to) => {
+	const keyRange = (from, to) => collection.withOrder(() => {
 		const keys = collection.orderedKeys();
-		const start = keys.indexOf(from);
-		const end = keys.indexOf(to);
+		const start = collection.getIndex(from);
+		const end = collection.getIndex(to);
 		if (start === -1 || end === -1) return [];
 		return keys.slice(Math.min(start, end), Math.max(start, end) + 1);
-	};
+	});
 	const extendSelection = (key) => {
 		if (selectionMode.value === "none") return;
 		if (selectionMode.value === "single") {

package/dist/composables/use-single-select-list-state.d.ts

@@ -0,0 +1,37 @@
+import type { CollectionKey, UseCollectionReturn } from "./use-collection.js";
+import type { UseSelectionManagerReturn } from "./use-selection-manager.js";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+export interface UseSingleSelectListStateOptions {
+    /** The selected item, when the caller drives it. */
+    selectedKey?: MaybeRefOrGetter<CollectionKey | undefined>;
+    /** The initially selected item. Falls back to the first item that is not disabled. */
+    defaultSelectedKey?: CollectionKey;
+    onSelectionChange?: (key: CollectionKey) => void;
+    disabledKeys?: MaybeRefOrGetter<Iterable<CollectionKey> | undefined>;
+    /** Whether the whole list is disabled: a selection that exists but cannot be changed. */
+    isDisabled?: MaybeRefOrGetter<boolean | undefined>;
+}
+export interface UseSingleSelectListStateReturn {
+    collection: UseCollectionReturn;
+    selection: UseSelectionManagerReturn;
+    /** The selected item, with the default resolved against the collection. */
+    selectedKey: ComputedRef<CollectionKey | null>;
+    setSelectedKey: (key: CollectionKey) => void;
+    isDisabled: ComputedRef<boolean>;
+}
+/**
+ * Which item of a collection is selected, for a list that always has exactly one.
+ *
+ * Ported from React Stately's `useSingleSelectListState`
+ * (`react-stately/src/list/useSingleSelectListState.ts`, react-stately 3.49.0).
+ *
+ * "Always exactly one" 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.
+ */
+export declare const useSingleSelectListState: (options?: UseSingleSelectListStateOptions) => UseSingleSelectListStateReturn;

package/dist/composables/use-single-select-list-state.js

@@ -0,0 +1,110 @@
+import { useControllableState } from "./use-controllable-state.js";
+import { useCollection } from "./use-collection.js";
+import { useSelectionManager } from "./use-selection-manager.js";
+import { computed, toValue, watch } from "vue";
+//#region src/composables/use-single-select-list-state.ts
+/**
+* Which item of a collection is selected, for a list that always has exactly one.
+*
+* Ported from React Stately's `useSingleSelectListState`
+* (`react-stately/src/list/useSingleSelectListState.ts`, react-stately 3.49.0).
+*
+* "Always exactly one" 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.
+*/
+var useSingleSelectListState = (options = {}) => {
+	const collection = useCollection();
+	const disabledKeySet = computed(() => new Set(toValue(options.disabledKeys) ?? []));
+	/**
+	* Whether an item 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 item that can be selected, or the first item when none of them can. */
+	const findDefaultSelectedKey = () => collection.withOrder(() => {
+		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 item, 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 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 list like this 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 item is the only way in — and with no focused key nothing inside is tabbable
+	* either, which would put the whole 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 items 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
+	});
+	return {
+		collection,
+		isDisabled: computed(() => Boolean(toValue(options.isDisabled))),
+		selectedKey,
+		selection,
+		setSelectedKey: (key) => stored.setState(key)
+	};
+};
+//#endregion
+export { useSingleSelectListState };

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,45 +1,36 @@
-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. */
     tabId: (key: CollectionKey | null | undefined) => string | undefined;
     tabPanelId: (key: CollectionKey | null | undefined) => string | undefined;
+    /**
+     * Whether a panel for this key is in the document.
+     *
+     * Tabs are usable without panels - driving something rendered elsewhere on the page is a normal
+     * arrangement - and a tab that points `aria-controls` at an element that was never rendered is
+     * worse than one that points nowhere.
+     */
+    hasPanel: (key: CollectionKey | null | undefined) => boolean;
+    /** Called by a panel while it is mounted. Returns the matching unregister. */
+    registerPanel: (key: CollectionKey) => () => void;
 }
 /**
  * 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,114 +1,35 @@
 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, 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,
-		isDisabled: computed(() => Boolean(toValue(options.isDisabled))),
-		selectedKey,
-		selection,
-		setSelectedKey: (key) => stored.setState(key),
+		...list,
+		hasPanel: (key) => key != null && panelKeys.value.has(key),
+		registerPanel: (key) => {
+			panelKeys.value = new Set(panelKeys.value).add(key);
+			return () => {
+				const next = new Set(panelKeys.value);
+				next.delete(key);
+				panelKeys.value = next;
+			};
+		},
 		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;