@stacksjs/composables 0.70.88 → 0.70.91

package/dist/useDateFormat.js

@@ -0,0 +1,11 @@
+import { computed, ref } from "@stacksjs/stx";
+import { format } from "@stacksjs/datetime";
+export function useDateFormat(date, formatStr) {
+  if (typeof date === "object" && date !== null && "value" in date && "subscribe" in date)
+    return computed(() => {
+      const d = date.value;
+      return format(d instanceof Date ? d : new Date(d), formatStr);
+    });
+  const d = date instanceof Date ? date : new Date(date);
+  return ref(format(d, formatStr));
+}

package/dist/useDebounce.d.ts

@@ -0,0 +1,10 @@
+import type { MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Debounce a value. Returns a ref that only updates after the source
+ * has stopped changing for the given delay.
+ *
+ * @param value - The source value or ref
+ * @param ms - Debounce delay in milliseconds. Default: 200
+ */
+export declare function useDebounce<T>(value: MaybeRef<T>, ms?: number): Ref<T>;

package/dist/useDebounce.js

@@ -0,0 +1,16 @@
+import { ref, watch } from "@stacksjs/stx";
+import { isRef, unref } from "./_shared";
+export function useDebounce(value, ms = 200) {
+  const debounced = ref(unref(value));
+  let timer = null;
+  if (isRef(value))
+    watch(value, (newVal) => {
+      if (timer !== null)
+        clearTimeout(timer);
+      timer = setTimeout(() => {
+        debounced.value = newVal;
+        timer = null;
+      }, ms);
+    });
+  return debounced;
+}

package/dist/useDebounceFn.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Debounce a function.
+ * Delays invoking the function until after `ms` milliseconds have elapsed
+ * since the last time the debounced function was invoked.
+ *
+ * @param fn - The function to debounce
+ * @param ms - Delay in milliseconds (default 200)
+ * @returns The debounced function with a `cancel` method
+ */
+export declare function useDebounceFn<T extends (...args: any[]) => any>(fn: T, ms?: number): T & { cancel: () => void };

package/dist/useDebounceFn.js

@@ -0,0 +1,18 @@
+export function useDebounceFn(fn, ms = 200) {
+  let timeoutId = null;
+  const debounced = function(...args) {
+    if (timeoutId !== null)
+      clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => {
+      timeoutId = null;
+      fn.apply(this, args);
+    }, ms);
+  };
+  debounced.cancel = () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+  };
+  return debounced;
+}

package/dist/useDebouncedRef.d.ts

@@ -0,0 +1,11 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * A ref with debounced updates.
+ * Changes to the returned ref's value are propagated after a delay.
+ * Rapidly setting the value resets the delay timer.
+ *
+ * @param value - The initial value
+ * @param delay - Debounce delay in milliseconds (default 200)
+ * @returns A Ref whose internal value updates are debounced
+ */
+export declare function useDebouncedRef<T>(value: T, delay?: number): Ref<T>;

package/dist/useDebouncedRef.js

@@ -0,0 +1,22 @@
+import { ref, watch } from "@stacksjs/stx";
+export function useDebouncedRef(value, delay = 200) {
+  const source = ref(value), debounced = ref(value);
+  let timeoutId = null;
+  watch(source, (newVal) => {
+    if (timeoutId !== null)
+      clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => {
+      debounced.value = newVal;
+      timeoutId = null;
+    }, delay);
+  });
+  return {
+    get value() {
+      return debounced.value;
+    },
+    set value(newVal) {
+      source.value = newVal;
+    },
+    subscribe: debounced.subscribe
+  };
+}

package/dist/useDebouncedRefHistory.d.ts

@@ -0,0 +1,5 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Like useRefHistory but debounces automatic commits.
+ */
+export declare function useDebouncedRefHistory<T>(source: Ref<T>, options?: { capacity?: number, clone?: boolean, debounce?: number }): void;

package/dist/useDebouncedRefHistory.js

@@ -0,0 +1,36 @@
+import { useManualRefHistory } from "./useManualRefHistory";
+import { watch } from "@stacksjs/stx";
+export function useDebouncedRefHistory(source, options) {
+  const delay = options?.debounce ?? 200, { history, commit, undo, redo, canUndo, canRedo, clear, last } = useManualRefHistory(source, options);
+  let timer = null, ignoreNext = !1;
+  watch(source, () => {
+    if (ignoreNext) {
+      ignoreNext = !1;
+      return;
+    }
+    if (timer !== null)
+      clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      commit();
+    }, delay);
+  });
+  const origUndo = undo, origRedo = redo;
+  function debouncedUndo() {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    ignoreNext = !0;
+    origUndo();
+  }
+  function debouncedRedo() {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    ignoreNext = !0;
+    origRedo();
+  }
+  return { history, commit, undo: debouncedUndo, redo: debouncedRedo, canUndo, canRedo, clear, last };
+}

