@stacksjs/composables 0.70.87 → 0.70.90

package/dist/useScreenOrientation.js

@@ -0,0 +1,27 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function useScreenOrientation() {
+  const isSupported = ref(typeof screen < "u" && "orientation" in screen), orientation = ref(void 0), angle = ref(0);
+  if (isSupported.value) {
+    orientation.value = screen.orientation.type;
+    angle.value = screen.orientation.angle;
+    const handler = () => {
+      orientation.value = screen.orientation.type;
+      angle.value = screen.orientation.angle;
+    };
+    screen.orientation.addEventListener("change", handler);
+    try {
+      onUnmounted(() => {
+        screen.orientation.removeEventListener("change", handler);
+      });
+    } catch {}
+  }
+  async function lockOrientation(type) {
+    if (isSupported.value)
+      await screen.orientation.lock(type);
+  }
+  function unlockOrientation() {
+    if (isSupported.value)
+      screen.orientation.unlock();
+  }
+  return { isSupported, orientation, angle, lockOrientation, unlockOrientation };
+}

package/dist/useScreenSafeArea.d.ts

@@ -0,0 +1,12 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive `env(safe-area-inset-*)` values.
+ */
+export declare function useScreenSafeArea(): UseScreenSafeAreaReturn;
+export declare interface UseScreenSafeAreaReturn {
+  top: Ref<string>
+  right: Ref<string>
+  bottom: Ref<string>
+  left: Ref<string>
+  update: () => void
+}

package/dist/useScreenSafeArea.js

@@ -0,0 +1,25 @@
+import { ref } from "@stacksjs/stx";
+export function useScreenSafeArea() {
+  const top = ref("0px"), right = ref("0px"), bottom = ref("0px"), left = ref("0px");
+  function update() {
+    if (typeof document > "u" || typeof getComputedStyle > "u")
+      return;
+    const div = document.createElement("div");
+    div.style.position = "fixed";
+    div.style.top = "env(safe-area-inset-top, 0px)";
+    div.style.right = "env(safe-area-inset-right, 0px)";
+    div.style.bottom = "env(safe-area-inset-bottom, 0px)";
+    div.style.left = "env(safe-area-inset-left, 0px)";
+    div.style.pointerEvents = "none";
+    div.style.visibility = "hidden";
+    document.body.appendChild(div);
+    const style = getComputedStyle(div);
+    top.value = style.top;
+    right.value = style.right;
+    bottom.value = style.bottom;
+    left.value = style.left;
+    document.body.removeChild(div);
+  }
+  update();
+  return { top, right, bottom, left, update };
+}

package/dist/useScriptTag.d.ts

@@ -0,0 +1,20 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Inject a script tag into the document.
+ */
+export declare function useScriptTag(src: string, onLoaded?: (el: HTMLScriptElement) => void, options?: UseScriptTagOptions): UseScriptTagReturn;
+export declare interface UseScriptTagOptions {
+  immediate?: boolean
+  type?: string
+  async?: boolean
+  defer?: boolean
+  crossOrigin?: string
+  referrerPolicy?: string
+  manual?: boolean
+  attrs?: Record<string, string>
+}
+export declare interface UseScriptTagReturn {
+  scriptTag: Ref<HTMLScriptElement | null>
+  load: () => Promise<HTMLScriptElement>
+  unload: () => void
+}

package/dist/useScriptTag.js

