@stacksjs/composables 0.70.87 → 0.70.90

package/dist/useSwipe.js

@@ -0,0 +1,58 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { unref } from "./_shared";
+export function useSwipe(target, options = {}) {
+  const { threshold = 50, onSwipe, onSwipeStart, onSwipeEnd, passive = !0 } = options, isSwiping = ref(!1), direction = ref("none"), lengthX = ref(0), lengthY = ref(0);
+  let startX = 0, startY = 0;
+  if (typeof window > "u")
+    return { isSwiping, direction, lengthX, lengthY };
+  const el = unref(target) ?? window, onTouchStart = (e) => {
+    const touch = e.touches[0];
+    if (!touch)
+      return;
+    startX = touch.clientX;
+    startY = touch.clientY;
+    isSwiping.value = !0;
+    direction.value = "none";
+    lengthX.value = 0;
+    lengthY.value = 0;
+    onSwipeStart?.(e);
+  }, onTouchMove = (e) => {
+    if (!isSwiping.value)
+      return;
+    const touch = e.touches[0];
+    if (!touch)
+      return;
+    lengthX.value = touch.clientX - startX;
+    lengthY.value = touch.clientY - startY;
+    const absX = Math.abs(lengthX.value), absY = Math.abs(lengthY.value);
+    if (absX > absY)
+      direction.value = lengthX.value > 0 ? "right" : "left";
+    else if (absY > absX)
+      direction.value = lengthY.value > 0 ? "down" : "up";
+  }, onTouchEnd = (e) => {
+    if (!isSwiping.value)
+      return;
+    isSwiping.value = !1;
+    const absX = Math.abs(lengthX.value), absY = Math.abs(lengthY.value);
+    if (Math.max(absX, absY) >= threshold) {
+      onSwipe?.(direction.value);
+      onSwipeEnd?.(e, direction.value);
+    } else {
+      direction.value = "none";
+      onSwipeEnd?.(e, "none");
+    }
+  };
+  el.addEventListener("touchstart", onTouchStart, { passive });
+  el.addEventListener("touchmove", onTouchMove, { passive });
+  el.addEventListener("touchend", onTouchEnd, { passive });
+  el.addEventListener("touchcancel", onTouchEnd, { passive });
+  try {
+    onUnmounted(() => {
+      el.removeEventListener("touchstart", onTouchStart);
+      el.removeEventListener("touchmove", onTouchMove);
+      el.removeEventListener("touchend", onTouchEnd);
+      el.removeEventListener("touchcancel", onTouchEnd);
+    });
+  } catch {}
+  return { isSwiping, direction, lengthX, lengthY };
+}

package/dist/useTextDirection.d.ts

@@ -0,0 +1,9 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive text direction of the document or element.
+ *
+ * @param target - Target element (defaults to document.documentElement)
+ * @param initialValue - Initial direction value
+ */
+export declare function useTextDirection(target?: HTMLElement, initialValue?: TextDirection): Ref<TextDirection>;
+export type TextDirection = 'ltr' | 'rtl' | 'auto';

package/dist/useTextDirection.js

@@ -0,0 +1,16 @@
+import { ref, watch } from "@stacksjs/stx";
+export function useTextDirection(target, initialValue) {
+  const el = target ?? (typeof document < "u" ? document.documentElement : null);
+  let initial = initialValue ?? "ltr";
+  if (el) {
+    const dir = el.getAttribute("dir");
+    if (dir === "rtl" || dir === "ltr" || dir === "auto")
+      initial = dir;
+  }
+  const direction = ref(initial);
+  watch(direction, (val) => {
+    if (el)
+      el.setAttribute("dir", val);
+  });
+  return direction;
+}

package/dist/useTextSelection.d.ts

@@ -0,0 +1,10 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactively track the user's text selection.
+ */
+export declare function useTextSelection(): UseTextSelectionReturn;
+export declare interface UseTextSelectionReturn {
+  text: Ref<string>
+  ranges: Ref<Range[]>
+  selection: Ref<Selection | null>
+}

package/dist/useTextSelection.js

