@vizejs/ui 0.345.0 → 0.350.2

package/dist/collection-eHN150dT.mjs

@@ -0,0 +1,453 @@
+import { computed, getCurrentScope, onScopeDispose, shallowRef, toValue, watch } from "vue";
+//#region src/collection-keys.ts
+/** Reject keys that cannot serve as stable, serializable item identities. */
+function validateCollectionKey(key) {
+	if (typeof key === "string") {
+		if (key.length === 0 || containsAsciiControl(key)) throw new Error("VIZE_UI_COLLECTION_KEY_VALUE: a string key must be non-empty and contain no ASCII controls");
+		return;
+	}
+	if (!Number.isSafeInteger(key) || Object.is(key, -0)) throw new Error("VIZE_UI_COLLECTION_KEY_VALUE: a numeric key must be a safe integer other than negative zero");
+}
+/** Whether a resolved item list still contains a key. */
+function hasCollectionKey(items, key) {
+	return items.some((item) => item.key === key);
+}
+/**
+* Pick the logical focus successor for a key that left the navigable set.
+*
+* The next navigable item wins, then the previous one, so removing or
+* disabling the active item never orphans logical focus.
+*/
+function recoverCollectionKey(removedKey, previousItems, nextItems) {
+	if (nextItems.length === 0) return null;
+	const nextKeys = new Set(nextItems.map((item) => item.key));
+	const previousIndex = previousItems.findIndex((item) => item.key === removedKey);
+	if (previousIndex < 0) return nextItems[0]?.key ?? null;
+	for (let index = previousIndex + 1; index < previousItems.length; index++) {
+		const key = previousItems[index]?.key;
+		if (key !== void 0 && nextKeys.has(key)) return key;
+	}
+	for (let index = previousIndex - 1; index >= 0; index--) {
+		const key = previousItems[index]?.key;
+		if (key !== void 0 && nextKeys.has(key)) return key;
+	}
+	return nextItems[0]?.key ?? null;
+}
+function containsAsciiControl(value) {
+	for (let index = 0; index < value.length; index++) {
+		const code = value.charCodeAt(index);
+		if (code <= 31 || code === 127) return true;
+	}
+	return false;
+}
+//#endregion
+//#region src/collection-observer.ts
+const orderAndTextMutations = {
+	attributeFilter: [
+		"alt",
+		"aria-hidden",
+		"aria-label",
+		"aria-labelledby",
+		"hidden",
+		"inert",
+		"title",
+		"type",
+		"value"
+	],
+	attributes: true,
+	characterData: true,
+	childList: true,
+	subtree: true
+};
+const mountMutations = {
+	childList: true,
+	subtree: true
+};
+/**
+* Observe DOM ordering and accessible text mutations for registered items.
+*
+* One observer is created per owning document. Connected items use their
+* closest common ancestor and disconnected items are observed directly, so
+* attribute and text noise from the rest of the document is never observed.
+* Disconnected items additionally use a structure-only document observer that
+* reports only once one of them mounts, because their insertion point is
+* unknowable beforehand.
+*/
+function observeCollectionMutations(items, onMutation) {
+	const elementsByDocument = /* @__PURE__ */ new Map();
+	for (const { element } of items) {
+		if (element === null) continue;
+		const elements = elementsByDocument.get(element.ownerDocument) ?? [];
+		elements.push(element);
+		elementsByDocument.set(element.ownerDocument, elements);
+	}
+	const observers = [];
+	for (const [ownerDocument, elements] of elementsByDocument) {
+		const MutationObserverConstructor = ownerDocument.defaultView?.MutationObserver;
+		if (MutationObserverConstructor === void 0) continue;
+		const observer = new MutationObserverConstructor(onMutation);
+		const connectedElements = elements.filter((element) => element.isConnected);
+		const disconnectedElements = elements.filter((element) => !element.isConnected);
+		const commonAncestor = connectedElements.length === elements.length ? findCollectionObservationRoot(connectedElements) : null;
+		const connectedRoot = commonAncestor === null ? findCollectionObservationRoot(connectedElements) : commonAncestor;
+		const targets = commonAncestor === null ? new Set([...connectedRoot === null ? connectedElements : [connectedRoot], ...disconnectedElements]) : new Set([commonAncestor]);
+		for (const target of targets) observer.observe(target, orderAndTextMutations);
+		observers.push(observer);
+		if (disconnectedElements.length === 0) continue;
+		const mountObserver = new MutationObserverConstructor(() => {
+			if (disconnectedElements.some((element) => element.isConnected)) onMutation();
+		});
+		mountObserver.observe(ownerDocument.documentElement, mountMutations);
+		observers.push(mountObserver);
+	}
+	return observers;
+}
+function findCollectionObservationRoot(elements) {
+	const firstElement = elements[0];
+	if (firstElement === void 0) return null;
+	let candidate = firstElement.parentNode ?? firstElement;
+	while (candidate !== null) {
+		if (elements.every((element) => candidate === element || candidate?.contains(element) === true)) return candidate;
+		candidate = candidate.parentNode;
+	}
+	return null;
+}
+//#endregion
+//#region src/collection-text.ts
+const ignoredTextTags = new Set([
+	"NOSCRIPT",
+	"SCRIPT",
+	"STYLE",
+	"TEMPLATE"
+]);
+/**
+* Normalize authored or extracted typeahead text without applying a locale.
+*
+* Unicode is normalized to NFC and every whitespace run becomes one ASCII
+* space. Locale-sensitive equality remains the responsibility of a collator.
+*/
+function normalizeCollectionTextValue(value) {
+	return value.normalize("NFC").trim().replace(/\s+/gu, " ");
+}
+/**
+* Extract a practical accessible text value from an item element.
+*
+* `aria-labelledby` and `aria-label` take precedence, hidden descendants are
+* excluded unless explicitly referenced, and image/input fallbacks are
+* included. Complex widgets should still provide `textValue` explicitly when
+* their typeahead label differs from their accessible name.
+*/
+function extractCollectionTextValue(element) {
+	return normalizeCollectionTextValue(readElementText(element, /* @__PURE__ */ new Set(), false));
+}
+/** Whether a candidate text starts with a query under locale-aware comparison. */
+function collectionTextStartsWith(candidate, query, collator) {
+	let codeUnitLength = 0;
+	for (const character of candidate) {
+		codeUnitLength += character.length;
+		if (collator.compare(candidate.slice(0, codeUnitLength), query) === 0) return true;
+	}
+	return false;
+}
+function readElementText(element, visited, referenced) {
+	if (visited.has(element)) return "";
+	visited.add(element);
+	if (!referenced && isCollectionTextHidden(element)) return "";
+	const labelledBy = element.getAttribute("aria-labelledby");
+	if (labelledBy !== null) {
+		const root = element.getRootNode();
+		const referenceRoot = hasGetElementById(root) ? root : element.ownerDocument;
+		const labelledText = labelledBy.split(/\s+/u).filter((id) => id.length > 0).map((id) => referenceRoot.getElementById(id)).filter((label) => label !== null).map((label) => readElementText(label, visited, true)).join(" ");
+		if (normalizeCollectionTextValue(labelledText).length > 0) return labelledText;
+	}
+	const ariaLabel = element.getAttribute("aria-label");
+	if (ariaLabel !== null && normalizeCollectionTextValue(ariaLabel).length > 0) return ariaLabel;
+	const tagName = element.tagName.toUpperCase();
+	if (tagName === "IMG" || tagName === "AREA") {
+		const alternative = element.getAttribute("alt");
+		if (alternative !== null) return alternative;
+	}
+	if (tagName === "INPUT") {
+		const type = element.getAttribute("type")?.toLowerCase();
+		if (type === "button" || type === "reset" || type === "submit") {
+			const value = element.value;
+			if (value.length > 0) return value;
+		}
+	}
+	if (!ignoredTextTags.has(tagName)) {
+		const fragments = [];
+		for (const child of element.childNodes) if (child.nodeType === 3) fragments.push(child.nodeValue ?? "");
+		else if (child.nodeType === 1) fragments.push(readElementText(child, visited, referenced));
+		const content = fragments.join("");
+		if (normalizeCollectionTextValue(content).length > 0) return content;
+	}
+	return element.getAttribute("title") ?? "";
+}
+function hasGetElementById(node) {
+	return "getElementById" in node && typeof node.getElementById === "function";
+}
+function isCollectionTextHidden(element) {
+	return element.hasAttribute("hidden") || element.hasAttribute("inert") || element.getAttribute("aria-hidden")?.trim().toLowerCase() === "true";
+}
+//#endregion
+//#region src/collection-order.ts
+const documentPositionDisconnected = 1;
+const documentPositionPreceding = 2;
+const documentPositionFollowing = 4;
+/** Resolve every reactive source of one record into an immutable snapshot. */
+function resolveCollectionRecord(record) {
+	const { input } = record;
+	const element = input.element === void 0 ? null : toValue(input.element) ?? null;
+	const explicitText = input.textValue === void 0 ? void 0 : toValue(input.textValue);
+	const order = input.order === void 0 ? void 0 : toValue(input.order);
+	if (order !== void 0 && !Number.isSafeInteger(order)) throw new Error(`VIZE_UI_COLLECTION_ORDER_VALUE: ${String(input.key)} requires a safe integer order`);
+	return {
+		sequence: record.sequence,
+		item: Object.freeze({
+			key: input.key,
+			value: input.value,
+			element,
+			textValue: explicitText === null || explicitText === void 0 ? element === null ? "" : extractCollectionTextValue(element) : normalizeCollectionTextValue(explicitText),
+			disabled: input.disabled === void 0 ? false : Boolean(toValue(input.disabled)),
+			order
+		})
+	};
+}
+/**
+* Sort resolved records in place using explicit order, DOM order, or
+* registration order, rejecting ambiguous mixes of explicit orders.
+*/
+function sortCollectionRecords(records) {
+	const explicitOrderCount = records.filter(({ item }) => item.order !== void 0).length;
+	if (explicitOrderCount > 0 && explicitOrderCount !== records.length) throw new Error("VIZE_UI_COLLECTION_ORDER_PARTIAL: every item must provide order when explicit ordering is used");
+	if (explicitOrderCount === records.length && records.length > 0) {
+		const seenOrders = /* @__PURE__ */ new Set();
+		for (const { item } of records) {
+			const order = item.order;
+			if (order === void 0) continue;
+			if (seenOrders.has(order)) throw new Error(`VIZE_UI_COLLECTION_ORDER_DUPLICATE: order ${String(order)} is registered more than once`);
+			seenOrders.add(order);
+		}
+		records.sort((left, right) => (left.item.order ?? 0) - (right.item.order ?? 0));
+		return;
+	}
+	const ownerDocument = records[0]?.item.element?.ownerDocument;
+	if (!(ownerDocument !== void 0 && records.every(({ item }) => item.element !== null && item.element.isConnected && item.element.ownerDocument === ownerDocument))) {
+		records.sort((left, right) => left.sequence - right.sequence);
+		return;
+	}
+	records.sort((left, right) => {
+		const leftElement = left.item.element;
+		const rightElement = right.item.element;
+		if (leftElement !== null && rightElement !== null && leftElement !== rightElement) {
+			const position = leftElement.compareDocumentPosition(rightElement);
+			if ((position & documentPositionDisconnected) === 0) {
+				if ((position & documentPositionFollowing) !== 0) return -1;
+				if ((position & documentPositionPreceding) !== 0) return 1;
+			}
+		}
+		return left.sequence - right.sequence;
+	});
+}
+//#endregion
+//#region src/collection-registry.ts
+/**
+* Create an SSR-safe, mutation-aware registry for one compound collection.
+*
+* The registry never moves DOM focus itself. Consumers bind `activeKey` to
+* roving tabindex or `aria-activedescendant`; synchronous recovery guarantees
+* that removing or disabling the active item selects the next navigable item,
+* then the previous one, before the mutation can leave focus state orphaned.
+*/
+function createCollectionRegistry(options = {}) {
+	const disabledBehavior = options.disabledBehavior ?? "skip";
+	const collator = options.collator ?? new Intl.Collator(void 0, {
+		sensitivity: "base",
+		usage: "search"
+	});
+	const records = /* @__PURE__ */ new Map();
+	const revision = shallowRef(0);
+	const activeKeyState = shallowRef(null);
+	const activeKey = computed(() => activeKeyState.value);
+	let sequence = 0;
+	let disposed = false;
+	let mutationObservers = [];
+	let observedElements;
+	let observedConnected = [];
+	const items = computed(() => {
+		revision.value;
+		const resolved = [...records.values()].map(resolveCollectionRecord);
+		sortCollectionRecords(resolved);
+		return Object.freeze(resolved.map(({ item }) => item));
+	});
+	const navigableItems = computed(() => {
+		const resolved = items.value.filter((item) => disabledBehavior === "focusable" || !item.disabled);
+		return Object.freeze(resolved);
+	});
+	const updateActiveKey = (key, reason) => {
+		const previousKey = activeKeyState.value;
+		if (previousKey === key) return false;
+		activeKeyState.value = key;
+		options.onActiveKeyChange?.(Object.freeze({
+			key,
+			previousKey,
+			reason
+		}));
+		return true;
+	};
+	const stopRecovery = watch(navigableItems, (nextItems, previousItems) => {
+		const activeKey = activeKeyState.value;
+		if (activeKey === null || hasCollectionKey(nextItems, activeKey)) return;
+		const reason = hasCollectionKey(items.value, activeKey) ? "item-disabled" : "item-removed";
+		updateActiveKey(recoverCollectionKey(activeKey, previousItems, nextItems), reason);
+	}, { flush: "sync" });
+	const stopObservation = watch(items, (nextItems) => {
+		const nextElements = nextItems.map(({ element }) => element);
+		const nextConnected = nextElements.map((element) => element?.isConnected === true);
+		if (observedElements !== void 0 && observedElements.length === nextElements.length && observedElements.every((element, index) => element === nextElements[index] && observedConnected[index] === nextConnected[index])) return;
+		for (const observer of mutationObservers) observer.disconnect();
+		mutationObservers = observeCollectionMutations(nextItems, () => {
+			if (!disposed) revision.value += 1;
+		});
+		observedElements = nextElements;
+		observedConnected = nextConnected;
+	}, {
+		flush: "sync",
+		immediate: true
+	});
+	const assertMutable = () => {
+		if (disposed) throw new Error("VIZE_UI_COLLECTION_DISPOSED: a disposed registry cannot be mutated");
+	};
+	const refresh = () => {
+		assertMutable();
+		revision.value += 1;
+	};
+	const getItem = (key) => items.value.find((item) => item.key === key);
+	const setActiveKey = (key) => {
+		assertMutable();
+		if (key === null) return updateActiveKey(null, "programmatic");
+		const item = getItem(key);
+		if (item === void 0) throw new Error(`VIZE_UI_COLLECTION_KEY_MISSING: no item is registered for ${String(key)}`);
+		if (disabledBehavior === "skip" && item.disabled) throw new Error(`VIZE_UI_COLLECTION_KEY_DISABLED: ${String(key)} is not navigable`);
+		return updateActiveKey(key, "programmatic");
+	};
+	const getNavigationKey = (direction, navigationOptions = {}) => {
+		const candidates = navigableItems.value;
+		if (candidates.length === 0) return null;
+		if (direction === "first") return candidates[0]?.key ?? null;
+		if (direction === "last") return candidates.at(-1)?.key ?? null;
+		const fromKey = navigationOptions.fromKey === void 0 ? activeKeyState.value : navigationOptions.fromKey;
+		if (fromKey === null) return direction === "next" ? candidates[0]?.key ?? null : candidates.at(-1)?.key ?? null;
+		const candidateIndex = candidates.findIndex((item) => item.key === fromKey);
+		if (candidateIndex >= 0) {
+			const target = candidates[candidateIndex + (direction === "next" ? 1 : -1)];
+			if (target !== void 0) return target.key;
+			if (navigationOptions.loop === true) return direction === "next" ? candidates[0]?.key ?? null : candidates.at(-1)?.key ?? null;
+			return fromKey;
+		}
+		const allItems = items.value;
+		const itemIndex = allItems.findIndex((item) => item.key === fromKey);
+		if (itemIndex >= 0) {
+			const step = direction === "next" ? 1 : -1;
+			for (let index = itemIndex + step; index >= 0 && index < allItems.length; index += step) {
+				const candidate = allItems[index];
+				if (candidate !== void 0 && hasCollectionKey(candidates, candidate.key)) return candidate.key;
+			}
+			if (navigationOptions.loop !== true) return null;
+		}
+		return direction === "next" ? candidates[0]?.key ?? null : candidates.at(-1)?.key ?? null;
+	};
+	const moveActive = (direction, navigationOptions = {}) => {
+		assertMutable();
+		const target = getNavigationKey(direction, navigationOptions);
+		if (target !== null) updateActiveKey(target, "navigation");
+		return target;
+	};
+	const findByTextValue = (query, searchOptions = {}) => {
+		const normalizedQuery = normalizeCollectionTextValue(query);
+		if (normalizedQuery.length === 0) return null;
+		const candidates = navigableItems.value;
+		if (candidates.length === 0) return null;
+		const fromKey = searchOptions.fromKey === void 0 ? activeKeyState.value : searchOptions.fromKey;
+		const fromIndex = fromKey === null ? -1 : candidates.findIndex((candidate) => candidate.key === fromKey);
+		const after = candidates.slice(fromIndex + 1);
+		const before = searchOptions.loop === false ? [] : candidates.slice(0, fromIndex + 1);
+		const searchCandidates = [...after, ...before];
+		const searchCollator = searchOptions.collator ?? collator;
+		const match = searchOptions.match ?? "prefix";
+		for (const candidate of searchCandidates) {
+			if (candidate.textValue.length === 0) continue;
+			if (match === "exact" ? searchCollator.compare(candidate.textValue, normalizedQuery) === 0 : collectionTextStartsWith(candidate.textValue, normalizedQuery, searchCollator)) return candidate.key;
+		}
+		return null;
+	};
+	const moveActiveByTextValue = (query, searchOptions = {}) => {
+		assertMutable();
+		const target = findByTextValue(query, searchOptions);
+		if (target !== null) updateActiveKey(target, "typeahead");
+		return target;
+	};
+	const register = (input) => {
+		assertMutable();
+		validateCollectionKey(input.key);
+		if (records.has(input.key)) throw new Error(`VIZE_UI_COLLECTION_KEY_DUPLICATE: ${String(input.key)} is already registered`);
+		const record = {
+			input: Object.freeze({ ...input }),
+			sequence: sequence++
+		};
+		records.set(input.key, record);
+		try {
+			revision.value += 1;
+		} catch (error) {
+			records.delete(input.key);
+			revision.value += 1;
+			throw error;
+		}
+		const unregister = () => {
+			if (records.get(input.key) !== record) return false;
+			records.delete(input.key);
+			revision.value += 1;
+			return true;
+		};
+		const registration = Object.freeze({
+			key: input.key,
+			registered: computed(() => {
+				revision.value;
+				return records.get(input.key) === record;
+			}),
+			unregister
+		});
+		if (getCurrentScope() !== void 0) onScopeDispose(unregister);
+		return registration;
+	};
+	const dispose = () => {
+		if (disposed) return false;
+		disposed = true;
+		stopRecovery();
+		stopObservation();
+		for (const observer of mutationObservers) observer.disconnect();
+		mutationObservers = [];
+		records.clear();
+		revision.value += 1;
+		updateActiveKey(null, "registry-disposed");
+		return true;
+	};
+	const registry = Object.freeze({
+		items,
+		navigableItems,
+		activeKey,
+		register,
+		getItem,
+		refresh,
+		setActiveKey,
+		getNavigationKey,
+		moveActive,
+		findByTextValue,
+		moveActiveByTextValue,
+		dispose
+	});
+	if (getCurrentScope() !== void 0) onScopeDispose(dispose);
+	return registry;
+}
+//#endregion
+export { extractCollectionTextValue as n, normalizeCollectionTextValue as r, createCollectionRegistry as t };

