@stacksjs/composables 0.70.87 → 0.70.90

package/dist/useToNumber.js

@@ -0,0 +1,25 @@
+import { computed, ref, watch } from "@stacksjs/stx";
+import { toValue } from "./_shared";
+export function useToNumber(value, options = {}) {
+  const { method = "parseFloat", radix = 10, nanToZero = !1 } = options, result = ref(0);
+  function convert(val) {
+    if (typeof val === "number")
+      return val;
+    let num;
+    if (method === "parseInt")
+      num = Number.parseInt(val, radix);
+    else
+      num = Number.parseFloat(val);
+    if (nanToZero && Number.isNaN(num))
+      return 0;
+    return num;
+  }
+  result.value = convert(toValue(value));
+  if (typeof value === "function")
+    ;
+  else if (value && typeof value === "object" && "value" in value && "subscribe" in value)
+    watch(value, (newVal) => {
+      result.value = convert(newVal);
+    });
+  return result;
+}

package/dist/useToString.d.ts

@@ -0,0 +1,6 @@
+import type { MaybeRefOrGetter } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactively convert a value to a string.
+ */
+export declare function useToString(value: MaybeRefOrGetter<any>): Ref<string>;

package/dist/useToString.js

@@ -0,0 +1,10 @@
+import { ref, watch } from "@stacksjs/stx";
+import { isRef, toValue } from "./_shared";
+export function useToString(value) {
+  const result = ref(String(toValue(value) ?? ""));
+  if (isRef(value))
+    watch(value, (newVal) => {
+      result.value = String(newVal ?? "");
+    });
+  return result;
+}

package/dist/useToggle.d.ts

@@ -0,0 +1,6 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Simple boolean toggle.
+ * Returns [state, toggleFn] where toggleFn flips the boolean or sets a specific value.
+ */
+export declare function useToggle(initialValue?: Ref<boolean> | boolean): [Ref<boolean>, (value?: boolean) => boolean];

package/dist/useToggle.js

@@ -0,0 +1,12 @@
+import { ref } from "@stacksjs/stx";
+export function useToggle(initialValue = !1) {
+  const state = typeof initialValue === "boolean" ? ref(initialValue) : initialValue;
+  function toggle(value) {
+    if (typeof value === "boolean")
+      state.value = value;
+    else
+      state.value = !state.value;
+    return state.value;
+  }
+  return [state, toggle];
+}

package/dist/useTransition.d.ts