@@ -0,0 +1,27 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function useTextSelection() {
+  const text = ref(""), ranges = ref([]), selection = ref(null);
+  if (typeof document > "u")
+    return { text, ranges, selection };
+  const handler = () => {
+    const sel = document.getSelection();
+    selection.value = sel;
+    if (sel && sel.rangeCount > 0) {
+      text.value = sel.toString();
+      const newRanges = [];
+      for (let i = 0;i < sel.rangeCount; i++)
+        newRanges.push(sel.getRangeAt(i));
+      ranges.value = newRanges;
+    } else {
+      text.value = "";
+      ranges.value = [];
+    }
+  };
+  document.addEventListener("selectionchange", handler, { passive: !0 });
+  try {
+    onUnmounted(() => {
+      document.removeEventListener("selectionchange", handler);
+    });
+  } catch {}
+  return { text, ranges, selection };
+}

package/dist/useTextareaAutosize.d.ts

@@ -0,0 +1,10 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Automatically adjust textarea height based on content.
+ */
+export declare function useTextareaAutosize(options?: { element?: HTMLTextAreaElement, input?: string }): UseTextareaAutosizeReturn;
+export declare interface UseTextareaAutosizeReturn {
+  textarea: Ref<HTMLTextAreaElement | null>
+  input: Ref<string>
+  triggerResize: () => void
+}

package/dist/useTextareaAutosize.js

@@ -0,0 +1,20 @@
+import { ref, watch } from "@stacksjs/stx";
+export function useTextareaAutosize(options) {
+  const textarea = ref(options?.element ?? null), input = ref(options?.input ?? "");
+  function triggerResize() {
+    const el = textarea.value;
+    if (!el)
+      return;
+    el.style.height = "auto";
+    el.style.height = `${el.scrollHeight}px`;
+  }
+  watch(input, () => {
+    if (textarea.value)
+      textarea.value.value = input.value;
+    if (typeof requestAnimationFrame < "u")
+      requestAnimationFrame(triggerResize);
+    else
+      triggerResize();
+  });
+  return { textarea, input, triggerResize };
+}

package/dist/useThrottle.d.ts

@@ -0,0 +1,9 @@
+import type { MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Throttle a value. Returns a ref that updates at most once per interval.
+ *
+ * @param value - The source value or ref
+ * @param ms - Throttle interval in milliseconds. Default: 200
+ */
+export declare function useThrottle<T>(value: MaybeRef<T>, ms?: number): Ref<T>;

package/dist/useThrottle.js

@@ -0,0 +1,23 @@
+import { ref, watch } from "@stacksjs/stx";
+import { isRef, unref } from "./_shared";
+export function useThrottle(value, ms = 200) {
+  const throttled = ref(unref(value));
+  let lastUpdate = 0, timer = null;
+  if (isRef(value))
+    watch(value, (newVal) => {
+      const now = Date.now(), elapsed = now - lastUpdate;
+      if (elapsed >= ms) {
+        throttled.value = newVal;
+        lastUpdate = now;
+      } else {
+        if (timer !== null)
+          clearTimeout(timer);
+        timer = setTimeout(() => {
+          throttled.value = value.value;
+          lastUpdate = Date.now();
+          timer = null;
+        }, ms - elapsed);
+      }
+    });
+  return throttled;
+}

package/dist/useThrottleFn.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Throttle a function.
+ * Ensures the function is called at most once every `ms` milliseconds.
+ * Supports a trailing call: if the function is called during the throttle
+ * period, the last call will be executed after the period ends.
+ *
+ * @param fn - The function to throttle
+ * @param ms - Throttle interval in milliseconds (default 200)
+ * @returns The throttled function with a `cancel` method
+ */
+export declare function useThrottleFn<T extends (...args: any[]) => any>(fn: T, ms?: number): T & { cancel: () => void };

package/dist/useThrottleFn.js

@@ -0,0 +1,36 @@
+export function useThrottleFn(fn, ms = 200) {
+  let lastExec = 0, timeoutId = null, lastArgs = null, lastThis = null;
+  const throttled = function(...args) {
+    const now = Date.now(), elapsed = now - lastExec;
+    if (elapsed >= ms) {
+      lastExec = now;
+      if (timeoutId !== null) {
+        clearTimeout(timeoutId);
+        timeoutId = null;
+      }
+      fn.apply(this, args);
+    } else {
+      lastArgs = args;
+      lastThis = this;
+      if (timeoutId === null)
+        timeoutId = setTimeout(() => {
+          lastExec = Date.now();
+          timeoutId = null;
+          if (lastArgs !== null) {
+            fn.apply(lastThis, lastArgs);
+            lastArgs = null;
+            lastThis = null;
+          }
+        }, ms - elapsed);
+    }
+  };
+  throttled.cancel = () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+    lastArgs = null;
+    lastThis = null;
+  };
+  return throttled;
+}

