@stacksjs/composables 0.70.88 → 0.70.90

package/dist/unrefElement.js

@@ -0,0 +1,9 @@
+import { unref } from "./_shared";
+export function unrefElement(elRef) {
+  const plain = unref(elRef);
+  if (!plain)
+    return plain;
+  if (plain.$el)
+    return plain.$el;
+  return plain;
+}

package/dist/until.d.ts

@@ -0,0 +1,34 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Promise-based utility to wait for a ref to meet a condition.
+ *
+ * @param r - The reactive ref to watch
+ * @returns A chainable instance with condition methods
+ *
+ * @example
+ * ```ts
+ * const ready = ref(false)
+ * await until(ready).toBe(true)
+ * ```
+ */
+export declare function until<T>(r: Ref<T>): UntilBaseInstance<T>;
+export declare interface UntilToMatchOptions {
+  timeout?: number
+  throwOnTimeout?: boolean
+}
+export declare interface UntilBaseInstance<T> {
+  toMatch: (condition: (v: T) => boolean, options?: UntilToMatchOptions) => Promise<T>
+  toBe: (value: T, options?: UntilToMatchOptions) => Promise<T>
+  toBeTruthy: (options?: UntilToMatchOptions) => Promise<T>
+  toBeNull: (options?: UntilToMatchOptions) => Promise<T>
+  toBeUndefined: (options?: UntilToMatchOptions) => Promise<T>
+  toBeNaN: (options?: UntilToMatchOptions) => Promise<T>
+  changed: (options?: UntilToMatchOptions) => Promise<T>
+  not: {
+    toBe: (value: T, options?: UntilToMatchOptions) => Promise<T>
+    toBeTruthy: (options?: UntilToMatchOptions) => Promise<T>
+    toBeNull: (options?: UntilToMatchOptions) => Promise<T>
+    toBeUndefined: (options?: UntilToMatchOptions) => Promise<T>
+    toBeNaN: (options?: UntilToMatchOptions) => Promise<T>
+  }
+}

package/dist/until.js

@@ -0,0 +1,62 @@
+import { watch } from "@stacksjs/stx";
+export function until(r) {
+  function toMatch(condition, options = {}) {
+    const { timeout, throwOnTimeout = !1 } = options;
+    if (condition(r.value))
+      return Promise.resolve(r.value);
+    return new Promise((resolve, reject) => {
+      let timer = null;
+      const unwatch = watch(r, (newVal) => {
+        if (condition(newVal)) {
+          unwatch();
+          if (timer !== null)
+            clearTimeout(timer);
+          resolve(newVal);
+        }
+      });
+      if (timeout !== void 0)
+        timer = setTimeout(() => {
+          unwatch();
+          if (throwOnTimeout)
+            reject(Error("Timeout"));
+          else
+            resolve(r.value);
+        }, timeout);
+    });
+  }
+  function toBe(value, options) {
+    return toMatch((v) => v === value, options);
+  }
+  function toBeTruthy(options) {
+    return toMatch((v) => Boolean(v), options);
+  }
+  function toBeNull(options) {
+    return toMatch((v) => v === null, options);
+  }
+  function toBeUndefined(options) {
+    return toMatch((v) => v === void 0, options);
+  }
+  function toBeNaN(options) {
+    return toMatch((v) => Number.isNaN(v), options);
+  }
+  function changed(options) {
+    const initial = r.value;
+    return toMatch((v) => v !== initial, options);
+  }
+  return {
+    toMatch,
+    toBe,
+    toBeTruthy,
+    toBeNull,
+    toBeUndefined,
+    toBeNaN,
+    changed,
+    not: {
+      toBe: (value, options) => toMatch((v) => v !== value, options),
+      toBeTruthy: (options) => toMatch((v) => !v, options),
+      toBeNull: (options) => toMatch((v) => v !== null, options),
+      toBeUndefined: (options) => toMatch((v) => v !== void 0, options),
+      toBeNaN: (options) => toMatch((v) => !Number.isNaN(v), options)
+    }
+  };
+}