@@ -0,0 +1,52 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function useScriptTag(src, onLoaded, options = {}) {
+  const {
+    immediate = !0,
+    type = "text/javascript",
+    manual = !1,
+    attrs = {}
+  } = options, scriptTag = ref(null);
+  function load() {
+    return new Promise((resolve, reject) => {
+      if (typeof document > "u") {
+        reject(Error("Document is not available"));
+        return;
+      }
+      const el = document.createElement("script");
+      el.type = type;
+      el.src = src;
+      if (options.async)
+        el.async = !0;
+      if (options.defer)
+        el.defer = !0;
+      if (options.crossOrigin)
+        el.crossOrigin = options.crossOrigin;
+      if (options.referrerPolicy)
+        el.referrerPolicy = options.referrerPolicy;
+      for (const [key, value] of Object.entries(attrs))
+        el.setAttribute(key, value);
+      el.addEventListener("load", () => {
+        scriptTag.value = el;
+        onLoaded?.(el);
+        resolve(el);
+      });
+      el.addEventListener("error", (event) => {
+        reject(event);
+      });
+      document.head.appendChild(el);
+    });
+  }
+  function unload() {
+    if (scriptTag.value) {
+      scriptTag.value.remove();
+      scriptTag.value = null;
+    }
+  }
+  if (immediate)
+    load();
+  if (!manual)
+    try {
+      onUnmounted(() => unload());
+    } catch {}
+  return { scriptTag, load, unload };
+}

package/dist/useScroll.d.ts