package/dist/useThrottledRef.d.ts

@@ -0,0 +1,11 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * A ref with throttled updates.
+ * Changes to the returned ref's value are propagated at most once every `delay` ms.
+ * The last value set during a throttle period will be applied after the period ends.
+ *
+ * @param value - The initial value
+ * @param delay - Throttle delay in milliseconds (default 200)
+ * @returns A Ref whose internal value updates are throttled
+ */
+export declare function useThrottledRef<T>(value: T, delay?: number): Ref<T>;

package/dist/useThrottledRef.js

@@ -0,0 +1,30 @@
+import { ref, watch } from "@stacksjs/stx";
+export function useThrottledRef(value, delay = 200) {
+  const source = ref(value), throttled = ref(value);
+  let lastUpdate = 0, timeoutId = null;
+  watch(source, (newVal) => {
+    const now = Date.now(), elapsed = now - lastUpdate;
+    if (elapsed >= delay) {
+      lastUpdate = now;
+      throttled.value = newVal;
+      if (timeoutId !== null) {
+        clearTimeout(timeoutId);
+        timeoutId = null;
+      }
+    } else if (timeoutId === null)
+      timeoutId = setTimeout(() => {
+        lastUpdate = Date.now();
+        throttled.value = source.value;
+        timeoutId = null;
+      }, delay - elapsed);
+  });
+  return {
+    get value() {
+      return throttled.value;
+    },
+    set value(newVal) {
+      source.value = newVal;
+    },
+    subscribe: throttled.subscribe
+  };
+}

package/dist/useThrottledRefHistory.d.ts

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

package/dist/useThrottledRefHistory.js

@@ -0,0 +1,43 @@
+import { watch } from "@stacksjs/stx";
+import { useManualRefHistory } from "./useManualRefHistory";
+export function useThrottledRefHistory(source, options) {
+  const interval = options?.throttle ?? 200, { history, commit, undo, redo, canUndo, canRedo, clear, last } = useManualRefHistory(source, options);
+  let lastCommit = 0, timer = null, ignoreNext = !1;
+  watch(source, () => {
+    if (ignoreNext) {
+      ignoreNext = !1;
+      return;
+    }
+    const now = Date.now();
+    if (now - lastCommit >= interval) {
+      lastCommit = now;
+      commit();
+    } else {
+      if (timer !== null)
+        clearTimeout(timer);
+      timer = setTimeout(() => {
+        timer = null;
+        lastCommit = Date.now();
+        commit();
+      }, interval - (now - lastCommit));
+    }
+  });
+  const origUndo = undo, origRedo = redo;
+  function throttledUndo() {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    ignoreNext = !0;
+    origUndo();
+  }
+  function throttledRedo() {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    ignoreNext = !0;
+    origRedo();
+  }
+  return { history, commit, undo: throttledUndo, redo: throttledRedo, canUndo, canRedo, clear, last };
+}

package/dist/useTimeAgo.d.ts

@@ -0,0 +1,16 @@
+import { type MaybeRefOrGetter } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive relative time string.
+ * Converts a date into a human-readable relative time string
+ * (e.g., "3 minutes ago", "in 2 hours", "just now").
+ * Supports both past and future dates.
+ *
+ * @param date - The target date (Date, number, or string, or a ref/getter of one)
+ * @param options - Configuration options
+ * @returns Ref<string> with the formatted time ago string
+ */
+export declare function useTimeAgo(date: MaybeRefOrGetter<Date | number | string>, options?: UseTimeAgoOptions): Ref<string>;
+declare interface UseTimeAgoOptions {
+  updateInterval?: number
+}

package/dist/useTimeAgo.js

