@vizejs/composable 0.426.3 → 0.428.0

package/dist/element-hover.mjs

@@ -0,0 +1,70 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { resolveElement } from "./element-target.mjs";
+import { readonly, ref, watch } from "vue";
+//#region src/element-hover.ts
+const defaultScheduler = {
+	setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+	clearTimeout: (handle) => {
+		globalThis.clearTimeout(handle);
+	}
+};
+/**
+* Track whether the pointer hovers an element.
+*
+* Uses `pointerenter`/`pointerleave` (which ignore descendants) with optional
+* enter/leave delays; a pending delay is cancelled by the opposite event.
+* Server renders report `false`; listeners and timers are released with the
+* owning reactive scope.
+*
+* @param target Reactive element target.
+* @param options Enter/leave delays and timer scheduler.
+* @default options {}
+* @returns Readonly hover flag.
+*/
+function useElementHover(target, options = {}) {
+	const { delayEnter = 0, delayLeave = 0, scheduler = defaultScheduler } = options;
+	const hovered = ref(false);
+	let handle;
+	let pending = false;
+	const cancel = () => {
+		if (!pending) return;
+		scheduler.clearTimeout(handle);
+		pending = false;
+	};
+	const set = (next) => {
+		cancel();
+		const delay = next ? delayEnter : delayLeave;
+		if (delay <= 0) {
+			hovered.value = next;
+			return;
+		}
+		pending = true;
+		handle = scheduler.setTimeout(() => {
+			pending = false;
+			hovered.value = next;
+		}, delay);
+	};
+	const onEnter = () => set(true);
+	const onLeave = () => set(false);
+	const stop = watch(() => resolveElement(target), (element, _previous, onCleanup) => {
+		if (!element) return;
+		element.addEventListener("pointerenter", onEnter, { passive: true });
+		element.addEventListener("pointerleave", onLeave, { passive: true });
+		onCleanup(() => {
+			element.removeEventListener("pointerenter", onEnter);
+			element.removeEventListener("pointerleave", onLeave);
+			cancel();
+			hovered.value = false;
+		});
+	}, {
+		immediate: true,
+		flush: "post"
+	});
+	tryOnScopeDispose(() => {
+		stop.stop();
+		cancel();
+	});
+	return readonly(hovered);
+}
+//#endregion
+export { useElementHover };

package/dist/element-ref.d.mts

@@ -0,0 +1,34 @@
+import { ComponentPublicInstance, ShallowRef } from "vue";
+
+//#region src/element-ref.d.ts
+/** Function ref accepted by `:ref` on elements and components. */
+type ElementRefSetter = (value: Element | ComponentPublicInstance | null) => void;
+/** State returned by {@link useElementRef}. */
+interface ElementRefControls<TargetElement extends Element> {
+  /** Resolved element (component roots are unwrapped); `null` while unmounted. */
+  readonly element: Readonly<ShallowRef<TargetElement | null>>;
+  /** Bind with `:ref="setRef"` on an element or component. */
+  readonly setRef: ElementRefSetter;
+}
+/**
+ * Capture a template element through a function ref.
+ *
+ * An instance-free alternative to "current element" helpers: it never reads
+ * `getCurrentInstance()`, so it works in Vapor components, render functions,
+ * and plain effect scopes. Inside a component the element is published after
+ * mounting (Vapor sets function refs during render), keeping hydration stable. Component refs are unwrapped to their root
+ * element, and an optional guard narrows the element type (elements failing
+ * it resolve to `null`). The ref is `null` during server rendering.
+ *
+ * @returns Reactive element plus the function ref to bind.
+ */
+declare function useElementRef(): ElementRefControls<Element>;
+/**
+ * Capture a template element narrowed by a type guard.
+ *
+ * @param guard Type guard; elements failing it resolve to `null`.
+ * @returns Reactive narrowed element plus the function ref to bind.
+ */
+declare function useElementRef<TargetElement extends Element>(guard: (element: Element) => element is TargetElement): ElementRefControls<TargetElement>;
+//#endregion
+export { ElementRefControls, ElementRefSetter, useElementRef };

