@vizejs/composable 0.345.0 → 0.347.7

package/dist/disposal-scope.mjs

@@ -0,0 +1,119 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+//#region src/disposal-scope.ts
+/** Stable error code reported when one or more owned cleanups fail. */
+const DISPOSAL_ERROR_CODE = "VIZE_COMPOSE_DISPOSAL_FAILED";
+/** Aggregate failure produced after every owned cleanup has been attempted. */
+var DisposalError = class extends AggregateError {
+	/** Stable machine-readable error code. */
+	code = DISPOSAL_ERROR_CODE;
+	/**
+	* Create an aggregate disposal failure.
+	*
+	* Nested {@link DisposalError} instances are flattened by the scope before
+	* construction, so `errors` contains the original cleanup failures in
+	* execution order.
+	*
+	* @param errors Cleanup failures in deterministic execution order.
+	*/
+	constructor(errors) {
+		super(errors, `[${DISPOSAL_ERROR_CODE}] ${String(errors.length)} cleanup operation(s) failed.`);
+		this.name = "DisposalError";
+	}
+};
+/**
+* Create an explicit, deterministic cleanup owner.
+*
+* The owner is runtime-neutral and performs no browser-global access. By
+* default it joins an active Vue reactive scope; when no scope exists, or
+* `scope` is disabled, the caller must invoke `dispose()`. Cleanups are
+* synchronous by contract so disposal completes before the owner releases
+* its records.
+*
+* @param options Reactive-scope ownership behavior.
+* @default options {}
+* @returns A disposal owner with child-lifetime support.
+*/
+function createDisposalScope(options = {}) {
+	const owner = createOwner();
+	if (options.scope ?? true) tryOnScopeDispose(owner.dispose);
+	return owner;
+}
+function createOwner(onDispose) {
+	const records = [];
+	let disposed = false;
+	let size = 0;
+	const add = (cleanup) => {
+		if (disposed) {
+			try {
+				cleanup();
+			} catch (error) {
+				throw new DisposalError(flattenDisposalError(error));
+			}
+			return inactiveRegistration();
+		}
+		const record = {
+			active: true,
+			cleanup
+		};
+		records.push(record);
+		size += 1;
+		return {
+			get active() {
+				return record.active;
+			},
+			unregister() {
+				if (!record.active) return false;
+				record.active = false;
+				size -= 1;
+				return true;
+			}
+		};
+	};
+	const dispose = () => {
+		if (disposed) return;
+		disposed = true;
+		onDispose?.();
+		const errors = [];
+		for (let index = records.length - 1; index >= 0; index -= 1) {
+			const record = records[index];
+			if (!record?.active) continue;
+			record.active = false;
+			size -= 1;
+			try {
+				record.cleanup();
+			} catch (error) {
+				errors.push(...flattenDisposalError(error));
+			}
+		}
+		records.length = 0;
+		if (errors.length > 0) throw new DisposalError(errors);
+	};
+	const child = () => {
+		let parentRegistration;
+		const childOwner = createOwner(() => parentRegistration?.unregister());
+		parentRegistration = add(childOwner.dispose);
+		return childOwner;
+	};
+	return {
+		get disposed() {
+			return disposed;
+		},
+		get size() {
+			return size;
+		},
+		add,
+		child,
+		dispose
+	};
+}
+function inactiveRegistration() {
+	return {
+		active: false,
+		unregister: () => false
+	};
+}
+function flattenDisposalError(error) {
+	return error instanceof DisposalError ? error.errors : [error];
+}
+//#endregion
+export { DISPOSAL_ERROR_CODE, DisposalError, createDisposalScope };

package/dist/event-listener.d.mts

