@vizejs/composable 0.426.3 → 0.427.0

package/dist/use-user-activation.d.mts

@@ -0,0 +1,83 @@
+import { n as IntervalScheduler } from "./use-interval-BA55gTHT.mjs";
+import { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/use-user-activation.d.ts
+/** Minimal `navigator.userActivation` (`UserActivation`). */
+interface UserActivationLike {
+  /** Whether the page ever had sticky activation. */
+  readonly hasBeenActive: boolean;
+  /** Whether the page currently has transient activation. */
+  readonly isActive: boolean;
+}
+/** Options for {@link useUserActivation}. */
+interface UseUserActivationOptions {
+  /**
+   * User activation state for alternate runtimes and tests.
+   *
+   * @default window.navigator.userActivation when it exists
+   */
+  readonly userActivation?: MaybeRefOrGetter<UserActivationLike | null | undefined>;
+  /**
+   * Target whose activation-triggering events refresh the state.
+   *
+   * @default window
+   */
+  readonly target?: MaybeRefOrGetter<EventTarget | null | undefined>;
+  /**
+   * Events that refresh the state.
+   *
+   * @default ["keydown", "mousedown", "pointerdown", "pointerup", "touchend"]
+   */
+  readonly events?: readonly string[];
+  /**
+   * Poll interval in milliseconds while `isActive` is true, so its expiry is
+   * observed. `0` disables polling.
+   *
+   * @default 1000
+   */
+  readonly interval?: number;
+  /**
+   * Timer host for polling.
+   *
+   * @default window timer functions
+   */
+  readonly scheduler?: IntervalScheduler;
+}
+/** Reactive state returned by {@link useUserActivation}. */
+interface UserActivationControls {
+  /** Whether the User Activation API is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Sticky activation: the user interacted with the page at least once. */
+  readonly hasBeenActive: Readonly<Ref<boolean>>;
+  /** Transient activation: a gated API (popup, fullscreen, clipboard) may be called now. */
+  readonly isActive: Readonly<Ref<boolean>>;
+  /** Re-read the activation state. */
+  readonly refresh: () => void;
+  /** Remove listeners and timers. Idempotent. */
+  readonly stop: () => void;
+}
+/**
+ * Track sticky and transient user activation with the User Activation API.
+ *
+ * The state is refreshed on activation-triggering events of `target`
+ * (immediately and again after a microtask) and polled while `isActive` is
+ * true so its expiry is observed. Listeners and the timer are removed when
+ * the owning reactive scope stops; outside a scope call `stop()`.
+ *
+ * Server rendering: no listeners or timers, `supported`, `hasBeenActive`,
+ * and `isActive` are false.
+ *
+ * @example
+ * ```ts
+ * const { isActive } = useUserActivation();
+ * const canOpenPopup = computed(() => isActive.value);
+ * ```
+ *
+ * @param options Capability host, event target, and polling policy.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_USER_ACTIVATION_INVALID_INTERVAL` when `interval` is negative or not finite.
+ * @returns Activation state.
+ */
+declare function useUserActivation(options?: UseUserActivationOptions): UserActivationControls;
+//#endregion
+export { UseUserActivationOptions, UserActivationControls, UserActivationLike, useUserActivation };

package/dist/use-user-activation.mjs

@@ -0,0 +1,113 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { computed, hasInjectionContext, readonly, ref, shallowRef, toValue, watch, watchPostEffect } from "vue";
+//#region src/use-user-activation.ts
+const defaultEvents = [
+	"keydown",
+	"mousedown",
+	"pointerdown",
+	"pointerup",
+	"touchend"
+];
+function isUserActivation(candidate) {
+	return typeof candidate === "object" && candidate !== null && "isActive" in candidate;
+}
+function browserUserActivation() {
+	if (typeof window === "undefined") return void 0;
+	const candidate = Reflect.get(window.navigator, "userActivation");
+	return isUserActivation(candidate) ? candidate : void 0;
+}
+function browserScheduler() {
+	if (typeof window === "undefined") return void 0;
+	return {
+		setInterval: (callback, intervalMs) => window.setInterval(callback, intervalMs),
+		clearInterval: (handle) => {
+			if (typeof handle === "number") window.clearInterval(handle);
+		}
+	};
+}
+/**
+* Track sticky and transient user activation with the User Activation API.
+*
+* The state is refreshed on activation-triggering events of `target`
+* (immediately and again after a microtask) and polled while `isActive` is
+* true so its expiry is observed. Listeners and the timer are removed when
+* the owning reactive scope stops; outside a scope call `stop()`.
+*
+* Server rendering: no listeners or timers, `supported`, `hasBeenActive`,
+* and `isActive` are false.
+*
+* @example
+* ```ts
+* const { isActive } = useUserActivation();
+* const canOpenPopup = computed(() => isActive.value);
+* ```
+*
+* @param options Capability host, event target, and polling policy.
+* @default options {}
+* @throws `RangeError` tagged `VIZE_COMPOSE_USER_ACTIVATION_INVALID_INTERVAL` when `interval` is negative or not finite.
+* @returns Activation state.
+*/
+function useUserActivation(options = {}) {
+	const interval = options.interval ?? 1e3;
+	if (!Number.isFinite(interval) || interval < 0) throw new RangeError(`[VIZE_COMPOSE_USER_ACTIVATION_INVALID_INTERVAL] interval must be a finite, non-negative number; received ${String(interval)}`);
+	const hasBeenActive = ref(false);
+	const isActive = ref(false);
+	let timer;
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const resolveHost = () => !hydrated.value ? void 0 : options.userActivation === void 0 ? browserUserActivation() : toValue(options.userActivation) ?? void 0;
+	const stopPolling = () => {
+		timer?.scheduler.clearInterval(timer.handle);
+		timer = void 0;
+	};
+	const refresh = () => {
+		const host = resolveHost();
+		hasBeenActive.value = host?.hasBeenActive ?? false;
+		isActive.value = host?.isActive ?? false;
+		if (!isActive.value) {
+			stopPolling();
+			return;
+		}
+		if (timer || interval === 0) return;
+		const scheduler = options.scheduler ?? browserScheduler();
+		if (scheduler) timer = {
+			scheduler,
+			handle: scheduler.setInterval(refresh, interval)
+		};
+	};
+	const onEvent = () => {
+		refresh();
+		Promise.resolve().then(refresh);
+	};
+	const stopWatch = watch(() => [options.target === void 0 ? typeof window === "undefined" ? void 0 : window : toValue(options.target) ?? void 0, resolveHost()], ([target, host], _previous, onCleanup) => {
+		if (host) refresh();
+		if (!target || !host) return;
+		const events = options.events ?? defaultEvents;
+		for (const type of events) target.addEventListener(type, onEvent, {
+			capture: true,
+			passive: true
+		});
+		onCleanup(() => {
+			for (const type of events) target.removeEventListener(type, onEvent, { capture: true });
+		});
+	}, {
+		immediate: true,
+		flush: "sync"
+	});
+	const stop = () => {
+		stopWatch();
+		stopPolling();
+	};
+	tryOnScopeDispose(stop);
+	return {
+		supported: computed(() => resolveHost() !== void 0),
+		hasBeenActive: readonly(hasBeenActive),
+		isActive: readonly(isActive),
+		refresh,
+		stop
+	};
+}
+//#endregion
+export { useUserActivation };

package/dist/use-user-media.d.mts

@@ -0,0 +1,194 @@
+import { ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+//#region src/use-user-media.d.ts
+/** Minimal `MediaStreamTrack`. */
+interface MediaStreamTrackLike extends EventTarget {
+  /** `"audio"` or `"video"`. */
+  readonly kind: string;
+  /** `"live"` or `"ended"`. */
+  readonly readyState: string;
+  /** Stop the track and release its device. */
+  stop(): void;
+}
+/** Minimal `MediaStream`. */
+interface MediaStreamLike {
+  /** Every track of the stream. */
+  getTracks(): readonly MediaStreamTrackLike[];
+}
+/** Anything that can asynchronously produce a media stream. */
+interface MediaStreamSource<Constraints> {
+  /** Acquire a stream; rejects with a DOMException on failure. */
+  request(constraints: Constraints): Promise<MediaStreamLike>;
+}
+/** Lifecycle state of a managed media stream. */
+type MediaStreamStatus = "idle" | "requesting" | "active" | "error";
+/** Normalized reason why a stream could not be acquired. */
+type MediaStreamErrorCode = "aborted" | "failed" | "invalid-constraints" | "not-found" | "not-readable" | "overconstrained" | "permission-denied" | "unsupported";
+/** Stream acquisition failure. */
+interface MediaStreamFailure {
+  /** Normalized reason. */
+  readonly code: MediaStreamErrorCode;
+  /** Exact error thrown by the source, when one was thrown. */
+  readonly cause: unknown;
+}
+/** Options for {@link useMediaStream}. */
+interface UseMediaStreamOptions<Constraints> {
+  /** Reactive stream source; `null`/`undefined` means unsupported. */
+  readonly source: MaybeRefOrGetter<MediaStreamSource<Constraints> | null | undefined>;
+  /** Reactive constraints passed to the source. */
+  readonly constraints: MaybeRefOrGetter<Constraints>;
+  /**
+   * Start while `true`, stop while `false`.
+   *
+   * @default false
+   */
+  readonly enabled?: MaybeRefOrGetter<boolean>;
+  /**
+   * Restart an active stream when the constraints change.
+   *
+   * @default true
+   */
+  readonly autoSwitch?: boolean;
+}
+/** Reactive state and actions of a managed media stream. */
+interface MediaStreamControls {
+  /** Whether a stream source is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** The active stream, if any. */
+  readonly stream: Readonly<ShallowRef<MediaStreamLike | undefined>>;
+  /** Lifecycle state. */
+  readonly status: Readonly<Ref<MediaStreamStatus>>;
+  /** Most recent acquisition failure, cleared by the next request. */
+  readonly error: Readonly<ShallowRef<MediaStreamFailure | undefined>>;
+  /**
+   * Acquire a stream unless one is active. Overlapping calls resolve to the
+   * newest stream; superseded streams are stopped immediately.
+   *
+   * @returns The active stream, or `undefined` on failure or supersession.
+   */
+  readonly start: () => Promise<MediaStreamLike | undefined>;
+  /** Stop every track and release the stream. Repeated calls are safe. */
+  readonly stop: () => void;
+  /**
+   * Stop and acquire a fresh stream with the current constraints.
+   *
+   * @returns The new stream, or `undefined` on failure or supersession.
+   */
+  readonly restart: () => Promise<MediaStreamLike | undefined>;
+}
+/**
+ * Manage the lifecycle of a media stream from any asynchronous source.
+ *
+ * This is the engine behind {@link useUserMedia} and `useDisplayMedia`, and
+ * can wrap any other stream producer (canvas capture, WebRTC). Acquisition
+ * failures are classified into {@link MediaStreamErrorCode}s; the stream
+ * returns to `"idle"` once all of its tracks ended (device unplugged, the
+ * user stopped screen sharing). Latest-wins: a stream that resolves after a
+ * newer request or a `stop` is stopped immediately. All tracks are stopped
+ * when the owning reactive scope stops.
+ *
+ * Server rendering: without a browser window a missing source keeps the
+ * status `"idle"` (no error), so server markup matches the first client
+ * render.
+ *
+ * @example
+ * ```ts
+ * const canvasStream = useMediaStream({
+ *   source: { request: async (fps: number) => canvas.captureStream(fps) },
+ *   constraints: 30,
+ * });
+ * ```
+ *
+ * @typeParam Constraints Constraint type accepted by the source.
+ * @param options Source, constraints, and activation.
+ * @returns Stream state and actions.
+ */
+declare function useMediaStream<Constraints>(options: UseMediaStreamOptions<Constraints>): MediaStreamControls;
+/** Minimal `MediaDeviceInfo`. */
+interface MediaDeviceInfoLike {
+  /** Device identifier. */
+  readonly deviceId: string;
+  /** `"audioinput"`, `"audiooutput"`, or `"videoinput"`. */
+  readonly kind: string;
+  /** Human-readable label (empty until permission is granted). */
+  readonly label: string;
+  /** Identifier shared by devices of one physical unit. */
+  readonly groupId: string;
+}
+/** Minimal `MediaDevices` consumed by {@link useUserMedia}. */
+interface UserMediaHost extends EventTarget {
+  /** Request camera/microphone access. */
+  getUserMedia(constraints?: MediaStreamConstraints): Promise<MediaStreamLike>;
+  /** List media devices. */
+  enumerateDevices?(): Promise<readonly MediaDeviceInfoLike[]>;
+}
+/** Options for {@link useUserMedia}. */
+interface UseUserMediaOptions {
+  /**
+   * Reactive constraints for `getUserMedia`.
+   *
+   * @default { audio: true, video: true }
+   */
+  readonly constraints?: MaybeRefOrGetter<MediaStreamConstraints>;
+  /**
+   * Start while `true`, stop while `false`.
+   *
+   * @default false
+   */
+  readonly enabled?: MaybeRefOrGetter<boolean>;
+  /**
+   * Restart an active stream when the constraints change.
+   *
+   * @default true
+   */
+  readonly autoSwitch?: boolean;
+  /**
+   * Keep `devices` current via `enumerateDevices` and `devicechange`.
+   *
+   * @default false
+   */
+  readonly listDevices?: boolean;
+  /**
+   * `MediaDevices` capability for alternate runtimes and tests.
+   *
+   * @default window.navigator.mediaDevices
+   */
+  readonly host?: MaybeRefOrGetter<UserMediaHost | null | undefined>;
+}
+/** Reactive state and actions returned by {@link useUserMedia}. */
+interface UserMediaControls extends MediaStreamControls {
+  /** Media devices, populated when `listDevices` is enabled. */
+  readonly devices: Readonly<ShallowRef<readonly MediaDeviceInfoLike[]>>;
+  /**
+   * Re-enumerate media devices.
+   *
+   * @returns The device list, empty when unsupported or on failure.
+   */
+  readonly refreshDevices: () => Promise<readonly MediaDeviceInfoLike[]>;
+}
+/**
+ * Access the camera and microphone with `getUserMedia`.
+ *
+ * Built on {@link useMediaStream}: reactive constraints (restarting an
+ * active stream when they change), `enabled` activation, classified
+ * failures such as `"permission-denied"`, and latest-wins requests. With
+ * `listDevices`, `devices` follows `devicechange`. Tracks and listeners are
+ * released when the owning reactive scope stops.
+ *
+ * Server rendering: no device is touched; `status` is `"idle"`, `stream` is
+ * undefined, and `supported` is false.
+ *
+ * @example
+ * ```ts
+ * const camera = useUserMedia({ constraints: { video: true, audio: false } });
+ * await camera.start();
+ * video.srcObject = camera.stream.value;
+ * ```
+ *
+ * @param options Constraints, activation, device listing, and capability.
+ * @default options {}
+ * @returns Stream state, device list, and actions.
+ */
+declare function useUserMedia(options?: UseUserMediaOptions): UserMediaControls;
+//#endregion
+export { MediaDeviceInfoLike, MediaStreamControls, MediaStreamErrorCode, MediaStreamFailure, MediaStreamLike, MediaStreamSource, MediaStreamStatus, MediaStreamTrackLike, UseMediaStreamOptions, UseUserMediaOptions, UserMediaControls, UserMediaHost, useMediaStream, useUserMedia };

package/dist/use-user-media.mjs

@@ -0,0 +1,214 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { computed, readonly, ref, shallowRef, toValue, watch } from "vue";
+//#region src/use-user-media.ts
+function errorName(error) {
+	return typeof error === "object" && error !== null && "name" in error ? String(error.name) : void 0;
+}
+function classify(error) {
+	switch (errorName(error)) {
+		case "NotAllowedError":
+		case "SecurityError": return "permission-denied";
+		case "NotFoundError": return "not-found";
+		case "NotReadableError": return "not-readable";
+		case "OverconstrainedError": return "overconstrained";
+		case "AbortError": return "aborted";
+		case "TypeError": return "invalid-constraints";
+		default: return "failed";
+	}
+}
+function stopTracks(stream) {
+	for (const track of stream.getTracks()) track.stop();
+}
+/**
+* Manage the lifecycle of a media stream from any asynchronous source.
+*
+* This is the engine behind {@link useUserMedia} and `useDisplayMedia`, and
+* can wrap any other stream producer (canvas capture, WebRTC). Acquisition
+* failures are classified into {@link MediaStreamErrorCode}s; the stream
+* returns to `"idle"` once all of its tracks ended (device unplugged, the
+* user stopped screen sharing). Latest-wins: a stream that resolves after a
+* newer request or a `stop` is stopped immediately. All tracks are stopped
+* when the owning reactive scope stops.
+*
+* Server rendering: without a browser window a missing source keeps the
+* status `"idle"` (no error), so server markup matches the first client
+* render.
+*
+* @example
+* ```ts
+* const canvasStream = useMediaStream({
+*   source: { request: async (fps: number) => canvas.captureStream(fps) },
+*   constraints: 30,
+* });
+* ```
+*
+* @typeParam Constraints Constraint type accepted by the source.
+* @param options Source, constraints, and activation.
+* @returns Stream state and actions.
+*/
+function useMediaStream(options) {
+	const stream = shallowRef(void 0);
+	const status = ref("idle");
+	const error = shallowRef(void 0);
+	let generation = 0;
+	let detach;
+	const resolveSource = () => toValue(options.source) ?? void 0;
+	const stop = () => {
+		generation += 1;
+		detach?.();
+		detach = void 0;
+		const current = stream.value;
+		stream.value = void 0;
+		if (current) stopTracks(current);
+		status.value = "idle";
+	};
+	const attach = (next) => {
+		const tracks = next.getTracks();
+		const onEnded = () => {
+			if (stream.value === next && tracks.every((track) => track.readyState === "ended")) stop();
+		};
+		for (const track of tracks) track.addEventListener("ended", onEnded);
+		detach = () => {
+			for (const track of tracks) track.removeEventListener("ended", onEnded);
+		};
+	};
+	const start = async () => {
+		if (status.value === "active" && stream.value) return stream.value;
+		const current = ++generation;
+		const source = resolveSource();
+		if (!source) {
+			if (typeof window !== "undefined") {
+				error.value = {
+					code: "unsupported",
+					cause: void 0
+				};
+				status.value = "error";
+			}
+			return;
+		}
+		error.value = void 0;
+		status.value = "requesting";
+		let next;
+		try {
+			next = await source.request(toValue(options.constraints));
+		} catch (cause) {
+			if (current === generation) {
+				error.value = {
+					code: classify(cause),
+					cause
+				};
+				status.value = "error";
+			}
+			return;
+		}
+		if (current !== generation) {
+			stopTracks(next);
+			return;
+		}
+		detach?.();
+		const previous = stream.value;
+		if (previous && previous !== next) stopTracks(previous);
+		stream.value = next;
+		attach(next);
+		status.value = "active";
+		return next;
+	};
+	const restart = async () => {
+		stop();
+		return start();
+	};
+	watch(() => toValue(options.enabled) ?? false, (enabled) => {
+		if (enabled) start();
+		else if (status.value !== "idle") stop();
+	}, { immediate: true });
+	watch(() => toValue(options.constraints), () => {
+		if ((options.autoSwitch ?? true) && status.value === "active") restart();
+	}, { deep: true });
+	tryOnScopeDispose(stop);
+	return {
+		supported: computed(() => resolveSource() !== void 0),
+		stream,
+		status: readonly(status),
+		error,
+		start,
+		stop,
+		restart
+	};
+}
+function browserUserMediaHost() {
+	if (typeof window === "undefined") return void 0;
+	return window.navigator.mediaDevices ?? void 0;
+}
+/**
+* Access the camera and microphone with `getUserMedia`.
+*
+* Built on {@link useMediaStream}: reactive constraints (restarting an
+* active stream when they change), `enabled` activation, classified
+* failures such as `"permission-denied"`, and latest-wins requests. With
+* `listDevices`, `devices` follows `devicechange`. Tracks and listeners are
+* released when the owning reactive scope stops.
+*
+* Server rendering: no device is touched; `status` is `"idle"`, `stream` is
+* undefined, and `supported` is false.
+*
+* @example
+* ```ts
+* const camera = useUserMedia({ constraints: { video: true, audio: false } });
+* await camera.start();
+* video.srcObject = camera.stream.value;
+* ```
+*
+* @param options Constraints, activation, device listing, and capability.
+* @default options {}
+* @returns Stream state, device list, and actions.
+*/
+function useUserMedia(options = {}) {
+	const resolveHost = () => options.host === void 0 ? browserUserMediaHost() : toValue(options.host) ?? void 0;
+	const devices = shallowRef([]);
+	const controls = useMediaStream({
+		source: () => {
+			const host = resolveHost();
+			return host ? { request: (constraints) => host.getUserMedia(constraints) } : void 0;
+		},
+		constraints: () => toValue(options.constraints) ?? {
+			audio: true,
+			video: true
+		},
+		enabled: () => toValue(options.enabled) ?? false,
+		autoSwitch: options.autoSwitch ?? true
+	});
+	const refreshDevices = async () => {
+		const host = resolveHost();
+		if (!host?.enumerateDevices) return devices.value = [];
+		try {
+			devices.value = [...await host.enumerateDevices()];
+		} catch {
+			devices.value = [];
+		}
+		return devices.value;
+	};
+	if (options.listDevices ?? false) {
+		watch(resolveHost, (host, _previous, onCleanup) => {
+			if (!host) return;
+			const update = () => {
+				refreshDevices();
+			};
+			update();
+			host.addEventListener("devicechange", update);
+			onCleanup(() => host.removeEventListener("devicechange", update));
+		}, {
+			immediate: true,
+			flush: "sync"
+		});
+		watch(controls.status, (status) => {
+			if (status === "active") refreshDevices();
+		});
+	}
+	return {
+		...controls,
+		devices,
+		refreshDevices
+	};
+}
+//#endregion
+export { useMediaStream, useUserMedia };