@stacksjs/composables 0.70.87 → 0.70.90

package/dist/useWebWorker.js

@@ -0,0 +1,56 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function useWebWorker(url, workerOptions) {
+  const data = ref(null), worker = ref(void 0);
+  if (typeof Worker < "u") {
+    const w = new Worker(url, workerOptions);
+    worker.value = w;
+    w.onmessage = (e) => {
+      data.value = e.data;
+    };
+    try {
+      onUnmounted(() => w.terminate());
+    } catch {}
+  }
+  function post(message) {
+    worker.value?.postMessage(message);
+  }
+  function terminate() {
+    worker.value?.terminate();
+    worker.value = void 0;
+  }
+  return { data, post, terminate, worker };
+}
+export function useWebWorkerFn(fn) {
+  let worker;
+  function createWorker() {
+    const blob = new Blob([`self.onmessage = function(e) { self.postMessage((${fn.toString()})(...e.data)); }`], { type: "text/javascript" }), url = URL.createObjectURL(blob);
+    return new Worker(url);
+  }
+  function workerFn(...args) {
+    return new Promise((resolve, reject) => {
+      if (typeof Worker > "u") {
+        try {
+          resolve(fn(...args));
+        } catch (e) {
+          reject(e);
+        }
+        return;
+      }
+      worker = createWorker();
+      worker.onmessage = (e) => {
+        resolve(e.data);
+        worker?.terminate();
+      };
+      worker.onerror = (e) => {
+        reject(e);
+        worker?.terminate();
+      };
+      worker.postMessage(args);
+    });
+  }
+  function terminate() {
+    worker?.terminate();
+    worker = void 0;
+  }
+  return { workerFn, terminate };
+}

package/dist/useWindowFocus.d.ts

@@ -0,0 +1,5 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactively track whether the window is focused.
+ */
+export declare function useWindowFocus(): Ref<boolean>;

package/dist/useWindowFocus.js

@@ -0,0 +1,20 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function useWindowFocus() {
+  const focused = ref(typeof document < "u" ? document.hasFocus() : !1);
+  if (typeof window > "u")
+    return focused;
+  const onFocus = () => {
+    focused.value = !0;
+  }, onBlur = () => {
+    focused.value = !1;
+  };
+  window.addEventListener("focus", onFocus, { passive: !0 });
+  window.addEventListener("blur", onBlur, { passive: !0 });
+  try {
+    onUnmounted(() => {
+      window.removeEventListener("focus", onFocus);
+      window.removeEventListener("blur", onBlur);
+    });
+  } catch {}
+  return focused;
+}

package/dist/useWindowScroll.d.ts

@@ -0,0 +1,9 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive window scroll position.
+ */
+export declare function useWindowScroll(): UseWindowScrollReturn;
+export declare interface UseWindowScrollReturn {
+  x: Ref<number>
+  y: Ref<number>
+}

package/dist/useWindowScroll.js

@@ -0,0 +1,17 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function useWindowScroll() {
+  const x = ref(typeof window < "u" ? window.scrollX : 0), y = ref(typeof window < "u" ? window.scrollY : 0);
+  if (typeof window > "u")
+    return { x, y };
+  const handler = () => {
+    x.value = window.scrollX;
+    y.value = window.scrollY;
+  };
+  window.addEventListener("scroll", handler, { passive: !0 });
+  try {
+    onUnmounted(() => {
+      window.removeEventListener("scroll", handler);
+    });
+  } catch {}
+  return { x, y };
+}

package/dist/useWindowSize.d.ts

@@ -0,0 +1,15 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive window dimensions.
+ * Tracks window.innerWidth and window.innerHeight.
+ */
+export declare function useWindowSize(options?: UseWindowSizeOptions): UseWindowSizeReturn;
+export declare interface UseWindowSizeOptions {
+  initialWidth?: number
+  initialHeight?: number
+  listenOrientation?: boolean
+}
+export declare interface UseWindowSizeReturn {
+  width: Ref<number>
+  height: Ref<number>
+}

package/dist/useWindowSize.js

