ropav 0.2.0 → 0.3.0

package/dist/composables/droppable-collection-registry.d.ts

@@ -0,0 +1,24 @@
+import type { UseDroppableCollectionStateReturn } from "./use-droppable-collection-state";
+import type { ShallowRef } from "vue";
+/**
+ * Which element and id each droppable collection state belongs to.
+ *
+ * An item needs both — its id to be labelled by, its element to tell an internal drag from a
+ * foreign one — but it is handed only the state, because that is the one thing a collection and
+ * its items already share. `useDroppableCollection` records the rest here on the way past.
+ *
+ * Deliberately outside `utils/`, unlike the rest of the drag and drop machinery: the key is a
+ * composable's return type, and `utils/` never imports from `composables/`.
+ *
+ * Weak, so a collection that unmounts takes its entry with it.
+ */
+interface DroppableCollectionEntry {
+    id: string;
+    element: ShallowRef<HTMLElement | null>;
+}
+export declare const registerDroppableCollection: (state: UseDroppableCollectionStateReturn<unknown>, entry: DroppableCollectionEntry) => void;
+/** The id of the collection this state belongs to, for an item to be labelled by. */
+export declare const getDroppableCollectionId: (state: object) => string;
+/** The element of the collection this state belongs to. */
+export declare const getDroppableCollectionElement: (state: object) => ShallowRef<HTMLElement | null>;
+export {};

package/dist/composables/droppable-collection-registry.js

@@ -0,0 +1,16 @@
+//#region src/composables/droppable-collection-registry.ts
+var registry = /* @__PURE__ */ new WeakMap();
+var registerDroppableCollection = (state, entry) => {
+	registry.set(state, entry);
+};
+var entryFor = (state) => {
+	const entry = registry.get(state);
+	if (!entry) throw new Error("Droppable item outside a droppable collection");
+	return entry;
+};
+/** The id of the collection this state belongs to, for an item to be labelled by. */
+var getDroppableCollectionId = (state) => entryFor(state).id;
+/** The element of the collection this state belongs to. */
+var getDroppableCollectionElement = (state) => entryFor(state).element;
+//#endregion
+export { getDroppableCollectionElement, getDroppableCollectionId, registerDroppableCollection };

package/dist/composables/focus-responder.d.ts

@@ -0,0 +1,52 @@
+import type { ComputedRef } from "vue";
+/** The listeners a focusable takes from above, in the shape a template attaches them in. */
+export interface FocusResponderHandlers {
+    onBlur: (event: FocusEvent) => void;
+    onFocus: (event: FocusEvent) => void;
+    onKeydown: (event: KeyboardEvent) => void;
+    onPointerdown: (event: PointerEvent) => void;
+    onPointerenter: (event: PointerEvent) => void;
+    onPointerleave: (event: PointerEvent) => void;
+}
+export interface FocusResponder {
+    /**
+     * Attributes the focusable renders with `v-bind` — the description it is given while whatever
+     * is watching it is showing something. Attributes only: see {@link composeFocusResponder} for
+     * why the handlers are kept out of this.
+     */
+    attrs: ComputedRef<Record<string, unknown>>;
+    /** Listeners the focusable chains ahead of its own, through {@link composeFocusResponder}. */
+    handlers: ComputedRef<FocusResponderHandlers>;
+    /** Reports the focusable's element, which is what the responder watches and positions against. */
+    registerElement: (element: HTMLElement | null) => void;
+}
+/**
+ * Hover and focus supplied from above, ported from React Aria's `FocusableContext`.
+ *
+ * This is how `<Tooltip><Button/></Tooltip>` works: the trigger is an ordinary button, and
+ * everything that makes it a tooltip trigger — opening after a delay on hover, opening at once on
+ * keyboard focus, closing when pressed — is handed down rather than built into the button.
+ *
+ * Deliberately not the same context as the press responder, which React also keeps separate. A
+ * button inside a dropdown already takes its press from above; if the two shared one channel, a
+ * tooltip wrapped around that button would replace the press that makes it a menu trigger.
+ *
+ * Optional: most focusables have nobody above them supplying anything.
+ */
+export declare const useFocusResponder: () => FocusResponder | null, provideFocusResponder: (value: FocusResponder | null) => FocusResponder | null;
+/**
+ * Chain a responder's listeners ahead of the element's own, as functions stable enough to
+ * attach with `@event`.
+ *
+ * **A listener must never reach a vapor element through `v-bind`** — the reasoning is the same as
+ * for {@link composePressResponder}, and a tooltip trigger is exactly the kind of element it bites:
+ * hovering it is itself a re-render, so a listener carried by `v-bind` would be removed in the
+ * middle of the very event that was meant to open the tooltip.
+ *
+ * @example
+ * ```ts
+ * const focus = composeFocusResponder(useFocusResponder(), {onFocus, onBlur});
+ * // <button @focus="focus.onFocus" @blur="focus.onBlur" ...>
+ * ```
+ */
+export declare const composeFocusResponder: (responder: FocusResponder | null, own?: Partial<FocusResponderHandlers>) => FocusResponderHandlers;

