@vizejs/ui 0.347.7 → 0.350.2

package/dist/spatial-navigation-CHj9mDZH.d.mts

@@ -0,0 +1,106 @@
+import { l as CollectionKey, p as CollectionRegistry, s as CollectionItem } from "./collection-B_dFZOHO.mjs";
+import { MaybeRefOrGetter } from "vue";
+
+//#region src/spatial-navigation-types.d.ts
+/** Physical direction requested by spatial navigation. */
+type SpatialNavigationDirection = "down" | "left" | "right" | "up";
+/** Candidate ranking behavior aligned with CSS Spatial Navigation Level 1. */
+type SpatialNavigationAlgorithm = "grid" | "normal";
+/** Arrow-key behavior when no candidate exists in the requested direction. */
+type SpatialNavigationBoundaryBehavior = "contain" | "exit";
+/** DOM focus policy after logical state changes. */
+type SpatialNavigationFocusBehavior = "focus" | "logical";
+/** Serializable, axis-aligned CSS pixel rectangle. */
+interface SpatialNavigationRect {
+  readonly bottom: number;
+  readonly height: number;
+  readonly left: number;
+  readonly right: number;
+  readonly top: number;
+  readonly width: number;
+}
+/** Immutable successful navigation snapshot. */
+interface SpatialNavigationChange<Key extends CollectionKey> {
+  readonly direction: SpatialNavigationDirection;
+  readonly key: Key;
+  readonly previousKey: Key | null;
+  readonly originalEvent: Event | null;
+  readonly algorithm: SpatialNavigationAlgorithm;
+  readonly score: number;
+}
+/** Immutable boundary snapshot emitted when no directional candidate exists. */
+interface SpatialNavigationBoundary<Key extends CollectionKey> {
+  readonly direction: SpatialNavigationDirection;
+  readonly key: Key | null;
+  readonly originalEvent: Event | null;
+}
+/** Spatial navigation configuration for one caller-owned collection. */
+interface SpatialNavigationOptions<Key extends CollectionKey, Value> {
+  /** Ordered logical items and active-key ownership. */
+  readonly registry: CollectionRegistry<Key, Value>;
+  /**
+   * Candidate scoring algorithm.
+   *
+   * @default "normal"
+   */
+  readonly algorithm?: MaybeRefOrGetter<SpatialNavigationAlgorithm | undefined>;
+  /**
+   * Whether a boundary arrow remains owned by the composite or exits to native behavior.
+   *
+   * @default "contain"
+   */
+  readonly boundaryBehavior?: MaybeRefOrGetter<SpatialNavigationBoundaryBehavior | undefined>;
+  /** Suppress keyboard and imperative navigation without discarding active state. */
+  readonly isDisabled?: MaybeRefOrGetter<boolean | undefined>;
+  /**
+   * Wrap to the opposite spatial edge when no forward candidate exists.
+   *
+   * @default false
+   */
+  readonly loop?: MaybeRefOrGetter<boolean | undefined>;
+  /**
+   * Whether successful navigation moves DOM focus or only logical active state.
+   *
+   * @default "focus"
+   */
+  readonly focusBehavior?: MaybeRefOrGetter<SpatialNavigationFocusBehavior | undefined>;
+  /**
+   * Avoid browser scrolling while moving DOM focus. Reveal behavior still runs.
+   *
+   * @default false
+   */
+  readonly preventScroll?: MaybeRefOrGetter<boolean | undefined>;
+  /**
+   * Resolve transformed viewport geometry for DOM or virtual items.
+   * The default reads `element.getBoundingClientRect()` and skips unmounted candidates.
+   */
+  readonly getRect?: (item: CollectionItem<Key, Value>) => SpatialNavigationRect | DOMRectReadOnly | null | undefined;
+  /** Custom visibility policy for virtualized or scroll-managed collections. */
+  readonly scrollIntoView?: (item: CollectionItem<Key, Value>, originalEvent: Event | null) => void;
+  /** Called after logical state, DOM focus, and reveal behavior commit. */
+  readonly onNavigate?: (change: SpatialNavigationChange<Key>) => void;
+  /** Called when a valid origin has no candidate in the requested direction. */
+  readonly onBoundary?: (boundary: SpatialNavigationBoundary<Key>) => void;
+}
+/** Stable event adapter for a spatial navigation container. */
+interface SpatialNavigationProps {
+  readonly onKeydown: (event: KeyboardEvent) => void;
+}
+/** Geometry-driven navigation controller. */
+interface SpatialNavigationController<Key extends CollectionKey> {
+  readonly spatialNavigationProps: Readonly<SpatialNavigationProps>;
+  /** Resolve the best candidate without mutating logical or DOM state. */
+  readonly findTarget: (direction: SpatialNavigationDirection, fromKey?: Key) => Key | null;
+  /** Navigate, returning the committed key or `null` at a boundary. */
+  readonly navigate: (direction: SpatialNavigationDirection, originalEvent?: Event | null) => Key | null;
+  /** Release scope ownership. The caller-owned registry is not disposed. */
+  readonly dispose: () => void;
+}
+//#endregion
+//#region src/spatial-navigation.d.ts
+/** Create a geometry-driven, SSR-safe arrow navigation controller. */
+declare function createSpatialNavigation<Key extends CollectionKey, Value>(options: SpatialNavigationOptions<Key, Value>): SpatialNavigationController<Key>;
+/** Create a spatial controller disposed with the current Vue effect scope. */
+declare function useSpatialNavigation<Key extends CollectionKey, Value>(options: SpatialNavigationOptions<Key, Value>): SpatialNavigationController<Key>;
+//#endregion
+export { SpatialNavigationBoundaryBehavior as a, SpatialNavigationDirection as c, SpatialNavigationProps as d, SpatialNavigationRect as f, SpatialNavigationBoundary as i, SpatialNavigationFocusBehavior as l, useSpatialNavigation as n, SpatialNavigationChange as o, SpatialNavigationAlgorithm as r, SpatialNavigationController as s, createSpatialNavigation as t, SpatialNavigationOptions as u };