@@ -0,0 +1,28 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { defaultWindow } from "./_shared";
+export function useWindowSize(options) {
+  const {
+    initialWidth = 0,
+    initialHeight = 0,
+    listenOrientation = !0
+  } = options ?? {}, win = defaultWindow(), width = ref(win ? win.innerWidth : initialWidth), height = ref(win ? win.innerHeight : initialHeight);
+  function update() {
+    if (win) {
+      width.value = win.innerWidth;
+      height.value = win.innerHeight;
+    }
+  }
+  if (win) {
+    win.addEventListener("resize", update);
+    if (listenOrientation)
+      win.addEventListener("orientationchange", update);
+    try {
+      onUnmounted(() => {
+        win.removeEventListener("resize", update);
+        if (listenOrientation)
+          win.removeEventListener("orientationchange", update);
+      });
+    } catch {}
+  }
+  return { width, height };
+}

package/dist/watchArray.d.ts

@@ -0,0 +1,5 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Watch an array ref and provide added/removed items in the callback.
+ */
+export declare function watchArray<T>(source: Ref<T[]>, callback: (newList: T[], oldList: T[], added: T[], removed: T[]) => void): () => void;

package/dist/watchArray.js

@@ -0,0 +1,9 @@
+import { watch } from "@stacksjs/stx";
+export function watchArray(source, callback) {
+  let oldList = [...source.value];
+  return watch(source, (newValue) => {
+    const newList = [...newValue], added = newList.filter((item) => !oldList.includes(item)), removed = oldList.filter((item) => !newList.includes(item));
+    callback(newList, oldList, added, removed);
+    oldList = newList;
+  });
+}

package/dist/watchAtMost.d.ts

@@ -0,0 +1,5 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Watch a source, but only trigger the callback at most `count` times.
+ */
+export declare function watchAtMost<T>(source: Ref<T>, callback: (value: T) => void, count: number): { stop: () => void, remaining: Ref<number> };

package/dist/watchAtMost.js

@@ -0,0 +1,12 @@
+import { ref, watch } from "@stacksjs/stx";
+export function watchAtMost(source, callback, count) {
+  const remaining = ref(count), unwatch = watch(source, (newValue) => {
+    if (remaining.value > 0) {
+      remaining.value--;
+      callback(newValue);
+      if (remaining.value <= 0)
+        unwatch();
+    }
+  });
+  return { stop: unwatch, remaining };
+}

package/dist/watchDebounced.d.ts

@@ -0,0 +1,23 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Watch a source with debounced callback invocation.
+ * The callback is only called after the source value has stopped changing
+ * for the specified debounce duration.
+ *
+ * @param source - The reactive source to watch
+ * @param callback - The callback to invoke (debounced)
+ * @param options - Configuration options
+ * @returns A stop function that cleans up both the watch and any pending timer
+ *
+ * @example
+ * ```ts
+ * const search = ref('')
+ * watchDebounced(search, (value) => {
+ *   fetchResults(value)
+ * }, { debounce: 300 })
+ * ```
+ */
+export declare function watchDebounced<T>(source: Ref<T>, callback: (value: T) => void, options?: WatchDebouncedOptions): () => void;
+export declare interface WatchDebouncedOptions {
+  debounce?: number
+}

package/dist/watchDebounced.js

@@ -0,0 +1,20 @@
+import { watch } from "@stacksjs/stx";
+export function watchDebounced(source, callback, options) {
+  const delay = options?.debounce ?? 200;
+  let timeoutId = null;
+  const unwatch = watch(source, (newValue) => {
+    if (timeoutId !== null)
+      clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => {
+      timeoutId = null;
+      callback(newValue);
+    }, delay);
+  });
+  return () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+    unwatch();
+  };
+}

package/dist/watchDeep.d.ts

@@ -0,0 +1,7 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Watch a source with deep comparison by serializing to JSON.
+ * Since stx watch is shallow, this provides deep-watch behavior by
+ * comparing JSON serializations.
+ */
+export declare function watchDeep<T>(source: Ref<T>, callback: (value: T) => void, options?: { immediate?: boolean }): () => void;

package/dist/watchDeep.js

@@ -0,0 +1,13 @@
+import { watch } from "@stacksjs/stx";
+export function watchDeep(source, callback, options) {
+  let prev = JSON.stringify(source.value);
+  if (options?.immediate)
+    callback(source.value);
+  return watch(source, (newValue) => {
+    const next = JSON.stringify(newValue);
+    if (next !== prev) {
+      prev = next;
+      callback(newValue);
+    }
+  });
+}

package/dist/watchIgnorable.d.ts