package/dist/composables/focus-responder.js

@@ -0,0 +1,63 @@
+import { createContext } from "../utils/create-context.js";
+//#region src/composables/focus-responder.ts
+/**
+* Hover and focus supplied from above, ported from React Aria's `FocusableContext`.
+*
+* This is how `<Tooltip><Button/></Tooltip>` works: the trigger is an ordinary button, and
+* everything that makes it a tooltip trigger — opening after a delay on hover, opening at once on
+* keyboard focus, closing when pressed — is handed down rather than built into the button.
+*
+* Deliberately not the same context as the press responder, which React also keeps separate. A
+* button inside a dropdown already takes its press from above; if the two shared one channel, a
+* tooltip wrapped around that button would replace the press that makes it a menu trigger.
+*
+* Optional: most focusables have nobody above them supplying anything.
+*/
+var [useFocusResponder, provideFocusResponder] = createContext({
+	defaultValue: null,
+	name: "FocusResponder",
+	strict: false
+});
+/**
+* Chain a responder's listeners ahead of the element's own, as functions stable enough to
+* attach with `@event`.
+*
+* **A listener must never reach a vapor element through `v-bind`** — the reasoning is the same as
+* for {@link composePressResponder}, and a tooltip trigger is exactly the kind of element it bites:
+* hovering it is itself a re-render, so a listener carried by `v-bind` would be removed in the
+* middle of the very event that was meant to open the tooltip.
+*
+* @example
+* ```ts
+* const focus = composeFocusResponder(useFocusResponder(), {onFocus, onBlur});
+* // <button @focus="focus.onFocus" @blur="focus.onBlur" ...>
+* ```
+*/
+var composeFocusResponder = (responder, own = {}) => ({
+	onBlur: (event) => {
+		responder?.handlers.value.onBlur(event);
+		own.onBlur?.(event);
+	},
+	onFocus: (event) => {
+		responder?.handlers.value.onFocus(event);
+		own.onFocus?.(event);
+	},
+	onKeydown: (event) => {
+		responder?.handlers.value.onKeydown(event);
+		own.onKeydown?.(event);
+	},
+	onPointerdown: (event) => {
+		responder?.handlers.value.onPointerdown(event);
+		own.onPointerdown?.(event);
+	},
+	onPointerenter: (event) => {
+		responder?.handlers.value.onPointerenter(event);
+		own.onPointerenter?.(event);
+	},
+	onPointerleave: (event) => {
+		responder?.handlers.value.onPointerleave(event);
+		own.onPointerleave?.(event);
+	}
+});
+//#endregion
+export { composeFocusResponder, provideFocusResponder, useFocusResponder };

package/dist/composables/index.d.ts

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

package/dist/composables/press-responder.d.ts

