@stacksjs/composables 0.70.88 → 0.70.90

package/dist/_shared.d.ts

@@ -0,0 +1,49 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Unwrap a MaybeRef to its raw value.
+ */
+export declare function unref<T>(val: MaybeRef<T>): T;
+/**
+ * Unwrap a MaybeRefOrGetter to its raw value.
+ */
+export declare function toValue<T>(val: MaybeRefOrGetter<T>): T;
+/**
+ * Check if a value is a Ref.
+ */
+export declare function isRef<T>(val: MaybeRef<T>): val is Ref<T>;
+/**
+ * No-op function for default callbacks.
+ */
+export declare function noop(): void;
+/**
+ * Get the default window, SSR-safe.
+ */
+export declare function defaultWindow(): Window | undefined;
+/**
+ * Get the default document, SSR-safe.
+ */
+export declare function defaultDocument(): Document | undefined;
+/**
+ * Get the default navigator, SSR-safe.
+ */
+export declare function defaultNavigator(): Navigator | undefined;
+/**
+ * Type helper for configurable window.
+ */
+export declare interface ConfigurableWindow {
+  window?: Window
+}
+/**
+ * Type helper for configurable document.
+ */
+export declare interface ConfigurableDocument {
+  document?: Document
+}
+/**
+ * A value that may be a raw value or a Ref.
+ */
+export type MaybeRef<T> = T | Ref<T>;
+/**
+ * A value that may be a raw value, a Ref, or a getter function.
+ */
+export type MaybeRefOrGetter<T> = T | Ref<T> | (() => T);

package/dist/_shared.js

@@ -0,0 +1,23 @@
+export function unref(val) {
+  if (val && typeof val === "object" && "value" in val && "subscribe" in val)
+    return val.value;
+  return val;
+}
+export function toValue(val) {
+  if (typeof val === "function")
+    return val();
+  return unref(val);
+}
+export function isRef(val) {
+  return val !== null && typeof val === "object" && "value" in val && "subscribe" in val;
+}
+export function noop() {}
+export function defaultWindow() {
+  return typeof window < "u" ? window : void 0;
+}
+export function defaultDocument() {
+  return typeof document < "u" ? document : void 0;
+}
+export function defaultNavigator() {
+  return typeof navigator < "u" ? navigator : void 0;
+}

package/dist/cloneFnJSON.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Clone a value using JSON serialization.
+ * Works for JSON-serializable values (no functions, symbols, etc).
+ */
+export declare function cloneFnJSON<T>(value: T): T;

package/dist/cloneFnJSON.js

@@ -0,0 +1,3 @@
+export function cloneFnJSON(value) {
+  return JSON.parse(JSON.stringify(value));
+}

package/dist/computedAsync.d.ts

@@ -0,0 +1,28 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Create an async computed ref.
+ *
+ * Returns a ref whose value is the result of an asynchronous evaluation function.
+ * Since stx does not auto-track dependencies like Vue's watchEffect, you can
+ * provide an optional array of dependency refs. When any dependency changes,
+ * the evaluation callback is re-run.
+ *
+ * @param evaluationCallback - An async function that returns the computed value
+ * @param initialState - The initial value before the first evaluation completes
+ * @param deps - Optional array of reactive refs to watch for re-evaluation
+ * @returns A ref containing the async computed value
+ *
+ * @example
+ * ```ts
+ * const userId = ref(1)
+ * const user = computedAsync(
+ *   async () => {
+ *     const response = await fetch(`/api/users/${userId.value}`)
+ *     return response.json()
+ *   },
+ *   null,
+ *   [userId],
+ * )
+ * ```
+ */
+export declare function computedAsync<T>(evaluationCallback: () => Promise<T>, initialState: T, deps?: Ref<any>[]): Ref<T>;

package/dist/computedAsync.js

