@vizejs/composable 0.424.11 → 0.426.0

package/dist/{catalog-BQMC1CcY.d.mts → catalog-D2AL3xYl.d.mts}

@@ -118,7 +118,7 @@ declare const COMPOSABLE_CATALOG: {
     readonly subpath: ".";
     readonly source: "src/index.ts";
     readonly gzipBudget: "sum-of-reexported-entry-budgets";
-    readonly reexportedEntries: readonly ["./abort-signal", "./async-resource", "./capability", "./catalog", "./disposal-scope", "./event-listener", "./locale", "./media-query", "./retry-async", "./retry-delay", "./scope", "./timeout-scheduler", "./use-counter", "./use-debounced", "./use-history", "./use-previous", "./use-throttled", "./use-toggle"];
+    readonly reexportedEntries: readonly ["./abort-signal", "./async-resource", "./capability", "./catalog", "./disposal-scope", "./document-visibility", "./event-listener", "./locale", "./media-query", "./retry-async", "./retry-delay", "./scope", "./timeout-scheduler", "./use-counter", "./use-debounced", "./use-history", "./use-previous", "./use-throttled", "./use-toggle"];
     readonly isolatedEntries: readonly ["./temporal"];
   };
   readonly entries: readonly [{
@@ -151,6 +151,12 @@ declare const COMPOSABLE_CATALOG: {
     readonly gzipBudgetBytes: number;
     readonly runtimeExports: readonly ["DISPOSAL_ERROR_CODE", "DisposalError", "createDisposalScope"];
     readonly utilities: readonly ["createDisposalScope"];
+  }, {
+    readonly subpath: "./document-visibility";
+    readonly source: "src/document-visibility.ts";
+    readonly gzipBudgetBytes: number;
+    readonly runtimeExports: readonly ["useDocumentVisibility"];
+    readonly utilities: readonly ["useDocumentVisibility"];
   }, {
     readonly subpath: "./event-listener";
     readonly source: "src/event-listener.ts";
@@ -335,6 +341,17 @@ declare const COMPOSABLE_CATALOG: {
     readonly cleanupOwners: readonly ["caller", "reactive-scope"];
     readonly runtimeGlobals: readonly [];
     readonly dependencies: readonly ["tryOnScopeDispose"];
+  }, {
+    readonly name: "useDocumentVisibility";
+    readonly entry: "./document-visibility";
+    readonly category: "events";
+    readonly stability: "experimental";
+    readonly targets: readonly ["web", "desktop"];
+    readonly ssr: "deterministic-fallback";
+    readonly hydration: "caller-managed";
+    readonly cleanupOwners: readonly ["reactive-scope"];
+    readonly runtimeGlobals: readonly ["document"];
+    readonly dependencies: readonly [];
   }, {
     readonly name: "useEventListener";
     readonly entry: "./event-listener";

package/dist/{catalog-CYHr82Jz.mjs → catalog-D5SYCsgW.mjs}

@@ -19,6 +19,7 @@ const rootEntry = {
 		"./capability",
 		"./catalog",
 		"./disposal-scope",
+		"./document-visibility",
 		"./event-listener",
 		"./locale",
 		"./media-query",
@@ -94,6 +95,13 @@ const entries = [
 		],
 		utilities: ["createDisposalScope"]
 	},
+	{
+		subpath: "./document-visibility",
+		source: "src/document-visibility.ts",
+		gzipBudgetBytes: 1.5 * 1024,
+		runtimeExports: ["useDocumentVisibility"],
+		utilities: ["useDocumentVisibility"]
+	},
 	{
 		subpath: "./event-listener",
 		source: "src/event-listener.ts",
@@ -343,6 +351,18 @@ const COMPOSABLE_CATALOG = {
 			runtimeGlobals: [],
 			dependencies: ["tryOnScopeDispose"]
 		},
+		{
+			name: "useDocumentVisibility",
+			entry: "./document-visibility",
+			category: "events",
+			stability: "experimental",
+			targets: browserTargets,
+			ssr: "deterministic-fallback",
+			hydration: "caller-managed",
+			cleanupOwners: ["reactive-scope"],
+			runtimeGlobals: ["document"],
+			dependencies: []
+		},
 		{
 			name: "useEventListener",
 			entry: "./event-listener",

package/dist/catalog.d.mts

@@ -1,2 +1,2 @@
-import { a as ComposableEntryMetadata, c as ComposableRootEntryMetadata, d as ComposableUtilityMetadata, i as ComposableCleanupOwner, l as ComposableSsrBehavior, n as ComposableCatalog, o as ComposableHydrationBehavior, r as ComposableCategory, s as ComposableInstallationAvailability, t as COMPOSABLE_CATALOG, u as ComposableStability } from "./catalog-BQMC1CcY.mjs";
+import { a as ComposableEntryMetadata, c as ComposableRootEntryMetadata, d as ComposableUtilityMetadata, i as ComposableCleanupOwner, l as ComposableSsrBehavior, n as ComposableCatalog, o as ComposableHydrationBehavior, r as ComposableCategory, s as ComposableInstallationAvailability, t as COMPOSABLE_CATALOG, u as ComposableStability } from "./catalog-D2AL3xYl.mjs";
 export { COMPOSABLE_CATALOG, type ComposableCatalog, type ComposableCategory, type ComposableCleanupOwner, type ComposableEntryMetadata, type ComposableHydrationBehavior, type ComposableInstallationAvailability, type ComposableRootEntryMetadata, type ComposableSsrBehavior, type ComposableStability, type ComposableUtilityMetadata };

package/dist/catalog.mjs

@@ -1,2 +1,2 @@
-import { t as COMPOSABLE_CATALOG } from "./catalog-CYHr82Jz.mjs";
+import { t as COMPOSABLE_CATALOG } from "./catalog-D5SYCsgW.mjs";
 export { COMPOSABLE_CATALOG };

package/dist/document-visibility.d.mts

@@ -0,0 +1,65 @@
+import { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/document-visibility.d.ts
+/** Page visibility state exposed by {@link useDocumentVisibility}. */
+type PageVisibilityState = "hidden" | "visible";
+/** Capability required to observe document visibility. */
+interface DocumentVisibilityHost {
+  /** Current browser visibility state. Unknown states are treated as hidden. */
+  readonly visibilityState?: string;
+  /** Legacy visibility flag used when `visibilityState` is absent. */
+  readonly hidden?: boolean;
+  /** Subscribe to `visibilitychange`. */
+  readonly addEventListener: (event: "visibilitychange", listener: EventListener, options?: boolean | AddEventListenerOptions) => void;
+  /** Remove a previous `visibilitychange` listener. */
+  readonly removeEventListener: (event: "visibilitychange", listener: EventListener, options?: boolean | EventListenerOptions) => void;
+}
+/** Options for {@link useDocumentVisibility}. */
+interface UseDocumentVisibilityOptions {
+  /**
+   * State exposed while no document capability is available.
+   *
+   * @default "visible"
+   */
+  readonly ssrState?: PageVisibilityState;
+  /**
+   * Reactive document capability for alternate runtimes and tests.
+   *
+   * @default globalThis.document when available
+   */
+  readonly host?: MaybeRefOrGetter<DocumentVisibilityHost | null | undefined>;
+  /**
+   * Reactive subscription update timing.
+   *
+   * @default "pre"
+   */
+  readonly flush?: "pre" | "post" | "sync";
+}
+/** Reactive state returned by {@link useDocumentVisibility}. */
+interface DocumentVisibilityControls {
+  /** Current visibility state, using the configured SSR fallback while unsupported. */
+  readonly state: Readonly<Ref<PageVisibilityState>>;
+  /** Whether a concrete document capability is currently attached. */
+  readonly supported: Readonly<Ref<boolean>>;
+  /** Whether `state` is `"visible"`. */
+  readonly visible: ComputedRef<boolean>;
+  /** Whether `state` is `"hidden"`. */
+  readonly hidden: ComputedRef<boolean>;
+}
+/**
+ * Observe document visibility without touching browser globals during module evaluation.
+ *
+ * The composable is safe during server rendering: when no host resolves, it exposes
+ * `ssrState` and marks `supported` false. During hydration or tests, passing a
+ * host attaches exactly one `visibilitychange` listener and removes it when the
+ * reactive host changes or the owning scope stops. Unsupported or future
+ * visibility states normalize to `"hidden"` so consumers fail closed instead of
+ * accidentally treating a prerendered or unloaded page as visible.
+ *
+ * @param options Runtime capability, server fallback, and watcher timing.
+ * @default options {}
+ * @returns Reactive visibility state plus derived booleans.
+ */
+declare function useDocumentVisibility(options?: UseDocumentVisibilityOptions): DocumentVisibilityControls;
+//#endregion
+export { DocumentVisibilityControls, DocumentVisibilityHost, PageVisibilityState, UseDocumentVisibilityOptions, useDocumentVisibility };

package/dist/document-visibility.mjs

@@ -0,0 +1,56 @@
+import { computed, readonly, ref, toValue, watchEffect } from "vue";
+//#region src/document-visibility.ts
+/**
+* Observe document visibility without touching browser globals during module evaluation.
+*
+* The composable is safe during server rendering: when no host resolves, it exposes
+* `ssrState` and marks `supported` false. During hydration or tests, passing a
+* host attaches exactly one `visibilitychange` listener and removes it when the
+* reactive host changes or the owning scope stops. Unsupported or future
+* visibility states normalize to `"hidden"` so consumers fail closed instead of
+* accidentally treating a prerendered or unloaded page as visible.
+*
+* @param options Runtime capability, server fallback, and watcher timing.
+* @default options {}
+* @returns Reactive visibility state plus derived booleans.
+*/
+function useDocumentVisibility(options = {}) {
+	const fallback = options.ssrState ?? "visible";
+	const state = ref(fallback);
+	const supported = ref(false);
+	watchEffect((onCleanup) => {
+		const host = options.host === void 0 ? browserDocumentVisibilityHost() : toValue(options.host);
+		if (!host) {
+			supported.value = false;
+			state.value = fallback;
+			return;
+		}
+		const update = () => {
+			state.value = readVisibilityState(host);
+		};
+		supported.value = true;
+		update();
+		host.addEventListener("visibilitychange", update);
+		onCleanup(() => {
+			host.removeEventListener("visibilitychange", update);
+			supported.value = false;
+		});
+	}, { flush: options.flush ?? "pre" });
+	return {
+		state: readonly(state),
+		supported: readonly(supported),
+		visible: computed(() => state.value === "visible"),
+		hidden: computed(() => state.value === "hidden")
+	};
+}
+function readVisibilityState(host) {
+	if (host.visibilityState === "visible") return "visible";
+	if (host.visibilityState === "hidden") return "hidden";
+	if (host.visibilityState !== void 0) return "hidden";
+	return host.hidden === false ? "visible" : "hidden";
+}
+function browserDocumentVisibilityHost() {
+	return typeof document !== "undefined" ? document : void 0;
+}
+//#endregion
+export { useDocumentVisibility };

package/dist/index.d.mts

@@ -2,8 +2,9 @@ import { TimeoutScheduler } from "./timeout-scheduler.mjs";
 import { DeadlineAbortSignalOptions, TimeoutAbortSignalOptions, anyAbortSignal, deadlineAbortSignal, timeoutAbortSignal } from "./abort-signal.mjs";
 import { AsyncResource, AsyncResourceContext, AsyncResourceExecution, AsyncResourceStatus, UseAsyncResourceOptions, useAsyncResource } from "./async-resource.mjs";
 import { a as CapabilityUnavailableReason, c as isCapabilityAvailable, i as CapabilityTarget, l as isCapabilityUnavailable, n as CapabilityResult, o as UnavailableCapability, r as CapabilitySource, s as availableCapability, t as AvailableCapability, u as unavailableCapability } from "./capability-Ptkjr_sD.mjs";
-import { a as ComposableEntryMetadata, c as ComposableRootEntryMetadata, d as ComposableUtilityMetadata, i as ComposableCleanupOwner, l as ComposableSsrBehavior, n as ComposableCatalog, o as ComposableHydrationBehavior, r as ComposableCategory, s as ComposableInstallationAvailability, t as COMPOSABLE_CATALOG, u as ComposableStability } from "./catalog-BQMC1CcY.mjs";
+import { a as ComposableEntryMetadata, c as ComposableRootEntryMetadata, d as ComposableUtilityMetadata, i as ComposableCleanupOwner, l as ComposableSsrBehavior, n as ComposableCatalog, o as ComposableHydrationBehavior, r as ComposableCategory, s as ComposableInstallationAvailability, t as COMPOSABLE_CATALOG, u as ComposableStability } from "./catalog-D2AL3xYl.mjs";
 import { CleanupRegistration, CreateDisposalScopeOptions, DISPOSAL_ERROR_CODE, DisposalError, DisposalScope, createDisposalScope } from "./disposal-scope.mjs";
+import { DocumentVisibilityControls, DocumentVisibilityHost, PageVisibilityState, UseDocumentVisibilityOptions, useDocumentVisibility } from "./document-visibility.mjs";
 import { EventListenerControls, UseEventListenerOptions, useEventListener } from "./event-listener.mjs";
 import { LocaleControls, TextDirection, UseLocaleOptions, useLocale } from "./locale.mjs";
 import { MediaQueryHost, MotionPreference, UseMediaQueryOptions, useMediaQuery, useReducedMotion } from "./media-query.mjs";
@@ -16,4 +17,4 @@ import { HistoryControls, UseHistoryOptions, useHistory } from "./use-history.mj
 import { usePrevious } from "./use-previous.mjs";
 import { ThrottledControls, UseThrottledOptions, useThrottled } from "./use-throttled.mjs";
 import { ToggleControls, useToggle } from "./use-toggle.mjs";
-export { AsyncResource, AsyncResourceContext, AsyncResourceExecution, AsyncResourceStatus, AvailableCapability, COMPOSABLE_CATALOG, CapabilityResult, CapabilitySource, CapabilityTarget, CapabilityUnavailableReason, CleanupRegistration, type ComposableCatalog, type ComposableCategory, type ComposableCleanupOwner, type ComposableEntryMetadata, type ComposableHydrationBehavior, type ComposableInstallationAvailability, type ComposableRootEntryMetadata, type ComposableSsrBehavior, type ComposableStability, type ComposableUtilityMetadata, CounterControls, CreateDisposalScopeOptions, DISPOSAL_ERROR_CODE, DeadlineAbortSignalOptions, DebouncedControls, DisposalError, DisposalScope, EventListenerControls, HistoryControls, LocaleControls, MediaQueryHost, MotionPreference, RetryAsyncOptions, RetryAttemptContext, RetryDelayOptions, RetryFailureContext, RetryScheduledContext, TextDirection, ThrottledControls, TimeoutAbortSignalOptions, TimeoutScheduler, ToggleControls, UnavailableCapability, UseAsyncResourceOptions, UseCounterOptions, UseDebouncedOptions, UseEventListenerOptions, UseHistoryOptions, UseLocaleOptions, UseMediaQueryOptions, UseThrottledOptions, anyAbortSignal, availableCapability, calculateRetryDelay, createDisposalScope, deadlineAbortSignal, isCapabilityAvailable, isCapabilityUnavailable, retryAsync, timeoutAbortSignal, tryOnScopeDispose, unavailableCapability, useAsyncResource, useCounter, useDebounced, useEventListener, useHistory, useLocale, useMediaQuery, usePrevious, useReducedMotion, useThrottled, useToggle };
+export { AsyncResource, AsyncResourceContext, AsyncResourceExecution, AsyncResourceStatus, AvailableCapability, COMPOSABLE_CATALOG, CapabilityResult, CapabilitySource, CapabilityTarget, CapabilityUnavailableReason, CleanupRegistration, type ComposableCatalog, type ComposableCategory, type ComposableCleanupOwner, type ComposableEntryMetadata, type ComposableHydrationBehavior, type ComposableInstallationAvailability, type ComposableRootEntryMetadata, type ComposableSsrBehavior, type ComposableStability, type ComposableUtilityMetadata, CounterControls, CreateDisposalScopeOptions, DISPOSAL_ERROR_CODE, DeadlineAbortSignalOptions, DebouncedControls, DisposalError, DisposalScope, DocumentVisibilityControls, DocumentVisibilityHost, EventListenerControls, HistoryControls, LocaleControls, MediaQueryHost, MotionPreference, PageVisibilityState, RetryAsyncOptions, RetryAttemptContext, RetryDelayOptions, RetryFailureContext, RetryScheduledContext, TextDirection, ThrottledControls, TimeoutAbortSignalOptions, TimeoutScheduler, ToggleControls, UnavailableCapability, UseAsyncResourceOptions, UseCounterOptions, UseDebouncedOptions, UseDocumentVisibilityOptions, UseEventListenerOptions, UseHistoryOptions, UseLocaleOptions, UseMediaQueryOptions, UseThrottledOptions, anyAbortSignal, availableCapability, calculateRetryDelay, createDisposalScope, deadlineAbortSignal, isCapabilityAvailable, isCapabilityUnavailable, retryAsync, timeoutAbortSignal, tryOnScopeDispose, unavailableCapability, useAsyncResource, useCounter, useDebounced, useDocumentVisibility, useEventListener, useHistory, useLocale, useMediaQuery, usePrevious, useReducedMotion, useThrottled, useToggle };

package/dist/index.mjs

@@ -2,7 +2,8 @@ import { anyAbortSignal, deadlineAbortSignal, timeoutAbortSignal } from "./abort
 import { tryOnScopeDispose } from "./scope.mjs";
 import { useAsyncResource } from "./async-resource.mjs";
 import { availableCapability, isCapabilityAvailable, isCapabilityUnavailable, unavailableCapability } from "./capability.mjs";
-import { t as COMPOSABLE_CATALOG } from "./catalog-CYHr82Jz.mjs";
+import { t as COMPOSABLE_CATALOG } from "./catalog-D5SYCsgW.mjs";
+import { useDocumentVisibility } from "./document-visibility.mjs";
 import { DISPOSAL_ERROR_CODE, DisposalError, createDisposalScope } from "./disposal-scope.mjs";
 import { useEventListener } from "./event-listener.mjs";
 import { useLocale } from "./locale.mjs";
@@ -16,4 +17,4 @@ import { useHistory } from "./use-history.mjs";
 import { usePrevious } from "./use-previous.mjs";
 import { useThrottled } from "./use-throttled.mjs";
 import { useToggle } from "./use-toggle.mjs";
-export { COMPOSABLE_CATALOG, DISPOSAL_ERROR_CODE, DisposalError, anyAbortSignal, availableCapability, calculateRetryDelay, createDisposalScope, deadlineAbortSignal, isCapabilityAvailable, isCapabilityUnavailable, retryAsync, timeoutAbortSignal, tryOnScopeDispose, unavailableCapability, useAsyncResource, useCounter, useDebounced, useEventListener, useHistory, useLocale, useMediaQuery, usePrevious, useReducedMotion, useThrottled, useToggle };
+export { COMPOSABLE_CATALOG, DISPOSAL_ERROR_CODE, DisposalError, anyAbortSignal, availableCapability, calculateRetryDelay, createDisposalScope, deadlineAbortSignal, isCapabilityAvailable, isCapabilityUnavailable, retryAsync, timeoutAbortSignal, tryOnScopeDispose, unavailableCapability, useAsyncResource, useCounter, useDebounced, useDocumentVisibility, useEventListener, useHistory, useLocale, useMediaQuery, usePrevious, useReducedMotion, useThrottled, useToggle };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizejs/composable",
-  "version": "0.424.11",
+  "version": "0.426.0",
   "description": "Lifecycle-safe composable foundations for Vize applications",
   "keywords": [
     "composables",
@@ -57,6 +57,11 @@
       "import": "./dist/disposal-scope.mjs",
       "default": "./dist/disposal-scope.mjs"
     },
+    "./document-visibility": {
+      "types": "./dist/document-visibility.d.mts",
+      "import": "./dist/document-visibility.mjs",
+      "default": "./dist/document-visibility.mjs"
+    },
     "./event-listener": {
       "types": "./dist/event-listener.d.mts",
       "import": "./dist/event-listener.mjs",
@@ -146,6 +151,12 @@
   "engines": {
     "node": ">=24"
   },
+  "metadata": {
+    "vize": {
+      "stability": "experimental",
+      "stabilityDocs": "https://github.com/ubugeeei-prod/vize/blob/main/docs/content/stability.md#package-support-tiers"
+    }
+  },
   "scripts": {
     "build": "vp pack",
     "dev": "vp pack --watch",