@@ -0,0 +1,51 @@
+import type { UsePressHandlers } from "./use-press";
+import type { ComputedRef } from "vue";
+export interface PressResponder {
+    /**
+     * Attributes the pressable renders with `v-bind` — the ARIA wiring and the id the overlay
+     * is labelled by. Attributes only: see {@link composePressResponder} for why the handlers
+     * are kept out of this.
+     */
+    attrs: ComputedRef<Record<string, unknown>>;
+    /** Listeners the pressable chains ahead of its own, through {@link composePressResponder}. */
+    handlers: ComputedRef<UsePressHandlers>;
+    /** Whether the pressable should look pressed regardless of its own state. */
+    isPressed: ComputedRef<boolean>;
+    /** Reports the pressable's element, which is what the responder acts on and positions against. */
+    registerElement: (element: HTMLElement | null) => void;
+}
+/**
+ * A press supplied from above, ported from React Aria's `PressResponder`.
+ *
+ * This is how `<Dropdown><Button/></Dropdown>` works: the trigger is an ordinary button, and
+ * everything that makes it a menu trigger — the ARIA wiring, opening on the way down for a mouse
+ * but on release for touch, the long-press variant — is handed down rather than built into the
+ * button. Any pressable can consume it, so the same trigger markup works for whatever opens next.
+ *
+ * Optional: most pressables have nobody above them supplying a press.
+ */
+export declare const usePressResponder: () => PressResponder | null, providePressResponder: (value: PressResponder | null) => PressResponder | null;
+/**
+ * Chain a responder's listeners ahead of the element's own, as functions stable enough to
+ * attach with `@event`.
+ *
+ * **A listener must never reach a vapor element through `v-bind`.** `setDynamicProps` re-applies
+ * every `on*` key on each render — unconditionally, since a handler cannot be compared for
+ * equality — and the previous listener is removed as the render effect cleans up. Two things
+ * follow, and both broke the dropdown: after the first re-render the responder's listeners sit
+ * *behind* the ones the template attached, so the element's own press runs first; and a re-render
+ * landing mid-dispatch removes a listener that has not been called yet, which the DOM then never
+ * calls for the event in flight. A real mouse press hits both — the pointer has to enter the
+ * element first, and hovering is itself a re-render — while a synthetic `dispatchEvent` in a test
+ * hits neither, so the bug only ever showed up under a real pointer.
+ *
+ * Attached once with `@event` and reading the responder at event time, the wrappers below have
+ * neither problem.
+ *
+ * @example
+ * ```ts
+ * const press = composePressResponder(usePressResponder(), {onClick, onPointerdown});
+ * // <button @click="press.onClick" @pointerdown="press.onPointerdown" ...>
+ * ```
+ */
+export declare const composePressResponder: (responder: PressResponder | null, own?: Partial<UsePressHandlers>) => UsePressHandlers;

package/dist/composables/press-responder.js

@@ -0,0 +1,76 @@
+import { createContext } from "../utils/create-context.js";
+//#region src/composables/press-responder.ts
+/**
+* A press supplied from above, ported from React Aria's `PressResponder`.
+*
+* This is how `<Dropdown><Button/></Dropdown>` works: the trigger is an ordinary button, and
+* everything that makes it a menu trigger — the ARIA wiring, opening on the way down for a mouse
+* but on release for touch, the long-press variant — is handed down rather than built into the
+* button. Any pressable can consume it, so the same trigger markup works for whatever opens next.
+*
+* Optional: most pressables have nobody above them supplying a press.
+*/
+var [usePressResponder, providePressResponder] = createContext({
+	defaultValue: null,
+	name: "PressResponder",
+	strict: false
+});
+/**
+* Chain a responder's listeners ahead of the element's own, as functions stable enough to
+* attach with `@event`.
+*
+* **A listener must never reach a vapor element through `v-bind`.** `setDynamicProps` re-applies
+* every `on*` key on each render — unconditionally, since a handler cannot be compared for
+* equality — and the previous listener is removed as the render effect cleans up. Two things
+* follow, and both broke the dropdown: after the first re-render the responder's listeners sit
+* *behind* the ones the template attached, so the element's own press runs first; and a re-render
+* landing mid-dispatch removes a listener that has not been called yet, which the DOM then never
+* calls for the event in flight. A real mouse press hits both — the pointer has to enter the
+* element first, and hovering is itself a re-render — while a synthetic `dispatchEvent` in a test
+* hits neither, so the bug only ever showed up under a real pointer.
+*
+* Attached once with `@event` and reading the responder at event time, the wrappers below have
+* neither problem.
+*
+* @example
+* ```ts
+* const press = composePressResponder(usePressResponder(), {onClick, onPointerdown});
+* // <button @click="press.onClick" @pointerdown="press.onPointerdown" ...>
+* ```
+*/
+var composePressResponder = (responder, own = {}) => ({
+	onClick: (event) => {
+		responder?.handlers.value.onClick(event);
+		own.onClick?.(event);
+	},
+	onDragstart: (event) => {
+		responder?.handlers.value.onDragstart(event);
+		own.onDragstart?.(event);
+	},
+	onKeydown: (event) => {
+		responder?.handlers.value.onKeydown(event);
+		own.onKeydown?.(event);
+	},
+	onMousedown: (event) => {
+		responder?.handlers.value.onMousedown(event);
+		own.onMousedown?.(event);
+	},
+	onPointerdown: (event) => {
+		responder?.handlers.value.onPointerdown(event);
+		own.onPointerdown?.(event);
+	},
+	onPointerenter: (event) => {
+		responder?.handlers.value.onPointerenter(event);
+		own.onPointerenter?.(event);
+	},
+	onPointerleave: (event) => {
+		responder?.handlers.value.onPointerleave(event);
+		own.onPointerleave?.(event);
+	},
+	onPointerup: (event) => {
+		responder?.handlers.value.onPointerup(event);
+		own.onPointerup?.(event);
+	}
+});
+//#endregion
+export { composePressResponder, providePressResponder, usePressResponder };