@@ -0,0 +1,20 @@
+import { ref, watch } from "@stacksjs/stx";
+export function computedAsync(evaluationCallback, initialState, deps) {
+  const result = ref(initialState);
+  let currentEvalId = 0;
+  async function evaluate() {
+    const evalId = ++currentEvalId;
+    try {
+      const value = await evaluationCallback();
+      if (evalId === currentEvalId)
+        result.value = value;
+    } catch {}
+  }
+  evaluate();
+  if (deps && deps.length > 0)
+    for (const dep of deps)
+      watch(dep, () => {
+        evaluate();
+      });
+  return result;
+}

package/dist/computedEager.d.ts

@@ -0,0 +1,27 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Create an eagerly evaluated computed ref.
+ *
+ * Unlike the standard lazy `computed()`, this evaluates the function immediately
+ * whenever any watched dependency changes, rather than deferring evaluation
+ * until `.value` is accessed. This is useful when you want to precompute values
+ * eagerly.
+ *
+ * Since stx does not auto-track dependencies in the same way as Vue's computed,
+ * this accepts an optional array of dependency refs to watch. When any dependency
+ * changes, the function is re-evaluated immediately.
+ *
+ * @param fn - A synchronous function that returns the computed value
+ * @param deps - Optional array of reactive refs to watch for re-evaluation
+ * @returns A ref containing the eagerly computed value
+ *
+ * @example
+ * ```ts
+ * const list = ref([1, 2, 3, 4, 5])
+ * const sum = computedEager(() => list.value.reduce((a, b) => a + b, 0), [list])
+ * console.log(sum.value) // 15
+ * list.value = [10, 20]
+ * console.log(sum.value) // 30
+ * ```
+ */
+export declare function computedEager<T>(fn: () => T, deps?: Ref<any>[]): Ref<T>;

package/dist/computedEager.js

@@ -0,0 +1,10 @@
+import { ref, watch } from "@stacksjs/stx";
+export function computedEager(fn, deps) {
+  const result = ref(fn());
+  if (deps && deps.length > 0)
+    for (const dep of deps)
+      watch(dep, () => {
+        result.value = fn();
+      });
+  return result;
+}

package/dist/createEventHook.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Create a typed event hook that can be triggered and subscribed to.
+ *
+ * @example
+ * ```ts
+ * const onFetch = createEventHook<Response>()
+ * onFetch.on((response) => console.log(response))
+ * onFetch.trigger(new Response())
+ * ```
+ */
+export declare function createEventHook<T = any>(): EventHookOn<T>;
+export declare interface EventHookOn<T = any> {
+  on: (fn: (param: T) => void) => { off: () => void }
+  off: (fn: (param: T) => void) => void
+  trigger: (param: T) => void
+}

package/dist/createEventHook.js

@@ -0,0 +1,15 @@
+export function createEventHook() {
+  const fns = new Set;
+  function on(fn) {
+    fns.add(fn);
+    return { off: () => fns.delete(fn) };
+  }
+  function off(fn) {
+    fns.delete(fn);
+  }
+  function trigger(param) {
+    for (const fn of fns)
+      fn(param);
+  }
+  return { on, off, trigger };
+}

package/dist/createFetch.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Create a pre-configured useFetch instance with a base URL and default options.
+ *
+ * @example
+ * ```ts
+ * const useMyFetch = createFetch({ baseUrl: '/api' })
+ * const { data, error } = await useMyFetch('/users').get().json()
+ * ```
+ */
+export declare function createFetch(config?: CreateFetchOptions): void;
+export declare interface CreateFetchOptions {
+  baseUrl?: string
+  options?: RequestInit
+}

package/dist/createFetch.js

@@ -0,0 +1,8 @@
+import { useFetch } from "./useFetch";
+export function createFetch(config = {}) {
+  const { baseUrl = "" } = config;
+  return function(url) {
+    const fullUrl = baseUrl ? `${baseUrl.replace(/\/$/, "")}/${url.replace(/^\//, "")}` : url;
+    return useFetch(fullUrl);
+  };
+}

