@vizejs/composable 0.426.2 → 0.427.0

package/dist/use-scheduler-post-task.mjs

@@ -0,0 +1,182 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { computed, hasInjectionContext, readonly, shallowRef, toValue, unref, watchPostEffect } from "vue";
+//#region src/use-scheduler-post-task.ts
+const PRIORITIES = [
+	"user-blocking",
+	"user-visible",
+	"background"
+];
+function isScheduler(candidate) {
+	return typeof candidate === "object" && candidate !== null && typeof Reflect.get(candidate, "postTask") === "function";
+}
+function isTaskControllerHost(candidate) {
+	return typeof candidate === "function";
+}
+function isTaskController(controller) {
+	return "setPriority" in controller && typeof controller.setPriority === "function";
+}
+function browserGlobal(name) {
+	return typeof window === "undefined" ? void 0 : Reflect.get(window, name);
+}
+function browserTimers() {
+	if (typeof window === "undefined") return void 0;
+	const target = window;
+	return {
+		setTimeout: (callback, delayMs) => target.setTimeout(callback, delayMs),
+		clearTimeout: (handle) => {
+			if (typeof handle === "number") target.clearTimeout(handle);
+		}
+	};
+}
+function validatePriority(priority) {
+	if (priority !== void 0 && !PRIORITIES.includes(priority)) throw new TypeError(`[VIZE_COMPOSE_POST_TASK_INVALID_PRIORITY] priority must be one of ${PRIORITIES.join(", ")}, received ${String(priority)}`);
+}
+/**
+* Post prioritized tasks with the Prioritized Task Scheduling API.
+*
+* Every task gets its own controller (a `TaskController` when available),
+* so `setPriority` re-prioritizes pending tasks and `abort` rejects them;
+* pending tasks are aborted when the owning reactive scope stops (their
+* promises reject with an AbortError; outside a scope the caller owns
+* `abort()`).
+*
+* Fallback without `scheduler`: tasks run from `setTimeout(delay)` in
+* timer (FIFO) order. Priorities are ignored, so a later "user-blocking"
+* task does not overtake an earlier "background" one, and tasks do not
+* yield to rendering or input the way native tasks do.
+*
+* Server rendering: nothing is scheduled, `supported` is false and
+* `postTask` rejects.
+*
+* @example
+* ```ts
+* const { postTask } = useSchedulerPostTask();
+* const total = await postTask(() => expensiveSum(rows), { priority: "background" });
+* ```
+*
+* @param options Hosts and the initial priority.
+* @default options {}
+* @returns Task state and actions.
+*/
+function useSchedulerPostTask(options = {}) {
+	validatePriority(options.priority);
+	const priority = shallowRef(options.priority ?? "user-visible");
+	const pending = shallowRef(0);
+	const tasks = /* @__PURE__ */ new Set();
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const resolveScheduler = () => {
+		if (!hydrated.value) return void 0;
+		const candidate = options.scheduler === void 0 ? browserGlobal("scheduler") : toValue(options.scheduler);
+		return isScheduler(candidate) ? candidate : void 0;
+	};
+	const resolveTaskController = () => {
+		if (!hydrated.value) return void 0;
+		const candidate = options.TaskController === void 0 ? browserGlobal("TaskController") : unref(options.TaskController);
+		return isTaskControllerHost(candidate) ? candidate : void 0;
+	};
+	const resolveTimers = () => options.timers === void 0 ? browserTimers() : toValue(options.timers) ?? void 0;
+	const postTask = (callback, callOptions = {}) => {
+		const { delay, signal } = callOptions;
+		validatePriority(callOptions.priority);
+		if (delay !== void 0 && (!Number.isFinite(delay) || delay < 0)) throw new RangeError(`[VIZE_COMPOSE_POST_TASK_INVALID_DELAY] delay must be a finite, non-negative number, received ${String(delay)}`);
+		const scheduler = resolveScheduler();
+		const timers = scheduler ? void 0 : resolveTimers();
+		if (!scheduler && !timers) return Promise.reject(/* @__PURE__ */ new Error("[VIZE_COMPOSE_POST_TASK_UNAVAILABLE] neither scheduler.postTask nor timers are available"));
+		const TaskController = resolveTaskController();
+		const taskPriority = callOptions.priority ?? priority.value;
+		const controller = TaskController ? new TaskController({ priority: taskPriority }) : new AbortController();
+		const task = {
+			controller,
+			fixed: callOptions.priority !== void 0
+		};
+		const forwardAbort = () => controller.abort(signal?.reason);
+		if (signal?.aborted) forwardAbort();
+		else signal?.addEventListener("abort", forwardAbort, { once: true });
+		tasks.add(task);
+		pending.value = tasks.size;
+		let result;
+		if (scheduler) {
+			const explicitPriority = task.fixed || !TaskController ? { priority: taskPriority } : {};
+			try {
+				result = scheduler.postTask(callback, {
+					signal: controller.signal,
+					...explicitPriority,
+					...delay === void 0 ? {} : { delay }
+				});
+			} catch (cause) {
+				signal?.removeEventListener("abort", forwardAbort);
+				tasks.delete(task);
+				pending.value = tasks.size;
+				return Promise.reject(cause);
+			}
+		} else result = new Promise((resolve, reject) => {
+			const taskSignal = controller.signal;
+			if (taskSignal.aborted) {
+				reject(taskSignal.reason);
+				return;
+			}
+			const onAbort = () => {
+				timers?.clearTimeout(handle);
+				reject(taskSignal.reason);
+			};
+			const handle = timers?.setTimeout(() => {
+				taskSignal.removeEventListener("abort", onAbort);
+				try {
+					resolve(callback());
+				} catch (cause) {
+					reject(cause);
+				}
+			}, delay ?? 0);
+			taskSignal.addEventListener("abort", onAbort, { once: true });
+		});
+		const settle = () => {
+			signal?.removeEventListener("abort", forwardAbort);
+			tasks.delete(task);
+			pending.value = tasks.size;
+		};
+		return result.then((value) => {
+			settle();
+			return value;
+		}, (cause) => {
+			settle();
+			throw cause;
+		});
+	};
+	const setPriority = (next) => {
+		validatePriority(next);
+		priority.value = next;
+		for (const task of tasks) {
+			if (task.fixed || !isTaskController(task.controller)) continue;
+			try {
+				task.controller.setPriority(next);
+			} catch {}
+		}
+	};
+	const abort = (reason) => {
+		for (const task of Array.from(tasks)) task.controller.abort(reason);
+	};
+	const yieldTask = () => {
+		const scheduler = resolveScheduler();
+		if (scheduler?.yield) return scheduler.yield();
+		const timers = resolveTimers();
+		if (!timers) return Promise.resolve();
+		return new Promise((resolve) => {
+			timers.setTimeout(resolve, 0);
+		});
+	};
+	tryOnScopeDispose(() => abort());
+	return {
+		supported: computed(() => resolveScheduler() !== void 0),
+		priority: readonly(priority),
+		pending: readonly(pending),
+		postTask,
+		setPriority,
+		abort,
+		yield: yieldTask
+	};
+}
+//#endregion
+export { useSchedulerPostTask };

