@vizejs/composable 0.426.3 → 0.427.0

package/dist/use-visual-viewport.mjs

@@ -0,0 +1,104 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { computed, hasInjectionContext, readonly, ref, shallowRef, toValue, watch, watchPostEffect } from "vue";
+//#region src/use-visual-viewport.ts
+/**
+* Track the visual viewport and on-screen keyboard.
+*
+* On mobile browsers the visual viewport shrinks (or scrolls) when a virtual
+* keyboard opens while the layout viewport stays put; `keyboardHeight` is the
+* occluded bottom area (`innerHeight - height - offsetTop`), or the
+* VirtualKeyboard API rectangle when `overlaysContent` is enabled. Pin
+* toolbars above the keyboard with `bottom: calc(var(--kb, 0px))` bound to it.
+*
+* Server rendering reports zeros (scale 1) and attaches nothing; inside a
+* component the host attaches after mount, so hydration renders the same
+* zeros first. Listeners
+* (`resize`, `scroll`, `geometrychange`) are passive and removed with the
+* owning reactive scope.
+*
+* @example
+* ```ts
+* const { keyboardHeight, keyboardOpen } = useVisualViewport();
+* const toolbarStyle = computed(() => ({ bottom: `${keyboardHeight.value}px` }));
+* ```
+*
+* @param options Keyboard threshold, VirtualKeyboard opt-in, and capability.
+* @default options {}
+* @returns Reactive viewport geometry and keyboard state.
+*/
+function useVisualViewport(options = {}) {
+	const threshold = typeof options.keyboardThreshold === "number" && Number.isFinite(options.keyboardThreshold) ? Math.max(options.keyboardThreshold, 0) : 120;
+	const width = ref(0);
+	const height = ref(0);
+	const offsetTop = ref(0);
+	const offsetLeft = ref(0);
+	const scale = ref(1);
+	const keyboardHeight = ref(0);
+	const isSupported = ref(false);
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const stopWatch = watch(() => !hydrated.value ? void 0 : options.host === void 0 ? browserViewportHost() : toValue(options.host), (host, _previous, onCleanup) => {
+		const viewport = host?.visualViewport ?? void 0;
+		const keyboard = options.overlaysContent === true ? virtualKeyboardOf(host?.navigator) : void 0;
+		isSupported.value = viewport !== void 0 || keyboard !== void 0;
+		if (host === null || host === void 0 || !isSupported.value) {
+			width.value = 0;
+			height.value = 0;
+			offsetTop.value = 0;
+			offsetLeft.value = 0;
+			scale.value = 1;
+			keyboardHeight.value = 0;
+			return;
+		}
+		const previousOverlay = keyboard?.overlaysContent;
+		if (keyboard !== void 0) keyboard.overlaysContent = true;
+		const update = () => {
+			if (viewport !== void 0) {
+				width.value = viewport.width;
+				height.value = viewport.height;
+				offsetTop.value = viewport.offsetTop;
+				offsetLeft.value = viewport.offsetLeft;
+				scale.value = viewport.scale;
+			}
+			const occluded = keyboard !== void 0 ? keyboard.boundingRect.height : viewport === void 0 ? 0 : host.innerHeight - viewport.height - viewport.offsetTop;
+			keyboardHeight.value = Math.max(Math.round(occluded), 0);
+		};
+		update();
+		const passive = { passive: true };
+		viewport?.addEventListener("resize", update, passive);
+		viewport?.addEventListener("scroll", update, passive);
+		keyboard?.addEventListener("geometrychange", update, passive);
+		onCleanup(() => {
+			viewport?.removeEventListener("resize", update);
+			viewport?.removeEventListener("scroll", update);
+			keyboard?.removeEventListener("geometrychange", update);
+			if (keyboard !== void 0 && previousOverlay !== void 0) keyboard.overlaysContent = previousOverlay;
+		});
+	}, { immediate: true });
+	tryOnScopeDispose(() => stopWatch.stop());
+	return {
+		width: readonly(width),
+		height: readonly(height),
+		offsetTop: readonly(offsetTop),
+		offsetLeft: readonly(offsetLeft),
+		scale: readonly(scale),
+		keyboardHeight: readonly(keyboardHeight),
+		keyboardOpen: computed(() => keyboardHeight.value > threshold),
+		isSupported: readonly(isSupported)
+	};
+}
+function browserViewportHost() {
+	return typeof window !== "undefined" ? window : void 0;
+}
+function isVirtualKeyboard(value) {
+	return typeof value === "object" && value !== null && "overlaysContent" in value && "boundingRect" in value && typeof Reflect.get(value, "addEventListener") === "function";
+}
+function virtualKeyboardOf(navigator) {
+	if (navigator === void 0 || !("virtualKeyboard" in navigator)) return void 0;
+	const keyboard = navigator.virtualKeyboard;
+	return isVirtualKeyboard(keyboard) ? keyboard : void 0;
+}
+//#endregion
+export { useVisualViewport };