package/dist/collection.d.mts

@@ -0,0 +1,2 @@
+import { a as CollectionActiveChangeReason, c as CollectionItemInput, d as CollectionNavigationOptions, f as CollectionRegistration, h as CollectionTextSearchOptions, i as CollectionActiveChange, l as CollectionKey, m as CollectionRegistryOptions, n as normalizeCollectionTextValue, o as CollectionDisabledBehavior, p as CollectionRegistry, r as createCollectionRegistry, s as CollectionItem, t as extractCollectionTextValue, u as CollectionNavigationDirection } from "./collection-B_dFZOHO.mjs";
+export { type CollectionActiveChange, type CollectionActiveChangeReason, type CollectionDisabledBehavior, type CollectionItem, type CollectionItemInput, type CollectionKey, type CollectionNavigationDirection, type CollectionNavigationOptions, type CollectionRegistration, type CollectionRegistry, type CollectionRegistryOptions, type CollectionTextSearchOptions, createCollectionRegistry, extractCollectionTextValue, normalizeCollectionTextValue };

package/dist/collection.mjs

@@ -0,0 +1,2 @@
+import { n as extractCollectionTextValue, r as normalizeCollectionTextValue, t as createCollectionRegistry } from "./collection-eHN150dT.mjs";
+export { createCollectionRegistry, extractCollectionTextValue, normalizeCollectionTextValue };