package/dist/createGlobalState.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Keep state in the global scope to be reusable across components.
+ *
+ * @param stateFactory - A function that creates the state
+ * @returns A function that returns the shared state
+ *
+ * @example
+ * ```ts
+ * const useGlobalCount = createGlobalState(() => {
+ *   const count = ref(0)
+ *   return { count }
+ * })
+ * // In any component:
+ * const { count } = useGlobalCount()
+ * ```
+ */
+export declare function createGlobalState<T>(stateFactory: () => T): () => T;

package/dist/createGlobalState.js

@@ -0,0 +1,10 @@
+export function createGlobalState(stateFactory) {
+  let initialized = !1, state;
+  return () => {
+    if (!initialized) {
+      state = stateFactory();
+      initialized = !0;
+    }
+    return state;
+  };
+}

package/dist/createSharedComposable.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Make a composable function usable with multiple consumers.
+ * The composable is only invoked once, and the result is shared.
+ *
+ * @param composable - The composable function to share
+ * @returns A shared version of the composable
+ */
+export declare function createSharedComposable<Fn extends (...args: any[]) => any>(composable: Fn): Fn;

package/dist/createSharedComposable.js

@@ -0,0 +1,9 @@
+export function createSharedComposable(composable) {
+  let subscribers = 0, state;
+  return (...args) => {
+    subscribers++;
+    if (!state)
+      state = composable(...args);
+    return state;
+  };
+}

package/dist/extendRef.d.ts

@@ -0,0 +1,9 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Extend a ref with additional properties.
+ *
+ * @param ref - The ref to extend
+ * @param extend - The properties to add
+ * @returns The extended ref
+ */
+export declare function extendRef<T, E extends Record<string, any>>(r: Ref<T>, extend: E): Ref<T> & E;

package/dist/extendRef.js

@@ -0,0 +1,6 @@
+export function extendRef(r, extend) {
+  for (const [key, value] of Object.entries(extend))
+    if (key !== "value")
+      r[key] = value;
+  return r;
+}

package/dist/formatTimeAgo.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Format a date to a human-readable time-ago string.
+ *
+ * @param date - The date to format
+ * @param options - Formatting options
+ */
+export declare function formatTimeAgo(date: Date | number | string, options?: FormatTimeAgoOptions): string;
+export declare interface FormatTimeAgoOptions {
+  max?: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year'
+  fullDateFormatter?: (date: Date) => string
+  messages?: Partial<{
+    justNow: string
+    past: (n: string) => string
+    future: (n: string) => string
+    second: (n: number) => string
+    minute: (n: number) => string
+    hour: (n: number) => string
+    day: (n: number) => string
+    week: (n: number) => string
+    month: (n: number) => string
+    year: (n: number) => string
+  }>
+}

package/dist/formatTimeAgo.js

@@ -0,0 +1,33 @@
+const defaultMessages = {
+  justNow: "just now",
+  past: (n) => `${n} ago`,
+  future: (n) => `in ${n}`,
+  second: (n) => `${n} second${n > 1 ? "s" : ""}`,
+  minute: (n) => `${n} minute${n > 1 ? "s" : ""}`,
+  hour: (n) => `${n} hour${n > 1 ? "s" : ""}`,
+  day: (n) => `${n} day${n > 1 ? "s" : ""}`,
+  week: (n) => `${n} week${n > 1 ? "s" : ""}`,
+  month: (n) => `${n} month${n > 1 ? "s" : ""}`,
+  year: (n) => `${n} year${n > 1 ? "s" : ""}`
+};
+export function formatTimeAgo(date, options = {}) {
+  const messages = { ...defaultMessages, ...options.messages }, d = date instanceof Date ? date : new Date(date), diff = Date.now() - d.getTime(), absDiff = Math.abs(diff), seconds = Math.floor(absDiff / 1000), minutes = Math.floor(seconds / 60), hours = Math.floor(minutes / 60), days = Math.floor(hours / 24), weeks = Math.floor(days / 7), months = Math.floor(days / 30), years = Math.floor(days / 365), isFuture = diff < 0;
+  function format(value) {
+    return isFuture ? messages.future(value) : messages.past(value);
+  }
+  if (seconds < 5)
+    return messages.justNow;
+  if (seconds < 60)
+    return format(messages.second(seconds));
+  if (minutes < 60)
+    return format(messages.minute(minutes));
+  if (hours < 24)
+    return format(messages.hour(hours));
+  if (days < 7)
+    return format(messages.day(days));
+  if (weeks < 4)
+    return format(messages.week(weeks));
+  if (months < 12)
+    return format(messages.month(months));
+  return format(messages.year(years));
+}

