ropav 0.4.0 → 0.6.0

package/dist/composables/use-collection.js

@@ -1,6 +1,26 @@
+import { sortByDocumentOrder } from "../utils/document-order.js";
 import { computed, shallowRef } from "vue";
 //#region src/composables/use-collection.ts
 /**
+* `key → index` for a data-backed collection, memoized on the source itself.
+*
+* A source is rebuilt whenever its data changes — it is handed over out of a `computed` — so its
+* identity is already the right cache key and nothing has to invalidate this by hand. Held weakly,
+* so a collection that has gone away takes its map with it.
+*
+* This is what keeps `getIndex` off a scan on the one path that has no operation to scope to:
+* `aria-posinset` and `aria-rowindex` are read during render, once per item, and a virtualized
+* collection's source holds every item rather than the rendered window.
+*/
+var sourceIndices = /* @__PURE__ */ new WeakMap();
+var indicesOf = (source) => {
+	const cached = sourceIndices.get(source);
+	if (cached) return cached;
+	const indices = new Map(source.keys.map((key, index) => [key, index]));
+	sourceIndices.set(source, indices);
+	return indices;
+};
+/**
 * The set of items a listbox, menu or tag group navigates over.
 *
 * React Aria builds this by rendering the children into a hidden tree and reading the result
@@ -8,7 +28,7 @@ import { computed, shallowRef } from "vue";
 * 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
@@ -18,8 +38,20 @@ import { computed, shallowRef } from "vue";
 * 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
@@ -56,18 +88,38 @@ var useCollection = (options = {}) => {
 			textValue: () => node.textValue ?? ""
 		};
 	};
-	const orderedKeys = () => {
+	const domOrderedKeys = () => sortByDocumentOrder([...items.entries()], ([, meta]) => meta.element()).map(([key]) => key);
+	const buildOrder = () => {
 		const sourced = source();
-		if (sourced) return sourced.keys;
-		return domOrderedKeys();
+		const keys = sourced ? sourced.keys : domOrderedKeys();
+		let indices = sourced ? indicesOf(sourced) : null;
+		return {
+			indexOf: (key) => {
+				indices ??= new Map(keys.map((entry, index) => [entry, index]));
+				return indices.get(key) ?? -1;
+			},
+			keys
+		};
 	};
-	const domOrderedKeys = () => [...items.entries()].filter(([, meta]) => meta.element()?.isConnected).sort(([, a], [, b]) => a.element().compareDocumentPosition(b.element()) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1).map(([key]) => key);
-	const keyAt = (index) => {
-		return orderedKeys()[index] ?? null;
+	/** The order this operation is reading, or a fresh reading for a call that stands alone. */
+	let scoped = null;
+	let depth = 0;
+	const order = () => scoped ?? buildOrder();
+	const withOrder = (operation) => {
+		if (depth === 0) scoped = buildOrder();
+		depth += 1;
+		try {
+			return operation();
+		} finally {
+			depth -= 1;
+			if (depth === 0) scoped = null;
+		}
 	};
+	const orderedKeys = () => order().keys;
+	const keyAt = (index) => order().keys[index] ?? null;
 	const neighbour = (key, step) => {
-		const keys = orderedKeys();
-		const index = keys.indexOf(key);
+		const { indexOf, keys } = order();
+		const index = indexOf(key);
 		if (index === -1) return null;
 		return keys[index + step] ?? null;
 	};
@@ -76,18 +128,19 @@ var useCollection = (options = {}) => {
 			return items.get(key)?.element() ?? null;
 		},
 		getFirstKey: () => keyAt(0),
-		getIndex: (key) => orderedKeys().indexOf(key),
+		getIndex: (key) => order().indexOf(key),
 		getItem: (key) => {
 			return items.get(key) ?? metaFromSource(key);
 		},
 		getKeyAfter: (key) => neighbour(key, 1),
 		getKeyBefore: (key) => neighbour(key, -1),
-		getLastKey: () => keyAt(orderedKeys().length - 1),
+		getLastKey: () => order().keys.at(-1) ?? null,
 		orderedKeys,
 		register,
 		size: computed(() => {
 			return source()?.itemCount ?? items.size;
-		})
+		}),
+		withOrder
 	};
 };
 //#endregion

package/dist/composables/use-color-area.js

@@ -1,3 +1,4 @@
+import { useMove } from "./use-move.js";
 import { useLocale } from "./use-locale.js";
 import { useLocalizedStringFormatter } from "./use-localized-string-formatter.js";
 import { colorStrings } from "../i18n/color.js";
@@ -6,7 +7,6 @@ import { visuallyHiddenStyle } from "../utils/visually-hidden.js";
 import { useLabels } from "./use-labels.js";
 import { setFormValue } from "../utils/form-value.js";
 import { useColorAreaGradient } from "./use-color-area-gradient.js";