package/dist/element-ref.mjs

@@ -0,0 +1,23 @@
+import { resolveElement } from "./element-target.mjs";
+import { hasInjectionContext, onMounted, shallowRef } from "vue";
+//#region src/element-ref.ts
+function useElementRef(guard) {
+	const element = shallowRef(null);
+	let mounted = !hasInjectionContext();
+	let pending = null;
+	if (!mounted) onMounted(() => {
+		mounted = true;
+		element.value = pending;
+	});
+	const setRef = (value) => {
+		const resolved = resolveElement(value);
+		pending = resolved && (!guard || guard(resolved)) ? resolved : null;
+		if (mounted) element.value = pending;
+	};
+	return {
+		element,
+		setRef
+	};
+}
+//#endregion
+export { useElementRef };

package/dist/element-target-Crpxl4D9.d.mts

@@ -0,0 +1,60 @@
+import { ComponentPublicInstance, MaybeRefOrGetter } from "vue";
+
+//#region src/element-target.d.ts
+/**
+ * A concrete value that can identify a DOM element.
+ *
+ * Template refs on native elements resolve to the element itself, while refs
+ * on components resolve to the component's public instance whose root node
+ * is exposed as `$el`. `null` and `undefined` represent a target that is not
+ * mounted yet (including every server render).
+ */
+type ElementTargetValue<TargetElement extends Element = Element> = TargetElement | ComponentPublicInstance | null | undefined;
+/**
+ * Reactive element target accepted by every element-based composable.
+ *
+ * Accepts a plain value, a ref (such as `useTemplateRef()`), or a getter.
+ */
+type MaybeElementTarget<TargetElement extends Element = Element> = MaybeRefOrGetter<ElementTargetValue<TargetElement>>;
+/**
+ * Reactive list of element targets for observers that watch several nodes.
+ *
+ * Each item follows {@link MaybeElementTarget} semantics; unresolved items
+ * are skipped.
+ */
+type MaybeElementTargets<TargetElement extends Element = Element> = MaybeElementTarget<TargetElement> | MaybeRefOrGetter<readonly ElementTargetValue<TargetElement>[]>;
+/**
+ * Whether a value is a DOM element node.
+ *
+ * Uses the `nodeType` contract instead of `instanceof Element`, so the check
+ * reads no browser globals and works across realms (iframes, happy-dom,
+ * jsdom).
+ *
+ * @param value Candidate value.
+ * @returns Whether `value` is an element node.
+ */
+declare function isElementNode(value: unknown): value is Element;
+/**
+ * Resolve a reactive element target to its concrete element.
+ *
+ * Reads the reactive source once (tracking it when called inside an effect).
+ * Component instances resolve to their root element; fragment or text roots
+ * resolve to `null`. Never throws and reads no browser globals, so it is safe
+ * during server rendering, where it always returns `null`.
+ *
+ * @param target Reactive element target.
+ * @returns The resolved element, or `null` while unresolved.
+ */
+declare function resolveElement(target: MaybeElementTarget): Element | null;
+/**
+ * Resolve a reactive list (or single) element target to its concrete elements.
+ *
+ * Unresolved entries are dropped and duplicates are removed while keeping the
+ * first-seen order, so observers never register the same node twice.
+ *
+ * @param targets Reactive element target or target list.
+ * @returns The resolved, de-duplicated elements.
+ */
+declare function resolveElements(targets: MaybeElementTargets): Element[];
+//#endregion
+export { resolveElement as a, isElementNode as i, MaybeElementTarget as n, resolveElements as o, MaybeElementTargets as r, ElementTargetValue as t };

package/dist/element-target.d.mts

