@stacksjs/composables 0.70.88 → 0.70.91

package/dist/useForm.js

@@ -0,0 +1,182 @@
+import { ref } from "@stacksjs/stx";
+export function useForm(opts) {
+  const validateOn = opts.validateOn ?? "submit", initial = { ...opts.initialValues }, values = ref({ ...initial }), errors = ref({}), touched = ref({}), dirty = ref({}), isSubmitting = ref(!1), isValid = ref(!0), isDirty = ref(!1);
+  function firstMessage(result) {
+    if (result.valid)
+      return "";
+    if (Array.isArray(result.errors))
+      return result.errors[0]?.message ?? "Invalid";
+    for (const list of Object.values(result.errors))
+      if (list.length > 0)
+        return list[0]?.message ?? "Invalid";
+    return "Invalid";
+  }
+  function validateField(name) {
+    const v = opts.schema?.[name];
+    if (!v)
+      return !0;
+    const result = v.validate(values.value[name]), message = firstMessage(result);
+    if (message) {
+      errors.value = { ...errors.value, [name]: message };
+      isValid.value = !1;
+      return !1;
+    }
+    if (errors.value[name]) {
+      const { [name]: _, ...rest } = errors.value;
+      errors.value = rest;
+    }
+    isValid.value = Object.keys(errors.value).length === 0;
+    return !0;
+  }
+  function setFieldValue(name, value) {
+    values.value = { ...values.value, [name]: value };
+    dirty.value = { ...dirty.value, [name]: value !== initial[name] };
+    isDirty.value = !0;
+    if (validateOn === "change")
+      validateField(name);
+  }
+  function setFieldTouched(name, isTouched = !0) {
+    touched.value = { ...touched.value, [name]: isTouched };
+    if (isTouched)
+      isDirty.value = !0;
+  }
+  function field(name) {
+    const key = name, errorId = `${key}-error`, onBlur = () => {
+      setFieldTouched(name, !0);
+      if (validateOn === "blur" || validateOn === "change")
+        validateField(name);
+    };
+    return {
+      get value() {
+        return values.value[name];
+      },
+      get error() {
+        return errors.value[key] ?? "";
+      },
+      get touched() {
+        return !!touched.value[key];
+      },
+      get dirty() {
+        return !!dirty.value[key];
+      },
+      errorId,
+      setValue: (next) => setFieldValue(name, next),
+      onBlur,
+      validate: () => validateField(name),
+      inputProps: () => {
+        const hasError = !!errors.value[key];
+        return {
+          name: key,
+          value: values.value[name],
+          onInput: (eventOrValue) => {
+            const next = eventOrValue && typeof eventOrValue === "object" && "target" in eventOrValue ? eventOrValue.target.value : eventOrValue;
+            setFieldValue(name, next);
+          },
+          onBlur,
+          "aria-invalid": hasError,
+          "aria-describedby": hasError ? errorId : void 0
+        };
+      }
+    };
+  }
+  function validateAll() {
+    let ok = !0;
+    for (const name of Object.keys(opts.schema ?? {}))
+      if (!validateField(name))
+        ok = !1;
+    return ok;
+  }
+  function setError(name, message) {
+    errors.value = { ...errors.value, [name]: message };
+    isValid.value = !1;
+  }
+  function setErrors(errorMap) {
+    const next = { ...errors.value };
+    let changed = !1;
+    const list = Object.entries(errorMap);
+    for (const [key, msg] of list) {
+      if (msg == null)
+        continue;
+      const message = Array.isArray(msg) ? msg[0] : msg;
+      if (message == null || message === "")
+        continue;
+      next[key] = message;
+      changed = !0;
+    }
+    errors.value = next;
+    if (changed)
+      isValid.value = !1;
+  }
+  function clearErrors(name) {
+    if (name == null) {
+      errors.value = {};
+      isValid.value = !0;
+      return;
+    }
+    const { [name]: _, ...rest } = errors.value;
+    errors.value = rest;
+    isValid.value = Object.keys(errors.value).length === 0;
+  }
+  async function handleSubmit() {
+    const allTouched = {};
+    for (const k of Object.keys(values.value))
+      allTouched[k] = !0;
+    touched.value = allTouched;
+    if (!validateAll()) {
+      opts.onError?.(errors.value);
+      return;
+    }
+    isSubmitting.value = !0;
+    try {
+      await opts.onSubmit(values.value);
+    } catch (err) {
+      const e = err instanceof Error ? err : Error(String(err));
+      setError("form", e.message);
+      opts.onError?.(e);
+    } finally {
+      isSubmitting.value = !1;
+    }
+  }
+  function reset() {
+    values.value = { ...initial };
+    errors.value = {};
+    touched.value = {};
+    dirty.value = {};
+    isSubmitting.value = !1;
+    isValid.value = !0;
+    isDirty.value = !1;
+  }
+  function submitButtonProps() {
+    return {
+      type: "submit",
+      disabled: isSubmitting.value,
+      "aria-busy": isSubmitting.value
+    };
+  }
+  function firstErrorField() {
+    for (const k of Object.keys(initial))
+      if (errors.value[k])
+        return k;
+    return null;
+  }
+  return {
+    values,
+    errors,
+    touched,
+    dirty,
+    isSubmitting,
+    isValid,
+    isDirty,
+    field,
+    setValue: setFieldValue,
+    setError,
+    setErrors,
+    clearErrors,
+    setTouched: setFieldTouched,
+    validate: validateAll,
+    handleSubmit,
+    reset,
+    submitButtonProps,
+    firstErrorField
+  };
+}