package/dist/useDeviceMotion.d.ts

@@ -0,0 +1,27 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive device motion.
+ * Tracks device acceleration and rotation using the DeviceMotionEvent API.
+ *
+ * @returns Reactive acceleration, accelerationIncludingGravity, rotationRate, and interval
+ */
+export declare function useDeviceMotion(): UseDeviceMotionReturn;
+export declare interface UseDeviceMotionReturn {
+  acceleration: {
+    x: Ref<number | null>
+    y: Ref<number | null>
+    z: Ref<number | null>
+  }
+  accelerationIncludingGravity: {
+    x: Ref<number | null>
+    y: Ref<number | null>
+    z: Ref<number | null>
+  }
+  rotationRate: {
+    alpha: Ref<number | null>
+    beta: Ref<number | null>
+    gamma: Ref<number | null>
+  }
+  interval: Ref<number>
+  isSupported: Ref<boolean>
+}

package/dist/useDeviceMotion.js

@@ -0,0 +1,53 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { noop } from "./_shared";
+export function useDeviceMotion() {
+  const isSupported = ref(typeof window < "u" && "DeviceMotionEvent" in window), acceleration = {
+    x: ref(null),
+    y: ref(null),
+    z: ref(null)
+  }, accelerationIncludingGravity = {
+    x: ref(null),
+    y: ref(null),
+    z: ref(null)
+  }, rotationRate = {
+    alpha: ref(null),
+    beta: ref(null),
+    gamma: ref(null)
+  }, interval = ref(0);
+  let cleanup = noop;
+  if (typeof window < "u" && isSupported.value) {
+    const handler = (event) => {
+      if (event.acceleration) {
+        acceleration.x.value = event.acceleration.x;
+        acceleration.y.value = event.acceleration.y;
+        acceleration.z.value = event.acceleration.z;
+      }
+      if (event.accelerationIncludingGravity) {
+        accelerationIncludingGravity.x.value = event.accelerationIncludingGravity.x;
+        accelerationIncludingGravity.y.value = event.accelerationIncludingGravity.y;
+        accelerationIncludingGravity.z.value = event.accelerationIncludingGravity.z;
+      }
+      if (event.rotationRate) {
+        rotationRate.alpha.value = event.rotationRate.alpha;
+        rotationRate.beta.value = event.rotationRate.beta;
+        rotationRate.gamma.value = event.rotationRate.gamma;
+      }
+      interval.value = event.interval;
+    };
+    window.addEventListener("devicemotion", handler, { passive: !0 });
+    cleanup = () => {
+      window.removeEventListener("devicemotion", handler);
+      cleanup = noop;
+    };
+  }
+  try {
+    onUnmounted(() => cleanup());
+  } catch {}
+  return {
+    acceleration,
+    accelerationIncludingGravity,
+    rotationRate,
+    interval,
+    isSupported
+  };
+}

package/dist/useDeviceOrientation.d.ts

@@ -0,0 +1,15 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive device orientation.
+ * Tracks device orientation using the DeviceOrientationEvent API.
+ *
+ * @returns Reactive alpha, beta, gamma angles, absolute flag, and support status
+ */
+export declare function useDeviceOrientation(): UseDeviceOrientationReturn;
+export declare interface UseDeviceOrientationReturn {
+  alpha: Ref<number | null>
+  beta: Ref<number | null>
+  gamma: Ref<number | null>
+  absolute: Ref<boolean>
+  isSupported: Ref<boolean>
+}

package/dist/useDeviceOrientation.js

@@ -0,0 +1,23 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { noop } from "./_shared";
+export function useDeviceOrientation() {
+  const isSupported = ref(typeof window < "u" && "DeviceOrientationEvent" in window), alpha = ref(null), beta = ref(null), gamma = ref(null), absolute = ref(!1);
+  let cleanup = noop;
+  if (typeof window < "u" && isSupported.value) {
+    const handler = (event) => {
+      alpha.value = event.alpha;
+      beta.value = event.beta;
+      gamma.value = event.gamma;
+      absolute.value = event.absolute;
+    };
+    window.addEventListener("deviceorientation", handler, { passive: !0 });
+    cleanup = () => {
+      window.removeEventListener("deviceorientation", handler);
+      cleanup = noop;
+    };
+  }
+  try {
+    onUnmounted(() => cleanup());
+  } catch {}
+  return { alpha, beta, gamma, absolute, isSupported };
+}

