@vizejs/composable 0.426.2 → 0.427.0

package/dist/watch-once.d.mts

@@ -0,0 +1,29 @@
+import { WatchHelperCallback, WatchSources } from "./watch-source.mjs";
+import { WatchHandle, WatchOptions } from "vue";
+
+//#region src/watch-once.d.ts
+/** Options for {@link watchOnce}: Vue watch options without `once`. */
+type WatchOnceOptions<Immediate extends boolean = false> = Omit<WatchOptions<Immediate>, "once">;
+/**
+ * Watch sources like Vue's `watch`, delivering exactly one change and then
+ * stopping.
+ *
+ * A thin, typed shorthand for `watch(source, callback, { once: true })`:
+ * with `immediate: true` the single call is the immediate one. The returned
+ * handle can stop the watcher before it fires. Safe during server rendering
+ * and bound to the owning reactive scope.
+ *
+ * @example
+ * ```ts
+ * watchOnce(user, (loaded) => track("first-user", loaded.id));
+ * ```
+ *
+ * @param source Ref, getter, reactive object, or tuple of those.
+ * @param callback Called at most once.
+ * @param options Vue watch options except `once`.
+ * @default options {}
+ * @returns Vue's watch handle.
+ */
+declare function watchOnce<const Sources extends WatchSources, Immediate extends Readonly<boolean> = false>(source: Sources, callback: WatchHelperCallback<Sources, Immediate>, options?: WatchOnceOptions<Immediate>): WatchHandle;
+//#endregion
+export { WatchOnceOptions, watchOnce };

package/dist/watch-once.mjs

@@ -0,0 +1,10 @@
+import { watch } from "vue";
+//#region src/watch-once.ts
+function watchOnce(source, callback, options = {}) {
+	return watch(source, callback, {
+		...options,
+		once: true
+	});
+}
+//#endregion
+export { watchOnce };

package/dist/watch-pausable.d.mts

@@ -0,0 +1,51 @@
+import { WatchHelperCallback, WatchSources } from "./watch-source.mjs";
+import { ShallowRef, WatchOptions } from "vue";
+
+//#region src/watch-pausable.d.ts
+/** Controls returned by {@link watchPausable}. */
+interface PausableWatchHandle {
+  /** Whether changes are currently delivered to the callback. */
+  readonly isActive: Readonly<ShallowRef<boolean>>;
+  /** Drop changes until {@link PausableWatchHandle.resume}. Idempotent. */
+  readonly pause: () => void;
+  /** Deliver changes again. Changes made while paused are not replayed. */
+  readonly resume: () => void;
+  /** Stop watching permanently. */
+  readonly stop: () => void;
+}
+/** Options for {@link watchPausable}. */
+interface WatchPausableOptions<Immediate extends boolean = false> extends WatchOptions<Immediate> {
+  /**
+   * Start in the paused state.
+   *
+   * @default false
+   */
+  readonly initiallyPaused?: boolean;
+}
+/**
+ * Watch sources like Vue's `watch`, with pause and resume.
+ *
+ * Unlike the `pause()` built into Vue 3.5 watch handles, which delivers one
+ * catch-up call on resume, changes made while paused are dropped: the
+ * callback only ever sees changes that happened while active. The old value
+ * passed after a resume is the value from the most recent change Vue
+ * observed, whether or not it was delivered. The watcher follows the owning
+ * reactive scope and is safe during server rendering.
+ *
+ * @example
+ * ```ts
+ * const { pause, resume } = watchPausable(form, persist, { deep: true });
+ * pause();
+ * form.name = "x"; // not persisted
+ * resume();
+ * ```
+ *
+ * @param source Ref, getter, reactive object, or tuple of those.
+ * @param callback Watch callback, skipped while paused.
+ * @param options Watch options plus the initial pause state.
+ * @default options {}
+ * @returns Pause, resume, and stop controls with the active flag.
+ */
+declare function watchPausable<const Sources extends WatchSources, Immediate extends Readonly<boolean> = false>(source: Sources, callback: WatchHelperCallback<Sources, Immediate>, options?: WatchPausableOptions<Immediate>): PausableWatchHandle;
+//#endregion
+export { PausableWatchHandle, WatchPausableOptions, watchPausable };

package/dist/watch-pausable.mjs