@@ -0,0 +1,2 @@
+import { a as resolveElement, i as isElementNode, n as MaybeElementTarget, o as resolveElements, r as MaybeElementTargets, t as ElementTargetValue } from "./element-target-Crpxl4D9.mjs";
+export { ElementTargetValue, MaybeElementTarget, MaybeElementTargets, isElementNode, resolveElement, resolveElements };

package/dist/element-target.mjs

@@ -0,0 +1,58 @@
+import { toValue } from "vue";
+//#region src/element-target.ts
+/**
+* Whether a value is a DOM element node.
+*
+* Uses the `nodeType` contract instead of `instanceof Element`, so the check
+* reads no browser globals and works across realms (iframes, happy-dom,
+* jsdom).
+*
+* @param value Candidate value.
+* @returns Whether `value` is an element node.
+*/
+function isElementNode(value) {
+	return typeof value === "object" && value !== null && "nodeType" in value && value.nodeType === 1 && "getBoundingClientRect" in value;
+}
+/**
+* Resolve a reactive element target to its concrete element.
+*
+* Reads the reactive source once (tracking it when called inside an effect).
+* Component instances resolve to their root element; fragment or text roots
+* resolve to `null`. Never throws and reads no browser globals, so it is safe
+* during server rendering, where it always returns `null`.
+*
+* @param target Reactive element target.
+* @returns The resolved element, or `null` while unresolved.
+*/
+function resolveElement(target) {
+	return elementFromValue(toValue(target));
+}
+function elementFromValue(value) {
+	if (isElementNode(value)) return value;
+	if (typeof value === "object" && value !== null && "$el" in value) {
+		const root = value.$el;
+		return isElementNode(root) ? root : null;
+	}
+	return null;
+}
+/**
+* Resolve a reactive list (or single) element target to its concrete elements.
+*
+* Unresolved entries are dropped and duplicates are removed while keeping the
+* first-seen order, so observers never register the same node twice.
+*
+* @param targets Reactive element target or target list.
+* @returns The resolved, de-duplicated elements.
+*/
+function resolveElements(targets) {
+	const value = toValue(targets);
+	const items = Array.isArray(value) ? value : [value];
+	const elements = [];
+	for (const item of items) {
+		const element = elementFromValue(item);
+		if (element && !elements.includes(element)) elements.push(element);
+	}
+	return elements;
+}
+//#endregion
+export { isElementNode, resolveElement, resolveElements };

package/dist/event-listener.mjs

@@ -1,5 +1,5 @@
 import { tryOnScopeDispose } from "./scope.mjs";