package/dist/useDevicePixelRatio.d.ts

@@ -0,0 +1,5 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactively track the device pixel ratio.
+ */
+export declare function useDevicePixelRatio(): { pixelRatio: Ref<number> };

package/dist/useDevicePixelRatio.js

@@ -0,0 +1,24 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function useDevicePixelRatio() {
+  const pixelRatio = ref(typeof window < "u" ? window.devicePixelRatio : 1);
+  if (typeof window > "u")
+    return { pixelRatio };
+  let mq = null, cleanup = () => {};
+  function observe() {
+    cleanup();
+    mq = window.matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`);
+    const handler = () => {
+      pixelRatio.value = window.devicePixelRatio;
+      observe();
+    };
+    mq.addEventListener("change", handler, { once: !0 });
+    cleanup = () => {
+      mq?.removeEventListener("change", handler);
+    };
+  }
+  observe();
+  try {
+    onUnmounted(() => cleanup());
+  } catch {}
+  return { pixelRatio };
+}

package/dist/useDocumentVisibility.d.ts

@@ -0,0 +1,5 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactively track `document.visibilityState`.
+ */
+export declare function useDocumentVisibility(): Ref<DocumentVisibilityState>;

package/dist/useDocumentVisibility.js

@@ -0,0 +1,16 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function useDocumentVisibility() {
+  const visibility = ref(typeof document < "u" ? document.visibilityState : "visible");
+  if (typeof document > "u")
+    return visibility;
+  const handler = () => {
+    visibility.value = document.visibilityState;
+  };
+  document.addEventListener("visibilitychange", handler, { passive: !0 });
+  try {
+    onUnmounted(() => {
+      document.removeEventListener("visibilitychange", handler);
+    });
+  } catch {}
+  return visibility;
+}

package/dist/useDraggable.d.ts

@@ -0,0 +1,23 @@
+import { type MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Make an element draggable.
+ * Handles pointer events to enable drag-and-drop positioning.
+ *
+ * @param target - The element to make draggable (or a Ref to one)
+ * @param options - Configuration for initial position and drag callbacks
+ * @returns Reactive x, y position, dragging state, and computed style string
+ */
+export declare function useDraggable(target: MaybeRef<HTMLElement | null>, options?: UseDraggableOptions): UseDraggableReturn;
+export declare interface UseDraggableOptions {
+  initialValue?: { x: number, y: number }
+  onStart?: (position: { x: number, y: number }, event: PointerEvent) => void | false
+  onMove?: (position: { x: number, y: number }, event: PointerEvent) => void
+  onEnd?: (position: { x: number, y: number }, event: PointerEvent) => void
+}
+export declare interface UseDraggableReturn {
+  x: Ref<number>
+  y: Ref<number>
+  isDragging: Ref<boolean>
+  style: Ref<string>
+}

package/dist/useDraggable.js

@@ -0,0 +1,58 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { unref, noop } from "./_shared";
+export function useDraggable(target, options) {
+  const initialX = options?.initialValue?.x ?? 0, initialY = options?.initialValue?.y ?? 0, x = ref(initialX), y = ref(initialY), isDragging = ref(!1), style = ref(`left: ${initialX}px; top: ${initialY}px;`);
+  let cleanup = noop;
+  if (typeof window < "u") {
+    const cleanups = [];
+    let startX = 0, startY = 0, offsetX = 0, offsetY = 0;
+    const updateStyle = () => {
+      style.value = `left: ${x.value}px; top: ${y.value}px;`;
+    }, onPointerMove = (event) => {
+      if (!isDragging.value)
+        return;
+      x.value = event.clientX - offsetX;
+      y.value = event.clientY - offsetY;
+      updateStyle();
+      if (options?.onMove)
+        options.onMove({ x: x.value, y: y.value }, event);
+    }, onPointerUp = (event) => {
+      if (!isDragging.value)
+        return;
+      isDragging.value = !1;
+      if (options?.onEnd)
+        options.onEnd({ x: x.value, y: y.value }, event);
+      window.removeEventListener("pointermove", onPointerMove);
+      window.removeEventListener("pointerup", onPointerUp);
+    }, onPointerDown = (event) => {
+      const pos = { x: x.value, y: y.value };
+      if (options?.onStart) {
+        if (options.onStart(pos, event) === !1)
+          return;
+      }
+      startX = event.clientX;
+      startY = event.clientY;
+      offsetX = startX - x.value;
+      offsetY = startY - y.value;
+      isDragging.value = !0;
+      window.addEventListener("pointermove", onPointerMove);
+      window.addEventListener("pointerup", onPointerUp);
+    }, el = unref(target);
+    if (el) {
+      el.addEventListener("pointerdown", onPointerDown);
+      cleanups.push(() => el.removeEventListener("pointerdown", onPointerDown));
+    }
+    cleanup = () => {
+      for (const fn of cleanups)
+        fn();
+      cleanups.length = 0;
+      window.removeEventListener("pointermove", onPointerMove);
+      window.removeEventListener("pointerup", onPointerUp);
+      cleanup = noop;
+    };
+  }
+  try {
+    onUnmounted(() => cleanup());
+  } catch {}
+  return { x, y, isDragging, style };
+}

package/dist/useDropZone.d.ts

@@ -0,0 +1,15 @@
+import { type MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Drop zone for drag and drop files.
+ * Tracks when files are dragged over the target element and captures dropped files.
+ *
+ * @param target - The drop zone element (or a Ref to one)
+ * @param onDrop - Optional callback called when files are dropped
+ * @returns Reactive isOverDropZone state and dropped files
+ */
+export declare function useDropZone(target: MaybeRef<HTMLElement | null>, onDrop?: (files: File[] | null) => void): UseDropZoneReturn;
+export declare interface UseDropZoneReturn {
+  isOverDropZone: Ref<boolean>
+  files: Ref<File[] | null>
+}

package/dist/useDropZone.js

@@ -0,0 +1,52 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { unref, noop } from "./_shared";
+export function useDropZone(target, onDrop) {
+  const isOverDropZone = ref(!1), files = ref(null);
+  let cleanup = noop, dragCounter = 0;
+  if (typeof window < "u") {
+    const el = unref(target);
+    if (el) {
+      const cleanups = [], onDragEnter = (event) => {
+        event.preventDefault();
+        dragCounter++;
+        isOverDropZone.value = !0;
+      }, onDragOver = (event) => {
+        event.preventDefault();
+        isOverDropZone.value = !0;
+      }, onDragLeave = (event) => {
+        event.preventDefault();
+        dragCounter--;
+        if (dragCounter <= 0) {
+          dragCounter = 0;
+          isOverDropZone.value = !1;
+        }
+      }, onDropHandler = (event) => {
+        event.preventDefault();
+        dragCounter = 0;
+        isOverDropZone.value = !1;
+        const droppedFiles = event.dataTransfer?.files;
+        if (droppedFiles && droppedFiles.length > 0)
+          files.value = Array.from(droppedFiles);
+        else
+          files.value = null;
+        if (onDrop)
+          onDrop(files.value);
+      };
+      el.addEventListener("dragenter", onDragEnter);
+      el.addEventListener("dragover", onDragOver);
+      el.addEventListener("dragleave", onDragLeave);
+      el.addEventListener("drop", onDropHandler);
+      cleanups.push(() => el.removeEventListener("dragenter", onDragEnter), () => el.removeEventListener("dragover", onDragOver), () => el.removeEventListener("dragleave", onDragLeave), () => el.removeEventListener("drop", onDropHandler));
+      cleanup = () => {
+        for (const fn of cleanups)
+          fn();
+        cleanups.length = 0;
+        cleanup = noop;
+      };
+    }
+  }
+  try {
+    onUnmounted(() => cleanup());
+  } catch {}
+  return { isOverDropZone, files };
+}

package/dist/useElementBounding.d.ts

@@ -0,0 +1,21 @@
+import { type MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive element bounding rect.
+ * Tracks the element's position and size, updating on resize, scroll, and mutations.
+ *
+ * @param target - The element to observe (or a Ref to one)
+ * @returns Reactive bounding rect properties and update function
+ */
+export declare function useElementBounding(target: MaybeRef<HTMLElement | null>): UseElementBoundingReturn;
+export declare interface UseElementBoundingReturn {
+  x: Ref<number>
+  y: Ref<number>
+  top: Ref<number>
+  right: Ref<number>
+  bottom: Ref<number>
+  left: Ref<number>
+  width: Ref<number>
+  height: Ref<number>
+  update: () => void
+}

package/dist/useElementBounding.js

@@ -0,0 +1,59 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { unref, noop } from "./_shared";
+export function useElementBounding(target) {
+  const x = ref(0), y = ref(0), top = ref(0), right = ref(0), bottom = ref(0), left = ref(0), width = ref(0), height = ref(0), cleanups = [];
+  let cleanup = noop;
+  const update = () => {
+    const el = unref(target);
+    if (!el)
+      return;
+    const rect = el.getBoundingClientRect();
+    x.value = rect.x;
+    y.value = rect.y;
+    top.value = rect.top;
+    right.value = rect.right;
+    bottom.value = rect.bottom;
+    left.value = rect.left;
+    width.value = rect.width;
+    height.value = rect.height;
+  };
+  if (typeof window < "u") {
+    update();
+    const onResize = () => update();
+    window.addEventListener("resize", onResize, { passive: !0 });
+    cleanups.push(() => window.removeEventListener("resize", onResize));
+    const onScroll = () => update();
+    window.addEventListener("scroll", onScroll, { passive: !0 });
+    cleanups.push(() => window.removeEventListener("scroll", onScroll));
+    if ("ResizeObserver" in window) {
+      const el = unref(target);
+      if (el) {
+        const resizeObserver = new ResizeObserver(update);
+        resizeObserver.observe(el);
+        cleanups.push(() => resizeObserver.disconnect());
+      }
+    }
+    if ("MutationObserver" in window) {
+      const el = unref(target);
+      if (el) {
+        const mutationObserver = new MutationObserver(update);
+        mutationObserver.observe(el, {
+          childList: !0,
+          subtree: !0,
+          attributes: !0
+        });
+        cleanups.push(() => mutationObserver.disconnect());
+      }
+    }
+    cleanup = () => {
+      for (const fn of cleanups)
+        fn();
+      cleanups.length = 0;
+      cleanup = noop;
+    };
+  }
+  try {
+    onUnmounted(() => cleanup());
+  } catch {}
+  return { x, y, top, right, bottom, left, width, height, update };
+}

package/dist/useElementByPoint.d.ts

@@ -0,0 +1,10 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive element at a given point. Tracks the element under the mouse cursor.
+ */
+export declare function useElementByPoint(options?: { x?: Ref<number>, y?: Ref<number> }): UseElementByPointReturn;
+export declare interface UseElementByPointReturn {
+  element: Ref<Element | null>
+  x: Ref<number>
+  y: Ref<number>
+}

package/dist/useElementByPoint.js

@@ -0,0 +1,18 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function useElementByPoint(options) {
+  const x = options?.x ?? ref(0), y = options?.y ?? ref(0), element = ref(null);
+  if (typeof document > "u")
+    return { element, x, y };
+  const handler = (e) => {
+    x.value = e.clientX;
+    y.value = e.clientY;
+    element.value = document.elementFromPoint(e.clientX, e.clientY);
+  };
+  document.addEventListener("mousemove", handler, { passive: !0 });
+  try {
+    onUnmounted(() => {
+      document.removeEventListener("mousemove", handler);
+    });
+  } catch {}
+  return { element, x, y };
+}

package/dist/useElementHover.d.ts

@@ -0,0 +1,9 @@
+import type { MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive element hover state.
+ *
+ * @param target - The target element or a ref to one
+ * @returns A ref that is true when the element is being hovered
+ */
+export declare function useElementHover(target: MaybeRef<HTMLElement | null | undefined>): Ref<boolean>;

package/dist/useElementHover.js

@@ -0,0 +1,28 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { unref } from "./_shared";
+export function useElementHover(target) {
+  const isHovered = ref(!1);
+  let cleanup = () => {};
+  function setup(el) {
+    cleanup();
+    if (!el)
+      return;
+    const onEnter = () => {
+      isHovered.value = !0;
+    }, onLeave = () => {
+      isHovered.value = !1;
+    };
+    el.addEventListener("mouseenter", onEnter, { passive: !0 });
+    el.addEventListener("mouseleave", onLeave, { passive: !0 });
+    cleanup = () => {
+      el.removeEventListener("mouseenter", onEnter);
+      el.removeEventListener("mouseleave", onLeave);
+      cleanup = () => {};
+    };
+  }
+  setup(unref(target));
+  try {
+    onUnmounted(() => cleanup());
+  } catch {}
+  return isHovered;
+}

package/dist/useElementSize.d.ts

@@ -0,0 +1,19 @@
+import { type MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive element dimensions.
+ * Uses ResizeObserver to track the width and height of an element.
+ *
+ * @param target - The element to observe (or a Ref to one)
+ * @param options - Configuration with optional initial size
+ * @returns Reactive width, height, and a stop function
+ */
+export declare function useElementSize(target: MaybeRef<HTMLElement | null>, options?: UseElementSizeOptions): UseElementSizeReturn;
+export declare interface UseElementSizeOptions {
+  initialSize?: { width: number, height: number }
+}
+export declare interface UseElementSizeReturn {
+  width: Ref<number>
+  height: Ref<number>
+  stop: () => void
+}