package/dist/use-screen-details.d.mts

@@ -0,0 +1,205 @@
+import { ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+//#region src/use-screen-details.d.ts
+/** Available (work) area of a screen in multi-screen coordinates. */
+interface ScreenArea {
+  /** Left edge of the available area. */
+  readonly availLeft: number;
+  /** Top edge of the available area. */
+  readonly availTop: number;
+  /** Width of the available area. */
+  readonly availWidth: number;
+  /** Height of the available area. */
+  readonly availHeight: number;
+}
+/** Plain snapshot of a `ScreenDetailed`. */
+interface ScreenSnapshot extends ScreenArea {
+  /** Human-readable label, possibly empty. */
+  readonly label: string;
+  /** Left edge in multi-screen coordinates. */
+  readonly left: number;
+  /** Top edge in multi-screen coordinates. */
+  readonly top: number;
+  /** Full width. */
+  readonly width: number;
+  /** Full height. */
+  readonly height: number;
+  /** Device pixel ratio. */
+  readonly devicePixelRatio: number;
+  /** Color depth in bits. */
+  readonly colorDepth: number;
+  /** Whether this is the primary screen. */
+  readonly isPrimary: boolean;
+  /** Whether this screen is built into the device. */
+  readonly isInternal: boolean;
+}
+/** Minimal `ScreenDetailed`. */
+interface ScreenDetailedLike extends ScreenSnapshot, EventTarget {}
+/** Minimal `ScreenDetails`. */
+interface ScreenDetailsLike extends EventTarget {
+  /** Every connected screen. */
+  readonly screens: readonly ScreenDetailedLike[];
+  /** Screen hosting the current window. */
+  readonly currentScreen: ScreenDetailedLike;
+}
+/** Capabilities used by {@link useScreenDetails}. */
+interface ScreenDetailsHost {
+  /** Window Management entry point (permission-gated). */
+  getScreenDetails?(): Promise<ScreenDetailsLike>;
+  /**
+   * `window.screen`. Its `isExtended` flag is read and, when it is an
+   * `EventTarget`, its `change` event refreshes the flag.
+   */
+  readonly screen?: object | null;
+  /** `window.open`, used by `openOnScreen`. */
+  open?(url: string, target: string, features: string): Window | null;
+}
+/** Options for {@link useScreenDetails}. */
+interface UseScreenDetailsOptions {
+  /**
+   * Window Management capability for alternate runtimes and tests.
+   *
+   * @default window
+   */
+  readonly host?: MaybeRefOrGetter<ScreenDetailsHost | null | undefined>;
+}
+/** Desired window geometry relative to a screen's available area. */
+interface WindowPlacementOptions {
+  /**
+   * Window width, clamped to the available width.
+   *
+   * @default the available width
+   */
+  readonly width?: number;
+  /**
+   * Window height, clamped to the available height.
+   *
+   * @default the available height
+   */
+  readonly height?: number;
+  /**
+   * Offset from the available area's left edge.
+   *
+   * @default centered horizontally
+   */
+  readonly left?: number;
+  /**
+   * Offset from the available area's top edge.
+   *
+   * @default centered vertically
+   */
+  readonly top?: number;
+}
+/** Absolute window geometry for `window.open` features or `moveTo`/`resizeTo`. */
+interface WindowPlacement {
+  /** Absolute left. */
+  readonly left: number;
+  /** Absolute top. */
+  readonly top: number;
+  /** Width. */
+  readonly width: number;
+  /** Height. */
+  readonly height: number;
+}
+/** Options of {@link ScreenDetailsControls.openOnScreen}. */
+interface OpenOnScreenOptions extends WindowPlacementOptions {
+  /**
+   * Browsing context name.
+   *
+   * @default "_blank"
+   */
+  readonly target?: string;
+  /**
+   * Extra comma-separated window features, for example `"popup"`.
+   *
+   * @default ""
+   */
+  readonly features?: string;
+}
+/** Discriminated outcome of {@link ScreenDetailsControls.request}. */
+type ScreenDetailsResult = {
+  /** Permission granted; state is live. */readonly status: "granted"; /** Screen snapshots. */
+  readonly screens: readonly ScreenSnapshot[];
+} | {
+  /** `denied`: permission refused; `unsupported`: no API; `failed`: anything else. */readonly status: "denied" | "unsupported" | "failed"; /** Error thrown by the host, when one was thrown. */
+  readonly error: unknown;
+};
+/** Reactive state and actions returned by {@link useScreenDetails}. */
+interface ScreenDetailsControls {
+  /** Whether the Window Management API is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Whether the window spans a multi-screen setup (`screen.isExtended`). */
+  readonly isExtended: Readonly<Ref<boolean>>;
+  /** Snapshots of every screen, empty until `request` succeeds. */
+  readonly screens: Readonly<ShallowRef<readonly ScreenSnapshot[]>>;
+  /** Snapshot of the current screen, once granted. */
+  readonly currentScreen: Readonly<ShallowRef<ScreenSnapshot | undefined>>;
+  /** Whether `request` is in progress. */
+  readonly pending: Readonly<Ref<boolean>>;
+  /** Most recent request failure, cleared on success. */
+  readonly error: Readonly<ShallowRef<unknown>>;
+  /**
+   * Request screen details (prompts for the window-management permission).
+   *
+   * @returns The discriminated outcome; never rejects.
+   */
+  readonly request: () => Promise<ScreenDetailsResult>;
+  /**
+   * Open a window placed on `screen`.
+   *
+   * @param url URL to open.
+   * @param screen Target screen (a snapshot or any {@link ScreenArea}).
+   * @param options Placement, target name, and extra features.
+   * @returns The opened window, or `null` when blocked or unsupported.
+   */
+  readonly openOnScreen: (url: string, screen: ScreenArea, options?: OpenOnScreenOptions) => Window | null;
+  /** Remove every listener. Idempotent. */
+  readonly stop: () => void;
+}
+/**
+ * Snapshot a `ScreenDetailed` into a plain object.
+ *
+ * @param screen Screen to copy.
+ * @returns Plain snapshot.
+ */
+declare function snapshotScreen(screen: ScreenSnapshot): ScreenSnapshot;
+/**
+ * Compute absolute window geometry inside a screen's available area.
+ *
+ * Sizes are clamped to the available area; omitted offsets center the window.
+ *
+ * @param screen Target screen area.
+ * @param placement Desired size and offsets.
+ * @default placement {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_SCREEN_DETAILS_INVALID_PLACEMENT` for negative or non-finite values.
+ * @returns Absolute placement.
+ */
+declare function placeWindow(screen: ScreenArea, placement?: WindowPlacementOptions): WindowPlacement;
+/**
+ * Enumerate and target multiple screens with the Window Management API.
+ *
+ * `isExtended` is live from `window.screen`. `request()` asks for the
+ * window-management permission; once granted, `screens` and
+ * `currentScreen` stay current through `screenschange`,
+ * `currentscreenchange`, and per-screen `change` events. `openOnScreen`
+ * opens a window placed with {@link placeWindow}. Listeners are removed when
+ * the owning reactive scope stops; outside a scope call `stop()`.
+ *
+ * Server rendering: nothing is requested, `supported` and `isExtended` are
+ * false and `screens` is empty.
+ *
+ * @example
+ * ```ts
+ * const { request, screens, openOnScreen } = useScreenDetails();
+ * await request();
+ * const external = screens.value.find((screen) => !screen.isPrimary);
+ * if (external) openOnScreen("/slides", external, { features: "popup" });
+ * ```
+ *
+ * @param options Capability host.
+ * @default options {}
+ * @returns Screen state and actions.
+ */
+declare function useScreenDetails(options?: UseScreenDetailsOptions): ScreenDetailsControls;
+//#endregion
+export { OpenOnScreenOptions, ScreenArea, ScreenDetailedLike, ScreenDetailsControls, ScreenDetailsHost, ScreenDetailsLike, ScreenDetailsResult, ScreenSnapshot, UseScreenDetailsOptions, WindowPlacement, WindowPlacementOptions, placeWindow, snapshotScreen, useScreenDetails };

package/dist/use-screen-details.mjs

@@ -0,0 +1,188 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { computed, hasInjectionContext, readonly, ref, shallowRef, toValue, watch, watchPostEffect } from "vue";
+//#region src/use-screen-details.ts
+/**
+* Snapshot a `ScreenDetailed` into a plain object.
+*
+* @param screen Screen to copy.
+* @returns Plain snapshot.
+*/
+function snapshotScreen(screen) {
+	return {
+		label: screen.label,
+		left: screen.left,
+		top: screen.top,
+		width: screen.width,
+		height: screen.height,
+		availLeft: screen.availLeft,
+		availTop: screen.availTop,
+		availWidth: screen.availWidth,
+		availHeight: screen.availHeight,
+		devicePixelRatio: screen.devicePixelRatio,
+		colorDepth: screen.colorDepth,
+		isPrimary: screen.isPrimary,
+		isInternal: screen.isInternal
+	};
+}
+/**
+* Compute absolute window geometry inside a screen's available area.
+*
+* Sizes are clamped to the available area; omitted offsets center the window.
+*
+* @param screen Target screen area.
+* @param placement Desired size and offsets.
+* @default placement {}
+* @throws `RangeError` tagged `VIZE_COMPOSE_SCREEN_DETAILS_INVALID_PLACEMENT` for negative or non-finite values.
+* @returns Absolute placement.
+*/
+function placeWindow(screen, placement = {}) {
+	for (const value of [
+		placement.width,
+		placement.height,
+		placement.left,
+		placement.top
+	]) if (value !== void 0 && (!Number.isFinite(value) || value < 0)) throw new RangeError(`[VIZE_COMPOSE_SCREEN_DETAILS_INVALID_PLACEMENT] placement values must be finite and non-negative; received ${String(value)}`);
+	const width = Math.round(Math.min(placement.width ?? screen.availWidth, screen.availWidth));
+	const height = Math.round(Math.min(placement.height ?? screen.availHeight, screen.availHeight));
+	const left = placement.left ?? (screen.availWidth - width) / 2;
+	const top = placement.top ?? (screen.availHeight - height) / 2;
+	return {
+		left: Math.round(screen.availLeft + Math.min(left, screen.availWidth - width)),
+		top: Math.round(screen.availTop + Math.min(top, screen.availHeight - height)),
+		width,
+		height
+	};
+}
+function browserHost() {
+	return typeof window === "undefined" ? void 0 : window;
+}
+function errorName(error) {
+	return typeof error === "object" && error !== null && "name" in error ? error.name : void 0;
+}
+/**
+* Enumerate and target multiple screens with the Window Management API.
+*
+* `isExtended` is live from `window.screen`. `request()` asks for the
+* window-management permission; once granted, `screens` and
+* `currentScreen` stay current through `screenschange`,
+* `currentscreenchange`, and per-screen `change` events. `openOnScreen`
+* opens a window placed with {@link placeWindow}. Listeners are removed when
+* the owning reactive scope stops; outside a scope call `stop()`.
+*
+* Server rendering: nothing is requested, `supported` and `isExtended` are
+* false and `screens` is empty.
+*
+* @example
+* ```ts
+* const { request, screens, openOnScreen } = useScreenDetails();
+* await request();
+* const external = screens.value.find((screen) => !screen.isPrimary);
+* if (external) openOnScreen("/slides", external, { features: "popup" });
+* ```
+*
+* @param options Capability host.
+* @default options {}
+* @returns Screen state and actions.
+*/
+function useScreenDetails(options = {}) {
+	const isExtended = ref(false);
+	const screens = shallowRef([]);
+	const currentScreen = shallowRef(void 0);
+	const pending = ref(false);
+	const error = shallowRef(void 0);
+	let unbind;
+	let stopped = false;
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const resolveHost = () => !hydrated.value ? void 0 : options.host === void 0 ? browserHost() : toValue(options.host) ?? void 0;
+	const bind = (details) => {
+		unbind?.();
+		let watched = [];
+		const sync = () => {
+			for (const screen of watched) screen.removeEventListener("change", sync);
+			watched = details.screens;
+			for (const screen of watched) screen.addEventListener("change", sync);
+			screens.value = watched.map(snapshotScreen);
+			currentScreen.value = snapshotScreen(details.currentScreen);
+		};
+		sync();
+		details.addEventListener("screenschange", sync);
+		details.addEventListener("currentscreenchange", sync);
+		unbind = () => {
+			for (const screen of watched) screen.removeEventListener("change", sync);
+			details.removeEventListener("screenschange", sync);
+			details.removeEventListener("currentscreenchange", sync);
+		};
+	};
+	const request = async () => {
+		const host = resolveHost();
+		if (!host?.getScreenDetails) return {
+			status: "unsupported",
+			error: void 0
+		};
+		pending.value = true;
+		try {
+			const details = await host.getScreenDetails();
+			if (stopped) return {
+				status: "failed",
+				error: void 0
+			};
+			bind(details);
+			error.value = void 0;
+			return {
+				status: "granted",
+				screens: screens.value
+			};
+		} catch (cause) {
+			error.value = cause;
+			return {
+				status: errorName(cause) === "NotAllowedError" ? "denied" : "failed",
+				error: cause
+			};
+		} finally {
+			pending.value = false;
+		}
+	};
+	const openOnScreen = (url, screen, openOptions = {}) => {
+		const host = resolveHost();
+		if (!host?.open) return null;
+		const { left, top, width, height } = placeWindow(screen, openOptions);
+		const features = [`left=${left},top=${top},width=${width},height=${height}`];
+		if (openOptions.features) features.push(openOptions.features);
+		return host.open(url, openOptions.target ?? "_blank", features.join(","));
+	};
+	const stopWatch = watch(() => resolveHost()?.screen ?? void 0, (screen, _previous, onCleanup) => {
+		const sync = () => {
+			isExtended.value = screen !== void 0 && "isExtended" in screen && screen.isExtended === true;
+		};
+		sync();
+		if (!(screen instanceof EventTarget)) return;
+		screen.addEventListener("change", sync);
+		onCleanup(() => screen.removeEventListener("change", sync));
+	}, {
+		immediate: true,
+		flush: "sync"
+	});
+	const stop = () => {
+		stopped = true;
+		stopWatch();
+		unbind?.();
+		unbind = void 0;
+	};
+	tryOnScopeDispose(stop);
+	return {
+		supported: computed(() => typeof resolveHost()?.getScreenDetails === "function"),
+		isExtended: readonly(isExtended),
+		screens: readonly(screens),
+		currentScreen: readonly(currentScreen),
+		pending: readonly(pending),
+		error: readonly(error),
+		request,
+		openOnScreen,
+		stop
+	};
+}
+//#endregion
+export { placeWindow, snapshotScreen, useScreenDetails };