package/dist/spatial-navigation-D6-UDavU.mjs

@@ -0,0 +1,301 @@
+import { getCurrentScope, onScopeDispose, toValue } from "vue";
+//#region src/spatial-navigation-internal.ts
+const optionDiagnostic = "VIZE_UI_SPATIAL_NAVIGATION_OPTION";
+const rectDiagnostic = "VIZE_UI_SPATIAL_NAVIGATION_RECT";
+function capture(errors, callback) {
+	try {
+		callback();
+	} catch (error) {
+		errors.push(error);
+	}
+}
+function surfaceErrors(errors, message) {
+	if (errors.length === 1) throw errors[0];
+	if (errors.length < 2) return;
+	const Aggregate = globalThis.AggregateError;
+	if (typeof Aggregate === "function") throw new Aggregate(errors, message);
+	const fallback = Object.assign(new Error(message), { errors: [...errors] });
+	fallback.name = "AggregateError";
+	throw fallback;
+}
+function readBoolean(source, name) {
+	const value = toValue(source);
+	if (value === void 0) return false;
+	if (typeof value !== "boolean") throw new TypeError(`${optionDiagnostic}: ${name} must resolve to a boolean`);
+	return value;
+}
+function readEnum(source, fallback, values, name) {
+	const value = toValue(source) ?? fallback;
+	if (!values.includes(value)) throw new TypeError(`${optionDiagnostic}: ${name} must resolve to ${values.join(" or ")}`);
+	return value;
+}
+const readAlgorithm = (source) => readEnum(source, "normal", ["normal", "grid"], "algorithm");
+const readBoundary = (source) => readEnum(source, "contain", ["contain", "exit"], "boundaryBehavior");
+const readFocus = (source) => readEnum(source, "focus", ["focus", "logical"], "focusBehavior");
+function readDirection(value) {
+	if (value !== "down" && value !== "left" && value !== "right" && value !== "up") throw new TypeError(`${optionDiagnostic}: direction is invalid`);
+	return value;
+}
+function validateOptions(options) {
+	if (!options || typeof options !== "object" || Array.isArray(options)) throw new TypeError(`${optionDiagnostic}: options must be an object`);
+	const registry = options.registry;
+	if (!registry || typeof registry.getItem !== "function" || !registry.navigableItems) throw new TypeError(`${optionDiagnostic}: registry must be a CollectionRegistry`);
+	for (const name of [
+		"getRect",
+		"scrollIntoView",
+		"onNavigate",
+		"onBoundary"
+	]) {
+		const callback = options[name];
+		if (callback !== void 0 && typeof callback !== "function") throw new TypeError(`${optionDiagnostic}: ${name} must be a function`);
+	}
+	readAlgorithm(options.algorithm);
+	readBoundary(options.boundaryBehavior);
+	readFocus(options.focusBehavior);
+	readBoolean(options.isDisabled, "isDisabled");
+	readBoolean(options.loop, "loop");
+	readBoolean(options.preventScroll, "preventScroll");
+}
+function normalizeRect(value) {
+	if (!value || typeof value !== "object") throw new TypeError(`${rectDiagnostic}: geometry must be a rectangle object`);
+	const input = value;
+	if ([
+		input.bottom,
+		input.height,
+		input.left,
+		input.right,
+		input.top,
+		input.width
+	].some((number) => typeof number !== "number" || !Number.isFinite(number))) throw new TypeError(`${rectDiagnostic}: rectangle coordinates must be finite numbers`);
+	if (input.width < 0 || input.height < 0 || input.right < input.left || input.bottom < input.top) throw new TypeError(`${rectDiagnostic}: rectangle dimensions must be non-negative and ordered`);
+	return Object.freeze({
+		bottom: input.bottom,
+		height: input.height,
+		left: input.left,
+		right: input.right,
+		top: input.top,
+		width: input.width
+	});
+}
+function intervalGap(startA, endA, startB, endB) {
+	return Math.max(0, startA - endB, startB - endA);
+}
+function intervalOverlap(startA, endA, startB, endB) {
+	return Math.max(0, Math.min(endA, endB) - Math.max(startA, startB));
+}
+function directionalGap(origin, candidate, direction) {
+	if (direction === "down") return candidate.top >= origin.bottom ? candidate.top - origin.bottom : null;
+	if (direction === "up") return candidate.bottom <= origin.top ? origin.top - candidate.bottom : null;
+	if (direction === "right") return candidate.left >= origin.right ? candidate.left - origin.right : null;
+	return candidate.right <= origin.left ? origin.left - candidate.right : null;
+}
+function rankItem(item, rect, index, origin, direction) {
+	const primary = directionalGap(origin, rect, direction);
+	if (primary === null) return null;
+	const horizontal = direction === "left" || direction === "right";
+	const orthogonal = horizontal ? intervalGap(origin.top, origin.bottom, rect.top, rect.bottom) : intervalGap(origin.left, origin.right, rect.left, rect.right);
+	const overlap = horizontal ? intervalOverlap(origin.top, origin.bottom, rect.top, rect.bottom) : intervalOverlap(origin.left, origin.right, rect.left, rect.right);
+	const orthogonalSize = horizontal ? origin.height : origin.width;
+	const orthogonalBias = orthogonalSize / 2;
+	const orthogonalWeight = horizontal ? 30 : 2;
+	const alignment = orthogonalSize > 0 ? overlap / orthogonalSize * 5 : 0;
+	return {
+		item,
+		rect,
+		index,
+		primary,
+		orthogonal,
+		overlap,
+		score: Math.hypot(primary, orthogonal) + (orthogonal + orthogonalBias) * orthogonalWeight - alignment
+	};
+}
+function selectCandidate(candidates, algorithm) {
+	let ranked = [...candidates];
+	if (algorithm === "grid" && ranked.some(({ overlap }) => overlap > 0)) ranked = ranked.filter(({ overlap }) => overlap > 0);
+	ranked.sort((left, right) => algorithm === "normal" ? left.score - right.score || left.index - right.index : left.primary - right.primary || right.overlap - left.overlap || left.orthogonal - right.orthogonal || left.index - right.index);
+	return ranked[0];
+}
+function selectWrappedCandidate(items, origin, direction) {
+	const horizontal = direction === "left" || direction === "right";
+	const candidates = items.map(({ item, rect, index }) => {
+		const orthogonal = horizontal ? intervalGap(origin.top, origin.bottom, rect.top, rect.bottom) : intervalGap(origin.left, origin.right, rect.left, rect.right);
+		const overlap = horizontal ? intervalOverlap(origin.top, origin.bottom, rect.top, rect.bottom) : intervalOverlap(origin.left, origin.right, rect.left, rect.right);
+		const primary = direction === "right" ? rect.left : direction === "left" ? -rect.right : direction === "down" ? rect.top : -rect.bottom;
+		return {
+			item,
+			rect,
+			index,
+			primary,
+			orthogonal,
+			overlap,
+			score: primary + orthogonal
+		};
+	});
+	const aligned = candidates.some(({ overlap }) => overlap > 0) ? candidates.filter(({ overlap }) => overlap > 0) : candidates;
+	aligned.sort((left, right) => left.primary - right.primary || left.orthogonal - right.orthogonal || right.overlap - left.overlap || left.index - right.index);
+	return aligned[0];
+}
+function keyDirection(event) {
+	if (event.isComposing || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return null;
+	if (event.key === "ArrowDown") return "down";
+	if (event.key === "ArrowLeft") return "left";
+	if (event.key === "ArrowRight") return "right";
+	if (event.key === "ArrowUp") return "up";
+	return null;
+}
+function isEditableDescendant(event) {
+	const path = typeof event.composedPath === "function" ? event.composedPath() : [event.target];
+	for (const candidate of path) {
+		if (candidate === event.currentTarget) break;
+		const target = candidate;
+		if (target?.localName === "input" || target?.localName === "select" || target?.localName === "textarea" || target?.isContentEditable === true) return true;
+	}
+	return false;
+}
+//#endregion
+//#region src/spatial-navigation.ts
+const disposedDiagnostic = "VIZE_UI_SPATIAL_NAVIGATION_DISPOSED";
+const originDiagnostic = "VIZE_UI_SPATIAL_NAVIGATION_ORIGIN";
+const setupDiagnostic = "VIZE_UI_SPATIAL_NAVIGATION_SETUP";
+/** Create a geometry-driven, SSR-safe arrow navigation controller. */
+function createSpatialNavigation(options) {
+	validateOptions(options);
+	const registry = options.registry;
+	let disposed = false;
+	const assertActive = () => {
+		if (disposed) throw new Error(`${disposedDiagnostic}: the controller has been disposed`);
+	};
+	const rectFor = (item) => {
+		const supplied = options.getRect?.(item);
+		if (supplied !== void 0 && supplied !== null) return normalizeRect(supplied);
+		if (options.getRect) return null;
+		const read = item.element?.getBoundingClientRect;
+		return typeof read === "function" ? normalizeRect(read.call(item.element)) : null;
+	};
+	const originItem = (fromKey) => {
+		const items = registry.navigableItems.value;
+		if (items.length === 0) return null;
+		const key = fromKey ?? registry.activeKey.value ?? items[0]?.key;
+		const item = items.find((candidate) => candidate.key === key);
+		if (!item) throw new Error(`${originDiagnostic}: ${String(key)} is not a navigable collection item`);
+		return item;
+	};
+	const resolve = (directionInput, fromKey) => {
+		assertActive();
+		const direction = readDirection(directionInput);
+		if (readBoolean(options.isDisabled, "isDisabled")) return null;
+		const origin = originItem(fromKey);
+		if (!origin) return null;
+		const originRect = rectFor(origin);
+		if (!originRect) throw new Error(`${originDiagnostic}: ${String(origin.key)} has no measurable rectangle`);
+		const measured = [];
+		const candidates = [];
+		for (const [index, item] of registry.navigableItems.value.entries()) {
+			if (item.key === origin.key) continue;
+			const rect = rectFor(item);
+			if (!rect) continue;
+			measured.push({
+				item,
+				rect,
+				index
+			});
+			const candidate = rankItem(item, rect, index, originRect, direction);
+			if (candidate) candidates.push(candidate);
+		}
+		const algorithm = readAlgorithm(options.algorithm);
+		let target = selectCandidate(candidates, algorithm) ?? null;
+		if (!target && readBoolean(options.loop, "loop")) target = selectWrappedCandidate(measured, originRect, direction) ?? null;
+		return {
+			algorithm,
+			originKey: origin.key,
+			target
+		};
+	};
+	const synchronizeDom = (item, originalEvent, errors) => {
+		const focusBehavior = readFocus(options.focusBehavior);
+		const preventScroll = readBoolean(options.preventScroll, "preventScroll");
+		if (focusBehavior === "focus") {
+			const focus = item.element?.focus;
+			if (typeof focus !== "function") errors.push(/* @__PURE__ */ new Error("VIZE_UI_SPATIAL_NAVIGATION_FOCUS: target item is not focusable"));
+			else capture(errors, () => {
+				try {
+					focus.call(item.element, { preventScroll });
+				} catch {
+					focus.call(item.element);
+				}
+			});
+		}
+		if (!(options.scrollIntoView || focusBehavior === "logical" || preventScroll)) return;
+		if (options.scrollIntoView) {
+			capture(errors, () => options.scrollIntoView?.(item, originalEvent));
+			return;
+		}
+		const reveal = item.element?.scrollIntoView;
+		if (typeof reveal === "function") capture(errors, () => reveal.call(item.element, {
+			block: "nearest",
+			inline: "nearest"
+		}));
+	};
+	const transition = (direction, resolution, originalEvent) => {
+		const errors = [];
+		if (!resolution) return null;
+		if (!resolution.target) {
+			const boundary = Object.freeze({
+				direction,
+				key: resolution.originKey,
+				originalEvent
+			});
+			capture(errors, () => options.onBoundary?.(boundary));
+			surfaceErrors(errors, "Spatial navigation boundary callback failed");
+			return null;
+		}
+		const { item, score } = resolution.target;
+		const previousKey = registry.activeKey.value;
+		capture(errors, () => {
+			registry.setActiveKey(item.key);
+		});
+		if (registry.activeKey.value === item.key && item.key !== previousKey) {
+			capture(errors, () => synchronizeDom(item, originalEvent, errors));
+			const change = Object.freeze({
+				algorithm: resolution.algorithm,
+				direction,
+				key: item.key,
+				previousKey,
+				originalEvent,
+				score
+			});
+			capture(errors, () => options.onNavigate?.(change));
+		}
+		surfaceErrors(errors, "Spatial navigation transition failed");
+		return registry.activeKey.value;
+	};
+	const navigate = (directionInput, originalEvent = null) => {
+		const direction = readDirection(directionInput);
+		return transition(direction, resolve(direction), originalEvent);
+	};
+	const spatialNavigationProps = Object.freeze({ onKeydown(event) {
+		if (event.defaultPrevented || isEditableDescendant(event)) return;
+		const direction = keyDirection(event);
+		if (!direction || readBoolean(options.isDisabled, "isDisabled")) return;
+		const resolution = resolve(direction);
+		if (resolution && (resolution.target || readBoundary(options.boundaryBehavior) === "contain")) event.preventDefault();
+		transition(direction, resolution, event);
+	} });
+	return Object.freeze({
+		spatialNavigationProps,
+		findTarget: (direction, fromKey) => resolve(direction, fromKey)?.target?.item.key ?? null,
+		navigate,
+		dispose: () => {
+			disposed = true;
+		}
+	});
+}
+/** Create a spatial controller disposed with the current Vue effect scope. */
+function useSpatialNavigation(options) {
+	if (!getCurrentScope()) throw new Error(`${setupDiagnostic}: use inside component setup or an active effect scope`);
+	const controller = createSpatialNavigation(options);
+	onScopeDispose(controller.dispose);
+	return controller;
+}
+//#endregion
+export { useSpatialNavigation as n, createSpatialNavigation as t };

package/dist/spatial-navigation.d.mts

@@ -0,0 +1,2 @@
+import { a as SpatialNavigationBoundaryBehavior, c as SpatialNavigationDirection, d as SpatialNavigationProps, f as SpatialNavigationRect, i as SpatialNavigationBoundary, l as SpatialNavigationFocusBehavior, n as useSpatialNavigation, o as SpatialNavigationChange, r as SpatialNavigationAlgorithm, s as SpatialNavigationController, t as createSpatialNavigation, u as SpatialNavigationOptions } from "./spatial-navigation-CHj9mDZH.mjs";
+export { type SpatialNavigationAlgorithm, type SpatialNavigationBoundary, type SpatialNavigationBoundaryBehavior, type SpatialNavigationChange, type SpatialNavigationController, type SpatialNavigationDirection, type SpatialNavigationFocusBehavior, type SpatialNavigationOptions, type SpatialNavigationProps, type SpatialNavigationRect, createSpatialNavigation, useSpatialNavigation };

package/dist/spatial-navigation.mjs

@@ -0,0 +1,2 @@
+import { n as useSpatialNavigation, t as createSpatialNavigation } from "./spatial-navigation-D6-UDavU.mjs";
+export { createSpatialNavigation, useSpatialNavigation };

package/dist/typeahead-B7KDxE_u.mjs

@@ -0,0 +1,175 @@
+import { getCurrentScope, isRef, onScopeDispose, shallowReadonly, shallowRef, toValue, watch } from "vue";
+//#region src/typeahead-internal.ts
+const optionDiagnostic = "VIZE_UI_TYPEAHEAD_OPTION";
+const inputDiagnostic = "VIZE_UI_TYPEAHEAD_INPUT";
+const graphemeSegmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
+function splitGraphemes(value) {
+	return [...graphemeSegmenter.segment(value)].map(({ segment }) => segment);
+}
+function readBoolean(source, name) {
+	const value = toValue(source);
+	if (value === void 0) return false;
+	if (typeof value !== "boolean") throw new TypeError(`${optionDiagnostic}: ${name} must resolve to a boolean`);
+	return value;
+}
+function readTimeout(source) {
+	const value = toValue(source) ?? 500;
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new TypeError(`${optionDiagnostic}: timeout must resolve to a finite number >= 0`);
+	return value;
+}
+function readGrapheme(value) {
+	if (typeof value !== "string" || value.length === 0) throw new TypeError(`${inputDiagnostic}: input must be exactly one Unicode grapheme`);
+	const segments = splitGraphemes(value);
+	if (segments.length !== 1 || segments[0] !== value) throw new TypeError(`${inputDiagnostic}: input must be exactly one Unicode grapheme`);
+	return value;
+}
+function isCharacterKey(event) {
+	if (event.isComposing || event.key === "Dead" || event.key === "Process") return false;
+	const altGraph = event.getModifierState?.("AltGraph") === true;
+	if (event.metaKey || event.ctrlKey && !altGraph || event.altKey && !altGraph) return false;
+	try {
+		readGrapheme(event.key);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function validateOptions(options) {
+	const registry = options.registry;
+	if (!registry || typeof registry.moveActiveByTextValue !== "function" || !registry.activeKey) throw new TypeError(`${optionDiagnostic}: registry must be a CollectionRegistry`);
+	if (options.allowSpace !== void 0 && typeof options.allowSpace !== "boolean") throw new TypeError(`${optionDiagnostic}: allowSpace must be a boolean`);
+	if (options.onMatch !== void 0 && typeof options.onMatch !== "function") throw new TypeError(`${optionDiagnostic}: onMatch must be a function`);
+	if (options.collator !== void 0 && typeof options.collator.compare !== "function") throw new TypeError(`${optionDiagnostic}: collator must be an Intl.Collator`);
+	readTimeout(options.timeout);
+	readBoolean(options.isDisabled, "isDisabled");
+}
+//#endregion
+//#region src/typeahead.ts
+const disposedDiagnostic = "VIZE_UI_TYPEAHEAD_DISPOSED";
+const setupDiagnostic = "VIZE_UI_TYPEAHEAD_SETUP";
+/** Create an SSR-safe, locale-aware typeahead buffer for one collection. */
+function createTypeahead(options) {
+	validateOptions(options);
+	const query = shallowRef("");
+	const collator = options.collator ?? new Intl.Collator(void 0, {
+		sensitivity: "base",
+		usage: "search"
+	});
+	let timer = null;
+	let disposed = false;
+	const clearTimer = () => {
+		if (timer !== null) clearTimeout(timer);
+		timer = null;
+	};
+	const reset = () => {
+		clearTimer();
+		if (query.value.length === 0) return false;
+		query.value = "";
+		return true;
+	};
+	const assertActive = () => {
+		if (disposed) throw new Error(`${disposedDiagnostic}: the controller has been disposed`);
+	};
+	const scheduleReset = (timeout) => {
+		clearTimer();
+		timer = setTimeout(() => {
+			query.value = "";
+			timer = null;
+		}, timeout);
+	};
+	const input = (value, originalEvent = null) => {
+		assertActive();
+		const grapheme = readGrapheme(value);
+		let timeout;
+		try {
+			if (readBoolean(options.isDisabled, "isDisabled")) {
+				reset();
+				return null;
+			}
+			timeout = readTimeout(options.timeout);
+		} catch (error) {
+			reset();
+			throw error;
+		}
+		const previousGraphemes = splitGraphemes(query.value);
+		const nextQuery = previousGraphemes.length > 0 && previousGraphemes.every((part) => collator.compare(part, grapheme) === 0) ? grapheme : `${query.value}${grapheme}`;
+		query.value = nextQuery;
+		scheduleReset(timeout);
+		const previousKey = options.registry.activeKey.value;
+		let key;
+		try {
+			key = options.registry.moveActiveByTextValue(nextQuery, { collator });
+		} catch (error) {
+			reset();
+			throw error;
+		}
+		if (key !== null && key !== previousKey) {
+			const match = Object.freeze({
+				key,
+				previousKey,
+				query: nextQuery,
+				originalEvent
+			});
+			options.onMatch?.(match);
+		}
+		return key;
+	};
+	const typeaheadProps = Object.freeze({ onKeydown(event) {
+		if (!isCharacterKey(event)) return;
+		if (event.key === " " && query.value.length === 0 && options.allowSpace !== true) return;
+		event.preventDefault();
+		input(event.key, event);
+	} });
+	const stopWatches = [];
+	const disabledSource = options.isDisabled;
+	if (isRef(disabledSource) || typeof disabledSource === "function") stopWatches.push(watch(() => {
+		try {
+			return isRef(disabledSource) ? disabledSource.value : disabledSource();
+		} catch (error) {
+			reset();
+			throw error;
+		}
+	}, () => {
+		try {
+			if (readBoolean(options.isDisabled, "isDisabled")) reset();
+		} catch (error) {
+			reset();
+			throw error;
+		}
+	}, { flush: "sync" }));
+	const timeoutSource = options.timeout;
+	if (isRef(timeoutSource) || typeof timeoutSource === "function") stopWatches.push(watch(() => {
+		try {
+			return readTimeout(timeoutSource);
+		} catch (error) {
+			reset();
+			throw error;
+		}
+	}, (timeout) => {
+		if (query.value.length > 0) scheduleReset(timeout);
+	}, { flush: "sync" }));
+	return Object.freeze({
+		query: shallowReadonly(query),
+		typeaheadProps,
+		input,
+		reset: () => {
+			assertActive();
+			return reset();
+		},
+		dispose: () => {
+			if (disposed) return;
+			disposed = true;
+			for (const stop of stopWatches) stop();
+			reset();
+		}
+	});
+}
+/** Create a typeahead controller disposed with the current Vue effect scope. */
+function useTypeahead(options) {
+	if (!getCurrentScope()) throw new Error(`${setupDiagnostic}: use inside component setup or an active effect scope`);
+	const controller = createTypeahead(options);
+	onScopeDispose(controller.dispose);
+	return controller;
+}
+//#endregion
+export { useTypeahead as n, createTypeahead as t };

package/dist/typeahead-BbgUB2Bj.d.mts

@@ -0,0 +1,71 @@
+import { l as CollectionKey, p as CollectionRegistry } from "./collection-B_dFZOHO.mjs";
+import { MaybeRefOrGetter, ShallowRef } from "vue";
+
+//#region src/typeahead-types.d.ts
+/** Immutable snapshot emitted when buffered text matches a collection item. */
+interface TypeaheadMatch<Key extends CollectionKey> {
+  /** Item selected by the locale-aware collection search. */
+  readonly key: Key;
+  /** Active item before the match. */
+  readonly previousKey: Key | null;
+  /** Normalized buffered query used for this search. */
+  readonly query: string;
+  /** Native key event responsible for the match, or `null` for manual input. */
+  readonly originalEvent: KeyboardEvent | null;
+}
+/** Options for {@link createTypeahead}. */
+interface TypeaheadOptions<Key extends CollectionKey, Value> {
+  /** Mutation-aware collection that owns active state and locale matching. */
+  readonly registry: CollectionRegistry<Key, Value>;
+  /**
+   * Idle time before a new grapheme starts a fresh query.
+   *
+   * @default 500
+   */
+  readonly timeout?: MaybeRefOrGetter<number | undefined>;
+  /**
+   * Ignore input and synchronously clear a pending query while true.
+   *
+   * @default false
+   */
+  readonly isDisabled?: MaybeRefOrGetter<boolean | undefined>;
+  /**
+   * Treat Space as the first grapheme of a query. A space is always accepted
+   * after another character so multi-word labels remain searchable.
+   *
+   * @default false
+   */
+  readonly allowSpace?: boolean;
+  /** Comparator used to detect repeated graphemes before cycling matches. */
+  readonly collator?: Intl.Collator;
+  /** Called after active collection state moves to a text match. */
+  readonly onMatch?: (match: TypeaheadMatch<Key>) => void;
+}
+/** Stable keyboard handler to merge onto a composite focus owner. */
+interface TypeaheadProps {
+  readonly onKeydown: (event: KeyboardEvent) => void;
+}
+/** Buffered, locale-aware collection typeahead controller. */
+interface TypeaheadController<Key extends CollectionKey> {
+  /** Current query, cleared after the configured timeout. */
+  readonly query: Readonly<ShallowRef<string>>;
+  /** Stable keyboard handler for declarative consumers. */
+  readonly typeaheadProps: Readonly<TypeaheadProps>;
+  /**
+   * Consume exactly one Unicode grapheme and return the matching item.
+   * Repeating one grapheme cycles through matching items.
+   */
+  readonly input: (grapheme: string, originalEvent?: KeyboardEvent | null) => Key | null;
+  /** Clear buffered input and report whether any text was pending. */
+  readonly reset: () => boolean;
+  /** Clear timers and make imperative operations terminal. Safe to repeat. */
+  readonly dispose: () => void;
+}
+//#endregion
+//#region src/typeahead.d.ts
+/** Create an SSR-safe, locale-aware typeahead buffer for one collection. */
+declare function createTypeahead<Key extends CollectionKey, Value>(options: TypeaheadOptions<Key, Value>): TypeaheadController<Key>;
+/** Create a typeahead controller disposed with the current Vue effect scope. */
+declare function useTypeahead<Key extends CollectionKey, Value>(options: TypeaheadOptions<Key, Value>): TypeaheadController<Key>;
+//#endregion
+export { TypeaheadOptions as a, TypeaheadMatch as i, useTypeahead as n, TypeaheadProps as o, TypeaheadController as r, createTypeahead as t };

package/dist/typeahead.d.mts

@@ -0,0 +1,2 @@
+import { a as TypeaheadOptions, i as TypeaheadMatch, n as useTypeahead, o as TypeaheadProps, r as TypeaheadController, t as createTypeahead } from "./typeahead-BbgUB2Bj.mjs";
+export { type TypeaheadController, type TypeaheadMatch, type TypeaheadOptions, type TypeaheadProps, createTypeahead, useTypeahead };

package/dist/typeahead.mjs

@@ -0,0 +1,2 @@
+import { n as useTypeahead, t as createTypeahead } from "./typeahead-B7KDxE_u.mjs";
+export { createTypeahead, useTypeahead };