package/dist/useActiveElement.d.ts

@@ -0,0 +1,6 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive `document.activeElement`.
+ * Tracks which element currently has focus.
+ */
+export declare function useActiveElement(): Ref<Element | null>;

package/dist/useActiveElement.js

@@ -0,0 +1,19 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function useActiveElement() {
+  const activeElement = ref(null);
+  if (typeof document > "u")
+    return activeElement;
+  activeElement.value = document.activeElement;
+  const handler = () => {
+    activeElement.value = document.activeElement;
+  };
+  document.addEventListener("focusin", handler, { passive: !0 });
+  document.addEventListener("focusout", handler, { passive: !0 });
+  try {
+    onUnmounted(() => {
+      document.removeEventListener("focusin", handler);
+      document.removeEventListener("focusout", handler);
+    });
+  } catch {}
+  return activeElement;
+}

package/dist/useAnimate.d.ts

@@ -0,0 +1,18 @@
+import type { MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive Web Animations API.
+ */
+export declare function useAnimate(target: MaybeRef<HTMLElement | null | undefined>, keyframes: Keyframe[] | PropertyIndexedKeyframes, options?: number | KeyframeAnimationOptions): UseAnimateReturn;
+export declare interface UseAnimateReturn {
+  isSupported: Ref<boolean>
+  animate: Ref<Animation | undefined>
+  play: () => void
+  pause: () => void
+  reverse: () => void
+  finish: () => void
+  cancel: () => void
+  pending: Ref<boolean>
+  playState: Ref<AnimationPlayState>
+  currentTime: Ref<number | null>
+}

package/dist/useAnimate.js

@@ -0,0 +1,48 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { unref } from "./_shared";
+export function useAnimate(target, keyframes, options) {
+  const isSupported = ref(typeof HTMLElement < "u" && "animate" in HTMLElement.prototype), animate = ref(void 0), pending = ref(!1), playState = ref("idle"), currentTime = ref(null);
+  function syncState() {
+    if (animate.value) {
+      pending.value = animate.value.pending;
+      playState.value = animate.value.playState;
+      currentTime.value = animate.value.currentTime;
+    }
+  }
+  function init() {
+    const el = unref(target);
+    if (!el || !isSupported.value)
+      return;
+    animate.value = el.animate(keyframes, options);
+    animate.value.addEventListener("finish", syncState);
+    animate.value.addEventListener("cancel", syncState);
+    syncState();
+  }
+  function play() {
+    animate.value?.play();
+    syncState();
+  }
+  function pause() {
+    animate.value?.pause();
+    syncState();
+  }
+  function reverse() {
+    animate.value?.reverse();
+    syncState();
+  }
+  function finish() {
+    animate.value?.finish();
+    syncState();
+  }
+  function cancel() {
+    animate.value?.cancel();
+    syncState();
+  }
+  init();
+  try {
+    onUnmounted(() => {
+      animate.value?.cancel();
+    });
+  } catch {}
+  return { isSupported, animate, play, pause, reverse, finish, cancel, pending, playState, currentTime };
+}

package/dist/useArrayUtils.d.ts

@@ -0,0 +1,42 @@
+import type { MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive array difference: items in list but not in other.
+ */
+export declare function useArrayDifference<T>(list: MaybeRef<T[]>, other: MaybeRef<T[]>, compareFn?: (a: T, b: T) => boolean): Ref<T[]>;
+/**
+ * Reactive Array.every.
+ */
+export declare function useArrayEvery<T>(list: MaybeRef<T[]>, fn: (element: T, index: number, array: T[]) => boolean): Ref<boolean>;
+/**
+ * Reactive Array.filter.
+ */
+export declare function useArrayFilter<T>(list: MaybeRef<T[]>, fn: (element: T, index: number, array: T[]) => boolean): Ref<T[]>;
+/**
+ * Reactive Array.find.
+ */
+export declare function useArrayFind<T>(list: MaybeRef<T[]>, fn: (element: T, index: number, array: T[]) => boolean): Ref<T | undefined>;
+/**
+ * Reactive Array.findIndex.
+ */
+export declare function useArrayFindIndex<T>(list: MaybeRef<T[]>, fn: (element: T, index: number, array: T[]) => boolean): Ref<number>;
+/**
+ * Reactive Array.includes.
+ */
+export declare function useArrayIncludes<T>(list: MaybeRef<T[]>, value: MaybeRef<T>, compareFn?: (a: T, b: T) => boolean): Ref<boolean>;
+/**
+ * Reactive Array.map.
+ */
+export declare function useArrayMap<T, U>(list: MaybeRef<T[]>, fn: (element: T, index: number, array: T[]) => U): Ref<U[]>;
+/**
+ * Reactive Array.reduce.
+ */
+export declare function useArrayReduce<T, U>(list: MaybeRef<T[]>, fn: (accumulator: U, current: T, index: number, array: T[]) => U, initialValue: U): Ref<U>;
+/**
+ * Reactive Array.some.
+ */
+export declare function useArraySome<T>(list: MaybeRef<T[]>, fn: (element: T, index: number, array: T[]) => boolean): Ref<boolean>;
+/**
+ * Reactive unique array values.
+ */
+export declare function useArrayUnique<T>(list: MaybeRef<T[]>, compareFn?: (a: T, b: T) => boolean): Ref<T[]>;

package/dist/useArrayUtils.js

@@ -0,0 +1,114 @@
+import { computed, ref, watch } from "@stacksjs/stx";
+import { isRef, unref } from "./_shared";
+function watchSource(source, cb) {
+  if (isRef(source))
+    watch(source, cb);
+}
+function getArray(source) {
+  return unref(source);
+}
+export function useArrayDifference(list, other, compareFn) {
+  const result = ref([]);
+  function update() {
+    const arr = getArray(list), otherArr = getArray(other);
+    if (compareFn)
+      result.value = arr.filter((item) => !otherArr.some((o) => compareFn(item, o)));
+    else
+      result.value = arr.filter((item) => !otherArr.includes(item));
+  }
+  update();
+  watchSource(list, update);
+  watchSource(other, update);
+  return result;
+}
+export function useArrayEvery(list, fn) {
+  const result = ref(!1);
+  function update() {
+    result.value = getArray(list).every(fn);
+  }
+  update();
+  watchSource(list, update);
+  return result;
+}
+export function useArrayFilter(list, fn) {
+  const result = ref([]);
+  function update() {
+    result.value = getArray(list).filter(fn);
+  }
+  update();
+  watchSource(list, update);
+  return result;
+}
+export function useArrayFind(list, fn) {
+  const result = ref(void 0);
+  function update() {
+    result.value = getArray(list).find(fn);
+  }
+  update();
+  watchSource(list, update);
+  return result;
+}
+export function useArrayFindIndex(list, fn) {
+  const result = ref(-1);
+  function update() {
+    result.value = getArray(list).findIndex(fn);
+  }
+  update();
+  watchSource(list, update);
+  return result;
+}
+export function useArrayIncludes(list, value, compareFn) {
+  const result = ref(!1);
+  function update() {
+    const arr = getArray(list), v = unref(value);
+    if (compareFn)
+      result.value = arr.some((item) => compareFn(item, v));
+    else
+      result.value = arr.includes(v);
+  }
+  update();
+  watchSource(list, update);
+  if (isRef(value))
+    watch(value, update);
+  return result;
+}
+export function useArrayMap(list, fn) {
+  const result = ref([]);
+  function update() {
+    result.value = getArray(list).map(fn);
+  }
+  update();
+  watchSource(list, update);
+  return result;
+}
+export function useArrayReduce(list, fn, initialValue) {
+  const result = ref(initialValue);
+  function update() {
+    result.value = getArray(list).reduce(fn, initialValue);
+  }
+  update();
+  watchSource(list, update);
+  return result;
+}
+export function useArraySome(list, fn) {
+  const result = ref(!1);
+  function update() {
+    result.value = getArray(list).some(fn);
+  }
+  update();
+  watchSource(list, update);
+  return result;
+}
+export function useArrayUnique(list, compareFn) {
+  const result = ref([]);
+  function update() {
+    const arr = getArray(list);
+    if (compareFn)
+      result.value = arr.filter((item, index) => arr.findIndex((other) => compareFn(item, other)) === index);
+    else
+      result.value = [...new Set(arr)];
+  }
+  update();
+  watchSource(list, update);
+  return result;
+}

package/dist/useAsyncQueue.d.ts

@@ -0,0 +1,18 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Sequential async task queue.
+ * Runs tasks one after another, tracking status and results.
+ *
+ * @param tasks - Array of async task functions to execute sequentially
+ */
+export declare function useAsyncQueue<T>(tasks: UseAsyncQueueTask<T>[]): UseAsyncQueueReturn<T>;
+export declare interface UseAsyncQueueResult<T> {
+  state: 'fulfilled' | 'rejected' | 'pending'
+  data?: T
+}
+export declare interface UseAsyncQueueReturn<T> {
+  activeIndex: Ref<number>
+  result: Ref<UseAsyncQueueResult<T>[]>
+  isFinished: Ref<boolean>
+}
+export type UseAsyncQueueTask<T> = () => Promise<T>;

package/dist/useAsyncQueue.js

@@ -0,0 +1,22 @@
+import { ref } from "@stacksjs/stx";
+export function useAsyncQueue(tasks) {
+  const activeIndex = ref(-1), isFinished = ref(!1), result = ref(tasks.map(() => ({ state: "pending" })));
+  async function runTasks() {
+    for (let i = 0;i < tasks.length; i++) {
+      activeIndex.value = i;
+      const task = tasks[i];
+      if (!task)
+        continue;
+      try {
+        const data = await task();
+        result.value = result.value.map((r, idx) => idx === i ? { state: "fulfilled", data } : r);
+      } catch (e) {
+        result.value = result.value.map((r, idx) => idx === i ? { state: "rejected", data: e } : r);
+      }
+    }
+    activeIndex.value = tasks.length;
+    isFinished.value = !0;
+  }
+  runTasks();
+  return { activeIndex, result, isFinished };
+}

package/dist/useAsyncState.d.ts

@@ -0,0 +1,23 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive async state management.
+ * Wraps an async function or promise with reactive loading/error/ready state.
+ *
+ * @param promise - Async function or promise to execute
+ * @param initialState - Initial state value
+ * @param options - Execution options
+ */
+export declare function useAsyncState<T>(promise: (() => Promise<T>) | Promise<T>, initialState: T, options?: UseAsyncStateOptions<T>): UseAsyncStateReturn<T>;
+export declare interface UseAsyncStateOptions<T> {
+  immediate?: boolean
+  onError?: (e: unknown) => void
+  resetOnExecute?: boolean
+  delay?: number
+}
+export declare interface UseAsyncStateReturn<T> {
+  state: Ref<T>
+  isReady: Ref<boolean>
+  isLoading: Ref<boolean>
+  error: Ref<unknown>
+  execute: (delay?: number) => Promise<T>
+}

package/dist/useAsyncState.js

@@ -0,0 +1,35 @@
+import { ref } from "@stacksjs/stx";
+export function useAsyncState(promise, initialState, options = {}) {
+  const {
+    immediate = !0,
+    onError,
+    resetOnExecute = !0,
+    delay = 0
+  } = options, state = ref(initialState), isReady = ref(!1), isLoading = ref(!1), error = ref(void 0);
+  async function execute(executeDelay) {
+    const delayMs = executeDelay ?? delay;
+    if (resetOnExecute)
+      state.value = initialState;
+    error.value = void 0;
+    isReady.value = !1;
+    isLoading.value = !0;
+    if (delayMs > 0)
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    try {
+      const result = typeof promise === "function" ? await promise() : await promise;
+      state.value = result;
+      isReady.value = !0;
+      return result;
+    } catch (e) {
+      error.value = e;
+      if (onError)
+        onError(e);
+      return state.value;
+    } finally {
+      isLoading.value = !1;
+    }
+  }
+  if (immediate)
+    execute();
+  return { state, isReady, isLoading, error, execute };
+}

package/dist/useBase64.d.ts

@@ -0,0 +1,12 @@
+import type { MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive Base64 encoding.
+ *
+ * @param source - The value to encode (string, Blob, ArrayBuffer, or canvas)
+ */
+export declare function useBase64(source: MaybeRef<string | Blob | ArrayBuffer | HTMLCanvasElement>): UseBase64Return;
+export declare interface UseBase64Return {
+  base64: Ref<string>
+  execute: () => Promise<string>
+}

package/dist/useBase64.js

@@ -0,0 +1,45 @@
+import { ref, watch } from "@stacksjs/stx";
+import { isRef, unref } from "./_shared";
+export function useBase64(source) {
+  const base64 = ref("");
+  async function encode(input) {
+    if (typeof input === "string") {
+      if (typeof btoa < "u")
+        return btoa(input);
+      return Buffer.from(input).toString("base64");
+    }
+    if (input instanceof ArrayBuffer) {
+      const bytes = new Uint8Array(input);
+      let binary = "";
+      for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+      if (typeof btoa < "u")
+        return btoa(binary);
+      return Buffer.from(input).toString("base64");
+    }
+    if (typeof Blob < "u" && input instanceof Blob)
+      return new Promise((resolve, reject) => {
+        const reader = new FileReader;
+        reader.onload = () => {
+          const result = reader.result, base64Part = result.split(",")[1] ?? result;
+          resolve(base64Part);
+        };
+        reader.onerror = reject;
+        reader.readAsDataURL(input);
+      });
+    if (typeof HTMLCanvasElement < "u" && input instanceof HTMLCanvasElement)
+      return input.toDataURL().split(",")[1] ?? "";
+    return "";
+  }
+  async function execute() {
+    const val = unref(source), result = await encode(val);
+    base64.value = result;
+    return result;
+  }
+  execute().catch(() => {});
+  if (isRef(source))
+    watch(source, () => {
+      execute().catch(() => {});
+    });
+  return { base64, execute };
+}

package/dist/useBattery.d.ts

@@ -0,0 +1,15 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive battery status.
+ * Tracks battery charging state, charge/discharge times, and level using the Battery Status API.
+ *
+ * @returns Reactive battery properties and support status
+ */
+export declare function useBattery(): UseBatteryReturn;
+export declare interface UseBatteryReturn {
+  charging: Ref<boolean>
+  chargingTime: Ref<number>
+  dischargingTime: Ref<number>
+  level: Ref<number>
+  isSupported: Ref<boolean>
+}

package/dist/useBattery.js

@@ -0,0 +1,38 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { noop } from "./_shared";
+export function useBattery() {
+  const nav = typeof navigator < "u" ? navigator : void 0, isSupported = ref(!!nav?.getBattery), charging = ref(!1), chargingTime = ref(0), dischargingTime = ref(0), level = ref(1), cleanups = [];
+  let cleanup = noop;
+  if (isSupported.value && nav?.getBattery)
+    nav.getBattery().then((battery) => {
+      const updateBatteryInfo = () => {
+        charging.value = battery.charging;
+        chargingTime.value = battery.chargingTime;
+        dischargingTime.value = battery.dischargingTime;
+        level.value = battery.level;
+      };
+      updateBatteryInfo();
+      battery.addEventListener("chargingchange", updateBatteryInfo);
+      battery.addEventListener("chargingtimechange", updateBatteryInfo);
+      battery.addEventListener("dischargingtimechange", updateBatteryInfo);
+      battery.addEventListener("levelchange", updateBatteryInfo);
+      cleanups.push(() => {
+        battery.removeEventListener("chargingchange", updateBatteryInfo);
+        battery.removeEventListener("chargingtimechange", updateBatteryInfo);
+        battery.removeEventListener("dischargingtimechange", updateBatteryInfo);
+        battery.removeEventListener("levelchange", updateBatteryInfo);
+      });
+      cleanup = () => {
+        for (const fn of cleanups)
+          fn();
+        cleanups.length = 0;
+        cleanup = noop;
+      };
+    }).catch(() => {
+      isSupported.value = !1;
+    });
+  try {
+    onUnmounted(() => cleanup());
+  } catch {}
+  return { charging, chargingTime, dischargingTime, level, isSupported };
+}

package/dist/useBreakpoints.d.ts

@@ -0,0 +1,96 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive responsive breakpoints.
+ * Observe viewport width changes and query breakpoint states.
+ */
+export declare function useBreakpoints<K extends string>(breakpoints: Breakpoints<K>): UseBreakpointsReturn<K>;
+/**
+ * Tailwind CSS default breakpoints.
+ */
+export declare const breakpointsTailwind: {
+  sm: 640;
+  md: 768;
+  lg: 1024;
+  xl: 1280;
+  '2xl': 1536
+};
+/**
+ * Bootstrap default breakpoints.
+ */
+export declare const breakpointsBootstrap: {
+  sm: 576;
+  md: 768;
+  lg: 992;
+  xl: 1200;
+  xxl: 1400
+};
+/** Alias for breakpointsBootstrap */
+export declare const breakpointsBootstrapV5: unknown;
+/**
+ * Ant Design breakpoints.
+ */
+export declare const breakpointsAntDesign: {
+  xs: 480;
+  sm: 576;
+  md: 768;
+  lg: 992;
+  xl: 1200;
+  xxl: 1600
+};
+/**
+ * Vuetify breakpoints.
+ */
+export declare const breakpointsVuetify: {
+  xs: 600;
+  sm: 960;
+  md: 1264;
+  lg: 1904
+};
+/**
+ * Quasar breakpoints.
+ */
+export declare const breakpointsQuasar: {
+  xs: 600;
+  sm: 1024;
+  md: 1440;
+  lg: 1920
+};
+/**
+ * Master CSS breakpoints.
+ */
+export declare const breakpointsMasterCss: {
+  '3xs': 360;
+  '2xs': 480;
+  'xs': 600;
+  'sm': 768;
+  'md': 1024;
+  'lg': 1280;
+  'xl': 1440;
+  '2xl': 1600;
+  '3xl': 1920;
+  '4xl': 2560
+};
+/**
+ * Semantic UI breakpoints.
+ */
+export declare const breakpointsSematic: {
+  mobileS: 320;
+  mobileM: 375;
+  mobileL: 425;
+  tablet: 768;
+  laptop: 1024;
+  laptopL: 1440;
+  desktop: 2560
+};
+export declare interface UseBreakpointsReturn<K extends string> {
+  greaterOrEqual: (k: K) => Ref<boolean>
+  smallerOrEqual: (k: K) => Ref<boolean>
+  between: (a: K, b: K) => Ref<boolean>
+  isGreater: (k: K) => Ref<boolean>
+  isSmaller: (k: K) => Ref<boolean>
+  current: () => Ref<K[]>
+}
+/**
+ * Breakpoints map type: key names to pixel widths.
+ */
+export type Breakpoints<K extends string = string> = Record<K, number>;