-import { readonly, ref, toValue, watch } from "vue";
+import { hasInjectionContext, onMounted, readonly, ref, shallowRef, toValue, watch } from "vue";
 //#region src/event-listener.ts
 function useEventListener(target, event, listener, options = {}) {
 	const { capture = false, once = false, passive = false, signal, immediate = true, flush = "pre" } = options;
@@ -10,6 +10,10 @@ function useEventListener(target, event, listener, options = {}) {
 		...signal ? { signal } : {}
 	};
 	let disposed = false;
+	const mounted = shallowRef(!hasInjectionContext());
+	if (!mounted.value) onMounted(() => {
+		mounted.value = true;
+	});
 	let stopWatch;
 	const stop = () => {
 		stopWatch?.stop();
@@ -18,7 +22,7 @@ function useEventListener(target, event, listener, options = {}) {
 	};
 	const start = () => {
 		if (disposed || stopWatch || signal?.aborted) return false;
-		stopWatch = watch(() => toValue(target), (next, _previous, onCleanup) => {
+		stopWatch = watch(() => mounted.value ? toValue(target) : null, (next, _previous, onCleanup) => {
 			isListening.value = false;
 			if (!next || signal?.aborted) return;
 			const invoke = (nativeEvent) => {
@@ -30,7 +34,7 @@ function useEventListener(target, event, listener, options = {}) {
 			signal?.addEventListener("abort", onAbort, { once: true });
 			isListening.value = true;
 			onCleanup(() => {
-				next.removeEventListener(event, invoke, capture);
+				next.removeEventListener(event, invoke, { capture });
 				signal?.removeEventListener("abort", onAbort);
 				isListening.value = false;
 			});

package/dist/focus.d.mts

@@ -0,0 +1,69 @@
+import { n as MaybeElementTarget } from "./element-target-Crpxl4D9.mjs";
+import { Ref, WritableComputedRef } from "vue";
+
+//#region src/focus.d.ts
+/** Element that can receive programmatic focus (`HTMLElement`, `SVGElement`, `MathMLElement`). */
+type FocusableElement = Element & HTMLOrSVGElement;
+/** Options for {@link useFocus}. */
+interface UseFocusOptions {
+  /**
+   * Focus the element as soon as it resolves.
+   *
+   * @default false
+   */
+  readonly initialValue?: boolean;
+  /**
+   * Only report focus when the user agent would show a focus ring
+   * (`:focus-visible`).
+   *
+   * @default false
+   */
+  readonly focusVisible?: boolean;
+  /**
+   * Avoid scrolling the element into view when focusing programmatically.
+   *
+   * @default false
+   */
+  readonly preventScroll?: boolean;
+}
+/** Reactive focus state returned by {@link useFocus}. */
+interface FocusControls {
+  /** Whether the element is focused. Assign `true`/`false` to focus/blur it. */
+  readonly focused: WritableComputedRef<boolean>;
+  /** Stop tracking. Idempotent. */
+  readonly stop: () => void;
+}
+/**
+ * Track and control focus of a single element.
+ *
+ * Listens for `focus`/`blur` on the resolved element and re-syncs when the
+ * target changes. Assigning `focused` calls `focus()`/`blur()`. Server renders
+ * always report `false`; `initialValue` is applied only after the element
+ * resolves on the client, so hydration output is unaffected.
+ *
+ * @param target Reactive element target.
+ * @param options Initial focus, focus-visible filtering, and scroll behavior.
+ * @default options {}
+ * @returns Writable focus ref and stop control.
+ */
+declare function useFocus(target: MaybeElementTarget, options?: UseFocusOptions): FocusControls;
+/** Reactive state returned by {@link useFocusWithin}. */
+interface FocusWithinControls {
+  /** Whether the element or any descendant has focus. */
+  readonly focused: Readonly<Ref<boolean>>;
+  /** Stop tracking. Idempotent. */
+  readonly stop: () => void;
+}
+/**
+ * Track whether focus is inside an element (the `:focus-within` state).
+ *
+ * Uses bubbling `focusin`/`focusout` and checks the `relatedTarget` so moving
+ * focus between descendants never flickers to `false`. Server renders report
+ * `false`.
+ *
+ * @param target Reactive element target.
+ * @returns Readonly focus-within ref and stop control.
+ */
+declare function useFocusWithin(target: MaybeElementTarget): FocusWithinControls;
+//#endregion
+export { FocusControls, FocusWithinControls, FocusableElement, UseFocusOptions, useFocus, useFocusWithin };

package/dist/focus.mjs

@@ -0,0 +1,124 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { resolveElement } from "./element-target.mjs";
+import { computed, readonly, ref, watch } from "vue";
+//#region src/focus.ts
+/**
+* Track and control focus of a single element.
+*
+* Listens for `focus`/`blur` on the resolved element and re-syncs when the
+* target changes. Assigning `focused` calls `focus()`/`blur()`. Server renders
+* always report `false`; `initialValue` is applied only after the element
+* resolves on the client, so hydration output is unaffected.
+*
+* @param target Reactive element target.
+* @param options Initial focus, focus-visible filtering, and scroll behavior.
+* @default options {}
+* @returns Writable focus ref and stop control.
+*/
+function useFocus(target, options = {}) {
+	const inner = ref(false);
+	const element = computed(() => {
+		const resolved = resolveElement(target);
+		return resolved && isFocusable(resolved) ? resolved : null;
+	});
+	const read = (el) => {
+		const active = el.ownerDocument.activeElement === el;
+		if (!active || !options.focusVisible) return active;
+		return safeMatches(el, ":focus-visible");
+	};
+	const stopWatch = watch(element, (el, _previous, onCleanup) => {
+		if (!el) {
+			inner.value = false;
+			return;
+		}
+		const onFocus = () => {
+			inner.value = read(el);
+		};
+		const onBlur = () => {
+			inner.value = false;
+		};
+		el.addEventListener("focus", onFocus);
+		el.addEventListener("blur", onBlur);
+		inner.value = read(el);
+		if (options.initialValue && !inner.value) el.focus({ preventScroll: options.preventScroll ?? false });
+		onCleanup(() => {
+			el.removeEventListener("focus", onFocus);
+			el.removeEventListener("blur", onBlur);
+		});
+	}, {
+		immediate: true,
+		flush: "post"
+	});
+	const stop = () => stopWatch.stop();
+	tryOnScopeDispose(stop);
+	return {
+		focused: computed({
+			get: () => inner.value,
+			set: (next) => {
+				const el = element.value;
+				if (!el) return;
+				if (next) el.focus({ preventScroll: options.preventScroll ?? false });
+				else el.blur();
+			}
+		}),
+		stop
+	};
+}
+/**
+* Track whether focus is inside an element (the `:focus-within` state).
+*
+* Uses bubbling `focusin`/`focusout` and checks the `relatedTarget` so moving
+* focus between descendants never flickers to `false`. Server renders report
+* `false`.
+*
+* @param target Reactive element target.
+* @returns Readonly focus-within ref and stop control.
+*/
+function useFocusWithin(target) {
+	const focused = ref(false);
+	const stopWatch = watch(() => resolveElement(target), (el, _previous, onCleanup) => {
+		if (!el) {
+			focused.value = false;
+			return;
+		}
+		const onFocusIn = () => {
+			focused.value = true;
+		};
+		const onFocusOut = (event) => {
+			const next = "relatedTarget" in event ? event.relatedTarget : null;
+			focused.value = isNode(next) && el.contains(next);
+		};
+		el.addEventListener("focusin", onFocusIn);
+		el.addEventListener("focusout", onFocusOut);
+		const active = el.ownerDocument.activeElement;
+		focused.value = active !== null && el.contains(active);
+		onCleanup(() => {
+			el.removeEventListener("focusin", onFocusIn);
+			el.removeEventListener("focusout", onFocusOut);
+		});
+	}, {
+		immediate: true,
+		flush: "post"
+	});
+	const stop = () => stopWatch.stop();
+	tryOnScopeDispose(stop);
+	return {
+		focused: readonly(focused),
+		stop
+	};
+}
+function isFocusable(element) {
+	return "focus" in element && typeof element.focus === "function" && "blur" in element && typeof element.blur === "function";
+}
+function isNode(value) {
+	return typeof value === "object" && value !== null && "nodeType" in value;
+}
+function safeMatches(element, selector) {
+	try {
+		return element.matches(selector);
+	} catch {
+		return true;
+	}
+}
+//#endregion
+export { useFocus, useFocusWithin };

package/dist/fps.d.mts

@@ -0,0 +1,59 @@
+import { MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/fps.d.ts
+/** Frame scheduling capability used by {@link useFps}. */
+interface AnimationFrameHost {
+  /** Schedule a callback before the next repaint. */
+  readonly requestAnimationFrame: (callback: FrameRequestCallback) => number;
+  /** Cancel a scheduled frame. */
+  readonly cancelAnimationFrame: (handle: number) => void;
+}
+/** Options for {@link useFps}. */
+interface UseFpsOptions {
+  /**
+   * Number of frames averaged per update.
+   *
+   * @default 10
+   */
+  readonly every?: number;
+  /**
+   * Start measuring during composable creation.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+  /**
+   * Reactive frame-scheduling capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<AnimationFrameHost | null | undefined>;
+}
+/** Reactive frame-rate state returned by {@link useFps}. */
+interface FpsControls {
+  /** Frames per second averaged over the last `every` frames; `0` until measured. */
+  readonly fps: Readonly<Ref<number>>;
+  /** Whether a frame-scheduling capability is attached. `false` during server rendering. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+  /** Whether the frame loop is running. */
+  readonly isActive: Readonly<Ref<boolean>>;
+  /** Stop the frame loop. */
+  readonly pause: () => void;
+  /** Restart the frame loop. */
+  readonly resume: () => void;
+}
+/**
+ * Measure the rendering frame rate with `requestAnimationFrame`.
+ *
+ * Uses the frame timestamps passed to the callback (no extra clock) and
+ * publishes a rounded average every `every` frames. No frames are requested
+ * during server rendering (`fps` stays `0`), and the pending frame is
+ * cancelled when paused or when the owning reactive scope stops.
+ *
+ * @param options Averaging window, start mode, and frame capability.
+ * @default options {}
+ * @returns Reactive frame rate plus pause/resume controls.
+ */
+declare function useFps(options?: UseFpsOptions): FpsControls;
+//#endregion
+export { AnimationFrameHost, FpsControls, UseFpsOptions, useFps };

package/dist/fps.mjs

@@ -0,0 +1,64 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { hasInjectionContext, onMounted, readonly, ref, shallowRef, toValue, watch } from "vue";
+//#region src/fps.ts
+/**
+* Measure the rendering frame rate with `requestAnimationFrame`.
+*
+* Uses the frame timestamps passed to the callback (no extra clock) and
+* publishes a rounded average every `every` frames. No frames are requested
+* during server rendering (`fps` stays `0`), and the pending frame is
+* cancelled when paused or when the owning reactive scope stops.
+*
+* @param options Averaging window, start mode, and frame capability.
+* @default options {}
+* @returns Reactive frame rate plus pause/resume controls.
+*/
+function useFps(options = {}) {
+	const every = Math.max(1, Math.floor(options.every ?? 10));
+	const fps = ref(0);
+	const isSupported = ref(false);
+	const isActive = ref(options.immediate ?? true);
+	const mounted = shallowRef(!hasInjectionContext());
+	if (!mounted.value) onMounted(() => {
+		mounted.value = true;
+	});
+	const stop = watch([() => !mounted.value ? void 0 : options.host === void 0 ? browserFrameHost() : toValue(options.host), isActive], ([host, active], _previous, onCleanup) => {
+		isSupported.value = Boolean(host);
+		if (!host || !active) return;
+		let handle = 0;
+		let first;
+		let frames = 0;
+		const tick = (time) => {
+			if (first === void 0) first = time;
+			else {
+				frames += 1;
+				if (frames >= every) {
+					const elapsed = time - first;
+					if (elapsed > 0) fps.value = Math.round(1e3 * frames / elapsed);
+					first = time;
+					frames = 0;
+				}
+			}
+			handle = host.requestAnimationFrame(tick);
+		};
+		handle = host.requestAnimationFrame(tick);
+		onCleanup(() => host.cancelAnimationFrame(handle));
+	}, { immediate: true });
+	tryOnScopeDispose(() => stop.stop());
+	return {
+		fps: readonly(fps),
+		isSupported: readonly(isSupported),
+		isActive: readonly(isActive),
+		pause: () => {
+			isActive.value = false;
+		},
+		resume: () => {
+			isActive.value = true;
+		}
+	};
+}
+function browserFrameHost() {
+	return typeof window !== "undefined" && typeof window.requestAnimationFrame === "function" ? window : void 0;
+}
+//#endregion
+export { useFps };