@@ -0,0 +1,23 @@
+import { shallowRef, watch } from "vue";
+//#region src/watch-pausable.ts
+function watchPausable(source, callback, options = {}) {
+	const { initiallyPaused = false, ...watchOptions } = options;
+	const isActive = shallowRef(!initiallyPaused);
+	const handle = watch(source, (value, oldValue, onCleanup) => {
+		if (isActive.value) callback(value, oldValue, onCleanup);
+	}, watchOptions);
+	return {
+		isActive,
+		pause: () => {
+			isActive.value = false;
+		},
+		resume: () => {
+			isActive.value = true;
+		},
+		stop: () => {
+			handle.stop();
+		}
+	};
+}
+//#endregion
+export { watchPausable };

package/dist/watch-source.d.mts

@@ -0,0 +1,29 @@
+import { WatchCallback, WatchSource } from "vue";
+
+//#region src/watch-source.d.ts
+/** A single source accepted by Vue's `watch`: ref, getter, or reactive object. */
+type WatchSourceInput = WatchSource<unknown> | object;
+/** Every source shape accepted by the watch helpers, including tuples. */
+type WatchSources = WatchSourceInput | readonly WatchSourceInput[];
+/**
+ * Value observed from a single source: the ref/getter value, or the reactive
+ * object itself.
+ */
+type WatchSourceValue<Source> = Source extends WatchSource<infer Value> ? Value : Source extends object ? Source : never;
+/**
+ * Value delivered to a watch callback for {@link WatchSources}: a tuple
+ * source maps element-wise, any other source resolves through
+ * {@link WatchSourceValue}.
+ */
+type WatchValue<Sources> = Sources extends readonly unknown[] ? { -readonly [Index in keyof Sources]: WatchSourceValue<Sources[Index]> } : WatchSourceValue<Sources>;
+/**
+ * Previous value delivered to a watch callback: `undefined` is added only
+ * when the watcher runs immediately (tuples get it per element, as in Vue).
+ */
+type WatchOldValue<Sources, Immediate> = Immediate extends true ? Sources extends readonly unknown[] ? { -readonly [Index in keyof Sources]: WatchSourceValue<Sources[Index]> | undefined } : WatchSourceValue<Sources> | undefined : WatchValue<Sources>;
+/** Callback typed from its sources and the `immediate` flag. */
+type WatchHelperCallback<Sources, Immediate = false> = WatchCallback<WatchValue<Sources>, WatchOldValue<Sources, Immediate>>;
+/** Cleanup registrar passed as the third argument of a watch callback. */
+type WatchCleanupRegistrar = Parameters<WatchCallback>[2];
+//#endregion
+export { WatchCleanupRegistrar, WatchHelperCallback, WatchOldValue, WatchSourceInput, WatchSourceValue, WatchSources, WatchValue };

package/dist/watch-source.mjs

@@ -0,0 +1 @@
+export {};

package/dist/watch-throttled.d.mts