-import { useMove } from "./use-move.js";
 import { computed, onScopeDispose, shallowRef, toValue, watch } from "vue";
 //#region src/composables/use-color-area.ts
 /**
@@ -68,7 +68,7 @@ var useColorArea = (options) => {
 		flush: "post",
 		immediate: true
 	});
-	useFormReset(inputXEl, () => state.defaultValue.value, state.setValue);
+	useFormReset(inputXEl, () => state.defaultValue.value, state.setValue, options.form);
 	/** Where the thumb is during a drag, in fractions of the area — not in pixels. */
 	let currentPosition = null;
 	/** The pointer that owns the interaction in flight, if any. */

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

@@ -86,7 +86,7 @@ var useColorField = (options = {}) => {
 		setInputValue: state.setInputValue,
 		validate: state.validate
 	});
-	useFormReset(field.element, () => state.defaultColorValue.value, state.setColorValue);
+	useFormReset(field.element, () => state.defaultColorValue.value, state.setColorValue, options.form);
 	/**
 	* Whether the input has focus, which gates the wheel.
 	*

package/dist/composables/use-combo-box.js

@@ -119,7 +119,7 @@ var useComboBox = (options, state) => {
 		validationState: state,
 		value: () => state.inputValue.value
 	});
-	useFormReset(computed(() => inputElement.value), () => state.defaultValue.value, state.setValue);
+	useFormReset(computed(() => inputElement.value), () => state.defaultValue.value, state.setValue, options.form);
 	/**
 	* Whether focus is still somewhere inside the combo box.
 	*

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

@@ -89,7 +89,7 @@ var useDateField = (options) => {
 		options.onFocusChange?.(false);
 	};
 	const inputValue = computed(() => toValue(options.inputValue) ?? state.value.value?.toString() ?? "");
-	useFormReset(options.inputElement, state.defaultValue, state.setValue);
+	useFormReset(options.inputElement, state.defaultValue, state.setValue, options.form);
 	watch([options.inputElement, inputValue], ([input, text]) => setFormValue(input, text), {
 		flush: "post",
 		immediate: true

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

@@ -31,12 +31,13 @@ export interface UseDragHandlers {
     onKeyupCapture?: (event: KeyboardEvent) => void;
     onClick?: (event: MouseEvent) => void;
 }
+/** Attributes for a draggable element. Attributes only, never listeners. */
+export interface DragAttrs {
+    draggable?: "true" | "false";
+    "aria-describedby"?: string;
+}
 export interface UseDragReturn {
-    /** Attributes for the draggable element. Attributes only, never listeners. */
-    attrs: ComputedRef<{
-        draggable: "true" | "false";
-        "aria-describedby"?: string;
-    }>;
+    attrs: ComputedRef<Required<Pick<DragAttrs, "draggable">> & DragAttrs>;
     handlers: UseDragHandlers;
     /** Attributes for the explicit drag control, when there is one. */
     dragButtonAttrs: ComputedRef<{

package/dist/composables/use-draggable-item.d.ts

@@ -1,5 +1,5 @@
 import type { DragKey } from "../utils/dnd-types.js";
-import type { UseDragHandlers } from "./use-drag.js";
+import type { DragAttrs, UseDragHandlers } from "./use-drag.js";
 import type { UseDraggableCollectionStateReturn } from "./use-draggable-collection-state.js";
 import type { PressEvent } from "./use-press.js";
 import type { ComputedRef, MaybeRefOrGetter } from "vue";
@@ -16,7 +16,7 @@ export interface UseDraggableItemOptions {
     hasAction?: MaybeRefOrGetter<boolean | undefined>;
 }
 export interface UseDraggableItemReturn {
-    attrs: ComputedRef<Record<string, unknown>>;
+    attrs: ComputedRef<DragAttrs>;
     handlers: UseDragHandlers;
     dragButtonAttrs: ComputedRef<{
         "aria-describedby": string | undefined;

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

@@ -3,11 +3,11 @@ import { useLocale } from "./use-locale.js";
 import { DIRECTORY_DRAG_TYPE } from "../utils/dnd-constants.js";
 import { dragTypesFromSet, getTypes } from "../utils/dnd-data-transfer.js";
 import { registerDropTarget } from "./drag-manager.js";
-import { registerDroppableCollection } from "./droppable-collection-registry.js";
-import { useAutoScroll } from "./use-auto-scroll.js";
 import { clearGlobalDnDState, globalDndState, isInternalDropOperation, setDropCollectionRef } from "../utils/dnd-state.js";
-import { navigateDropTarget } from "../utils/dnd-drop-target-navigation.js";
 import { useDrop } from "./use-drop.js";
+import { registerDroppableCollection } from "./droppable-collection-registry.js";
+import { navigateDropTarget } from "../utils/dnd-drop-target-navigation.js";
+import { useAutoScroll } from "./use-auto-scroll.js";
 import { computed, onScopeDispose, useId, watch } from "vue";
 //#region src/composables/use-droppable-collection.ts
 /** How long to wait for a drop handler's async work before deciding where focus lands. */

package/dist/composables/use-droppable-item.js

@@ -1,8 +1,8 @@
 import { getTypes } from "../utils/dnd-data-transfer.js";
 import { registerDropItem, useDragSession } from "./drag-manager.js";
-import { getDroppableCollectionElement } from "./droppable-collection-registry.js";
 import { globalDndState, isInternalDropOperation } from "../utils/dnd-state.js";
 import { useVirtualDrop } from "./use-virtual-drop.js";
+import { getDroppableCollectionElement } from "./droppable-collection-registry.js";
 import { computed, watch } from "vue";
 //#region src/composables/use-droppable-item.ts
 /**

package/dist/composables/use-form-reset.d.ts

@@ -13,11 +13,15 @@ type ResettableElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElem
  * `initialValue` is read when the reset happens rather than when the listener is attached,
  * so a default that changes over the component's life still resets to the current one.
  *
+ * `form` is the `id` the caller renders as the control's `form` attribute, for a control that
+ * submits to a form it does not sit inside. Pass it wherever that attribute is rendered: it is
+ * what moves the listener when a mounted control is repointed.
+ *
  * @example
  * ```ts
  * const input = useTemplateRef<HTMLInputElement>("input");
- * useFormReset(input, () => props.defaultSelected ?? false, setSelected);
+ * useFormReset(input, () => props.defaultSelected ?? false, setSelected, () => props.form);
  * ```
  */
-export declare const useFormReset: <T>(element: Ref<ResettableElement | null | undefined>, initialValue: MaybeRefOrGetter<T>, onReset: (value: T) => void) => void;
+export declare const useFormReset: <T>(element: Ref<ResettableElement | null | undefined>, initialValue: MaybeRefOrGetter<T>, onReset: (value: T) => void, form?: MaybeRefOrGetter<string | undefined>) => void;
 export {};

package/dist/composables/use-form-reset.js

@@ -12,13 +12,17 @@ import { onScopeDispose, toValue, watch } from "vue";
 * `initialValue` is read when the reset happens rather than when the listener is attached,
 * so a default that changes over the component's life still resets to the current one.
 *
+* `form` is the `id` the caller renders as the control's `form` attribute, for a control that
+* submits to a form it does not sit inside. Pass it wherever that attribute is rendered: it is
+* what moves the listener when a mounted control is repointed.
+*
 * @example
 * ```ts
 * const input = useTemplateRef<HTMLInputElement>("input");
-* useFormReset(input, () => props.defaultSelected ?? false, setSelected);
+* useFormReset(input, () => props.defaultSelected ?? false, setSelected, () => props.form);
 * ```
 */
-var useFormReset = (element, initialValue, onReset) => {
+var useFormReset = (element, initialValue, onReset, form) => {
 	let attachedForm = null;
 	const onFormReset = (event) => {
 		if (event.defaultPrevented) return;
@@ -28,10 +32,10 @@ var useFormReset = (element, initialValue, onReset) => {
 		attachedForm?.removeEventListener("reset", onFormReset);
 		attachedForm = null;
 	};
-	watch(() => element.value?.form ?? null, (form) => {
+	watch([() => element.value?.form ?? null, () => toValue(form)], ([owner]) => {
 		detach();
-		form?.addEventListener("reset", onFormReset);
-		attachedForm = form;
+		owner?.addEventListener("reset", onFormReset);
+		attachedForm = owner;
 	}, {
 		flush: "post",
 		immediate: true

package/dist/composables/use-list-keyboard.js

@@ -169,7 +169,7 @@ var useListKeyboard = (options) => {
 		}
 		return next ?? (step === 1 ? getLastKey() : getFirstKey());
 	};
-	const getKeyForSearch = (search, fromKey) => {
+	const getKeyForSearch = (search, fromKey) => collection.withOrder(() => {
 		let key = fromKey ?? getFirstKey();
 		while (key != null) {
 			const item = collection.getItem(key);
@@ -179,7 +179,7 @@ var useListKeyboard = (options) => {
 			key = walk(collection.getKeyAfter(key), 1);
 		}
 		return null;
-	};
+	});
 	const land = (element, scroll) => {
 		if (!isVirtual.value) element.focus();
 		if (scroll && typeof element.scrollIntoView === "function") element.scrollIntoView({ block: "nearest" });
@@ -228,67 +228,69 @@ var useListKeyboard = (options) => {
 			event.stopPropagation();
 			return true;
 		};
-		switch (event.key) {
-			case "ArrowDown":
-				move(focused == null ? getFirstKey() : getKeyBelow(focused));
-				return;
-			case "ArrowUp":
-				move(focused == null ? getLastKey() : getKeyAbove(focused));
-				return;
-			case "ArrowRight":
-				if (!answersInlineAxis()) return;
-				move(focused == null ? getFirstKey() : getKeyRightOf(focused));
-				return;
-			case "ArrowLeft":
-				if (!answersInlineAxis()) return;
-				move(focused == null ? getLastKey() : getKeyLeftOf(focused));
-				return;
-			case "Home":
-				if (focused == null && event.shiftKey) return;
-				move(getFirstKey(), false);
-				return;
-			case "End":
-				if (focused == null && event.shiftKey) return;
-				move(getLastKey(), false);
-				return;
-			case "PageUp":
-				move(focused == null ? getFirstKey() : pageStep(focused, -1));
-				return;
-			case "PageDown":
-				move(focused == null ? getLastKey() : pageStep(focused, 1));
-				return;
-			case "a":
-				if (!(event.ctrlKey || event.metaKey) || toValue(options.disallowSelectAll)) return;
-				if (selection.selectionMode.value !== "multiple") return;
-				selection.selectAll();
-				event.preventDefault();
-				event.stopPropagation();
-				return;
-			case "Escape":
-				if (escapeKeyBehavior.value !== "clearSelection" || selection.isEmpty.value) return;
-				selection.clearSelection();
-				event.preventDefault();
-				event.stopPropagation();
-				return;
-			case "Tab": {
-				if (isVirtual.value) return;
-				const focusable = focusableIn(element);
-				(event.shiftKey ? element : focusable.at(-1))?.focus();
-				return;
+		collection.withOrder(() => {
+			switch (event.key) {
+				case "ArrowDown":
+					move(focused == null ? getFirstKey() : getKeyBelow(focused));
+					return;
+				case "ArrowUp":
+					move(focused == null ? getLastKey() : getKeyAbove(focused));
+					return;
+				case "ArrowRight":
+					if (!answersInlineAxis()) return;
+					move(focused == null ? getFirstKey() : getKeyRightOf(focused));
+					return;
+				case "ArrowLeft":
+					if (!answersInlineAxis()) return;
+					move(focused == null ? getLastKey() : getKeyLeftOf(focused));
+					return;
+				case "Home":
+					if (focused == null && event.shiftKey) return;
+					move(getFirstKey(), false);
+					return;
+				case "End":
+					if (focused == null && event.shiftKey) return;
+					move(getLastKey(), false);
+					return;
+				case "PageUp":
+					move(focused == null ? getFirstKey() : pageStep(focused, -1));
+					return;
+				case "PageDown":
+					move(focused == null ? getLastKey() : pageStep(focused, 1));
+					return;
+				case "a":
+					if (!(event.ctrlKey || event.metaKey) || toValue(options.disallowSelectAll)) return;
+					if (selection.selectionMode.value !== "multiple") return;
+					selection.selectAll();
+					event.preventDefault();
+					event.stopPropagation();
+					return;
+				case "Escape":
+					if (escapeKeyBehavior.value !== "clearSelection" || selection.isEmpty.value) return;
+					selection.clearSelection();
+					event.preventDefault();
+					event.stopPropagation();
+					return;
+				case "Tab": {
+					if (isVirtual.value) return;
+					const focusable = focusableIn(element);
+					(event.shiftKey ? element : focusable.at(-1))?.focus();
+					return;
+				}
+				case "Enter":
+					if (focused == null || toValue(options.disallowActivation)) return;
+					options.onAction?.(focused);
+					event.preventDefault();
+					return;
+				case " ":
+					if (focused == null || toValue(options.disallowActivation)) return;
+					if (selection.selectionMode.value === "none") options.onAction?.(focused);
+					else selection.select(focused, { isShiftPressed: event.shiftKey });
+					event.preventDefault();
+					return;
+				default: return;
 			}
-			case "Enter":
-				if (focused == null || toValue(options.disallowActivation)) return;
-				options.onAction?.(focused);
-				event.preventDefault();
-				return;
-			case " ":
-				if (focused == null || toValue(options.disallowActivation)) return;
-				if (selection.selectionMode.value === "none") options.onAction?.(focused);
-				else selection.select(focused, { isShiftPressed: event.shiftKey });
-				event.preventDefault();
-				return;
-			default: return;
-		}
+		});
 	};
 	const onFocusin = (event) => {
 		if (isVirtual.value) return;

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,

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