package/dist/index.d.ts

@@ -0,0 +1,271 @@
+export type { ConfigurableDocument, ConfigurableWindow, MaybeRef, MaybeRefOrGetter } from './_shared';
+export type {
+  QueryClient,
+  QueryKey,
+  UseMutationOptions,
+  UseMutationResult,
+  UseQueryOptions,
+  UseQueryResult,
+} from './useQuery';
+export type {
+  FormFieldAccessor,
+  FormValidator,
+  UseFormOptions,
+  UseFormResult,
+  ValidationMode,
+} from './useForm';
+// Shared utilities & types
+export { defaultDocument, defaultNavigator, defaultWindow, isRef, noop, toValue, unref } from './_shared';
+export { getSSRHandler, setSSRHandler, customStorageEventName } from './ssrHandlers';
+// Storage
+export { useStorage } from './useStorage';
+export { useLocalStorage } from './useLocalStorage';
+export { useSessionStorage } from './useSessionStorage';
+// Color mode / Dark mode
+export { useDark, usePreferredDark } from './useDark';
+export { useColorMode } from './useColorMode';
+export { usePreferredColorScheme } from './usePreferredColorScheme';
+export { usePreferredContrast } from './usePreferredContrast';
+export { usePreferredReducedMotion } from './usePreferredReducedMotion';
+// Online / Network
+export { useOnline } from './useOnline';
+export { useNetwork } from './useNetwork';
+// Toggle
+export { useToggle } from './useToggle';
+// Fetch
+export { useFetch } from './useFetch';
+export { createFetch } from './createFetch';
+// Query / Mutation (stacksjs/stacks#1939)
+export { createQueryClient, queryClient, useMutation, useQuery } from './useQuery';
+// Form primitive (stacksjs/stacks#1940)
+export { useForm } from './useForm';
+// Date / Time
+export { useDateFormat } from './useDateFormat';
+export { useNow } from './useNow';
+export { useTimestamp } from './useTimestamp';
+export { useTimeAgo } from './useTimeAgo';
+// Event listeners
+export { useEventListener } from './useEventListener';
+export { useEventBus } from './useEventBus';
+export { createEventHook } from './createEventHook';
+// Debounce / Throttle
+export { useDebounceFn } from './useDebounceFn';
+export { useThrottleFn } from './useThrottleFn';
+export { useDebouncedRef } from './useDebouncedRef';
+export { useThrottledRef } from './useThrottledRef';
+export { useDebounce } from './useDebounce';
+export { useThrottle } from './useThrottle';
+// Timing
+export { useInterval } from './useInterval';
+export { useIntervalFn } from './useIntervalFn';
+export { useTimeout } from './useTimeout';
+export { useTimeoutFn } from './useTimeoutFn';
+export { useTimeoutPoll } from './useTimeoutPoll';
+export { useRafFn } from './useRafFn';
+export { useFps } from './useFps';
+// Clipboard
+export { useClipboard } from './useClipboard';
+export { useClipboardItems } from './useClipboardItems';
+// Media / Responsive
+export { useMediaQuery } from './useMediaQuery';
+export {
+  breakpointsAntDesign,
+  breakpointsBootstrap,
+  breakpointsBootstrapV5,
+  breakpointsMasterCss,
+  breakpointsQuasar,
+  breakpointsSematic,
+  breakpointsTailwind,
+  breakpointsVuetify,
+  useBreakpoints,
+} from './useBreakpoints';
+// Document / Page
+export { useTitle } from './useTitle';
+export { useFavicon } from './useFavicon';
+export { useDocumentVisibility } from './useDocumentVisibility';
+export { useTextDirection } from './useTextDirection';
+export { useTextSelection } from './useTextSelection';
+// URL / Location
+export { useUrlSearchParams } from './useUrlSearchParams';
+export { useBrowserLocation } from './useBrowserLocation';
+// Window
+export { useWindowSize } from './useWindowSize';
+export { useWindowFocus } from './useWindowFocus';
+export { useWindowScroll } from './useWindowScroll';
+// Scroll
+export { useScroll } from './useScroll';
+export { useScrollLock } from './useScrollLock';
+export { useInfiniteScroll } from './useInfiniteScroll';
+// Fullscreen
+export { useFullscreen } from './useFullscreen';
+// Click / Keyboard / Interaction
+export { onClickOutside } from './onClickOutside';
+export { onKeyStroke, onKeyDown, onKeyUp } from './onKeyStroke';
+export { onLongPress } from './onLongPress';
+export { onStartTyping } from './onStartTyping';
+export { useKeyModifier } from './useKeyModifier';
+export { useMagicKeys } from './useMagicKeys';
+// Math / Logic
+export {
+  and,
+  logicNot,
+  logicOr,
+  or,
+  useAbs,
+  useAverage,
+  useCeil,
+  useClamp,
+  useFloor,
+  useMax,
+  useMin,
+  usePrecision,
+  useRound,
+  useSum,
+  useTrunc,
+} from './useMath';
+// State / Counter / History
+export { useCounter } from './useCounter';
+export { usePrevious } from './usePrevious';
+export { useLastChanged } from './useLastChanged';
+export { useStepper } from './useStepper';
+export { useCycleList } from './useCycleList';
+export { useSorted } from './useSorted';
+export { useCloned } from './useCloned';
+export { useManualRefHistory } from './useManualRefHistory';
+export { useRefHistory } from './useRefHistory';
+export { useDebouncedRefHistory } from './useDebouncedRefHistory';
+export { useThrottledRefHistory } from './useThrottledRefHistory';
+// Async
+export { useAsyncState } from './useAsyncState';
+export { useAsyncQueue } from './useAsyncQueue';
+// Watchers
+export { whenever } from './whenever';
+export { watchOnce } from './watchOnce';
+export { watchDebounced } from './watchDebounced';
+export { watchThrottled } from './watchThrottled';
+export { watchPausable, pausableWatch } from './watchPausable';
+export { watchIgnorable, ignorableWatch } from './watchIgnorable';
+export { watchArray } from './watchArray';
+export { watchAtMost } from './watchAtMost';
+export { watchDeep } from './watchDeep';
+export { watchImmediate } from './watchImmediate';
+export { watchTriggerable } from './watchTriggerable';
+export { watchWithFilter } from './watchWithFilter';
+// WebSocket / EventSource
+export { useWebSocket } from './useWebSocket';
+export { useEventSource } from './useEventSource';
+export { useBroadcastChannel } from './useBroadcastChannel';
+// Computed
+export { computedAsync } from './computedAsync';
+export { computedEager } from './computedEager';
+// Observers
+export { useIntersectionObserver } from './useIntersectionObserver';
+export { useResizeObserver } from './useResizeObserver';
+export { useMutationObserver } from './useMutationObserver';
+// Element
+export { useElementSize } from './useElementSize';
+export { useElementBounding } from './useElementBounding';
+export { useElementVisibility } from './useElementVisibility';
+export { useElementHover } from './useElementHover';
+export { useElementByPoint } from './useElementByPoint';
+export { useCssVar } from './useCssVar';
+export { unrefElement } from './unrefElement';
+// Mouse / Pointer
+export { useMouse } from './useMouse';
+export { useMouseInElement } from './useMouseInElement';
+export { useMousePressed } from './useMousePressed';
+export { usePointer } from './usePointer';
+export { useSwipe } from './useSwipe';
+export { usePointerSwipe } from './usePointerSwipe';
+export { usePointerLock } from './usePointerLock';
+export { useParallax } from './useParallax';
+// Sensors / Device
+export { useGeolocation } from './useGeolocation';
+export { useDeviceMotion } from './useDeviceMotion';
+export { useDeviceOrientation } from './useDeviceOrientation';
+export { useDevicePixelRatio } from './useDevicePixelRatio';
+export { useBattery } from './useBattery';
+// Focus
+export { useFocus } from './useFocus';
+export { useFocusWithin } from './useFocusWithin';
+export { useActiveElement } from './useActiveElement';
+// Idle / Page
+export { useIdle } from './useIdle';
+export { usePageLeave } from './usePageLeave';
+export { useMounted } from './useMounted';
+// Drag / Drop
+export { useDraggable } from './useDraggable';
+export { useDropZone } from './useDropZone';
+// Navigation
+export { useNavigatorLanguage } from './useNavigatorLanguage';
+export { usePreferredLanguages } from './usePreferredLanguages';
+export { useScreenOrientation } from './useScreenOrientation';
+export { useScreenSafeArea } from './useScreenSafeArea';
+export { useParentElement } from './useParentElement';
+// Permissions / Share
+export { usePermission } from './usePermission';
+export { useShare } from './useShare';
+// Object / Blob
+export { useObjectUrl } from './useObjectUrl';
+export { useImage } from './useImage';
+export { useBase64 } from './useBase64';
+// Animate / Transition
+export { useAnimate } from './useAnimate';
+export { useTransition, executeTransition, TransitionPresets } from './useTransition';
+// Script / Style
+export { useScriptTag } from './useScriptTag';
+export { useStyleTag } from './useStyleTag';
+// Dialogs / Files
+export { useConfirmDialog } from './useConfirmDialog';
+export { useFileDialog } from './useFileDialog';
+export { useEyeDropper } from './useEyeDropper';
+export { useTextareaAutosize } from './useTextareaAutosize';
+// Notifications / Vibration / Wake
+export { useWebNotification } from './useWebNotification';
+export { useVibrate } from './useVibrate';
+export { useWakeLock } from './useWakeLock';
+// Workers
+export { useWebWorker, useWebWorkerFn } from './useWebWorker';
+// Virtual list / Pagination
+export { useVirtualList } from './useVirtualList';
+export { useOffsetPagination } from './useOffsetPagination';
+// Utility composables
+export { isDefined } from './isDefined';
+export { useSupported } from './useSupported';
+export { useToNumber } from './useToNumber';
+export { useToString } from './useToString';
+export { refDefault } from './refDefault';
+export { refAutoReset, autoResetRef } from './refAutoReset';
+export { cloneFnJSON } from './cloneFnJSON';
+export { formatTimeAgo } from './formatTimeAgo';
+export { until } from './until';
+export { resolveRef } from './resolveRef';
+export { extendRef } from './extendRef';
+export { useMemoize } from './useMemoize';
+export { makeDestructurable } from './makeDestructurable';
+export { syncRef, syncRefs } from './syncRef';
+export { createGlobalState } from './createGlobalState';
+export { createSharedComposable } from './createSharedComposable';
+export { tryOnMounted, tryOnBeforeMount, tryOnUnmounted, tryOnBeforeUnmount, tryOnScopeDispose } from './tryOnMounted';
+// Array utilities
+export {
+  useArrayDifference,
+  useArrayEvery,
+  useArrayFilter,
+  useArrayFind,
+  useArrayFindIndex,
+  useArrayIncludes,
+  useArrayMap,
+  useArrayReduce,
+  useArraySome,
+  useArrayUnique,
+} from './useArrayUtils';
+// Aliases (matching VueUse naming)
+export { computedAsync as asyncComputed } from './computedAsync';
+export { computedEager as eagerComputed } from './computedEager';
+export { useDebouncedRef as debouncedRef } from './useDebouncedRef';
+export { useDebouncedRef as refDebounced } from './useDebouncedRef';
+export { useThrottledRef as throttledRef } from './useThrottledRef';
+export { useThrottledRef as refThrottled } from './useThrottledRef';
+export { watchDebounced as debouncedWatch } from './watchDebounced';
+export { watchThrottled as throttledWatch } from './watchThrottled';