package/dist/composables/table-drag-collection.d.ts

@@ -0,0 +1,18 @@
+import type { DragCollection } from "../utils/dnd-types";
+import type { UseTableCollectionReturn } from "./use-table-collection";
+/**
+ * A `DragCollection` over a table's rows.
+ *
+ * A tree grid needs its own rather than the flat `toDragCollection`, because the drag layer asks
+ * two different questions that a flat list answers identically and a tree does not:
+ *
+ * - **Document order** — `getKeyAfter`/`getKeyBefore`, which descend into open rows. This is how
+ *   a drag steps down the table, one visible row at a time.
+ * - **Sibling order** — `prevKey`/`nextKey` on a node, which skip over a row's whole subtree.
+ *   This is how the drop layer recognises two names for the same gap, and how the tree delegate
+ *   finds where a subtree ends.
+ *
+ * A flat table has one level, so the two coincide and this behaves exactly like the listbox
+ * adapter.
+ */
+export declare const toTableDragCollection: (collection: UseTableCollectionReturn) => DragCollection<unknown>;

package/dist/composables/table-drag-collection.js

@@ -0,0 +1,54 @@
+//#region src/composables/table-drag-collection.ts
+/**
+* A `DragCollection` over a table's rows.
+*
+* A tree grid needs its own rather than the flat `toDragCollection`, because the drag layer asks
+* two different questions that a flat list answers identically and a tree does not:
+*
+* - **Document order** — `getKeyAfter`/`getKeyBefore`, which descend into open rows. This is how
+*   a drag steps down the table, one visible row at a time.
+* - **Sibling order** — `prevKey`/`nextKey` on a node, which skip over a row's whole subtree.
+*   This is how the drop layer recognises two names for the same gap, and how the tree delegate
+*   finds where a subtree ends.
+*
+* A flat table has one level, so the two coincide and this behaves exactly like the listbox
+* adapter.
+*/
+var toTableDragCollection = (collection) => {
+	const { rows, tree } = collection;
+	const levelOf = (key) => tree.getItem(key)?.level() ?? 0;
+	const parentOf = (key) => tree.getItem(key)?.parentKey() ?? null;
+	/** Rows sharing a parent, in document order. Empty for a table with no tree registered. */
+	const siblingsOf = (parentKey) => rows.orderedKeys().filter((key) => parentOf(key) === parentKey);
+	const siblingAt = (key, offset) => {
+		const siblings = siblingsOf(parentOf(key));
+		const index = siblings.indexOf(key);
+		if (index < 0) return null;
+		return siblings[index + offset] ?? null;
+	};
+	const childrenOf = (key) => siblingsOf(key);
+	return {
+		getItem: (key) => {
+			const row = rows.getItem(key);
+			if (!row) return null;
+			const children = childrenOf(key);
+			return {
+				firstChildKey: children[0] ?? null,
+				hasChildItems: tree.getItem(key)?.hasChildRows() ?? children.length > 0,
+				key,
+				lastChildKey: children[children.length - 1] ?? null,
+				level: levelOf(key),
+				nextKey: siblingAt(key, 1),
+				parentKey: parentOf(key),
+				prevKey: siblingAt(key, -1),
+				textValue: row.textValue(),
+				type: "item"
+			};
+		},
+		getKeyAfter: (key) => rows.getKeyAfter(key),
+		getKeyBefore: (key) => rows.getKeyBefore(key),
+		getKeys: () => rows.orderedKeys()
+	};
+};
+//#endregion
+export { toTableDragCollection };

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