@@ -0,0 +1,70 @@
+import { t as TimeoutScheduler } from "./timeout-scheduler-CI8RVLZs.mjs";
+import { WatchHelperCallback, WatchSources } from "./watch-source.mjs";
+import { TimedWatchHandle } from "./watch-debounced.mjs";
+import { MaybeRefOrGetter, WatchOptions } from "vue";
+
+//#region src/watch-throttled.d.ts
+/** Options for {@link watchThrottled}. */
+interface WatchThrottledOptions<Immediate extends boolean = false> extends WatchOptions<Immediate> {
+  /**
+   * Cooldown window in milliseconds. Reactive; read whenever a window opens.
+   *
+   * @default 0
+   */
+  readonly throttle?: MaybeRefOrGetter<number>;
+  /**
+   * Run the first change of a window immediately.
+   *
+   * @default true
+   */
+  readonly leading?: boolean;
+  /**
+   * Run the newest change collected during a window when it closes.
+   *
+   * @default true
+   */
+  readonly trailing?: boolean;
+  /**
+   * Applies the timing policy when no browser `window` is available. When
+   * disabled, the callback runs synchronously on the server.
+   *
+   * @default false
+   */
+  readonly runOnServer?: boolean;
+  /**
+   * Owns the cooldown timer.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+}
+/**
+ * Watch sources like Vue's `watch`, but run the callback at most once per
+ * cooldown window.
+ *
+ * With the defaults (`leading` and `trailing` both on) the first change runs
+ * immediately and the newest change inside the window runs when it closes,
+ * which opens a new window. Every call receives, as its old value, the value
+ * of the previously delivered call, so consecutive calls chain without gaps. Source
+ * typing mirrors `watch`.
+ *
+ * Without a browser `window` (and without `runOnServer`) the callback runs
+ * synchronously. Timers are cleared when the watcher stops or the owning
+ * scope is disposed.
+ *
+ * @example
+ * ```ts
+ * watchThrottled(scrollY, (y) => report(y), { throttle: 100 });
+ * ```
+ *
+ * @param source Ref, getter, reactive object, or tuple of those.
+ * @param callback Throttled watch callback.
+ * @param options Watch options plus the throttle policy.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_WATCH_THROTTLED_INVALID_DELAY`
+ * when `throttle` resolves to a negative or non-finite value.
+ * @returns Stop, flush, and cancel controls.
+ */
+declare function watchThrottled<const Sources extends WatchSources, Immediate extends Readonly<boolean> = false>(source: Sources, callback: WatchHelperCallback<Sources, Immediate>, options?: WatchThrottledOptions<Immediate>): TimedWatchHandle;
+//#endregion
+export { WatchThrottledOptions, watchThrottled };

package/dist/watch-throttled.mjs

@@ -0,0 +1,94 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { toValue, watch } from "vue";
+//#region src/watch-throttled.ts
+const defaultScheduler = {
+	setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+	clearTimeout: (handle) => {
+		globalThis.clearTimeout(handle);
+	}
+};
+function resolveThrottleMs(value) {
+	if (!Number.isFinite(value) || value < 0) throw new RangeError(`[VIZE_COMPOSE_WATCH_THROTTLED_INVALID_DELAY] throttle must be finite and at least zero; received ${String(value)}`);
+	return Math.trunc(value);
+}
+function watchThrottled(source, callback, options = {}) {
+	const { throttle = 0, leading = true, trailing = true, runOnServer = false, scheduler = defaultScheduler, ...watchOptions } = options;
+	resolveThrottleMs(toValue(throttle));
+	let timer;
+	let pending;
+	let lastDelivered;
+	let pendingOld;
+	let delivered = false;
+	let cleanup;
+	const invoke = (value, oldValue) => {
+		const runCleanup = cleanup;
+		cleanup = void 0;
+		runCleanup?.();
+		lastDelivered = value;
+		delivered = true;
+		const onCleanup = (fn) => {
+			cleanup = fn;
+		};
+		callback(value, oldValue, onCleanup);
+	};
+	const closeWindow = () => {
+		timer = void 0;
+		const run = pending;
+		pending = void 0;
+		if (run === void 0) return;
+		run();
+		openWindow();
+	};
+	function openWindow() {
+		timer = scheduler.setTimeout(closeWindow, resolveThrottleMs(toValue(throttle)));
+	}
+	const cancel = () => {
+		if (timer !== void 0) scheduler.clearTimeout(timer);
+		timer = void 0;
+		const hadPending = pending !== void 0;
+		pending = void 0;
+		return hadPending;
+	};
+	const flush = () => {
+		const run = pending;
+		if (run === void 0) return false;
+		pending = void 0;
+		run();
+		return true;
+	};
+	const schedule = (value, previous) => {
+		pending = () => {
+			invoke(value, previous);
+		};
+		pendingOld = previous;
+	};
+	const handle = watch(source, (value, oldValue) => {
+		if (typeof window === "undefined" && !runOnServer) {
+			invoke(value, oldValue);
+			return;
+		}
+		const previous = pending === void 0 ? delivered ? lastDelivered : oldValue : pendingOld;
+		if (timer === void 0) {
+			if (leading) invoke(value, previous);
+			else if (trailing) schedule(value, previous);
+			openWindow();
+			return;
+		}
+		if (trailing) schedule(value, previous);
+	}, watchOptions);
+	const stop = () => {
+		handle.stop();
+		cancel();
+		const runCleanup = cleanup;
+		cleanup = void 0;
+		runCleanup?.();
+	};
+	tryOnScopeDispose(stop);
+	return {
+		stop,
+		flush,
+		cancel
+	};
+}
+//#endregion
+export { watchThrottled };

package/dist/whenever.d.mts

@@ -0,0 +1,39 @@
+import { WatchCleanupRegistrar } from "./watch-source.mjs";
+import { WatchHandle, WatchOptions, WatchSource } from "vue";
+
+//#region src/whenever.d.ts
+/** Values treated as "not yet" by {@link whenever}. */
+type Falsy = false | 0 | 0n | "" | null | undefined;
+/** Options for {@link whenever}. */
+type WheneverOptions = Omit<WatchOptions<boolean>, "once"> & {
+  /**
+   * Stop after the first truthy delivery instead of after the first change.
+   *
+   * @default false
+   */
+  readonly once?: boolean;
+};
+/**
+ * Run a callback whenever a source becomes (or changes while) truthy.
+ *
+ * The callback's value is narrowed with `Exclude<Value, Falsy>`, so a
+ * `Ref<User | null>` delivers `User`. With `once`, the watcher stops after
+ * the first truthy delivery, not after the first change (unlike Vue's
+ * `once`). With `immediate`, an already-truthy source is delivered right
+ * away. Safe during server rendering and bound to the owning scope.
+ *
+ * @example
+ * ```ts
+ * whenever(currentUser, (user) => greet(user.name), { immediate: true, once: true });
+ * ```
+ *
+ * @param source Ref or getter.
+ * @param callback Receives the truthy value, the previous value, and
+ * `onCleanup`.
+ * @param options Vue watch options; `once` counts truthy deliveries only.
+ * @default options {}
+ * @returns Vue's watch handle.
+ */
+declare function whenever<Value>(source: WatchSource<Value>, callback: (value: Exclude<Value, Falsy>, oldValue: Value | undefined, onCleanup: WatchCleanupRegistrar) => void, options?: WheneverOptions): WatchHandle;
+//#endregion
+export { Falsy, WheneverOptions, whenever };

package/dist/whenever.mjs

@@ -0,0 +1,41 @@
+import { watch } from "vue";
+//#region src/whenever.ts
+/**
+* Run a callback whenever a source becomes (or changes while) truthy.
+*
+* The callback's value is narrowed with `Exclude<Value, Falsy>`, so a
+* `Ref<User | null>` delivers `User`. With `once`, the watcher stops after
+* the first truthy delivery, not after the first change (unlike Vue's
+* `once`). With `immediate`, an already-truthy source is delivered right
+* away. Safe during server rendering and bound to the owning scope.
+*
+* @example
+* ```ts
+* whenever(currentUser, (user) => greet(user.name), { immediate: true, once: true });
+* ```
+*
+* @param source Ref or getter.
+* @param callback Receives the truthy value, the previous value, and
+* `onCleanup`.
+* @param options Vue watch options; `once` counts truthy deliveries only.
+* @default options {}
+* @returns Vue's watch handle.
+*/
+function whenever(source, callback, options = {}) {
+	const { once = false, ...watchOptions } = options;
+	let handle;
+	let stopRequested = false;
+	handle = watch(source, (value, oldValue, onCleanup) => {
+		if (!isTruthy(value)) return;
+		if (once) if (handle === void 0) stopRequested = true;
+		else handle.stop();
+		callback(value, oldValue, onCleanup);
+	}, watchOptions);
+	if (stopRequested) handle.stop();
+	return handle;
+}
+function isTruthy(value) {
+	return Boolean(value);
+}
+//#endregion
+export { whenever };

package/dist/window-size.d.mts

@@ -0,0 +1,87 @@
+import { MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/window-size.d.ts
+/** Window-like capability observed by {@link useWindowSize}. */
+interface WindowSizeHost extends EventTarget {
+  /** Viewport width including the vertical scrollbar. */
+  readonly innerWidth: number;
+  /** Viewport height including the horizontal scrollbar. */
+  readonly innerHeight: number;
+  /** Outer browser window width. */
+  readonly outerWidth: number;
+  /** Outer browser window height. */
+  readonly outerHeight: number;
+  /** Document whose root element reports the scrollbar-free viewport. */
+  readonly document: {
+    readonly documentElement: {
+      readonly clientWidth: number;
+      readonly clientHeight: number;
+    };
+  };
+}
+/** Which window dimensions {@link useWindowSize} reports. */
+type WindowSizeKind = "inner" | "outer";
+/** Options for {@link useWindowSize}. */
+interface UseWindowSizeOptions {
+  /**
+   * Width exposed during server rendering and before hydration.
+   *
+   * @default 0
+   */
+  readonly initialWidth?: number;
+  /**
+   * Height exposed during server rendering and before hydration.
+   *
+   * @default 0
+   */
+  readonly initialHeight?: number;
+  /**
+   * Include scrollbars in the inner dimensions. When `false`, the root
+   * element's `clientWidth`/`clientHeight` are reported instead.
+   *
+   * @default true
+   */
+  readonly includeScrollbar?: boolean;
+  /**
+   * Report inner (viewport) or outer (browser window) dimensions.
+   *
+   * @default "inner"
+   */
+  readonly type?: WindowSizeKind;
+  /**
+   * Also re-measure on `orientationchange` for engines that resize late.
+   *
+   * @default true
+   */
+  readonly listenOrientation?: boolean;
+  /**
+   * Reactive window capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<WindowSizeHost | null | undefined>;
+}
+/** Reactive size returned by {@link useWindowSize}. */
+interface WindowSizeControls {
+  /** Current width in CSS pixels. */
+  readonly width: Readonly<Ref<number>>;
+  /** Current height in CSS pixels. */
+  readonly height: Readonly<Ref<number>>;
+  /** Whether a window capability is attached. `false` during server rendering. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+}
+/**
+ * Track the window size reactively.
+ *
+ * Server renders expose `initialWidth`/`initialHeight` (default `0`), so the
+ * first client render matches; the real size is applied as soon as a window
+ * resolves (after mounting when called inside a component). Resize (and orientation) listeners are passive and removed with
+ * the owning reactive scope.
+ *
+ * @param options Initial size, measurement kind, and capability.
+ * @default options {}
+ * @returns Reactive width/height plus a support flag.
+ */
+declare function useWindowSize(options?: UseWindowSizeOptions): WindowSizeControls;
+//#endregion
+export { UseWindowSizeOptions, WindowSizeControls, WindowSizeHost, WindowSizeKind, useWindowSize };

package/dist/window-size.mjs

@@ -0,0 +1,65 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { hasInjectionContext, onMounted, readonly, ref, toValue, watch } from "vue";
+//#region src/window-size.ts
+/**
+* Track the window size reactively.
+*
+* Server renders expose `initialWidth`/`initialHeight` (default `0`), so the
+* first client render matches; the real size is applied as soon as a window
+* resolves (after mounting when called inside a component). Resize (and orientation) listeners are passive and removed with
+* the owning reactive scope.
+*
+* @param options Initial size, measurement kind, and capability.
+* @default options {}
+* @returns Reactive width/height plus a support flag.
+*/
+function useWindowSize(options = {}) {
+	const { initialWidth = 0, initialHeight = 0, includeScrollbar = true, type = "inner", listenOrientation = true } = options;
+	const width = ref(initialWidth);
+	const height = ref(initialHeight);
+	const isSupported = ref(false);
+	let stopWatch;
+	const start = () => {
+		stopWatch = watch(() => options.host === void 0 ? browserWindowSizeHost() : toValue(options.host), (host, _previous, onCleanup) => {
+			isSupported.value = Boolean(host);
+			if (!host) {
+				width.value = initialWidth;
+				height.value = initialHeight;
+				return;
+			}
+			const update = () => {
+				if (type === "outer") {
+					width.value = host.outerWidth;
+					height.value = host.outerHeight;
+				} else if (includeScrollbar) {
+					width.value = host.innerWidth;
+					height.value = host.innerHeight;
+				} else {
+					width.value = host.document.documentElement.clientWidth;
+					height.value = host.document.documentElement.clientHeight;
+				}
+			};
+			update();
+			const listenerOptions = { passive: true };
+			host.addEventListener("resize", update, listenerOptions);
+			if (listenOrientation) host.addEventListener("orientationchange", update, listenerOptions);
+			onCleanup(() => {
+				host.removeEventListener("resize", update);
+				if (listenOrientation) host.removeEventListener("orientationchange", update);
+			});
+		}, { immediate: true });
+	};
+	if (hasInjectionContext()) onMounted(start);
+	else start();
+	tryOnScopeDispose(() => stopWatch?.stop());
+	return {
+		width: readonly(width),
+		height: readonly(height),
+		isSupported: readonly(isSupported)
+	};
+}
+function browserWindowSizeHost() {
+	return typeof window !== "undefined" ? window : void 0;
+}
+//#endregion
+export { useWindowSize };