package/dist/useFps.d.ts

@@ -0,0 +1,7 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive FPS (frames per second) counter.
+ *
+ * @param every - How many frames between updates. Default: 10
+ */
+export declare function useFps(every?: number): Ref<number>;

package/dist/useFps.js

@@ -0,0 +1,22 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function useFps(every = 10) {
+  const fps = ref(0);
+  if (typeof requestAnimationFrame > "u")
+    return fps;
+  let last = performance.now(), ticks = 0, rafId;
+  function loop() {
+    ticks++;
+    if (ticks >= every) {
+      const now = performance.now(), diff = now - last;
+      fps.value = Math.round(ticks / diff * 1000);
+      last = now;
+      ticks = 0;
+    }
+    rafId = requestAnimationFrame(loop);
+  }
+  rafId = requestAnimationFrame(loop);
+  try {
+    onUnmounted(() => cancelAnimationFrame(rafId));
+  } catch {}
+  return fps;
+}

package/dist/useFullscreen.d.ts

@@ -0,0 +1,16 @@
+import type { MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive Fullscreen API.
+ * Enter, exit, and toggle fullscreen mode on an element.
+ *
+ * @param target - Target element (defaults to documentElement)
+ */
+export declare function useFullscreen(target?: MaybeRef<HTMLElement | null>): UseFullscreenReturn;
+export declare interface UseFullscreenReturn {
+  isFullscreen: Ref<boolean>
+  isSupported: Ref<boolean>
+  enter: () => Promise<void>
+  exit: () => Promise<void>
+  toggle: () => Promise<void>
+}

package/dist/useFullscreen.js

@@ -0,0 +1,67 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { defaultDocument, unref } from "./_shared";
+export function useFullscreen(target) {
+  const doc = defaultDocument(), isFullscreen = ref(!1), isSupported = ref(!!doc && (("fullscreenEnabled" in doc) || ("webkitFullscreenEnabled" in doc)));
+  function getTarget() {
+    if (target)
+      return unref(target);
+    return doc?.documentElement ?? null;
+  }
+  function getFullscreenElement() {
+    if (!doc)
+      return null;
+    return doc.fullscreenElement ?? doc.webkitFullscreenElement ?? null;
+  }
+  function updateState() {
+    isFullscreen.value = getFullscreenElement() !== null;
+  }
+  async function enter() {
+    if (!isSupported.value)
+      return;
+    const el = getTarget();
+    if (!el)
+      return;
+    try {
+      if (el.requestFullscreen)
+        await el.requestFullscreen();
+      else if (el.webkitRequestFullscreen)
+        await el.webkitRequestFullscreen();
+      isFullscreen.value = !0;
+    } catch {}
+  }
+  async function exit() {
+    if (!isSupported.value || !doc)
+      return;
+    try {
+      if (doc.exitFullscreen)
+        await doc.exitFullscreen();
+      else if (doc.webkitExitFullscreen)
+        await doc.webkitExitFullscreen();
+      isFullscreen.value = !1;
+    } catch {}
+  }
+  async function toggle() {
+    if (isFullscreen.value)
+      await exit();
+    else
+      await enter();
+  }
+  if (doc) {
+    const handler = () => updateState();
+    doc.addEventListener("fullscreenchange", handler);
+    doc.addEventListener("webkitfullscreenchange", handler);
+    try {
+      onUnmounted(() => {
+        doc.removeEventListener("fullscreenchange", handler);
+        doc.removeEventListener("webkitfullscreenchange", handler);
+      });
+    } catch {}
+  }
+  return {
+    isFullscreen,
+    isSupported,
+    enter,
+    exit,
+    toggle
+  };
+}

package/dist/useGeolocation.d.ts

@@ -0,0 +1,26 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive geolocation.
+ * Tracks the user's geographic position using the Geolocation API.
+ *
+ * @param options - PositionOptions plus an immediate flag (default: true)
+ * @returns Reactive coords, location timestamp, error, support status, and pause/resume controls
+ */
+export declare function useGeolocation(options?: PositionOptions & { immediate?: boolean }): UseGeolocationReturn;
+export declare interface UseGeolocationCoords {
+  latitude: Ref<number | null>
+  longitude: Ref<number | null>
+  accuracy: Ref<number | null>
+  altitude: Ref<number | null>
+  altitudeAccuracy: Ref<number | null>
+  heading: Ref<number | null>
+  speed: Ref<number | null>
+}
+export declare interface UseGeolocationReturn {
+  coords: UseGeolocationCoords
+  locatedAt: Ref<number | null>
+  error: Ref<GeolocationPositionError | null>
+  isSupported: Ref<boolean>
+  pause: () => void
+  resume: () => void
+}

package/dist/useGeolocation.js

@@ -0,0 +1,55 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { noop } from "./_shared";
+export function useGeolocation(options) {
+  const { immediate = !0, ...positionOptions } = options ?? {}, isSupported = ref(typeof navigator < "u" && "geolocation" in navigator), coords = {
+    latitude: ref(null),
+    longitude: ref(null),
+    accuracy: ref(null),
+    altitude: ref(null),
+    altitudeAccuracy: ref(null),
+    heading: ref(null),
+    speed: ref(null)
+  }, locatedAt = ref(null), error = ref(null);
+  let watchId = null, cleanup = noop;
+  const updatePosition = (position) => {
+    coords.latitude.value = position.coords.latitude;
+    coords.longitude.value = position.coords.longitude;
+    coords.accuracy.value = position.coords.accuracy;
+    coords.altitude.value = position.coords.altitude;
+    coords.altitudeAccuracy.value = position.coords.altitudeAccuracy;
+    coords.heading.value = position.coords.heading;
+    coords.speed.value = position.coords.speed;
+    locatedAt.value = position.timestamp;
+    error.value = null;
+  }, onError = (err) => {
+    error.value = err;
+  }, resume = () => {
+    if (!isSupported.value)
+      return;
+    if (watchId !== null)
+      return;
+    watchId = navigator.geolocation.watchPosition(updatePosition, onError, positionOptions);
+    cleanup = () => {
+      if (watchId !== null) {
+        navigator.geolocation.clearWatch(watchId);
+        watchId = null;
+      }
+      cleanup = noop;
+    };
+  }, pause = () => {
+    cleanup();
+  };
+  if (immediate)
+    resume();
+  try {
+    onUnmounted(pause);
+  } catch {}
+  return {
+    coords,
+    locatedAt,
+    error,
+    isSupported,
+    pause,
+    resume
+  };
+}

package/dist/useIdle.d.ts

@@ -0,0 +1,18 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * User idle detection.
+ * Tracks whether the user is idle based on activity events.
+ *
+ * @param timeout - Idle timeout in milliseconds. Default: 60000 (1 minute)
+ * @param options - Configuration for events and initial state
+ * @returns Reactive idle state and last active timestamp
+ */
+export declare function useIdle(timeout?: number, options?: UseIdleOptions): UseIdleReturn;
+export declare interface UseIdleOptions {
+  events?: string[]
+  initialState?: boolean
+}
+export declare interface UseIdleReturn {
+  idle: Ref<boolean>
+  lastActive: Ref<number>
+}

package/dist/useIdle.js

@@ -0,0 +1,46 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { noop } from "./_shared";
+const DEFAULT_EVENTS = [
+  "mousemove",
+  "mousedown",
+  "resize",
+  "keydown",
+  "touchstart",
+  "wheel"
+];
+export function useIdle(timeout = 60000, options) {
+  const events = options?.events ?? DEFAULT_EVENTS, initialState = options?.initialState ?? !1, idle = ref(initialState), lastActive = ref(Date.now());
+  let timer = null, cleanup = noop;
+  if (typeof window < "u") {
+    const cleanups = [], reset = () => {
+      idle.value = !1;
+      lastActive.value = Date.now();
+      if (timer !== null)
+        clearTimeout(timer);
+      timer = setTimeout(() => {
+        idle.value = !0;
+      }, timeout);
+    };
+    for (const event of events) {
+      window.addEventListener(event, reset, { passive: !0 });
+      cleanups.push(() => window.removeEventListener(event, reset));
+    }
+    timer = setTimeout(() => {
+      idle.value = !0;
+    }, timeout);
+    cleanup = () => {
+      for (const fn of cleanups)
+        fn();
+      cleanups.length = 0;
+      if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      cleanup = noop;
+    };
+  }
+  try {
+    onUnmounted(() => cleanup());
+  } catch {}
+  return { idle, lastActive };
+}

package/dist/useImage.d.ts

@@ -0,0 +1,18 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive image loading state.
+ */
+export declare function useImage(options: UseImageOptions): UseImageReturn;
+export declare interface UseImageOptions {
+  src: string
+  srcset?: string
+  sizes?: string
+  alt?: string
+  crossorigin?: string
+  referrerpolicy?: string
+}
+export declare interface UseImageReturn {
+  isLoading: Ref<boolean>
+  error: Ref<string | null>
+  isReady: Ref<boolean>
+}

package/dist/useImage.js

@@ -0,0 +1,32 @@
+import { ref } from "@stacksjs/stx";
+export function useImage(options) {
+  const isLoading = ref(!0), isReady = ref(!1), error = ref(null);
+  if (typeof Image > "u") {
+    isLoading.value = !1;
+    return { isLoading, error, isReady };
+  }
+  const img = new Image;
+  img.onload = () => {
+    isLoading.value = !1;
+    isReady.value = !0;
+  };
+  img.onerror = (e) => {
+    isLoading.value = !1;
+    if (typeof e === "string")
+      error.value = e;
+    else if (e instanceof Event && e.type === "error")
+      error.value = `Failed to load image: ${options.src}`;
+    else
+      error.value = "Failed to load image";
+  };
+  if (options.crossorigin)
+    img.crossOrigin = options.crossorigin;
+  if (options.referrerpolicy)
+    img.referrerPolicy = options.referrerpolicy;
+  if (options.sizes)
+    img.sizes = options.sizes;
+  if (options.srcset)
+    img.srcset = options.srcset;
+  img.src = options.src;
+  return { isLoading, error, isReady };
+}

package/dist/useInfiniteScroll.d.ts

@@ -0,0 +1,11 @@
+import type { MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Infinite scroll detection.
+ * Calls the `onLoadMore` callback when the user scrolls near the edge.
+ */
+export declare function useInfiniteScroll(target: MaybeRef<HTMLElement | Window | null | undefined>, onLoadMore: () => void | Promise<void>, options?: UseInfiniteScrollOptions): { isLoading: Ref<boolean> };
+export declare interface UseInfiniteScrollOptions {
+  distance?: number
+  direction?: 'top' | 'bottom' | 'left' | 'right'
+}

package/dist/useInfiniteScroll.js

@@ -0,0 +1,50 @@
+import { onUnmounted, ref, watch } from "@stacksjs/stx";
+import { unref } from "./_shared";
+export function useInfiniteScroll(target, onLoadMore, options = {}) {
+  const { distance = 100, direction = "bottom" } = options, isLoading = ref(!1);
+  let active = !0;
+  const handler = async () => {
+    if (!active || isLoading.value)
+      return;
+    const el = unref(target);
+    if (!el)
+      return;
+    let shouldLoad = !1;
+    if (el === window || el === document.documentElement) {
+      const scrollTop = window.scrollY || document.documentElement.scrollTop, scrollHeight = document.documentElement.scrollHeight, clientHeight = window.innerHeight;
+      if (direction === "bottom")
+        shouldLoad = scrollHeight - scrollTop - clientHeight <= distance;
+      else if (direction === "top")
+        shouldLoad = scrollTop <= distance;
+    } else {
+      const element = el;
+      if (direction === "bottom")
+        shouldLoad = element.scrollHeight - element.scrollTop - element.clientHeight <= distance;
+      else if (direction === "top")
+        shouldLoad = element.scrollTop <= distance;
+      else if (direction === "right")
+        shouldLoad = element.scrollWidth - element.scrollLeft - element.clientWidth <= distance;
+      else if (direction === "left")
+        shouldLoad = element.scrollLeft <= distance;
+    }
+    if (shouldLoad) {
+      isLoading.value = !0;
+      try {
+        await onLoadMore();
+      } finally {
+        isLoading.value = !1;
+      }
+    }
+  }, el = unref(target);
+  if (el) {
+    const scrollTarget = el === document.documentElement ? window : el;
+    scrollTarget.addEventListener("scroll", handler, { passive: !0 });
+    try {
+      onUnmounted(() => {
+        active = !1;
+        scrollTarget.removeEventListener("scroll", handler);
+      });
+    } catch {}
+  }
+  return { isLoading };
+}

package/dist/useIntersectionObserver.d.ts

@@ -0,0 +1,16 @@
+import { type MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive IntersectionObserver.
+ * Observes the target element and calls the callback when intersection changes.
+ *
+ * @param target - The element to observe (or a Ref to one)
+ * @param callback - IntersectionObserverCallback
+ * @param options - IntersectionObserverInit options
+ * @returns isSupported ref and stop function
+ */
+export declare function useIntersectionObserver(target: MaybeRef<HTMLElement | null>, callback: IntersectionObserverCallback, options?: IntersectionObserverInit): UseIntersectionObserverReturn;
+export declare interface UseIntersectionObserverReturn {
+  isSupported: Ref<boolean>
+  stop: () => void
+}

package/dist/useIntersectionObserver.js

@@ -0,0 +1,27 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { unref, noop } from "./_shared";
+export function useIntersectionObserver(target, callback, options) {
+  const isSupported = ref(typeof window < "u" && "IntersectionObserver" in window);
+  let cleanup = noop;
+  (() => {
+    cleanup();
+    if (!isSupported.value)
+      return;
+    const el = unref(target);
+    if (!el)
+      return;
+    const observer = new IntersectionObserver(callback, options);
+    observer.observe(el);
+    cleanup = () => {
+      observer.disconnect();
+      cleanup = noop;
+    };
+  })();
+  const stop = () => {
+    cleanup();
+  };
+  try {
+    onUnmounted(stop);
+  } catch {}
+  return { isSupported, stop };
+}

package/dist/useInterval.d.ts

@@ -0,0 +1,13 @@
+import type { Ref } from '@stacksjs/stx';
+export declare function useInterval(interval?: number, options?: { controls?: false, immediate?: boolean }): Ref<number>;
+export declare function useInterval(interval?: number, options?: UseIntervalOptions): Ref<number> | UseIntervalControls;
+declare interface UseIntervalControls {
+  counter: Ref<number>
+  pause: () => void
+  resume: () => void
+  reset: () => void
+}
+declare interface UseIntervalOptions {
+  controls?: boolean
+  immediate?: boolean
+}

package/dist/useInterval.js

@@ -0,0 +1,32 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function useInterval(interval = 1000, options = {}) {
+  const { controls = !1, immediate = !0 } = options, counter = ref(0);
+  let intervalId = null;
+  function pause() {
+    if (intervalId !== null) {
+      clearInterval(intervalId);
+      intervalId = null;
+    }
+  }
+  function resume() {
+    if (intervalId !== null)
+      return;
+    intervalId = setInterval(() => {
+      counter.value++;
+    }, interval);
+  }
+  function reset() {
+    counter.value = 0;
+    pause();
+    if (immediate)
+      resume();
+  }
+  if (immediate)
+    resume();
+  try {
+    onUnmounted(pause);
+  } catch {}
+  if (controls)
+    return { counter, pause, resume, reset };
+  return counter;
+}

package/dist/useIntervalFn.d.ts

@@ -0,0 +1,16 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Call a function on a regular interval.
+ * Provides pause/resume controls and auto-cleanup on unmount.
+ *
+ * @param cb - The callback to invoke on each interval tick
+ * @param interval - Interval duration in milliseconds (default 1000)
+ * @param options - Configuration options
+ * @returns Controls to pause, resume, and check active state
+ */
+export declare function useIntervalFn(cb: () => void, interval?: number, options?: { immediate?: boolean }): UseIntervalFnReturn;
+declare interface UseIntervalFnReturn {
+  pause: () => void
+  resume: () => void
+  isActive: Ref<boolean>
+}