@@ -0,0 +1,58 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { toValue } from "./_shared";
+const SECOND = 1000, MINUTE = 60 * SECOND, HOUR = 60 * MINUTE, DAY = 24 * HOUR, WEEK = 7 * DAY, MONTH = 30 * DAY, YEAR = 365 * DAY;
+function formatTimeAgo(diff) {
+  const absDiff = Math.abs(diff);
+  if (absDiff < 5 * SECOND)
+    return "just now";
+  const isFuture = diff < 0;
+  let value, unit;
+  if (absDiff < MINUTE) {
+    value = Math.floor(absDiff / SECOND);
+    unit = "second";
+  } else if (absDiff < HOUR) {
+    value = Math.floor(absDiff / MINUTE);
+    unit = "minute";
+  } else if (absDiff < DAY) {
+    value = Math.floor(absDiff / HOUR);
+    unit = "hour";
+  } else if (absDiff < WEEK) {
+    value = Math.floor(absDiff / DAY);
+    unit = "day";
+  } else if (absDiff < MONTH) {
+    value = Math.floor(absDiff / WEEK);
+    unit = "week";
+  } else if (absDiff < YEAR) {
+    value = Math.floor(absDiff / MONTH);
+    unit = "month";
+  } else {
+    value = Math.floor(absDiff / YEAR);
+    unit = "year";
+  }
+  const plural = value !== 1 ? "s" : "";
+  if (isFuture)
+    return `in ${value} ${unit}${plural}`;
+  return `${value} ${unit}${plural} ago`;
+}
+export function useTimeAgo(date, options = {}) {
+  const { updateInterval = 30000 } = options;
+  function getTimestamp() {
+    const d = toValue(date);
+    if (d instanceof Date)
+      return d.getTime();
+    if (typeof d === "number")
+      return d;
+    return new Date(d).getTime();
+  }
+  function update() {
+    const now = Date.now(), target = getTimestamp(), diff = now - target;
+    return formatTimeAgo(diff);
+  }
+  const timeAgo = ref(update()), intervalId = setInterval(() => {
+    timeAgo.value = update();
+  }, updateInterval);
+  try {
+    onUnmounted(() => clearInterval(intervalId));
+  } catch {}
+  return timeAgo;
+}

package/dist/useTimeout.d.ts

@@ -0,0 +1,12 @@
+import type { Ref } from '@stacksjs/stx';
+export declare function useTimeout(interval?: number, options?: { controls?: false, immediate?: boolean }): Ref<boolean>;
+export declare function useTimeout(interval?: number, options?: UseTimeoutOptions): Ref<boolean> | UseTimeoutControls;
+declare interface UseTimeoutControls {
+  ready: Ref<boolean>
+  start: () => void
+  stop: () => void
+}
+declare interface UseTimeoutOptions {
+  controls?: boolean
+  immediate?: boolean
+}

package/dist/useTimeout.js

@@ -0,0 +1,32 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function useTimeout(interval = 1000, options = {}) {
+  const { controls = !1, immediate = !0 } = options, ready = ref(!1);
+  let timeoutId = null;
+  function stop() {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+    ready.value = !1;
+  }
+  function start() {
+    stop();
+    timeoutId = setTimeout(() => {
+      ready.value = !0;
+      timeoutId = null;
+    }, interval);
+  }
+  if (immediate)
+    start();
+  try {
+    onUnmounted(() => {
+      if (timeoutId !== null) {
+        clearTimeout(timeoutId);
+        timeoutId = null;
+      }
+    });
+  } catch {}
+  if (controls)
+    return { ready, start, stop };
+  return ready;
+}

package/dist/useTimeoutFn.d.ts

@@ -0,0 +1,16 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Call a function after a timeout.
+ * Provides start/stop controls and auto-cleanup on unmount.
+ *
+ * @param cb - The callback to invoke after the timeout
+ * @param interval - Timeout duration in milliseconds (default 1000)
+ * @param options - Configuration options (immediate defaults to true)
+ * @returns Controls to start, stop, and check pending state
+ */
+export declare function useTimeoutFn(cb: () => void, interval?: number, options?: { immediate?: boolean }): UseTimeoutFnReturn;
+declare interface UseTimeoutFnReturn {
+  start: () => void
+  stop: () => void
+  isPending: Ref<boolean>
+}

package/dist/useTimeoutFn.js

@@ -0,0 +1,27 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function useTimeoutFn(cb, interval = 1000, options = {}) {
+  const { immediate = !0 } = options, isPending = ref(!1);
+  let timeoutId = null;
+  function stop() {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+    isPending.value = !1;
+  }
+  function start() {
+    stop();
+    isPending.value = !0;
+    timeoutId = setTimeout(() => {
+      timeoutId = null;
+      isPending.value = !1;
+      cb();
+    }, interval);
+  }
+  if (immediate)
+    start();
+  try {
+    onUnmounted(stop);
+  } catch {}
+  return { start, stop, isPending };
+}

package/dist/useTimeoutPoll.d.ts