@@ -0,0 +1,36 @@
+import type { MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive scroll position tracking.
+ * Tracks scroll position, scrolling state, arrived edges, and scroll directions.
+ *
+ * @param target - Scroll target element or window
+ * @param options - Configuration options
+ */
+export declare function useScroll(target?: MaybeRef<HTMLElement | Window | Document | null>, options?: UseScrollOptions): UseScrollReturn;
+export declare interface UseScrollOptions {
+  throttle?: number
+  offset?: {
+    top?: number
+    bottom?: number
+    left?: number
+    right?: number
+  }
+}
+export declare interface UseScrollReturn {
+  x: Ref<number>
+  y: Ref<number>
+  isScrolling: Ref<boolean>
+  arrivedState: {
+    top: Ref<boolean>
+    bottom: Ref<boolean>
+    left: Ref<boolean>
+    right: Ref<boolean>
+  }
+  directions: {
+    top: Ref<boolean>
+    bottom: Ref<boolean>
+    left: Ref<boolean>
+    right: Ref<boolean>
+  }
+}

package/dist/useScroll.js

@@ -0,0 +1,116 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { unref } from "./_shared";
+export function useScroll(target, options) {
+  const { throttle = 0, offset = {} } = options ?? {}, offsetTop = offset.top ?? 0, offsetBottom = offset.bottom ?? 0, offsetLeft = offset.left ?? 0, offsetRight = offset.right ?? 0, x = ref(0), y = ref(0), isScrolling = ref(!1), arrivedTop = ref(!0), arrivedBottom = ref(!1), arrivedLeft = ref(!0), arrivedRight = ref(!1), dirTop = ref(!1), dirBottom = ref(!1), dirLeft = ref(!1), dirRight = ref(!1);
+  let scrollingTimer, lastX = 0, lastY = 0, throttleTimer, isThrottled = !1;
+  function getScrollPosition(el) {
+    if (typeof window < "u" && el === window || "innerHeight" in el && "scrollX" in el) {
+      const win = el, doc = typeof document < "u" ? document : void 0;
+      return {
+        scrollLeft: win.scrollX ?? win.pageXOffset ?? 0,
+        scrollTop: win.scrollY ?? win.pageYOffset ?? 0,
+        scrollHeight: doc?.documentElement?.scrollHeight ?? 0,
+        scrollWidth: doc?.documentElement?.scrollWidth ?? 0,
+        clientHeight: win.innerHeight,
+        clientWidth: win.innerWidth
+      };
+    }
+    if (typeof document < "u" && el === document || "documentElement" in el) {
+      const docEl = el.documentElement;
+      return {
+        scrollLeft: docEl.scrollLeft,
+        scrollTop: docEl.scrollTop,
+        scrollHeight: docEl.scrollHeight,
+        scrollWidth: docEl.scrollWidth,
+        clientHeight: docEl.clientHeight,
+        clientWidth: docEl.clientWidth
+      };
+    }
+    const htmlEl = el;
+    return {
+      scrollLeft: htmlEl.scrollLeft,
+      scrollTop: htmlEl.scrollTop,
+      scrollHeight: htmlEl.scrollHeight,
+      scrollWidth: htmlEl.scrollWidth,
+      clientHeight: htmlEl.clientHeight,
+      clientWidth: htmlEl.clientWidth
+    };
+  }
+  function update() {
+    const el = target ? unref(target) : typeof window < "u" ? window : null;
+    if (!el)
+      return;
+    const pos = getScrollPosition(el);
+    dirTop.value = pos.scrollTop < lastY;
+    dirBottom.value = pos.scrollTop > lastY;
+    dirLeft.value = pos.scrollLeft < lastX;
+    dirRight.value = pos.scrollLeft > lastX;
+    lastX = pos.scrollLeft;
+    lastY = pos.scrollTop;
+    x.value = pos.scrollLeft;
+    y.value = pos.scrollTop;
+    arrivedTop.value = pos.scrollTop <= offsetTop;
+    arrivedLeft.value = pos.scrollLeft <= offsetLeft;
+    arrivedBottom.value = pos.scrollTop + pos.clientHeight >= pos.scrollHeight - offsetBottom;
+    arrivedRight.value = pos.scrollLeft + pos.clientWidth >= pos.scrollWidth - offsetRight;
+    isScrolling.value = !0;
+    if (scrollingTimer)
+      clearTimeout(scrollingTimer);
+    scrollingTimer = setTimeout(() => {
+      isScrolling.value = !1;
+    }, 150);
+  }
+  function onScroll() {
+    if (throttle > 0) {
+      if (!isThrottled) {
+        update();
+        isThrottled = !0;
+        throttleTimer = setTimeout(() => {
+          isThrottled = !1;
+        }, throttle);
+      }
+    } else
+      update();
+  }
+  if (typeof window < "u") {
+    const el = target ? unref(target) : window;
+    if (el) {
+      const pos = getScrollPosition(el);
+      x.value = pos.scrollLeft;
+      y.value = pos.scrollTop;
+      lastX = pos.scrollLeft;
+      lastY = pos.scrollTop;
+      arrivedTop.value = pos.scrollTop <= offsetTop;
+      arrivedLeft.value = pos.scrollLeft <= offsetLeft;
+      arrivedBottom.value = pos.scrollTop + pos.clientHeight >= pos.scrollHeight - offsetBottom;
+      arrivedRight.value = pos.scrollLeft + pos.clientWidth >= pos.scrollWidth - offsetRight;
+      el.addEventListener("scroll", onScroll, { passive: !0 });
+      try {
+        onUnmounted(() => {
+          el.removeEventListener("scroll", onScroll);
+          if (scrollingTimer)
+            clearTimeout(scrollingTimer);
+          if (throttleTimer)
+            clearTimeout(throttleTimer);
+        });
+      } catch {}
+    }
+  }
+  return {
+    x,
+    y,
+    isScrolling,
+    arrivedState: {
+      top: arrivedTop,
+      bottom: arrivedBottom,
+      left: arrivedLeft,
+      right: arrivedRight
+    },
+    directions: {
+      top: dirTop,
+      bottom: dirBottom,
+      left: dirLeft,
+      right: dirRight
+    }
+  };
+}

package/dist/useScrollLock.d.ts

@@ -0,0 +1,10 @@
+import type { MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive scroll lock.
+ * Returns a writable ref: set to true to lock scrolling, false to unlock.
+ * Sets `overflow: hidden` on the target element.
+ *
+ * @param element - Target element to lock (defaults to document.body)
+ */
+export declare function useScrollLock(element?: MaybeRef<HTMLElement | null>): Ref<boolean>;

package/dist/useScrollLock.js

@@ -0,0 +1,39 @@
+import { onUnmounted, ref, watch } from "@stacksjs/stx";
+import { unref } from "./_shared";
+export function useScrollLock(element) {
+  const isLocked = ref(!1);
+  let originalOverflow = "";
+  function getElement() {
+    if (element)
+      return unref(element);
+    if (typeof document < "u")
+      return document.body;
+    return null;
+  }
+  function lock() {
+    const el = getElement();
+    if (!el)
+      return;
+    originalOverflow = el.style.overflow;
+    el.style.overflow = "hidden";
+  }
+  function unlock() {
+    const el = getElement();
+    if (!el)
+      return;
+    el.style.overflow = originalOverflow;
+  }
+  watch(isLocked, (val) => {
+    if (val)
+      lock();
+    else
+      unlock();
+  });
+  try {
+    onUnmounted(() => {
+      if (isLocked.value)
+        unlock();
+    });
+  } catch {}
+  return isLocked;
+}

package/dist/useSessionStorage.d.ts

@@ -0,0 +1,17 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive sessionStorage wrapper.
+ * Convenience composable that delegates to useStorage with sessionStorage.
+ *
+ * @param key - Storage key
+ * @param defaultValue - Default value when key doesn't exist
+ * @param options - Serializer options
+ */
+export declare function useSessionStorage<T>(key: string, defaultValue: T, options?: UseSessionStorageOptions<T>): Ref<T>;
+declare interface UseSessionStorageSerializer<T> {
+  read: (raw: string) => T
+  write: (value: T) => string
+}
+declare interface UseSessionStorageOptions<T> {
+  serializer?: UseSessionStorageSerializer<T>
+}

package/dist/useSessionStorage.js

@@ -0,0 +1,4 @@
+import { useStorage } from "./useStorage";
+export function useSessionStorage(key, defaultValue, options) {
+  return useStorage(key, defaultValue, typeof sessionStorage < "u" ? sessionStorage : void 0, options);
+}

package/dist/useShare.d.ts

@@ -0,0 +1,15 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive Web Share API.
+ */
+export declare function useShare(options?: UseShareOptions): UseShareReturn;
+export declare interface UseShareOptions {
+  title?: string
+  text?: string
+  url?: string
+  files?: File[]
+}
+export declare interface UseShareReturn {
+  share: (overrideOptions?: UseShareOptions) => Promise<void>
+  isSupported: Ref<boolean>
+}

package/dist/useShare.js

@@ -0,0 +1,11 @@
+import { ref } from "@stacksjs/stx";
+export function useShare(options = {}) {
+  const isSupported = ref(typeof navigator < "u" && "share" in navigator);
+  async function share(overrideOptions) {
+    if (!isSupported.value)
+      return;
+    const shareData = { ...options, ...overrideOptions };
+    await navigator.share(shareData);
+  }
+  return { share, isSupported };
+}

package/dist/useSorted.d.ts

@@ -0,0 +1,10 @@
+import type { MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive sorted array. Returns a computed ref containing a sorted copy
+ * of the source array.
+ *
+ * @param source - Source array (raw or ref)
+ * @param compareFn - Optional comparison function (defaults to natural order)
+ */
+export declare function useSorted<T>(source: MaybeRef<T[]>, compareFn?: (a: T, b: T) => number): Ref<T[]>;

package/dist/useSorted.js

@@ -0,0 +1,10 @@
+import { computed } from "@stacksjs/stx";
+import { unref } from "./_shared";
+export function useSorted(source, compareFn) {
+  return computed(() => {
+    const arr = [...unref(source)];
+    if (compareFn)
+      return arr.sort(compareFn);
+    return arr.sort();
+  });
+}

package/dist/useStepper.d.ts

@@ -0,0 +1,23 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Step-by-step navigation composable.
+ * Provides reactive state and controls for stepping through an ordered list.
+ *
+ * @param steps - Array of step values
+ * @param initialStep - Optional initial step (defaults to first step)
+ */
+export declare function useStepper<T>(steps: T[], initialStep?: T): UseStepperReturn<T>;
+export declare interface UseStepperReturn<T> {
+  steps: Ref<T[]>
+  current: Ref<T>
+  index: Ref<number>
+  isFirst: Ref<boolean>
+  isLast: Ref<boolean>
+  next: () => void
+  previous: () => void
+  goTo: (step: T) => void
+  goToIndex: (index: number) => void
+  isBefore: (step: T) => boolean
+  isAfter: (step: T) => boolean
+  isCurrent: (step: T) => boolean
+}

package/dist/useStepper.js

@@ -0,0 +1,46 @@
+import { computed, ref } from "@stacksjs/stx";
+export function useStepper(steps, initialStep) {
+  const stepsRef = ref([...steps]), initialIndex = initialStep !== void 0 ? steps.indexOf(initialStep) : 0, index = ref(initialIndex >= 0 ? initialIndex : 0), current = computed(() => stepsRef.value[index.value]), isFirst = computed(() => index.value === 0), isLast = computed(() => index.value === stepsRef.value.length - 1);
+  function next() {
+    if (index.value < stepsRef.value.length - 1)
+      index.value++;
+  }
+  function previous() {
+    if (index.value > 0)
+      index.value--;
+  }
+  function goTo(step) {
+    const idx = stepsRef.value.indexOf(step);
+    if (idx >= 0)
+      index.value = idx;
+  }
+  function goToIndex(idx) {
+    if (idx >= 0 && idx < stepsRef.value.length)
+      index.value = idx;
+  }
+  function isBefore(step) {
+    const stepIndex = stepsRef.value.indexOf(step);
+    return stepIndex >= 0 && index.value < stepIndex;
+  }
+  function isAfter(step) {
+    const stepIndex = stepsRef.value.indexOf(step);
+    return stepIndex >= 0 && index.value > stepIndex;
+  }
+  function isCurrent(step) {
+    return stepsRef.value[index.value] === step;
+  }
+  return {
+    steps: stepsRef,
+    current,
+    index,
+    isFirst,
+    isLast,
+    next,
+    previous,
+    goTo,
+    goToIndex,
+    isBefore,
+    isAfter,
+    isCurrent
+  };
+}

package/dist/useStorage.d.ts

@@ -0,0 +1,18 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive localStorage/sessionStorage wrapper.
+ * Creates a stx ref that syncs with browser storage.
+ *
+ * @param key - Storage key
+ * @param defaultValue - Default value when key doesn't exist
+ * @param storage - Storage backend (defaults to localStorage)
+ * @param options - Serializer options
+ */
+export declare function useStorage<T>(key: string, defaultValue: T, storage?: Storage, options?: UseStorageOptions<T>): Ref<T>;
+declare interface UseStorageSerializer<T> {
+  read: (raw: string) => T
+  write: (value: T) => string
+}
+declare interface UseStorageOptions<T> {
+  serializer?: UseStorageSerializer<T>
+}

package/dist/useStorage.js

@@ -0,0 +1,54 @@
+import { onUnmounted, ref, watch } from "@stacksjs/stx";
+export function useStorage(key, defaultValue, storage, options) {
+  const store = storage ?? (typeof localStorage < "u" ? localStorage : void 0), serializer = options?.serializer ?? {
+    read: (raw) => {
+      try {
+        return JSON.parse(raw);
+      } catch {
+        return raw;
+      }
+    },
+    write: (value) => JSON.stringify(value)
+  };
+  let initialValue = defaultValue;
+  if (store)
+    try {
+      const raw = store.getItem(key);
+      if (raw !== null)
+        initialValue = serializer.read(raw);
+    } catch {}
+  const data = ref(initialValue);
+  watch(data, (val) => {
+    if (!store)
+      return;
+    try {
+      if (val === null || val === void 0)
+        store.removeItem(key);
+      else
+        store.setItem(key, serializer.write(val));
+    } catch (err) {
+      const name = err?.name ?? "", msg = err?.message ?? String(err);
+      if (name === "QuotaExceededError" || /quota/i.test(msg))
+        console.warn(`[useStorage] ${key}: storage quota exceeded \u2014 value not persisted.`);
+      else
+        console.warn(`[useStorage] ${key}: failed to persist value \u2014 ${msg}`);
+    }
+  });
+  if (typeof window < "u") {
+    const onStorageChange = (e) => {
+      if (e.key !== key || e.storageArea !== store)
+        return;
+      if (e.newValue === null)
+        data.value = defaultValue;
+      else
+        try {
+          data.value = serializer.read(e.newValue);
+        } catch {
+          data.value = defaultValue;
+        }
+    };
+    window.addEventListener("storage", onStorageChange);
+    onUnmounted(() => window.removeEventListener("storage", onStorageChange));
+  }
+  return data;
+}

package/dist/useStyleTag.d.ts

@@ -0,0 +1,17 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Inject a style tag into the document head.
+ */
+export declare function useStyleTag(initialCss: string, options?: UseStyleTagOptions): UseStyleTagReturn;
+export declare interface UseStyleTagOptions {
+  immediate?: boolean
+  id?: string
+  media?: string
+}
+export declare interface UseStyleTagReturn {
+  id: string
+  css: Ref<string>
+  load: () => void
+  unload: () => void
+  isLoaded: Ref<boolean>
+}

package/dist/useStyleTag.js

@@ -0,0 +1,39 @@
+import { onUnmounted, ref, watch } from "@stacksjs/stx";
+export function useStyleTag(initialCss, options = {}) {
+  const {
+    immediate = !0,
+    id = `style-${Math.random().toString(36).slice(2, 9)}`,
+    media
+  } = options, css = ref(initialCss), isLoaded = ref(!1);
+  let styleEl = null;
+  function load() {
+    if (typeof document > "u")
+      return;
+    if (styleEl)
+      return;
+    styleEl = document.createElement("style");
+    styleEl.id = id;
+    if (media)
+      styleEl.media = media;
+    styleEl.textContent = css.value;
+    document.head.appendChild(styleEl);
+    isLoaded.value = !0;
+  }
+  function unload() {
+    if (styleEl) {
+      styleEl.remove();
+      styleEl = null;
+      isLoaded.value = !1;
+    }
+  }
+  watch(css, (val) => {
+    if (styleEl)
+      styleEl.textContent = val;
+  });
+  if (immediate)
+    load();
+  try {
+    onUnmounted(() => unload());
+  } catch {}
+  return { id, css, load, unload, isLoaded };
+}

package/dist/useSupported.d.ts

@@ -0,0 +1,8 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Check if a browser feature is supported.
+ *
+ * @param callback - A function that returns true if the feature is supported
+ * @returns A reactive ref indicating support status
+ */
+export declare function useSupported(callback: () => boolean): Ref<boolean>;

package/dist/useSupported.js

@@ -0,0 +1,10 @@
+import { ref } from "@stacksjs/stx";
+export function useSupported(callback) {
+  const isSupported = ref(!1);
+  try {
+    isSupported.value = callback();
+  } catch {
+    isSupported.value = !1;
+  }
+  return isSupported;
+}

package/dist/useSwipe.d.ts

@@ -0,0 +1,20 @@
+import type { MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive swipe detection.
+ */
+export declare function useSwipe(target: MaybeRef<HTMLElement | Window | null | undefined>, options?: UseSwipeOptions): UseSwipeReturn;
+export declare interface UseSwipeOptions {
+  threshold?: number
+  onSwipe?: (direction: SwipeDirection) => void
+  onSwipeStart?: (e: TouchEvent) => void
+  onSwipeEnd?: (e: TouchEvent, direction: SwipeDirection) => void
+  passive?: boolean
+}
+export declare interface UseSwipeReturn {
+  isSwiping: Ref<boolean>
+  direction: Ref<SwipeDirection>
+  lengthX: Ref<number>
+  lengthY: Ref<number>
+}
+export type SwipeDirection = 'up' | 'down' | 'left' | 'right' | 'none';