package/dist/use-wake-lock.d.mts

@@ -0,0 +1,96 @@
+import { ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+//#region src/use-wake-lock.d.ts
+/** Wake lock types defined by the Screen Wake Lock API. */
+type WakeLockKind = "screen";
+/** Minimal `WakeLockSentinel` consumed by {@link useWakeLock}. */
+interface WakeLockSentinelLike extends EventTarget {
+  /** Whether the platform already released this lock. */
+  readonly released: boolean;
+  /** Release the lock. */
+  release(): Promise<void>;
+}
+/** Capabilities used by {@link useWakeLock}. */
+interface WakeLockHost {
+  /** Screen Wake Lock API (`navigator.wakeLock`). */
+  readonly wakeLock: {
+    /** Request a lock of `type`. */request(type: WakeLockKind): Promise<WakeLockSentinelLike>;
+  };
+  /**
+   * Document whose `visibilitychange` re-acquires a lock the platform
+   * released while the page was hidden.
+   */
+  readonly document?: {
+    /** Current visibility. */readonly visibilityState: string; /** Subscribe to `visibilitychange`. */
+    addEventListener(type: "visibilitychange", listener: () => void): void; /** Unsubscribe from `visibilitychange`. */
+    removeEventListener(type: "visibilitychange", listener: () => void): void;
+  } | null;
+}
+/** Options for {@link useWakeLock}. */
+interface UseWakeLockOptions {
+  /**
+   * Wake Lock capability for alternate runtimes and tests.
+   *
+   * @default window.navigator and window.document when `navigator.wakeLock` exists
+   */
+  readonly host?: MaybeRefOrGetter<WakeLockHost | null | undefined>;
+  /**
+   * Re-acquire a requested lock when the page becomes visible again (the
+   * platform releases screen locks whenever the page is hidden).
+   *
+   * @default true
+   */
+  readonly reacquireOnVisible?: boolean;
+}
+/** Reactive state and actions returned by {@link useWakeLock}. */
+interface WakeLockControls {
+  /** Whether the Screen Wake Lock API is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Whether a lock is currently held. */
+  readonly active: Readonly<Ref<boolean>>;
+  /**
+   * Whether the caller wants a lock: set by `request`, cleared by `release`.
+   * While requested, the lock is re-acquired after visibility returns.
+   */
+  readonly requested: Readonly<Ref<boolean>>;
+  /** Most recent request failure (for example NotAllowedError), cleared on success. */
+  readonly error: Readonly<ShallowRef<unknown>>;
+  /**
+   * Request a wake lock.
+   *
+   * @param type Lock type.
+   * @default type "screen"
+   * @returns Whether a lock is held afterwards.
+   */
+  readonly request: (type?: WakeLockKind) => Promise<boolean>;
+  /**
+   * Release the lock and stop re-acquiring it. Repeated calls are safe.
+   *
+   * @returns Resolves once the lock was released.
+   */
+  readonly release: () => Promise<void>;
+}
+/**
+ * Keep the screen awake with the Screen Wake Lock API.
+ *
+ * Browsers release screen locks when the page is hidden; while a lock is
+ * `requested`, it is re-acquired on the next `visibilitychange` to visible.
+ * Request failures (missing user activation, battery saver) are exposed
+ * through `error` rather than thrown. The lock and the visibility listener
+ * are released when the owning reactive scope stops.
+ *
+ * Server rendering: nothing is requested, `supported` and `active` are false.
+ *
+ * @example
+ * ```ts
+ * const wakeLock = useWakeLock();
+ * const startPresentation = () => wakeLock.request();
+ * ```
+ *
+ * @param options Capability host and re-acquisition policy.
+ * @default options {}
+ * @returns Wake lock state and actions.
+ */
+declare function useWakeLock(options?: UseWakeLockOptions): WakeLockControls;
+//#endregion
+export { UseWakeLockOptions, WakeLockControls, WakeLockHost, WakeLockKind, WakeLockSentinelLike, useWakeLock };

package/dist/use-wake-lock.mjs

@@ -0,0 +1,106 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { computed, readonly, ref, shallowRef, toValue, watch } from "vue";
+//#region src/use-wake-lock.ts
+function browserWakeLockHost() {
+	if (typeof window === "undefined") return void 0;
+	const { navigator, document } = window;
+	return "wakeLock" in navigator && navigator.wakeLock ? {
+		wakeLock: navigator.wakeLock,
+		document
+	} : void 0;
+}
+/**
+* Keep the screen awake with the Screen Wake Lock API.
+*
+* Browsers release screen locks when the page is hidden; while a lock is
+* `requested`, it is re-acquired on the next `visibilitychange` to visible.
+* Request failures (missing user activation, battery saver) are exposed
+* through `error` rather than thrown. The lock and the visibility listener
+* are released when the owning reactive scope stops.
+*
+* Server rendering: nothing is requested, `supported` and `active` are false.
+*
+* @example
+* ```ts
+* const wakeLock = useWakeLock();
+* const startPresentation = () => wakeLock.request();
+* ```
+*
+* @param options Capability host and re-acquisition policy.
+* @default options {}
+* @returns Wake lock state and actions.
+*/
+function useWakeLock(options = {}) {
+	const active = ref(false);
+	const requested = ref(false);
+	const error = shallowRef(void 0);
+	let sentinel;
+	let kind = "screen";
+	let generation = 0;
+	const resolveHost = () => options.host === void 0 ? browserWakeLockHost() : toValue(options.host) ?? void 0;
+	const onRelease = () => {
+		active.value = false;
+		sentinel = void 0;
+	};
+	const acquire = async () => {
+		const host = resolveHost();
+		if (!host) return false;
+		const current = ++generation;
+		try {
+			const next = await host.wakeLock.request(kind);
+			if (current !== generation || !requested.value) {
+				await next.release();
+				return active.value;
+			}
+			sentinel?.removeEventListener("release", onRelease);
+			sentinel = next;
+			next.addEventListener("release", onRelease, { once: true });
+			active.value = !next.released;
+			error.value = void 0;
+			return active.value;
+		} catch (cause) {
+			if (current === generation) error.value = cause;
+			return false;
+		}
+	};
+	const request = async (type = "screen") => {
+		kind = type;
+		requested.value = true;
+		if (active.value) return true;
+		return acquire();
+	};
+	const release = async () => {
+		requested.value = false;
+		generation += 1;
+		const current = sentinel;
+		sentinel = void 0;
+		active.value = false;
+		if (!current) return;
+		current.removeEventListener("release", onRelease);
+		if (!current.released) await current.release();
+	};
+	if (options.reacquireOnVisible ?? true) watch(() => resolveHost()?.document ?? void 0, (document, _previous, onCleanup) => {
+		if (!document) return;
+		const onVisibility = () => {
+			if (document.visibilityState === "visible" && requested.value && !active.value) acquire();
+		};
+		document.addEventListener("visibilitychange", onVisibility);
+		onCleanup(() => document.removeEventListener("visibilitychange", onVisibility));
+	}, {
+		immediate: true,
+		flush: "sync"
+	});
+	tryOnScopeDispose(() => {
+		release();
+	});
+	return {
+		supported: computed(() => resolveHost() !== void 0),
+		active: readonly(active),
+		requested: readonly(requested),
+		error: readonly(error),
+		request,
+		release
+	};
+}
+//#endregion
+export { useWakeLock };