@@ -0,0 +1,28 @@
+import type { MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive value transition. Smoothly transitions between values over time.
+ */
+export declare function useTransition(source: MaybeRef<number>, options?: UseTransitionOptions): Ref<number>;
+/**
+ * Execute a transition between values.
+ */
+export declare function executeTransition(_from: number, _to: number, options?: UseTransitionOptions): Promise<void>;
+// Common easing functions
+export declare const TransitionPresets: {
+  linear: (t: number) => number;
+  easeInQuad: (t: number) => number;
+  easeOutQuad: (t: number) => number;
+  easeInOutQuad: (t: number) => number;
+  easeInCubic: (t: number) => number;
+  easeOutCubic: (t: number) => unknown;
+  easeInOutCubic: (t: number) => number
+};
+export declare interface UseTransitionOptions {
+  duration?: number
+  transition?: TransitionFunction
+  delay?: number
+  onFinished?: () => void
+  onStarted?: () => void
+}
+export type TransitionFunction = (_t: number) => number;

package/dist/useTransition.js

@@ -0,0 +1,89 @@
+import { onUnmounted, ref, watch } from "@stacksjs/stx";
+import { unref } from "./_shared";
+export const TransitionPresets = {
+  linear: (t) => t,
+  easeInQuad: (t) => t * t,
+  easeOutQuad: (t) => t * (2 - t),
+  easeInOutQuad: (t) => t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t,
+  easeInCubic: (t) => t * t * t,
+  easeOutCubic: (t) => --t * t * t + 1,
+  easeInOutCubic: (t) => t < 0.5 ? 4 * t * t * t : (t - 1) * (2 * t - 2) * (2 * t - 2) + 1
+};
+export function useTransition(source, options = {}) {
+  const {
+    duration = 300,
+    transition = TransitionPresets.linear,
+    delay = 0,
+    onFinished,
+    onStarted
+  } = options, output = ref(unref(source));
+  let rafId = null;
+  function startTransition(from, to) {
+    if (rafId !== null)
+      cancelAnimationFrame(rafId);
+    const start = performance.now() + delay;
+    onStarted?.();
+    function tick(now) {
+      const elapsed = now - start;
+      if (elapsed < 0) {
+        rafId = requestAnimationFrame(tick);
+        return;
+      }
+      const progress = Math.min(elapsed / duration, 1), eased = transition(progress);
+      output.value = from + (to - from) * eased;
+      if (progress < 1)
+        rafId = requestAnimationFrame(tick);
+      else {
+        rafId = null;
+        output.value = to;
+        onFinished?.();
+      }
+    }
+    rafId = requestAnimationFrame(tick);
+  }
+  if (typeof source === "object" && source && "value" in source && "subscribe" in source)
+    watch(source, (newValue) => {
+      if (typeof requestAnimationFrame < "u")
+        startTransition(output.value, newValue);
+      else
+        output.value = newValue;
+    });
+  try {
+    onUnmounted(() => {
+      if (rafId !== null)
+        cancelAnimationFrame(rafId);
+    });
+  } catch {}
+  return output;
+}
+export function executeTransition(_from, _to, options = {}) {
+  return new Promise((resolve) => {
+    const {
+      duration = 300,
+      transition = TransitionPresets.linear,
+      delay = 0,
+      onFinished,
+      onStarted
+    } = options;
+    if (typeof requestAnimationFrame > "u") {
+      onFinished?.();
+      resolve();
+      return;
+    }
+    const start = performance.now() + delay;
+    onStarted?.();
+    function tick(now) {
+      const elapsed = now - start;
+      if (elapsed < 0) {
+        requestAnimationFrame(tick);
+        return;
+      }
+      if (Math.min(elapsed / duration, 1) >= 1) {
+        onFinished?.();
+        resolve();
+      } else
+        requestAnimationFrame(tick);
+    }
+    requestAnimationFrame(tick);
+  });
+}

package/dist/useUrlSearchParams.d.ts

@@ -0,0 +1,18 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive URL search params.
+ * Reads and writes query string parameters reactively.
+ *
+ * @param mode - 'history' for URL search params, 'hash' for hash-based params
+ * @param options - Configuration options
+ */
+export declare function useUrlSearchParams<T extends Record<string, string> = Record<string, string>>(mode?: 'history' | 'hash', options?: UseUrlSearchParamsOptions<T>): UseUrlSearchParamsReturn;
+export declare interface UseUrlSearchParamsOptions<T extends Record<string, string> = Record<string, string>> {
+  initialValue?: T
+}
+export declare interface UseUrlSearchParamsReturn {
+  params: Ref<Record<string, string>>
+  get: (key: string) => string | null
+  set: (key: string, value: string) => void
+  delete: (key: string) => void
+}

package/dist/useUrlSearchParams.js

@@ -0,0 +1,72 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { defaultWindow } from "./_shared";
+export function useUrlSearchParams(mode = "history", options) {
+  const win = defaultWindow(), { initialValue } = options ?? {};
+  function readParams() {
+    if (!win)
+      return { ...initialValue };
+    let search = "";
+    if (mode === "hash") {
+      const hash = win.location.hash, idx = hash.indexOf("?");
+      search = idx >= 0 ? hash.slice(idx + 1) : "";
+    } else
+      search = win.location.search.slice(1);
+    const result = { ...initialValue };
+    new URLSearchParams(search).forEach((value, key) => {
+      result[key] = value;
+    });
+    return result;
+  }
+  const params = ref(readParams());
+  function writeParams() {
+    if (!win)
+      return;
+    const searchParams = new URLSearchParams;
+    for (const [key, value] of Object.entries(params.value))
+      if (value !== void 0 && value !== null && value !== "")
+        searchParams.set(key, value);
+    const query = searchParams.toString();
+    if (mode === "hash") {
+      const basePath = win.location.hash.split("?")[0] || "#";
+      win.location.hash = query ? `${basePath}?${query}` : basePath;
+    } else {
+      const url = query ? `${win.location.pathname}?${query}` : win.location.pathname;
+      win.history.replaceState(win.history.state, "", url);
+    }
+  }
+  function get(key) {
+    return params.value[key] ?? null;
+  }
+  function set(key, value) {
+    const current = { ...params.value };
+    current[key] = value;
+    params.value = current;
+    writeParams();
+  }
+  function del(key) {
+    const current = { ...params.value };
+    delete current[key];
+    params.value = current;
+    writeParams();
+  }
+  if (win) {
+    const onPopState = () => {
+      params.value = readParams();
+    }, onHashChange = () => {
+      if (mode === "hash")
+        params.value = readParams();
+    };
+    win.addEventListener("popstate", onPopState);
+    win.addEventListener("hashchange", onHashChange);
+    onUnmounted(() => {
+      win.removeEventListener("popstate", onPopState);
+      win.removeEventListener("hashchange", onHashChange);
+    });
+  }
+  return {
+    params,
+    get,
+    set,
+    delete: del
+  };
+}

package/dist/useVibrate.d.ts

@@ -0,0 +1,13 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive Vibration API.
+ */
+export declare function useVibrate(options?: UseVibrateOptions): UseVibrateReturn;
+export declare interface UseVibrateOptions {
+  pattern?: number | number[]
+}
+export declare interface UseVibrateReturn {
+  isSupported: Ref<boolean>
+  vibrate: (pattern?: number | number[]) => boolean
+  stop: () => void
+}

package/dist/useVibrate.js

@@ -0,0 +1,14 @@
+import { ref } from "@stacksjs/stx";
+export function useVibrate(options = {}) {
+  const { pattern = 200 } = options, isSupported = ref(typeof navigator < "u" && "vibrate" in navigator);
+  function vibrate(p) {
+    if (!isSupported.value)
+      return !1;
+    return navigator.vibrate(p ?? pattern);
+  }
+  function stop() {
+    if (isSupported.value)
+      navigator.vibrate(0);
+  }
+  return { isSupported, vibrate, stop };
+}

package/dist/useVirtualList.d.ts

@@ -0,0 +1,23 @@
+import type { MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Virtual list for efficiently rendering large lists.
+ */
+export declare function useVirtualList<T>(source: MaybeRef<T[]>, options: UseVirtualListOptions): UseVirtualListReturn<T>;
+export declare interface UseVirtualListOptions {
+  itemHeight: number
+  overscan?: number
+}
+export declare interface UseVirtualListItem<T> {
+  data: T
+  index: number
+}
+export declare interface UseVirtualListReturn<T> {
+  list: Ref<UseVirtualListItem<T>[]>
+  containerProps: {
+    onScroll: (e: Event) => void
+    style: { overflow: string, position: string }
+  }
+  wrapperProps: Ref<{ style: { width: string, height: string, marginTop: string } }>
+  scrollTo: (index: number) => void
+}

package/dist/useVirtualList.js

@@ -0,0 +1,49 @@
+import { ref, watch } from "@stacksjs/stx";
+import { unref } from "./_shared";
+export function useVirtualList(source, options) {
+  const { itemHeight, overscan = 5 } = options, list = ref([]), containerHeight = ref(0), scrollTop = ref(0), wrapperProps = ref({
+    style: { width: "100%", height: "0px", marginTop: "0px" }
+  });
+  function getItems() {
+    return unref(source);
+  }
+  function update() {
+    const items = getItems(), totalHeight = items.length * itemHeight, startIndex = Math.max(0, Math.floor(scrollTop.value / itemHeight) - overscan), endIndex = Math.min(items.length, Math.ceil((scrollTop.value + containerHeight.value) / itemHeight) + overscan), visibleItems = [];
+    for (let i = startIndex;i < endIndex; i++) {
+      const data = items[i];
+      if (data === void 0 && !(i in items))
+        continue;
+      visibleItems.push({ data, index: i });
+    }
+    list.value = visibleItems;
+    wrapperProps.value = {
+      style: {
+        width: "100%",
+        height: `${totalHeight - startIndex * itemHeight}px`,
+        marginTop: `${startIndex * itemHeight}px`
+      }
+    };
+  }
+  const onScroll = (e) => {
+    const target = e.target;
+    scrollTop.value = target.scrollTop;
+    containerHeight.value = target.clientHeight;
+    update();
+  };
+  update();
+  if (typeof source === "object" && source && "value" in source && "subscribe" in source)
+    watch(source, () => update());
+  function scrollTo(index) {
+    scrollTop.value = index * itemHeight;
+    update();
+  }
+  return {
+    list,
+    containerProps: {
+      onScroll,
+      style: { overflow: "auto", position: "relative" }
+    },
+    wrapperProps,
+    scrollTo
+  };
+}

package/dist/useWakeLock.d.ts

@@ -0,0 +1,12 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive Screen Wake Lock API.
+ * Prevents the screen from dimming/locking.
+ */
+export declare function useWakeLock(): UseWakeLockReturn;
+export declare interface UseWakeLockReturn {
+  isSupported: Ref<boolean>
+  isActive: Ref<boolean>
+  request: () => Promise<void>
+  release: () => Promise<void>
+}

package/dist/useWakeLock.js

@@ -0,0 +1,32 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function useWakeLock() {
+  const isSupported = ref(typeof navigator < "u" && "wakeLock" in navigator), isActive = ref(!1);
+  let sentinel = null;
+  async function request() {
+    if (!isSupported.value)
+      return;
+    try {
+      sentinel = await navigator.wakeLock.request("screen");
+      isActive.value = !0;
+      sentinel.addEventListener("release", () => {
+        isActive.value = !1;
+        sentinel = null;
+      });
+    } catch {
+      isActive.value = !1;
+    }
+  }
+  async function release() {
+    if (sentinel) {
+      await sentinel.release();
+      sentinel = null;
+      isActive.value = !1;
+    }
+  }
+  try {
+    onUnmounted(() => {
+      release();
+    });
+  } catch {}
+  return { isSupported, isActive, request, release };
+}

package/dist/useWebNotification.d.ts

@@ -0,0 +1,25 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive Web Notification API.
+ */
+export declare function useWebNotification(options?: UseWebNotificationOptions): UseWebNotificationReturn;
+export declare interface UseWebNotificationOptions {
+  title?: string
+  body?: string
+  icon?: string
+  dir?: NotificationDirection
+  lang?: string
+  tag?: string
+  requireInteraction?: boolean
+}
+export declare interface UseWebNotificationReturn {
+  isSupported: Ref<boolean>
+  notification: Ref<Notification | null>
+  permissionGranted: Ref<boolean>
+  show: (overrideOptions?: UseWebNotificationOptions) => Promise<Notification | undefined>
+  close: () => void
+  onClick: Ref<((_evt: Event) => void) | null>
+  onShow: Ref<((_evt: Event) => void) | null>
+  onError: Ref<((_evt: Event) => void) | null>
+  onClose: Ref<((_evt: Event) => void) | null>
+}

package/dist/useWebNotification.js

@@ -0,0 +1,39 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function useWebNotification(options = {}) {
+  const isSupported = ref(typeof Notification < "u"), notification = ref(null), permissionGranted = ref(isSupported.value && Notification.permission === "granted"), onClick = ref(null), onShow = ref(null), onError = ref(null), onClose = ref(null);
+  async function show(overrideOptions) {
+    if (!isSupported.value)
+      return;
+    if (Notification.permission !== "granted") {
+      const result = await Notification.requestPermission();
+      permissionGranted.value = result === "granted";
+      if (!permissionGranted.value)
+        return;
+    }
+    const opts = { ...options, ...overrideOptions }, title = opts.title ?? "", n = new Notification(title, {
+      body: opts.body,
+      icon: opts.icon,
+      dir: opts.dir,
+      lang: opts.lang,
+      tag: opts.tag,
+      requireInteraction: opts.requireInteraction
+    });
+    notification.value = n;
+    n.onclick = (e) => onClick.value?.(e);
+    n.onshow = (e) => onShow.value?.(e);
+    n.onerror = (e) => onError.value?.(e);
+    n.onclose = (e) => {
+      onClose.value?.(e);
+      notification.value = null;
+    };
+    return n;
+  }
+  function close() {
+    notification.value?.close();
+    notification.value = null;
+  }
+  try {
+    onUnmounted(() => close());
+  } catch {}
+  return { isSupported, notification, permissionGranted, show, close, onClick, onShow, onError, onClose };
+}

package/dist/useWebSocket.d.ts

@@ -0,0 +1,38 @@
+import type { MaybeRefOrGetter } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive WebSocket connection.
+ *
+ * @param url - The WebSocket URL (can be a ref, getter, or raw string)
+ * @param options - Configuration options
+ * @returns Reactive WebSocket state and control methods
+ *
+ * @example
+ * ```ts
+ * const { data, status, send, close } = useWebSocket('ws://localhost:8080', {
+ *   onConnected(ws) { console.log('Connected') },
+ *   onMessage(ws, event) { console.log('Message:', event.data) },
+ *   autoReconnect: { retries: 3, delay: 1000 },
+ * })
+ * ```
+ */
+export declare function useWebSocket(url: MaybeRefOrGetter<string>, options?: UseWebSocketOptions): UseWebSocketReturn;
+export declare interface UseWebSocketOptions {
+  onConnected?: (ws: WebSocket) => void
+  onDisconnected?: (ws: WebSocket, event: CloseEvent) => void
+  onError?: (ws: WebSocket, event: Event) => void
+  onMessage?: (ws: WebSocket, event: MessageEvent) => void
+  immediate?: boolean
+  autoReconnect?: boolean | { retries?: number, delay?: number }
+  heartbeat?: boolean | { interval?: number, message?: string }
+  protocols?: string | string[]
+}
+export declare interface UseWebSocketReturn {
+  data: Ref<string | null>
+  status: Ref<WebSocketStatus>
+  ws: Ref<WebSocket | null>
+  open: () => void
+  close: (code?: number, reason?: string) => void
+  send: (data: string | ArrayBuffer | Blob) => void
+}
+export type WebSocketStatus = 'CONNECTING' | 'OPEN' | 'CLOSING' | 'CLOSED';

package/dist/useWebSocket.js

@@ -0,0 +1,103 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { toValue } from "./_shared";
+export function useWebSocket(url, options = {}) {
+  const {
+    onConnected,
+    onDisconnected,
+    onError,
+    onMessage,
+    immediate = !0,
+    autoReconnect = !1,
+    heartbeat = !1,
+    protocols
+  } = options, data = ref(null), status = ref("CLOSED"), wsRef = ref(null);
+  let retryCount = 0, retryTimer = null, heartbeatTimer = null, explicitlyClosed = !1;
+  const heartbeatInterval = typeof heartbeat === "object" ? heartbeat.interval ?? 30000 : 30000, heartbeatMessage = typeof heartbeat === "object" ? heartbeat.message ?? "ping" : "ping", maxRetries = typeof autoReconnect === "object" ? autoReconnect.retries ?? 3 : autoReconnect ? 1 / 0 : 0, retryDelay = typeof autoReconnect === "object" ? autoReconnect.delay ?? 1000 : 1000;
+  function startHeartbeat(ws) {
+    stopHeartbeat();
+    if (!heartbeat)
+      return;
+    heartbeatTimer = setInterval(() => {
+      if (ws.readyState === WebSocket.OPEN)
+        ws.send(heartbeatMessage);
+    }, heartbeatInterval);
+  }
+  function stopHeartbeat() {
+    if (heartbeatTimer !== null) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+  }
+  function open() {
+    if (typeof WebSocket > "u")
+      return;
+    close();
+    explicitlyClosed = !1;
+    retryCount = 0;
+    const resolvedUrl = toValue(url);
+    status.value = "CONNECTING";
+    const ws = protocols ? new WebSocket(resolvedUrl, protocols) : new WebSocket(resolvedUrl);
+    wsRef.value = ws;
+    ws.onopen = () => {
+      status.value = "OPEN";
+      retryCount = 0;
+      startHeartbeat(ws);
+      onConnected?.(ws);
+    };
+    ws.onclose = (event) => {
+      status.value = "CLOSED";
+      wsRef.value = null;
+      stopHeartbeat();
+      onDisconnected?.(ws, event);
+      if (!explicitlyClosed && autoReconnect && retryCount < maxRetries) {
+        retryCount++;
+        retryTimer = setTimeout(() => {
+          open();
+        }, retryDelay);
+      }
+    };
+    ws.onerror = (event) => {
+      onError?.(ws, event);
+    };
+    ws.onmessage = (event) => {
+      data.value = typeof event.data === "string" ? event.data : String(event.data);
+      onMessage?.(ws, event);
+    };
+  }
+  function close(code, reason) {
+    explicitlyClosed = !0;
+    stopHeartbeat();
+    if (retryTimer !== null) {
+      clearTimeout(retryTimer);
+      retryTimer = null;
+    }
+    const ws = wsRef.value;
+    if (ws) {
+      if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+        status.value = "CLOSING";
+        ws.close(code, reason);
+      }
+      wsRef.value = null;
+    }
+  }
+  function send(sendData) {
+    const ws = wsRef.value;
+    if (ws && ws.readyState === WebSocket.OPEN)
+      ws.send(sendData);
+  }
+  if (immediate)
+    open();
+  try {
+    onUnmounted(() => {
+      close();
+    });
+  } catch {}
+  return {
+    data,
+    status,
+    ws: wsRef,
+    open,
+    close,
+    send
+  };
+}

package/dist/useWebWorker.d.ts

@@ -0,0 +1,18 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive Web Worker.
+ */
+export declare function useWebWorker(url: string | URL, workerOptions?: WorkerOptions): UseWebWorkerReturn;
+/**
+ * Run a function in a Web Worker via inline blob.
+ */
+export declare function useWebWorkerFn<T extends (...args: any[]) => any>(fn: T): {
+    workerFn: (...args: Parameters<T>) => Promise<ReturnType<T>>
+    terminate: () => void
+  };
+export declare interface UseWebWorkerReturn {
+  data: Ref<any>
+  post: (message: any) => void
+  terminate: () => void
+  worker: Ref<Worker | undefined>
+}