@vizejs/composable 0.426.3 → 0.427.0

package/dist/use-clipboard.d.mts

@@ -0,0 +1,169 @@
+import { t as TimeoutScheduler } from "./timeout-scheduler-CI8RVLZs.mjs";
+import { PermissionQueryState, PermissionsHost } from "./use-permission.mjs";
+import { ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+//#region src/use-clipboard.d.ts
+/** One clipboard entry, compatible with the DOM `ClipboardItem`. */
+interface ClipboardItemLike {
+  /** MIME types available in this item. */
+  readonly types: readonly string[];
+  /** Read the item's data for one of its `types`. */
+  getType(type: string): Promise<Blob>;
+}
+/** Minimal async Clipboard API consumed by {@link useClipboard}. */
+interface ClipboardLike {
+  /** Read plain text. */
+  readText(): Promise<string>;
+  /** Write plain text. */
+  writeText(text: string): Promise<void>;
+  /** Read rich items. Absent in older browsers. */
+  read?(): Promise<readonly ClipboardItemLike[]>;
+  /** Write rich items. Absent in older browsers. */
+  write?(items: readonly ClipboardItemLike[]): Promise<void>;
+}
+/** Capabilities used by {@link useClipboard}; every member is optional. */
+interface ClipboardHost {
+  /** Async Clipboard API (`navigator.clipboard`). */
+  readonly clipboard?: ClipboardLike | null;
+  /** Permissions API used to report read/write permission state. */
+  readonly permissions?: PermissionsHost | null;
+  /**
+   * Synchronous legacy copy used when the async API is missing or refuses.
+   * Returns whether the copy succeeded.
+   */
+  readonly legacyCopy?: ((text: string) => boolean) | null;
+  /** Target of `copy`/`cut` events observed when `listen` is enabled. */
+  readonly events?: EventTarget | null;
+}
+/** Why a clipboard operation did not complete. */
+type ClipboardFailureReason = "permission-denied" | "unsupported" | "failed";
+/** Successful clipboard operation. */
+interface ClipboardSuccess<Value> {
+  /** The operation succeeded. */
+  readonly status: "success";
+  /** Value that was read or written. */
+  readonly value: Value;
+  /** Mechanism that performed the operation. */
+  readonly method: "clipboard" | "legacy";
+}
+/** Failed clipboard operation. */
+interface ClipboardFailure {
+  /** Why the operation failed. */
+  readonly status: ClipboardFailureReason;
+  /** Exact error thrown by the host, when one was thrown. */
+  readonly error: unknown;
+}
+/** Discriminated result of a clipboard operation. */
+type ClipboardResult<Value> = ClipboardSuccess<Value> | ClipboardFailure;
+/** Options for {@link useClipboard}. */
+interface UseClipboardOptions {
+  /**
+   * Clipboard capabilities for alternate runtimes and tests.
+   *
+   * @default navigator.clipboard, navigator.permissions, and an
+   * `execCommand("copy")` fallback when a browser window exists
+   */
+  readonly host?: MaybeRefOrGetter<ClipboardHost | null | undefined>;
+  /**
+   * Fall back to `document.execCommand("copy")` when the async API is
+   * unavailable or rejects a write.
+   *
+   * @default true
+   */
+  readonly legacy?: boolean;
+  /**
+   * Milliseconds for which `copied` stays `true` after a successful write.
+   *
+   * @default 1500
+   */
+  readonly copiedDuringMs?: number;
+  /**
+   * Timer host used to reset `copied`.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+  /**
+   * Update `text` by reading the clipboard after every `copy`/`cut` event.
+   *
+   * @default false
+   */
+  readonly listen?: boolean;
+  /**
+   * Query the `clipboard-read` / `clipboard-write` permissions.
+   *
+   * @default true
+   */
+  readonly queryPermissions?: boolean;
+}
+/** Reactive state and actions returned by {@link useClipboard}. */
+interface ClipboardControls {
+  /** Whether the async Clipboard API or the legacy fallback is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Text most recently copied or read. */
+  readonly text: Readonly<Ref<string>>;
+  /** `true` for `copiedDuringMs` after a successful copy. */
+  readonly copied: Readonly<Ref<boolean>>;
+  /** Most recent failure, cleared by the next success. */
+  readonly error: Readonly<ShallowRef<ClipboardFailure | undefined>>;
+  /** State of the `clipboard-read` permission. */
+  readonly readPermission: Readonly<Ref<PermissionQueryState>>;
+  /** State of the `clipboard-write` permission. */
+  readonly writePermission: Readonly<Ref<PermissionQueryState>>;
+  /**
+   * Copy text, falling back to the legacy mechanism when allowed.
+   *
+   * @param text Text to copy.
+   * @returns The discriminated outcome; never rejects.
+   */
+  readonly copy: (text: string) => Promise<ClipboardResult<string>>;
+  /**
+   * Read plain text.
+   *
+   * @returns The discriminated outcome; never rejects.
+   */
+  readonly readText: () => Promise<ClipboardResult<string>>;
+  /**
+   * Write rich clipboard items.
+   *
+   * @param items Items to write.
+   * @returns The discriminated outcome; never rejects.
+   */
+  readonly writeItems: (items: readonly ClipboardItemLike[]) => Promise<ClipboardResult<readonly ClipboardItemLike[]>>;
+  /**
+   * Read rich clipboard items.
+   *
+   * @returns The discriminated outcome; never rejects.
+   */
+  readonly readItems: () => Promise<ClipboardResult<readonly ClipboardItemLike[]>>;
+}
+/**
+ * Permission-aware clipboard access with a legacy copy fallback.
+ *
+ * Text and rich items go through the async Clipboard API. When it is
+ * missing (insecure contexts, older engines) or refuses a write, `copy`
+ * falls back to `document.execCommand("copy")` unless `legacy` is false.
+ * Every action resolves to a discriminated {@link ClipboardResult}
+ * (`"success"`, `"permission-denied"`, `"unsupported"`, `"failed"`) instead
+ * of rejecting, and the read/write permission states are exposed reactively.
+ *
+ * Server rendering: nothing is read and no permission is queried; `text` is
+ * empty and `supported` is false. The `copied` reset timer and the optional
+ * `copy`/`cut` listeners are released when the owning scope stops.
+ *
+ * Inside a component the host is read after mounting, so hydration renders
+ * the server fallback first and never mismatches.
+ *
+ * @example
+ * ```ts
+ * const { copy, copied } = useClipboard();
+ * await copy("npm i @vizejs/composable");
+ * ```
+ *
+ * @param options Capabilities, fallback policy, and feedback timing.
+ * @default options {}
+ * @returns Reactive clipboard state and actions.
+ */
+declare function useClipboard(options?: UseClipboardOptions): ClipboardControls;
+//#endregion
+export { ClipboardControls, ClipboardFailure, ClipboardFailureReason, ClipboardHost, ClipboardItemLike, ClipboardLike, ClipboardResult, ClipboardSuccess, UseClipboardOptions, useClipboard };

package/dist/use-clipboard.mjs

@@ -0,0 +1,226 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { usePermission } from "./use-permission.mjs";
+import { computed, hasInjectionContext, readonly, ref, shallowRef, toValue, watch, watchPostEffect } from "vue";
+//#region src/use-clipboard.ts
+const defaultScheduler = {
+	setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+	clearTimeout: (handle) => {
+		globalThis.clearTimeout(handle);
+	}
+};
+function legacyDocumentCopy(document) {
+	return (text) => {
+		const area = document.createElement("textarea");
+		area.value = text;
+		area.setAttribute("readonly", "");
+		area.style.position = "fixed";
+		area.style.opacity = "0";
+		area.style.pointerEvents = "none";
+		document.body.append(area);
+		area.select();
+		try {
+			return document.execCommand("copy");
+		} catch {
+			return false;
+		} finally {
+			area.remove();
+		}
+	};
+}
+function browserClipboardHost() {
+	if (typeof window === "undefined") return void 0;
+	const { navigator, document } = window;
+	return {
+		clipboard: navigator.clipboard ?? null,
+		permissions: navigator.permissions ?? null,
+		legacyCopy: typeof document.execCommand === "function" ? legacyDocumentCopy(document) : null,
+		events: document
+	};
+}
+function isPermissionError(error) {
+	return typeof error === "object" && error !== null && "name" in error && (error.name === "NotAllowedError" || error.name === "SecurityError");
+}
+function failure(error) {
+	return {
+		status: isPermissionError(error) ? "permission-denied" : "failed",
+		error
+	};
+}
+const unsupported = {
+	status: "unsupported",
+	error: void 0
+};
+/**
+* Permission-aware clipboard access with a legacy copy fallback.
+*
+* Text and rich items go through the async Clipboard API. When it is
+* missing (insecure contexts, older engines) or refuses a write, `copy`
+* falls back to `document.execCommand("copy")` unless `legacy` is false.
+* Every action resolves to a discriminated {@link ClipboardResult}
+* (`"success"`, `"permission-denied"`, `"unsupported"`, `"failed"`) instead
+* of rejecting, and the read/write permission states are exposed reactively.
+*
+* Server rendering: nothing is read and no permission is queried; `text` is
+* empty and `supported` is false. The `copied` reset timer and the optional
+* `copy`/`cut` listeners are released when the owning scope stops.
+*
+* Inside a component the host is read after mounting, so hydration renders
+* the server fallback first and never mismatches.
+*
+* @example
+* ```ts
+* const { copy, copied } = useClipboard();
+* await copy("npm i @vizejs/composable");
+* ```
+*
+* @param options Capabilities, fallback policy, and feedback timing.
+* @default options {}
+* @returns Reactive clipboard state and actions.
+*/
+function useClipboard(options = {}) {
+	const copiedDuringMs = options.copiedDuringMs ?? 1500;
+	if (!Number.isFinite(copiedDuringMs) || copiedDuringMs < 0) throw new RangeError(`[VIZE_COMPOSE_CLIPBOARD_INVALID_DURATION] copiedDuringMs must be a non-negative finite number; received ${String(copiedDuringMs)}`);
+	const scheduler = options.scheduler ?? defaultScheduler;
+	const allowLegacy = options.legacy ?? true;
+	const text = ref("");
+	const copied = ref(false);
+	const error = shallowRef(void 0);
+	let resetHandle;
+	let resetPending = false;
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const resolveHost = () => options.host === void 0 ? browserClipboardHost() : toValue(options.host) ?? void 0;
+	const queryPermissions = options.queryPermissions ?? true;
+	const permissionHost = () => queryPermissions ? resolveHost()?.permissions ?? void 0 : void 0;
+	const readPermission = usePermission("clipboard-read", { host: permissionHost });
+	const writePermission = usePermission("clipboard-write", { host: permissionHost });
+	const supported = computed(() => {
+		if (!hydrated.value) return false;
+		const host = resolveHost();
+		return Boolean(host?.clipboard) || Boolean(allowLegacy && host?.legacyCopy);
+	});
+	const settle = (result) => {
+		error.value = result.status === "success" ? void 0 : result;
+		return result;
+	};
+	const markCopied = (value) => {
+		text.value = value;
+		copied.value = true;
+		if (resetPending) scheduler.clearTimeout(resetHandle);
+		resetPending = true;
+		resetHandle = scheduler.setTimeout(() => {
+			resetPending = false;
+			copied.value = false;
+		}, copiedDuringMs);
+	};
+	const tryLegacy = (host, value) => {
+		if (!allowLegacy || !host.legacyCopy) return void 0;
+		try {
+			return host.legacyCopy(value) ? {
+				status: "success",
+				value,
+				method: "legacy"
+			} : {
+				status: "failed",
+				error: void 0
+			};
+		} catch (cause) {
+			return failure(cause);
+		}
+	};
+	const copy = async (value) => {
+		const host = resolveHost();
+		if (!host) return settle(unsupported);
+		let result;
+		if (host.clipboard) try {
+			await host.clipboard.writeText(value);
+			result = {
+				status: "success",
+				value,
+				method: "clipboard"
+			};
+		} catch (cause) {
+			result = tryLegacy(host, value) ?? failure(cause);
+		}
+		else result = tryLegacy(host, value) ?? unsupported;
+		if (result.status === "success") markCopied(value);
+		return settle(result);
+	};
+	const readText = async () => {
+		const clipboard = resolveHost()?.clipboard;
+		if (!clipboard) return settle(unsupported);
+		try {
+			const value = await clipboard.readText();
+			text.value = value;
+			return settle({
+				status: "success",
+				value,
+				method: "clipboard"
+			});
+		} catch (cause) {
+			return settle(failure(cause));
+		}
+	};
+	const writeItems = async (items) => {
+		const clipboard = resolveHost()?.clipboard;
+		if (!clipboard?.write) return settle(unsupported);
+		try {
+			await clipboard.write(items);
+			return settle({
+				status: "success",
+				value: items,
+				method: "clipboard"
+			});
+		} catch (cause) {
+			return settle(failure(cause));
+		}
+	};
+	const readItems = async () => {
+		const clipboard = resolveHost()?.clipboard;
+		if (!clipboard?.read) return settle(unsupported);
+		try {
+			return settle({
+				status: "success",
+				value: await clipboard.read(),
+				method: "clipboard"
+			});
+		} catch (cause) {
+			return settle(failure(cause));
+		}
+	};
+	if (options.listen ?? false) watch(() => resolveHost()?.events ?? void 0, (events, _previous, onCleanup) => {
+		if (!events) return;
+		const onCopy = () => {
+			readText();
+		};
+		events.addEventListener("copy", onCopy);
+		events.addEventListener("cut", onCopy);
+		onCleanup(() => {
+			events.removeEventListener("copy", onCopy);
+			events.removeEventListener("cut", onCopy);
+		});
+	}, {
+		immediate: true,
+		flush: "sync"
+	});
+	tryOnScopeDispose(() => {
+		if (resetPending) scheduler.clearTimeout(resetHandle);
+		resetPending = false;
+	});
+	return {
+		supported,
+		text: readonly(text),
+		copied: readonly(copied),
+		error: readonly(error),
+		readPermission: readPermission.state,
+		writePermission: writePermission.state,
+		copy,
+		readText,
+		writeItems,
+		readItems
+	};
+}
+//#endregion
+export { useClipboard };

package/dist/use-compression-stream.d.mts

@@ -0,0 +1,173 @@
+import { ComputedRef, MaybeRef, Ref, ShallowRef } from "vue";
+
+//#region src/use-compression-stream.d.ts
+/** Formats supported by `CompressionStream` and `DecompressionStream`. */
+type CompressionFormatName = "gzip" | "deflate" | "deflate-raw";
+/** Data accepted by {@link compress} and {@link decompress}. */
+type CompressionInput = string | ArrayBuffer | ArrayBufferView | Blob | ReadableStream<BufferSource>;
+/** Transform stream created by a (de)compression constructor. */
+interface CompressionTransformLike {
+  /** Transformed output. */
+  readonly readable: ReadableStream<Uint8Array>;
+  /** Raw input. */
+  readonly writable: WritableStream<BufferSource>;
+}
+/** Minimal `CompressionStream` / `DecompressionStream` constructor. */
+type CompressionStreamConstructor = new (format: CompressionFormatName) => CompressionTransformLike;
+/** Options for {@link compress}. */
+interface CompressOptions {
+  /**
+   * Compression stream constructor.
+   *
+   * @default window.CompressionStream when it exists
+   */
+  readonly CompressionStream?: CompressionStreamConstructor | null | undefined;
+}
+/** Options for {@link decompress} and {@link decompressText}. */
+interface DecompressOptions {
+  /**
+   * Decompression stream constructor.
+   *
+   * @default window.DecompressionStream when it exists
+   */
+  readonly DecompressionStream?: CompressionStreamConstructor | null | undefined;
+}
+/** Options for {@link useCompressionStream}. */
+interface UseCompressionStreamOptions {
+  /**
+   * Compression stream constructor. A ref (not a getter) because the host is
+   * a constructor function.
+   *
+   * @default window.CompressionStream when it exists
+   */
+  readonly CompressionStream?: MaybeRef<CompressionStreamConstructor | null | undefined>;
+  /**
+   * Decompression stream constructor.
+   *
+   * @default window.DecompressionStream when it exists
+   */
+  readonly DecompressionStream?: MaybeRef<CompressionStreamConstructor | null | undefined>;
+  /**
+   * Format used when an action is called without one.
+   *
+   * @default "gzip"
+   */
+  readonly format?: CompressionFormatName;
+}
+/** Reactive state and actions returned by {@link useCompressionStream}. */
+interface CompressionStreamControls {
+  /** Whether both `CompressionStream` and `DecompressionStream` are available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Whether an action is in flight. */
+  readonly pending: Readonly<Ref<boolean>>;
+  /** Most recent failure, cleared by the next successful action. */
+  readonly error: Readonly<ShallowRef<unknown>>;
+  /**
+   * Compress `data`; rejects like {@link compress}.
+   *
+   * @param data Input data.
+   * @param format Compression format.
+   * @returns Compressed bytes.
+   */
+  readonly compress: (data: CompressionInput, format?: CompressionFormatName) => Promise<Uint8Array<ArrayBuffer>>;
+  /**
+   * Decompress `data`; rejects like {@link decompress}.
+   *
+   * @param data Compressed data.
+   * @param format Compression format.
+   * @returns Decompressed bytes.
+   */
+  readonly decompress: (data: CompressionInput, format?: CompressionFormatName) => Promise<Uint8Array<ArrayBuffer>>;
+  /**
+   * Decompress `data` and decode it as UTF-8.
+   *
+   * @param data Compressed data.
+   * @param format Compression format.
+   * @returns Decompressed text.
+   */
+  readonly decompressText: (data: CompressionInput, format?: CompressionFormatName) => Promise<string>;
+}
+/**
+ * Compress data with the Compression Streams API.
+ *
+ * Strings are UTF-8 encoded first. Rejects with a tagged `TypeError` for an
+ * unknown format or when no `CompressionStream` is available (always on the
+ * server unless one is injected).
+ *
+ * @example
+ * ```ts
+ * const gzipped = await compress(JSON.stringify(state), "gzip");
+ * ```
+ *
+ * @param data Input data.
+ * @param format Compression format.
+ * @param options Constructor override.
+ * @default format "gzip"
+ * @default options {}
+ * @returns Compressed bytes.
+ */
+declare function compress(data: CompressionInput, format?: CompressionFormatName, options?: CompressOptions): Promise<Uint8Array<ArrayBuffer>>;
+/**
+ * Decompress data with the Compression Streams API.
+ *
+ * Rejects with a tagged `TypeError` for an unknown format or when no
+ * `DecompressionStream` is available, and with the stream's error for
+ * corrupt input.
+ *
+ * @example
+ * ```ts
+ * const bytes = await decompress(await response.blob(), "gzip");
+ * ```
+ *
+ * @param data Compressed data.
+ * @param format Compression format.
+ * @param options Constructor override.
+ * @default format "gzip"
+ * @default options {}
+ * @returns Decompressed bytes.
+ */
+declare function decompress(data: CompressionInput, format?: CompressionFormatName, options?: DecompressOptions): Promise<Uint8Array<ArrayBuffer>>;
+/**
+ * Decompress data and decode the result as UTF-8 text.
+ *
+ * Rejects exactly like {@link decompress}.
+ *
+ * @example
+ * ```ts
+ * const json = JSON.parse(await decompressText(bytes, "deflate"));
+ * ```
+ *
+ * @param data Compressed data.
+ * @param format Compression format.
+ * @param options Constructor override.
+ * @default format "gzip"
+ * @default options {}
+ * @returns Decompressed text.
+ */
+declare function decompressText(data: CompressionInput, format?: CompressionFormatName, options?: DecompressOptions): Promise<string>;
+/**
+ * Reactive wrapper around {@link compress}, {@link decompress} and
+ * {@link decompressText}.
+ *
+ * Tracks whether an action is in flight and records the last failure in
+ * `error`; actions still reject so callers can handle failures inline.
+ * Nothing needs cleanup.
+ *
+ * Server rendering: `supported` is false and actions reject with the tagged
+ * unsupported error unless constructors are injected.
+ * Inside a component `supported` turns true only after mounting, so
+ * hydration renders this server state first.
+ *
+ * @example
+ * ```ts
+ * const { compress, decompressText, pending } = useCompressionStream({ format: "deflate" });
+ * const packed = await compress(draft.value);
+ * ```
+ *
+ * @param options Constructor overrides and default format.
+ * @default options {}
+ * @returns Compression state and bound actions.
+ */
+declare function useCompressionStream(options?: UseCompressionStreamOptions): CompressionStreamControls;
+//#endregion
+export { CompressOptions, CompressionFormatName, CompressionInput, CompressionStreamConstructor, CompressionStreamControls, CompressionTransformLike, DecompressOptions, UseCompressionStreamOptions, compress, decompress, decompressText, useCompressionStream };