@vizejs/composable 0.426.3 → 0.428.0

package/dist/network.d.mts

@@ -0,0 +1,96 @@
+import { MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/network.d.ts
+/** Effective connection classes reported by the Network Information API. */
+type NetworkEffectiveType = "slow-2g" | "2g" | "3g" | "4g";
+/** Physical connection types reported by the Network Information API. */
+type NetworkConnectionType = "bluetooth" | "cellular" | "ethernet" | "none" | "wifi" | "wimax" | "other" | "unknown";
+/** Subset of the (non-standard) `NetworkInformation` interface. */
+interface NetworkInformationLike extends EventTarget {
+  /** Estimated downlink bandwidth in Mbit/s. */
+  readonly downlink?: number;
+  /** Maximum downlink bandwidth in Mbit/s. */
+  readonly downlinkMax?: number;
+  /** Effective connection class. */
+  readonly effectiveType?: string;
+  /** Estimated round-trip time in milliseconds. */
+  readonly rtt?: number;
+  /** Whether the user requested reduced data usage. */
+  readonly saveData?: boolean;
+  /** Physical connection type. */
+  readonly type?: string;
+}
+/** Window-like capability observed by the network composables. */
+interface NetworkHost extends EventTarget {
+  /** Navigator exposing connectivity. */
+  readonly navigator: {
+    /** Whether the browser believes it is online. */readonly onLine: boolean; /** Network Information API object, where supported. */
+    readonly connection?: NetworkInformationLike;
+  };
+}
+/** Options shared by {@link useOnline} and {@link useNetwork}. */
+interface UseNetworkOptions {
+  /**
+   * Connectivity exposed during server rendering.
+   *
+   * @default true
+   */
+  readonly ssrOnline?: boolean;
+  /**
+   * Reactive window capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<NetworkHost | null | undefined>;
+}
+/** Reactive network state returned by {@link useNetwork}. */
+interface NetworkControls {
+  /** Whether the Network Information API is available. `false` during server rendering. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+  /** Whether the browser reports being online. */
+  readonly isOnline: Readonly<Ref<boolean>>;
+  /** Epoch milliseconds of the latest `online` event. */
+  readonly onlineAt: Readonly<Ref<number | null>>;
+  /** Epoch milliseconds of the latest `offline` event. */
+  readonly offlineAt: Readonly<Ref<number | null>>;
+  /** Estimated downlink in Mbit/s. */
+  readonly downlink: Readonly<Ref<number | null>>;
+  /** Maximum downlink in Mbit/s. */
+  readonly downlinkMax: Readonly<Ref<number | null>>;
+  /** Effective connection class, or `null` when unknown. */
+  readonly effectiveType: Readonly<Ref<NetworkEffectiveType | null>>;
+  /** Estimated round-trip time in milliseconds. */
+  readonly rtt: Readonly<Ref<number | null>>;
+  /** Whether the user requested reduced data usage. */
+  readonly saveData: Readonly<Ref<boolean>>;
+  /** Physical connection type, or `null` when unknown. */
+  readonly type: Readonly<Ref<NetworkConnectionType | null>>;
+}
+/**
+ * Track connectivity and connection quality.
+ *
+ * Listens for `online`/`offline` on the window and `change` on
+ * `navigator.connection` where available. Unknown or future enum values
+ * normalize to `null` so the public unions stay closed. Server renders
+ * report `ssrOnline` with every quality metric `null`. Inside a component
+ * the connection is read after mounting, so hydration renders the server
+ * values first. Listeners are removed with the owning reactive scope.
+ *
+ * @param options Server fallback and window capability.
+ * @default options {}
+ * @returns Reactive connectivity and connection metrics.
+ */
+declare function useNetwork(options?: UseNetworkOptions): NetworkControls;
+/**
+ * Track whether the browser reports being online.
+ *
+ * Shorthand for `useNetwork(options).isOnline` with the same SSR fallback
+ * and cleanup semantics.
+ *
+ * @param options Server fallback and window capability.
+ * @default options {}
+ * @returns Readonly online flag.
+ */
+declare function useOnline(options?: UseNetworkOptions): Readonly<Ref<boolean>>;
+//#endregion
+export { NetworkConnectionType, NetworkControls, NetworkEffectiveType, NetworkHost, NetworkInformationLike, UseNetworkOptions, useNetwork, useOnline };

package/dist/network.mjs

@@ -0,0 +1,117 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { hasInjectionContext, readonly, ref, shallowRef, toValue, watch, watchPostEffect } from "vue";
+//#region src/network.ts
+/**
+* Track connectivity and connection quality.
+*
+* Listens for `online`/`offline` on the window and `change` on
+* `navigator.connection` where available. Unknown or future enum values
+* normalize to `null` so the public unions stay closed. Server renders
+* report `ssrOnline` with every quality metric `null`. Inside a component
+* the connection is read after mounting, so hydration renders the server
+* values first. Listeners are removed with the owning reactive scope.
+*
+* @param options Server fallback and window capability.
+* @default options {}
+* @returns Reactive connectivity and connection metrics.
+*/
+function useNetwork(options = {}) {
+	const ssrOnline = options.ssrOnline ?? true;
+	const isSupported = ref(false);
+	const isOnline = ref(ssrOnline);
+	const onlineAt = ref(null);
+	const offlineAt = ref(null);
+	const downlink = ref(null);
+	const downlinkMax = ref(null);
+	const effectiveType = ref(null);
+	const rtt = ref(null);
+	const saveData = ref(false);
+	const type = ref(null);
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const stop = watch(() => hydrated.value ? options.host === void 0 ? browserNetworkHost() : toValue(options.host) : void 0, (host, _previous, onCleanup) => {
+		if (!host) {
+			isSupported.value = false;
+			isOnline.value = ssrOnline;
+			return;
+		}
+		const connection = host.navigator.connection;
+		isSupported.value = connection !== void 0;
+		const readConnection = () => {
+			isOnline.value = host.navigator.onLine;
+			if (!connection) return;
+			downlink.value = connection.downlink ?? null;
+			downlinkMax.value = connection.downlinkMax ?? null;
+			effectiveType.value = toEffectiveType(connection.effectiveType);
+			rtt.value = connection.rtt ?? null;
+			saveData.value = connection.saveData ?? false;
+			type.value = toConnectionType(connection.type);
+		};
+		const onOnline = () => {
+			onlineAt.value = Date.now();
+			readConnection();
+		};
+		const onOffline = () => {
+			offlineAt.value = Date.now();
+			readConnection();
+		};
+		readConnection();
+		host.addEventListener("online", onOnline, { passive: true });
+		host.addEventListener("offline", onOffline, { passive: true });
+		connection?.addEventListener("change", readConnection, { passive: true });
+		onCleanup(() => {
+			host.removeEventListener("online", onOnline);
+			host.removeEventListener("offline", onOffline);
+			connection?.removeEventListener("change", readConnection);
+		});
+	}, { immediate: true });
+	tryOnScopeDispose(() => stop.stop());
+	return {
+		isSupported: readonly(isSupported),
+		isOnline: readonly(isOnline),
+		onlineAt: readonly(onlineAt),
+		offlineAt: readonly(offlineAt),
+		downlink: readonly(downlink),
+		downlinkMax: readonly(downlinkMax),
+		effectiveType: readonly(effectiveType),
+		rtt: readonly(rtt),
+		saveData: readonly(saveData),
+		type: readonly(type)
+	};
+}
+/**
+* Track whether the browser reports being online.
+*
+* Shorthand for `useNetwork(options).isOnline` with the same SSR fallback
+* and cleanup semantics.
+*
+* @param options Server fallback and window capability.
+* @default options {}
+* @returns Readonly online flag.
+*/
+function useOnline(options = {}) {
+	return useNetwork(options).isOnline;
+}
+function toEffectiveType(value) {
+	return value === "slow-2g" || value === "2g" || value === "3g" || value === "4g" ? value : null;
+}
+function toConnectionType(value) {
+	switch (value) {
+		case "bluetooth":
+		case "cellular":
+		case "ethernet":
+		case "none":
+		case "wifi":
+		case "wimax":
+		case "other":
+		case "unknown": return value;
+		default: return null;
+	}
+}
+function browserNetworkHost() {
+	return typeof window !== "undefined" ? window : void 0;
+}
+//#endregion
+export { useNetwork, useOnline };

package/dist/on-click-outside.d.mts

@@ -0,0 +1,69 @@
+import { t as TimeoutScheduler } from "./timeout-scheduler-CI8RVLZs.mjs";
+import { n as MaybeElementTarget } from "./element-target-Crpxl4D9.mjs";
+import { MaybeRefOrGetter } from "vue";
+
+//#region src/on-click-outside.d.ts
+/** Window-like capability observed by {@link onClickOutside}. */
+interface ClickOutsideHost extends EventTarget {
+  /** Document used to detect focus moving into an iframe. */
+  readonly document: {
+    readonly activeElement: Element | null;
+  };
+}
+/** Ignore entry: an element target or a CSS selector matched against the event path. */
+type ClickOutsideIgnore = MaybeElementTarget | string;
+/** Options for {@link onClickOutside}. */
+interface OnClickOutsideOptions {
+  /**
+   * Elements (or selectors) whose clicks never count as outside, e.g. the
+   * button that toggles a popover.
+   *
+   * @default []
+   */
+  readonly ignore?: MaybeRefOrGetter<readonly ClickOutsideIgnore[]>;
+  /**
+   * Listen in the capture phase so `stopPropagation()` inside the page
+   * cannot hide outside clicks.
+   *
+   * @default true
+   */
+  readonly capture?: boolean;
+  /**
+   * Treat focus moving into an `<iframe>` outside the target as an outside
+   * click (iframes swallow pointer events).
+   *
+   * @default false
+   */
+  readonly detectIframe?: boolean;
+  /**
+   * Owns the zero-delay timer used for iframe detection.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+  /**
+   * Reactive window capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<ClickOutsideHost | null | undefined>;
+}
+/**
+ * Call a handler when the user clicks (or focuses an iframe) outside an element.
+ *
+ * A click counts as outside only when its `pointerdown` also started outside
+ * the target, so drags that begin inside (e.g. text selection) and end
+ * outside are ignored. Event paths (`composedPath()`) make shadow-DOM targets
+ * work. The host is resolved once, when called. Nothing is registered
+ * during server rendering; listeners are removed with the owning scope or by
+ * the returned stop function.
+ *
+ * @param target Reactive element target.
+ * @param handler Called with the outside `PointerEvent`/`MouseEvent` or `FocusEvent`.
+ * @param options Ignore list, phase, iframe detection, and capabilities.
+ * @default options {}
+ * @returns Stop function.
+ */
+declare function onClickOutside(target: MaybeElementTarget, handler: (event: Event) => void, options?: OnClickOutsideOptions): () => void;
+//#endregion
+export { ClickOutsideHost, ClickOutsideIgnore, OnClickOutsideOptions, onClickOutside };

package/dist/on-click-outside.mjs

@@ -0,0 +1,115 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { resolveElement } from "./element-target.mjs";
+import { toValue } from "vue";
+//#region src/on-click-outside.ts
+const defaultScheduler = {
+	setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+	clearTimeout: (handle) => {
+		globalThis.clearTimeout(handle);
+	}
+};
+/**
+* Call a handler when the user clicks (or focuses an iframe) outside an element.
+*
+* A click counts as outside only when its `pointerdown` also started outside
+* the target, so drags that begin inside (e.g. text selection) and end
+* outside are ignored. Event paths (`composedPath()`) make shadow-DOM targets
+* work. The host is resolved once, when called. Nothing is registered
+* during server rendering; listeners are removed with the owning scope or by
+* the returned stop function.
+*
+* @param target Reactive element target.
+* @param handler Called with the outside `PointerEvent`/`MouseEvent` or `FocusEvent`.
+* @param options Ignore list, phase, iframe detection, and capabilities.
+* @default options {}
+* @returns Stop function.
+*/
+function onClickOutside(target, handler, options = {}) {
+	const host = options.host === void 0 ? browserClickHost() : toValue(options.host);
+	if (!host) return () => void 0;
+	const capture = options.capture ?? true;
+	const scheduler = options.scheduler ?? defaultScheduler;
+	let startedInside = false;
+	let pendingBlur;
+	let hasPendingBlur = false;
+	const pathOf = (event) => {
+		const path = typeof event.composedPath === "function" ? event.composedPath() : [];
+		return path.length > 0 ? path : event.target ? [event.target] : [];
+	};
+	const isIgnored = (event) => {
+		const path = pathOf(event);
+		for (const entry of toValue(options.ignore) ?? []) {
+			if (typeof entry === "string") {
+				if (path.some((node) => matchesSelector(node, entry))) return true;
+				continue;
+			}
+			const element = resolveElement(entry);
+			if (element && path.some((node) => node === element || containsNode(element, node))) return true;
+		}
+		return false;
+	};
+	const isInside = (event) => {
+		const element = resolveElement(target);
+		if (!element) return true;
+		return pathOf(event).some((node) => node === element || containsNode(element, node));
+	};
+	const onPointerDown = (event) => {
+		startedInside = isInside(event) || isIgnored(event);
+	};
+	const onClick = (event) => {
+		const inside = isInside(event) || isIgnored(event);
+		const began = startedInside;
+		startedInside = false;
+		if (inside || began) return;
+		handler(event);
+	};
+	const onBlur = (event) => {
+		if (hasPendingBlur) scheduler.clearTimeout(pendingBlur);
+		hasPendingBlur = true;
+		pendingBlur = scheduler.setTimeout(() => {
+			hasPendingBlur = false;
+			const active = host.document.activeElement;
+			const element = resolveElement(target);
+			if (active?.tagName === "IFRAME" && element && !containsNode(element, active)) handler(event);
+		}, 0);
+	};
+	host.addEventListener("pointerdown", onPointerDown, {
+		capture,
+		passive: true
+	});
+	host.addEventListener("click", onClick, {
+		capture,
+		passive: true
+	});
+	if (options.detectIframe) host.addEventListener("blur", onBlur);
+	let stopped = false;
+	const stop = () => {
+		if (stopped) return;
+		stopped = true;
+		host.removeEventListener("pointerdown", onPointerDown, { capture });
+		host.removeEventListener("click", onClick, { capture });
+		host.removeEventListener("blur", onBlur);
+		if (hasPendingBlur) scheduler.clearTimeout(pendingBlur);
+	};
+	tryOnScopeDispose(stop);
+	return stop;
+}
+function containsNode(element, node) {
+	return typeof element.contains === "function" && isNodeLike(node) && element.contains(node);
+}
+function isNodeLike(value) {
+	return "nodeType" in value;
+}
+function matchesSelector(node, selector) {
+	if (!("matches" in node) || typeof node.matches !== "function") return false;
+	try {
+		return node.matches(selector) === true;
+	} catch {
+		return false;
+	}
+}
+function browserClickHost() {
+	return typeof window !== "undefined" ? window : void 0;
+}
+//#endregion
+export { onClickOutside };

package/dist/on-key-stroke.d.mts

@@ -0,0 +1,71 @@
+import { KeyFilter } from "./magic-keys.mjs";
+import { MaybeRefOrGetter } from "vue";
+
+//#region src/on-key-stroke.d.ts
+/** Keyboard event names accepted by {@link onKeyStroke}. */
+type KeyStrokeEventName = "keydown" | "keyup" | "keypress";
+/** Options for {@link onKeyStroke}. */
+interface OnKeyStrokeOptions {
+  /**
+   * Keyboard event to listen for.
+   *
+   * @default "keydown"
+   */
+  readonly eventName?: KeyStrokeEventName;
+  /**
+   * Event target.
+   *
+   * @default globalThis.window when available
+   */
+  readonly target?: MaybeRefOrGetter<EventTarget | null | undefined>;
+  /**
+   * Register a passive listener (the handler then cannot `preventDefault()`).
+   *
+   * @default false
+   */
+  readonly passive?: boolean;
+  /**
+   * Ignore auto-repeated `keydown` events while a key is held.
+   *
+   * @default false
+   */
+  readonly dedupe?: MaybeRefOrGetter<boolean>;
+}
+/**
+ * Run a handler when matching keys are pressed.
+ *
+ * `key` accepts a name, a list of names (normalized like combos, so `"esc"`
+ * matches `Escape` and `"a"` matches `KeyA`), a predicate, or `true` for every
+ * key. The listener follows the reactive target and is removed with the
+ * owning scope or the returned stop function; nothing is registered during
+ * server rendering.
+ *
+ * @param key Key filter, or `true` for any key.
+ * @param handler Called with the matching `KeyboardEvent`.
+ * @param options Event name, target, passivity, and dedupe.
+ * @default options {}
+ * @returns Stop function.
+ */
+declare function onKeyStroke(key: KeyFilter | true, handler: (event: KeyboardEvent) => void, options?: OnKeyStrokeOptions): () => void;
+/**
+ * {@link onKeyStroke} for `keydown`.
+ *
+ * @param key Key filter, or `true` for any key.
+ * @param handler Called with the matching `KeyboardEvent`.
+ * @param options Target, passivity, and dedupe.
+ * @default options {}
+ * @returns Stop function.
+ */
+declare function onKeyDown(key: KeyFilter | true, handler: (event: KeyboardEvent) => void, options?: Omit<OnKeyStrokeOptions, "eventName">): () => void;
+/**
+ * {@link onKeyStroke} for `keyup`.
+ *
+ * @param key Key filter, or `true` for any key.
+ * @param handler Called with the matching `KeyboardEvent`.
+ * @param options Target, passivity, and dedupe.
+ * @default options {}
+ * @returns Stop function.
+ */
+declare function onKeyUp(key: KeyFilter | true, handler: (event: KeyboardEvent) => void, options?: Omit<OnKeyStrokeOptions, "eventName">): () => void;
+//#endregion
+export { KeyStrokeEventName, OnKeyStrokeOptions, onKeyDown, onKeyStroke, onKeyUp };

package/dist/on-key-stroke.mjs

@@ -0,0 +1,79 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { normalizeKeyName } from "./magic-keys.mjs";
+import { toValue, watch } from "vue";
+//#region src/on-key-stroke.ts
+/**
+* Run a handler when matching keys are pressed.
+*
+* `key` accepts a name, a list of names (normalized like combos, so `"esc"`
+* matches `Escape` and `"a"` matches `KeyA`), a predicate, or `true` for every
+* key. The listener follows the reactive target and is removed with the
+* owning scope or the returned stop function; nothing is registered during
+* server rendering.
+*
+* @param key Key filter, or `true` for any key.
+* @param handler Called with the matching `KeyboardEvent`.
+* @param options Event name, target, passivity, and dedupe.
+* @default options {}
+* @returns Stop function.
+*/
+function onKeyStroke(key, handler, options = {}) {
+	const eventName = options.eventName ?? "keydown";
+	const names = key === true || typeof key === "function" ? void 0 : new Set((typeof key === "string" ? [key] : key).map((name) => normalizeKeyName(name)));
+	const matches = (event) => {
+		if (key === true) return true;
+		if (typeof key === "function") return key(event);
+		return names !== void 0 && (names.has(normalizeKeyName(event.key)) || names.has(normalizeKeyName(event.code)));
+	};
+	const listener = (event) => {
+		if (!isKeyboardEvent(event)) return;
+		if (event.repeat && toValue(options.dedupe)) return;
+		if (matches(event)) handler(event);
+	};
+	const stop = watch(() => options.target === void 0 ? browserWindow() : toValue(options.target), (target, _previous, onCleanup) => {
+		if (!target) return;
+		target.addEventListener(eventName, listener, { passive: options.passive ?? false });
+		onCleanup(() => target.removeEventListener(eventName, listener));
+	}, { immediate: true });
+	const dispose = () => stop.stop();
+	tryOnScopeDispose(dispose);
+	return dispose;
+}
+/**
+* {@link onKeyStroke} for `keydown`.
+*
+* @param key Key filter, or `true` for any key.
+* @param handler Called with the matching `KeyboardEvent`.
+* @param options Target, passivity, and dedupe.
+* @default options {}
+* @returns Stop function.
+*/
+function onKeyDown(key, handler, options = {}) {
+	return onKeyStroke(key, handler, {
+		...options,
+		eventName: "keydown"
+	});
+}
+/**
+* {@link onKeyStroke} for `keyup`.
+*
+* @param key Key filter, or `true` for any key.
+* @param handler Called with the matching `KeyboardEvent`.
+* @param options Target, passivity, and dedupe.
+* @default options {}
+* @returns Stop function.
+*/
+function onKeyUp(key, handler, options = {}) {
+	return onKeyStroke(key, handler, {
+		...options,
+		eventName: "keyup"
+	});
+}
+function isKeyboardEvent(event) {
+	return "key" in event && "code" in event;
+}
+function browserWindow() {
+	return typeof window !== "undefined" ? window : void 0;
+}
+//#endregion
+export { onKeyDown, onKeyStroke, onKeyUp };

package/dist/on-long-press.d.mts

@@ -0,0 +1,82 @@
+import { t as TimeoutScheduler } from "./timeout-scheduler-CI8RVLZs.mjs";
+import { n as MaybeElementTarget } from "./element-target-Crpxl4D9.mjs";
+
+//#region src/on-long-press.d.ts
+/** Event modifiers applied to the pointer events handled by {@link onLongPress}. */
+interface LongPressModifiers {
+  /** Call `stopPropagation()`. */
+  readonly stop?: boolean;
+  /** Fire at most once. */
+  readonly once?: boolean;
+  /** Call `preventDefault()`. */
+  readonly prevent?: boolean;
+  /** Listen in the capture phase. */
+  readonly capture?: boolean;
+  /** Only start when the element itself (not a descendant) is pressed. */
+  readonly self?: boolean;
+}
+/** Summary passed to {@link OnLongPressOptions.onRelease}. */
+interface LongPressRelease {
+  /** Milliseconds between press and release. */
+  readonly duration: number;
+  /** Pointer travel in CSS pixels. */
+  readonly distance: number;
+  /** Whether the long-press handler fired. */
+  readonly isLongPress: boolean;
+}
+/** Options for {@link onLongPress}. */
+interface OnLongPressOptions {
+  /**
+   * Hold time in milliseconds.
+   *
+   * @default 500
+   */
+  readonly delay?: number;
+  /**
+   * Maximum pointer travel before the press is cancelled.
+   *
+   * @default 10
+   */
+  readonly distanceThreshold?: number;
+  /**
+   * Event modifiers.
+   *
+   * @default {}
+   */
+  readonly modifiers?: LongPressModifiers;
+  /**
+   * Called on every release with timing details.
+   *
+   * @default undefined
+   */
+  readonly onRelease?: (release: LongPressRelease, event: PointerEvent) => void;
+  /**
+   * Clock for durations.
+   *
+   * @default Date.now
+   */
+  readonly now?: () => number;
+  /**
+   * Owns the hold timer.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+}
+/**
+ * Call a handler when an element is pressed and held.
+ *
+ * Uses Pointer Events, so mouse, touch, and pen behave alike. Moving more than
+ * `distanceThreshold` or releasing early cancels the press. Nothing is
+ * registered during server rendering; listeners and the timer are released
+ * with the owning scope or the returned stop function.
+ *
+ * @param target Reactive element target.
+ * @param handler Called with the initiating `pointerdown` event.
+ * @param options Delay, threshold, modifiers, and callbacks.
+ * @default options {}
+ * @returns Stop function.
+ */
+declare function onLongPress(target: MaybeElementTarget, handler: (event: PointerEvent) => void, options?: OnLongPressOptions): () => void;
+//#endregion
+export { LongPressModifiers, LongPressRelease, OnLongPressOptions, onLongPress };