@vizejs/composable 0.426.3 → 0.428.0

package/dist/infinite-scroll.d.mts

@@ -0,0 +1,56 @@
+import { ScrollTargetValue, UseScrollOptions } from "./scroll.mjs";
+import { MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/infinite-scroll.d.ts
+/** Edge that triggers loading in {@link useInfiniteScroll}. */
+type InfiniteScrollDirection = "top" | "bottom" | "left" | "right";
+/** Options for {@link useInfiniteScroll}. */
+interface UseInfiniteScrollOptions extends Omit<UseScrollOptions, "offset"> {
+  /**
+   * Distance in CSS pixels from the edge that triggers loading.
+   *
+   * @default 0
+   */
+  readonly distance?: number;
+  /**
+   * Edge that triggers loading.
+   *
+   * @default "bottom"
+   */
+  readonly direction?: InfiniteScrollDirection;
+  /**
+   * Return `false` to stop loading (for example once every page is loaded).
+   *
+   * @default () => true
+   */
+  readonly canLoadMore?: MaybeRefOrGetter<boolean>;
+}
+/** Reactive state returned by {@link useInfiniteScroll}. */
+interface InfiniteScrollControls {
+  /** Whether `onLoadMore` is running. */
+  readonly isLoading: Readonly<Ref<boolean>>;
+  /**
+   * Re-check the edge and load when it is still within `distance` (call after
+   * the list was replaced).
+   */
+  readonly reset: () => void;
+}
+/**
+ * Load more content when a scroll container reaches an edge.
+ *
+ * Built on `useScroll`: when the configured edge is within `distance`,
+ * `onLoadMore` runs; concurrent calls are prevented, and after each load the
+ * edge is re-measured so short pages keep loading until the container
+ * overflows or `canLoadMore` returns `false`. Loader errors propagate to the
+ * returned promise of the internal run but never leave `isLoading` stuck.
+ * No loading happens during server rendering.
+ *
+ * @param target Reactive scroll container (element, component, or window).
+ * @param onLoadMore Loader invoked at the edge.
+ * @param options Edge, distance, gating, and {@link useScroll} options.
+ * @default options {}
+ * @returns Loading flag and a manual re-check.
+ */
+declare function useInfiniteScroll(target: MaybeRefOrGetter<ScrollTargetValue>, onLoadMore: () => unknown, options?: UseInfiniteScrollOptions): InfiniteScrollControls;
+//#endregion
+export { InfiniteScrollControls, InfiniteScrollDirection, UseInfiniteScrollOptions, useInfiniteScroll };

package/dist/infinite-scroll.mjs

@@ -0,0 +1,72 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { useScroll } from "./scroll.mjs";
+import { nextTick, readonly, ref, toValue, watch } from "vue";
+//#region src/infinite-scroll.ts
+/**
+* Load more content when a scroll container reaches an edge.
+*
+* Built on `useScroll`: when the configured edge is within `distance`,
+* `onLoadMore` runs; concurrent calls are prevented, and after each load the
+* edge is re-measured so short pages keep loading until the container
+* overflows or `canLoadMore` returns `false`. Loader errors propagate to the
+* returned promise of the internal run but never leave `isLoading` stuck.
+* No loading happens during server rendering.
+*
+* @param target Reactive scroll container (element, component, or window).
+* @param onLoadMore Loader invoked at the edge.
+* @param options Edge, distance, gating, and {@link useScroll} options.
+* @default options {}
+* @returns Loading flag and a manual re-check.
+*/
+function useInfiniteScroll(target, onLoadMore, options = {}) {
+	const { distance = 0, direction = "bottom", canLoadMore = true, ...scrollOptions } = options;
+	const isLoading = ref(false);
+	const scroll = useScroll(target, {
+		...scrollOptions,
+		offset: { [direction]: distance }
+	});
+	let disposed = false;
+	const check = async () => {
+		if (disposed || isLoading.value || !toValue(canLoadMore)) return;
+		if (!scroll.arrivedState[direction] || !hasContainer(target)) return;
+		isLoading.value = true;
+		const before = contentSize(target);
+		try {
+			await onLoadMore();
+		} finally {
+			isLoading.value = false;
+		}
+		await nextTick();
+		if (disposed) return;
+		scroll.measure();
+		const after = contentSize(target);
+		if (after === void 0 || after !== before) check();
+	};
+	const stop = watch(() => [scroll.arrivedState[direction], toValue(canLoadMore)], () => void check(), { immediate: true });
+	tryOnScopeDispose(() => {
+		disposed = true;
+		stop.stop();
+	});
+	return {
+		isLoading: readonly(isLoading),
+		reset: () => {
+			scroll.measure();
+			check();
+		}
+	};
+}
+function hasContainer(target) {
+	const value = toValue(target);
+	return value !== null && value !== void 0;
+}
+function contentSize(target) {
+	const value = toValue(target);
+	if (typeof value !== "object" || value === null) return void 0;
+	const element = "scrollHeight" in value ? value : "documentElement" in value ? value.documentElement : "document" in value && typeof value.document === "object" && value.document !== null ? Reflect.get(value.document, "documentElement") : "$el" in value ? value.$el : void 0;
+	if (typeof element !== "object" || element === null) return void 0;
+	const height = Reflect.get(element, "scrollHeight");
+	const width = Reflect.get(element, "scrollWidth");
+	return typeof height === "number" && typeof width === "number" ? `${String(height)}x${String(width)}` : void 0;
+}
+//#endregion
+export { useInfiniteScroll };

package/dist/intersection-observer.d.mts

@@ -0,0 +1,122 @@
+import { n as MaybeElementTarget, r as MaybeElementTargets } from "./element-target-Crpxl4D9.mjs";
+import { ComponentPublicInstance, MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/intersection-observer.d.ts
+/** Runtime capability that supplies the `IntersectionObserver` constructor. */
+interface IntersectionObserverHost {
+  /** `IntersectionObserver` constructor, absent in unsupported runtimes. */
+  readonly IntersectionObserver?: new (callback: IntersectionObserverCallback, options?: IntersectionObserverInit) => IntersectionObserver;
+}
+/**
+ * Intersection root: an element target, a document, or `null`/`undefined`
+ * for the top-level viewport.
+ */
+type IntersectionRoot = MaybeRefOrGetter<Element | Document | ComponentPublicInstance | null | undefined>;
+/** Options for {@link useIntersectionObserver}. */
+interface UseIntersectionObserverOptions {
+  /**
+   * Ancestor (or document) whose box is used as the viewport.
+   *
+   * @default undefined (the top-level viewport)
+   */
+  readonly root?: IntersectionRoot;
+  /**
+   * Margin grown or shrunk around the root box, in CSS margin syntax.
+   *
+   * @default "0px"
+   */
+  readonly rootMargin?: MaybeRefOrGetter<string>;
+  /**
+   * Visible-ratio thresholds that trigger the callback.
+   *
+   * @default 0
+   */
+  readonly threshold?: MaybeRefOrGetter<number | readonly number[]>;
+  /**
+   * Start observing during composable creation. When `false`, call `resume`.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+  /**
+   * Reactive constructor capability for alternate runtimes and tests.
+   *
+   * @default globalThis when it provides `IntersectionObserver`
+   */
+  readonly host?: MaybeRefOrGetter<IntersectionObserverHost | null | undefined>;
+  /**
+   * Target resolution timing. `"post"` observes template refs after mount.
+   *
+   * @default "post"
+   */
+  readonly flush?: "pre" | "post" | "sync";
+}
+/** Controls returned by {@link useIntersectionObserver}. */
+interface IntersectionObserverControls {
+  /** Whether the host provides `IntersectionObserver`. `false` during server rendering. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+  /** Whether observation is currently requested (not paused or stopped). */
+  readonly isActive: Readonly<Ref<boolean>>;
+  /** Disconnect the observer while keeping the ability to `resume`. */
+  readonly pause: () => void;
+  /** Reconnect after `pause` (or start when created with `immediate: false`). */
+  readonly resume: () => void;
+  /** Disconnect permanently. Later `resume` calls are ignored. Idempotent. */
+  readonly stop: () => void;
+}
+/**
+ * Observe the intersection of reactive elements with a root.
+ *
+ * One observer is created per combination of resolved targets, root,
+ * margin, and threshold; changing any of them disconnects the previous
+ * observer first. During server rendering `isSupported` is `false` and the
+ * callback never runs. The observer is disconnected when the owning scope
+ * stops.
+ *
+ * @param targets Reactive element target or list of targets.
+ * @param callback Native `IntersectionObserver` callback.
+ * @param options Root, margin, thresholds, capability, and timing.
+ * @default options {}
+ * @returns Support/activity flags and pause/resume/stop controls.
+ */
+declare function useIntersectionObserver(targets: MaybeElementTargets, callback: IntersectionObserverCallback, options?: UseIntersectionObserverOptions): IntersectionObserverControls;
+/** Options for {@link useElementVisibility}. */
+interface UseElementVisibilityOptions extends Omit<UseIntersectionObserverOptions, "immediate"> {
+  /**
+   * Visibility exposed before the first observation and during server
+   * rendering. Keep it identical on server and client.
+   *
+   * @default false
+   */
+  readonly initialValue?: boolean;
+  /**
+   * Stop observing after the element becomes visible for the first time.
+   *
+   * @default false
+   */
+  readonly once?: boolean;
+}
+/** Reactive state returned by {@link useElementVisibility}. */
+interface ElementVisibilityControls {
+  /** Whether the element currently intersects the root. */
+  readonly isVisible: Readonly<Ref<boolean>>;
+  /** Whether the host provides `IntersectionObserver`. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+  /** Stop observing. Idempotent. */
+  readonly stop: () => void;
+}
+/**
+ * Track whether an element is visible inside the viewport (or a root).
+ *
+ * Uses the latest intersection entry, so rapid enter/leave sequences settle
+ * on the final state. With `once`, the observer disconnects after the first
+ * visible entry and `isVisible` stays `true`.
+ *
+ * @param target Reactive element target.
+ * @param options Initial value, one-shot mode, and observer options.
+ * @default options {}
+ * @returns Reactive visibility plus controls.
+ */
+declare function useElementVisibility(target: MaybeElementTarget, options?: UseElementVisibilityOptions): ElementVisibilityControls;
+//#endregion
+export { ElementVisibilityControls, IntersectionObserverControls, IntersectionObserverHost, IntersectionRoot, UseElementVisibilityOptions, UseIntersectionObserverOptions, useElementVisibility, useIntersectionObserver };

package/dist/intersection-observer.mjs

@@ -0,0 +1,117 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { resolveElement, resolveElements } from "./element-target.mjs";
+import { hasInjectionContext, onMounted, readonly, ref, shallowRef, toValue, watch } from "vue";
+//#region src/intersection-observer.ts
+/**
+* Observe the intersection of reactive elements with a root.
+*
+* One observer is created per combination of resolved targets, root,
+* margin, and threshold; changing any of them disconnects the previous
+* observer first. During server rendering `isSupported` is `false` and the
+* callback never runs. The observer is disconnected when the owning scope
+* stops.
+*
+* @param targets Reactive element target or list of targets.
+* @param callback Native `IntersectionObserver` callback.
+* @param options Root, margin, thresholds, capability, and timing.
+* @default options {}
+* @returns Support/activity flags and pause/resume/stop controls.
+*/
+function useIntersectionObserver(targets, callback, options = {}) {
+	const isSupported = ref(false);
+	const isActive = ref(options.immediate ?? true);
+	let stopped = false;
+	let stopWatch;
+	const mounted = shallowRef(!hasInjectionContext());
+	if (!mounted.value) onMounted(() => {
+		mounted.value = true;
+	});
+	const host = () => !mounted.value ? void 0 : options.host === void 0 ? browserIntersectionObserverHost() : toValue(options.host);
+	isSupported.value = host()?.IntersectionObserver !== void 0;
+	const connect = () => {
+		stopWatch = watch(() => [
+			host(),
+			resolveElements(targets),
+			resolveRoot(options.root),
+			toValue(options.rootMargin) ?? "0px",
+			toValue(options.threshold) ?? 0
+		], ([currentHost, elements, root, rootMargin, threshold], _previous, onCleanup) => {
+			const Observer = currentHost?.IntersectionObserver;
+			isSupported.value = Observer !== void 0;
+			if (!Observer || elements.length === 0) return;
+			const observer = new Observer(callback, {
+				root,
+				rootMargin,
+				threshold: typeof threshold === "number" ? threshold : [...threshold]
+			});
+			for (const element of elements) observer.observe(element);
+			onCleanup(() => observer.disconnect());
+		}, {
+			immediate: true,
+			flush: options.flush ?? "post"
+		});
+	};
+	const pause = () => {
+		stopWatch?.stop();
+		stopWatch = void 0;
+		isActive.value = false;
+	};
+	const resume = () => {
+		if (stopped || stopWatch) return;
+		isActive.value = true;
+		connect();
+	};
+	const stop = () => {
+		stopped = true;
+		pause();
+	};
+	if (isActive.value) connect();
+	tryOnScopeDispose(stop);
+	return {
+		isSupported: readonly(isSupported),
+		isActive: readonly(isActive),
+		pause,
+		resume,
+		stop
+	};
+}
+/**
+* Track whether an element is visible inside the viewport (or a root).
+*
+* Uses the latest intersection entry, so rapid enter/leave sequences settle
+* on the final state. With `once`, the observer disconnects after the first
+* visible entry and `isVisible` stays `true`.
+*
+* @param target Reactive element target.
+* @param options Initial value, one-shot mode, and observer options.
+* @default options {}
+* @returns Reactive visibility plus controls.
+*/
+function useElementVisibility(target, options = {}) {
+	const isVisible = ref(options.initialValue ?? false);
+	const controls = useIntersectionObserver(target, (entries) => {
+		let latest;
+		for (const entry of entries) if (!latest || entry.time >= latest.time) latest = entry;
+		if (!latest) return;
+		isVisible.value = latest.isIntersecting;
+		if (options.once && latest.isIntersecting) controls.stop();
+	}, options);
+	return {
+		isVisible: readonly(isVisible),
+		isSupported: controls.isSupported,
+		stop: controls.stop
+	};
+}
+function resolveRoot(root) {
+	if (root === void 0) return null;
+	const value = toValue(root);
+	return isDocumentNode(value) ? value : resolveElement(value);
+}
+function isDocumentNode(value) {
+	return typeof value === "object" && value !== null && "nodeType" in value && value.nodeType === 9;
+}
+function browserIntersectionObserverHost() {
+	return typeof IntersectionObserver === "function" ? globalThis : void 0;
+}
+//#endregion
+export { useElementVisibility, useIntersectionObserver };

package/dist/magic-keys.d.mts

@@ -0,0 +1,121 @@
+import { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/magic-keys.d.ts
+/** Modifier key names recognized in combos (after alias resolution). */
+type ModifierKeyName = "control" | "shift" | "alt" | "meta";
+/**
+ * Validate a key combo string at the type level.
+ *
+ * Combos join lowercase-insensitive key names with `+` or `_`
+ * (`"ctrl+s"`, `"shift_arrowup"`). Empty segments such as `"ctrl+"` or
+ * `"+s"` resolve to `never`, turning typos into compile errors. Non-literal
+ * `string` values are accepted unchanged.
+ */
+type KeyCombo<Combo extends string> = string extends Combo ? string : Combo extends "" ? never : Combo extends `${infer Head}${"+" | "_"}${infer Tail}` ? Head extends "" ? never : Tail extends "" ? never : KeyCombo<Tail> extends never ? never : Combo : Combo;
+/** Default aliases resolved before matching combos. */
+declare const DEFAULT_KEY_ALIASES: {
+  readonly ctrl: "control";
+  readonly command: "meta";
+  readonly cmd: "meta";
+  readonly option: "alt";
+  readonly esc: "escape";
+  readonly up: "arrowup";
+  readonly down: "arrowdown";
+  readonly left: "arrowleft";
+  readonly right: "arrowright";
+  readonly " ": "space";
+  readonly spacebar: "space";
+};
+/** Options shared by the keyboard composables. */
+interface UseKeyboardTargetOptions {
+  /**
+   * Event target that receives `keydown`/`keyup`.
+   *
+   * @default globalThis.window when available
+   */
+  readonly target?: MaybeRefOrGetter<EventTarget | null | undefined>;
+  /**
+   * Register passive listeners.
+   *
+   * @default true
+   */
+  readonly passive?: boolean;
+}
+/** Options for {@link useMagicKeys}. */
+interface UseMagicKeysOptions extends UseKeyboardTargetOptions {
+  /**
+   * Extra aliases merged over {@link DEFAULT_KEY_ALIASES}. Keys and values are
+   * matched case-insensitively.
+   *
+   * @default {}
+   */
+  readonly aliasMap?: Readonly<Record<string, string>>;
+  /**
+   * Called for every `keydown`/`keyup` after the pressed set has been
+   * updated. Useful for `preventDefault()` with `passive: false`.
+   *
+   * @default undefined
+   */
+  readonly onEventFired?: (event: KeyboardEvent) => void;
+}
+/** Reactive keyboard state returned by {@link useMagicKeys}. */
+interface MagicKeys {
+  /** Normalized names (`event.key` and `event.code`, lowercase) currently pressed. */
+  readonly current: ReadonlySet<string>;
+  /**
+   * Proxy of combo refs created lazily on property access, e.g.
+   * `const { shift, ctrl_s } = keys.combos`.
+   */
+  readonly combos: Readonly<Record<string, ComputedRef<boolean>>>;
+  /**
+   * Create (or reuse) a ref that is `true` while every key of the combo is
+   * pressed.
+   *
+   * @param combo Key combo such as `"ctrl+shift+p"`.
+   * @returns Readonly computed ref.
+   */
+  readonly isPressed: <const Combo extends string>(combo: Combo & KeyCombo<Combo>) => ComputedRef<boolean>;
+  /** Forget every pressed key (for example after a modal steals focus). */
+  readonly reset: () => void;
+}
+/**
+ * Normalize a key name the way combos are matched.
+ *
+ * @param name Raw `KeyboardEvent.key`/`code` or combo segment.
+ * @param aliases Alias table (keys lowercased).
+ * @default aliases DEFAULT_KEY_ALIASES
+ * @returns Lowercase, alias-resolved name.
+ */
+declare function normalizeKeyName(name: string, aliases?: Readonly<Record<string, string>>): string;
+/**
+ * Track pressed keys and expose reactive key combos.
+ *
+ * Both `event.key` and `event.code` are recorded (lowercased), so `"a"` and
+ * `"keya"` both match. Because some platforms (notably macOS with `meta`)
+ * swallow `keyup` for other keys while a modifier is held, releasing a
+ * modifier clears every non-modifier key; losing window focus clears
+ * everything. Nothing is pressed during server rendering, and listeners are
+ * removed with the owning reactive scope.
+ *
+ * @param options Target, passivity, aliases, and event hook.
+ * @default options {}
+ * @returns Pressed set, lazily created combo refs, and controls.
+ */
+declare function useMagicKeys(options?: UseMagicKeysOptions): MagicKeys;
+/** Key filter accepted by {@link useKeyPressed}. */
+type KeyFilter = string | readonly string[] | ((event: KeyboardEvent) => boolean);
+/**
+ * Track whether any key matching a filter is held down.
+ *
+ * String filters are normalized like combos (`"esc"` matches `Escape`) and
+ * compared against both `event.key` and `event.code`. The state resets on
+ * window blur and during server rendering is always `false`.
+ *
+ * @param filter Key name(s) or predicate.
+ * @param options Target and passivity.
+ * @default options {}
+ * @returns Readonly ref that is `true` while a matching key is held.
+ */
+declare function useKeyPressed(filter: KeyFilter, options?: UseKeyboardTargetOptions): Readonly<Ref<boolean>>;
+//#endregion
+export { DEFAULT_KEY_ALIASES, KeyCombo, KeyFilter, MagicKeys, ModifierKeyName, UseKeyboardTargetOptions, UseMagicKeysOptions, normalizeKeyName, useKeyPressed, useMagicKeys };

package/dist/magic-keys.mjs

@@ -0,0 +1,163 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { computed, reactive, readonly, ref, toValue, watch } from "vue";
+//#region src/magic-keys.ts
+/** Default aliases resolved before matching combos. */
+const DEFAULT_KEY_ALIASES = {
+	ctrl: "control",
+	command: "meta",
+	cmd: "meta",
+	option: "alt",
+	esc: "escape",
+	up: "arrowup",
+	down: "arrowdown",
+	left: "arrowleft",
+	right: "arrowright",
+	" ": "space",
+	spacebar: "space"
+};
+const modifierNames = new Set([
+	"control",
+	"shift",
+	"alt",
+	"meta"
+]);
+/**
+* Normalize a key name the way combos are matched.
+*
+* @param name Raw `KeyboardEvent.key`/`code` or combo segment.
+* @param aliases Alias table (keys lowercased).
+* @default aliases DEFAULT_KEY_ALIASES
+* @returns Lowercase, alias-resolved name.
+*/
+function normalizeKeyName(name, aliases = DEFAULT_KEY_ALIASES) {
+	const lower = name.toLowerCase();
+	return (aliases[lower] ?? lower).toLowerCase();
+}
+/**
+* Track pressed keys and expose reactive key combos.
+*
+* Both `event.key` and `event.code` are recorded (lowercased), so `"a"` and
+* `"keya"` both match. Because some platforms (notably macOS with `meta`)
+* swallow `keyup` for other keys while a modifier is held, releasing a
+* modifier clears every non-modifier key; losing window focus clears
+* everything. Nothing is pressed during server rendering, and listeners are
+* removed with the owning reactive scope.
+*
+* @param options Target, passivity, aliases, and event hook.
+* @default options {}
+* @returns Pressed set, lazily created combo refs, and controls.
+*/
+function useMagicKeys(options = {}) {
+	const aliases = { ...DEFAULT_KEY_ALIASES };
+	for (const [alias, key] of Object.entries(options.aliasMap ?? {})) aliases[alias.toLowerCase()] = key.toLowerCase();
+	const current = reactive(/* @__PURE__ */ new Set());
+	const cache = /* @__PURE__ */ new Map();
+	const namesOf = (event) => {
+		const names = /* @__PURE__ */ new Set();
+		if (event.key) names.add(normalizeKeyName(event.key, aliases));
+		if (event.code) names.add(normalizeKeyName(event.code, aliases));
+		return [...names];
+	};
+	const reset = () => current.clear();
+	const onKey = (event) => {
+		if (!isKeyboardEvent(event)) return;
+		const names = namesOf(event);
+		if (event.type === "keydown") for (const name of names) current.add(name);
+		else {
+			for (const name of names) current.delete(name);
+			if (names.some((name) => modifierNames.has(name))) {
+				for (const name of current) if (!modifierNames.has(name)) current.delete(name);
+			}
+		}
+		options.onEventFired?.(event);
+	};
+	const stop = watch(() => options.target === void 0 ? browserWindow() : toValue(options.target), (target, _previous, onCleanup) => {
+		if (!target) return;
+		const listenerOptions = { passive: options.passive ?? true };
+		target.addEventListener("keydown", onKey, listenerOptions);
+		target.addEventListener("keyup", onKey, listenerOptions);
+		target.addEventListener("blur", reset, { passive: true });
+		onCleanup(() => {
+			target.removeEventListener("keydown", onKey);
+			target.removeEventListener("keyup", onKey);
+			target.removeEventListener("blur", reset);
+			reset();
+		});
+	}, { immediate: true });
+	tryOnScopeDispose(() => stop.stop());
+	const comboRef = (combo) => {
+		const key = combo.toLowerCase();
+		const cached = cache.get(key);
+		if (cached) return cached;
+		const parts = key.split(/[+_]/).filter((part) => part !== "").map((part) => normalizeKeyName(part, aliases));
+		const pressed = computed(() => parts.length > 0 && parts.every((part) => current.has(part)));
+		cache.set(key, pressed);
+		return pressed;
+	};
+	const combos = new Proxy({}, {
+		get: (_target, property) => typeof property === "string" ? comboRef(property) : void 0,
+		has: (_target, property) => typeof property === "string"
+	});
+	return {
+		current: readonly(current),
+		combos,
+		isPressed: (combo) => comboRef(combo),
+		reset
+	};
+}
+/**
+* Track whether any key matching a filter is held down.
+*
+* String filters are normalized like combos (`"esc"` matches `Escape`) and
+* compared against both `event.key` and `event.code`. The state resets on
+* window blur and during server rendering is always `false`.
+*
+* @param filter Key name(s) or predicate.
+* @param options Target and passivity.
+* @default options {}
+* @returns Readonly ref that is `true` while a matching key is held.
+*/
+function useKeyPressed(filter, options = {}) {
+	const held = /* @__PURE__ */ new Set();
+	const pressed = ref(false);
+	const names = typeof filter === "function" ? void 0 : new Set((typeof filter === "string" ? [filter] : filter).map((name) => normalizeKeyName(name)));
+	const matches = (event) => names === void 0 ? typeof filter === "function" && filter(event) : names.has(normalizeKeyName(event.key)) || names.has(normalizeKeyName(event.code));
+	const identity = (event) => event.code || event.key;
+	const onDown = (event) => {
+		if (!isKeyboardEvent(event) || !matches(event)) return;
+		held.add(identity(event));
+		pressed.value = true;
+	};
+	const onUp = (event) => {
+		if (!isKeyboardEvent(event)) return;
+		held.delete(identity(event));
+		pressed.value = held.size > 0;
+	};
+	const reset = () => {
+		held.clear();
+		pressed.value = false;
+	};
+	const stop = watch(() => options.target === void 0 ? browserWindow() : toValue(options.target), (target, _previous, onCleanup) => {
+		if (!target) return;
+		const listenerOptions = { passive: options.passive ?? true };
+		target.addEventListener("keydown", onDown, listenerOptions);
+		target.addEventListener("keyup", onUp, listenerOptions);
+		target.addEventListener("blur", reset, { passive: true });
+		onCleanup(() => {
+			target.removeEventListener("keydown", onDown);
+			target.removeEventListener("keyup", onUp);
+			target.removeEventListener("blur", reset);
+			reset();
+		});
+	}, { immediate: true });
+	tryOnScopeDispose(() => stop.stop());
+	return readonly(pressed);
+}
+function isKeyboardEvent(event) {
+	return "key" in event && "code" in event;
+}
+function browserWindow() {
+	return typeof window !== "undefined" ? window : void 0;
+}
+//#endregion
+export { DEFAULT_KEY_ALIASES, normalizeKeyName, useKeyPressed, useMagicKeys };