ropav 0.4.0 → 0.5.0

package/dist/components/virtualizer/virtualizer-item.js

@@ -1,7 +1,5 @@
-import { useVirtualizerStateContext } from "./virtualizer.context.js";
-import { Size } from "../../utils/virtualizer-geometry.js";
-import { layoutInfoToStyle } from "../../utils/virtualizer-layout-info.js";
-import { computed, createSlot, defineVaporComponent, renderEffect, setInsertionState, setStaticTemplateRef, setStyle, shallowRef, template, watch } from "vue";
+import { useVirtualizerItem } from "./use-virtualizer-item.js";
+import { createSlot, defineVaporComponent, renderEffect, setInsertionState, setStaticTemplateRef, setStyle, shallowRef, template, unref } from "vue";
 //#region src/components/virtualizer/virtualizer-item.vue?vue&type=script&setup=true&vapor=true&lang.ts
 var t0 = template("<div role=presentation>", 1);
 var virtualizer_item_vue_vue_type_script_setup_true_vapor_true_lang_default = /*@__PURE__*/ defineVaporComponent({
@@ -12,46 +10,14 @@ var virtualizer_item_vue_vue_type_script_setup_true_vapor_true_lang_default = /*
 	},
 	setup(__props) {
 		const props = __props;
-		const virtualizer = useVirtualizerStateContext();
 		const element = shallowRef(null);
-		const style = computed(() => props.layoutInfo ? layoutInfoToStyle(props.layoutInfo, props.parentLayoutInfo) : void 0);
-		/**
-		* Measure what the layout could only estimate.
-		*
-		* The inline height is cleared first: it is the estimate, and measuring through it would just
-		* read the guess back. `scrollHeight` rather than `getBoundingClientRect` because that is what
-		* React Aria reads, and a row whose content overflows should report the content.
-		*/
-		const measure = () => {
-			const current = element.value;
-			if (!current) return;
-			const height = current.style.height;
-			current.style.height = "";
-			const measured = new Size(current.scrollWidth, current.scrollHeight);
-			current.style.height = height;
-			if (props.layoutInfo) virtualizer?.updateItemSize(props.layoutInfo.key, measured);
-		};
-		watch(() => [element.value, props.layoutInfo], ([current, layoutInfo]) => {
-			if (current && layoutInfo?.estimatedSize) measure();
-		}, {
-			flush: "post",
-			immediate: true
-		});
-		/**
-		* Watching the children rather than the wrapper: the wrapper's height is set by the layout, so it
-		* never changes on its own, while what is inside it does.
-		*/
-		watch(() => [element.value, virtualizer?.shouldObserveItemSize.value], ([current, shouldObserve], _previous, onCleanup) => {
-			if (!current || !shouldObserve || typeof ResizeObserver === "undefined") return;
-			const observer = new ResizeObserver(() => measure());
-			for (const child of current.children) observer.observe(child);
-			onCleanup(() => observer.disconnect());
-		}, {
-			flush: "post",
-			immediate: true
+		const { style } = useVirtualizerItem({
+			element,
+			layoutInfo: () => props.layoutInfo,
+			parentLayoutInfo: () => props.parentLayoutInfo
 		});
 		const n1 = t0();
-		renderEffect(() => setStyle(n1, style.value));
+		renderEffect(() => setStyle(n1, unref(style)));
 		setInsertionState(n1);
 		createSlot();
 		setStaticTemplateRef(n1, element, null, "element");

package/dist/components/virtualizer/virtualizer-scrollbar-track.d.ts

@@ -0,0 +1,20 @@
+declare const __VLS_export: (__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>['props'], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, 'attrs' | 'emit' | 'slots'>>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>['expose'], __VLS_setup?: Promise<{
+    props: import('vue').PublicProps & __VLS_PrettifyLocal<{
+        orientation: "horizontal" | "vertical";
+    }> & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: {}) => void;
+    attrs: any;
+    slots: {};
+    emit: {};
+}>) => import('vue').VNode & {
+    __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
+};
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_PrettifyLocal<T> = (T extends any ? {
+    [K in keyof T]: T[K];
+} : {
+    [K in keyof T as K]: T[K];
+}) & {};

package/dist/components/virtualizer/virtualizer-scrollbar-track.js

@@ -0,0 +1,141 @@
+import { dataAttr } from "../../utils/assertion.js";
+import { useInteractionStates } from "../../composables/use-interaction-states.js";
+import { useVirtualizerStateContext } from "./virtualizer.context.js";
+import { useMove } from "../../composables/use-move.js";
+import { child, computed, createIf, defineVaporComponent, on, renderEffect, setAttr, setClass, setStyle, template, unref } from "vue";
+import { virtualizerVariants } from "@ropav/styles";
+//#region src/components/virtualizer/virtualizer-scrollbar-track.vue?vue&type=script&setup=true&vapor=true&lang.ts
+var t0 = template("<div data-slot=virtualizer-scrollbar-track><div data-slot=virtualizer-scrollbar-thumb>", 1);
+/**
+* One axis of the scrollbar a windowed collection draws for itself: a track, and the thumb in it.
+*
+* The thumb is moved by the main thread. Every pointer move sets the scroll offset and the rows for
+* it in one task, so no frame is ever drawn with rows that were built for another offset — which is
+* what a native thumb, moved by the compositor, cannot promise. See `VirtualizerScrollbar`.
+*/
+var THICKNESS = 10;
+/** The shortest the thumb gets: a long collection would otherwise leave nothing to grab. */
+var MIN_THUMB_LENGTH = 32;
+/**
+* How much of the viewport a press on the track moves by. Less than the whole of it, so what was
+* at the edge is still on screen afterwards to hold the eye — the fraction browsers page by.
+*/
+var PAGE_FRACTION = .875;
+var virtualizer_scrollbar_track_vue_vue_type_script_setup_true_vapor_true_lang_default = /*@__PURE__*/ defineVaporComponent({
+	__name: "virtualizer-scrollbar-track",
+	props: { orientation: {} },
+	setup(__props) {
+		const props = __props;
+		/** How thick the track is, across its axis. */
+		const state = useVirtualizerStateContext();
+		if (!state) throw new Error("`VirtualizerScrollbarTrack` was rendered outside of a windowed collection.");
+		const { scroll } = state;
+		const styles = virtualizerVariants();
+		const isVertical = props.orientation === "vertical";
+		/** A size measured along this track's axis. */
+		const along = (size) => isVertical ? size.height : size.width;
+		/** A size measured across it, which is the other track's axis. */
+		const across = (size) => isVertical ? size.width : size.height;
+		const viewport = computed(() => along(scroll.size.value));
+		/** How far the box can scroll along this axis. */
+		const range = computed(() => Math.max(0, along(scroll.scrollSize.value) - viewport.value));
+		/** Whether the box scrolls along this axis at all, rather than clipping it. */
+		const scrolls = computed(() => isVertical ? scroll.box.value.scrollsY : scroll.box.value.scrollsX);
+		/** Whether the other axis has a track too, which is when the two leave each other a corner. */
+		const hasCorner = computed(() => (isVertical ? scroll.box.value.scrollsX : scroll.box.value.scrollsY) && across(scroll.scrollSize.value) > across(scroll.size.value));
+		const trackLength = computed(() => Math.max(0, viewport.value - (hasCorner.value ? THICKNESS : 0)));
+		/** The thumb is to the track what the viewport is to the content, down to a graspable floor. */
+		const thumbLength = computed(() => {
+			const total = along(scroll.scrollSize.value);
+			if (total <= 0) return trackLength.value;
+			return Math.min(trackLength.value, Math.max(MIN_THUMB_LENGTH, trackLength.value * viewport.value / total));
+		});
+		/** How far the thumb can travel. */
+		const travel = computed(() => Math.max(0, trackLength.value - thumbLength.value));
+		/** The scroll offset along this axis, signed. */
+		const offset = computed(() => isVertical ? scroll.offset.value.y : scroll.offset.value.x);
+		/** Where the thumb sits, measured from the start of the track. */
+		const thumbOffset = computed(() => range.value > 0 ? Math.min(Math.abs(offset.value), range.value) / range.value * travel.value : 0);
+		const isVisible = computed(() => scrolls.value && range.value > 0);
+		const scrollTo = (value) => {
+			scroll.scrollTo(isVertical ? { top: value } : { left: value });
+		};
+		const states = useInteractionStates();
+		/** The offset the press started from, and how far the pointer has travelled along the track since. */
+		let startOffset = 0;
+		let dragged = 0;
+		/** Content pixels per thumb pixel, fixed at the press so the mapping cannot drift mid-drag. */
+		let ratio = 0;
+		const { handlers: moveHandlers } = useMove({
+			onMove: ({ deltaX, deltaY }) => {
+				dragged += isVertical ? deltaY : deltaX;
+				scrollTo(startOffset + dragged * ratio);
+			},
+			onMoveEnd: () => {
+				dragged = 0;
+			}
+		});
+		const onThumbPointerdown = (event) => {
+			if (event.button !== 0) return;
+			startOffset = offset.value;
+			dragged = 0;
+			ratio = travel.value > 0 ? range.value / travel.value : 0;
+			states.onPointerdown(event);
+			moveHandlers.onPointerdown(event);
+		};
+		/** A press beside the thumb pages towards it. The thumb itself stops its press from reaching here. */
+		const onTrackPointerdown = (event) => {
+			if (event.button !== 0) return;
+			event.preventDefault();
+			const track = event.currentTarget;
+			const bounds = track.getBoundingClientRect();
+			const isReversed = !isVertical && getComputedStyle(track).direction === "rtl";
+			let pressed;
+			if (isVertical) pressed = event.clientY - bounds.top;
+			else if (isReversed) pressed = bounds.right - event.clientX;
+			else pressed = event.clientX - bounds.left;
+			const page = Math.round(viewport.value * PAGE_FRACTION) * (pressed > thumbOffset.value ? 1 : -1);
+			scrollTo(offset.value + (isReversed ? -page : page));
+		};
+		const trackStyle = computed(() => isVertical ? {
+			height: `${trackLength.value}px`,
+			width: `${THICKNESS}px`
+		} : {
+			height: `${THICKNESS}px`,
+			top: `${across(scroll.size.value) - THICKNESS}px`,
+			width: `${trackLength.value}px`
+		});
+		const thumbStyle = computed(() => isVertical ? {
+			height: `${thumbLength.value}px`,
+			top: `${thumbOffset.value}px`
+		} : {
+			"inset-inline-start": `${thumbOffset.value}px`,
+			width: `${thumbLength.value}px`
+		});
+		return createIf(() => isVisible.value, () => {
+			const n3 = t0();
+			const n2 = child(n3);
+			on(n2, "pointerdown", onThumbPointerdown);
+			on(n2, "pointerenter", (e) => unref(states).onPointerenter(e));
+			on(n2, "pointerleave", (e) => unref(states).onPointerleave(e));
+			on(n3, "pointerdown", onTrackPointerdown);
+			renderEffect(() => {
+				const _styles = unref(styles);
+				const _orientation = __props.orientation;
+				const _dataAttr = unref(dataAttr);
+				const _states = unref(states);
+				setClass(n3, _styles.scrollbarTrack());
+				setAttr(n3, "data-orientation", _orientation);
+				setStyle(n3, trackStyle.value);
+				setClass(n2, _styles.scrollbarThumb());
+				setAttr(n2, "data-hovered", _dataAttr(_states.isHovered.value));
+				setAttr(n2, "data-orientation", _orientation);
+				setAttr(n2, "data-pressed", _dataAttr(_states.isPressed.value));
+				setStyle(n2, thumbStyle.value);
+			});
+			return n3;
+		});
+	}
+});
+//#endregion
+export { virtualizer_scrollbar_track_vue_vue_type_script_setup_true_vapor_true_lang_default as default };

package/dist/components/virtualizer/virtualizer-scrollbar.d.ts

@@ -0,0 +1,18 @@
+declare const __VLS_export: (__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>['props'], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, 'attrs' | 'emit' | 'slots'>>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>['expose'], __VLS_setup?: Promise<{
+    props: import('vue').PublicProps & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: {}) => void;
+    attrs: any;
+    slots: {};
+    emit: {};
+}>) => import('vue').VNode & {
+    __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
+};
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_PrettifyLocal<T> = (T extends any ? {
+    [K in keyof T]: T[K];
+} : {
+    [K in keyof T as K]: T[K];
+}) & {};

package/dist/components/virtualizer/virtualizer-scrollbar.js

@@ -0,0 +1,55 @@
+import { useVirtualizerStateContext } from "./virtualizer.context.js";
+import virtualizer_scrollbar_track_default from "./virtualizer-scrollbar-track.js";
+import { computed, createComponent, defineVaporComponent, renderEffect, setClass, setInsertionState, setStyle, template, unref } from "vue";
+import { virtualizerVariants } from "@ropav/styles";
+//#region src/components/virtualizer/virtualizer-scrollbar.vue?vue&type=script&setup=true&vapor=true&lang.ts
+var t0 = template("<div aria-hidden=true data-slot=virtualizer-scrollbar>", 1);
+/**
+* The scrollbar a windowed collection draws for itself, in place of the native one it hides.
+*
+* A native thumb is moved by the compositor, which draws every frame at the new offset with
+* whatever rows the main thread last committed — and across a long collection those rows are
+* always somewhere else, so the window is empty for as long as the main thread takes to catch up.
+* This thumb is moved by the main thread: a pointer move sets the offset and the rows for it in
+* one task, so no frame is ever drawn with rows that were built for another offset. Wheel,
+* trackpad and keyboard scrolling stay native, and the thumb follows them.
+*
+* A pointer affordance and nothing more, like the native one: the box stays the focusable
+* scroller and the keyboard reaches every offset through it. Hidden from assistive technology for
+* the same reason a native scrollbar is not exposed.
+*
+* Rendered by the collection as the first child of its content wrapper — inside the wrapper rather
+* than beside it, because a stuck box cannot leave its containing block, and only the wrapper is
+* tall enough to stay stuck to for the whole of the scroll. A stuck box is held inside the scroll
+* container's content box, so on a padded container it sits at the content's corner, not the
+* container's; the difference is the padding, and it is given back with a translation, which
+* sticky positioning leaves alone. A track along the edge then runs the full length of the box.
+*/
+var virtualizer_scrollbar_vue_vue_type_script_setup_true_vapor_true_lang_default = /*@__PURE__*/ defineVaporComponent({
+	__name: "virtualizer-scrollbar",
+	setup(__props) {
+		const state = useVirtualizerStateContext();
+		if (!state) throw new Error("`VirtualizerScrollbar` was rendered outside of a windowed collection.");
+		const { scroll } = state;
+		const styles = virtualizerVariants();
+		const style = computed(() => {
+			const { direction, paddingInlineStart, paddingTop } = scroll.box.value;
+			return {
+				translate: `${direction === "rtl" ? paddingInlineStart : -paddingInlineStart}px ${-paddingTop}px`,
+				width: `${scroll.size.value.width}px`
+			};
+		});
+		const n2 = t0();
+		renderEffect(() => {
+			setClass(n2, unref(styles).scrollbar());
+			setStyle(n2, style.value);
+		});
+		setInsertionState(n2);
+		createComponent(virtualizer_scrollbar_track_default, { orientation: "vertical" });
+		setInsertionState(n2, 1);
+		createComponent(virtualizer_scrollbar_track_default, { orientation: "horizontal" });
+		return n2;
+	}
+});
+//#endregion
+export { virtualizer_scrollbar_vue_vue_type_script_setup_true_vapor_true_lang_default as default };

package/dist/components/virtualizer/virtualizer.context.d.ts

@@ -1,5 +1,6 @@
+import type { ScrollBoxInfo, ScrollToOffset } from "../../composables/use-virtualizer-scroll.js";
 import type { ItemDropTarget } from "../../utils/dnd-types.js";
-import type { Size } from "../../utils/virtualizer-geometry.js";
+import type { Point, Size } from "../../utils/virtualizer-geometry.js";
 import type { Layout } from "../../utils/virtualizer-layout.js";
 import type { LayoutInfo, VirtualizerKey } from "../../utils/virtualizer-layout-info.js";
 import type { ComputedRef, ShallowRef } from "vue";
@@ -19,8 +20,23 @@ export interface VirtualizerConfigContext {
  * for one would make `Virtualizer` mandatory for every listbox in the library.
  */
 export declare const useVirtualizerConfigContext: () => VirtualizerConfigContext | null, provideVirtualizerConfigContext: (value: VirtualizerConfigContext | null) => VirtualizerConfigContext | null;
+/** The scroll box as the scrollbar a windowed collection draws for itself reads it. */
+export interface VirtualizerScrollState {
+    /** How far the box is scrolled. The inline axis runs negative in a right-to-left box. */
+    offset: ComputedRef<Point>;
+    /** The box's own size, which is what it shows of the content at once. */
+    size: ComputedRef<Size>;
+    /** The box's scrollable overflow — everything it could show. */
+    scrollSize: ComputedRef<Size>;
+    /** The box's padding, and which of its axes scroll at all. */
+    box: ComputedRef<ScrollBoxInfo>;
+    /** Scrolls the box from the main thread, so the rows and the offset are committed together. */
+    scrollTo: (offset: ScrollToOffset) => void;
+}
 /** What a virtualized collection hands its own parts, so they can describe themselves. */
 export interface VirtualizerStateContext {
+    /** The scroll box, for the scrollbar the collection draws in place of the native one. */
+    scroll: VirtualizerScrollState;
     /** How many items the collection holds, which is not how many are rendered. */
     itemCount: ComputedRef<number>;
     /** An item's position among all of them, zero-based. */

package/dist/composables/drag-manager.js

@@ -109,11 +109,6 @@ var endDragging = () => {
 };
 /** Whether a keyboard or screen reader drag is in flight. */
 var isVirtualDragging = () => dragSession != null;
-/** Whether an element is inside a registered drop target. */
-var isValidDropTarget = (element) => {
-	for (const target of dropTargets.keys()) if (contains(target, element)) return true;
-	return false;
-};
 /**
 * The session in flight, as a ref that updates when one starts or ends.
 *
@@ -432,12 +427,5 @@ var DragSession = class {
 		}, dropItem?.target ?? null);
 	}
 };
-/**
-* The session in flight, read once.
-*
-* The imperative sibling of `useDragSession`, for callers that are not inside an effect scope —
-* an event handler deciding whether a keystroke belongs to a drag, or a test ending one.
-*/
-var getDragSession = () => dragSession;
 //#endregion
-export { DragSession, beginDragging, getDragSession, isValidDropTarget, isVirtualDragging, registerDropItem, registerDropTarget, useDragSession };
+export { DragSession, beginDragging, isVirtualDragging, registerDropItem, registerDropTarget, useDragSession };

package/dist/composables/index.d.ts

@@ -1,76 +1,32 @@
-export * from "./drag-collection.js";
-export * from "./drag-manager.js";
-export * from "./drag-modality.js";
-export * from "./droppable-collection-registry.js";
 export * from "./focus-responder.js";
 export * from "./press-responder.js";
-export * from "./table-drag-collection.js";
-export * from "./use-auto-scroll.js";
-export * from "./use-autocomplete.js";
-export * from "./use-calendar.js";
-export * from "./use-calendar-cell.js";
-export * from "./use-calendar-grid.js";
-export * from "./use-calendar-heading.js";
 export * from "./use-calendar-state.js";
-export * from "./use-calendar-year-picker.js";
 export * from "./use-checkbox-group-state.js";
 export * from "./use-collator.js";
 export * from "./use-collection.js";
-export * from "./use-collection-auto-focus.js";
-export * from "./use-combo-box.js";
-export * from "./use-combo-box-state.js";
-export * from "./use-color-area.js";
-export * from "./use-color-area-gradient.js";
 export * from "./use-color-area-state.js";
-export * from "./use-color-channel-field.js";
 export * from "./use-color-channel-field-state.js";
-export * from "./use-color-field.js";
 export * from "./use-color-field-state.js";
 export * from "./use-color-picker-state.js";
-export * from "./use-color-slider.js";
 export * from "./use-color-slider-state.js";
-export * from "./use-color-swatch.js";
+export * from "./use-combo-box-state.js";
 export * from "./use-controllable-state.js";
 export * from "./use-css-variable.js";
-export * from "./use-date-field.js";
 export * from "./use-date-field-state.js";
 export * from "./use-date-formatter.js";
-export * from "./use-date-picker.js";
-export * from "./use-date-picker-group.js";
 export * from "./use-date-picker-state.js";
-export * from "./use-date-segment.js";
-export * from "./use-default-date-props.js";
+export * from "./use-date-range-picker-state.js";
 export * from "./use-description.js";
-export * from "./use-dialog-trigger.js";
 export * from "./use-disclosure-group.js";
-export * from "./use-disclosure-group-navigation.js";
-export * from "./use-disclosure-panel.js";
 export * from "./use-dismissable.js";
-export * from "./use-display-names.js";
-export * from "./use-drag.js";
 export * from "./use-drag-and-drop.js";
-export * from "./use-draggable-collection.js";
-export * from "./use-draggable-collection-state.js";
-export * from "./use-draggable-item.js";
-export * from "./use-drawer-drag.js";
-export * from "./use-drop.js";
-export * from "./use-drop-indicator.js";
-export * from "./use-droppable-collection.js";
-export * from "./use-droppable-collection-state.js";
-export * from "./use-droppable-item.js";
 export * from "./use-enter-exit.js";
 export * from "./use-field-ids.js";
 export * from "./use-filter.js";
 export * from "./use-focus-scope.js";
 export * from "./use-form-reset.js";
-export * from "./use-form-validation.js";
 export * from "./use-form-validation-state.js";
-export * from "./use-formatted-text-field.js";
-export * from "./use-grid-keyboard.js";
-export * from "./use-grid-selection-announcement.js";
 export * from "./use-id.js";
-export * from "./use-image-loading-status.js";
-export * from "./use-input-otp.js";
 export * from "./use-interaction-states.js";
 export * from "./use-labels.js";
 export * from "./use-list-data.js";
@@ -78,48 +34,24 @@ export * from "./use-list-keyboard.js";
 export * from "./use-locale.js";
 export * from "./use-localized-string-formatter.js";
 export * from "./use-long-press.js";
-export * from "./use-measured-height.js";
 export * from "./use-media-query.js";
-export * from "./use-menu.js";
-export * from "./use-modal-overlay.js";
-export * from "./use-modal-transition.js";
 export * from "./use-move.js";
-export * from "./use-number-field.js";
 export * from "./use-number-field-state.js";
 export * from "./use-number-formatter.js";
 export * from "./use-overlay-position.js";
-export * from "./use-overlay-trigger.js";
 export * from "./use-overlay-trigger-state.js";
-export * from "./use-password-manager-badge.js";
 export * from "./use-press.js";
 export * from "./use-prevent-scroll.js";
 export * from "./use-radio-group-state.js";
-export * from "./use-range-calendar.js";
 export * from "./use-range-calendar-state.js";
-export * from "./use-safely-mouse-to-submenu.js";
-export * from "./use-scroll-wheel.js";
-export * from "./use-search-field.js";
-export * from "./use-select.js";
 export * from "./use-select-state.js";
 export * from "./use-selection-manager.js";
-export * from "./use-shared-element.js";
-export * from "./use-slider.js";
+export * from "./use-single-select-list-state.js";
 export * from "./use-slider-state.js";
-export * from "./use-slider-thumb.js";
-export * from "./use-spin-button.js";
 export * from "./use-tab-list-state.js";
-export * from "./use-table-collection.js";
-export * from "./use-table-column-layout.js";
-export * from "./use-text-field.js";
 export * from "./use-time-field-state.js";
 export * from "./use-toast.js";
-export * from "./use-toast-region.js";
 export * from "./use-toggle-group-state.js";
-export * from "./use-toolbar.js";
-export * from "./use-tooltip-trigger.js";
 export * from "./use-tooltip-trigger-state.js";
 export * from "./use-typeahead.js";
 export * from "./use-viewport-size.js";
-export * from "./use-virtual-drop.js";
-export * from "./use-virtualizer.js";
-export * from "./use-virtualizer-scroll.js";

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

@@ -33,6 +33,13 @@ export interface UseCollectionReturn {
     getKeyBefore: (key: CollectionKey) => CollectionKey | null;
     /** The item's position among its siblings, or `-1` when it is not in the collection. */
     getIndex: (key: CollectionKey) => number;
+    /**
+     * Run `operation` against a single reading of the collection's order.
+     *
+     * Wrap anything that walks the collection more than once — arrow navigation, paging, typeahead,
+     * extending a selection. See {@link useCollection} for why this is scoped rather than cached.
+     */
+    withOrder: <T>(operation: () => T) => T;
     /** Register an item and return the call that unregisters it. */
     register: (key: CollectionKey, meta: CollectionItemMeta) => () => void;
 }
@@ -44,7 +51,7 @@ export interface UseCollectionReturn {
  * rendering a slot is what creates its DOM, so there is no "render to inspect" pass. The flow
  * is inverted instead — each item registers itself, and the parent asks the DOM for the order.
  *
- * Two choices carry the weight:
+ * Three choices carry the weight:
  *
  * Metadata is stored as **getters**, not values, so the parent always reads an item's current
  * text and disabled state. Nothing has to re-register when a prop changes, and no
@@ -54,8 +61,20 @@ export interface UseCollectionReturn {
  * invalidated by a counter bumped on register and unregister — but reordering items that are
  * already registered changes their document order without touching that counter, which would
  * silently break arrow navigation. Order is only ever read on an interaction (a keypress, a
- * focus change, extending a selection), never during render, so re-sorting per call is both
- * correct and cheap. `size` stays reactive because it *is* read during render.
+ * focus change, extending a selection), never during render, so `size` stays reactive — because
+ * it *is* read during render — while order deliberately stays outside reactivity.
+ *
+ * Sorting the DOM per call, however, is only cheap for a *single* read, and the callers that
+ * matter walk the collection one neighbour at a time: typeahead, paging, and skipping disabled
+ * items all ask for a neighbour in a loop. Sorting inside that loop is quadratic, and a search
+ * that matches nothing walks the whole collection twice. {@link UseCollectionReturn.withOrder}
+ * is what those callers wrap themselves in: the order is read once and every step reads that one
+ * snapshot.
+ *
+ * The snapshot is **scoped to one synchronous operation** rather than cached across operations,
+ * because caching is the very thing the second choice above rules out. Vue flushes renders on
+ * `nextTick`, so the DOM cannot reorder itself in the middle of a keydown handler — which is
+ * exactly as long as a snapshot is allowed to live. It must never become a `computed`.
  *
  * A collection that is virtualized cannot work that way at all: all but a window of its items are
  * absent from the DOM, so asking the DOM would answer for the window and call the rest