package/dist/composite-navigation-QINW9GLy.d.mts

@@ -0,0 +1,115 @@
+import { l as CollectionKey, p as CollectionRegistry, s as CollectionItem } from "./collection-B_dFZOHO.mjs";
+import { a as TypeaheadOptions, r as TypeaheadController } from "./typeahead-BbgUB2Bj.mjs";
+import { ComputedRef, MaybeRefOrGetter } from "vue";
+
+//#region src/composite-navigation-types.d.ts
+/** Physical axes recognized by composite arrow-key navigation. */
+type CompositeOrientation = "both" | "horizontal" | "vertical";
+/** Reading direction used to map horizontal arrows. */
+type CompositeDirection = "ltr" | "rtl";
+/** DOM focus-management strategy described by the WAI-ARIA APG. */
+type CompositeFocusStrategy = "active-descendant" | "roving";
+/** Logical movement requested from a composite controller. */
+type CompositeNavigationIntent = "first" | "focus" | "last" | "next" | "page-next" | "page-previous" | "pointer" | "previous" | "typeahead";
+/** Imperative and keyboard movement commands accepted by `navigate`. */
+type CompositeNavigationCommand = Exclude<CompositeNavigationIntent, "focus" | "pointer" | "typeahead">;
+/** Immutable snapshot published after logical active state changes. */
+interface CompositeNavigationChange<Key extends CollectionKey> {
+  /** Newly active item. */
+  readonly key: Key;
+  /** Active item before navigation. */
+  readonly previousKey: Key | null;
+  /** Navigation operation that selected this item. */
+  readonly intent: CompositeNavigationIntent;
+  /** Native event responsible for navigation, or `null` for imperative calls. */
+  readonly originalEvent: Event | null;
+  /** Focus-management strategy used while synchronizing the DOM. */
+  readonly focusStrategy: CompositeFocusStrategy;
+}
+/** Shared options for both composite focus-management strategies. */
+interface CompositeNavigationBaseOptions<Key extends CollectionKey, Value> {
+  /** Ordered, mutation-aware logical item registry. */
+  readonly registry: CollectionRegistry<Key, Value>;
+  /**
+   * Arrow-key axes recognized by this composite.
+   *
+   * @default "vertical"
+   */
+  readonly orientation?: MaybeRefOrGetter<CompositeOrientation | undefined>;
+  /**
+   * Reading direction used by horizontal arrows.
+   *
+   * @default "ltr"
+   */
+  readonly direction?: MaybeRefOrGetter<CompositeDirection | undefined>;
+  /** Wrap arrow navigation at collection boundaries. */
+  readonly loop?: MaybeRefOrGetter<boolean | undefined>;
+  /** Suppress keyboard and pointer navigation while retaining active state. */
+  readonly isDisabled?: MaybeRefOrGetter<boolean | undefined>;
+  /** Number of logical items traversed by PageUp and PageDown. */
+  readonly pageSize?: MaybeRefOrGetter<number | undefined>;
+  /** Optional buffered typeahead integrated into the same active state. */
+  readonly typeahead?: false | Omit<TypeaheadOptions<Key, Value>, "registry">;
+  /** Called after the active item and DOM focus representation are synchronized. */
+  readonly onNavigate?: (change: CompositeNavigationChange<Key>) => void;
+  /**
+   * Custom visibility policy for virtualized or scroll-managed collections.
+   * The default calls `scrollIntoView({block: "nearest", inline: "nearest"})`
+   * when the method exists and DOM focus did not already scroll the item.
+   */
+  readonly scrollIntoView?: (item: CollectionItem<Key, Value>, originalEvent: Event | null) => void;
+}
+/** Roving-tabindex options. */
+interface RovingNavigationOptions<Key extends CollectionKey, Value> extends CompositeNavigationBaseOptions<Key, Value> {
+  /** @default "roving" */
+  readonly focusStrategy?: "roving";
+  /** Avoid browser scrolling when DOM focus moves; custom scrolling still runs. */
+  readonly preventScroll?: MaybeRefOrGetter<boolean | undefined>;
+  /** Optional stable ID projection for item props. */
+  readonly getItemId?: (item: CollectionItem<Key, Value>) => string | undefined;
+}
+/** `aria-activedescendant` options with a required SSR-stable ID projection. */
+interface ActiveDescendantNavigationOptions<Key extends CollectionKey, Value> extends CompositeNavigationBaseOptions<Key, Value> {
+  readonly focusStrategy: "active-descendant";
+  /** Resolve the stable DOM ID referenced by `aria-activedescendant`. */
+  readonly getItemId: (item: CollectionItem<Key, Value>) => string;
+}
+/** Closed, strategy-discriminated composite configuration. */
+type CompositeNavigationOptions<Key extends CollectionKey, Value> = ActiveDescendantNavigationOptions<Key, Value> | RovingNavigationOptions<Key, Value>;
+/** Dynamic props for the composite container. */
+interface CompositeContainerProps {
+  readonly "aria-activedescendant"?: string;
+  readonly tabindex?: 0;
+  readonly onFocus: (event: FocusEvent) => void;
+  readonly onKeydown: (event: KeyboardEvent) => void;
+}
+/** Dynamic props for one registered composite item. */
+interface CompositeItemProps {
+  readonly id?: string;
+  readonly tabindex?: -1 | 0;
+  readonly onFocus: (event: FocusEvent) => void;
+  readonly onPointerdown: (event: PointerEvent) => void;
+}
+/** Focus and keyboard adapter layered over a collection registry. */
+interface CompositeNavigationController<Key extends CollectionKey> {
+  /** Registry-owned logical active key. */
+  readonly activeKey: ComputedRef<Key | null>;
+  /** Integrated typeahead controller, or `null` when typeahead is disabled. */
+  readonly typeahead: TypeaheadController<Key> | null;
+  /** Resolve current dynamic container attributes and stable handlers. */
+  readonly getContainerProps: () => Readonly<CompositeContainerProps>;
+  /** Resolve current dynamic item attributes and stable key-owned handlers. */
+  readonly getItemProps: (key: Key) => Readonly<CompositeItemProps>;
+  /** Move logical focus and synchronize the configured DOM representation. */
+  readonly navigate: (intent: CompositeNavigationCommand, originalEvent?: Event | null) => Key | null;
+  /** Release typeahead timers and cached handlers without disposing the registry. */
+  readonly dispose: () => void;
+}
+//#endregion
+//#region src/composite-navigation.d.ts
+/** Create an SSR-safe roving-tabindex or active-descendant collection adapter. */
+declare function createCompositeNavigation<Key extends CollectionKey, Value>(options: CompositeNavigationOptions<Key, Value>): CompositeNavigationController<Key>;
+/** Create a composite adapter disposed with the current Vue effect scope. */
+declare function useCompositeNavigation<Key extends CollectionKey, Value>(options: CompositeNavigationOptions<Key, Value>): CompositeNavigationController<Key>;
+//#endregion
+export { CompositeDirection as a, CompositeNavigationBaseOptions as c, CompositeNavigationController as d, CompositeNavigationIntent as f, RovingNavigationOptions as h, CompositeContainerProps as i, CompositeNavigationChange as l, CompositeOrientation as m, useCompositeNavigation as n, CompositeFocusStrategy as o, CompositeNavigationOptions as p, ActiveDescendantNavigationOptions as r, CompositeItemProps as s, createCompositeNavigation as t, CompositeNavigationCommand as u };