@@ -0,0 +1,12 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * A watch that can temporarily ignore updates.
+ */
+export declare function watchIgnorable<T>(source: Ref<T>, callback: (value: T, oldValue: T | undefined) => void): WatchIgnorableReturn;
+/** Alias for watchIgnorable */
+export declare const ignorableWatch: unknown;
+export declare interface WatchIgnorableReturn {
+  stop: () => void
+  ignoreUpdates: (updater: () => void) => void
+  isIgnoring: Ref<boolean>
+}

package/dist/watchIgnorable.js

@@ -0,0 +1,19 @@
+import { ref, watch } from "@stacksjs/stx";
+export function watchIgnorable(source, callback) {
+  const isIgnoring = ref(!1);
+  let lastValue;
+  const unwatch = watch(source, (newValue) => {
+    if (!isIgnoring.value)
+      callback(newValue, lastValue);
+    lastValue = newValue;
+  });
+  function ignoreUpdates(updater) {
+    isIgnoring.value = !0;
+    updater();
+    Promise.resolve().then(() => {
+      isIgnoring.value = !1;
+    });
+  }
+  return { stop: unwatch, ignoreUpdates, isIgnoring };
+}
+export const ignorableWatch = watchIgnorable;

package/dist/watchImmediate.d.ts

@@ -0,0 +1,5 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Watch a source and call the callback immediately with the current value, then on changes.
+ */
+export declare function watchImmediate<T>(source: Ref<T>, callback: (value: T) => void): () => void;

package/dist/watchImmediate.js

@@ -0,0 +1,7 @@
+import { watch } from "@stacksjs/stx";
+export function watchImmediate(source, callback) {
+  callback(source.value);
+  return watch(source, (newValue) => {
+    callback(newValue);
+  });
+}

package/dist/watchOnce.d.ts

@@ -0,0 +1,19 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Watch a source and automatically stop after the first change.
+ *
+ * @param source - The reactive source to watch
+ * @param callback - The callback to invoke on the first change
+ * @returns A manual stop function (in case you want to stop before first trigger)
+ *
+ * @example
+ * ```ts
+ * const count = ref(0)
+ * watchOnce(count, (value) => {
+ *   console.log('First change:', value)
+ * })
+ * count.value = 1 // callback fires
+ * count.value = 2 // callback does NOT fire
+ * ```
+ */
+export declare function watchOnce<T>(source: Ref<T>, callback: (value: T) => void): () => void;

package/dist/watchOnce.js

@@ -0,0 +1,17 @@
+import { watch } from "@stacksjs/stx";
+export function watchOnce(source, callback) {
+  let stopped = !1;
+  const unwatch = watch(source, (newValue) => {
+    if (stopped)
+      return;
+    stopped = !0;
+    unwatch();
+    callback(newValue);
+  });
+  return () => {
+    if (!stopped) {
+      stopped = !0;
+      unwatch();
+    }
+  };
+}

package/dist/watchPausable.d.ts

@@ -0,0 +1,13 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * A pausable watch.
+ */
+export declare function watchPausable<T>(source: Ref<T>, callback: (value: T, oldValue: T | undefined) => void): WatchPausableReturn;
+/** Alias for watchPausable */
+export declare const pausableWatch: unknown;
+export declare interface WatchPausableReturn {
+  stop: () => void
+  pause: () => void
+  resume: () => void
+  isActive: Ref<boolean>
+}

package/dist/watchPausable.js

@@ -0,0 +1,23 @@
+import { ref, watch } from "@stacksjs/stx";
+export function watchPausable(source, callback) {
+  const isActive = ref(!0);
+  let lastValue;
+  const unwatch = watch(source, (newValue) => {
+    if (isActive.value)
+      callback(newValue, lastValue);
+    lastValue = newValue;
+  });
+  function pause() {
+    isActive.value = !1;
+  }
+  function resume() {
+    isActive.value = !0;
+  }
+  return {
+    stop: unwatch,
+    pause,
+    resume,
+    isActive
+  };
+}
+export const pausableWatch = watchPausable;

package/dist/watchThrottled.d.ts