@@ -0,0 +1,15 @@
+import type { ShallowRef } from "vue";
+export interface UseAutoScrollReturn {
+    /** Report the pointer position, in coordinates relative to the scrollable container. */
+    move: (x: number, y: number) => void;
+    stop: () => void;
+}
+/**
+ * Scroll a container while a drag hovers near its edge, ported from React Aria's `useAutoScroll`.
+ *
+ * A no-op in every engine except WebKit on macOS, which is the only one that does not do this
+ * itself during a drag. iOS WebKit does, so it is excluded too.
+ *
+ * @see https://bugs.webkit.org/show_bug.cgi?id=222636
+ */
+export declare const useAutoScroll: (element: ShallowRef<HTMLElement | null>) => UseAutoScrollReturn;

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

@@ -0,0 +1,68 @@
+import { getScrollParent, isScrollable } from "../utils/focus.js";
+import { isIOS, isWebKit } from "../utils/platform.js";
+import { onScopeDispose, watch } from "vue";
+//#region src/composables/use-auto-scroll.ts
+/** How close to an edge the pointer must come before the container starts scrolling. */
+var AUTOSCROLL_AREA_SIZE = 20;
+/**
+* Scroll a container while a drag hovers near its edge, ported from React Aria's `useAutoScroll`.
+*
+* A no-op in every engine except WebKit on macOS, which is the only one that does not do this
+* itself during a drag. iOS WebKit does, so it is excluded too.
+*
+* @see https://bugs.webkit.org/show_bug.cgi?id=222636
+*/
+var useAutoScroll = (element) => {
+	let scrollable = null;
+	let scrollableX = true;
+	let scrollableY = true;
+	let timer;
+	let dx = 0;
+	let dy = 0;
+	watch(element, (value) => {
+		if (!value) {
+			scrollable = null;
+			return;
+		}
+		scrollable = isScrollable(value) ? value : getScrollParent(value);
+		if (!scrollable) return;
+		const style = window.getComputedStyle(scrollable);
+		scrollableX = /(auto|scroll)/.test(style.overflowX);
+		scrollableY = /(auto|scroll)/.test(style.overflowY);
+	}, { immediate: true });
+	const stop = () => {
+		if (timer == null) return;
+		cancelAnimationFrame(timer);
+		timer = void 0;
+	};
+	const scroll = () => {
+		if (scrollable) {
+			if (scrollableX) scrollable.scrollLeft += dx;
+			if (scrollableY) scrollable.scrollTop += dy;
+		}
+		if (timer != null) timer = requestAnimationFrame(scroll);
+	};
+	onScopeDispose(stop);
+	return {
+		move(x, y) {
+			if (!isWebKit() || isIOS() || !scrollable) return;
+			const box = scrollable.getBoundingClientRect();
+			const left = AUTOSCROLL_AREA_SIZE;
+			const top = AUTOSCROLL_AREA_SIZE;
+			const right = box.width - AUTOSCROLL_AREA_SIZE;
+			const bottom = box.height - AUTOSCROLL_AREA_SIZE;
+			if (x >= left && x <= right && y >= top && y <= bottom) {
+				stop();
+				return;
+			}
+			if (x < left) dx = x - left;
+			else if (x > right) dx = x - right;
+			if (y < top) dy = y - top;
+			else if (y > bottom) dy = y - bottom;
+			if (timer == null) timer = requestAnimationFrame(scroll);
+		},
+		stop
+	};
+};
+//#endregion
+export { useAutoScroll };

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