@@ -0,0 +1,85 @@
+import { MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/event-listener.d.ts
+/** Options for {@link useEventListener}. */
+interface UseEventListenerOptions {
+  /**
+   * Invoke the listener during the capture phase.
+   *
+   * @default false
+   */
+  readonly capture?: boolean;
+  /**
+   * Stop listening after the first event.
+   *
+   * @default false
+   */
+  readonly once?: boolean;
+  /**
+   * Declare that the listener does not cancel the event's default action.
+   *
+   * @default false
+   */
+  readonly passive?: boolean;
+  /**
+   * Stop listening when this signal is aborted. An already-aborted signal
+   * prevents listening from ever starting.
+   *
+   * @default undefined
+   */
+  readonly signal?: AbortSignal;
+  /**
+   * Start listening during composable creation.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+  /**
+   * Reactive target update timing.
+   *
+   * @default "pre"
+   */
+  readonly flush?: "pre" | "post" | "sync";
+}
+/** Reactive controls returned by {@link useEventListener}. */
+interface EventListenerControls {
+  /** Whether a concrete target currently owns the listener. */
+  readonly isListening: Readonly<Ref<boolean>>;
+  /**
+   * Begin listening.
+   *
+   * @returns Whether a new reactive watcher was started. `false` while the
+   * watcher is already active (including a null-target watcher with no
+   * listener attached), after the abort signal has fired, and after the
+   * owning reactive scope has been disposed.
+   */
+  readonly start: () => boolean;
+  /** Stop listening. Repeated calls are safe. */
+  readonly stop: () => void;
+}
+/**
+ * Attach an event listener to a reactive target and clean it up with the
+ * current reactive scope. Missing targets are valid during server rendering:
+ * a `null`/`undefined` target keeps the listener detached until a concrete
+ * target appears, so no browser globals are required.
+ *
+ * The listener is re-attached whenever the reactive target changes and is
+ * removed when the owning reactive scope stops, when
+ * {@link EventListenerControls.stop} is called, or when the abort signal
+ * fires. Outside an active scope, teardown ownership stays with the caller,
+ * who must call `stop` explicitly. Errors thrown by a custom target's
+ * add/remove methods propagate to the active watcher run.
+ *
+ * @param target Reactive event target.
+ * @param event Event name.
+ * @param listener Typed event listener.
+ * @param options Listener lifecycle and scheduling options.
+ * @default options {}
+ * @returns Controls to observe and change the listening state.
+ */
+declare function useEventListener<Key extends keyof WindowEventMap>(target: MaybeRefOrGetter<Window | null | undefined>, event: Key, listener: (event: WindowEventMap[Key]) => void, options?: UseEventListenerOptions): EventListenerControls;
+declare function useEventListener<Key extends keyof DocumentEventMap>(target: MaybeRefOrGetter<Document | null | undefined>, event: Key, listener: (event: DocumentEventMap[Key]) => void, options?: UseEventListenerOptions): EventListenerControls;
+declare function useEventListener<Key extends keyof HTMLElementEventMap>(target: MaybeRefOrGetter<HTMLElement | null | undefined>, event: Key, listener: (event: HTMLElementEventMap[Key]) => void, options?: UseEventListenerOptions): EventListenerControls;
+declare function useEventListener(target: MaybeRefOrGetter<EventTarget | null | undefined>, event: string, listener: EventListener, options?: UseEventListenerOptions): EventListenerControls;
+//#endregion
+export { EventListenerControls, UseEventListenerOptions, useEventListener };

package/dist/event-listener.mjs

@@ -0,0 +1,55 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { readonly, ref, 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;
+	const isListening = ref(false);
+	const eventOptions = {
+		capture,
+		passive,
+		...signal ? { signal } : {}
+	};
+	let disposed = false;
+	let stopWatch;
+	const stop = () => {
+		stopWatch?.stop();
+		stopWatch = void 0;
+		isListening.value = false;
+	};
+	const start = () => {
+		if (disposed || stopWatch || signal?.aborted) return false;
+		stopWatch = watch(() => toValue(target), (next, _previous, onCleanup) => {
+			isListening.value = false;
+			if (!next || signal?.aborted) return;
+			const invoke = (nativeEvent) => {
+				if (once) stop();
+				listener(nativeEvent);
+			};
+			const onAbort = () => stop();
+			next.addEventListener(event, invoke, eventOptions);
+			signal?.addEventListener("abort", onAbort, { once: true });
+			isListening.value = true;
+			onCleanup(() => {
+				next.removeEventListener(event, invoke, capture);
+				signal?.removeEventListener("abort", onAbort);
+				isListening.value = false;
+			});
+		}, {
+			flush,
+			immediate: true
+		});
+		return true;
+	};
+	tryOnScopeDispose(() => {
+		disposed = true;
+		stop();
+	});
+	if (immediate) start();
+	return {
+		isListening: readonly(isListening),
+		start,
+		stop
+	};
+}
+//#endregion
+export { useEventListener };