@@ -0,0 +1,10 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Poll a function with setTimeout. Waits for the function to complete before scheduling the next.
+ */
+export declare function useTimeoutPoll(fn: () => Promise<void> | void, interval: number, options?: { immediate?: boolean }): UseTimeoutPollReturn;
+export declare interface UseTimeoutPollReturn {
+  isActive: Ref<boolean>
+  pause: () => void
+  resume: () => void
+}

package/dist/useTimeoutPoll.js

@@ -0,0 +1,33 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function useTimeoutPoll(fn, interval, options) {
+  const { immediate = !0 } = options ?? {}, isActive = ref(!1);
+  let timer = null;
+  async function poll() {
+    if (!isActive.value)
+      return;
+    try {
+      await fn();
+    } catch {}
+    if (isActive.value)
+      timer = setTimeout(poll, interval);
+  }
+  function resume() {
+    if (isActive.value)
+      return;
+    isActive.value = !0;
+    poll();
+  }
+  function pause() {
+    isActive.value = !1;
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  }
+  if (immediate)
+    resume();
+  try {
+    onUnmounted(() => pause());
+  } catch {}
+  return { isActive, pause, resume };
+}

package/dist/useTimestamp.d.ts

@@ -0,0 +1,15 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive current timestamp.
+ * Returns a ref containing Date.now() + offset, updated on a regular interval
+ * or via requestAnimationFrame.
+ *
+ * @param options - Configuration options
+ * @returns Ref<number> with the current timestamp
+ */
+export declare function useTimestamp(options?: UseTimestampOptions): Ref<number>;
+declare interface UseTimestampOptions {
+  offset?: number
+  interval?: number | 'requestAnimationFrame'
+  immediate?: boolean
+}

package/dist/useTimestamp.js

@@ -0,0 +1,43 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function useTimestamp(options = {}) {
+  const { offset = 0, interval = 1000, immediate = !0 } = options, timestamp = ref(Date.now() + offset);
+  let intervalId = null, rafId = null, active = !1;
+  function update() {
+    timestamp.value = Date.now() + offset;
+  }
+  function cleanup() {
+    if (intervalId !== null) {
+      clearInterval(intervalId);
+      intervalId = null;
+    }
+    if (rafId !== null && typeof cancelAnimationFrame < "u") {
+      cancelAnimationFrame(rafId);
+      rafId = null;
+    }
+    active = !1;
+  }
+  function start() {
+    if (active)
+      return;
+    active = !0;
+    update();
+    if (interval === "requestAnimationFrame") {
+      if (typeof requestAnimationFrame < "u") {
+        const tick = () => {
+          if (!active)
+            return;
+          update();
+          rafId = requestAnimationFrame(tick);
+        };
+        rafId = requestAnimationFrame(tick);
+      }
+    } else
+      intervalId = setInterval(update, interval);
+  }
+  if (immediate)
+    start();
+  try {
+    onUnmounted(cleanup);
+  } catch {}
+  return timestamp;
+}

package/dist/useTitle.d.ts

@@ -0,0 +1,10 @@
+import type { MaybeRefOrGetter } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive document title.
+ * Returns a writable ref synced with document.title.
+ * If no argument is provided, reads the current document title.
+ *
+ * @param newTitle - Optional initial title (or ref/getter)
+ */
+export declare function useTitle(newTitle?: MaybeRefOrGetter<string>): Ref<string>;

package/dist/useTitle.js

@@ -0,0 +1,12 @@
+import { ref, watch } from "@stacksjs/stx";
+import { defaultDocument, toValue } from "./_shared";
+export function useTitle(newTitle) {
+  const doc = defaultDocument(), initialTitle = newTitle !== void 0 ? toValue(newTitle) : doc?.title ?? "", title = ref(initialTitle);
+  if (doc && newTitle !== void 0)
+    doc.title = title.value;
+  watch(title, (val) => {
+    if (doc)
+      doc.title = val;
+  });
+  return title;
+}

package/dist/useToNumber.d.ts

@@ -0,0 +1,11 @@
+import type { MaybeRefOrGetter } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactively convert a string ref to a number.
+ */
+export declare function useToNumber(value: MaybeRefOrGetter<string | number>, options?: UseToNumberOptions): Ref<number>;
+export declare interface UseToNumberOptions {
+  method?: 'parseFloat' | 'parseInt'
+  radix?: number
+  nanToZero?: boolean
+}