@@ -0,0 +1,93 @@
+import type { UseCollectionReturn } from "./use-collection";
+import type { UseListKeyboardReturn } from "./use-list-keyboard";
+import type { UseSelectionManagerReturn } from "./use-selection-manager";
+import type { ComputedRef, MaybeRefOrGetter, ShallowRef } from "vue";
+/** Attributes the input renders so assistive technology reads the collection as its own. */
+export interface AutocompleteInputAttributes {
+    "aria-activedescendant": string | undefined;
+    "aria-autocomplete": string;
+    "aria-controls": string;
+    autocomplete: string;
+    autocorrect: string;
+    enterkeyhint: string;
+    spellcheck: string;
+}
+export interface UseAutocompleteOptions {
+    /**
+     * The keyboard behaviour of the collection below, with virtual focus turned on.
+     *
+     * Read through a getter because only the collection can build it — it is the one that knows
+     * its own element and its own layout — so it arrives once the collection has mounted, which in
+     * a picker is when the overlay opens.
+     */
+    keyboard: MaybeRefOrGetter<UseListKeyboardReturn | null | undefined>;
+    selection: UseSelectionManagerReturn;
+    collection: UseCollectionReturn;
+    /** The input that keeps real focus, reported by whichever control renders it. */
+    inputElement: ShallowRef<HTMLInputElement | null>;
+    /** The collection element's id, for `aria-controls`. */
+    collectionId: MaybeRefOrGetter<string>;
+    /** Text in the input. Present at all puts the caller in charge of it. */
+    inputValue?: MaybeRefOrGetter<string | undefined>;
+    defaultInputValue?: string;
+    onInputChange?: (value: string) => void;
+    /** Whether typing stops moving virtual focus onto the first option. @default false */
+    disableAutoFocusFirst?: MaybeRefOrGetter<boolean | undefined>;
+    /** Whether virtual focus is off entirely. @default false */
+    disableVirtualFocus?: MaybeRefOrGetter<boolean | undefined>;
+}
+export interface UseAutocompleteReturn {
+    inputValue: ComputedRef<string>;
+    setInputValue: (value: string) => void;
+    /** Feed into `useSearchField` / `useTextField`, which render every key of it. */
+    inputAttributes: ComputedRef<AutocompleteInputAttributes>;
+    /** Bind statically with `@keydown` — a handler must never travel through `v-bind`. */
+    onKeydown: (event: KeyboardEvent) => void;
+    onKeyup: (event: KeyboardEvent) => void;
+    onBlur: () => void;
+    /** Take virtual focus off whatever option holds it, leaving the input as the only focus. */
+    clearVirtualFocus: () => void;
+    /** Put virtual focus on the first option that can take it. */
+    focusFirstItem: () => void;
+}
+/**
+ * What an autocomplete hands down to whichever control renders its text input.
+ *
+ * Lives with the composable rather than with the component, for the same reason
+ * `TextFieldControlContext` does: `SearchField` is the control that consumes it, and routing it
+ * through the autocomplete's own directory would make that component depend on this one.
+ *
+ * Loose, and absent is the ordinary case — a search field standing on its own filters nothing.
+ */
+export interface AutocompleteInputContext extends Pick<UseAutocompleteReturn, "inputAttributes" | "inputValue" | "onBlur" | "onKeydown" | "onKeyup" | "setInputValue"> {
+    /** The control reports its element, which the beforeinput and pointer wiring hangs off. */
+    setInputElement: (element: HTMLInputElement | null) => void;
+}
+export declare const useAutocompleteInputContext: () => AutocompleteInputContext | null, provideAutocompleteInputContext: (value: AutocompleteInputContext | null) => AutocompleteInputContext | null;
+/**
+ * An input that drives a collection beside it, ported from React Aria's
+ * `packages/react-aria/src/autocomplete/useAutocomplete.ts` (react-aria 3.51.0).
+ *
+ * The whole arrangement is that real focus never leaves the input: the arrows move a *nominal*
+ * focus over the collection, the input names whichever option holds it with
+ * `aria-activedescendant`, and Enter acts on that option. Without it, arrowing into the options
+ * would take the caret out of the field the user is typing in.
+ *
+ * The event simulation upstream is deliberately left out. React has to dispatch synthetic
+ * `CustomEvent`s and re-dispatch `KeyboardEvent`s onto the collection element, because the
+ * collection's own keyboard layer lives in a different component and the DOM is the only channel
+ * between them. Here the caller holds both halves and hands the keyboard layer over directly, so
+ * the keys are simply passed to it — same behaviour, without the round trip through the DOM.
+ *
+ * @example
+ * ```ts
+ * const autocomplete = useAutocomplete({
+ *   collection,
+ *   collectionId: () => listId.value,
+ *   inputElement,
+ *   keyboard,
+ *   selection,
+ * });
+ * ```
+ */
+export declare const useAutocomplete: (options: UseAutocompleteOptions) => UseAutocompleteReturn;