@@ -0,0 +1,23 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Watch a source with throttled callback invocation.
+ * The callback is called at most once per throttle interval.
+ * A trailing call is scheduled if changes occur during the throttle window.
+ *
+ * @param source - The reactive source to watch
+ * @param callback - The callback to invoke (throttled)
+ * @param options - Configuration options
+ * @returns A stop function that cleans up both the watch and any pending timer
+ *
+ * @example
+ * ```ts
+ * const scrollY = ref(0)
+ * watchThrottled(scrollY, (value) => {
+ *   updateHeader(value)
+ * }, { throttle: 100 })
+ * ```
+ */
+export declare function watchThrottled<T>(source: Ref<T>, callback: (value: T) => void, options?: WatchThrottledOptions): () => void;
+export declare interface WatchThrottledOptions {
+  throttle?: number
+}

package/dist/watchThrottled.js

@@ -0,0 +1,37 @@
+import { watch } from "@stacksjs/stx";
+export function watchThrottled(source, callback, options) {
+  const interval = options?.throttle ?? 200;
+  let lastExec = 0, timeoutId = null, latestValue, hasPending = !1;
+  const unwatch = watch(source, (newValue) => {
+    const now = Date.now(), elapsed = now - lastExec;
+    if (elapsed >= interval) {
+      lastExec = now;
+      if (timeoutId !== null) {
+        clearTimeout(timeoutId);
+        timeoutId = null;
+      }
+      hasPending = !1;
+      callback(newValue);
+    } else {
+      latestValue = newValue;
+      hasPending = !0;
+      if (timeoutId === null)
+        timeoutId = setTimeout(() => {
+          lastExec = Date.now();
+          timeoutId = null;
+          if (hasPending) {
+            hasPending = !1;
+            callback(latestValue);
+          }
+        }, interval - elapsed);
+    }
+  });
+  return () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+    hasPending = !1;
+    unwatch();
+  };
+}

package/dist/watchTriggerable.d.ts

@@ -0,0 +1,5 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * A watch that can also be manually triggered.
+ */
+export declare function watchTriggerable<T>(source: Ref<T>, callback: (value: T) => void): { stop: () => void, trigger: () => void };

package/dist/watchTriggerable.js

@@ -0,0 +1,10 @@
+import { watch } from "@stacksjs/stx";
+export function watchTriggerable(source, callback) {
+  const unwatch = watch(source, (newValue) => {
+    callback(newValue);
+  });
+  function trigger() {
+    callback(source.value);
+  }
+  return { stop: unwatch, trigger };
+}

package/dist/watchWithFilter.d.ts

@@ -0,0 +1,7 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Watch a source with a custom event filter.
+ * The filter receives the invoke function and decides when to call it.
+ */
+export declare function watchWithFilter<T>(source: Ref<T>, callback: (value: T) => void, eventFilter: EventFilter): () => void;
+export type EventFilter = (invoke: () => void) => void;

package/dist/watchWithFilter.js

@@ -0,0 +1,6 @@
+import { watch } from "@stacksjs/stx";
+export function watchWithFilter(source, callback, eventFilter) {
+  return watch(source, (newValue) => {
+    eventFilter(() => callback(newValue));
+  });
+}

package/dist/whenever.d.ts

@@ -0,0 +1,18 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Watch a source and call callback only when the value becomes truthy.
+ *
+ * @param source - The reactive source to watch
+ * @param callback - The callback to invoke when the source value is truthy
+ * @returns An unsubscribe function that stops watching
+ *
+ * @example
+ * ```ts
+ * const isReady = ref(false)
+ * whenever(isReady, (value) => {
+ *   console.log('Ready!', value)
+ * })
+ * isReady.value = true // callback fires
+ * ```
+ */
+export declare function whenever<T>(source: Ref<T>, callback: (value: T) => void): () => void;

package/dist/whenever.js

@@ -0,0 +1,7 @@
+import { watch } from "@stacksjs/stx";
+export function whenever(source, callback) {
+  return watch(source, (newValue) => {
+    if (newValue)
+      callback(newValue);
+  });
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/composables",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.87",
+  "version": "0.70.90",
   "description": "Stacks composables powered by stx reactivity.",
   "author": "Chris Breuer",
   "contributors": [
@@ -53,7 +53,7 @@
   },
   "dependencies": {
     "@stacksjs/stx": "^0.2.82",
-    "@stacksjs/datetime": "0.70.87"
+    "@stacksjs/datetime": "0.70.90"
   },
   "devDependencies": {
     "better-dx": "^0.2.16"