@stacksjs/composables 0.70.87 → 0.70.90

package/dist/usePreferredContrast.js

@@ -0,0 +1,29 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function usePreferredContrast() {
+  const contrast = ref("no-preference");
+  if (typeof window > "u" || !window.matchMedia)
+    return contrast;
+  const more = window.matchMedia("(prefers-contrast: more)"), less = window.matchMedia("(prefers-contrast: less)"), custom = window.matchMedia("(prefers-contrast: custom)");
+  function update() {
+    if (more.matches)
+      contrast.value = "more";
+    else if (less.matches)
+      contrast.value = "less";
+    else if (custom.matches)
+      contrast.value = "custom";
+    else
+      contrast.value = "no-preference";
+  }
+  update();
+  more.addEventListener("change", update);
+  less.addEventListener("change", update);
+  custom.addEventListener("change", update);
+  try {
+    onUnmounted(() => {
+      more.removeEventListener("change", update);
+      less.removeEventListener("change", update);
+      custom.removeEventListener("change", update);
+    });
+  } catch {}
+  return contrast;
+}

package/dist/usePreferredLanguages.d.ts

@@ -0,0 +1,5 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive `navigator.languages`. Returns the user's preferred languages.
+ */
+export declare function usePreferredLanguages(): Ref<readonly string[]>;

package/dist/usePreferredLanguages.js

@@ -0,0 +1,16 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function usePreferredLanguages() {
+  const languages = ref(typeof navigator < "u" ? navigator.languages : []);
+  if (typeof window > "u")
+    return languages;
+  const handler = () => {
+    languages.value = navigator.languages;
+  };
+  window.addEventListener("languagechange", handler, { passive: !0 });
+  try {
+    onUnmounted(() => {
+      window.removeEventListener("languagechange", handler);
+    });
+  } catch {}
+  return languages;
+}

package/dist/usePreferredReducedMotion.d.ts

@@ -0,0 +1,6 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive preferred reduced motion.
+ */
+export declare function usePreferredReducedMotion(): Ref<ReducedMotionType>;
+export type ReducedMotionType = 'reduce' | 'no-preference';

package/dist/usePreferredReducedMotion.js

@@ -0,0 +1,18 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function usePreferredReducedMotion() {
+  const motion = ref("no-preference");
+  if (typeof window > "u" || !window.matchMedia)
+    return motion;
+  const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
+  function update() {
+    motion.value = mq.matches ? "reduce" : "no-preference";
+  }
+  update();
+  mq.addEventListener("change", update);
+  try {
+    onUnmounted(() => {
+      mq.removeEventListener("change", update);
+    });
+  } catch {}
+  return motion;
+}

package/dist/usePrevious.d.ts

@@ -0,0 +1,9 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Track the previous value of a ref.
+ * Returns a ref containing the value before the last change.
+ *
+ * @param value - The source ref to track
+ * @param initialValue - Optional initial value for the previous ref
+ */
+export declare function usePrevious<T>(value: Ref<T>, initialValue?: T): Ref<T | undefined>;

package/dist/usePrevious.js

@@ -0,0 +1,8 @@
+import { ref, watch } from "@stacksjs/stx";
+export function usePrevious(value, initialValue) {
+  const previous = ref(initialValue);
+  watch(value, (_newVal, oldVal) => {
+    previous.value = oldVal;
+  });
+  return previous;
+}

package/dist/useQuery.d.ts

@@ -0,0 +1,106 @@
+import type { Ref } from '@stacksjs/stx';
+export declare function createQueryClient(options?: CreateQueryClientOptions): QueryClient;
+/**
+ * Reactive query with cache + dedup + stale-while-revalidate.
+ *
+ * @example
+ * ```ts
+ * const judges = useQuery({
+ *   queryKey: ['judges', { practiceArea: filter() }],
+ *   queryFn: async ({ signal }) => {
+ *     const res = await fetch('/api/judges', { signal })
+ *     return res.json() as Promise<Judge[]>
+ *   },
+ *   staleTime: 30_000,
+ * })
+ * ```
+ */
+export declare function useQuery<T>(opts: UseQueryOptions<T>): UseQueryResult<T>;
+/**
+ * Reactive write-side primitive. Pairs with `useQuery` via
+ * `queryClient.invalidate(...)` inside `onSettled` for the canonical
+ * optimistic-with-rollback pattern.
+ */
+export declare function useMutation<TData, TVars = void, TCtx = unknown>(opts: UseMutationOptions<TData, TVars, TCtx>): UseMutationResult<TData, TVars>;
+/** Default app-wide client. Tests should pass their own via `client:`. */
+export declare const queryClient: QueryClient;
+declare interface CacheEntry<T = unknown> {
+  key: QueryKey
+  hash: string
+  data: T | undefined
+  error: Error | null
+  updatedAt: number
+  status: 'idle' | 'fetching' | 'success' | 'error'
+  inflight: Promise<T> | null
+  invalidated: boolean
+  subscribers: Set<() => unknown>
+}
+export declare interface CreateQueryClientOptions {
+  gcTime?: number
+}
+/**
+ * Central cache. Hold one per app (the default `queryClient` export)
+ * or create scoped ones for tests.
+ */
+export declare interface QueryClient {
+  get: <T = unknown>(key: QueryKey) => T | undefined
+  set: <T = unknown>(key: QueryKey, value: T | ((old: T | undefined) => T)) => void
+  invalidate: (matcher: QueryMatcher) => Promise<void>
+  clear: () => void
+  gc: () => number
+  _subscribe: (hash: string, fn: () => unknown) => () => void
+  _entry: <T = unknown>(key: QueryKey) => CacheEntry<T>
+  _notify: (hash: string) => void
+}
+export declare interface UseQueryOptions<T> {
+  queryKey: QueryKey
+  queryFn: (ctx: { signal: AbortSignal }) => Promise<T>
+  staleTime?: number
+  enabled?: boolean
+  refetchOnFocus?: boolean
+  refetchOnReconnect?: boolean
+  window?: EventTarget
+  client?: QueryClient
+}
+export declare interface UseQueryResult<T> {
+  data: Ref<T | undefined>
+  error: Ref<Error | null>
+  isLoading: Ref<boolean>
+  isFetching: Ref<boolean>
+  refetch: () => Promise<void>
+  unsubscribe: () => void
+}
+export declare interface UseMutationOptions<TData, TVars, TCtx = unknown> {
+  mutationFn: (vars: TVars) => Promise<TData>
+  onMutate?: (vars: TVars) => Promise<TCtx> | TCtx
+  onSuccess?: (data: TData, vars: TVars, ctx: TCtx | undefined) => void | Promise<void>
+  onError?: (error: Error, vars: TVars, ctx: TCtx | undefined) => void | Promise<void>
+  onSettled?: (data: TData | undefined, error: Error | null, vars: TVars, ctx: TCtx | undefined) => void | Promise<void>
+}
+export declare interface UseMutationResult<TData, TVars> {
+  data: Ref<TData | undefined>
+  error: Ref<Error | null>
+  isPending: Ref<boolean>
+  mutate: (vars: TVars) => void
+  mutateAsync: (vars: TVars) => Promise<TData>
+  reset: () => void
+}
+/**
+ * useQuery / useMutation / queryClient (stacksjs/stacks#1939 — Phase A).
+ *
+ * Cache + dedup + invalidation primitives. Mirrors TanStack Query shape
+ * so adopters transfer immediately. Phase A intentionally omits:
+ *   - `refetchOnFocus` / `refetchOnReconnect` (DOM listener coupling)
+ *   - automatic GC of unsubscribed cache entries
+ *   - query key partial-match invalidation via predicate functions
+ * Those land in Phase B. Prefix-match invalidation IS supported
+ * (`invalidate(['judges'])` matches `['judges', filterObj]` etc).
+ */
+export type QueryKey = readonly unknown[];
+/**
+ * Matcher for `invalidate`. Either a `QueryKey` (prefix match, the common
+ * case) or a predicate run against every cached key (stacksjs/stacks#1939
+ * Phase B) — e.g. invalidate everything tagged a given entity:
+ * `invalidate({ predicate: k => k.includes('judges') })`.
+ */
+export type QueryMatcher = QueryKey | { predicate: (key: QueryKey) => boolean }

package/dist/useQuery.js

@@ -0,0 +1,265 @@
+import { ref } from "@stacksjs/stx";
+function stableStringify(value) {
+  if (value === null || typeof value !== "object")
+    return JSON.stringify(value);
+  if (Array.isArray(value))
+    return `[${value.map(stableStringify).join(",")}]`;
+  return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(",")}}`;
+}
+function hashKey(key) {
+  return stableStringify(key);
+}
+export function createQueryClient(options = {}) {
+  const entries = new Map, gcTime = options.gcTime ?? 300000, gcTimers = new Map;
+  function collectable(e) {
+    return e.subscribers.size === 0 && e.inflight === null;
+  }
+  function removeIfCollectable(hash) {
+    const e = entries.get(hash);
+    if (e && collectable(e))
+      entries.delete(hash);
+    gcTimers.delete(hash);
+  }
+  function scheduleGc(hash) {
+    const existing = gcTimers.get(hash);
+    if (existing)
+      clearTimeout(existing);
+    if (!Number.isFinite(gcTime))
+      return;
+    if (gcTime <= 0) {
+      removeIfCollectable(hash);
+      return;
+    }
+    const t = setTimeout(() => removeIfCollectable(hash), gcTime);
+    t.unref?.();
+    gcTimers.set(hash, t);
+  }
+  function cancelGc(hash) {
+    const t = gcTimers.get(hash);
+    if (t) {
+      clearTimeout(t);
+      gcTimers.delete(hash);
+    }
+  }
+  function entry(key) {
+    const hash = hashKey(key);
+    let e = entries.get(hash);
+    if (!e) {
+      e = {
+        key,
+        hash,
+        data: void 0,
+        error: null,
+        updatedAt: 0,
+        status: "idle",
+        inflight: null,
+        invalidated: !1,
+        subscribers: new Set
+      };
+      entries.set(hash, e);
+    }
+    return e;
+  }
+  function notify(hash) {
+    const e = entries.get(hash);
+    if (!e)
+      return;
+    for (const fn of e.subscribers)
+      fn();
+  }
+  function prefixMatches(prefix, candidate) {
+    if (prefix.length > candidate.length)
+      return !1;
+    for (let i = 0;i < prefix.length; i++)
+      if (stableStringify(prefix[i]) !== stableStringify(candidate[i]))
+        return !1;
+    return !0;
+  }
+  return {
+    get(key) {
+      const hash = hashKey(key);
+      return entries.get(hash)?.data;
+    },
+    set(key, value) {
+      const e = entry(key), next = typeof value === "function" ? value(e.data) : value;
+      e.data = next;
+      e.updatedAt = Date.now();
+      e.status = "success";
+      e.error = null;
+      e.invalidated = !1;
+      notify(e.hash);
+    },
+    async invalidate(matcher) {
+      const matches = Array.isArray(matcher) ? (key) => prefixMatches(matcher, key) : matcher.predicate, refetches = [];
+      for (const e of entries.values()) {
+        if (!matches(e.key))
+          continue;
+        e.updatedAt = 0;
+        e.invalidated = !0;
+        for (const fn of e.subscribers) {
+          const result = fn();
+          if (result && typeof result.then === "function")
+            refetches.push(result);
+        }
+      }
+      await Promise.all(refetches);
+    },
+    clear() {
+      for (const t of gcTimers.values())
+        clearTimeout(t);
+      gcTimers.clear();
+      entries.clear();
+    },
+    gc() {
+      let removed = 0;
+      for (const [hash, e] of entries)
+        if (collectable(e)) {
+          entries.delete(hash);
+          cancelGc(hash);
+          removed++;
+        }
+      return removed;
+    },
+    _subscribe(hash, fn) {
+      const e = entries.get(hash);
+      if (!e)
+        return () => {};
+      cancelGc(hash);
+      e.subscribers.add(fn);
+      return () => {
+        e.subscribers.delete(fn);
+        if (e.subscribers.size === 0)
+          scheduleGc(hash);
+      };
+    },
+    _entry: entry,
+    _notify: notify
+  };
+}
+export const queryClient = createQueryClient();
+export function useQuery(opts) {
+  const client = opts.client ?? queryClient, staleTime = opts.staleTime ?? 0, enabled = opts.enabled ?? !0, e = client._entry(opts.queryKey), data = ref(e.data), error = ref(e.error), isLoading = ref(e.data === void 0 && enabled), isFetching = ref(!1);
+  function sync() {
+    data.value = e.data;
+    error.value = e.error;
+    isFetching.value = e.status === "fetching";
+    if (e.data !== void 0 || e.error !== null)
+      isLoading.value = !1;
+  }
+  async function doFetch(force) {
+    if (!force) {
+      if (e.data !== void 0 && Date.now() - e.updatedAt < staleTime) {
+        sync();
+        return;
+      }
+    }
+    if (e.inflight) {
+      try {
+        await e.inflight;
+      } catch {}
+      sync();
+      return;
+    }
+    const controller = new AbortController;
+    e.status = "fetching";
+    isFetching.value = !0;
+    if (e.data === void 0)
+      isLoading.value = !0;
+    const p = opts.queryFn({ signal: controller.signal }).then((result) => {
+      e.data = result;
+      e.error = null;
+      e.updatedAt = Date.now();
+      e.status = "success";
+      e.invalidated = !1;
+      return result;
+    }).catch((err) => {
+      e.error = err instanceof Error ? err : Error(String(err));
+      e.status = "error";
+      e.invalidated = !1;
+      throw e.error;
+    }).finally(() => {
+      e.inflight = null;
+      client._notify(e.hash);
+    });
+    e.inflight = p;
+    try {
+      await p;
+    } catch {}
+    sync();
+  }
+  const unsubscribeCache = client._subscribe(e.hash, () => {
+    if (e.invalidated && enabled && e.status !== "fetching")
+      return doFetch(!0);
+    sync();
+    return;
+  }), target = opts.window ?? (typeof window < "u" ? window : void 0), winListeners = [];
+  if (target && enabled) {
+    const onWake = () => {
+      if (e.status !== "fetching")
+        doFetch(!1);
+    };
+    if (opts.refetchOnFocus)
+      winListeners.push(["focus", onWake]);
+    if (opts.refetchOnReconnect)
+      winListeners.push(["online", onWake]);
+    for (const [evt, fn] of winListeners)
+      target.addEventListener(evt, fn);
+  }
+  function unsubscribe() {
+    unsubscribeCache();
+    if (target)
+      for (const [evt, fn] of winListeners)
+        target.removeEventListener(evt, fn);
+  }
+  if (enabled)
+    doFetch(!1);
+  else
+    sync();
+  return {
+    data,
+    error,
+    isLoading,
+    isFetching,
+    refetch: () => doFetch(!0),
+    unsubscribe
+  };
+}
+export function useMutation(opts) {
+  const data = ref(void 0), error = ref(null), isPending = ref(!1);
+  async function run(vars) {
+    isPending.value = !0;
+    error.value = null;
+    let ctx;
+    try {
+      if (opts.onMutate)
+        ctx = await opts.onMutate(vars);
+      const result = await opts.mutationFn(vars);
+      data.value = result;
+      await opts.onSuccess?.(result, vars, ctx);
+      await opts.onSettled?.(result, null, vars, ctx);
+      return result;
+    } catch (err) {
+      const e = err instanceof Error ? err : Error(String(err));
+      error.value = e;
+      await opts.onError?.(e, vars, ctx);
+      await opts.onSettled?.(void 0, e, vars, ctx);
+      throw e;
+    } finally {
+      isPending.value = !1;
+    }
+  }
+  return {
+    data,
+    error,
+    isPending,
+    mutate(vars) {
+      run(vars).catch(() => {});
+    },
+    mutateAsync: run,
+    reset() {
+      data.value = void 0;
+      error.value = null;
+      isPending.value = !1;
+    }
+  };
+}

package/dist/useRafFn.d.ts

@@ -0,0 +1,19 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Call a function on every requestAnimationFrame.
+ * Provides pause/resume controls and auto-cleanup on unmount.
+ *
+ * @param fn - The callback invoked on each animation frame, receives { delta, timestamp }
+ * @param options - Configuration options (immediate defaults to true)
+ * @returns Controls to pause, resume, and check active state
+ */
+export declare function useRafFn(fn: (args: UseRafFnCallbackArgs) => void, options?: { immediate?: boolean }): UseRafFnReturn;
+declare interface UseRafFnCallbackArgs {
+  delta: number
+  timestamp: number
+}
+declare interface UseRafFnReturn {
+  pause: () => void
+  resume: () => void
+  isActive: Ref<boolean>
+}

package/dist/useRafFn.js

@@ -0,0 +1,37 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function useRafFn(fn, options = {}) {
+  const { immediate = !0 } = options, isActive = ref(!1);
+  let rafId = null, previousTimestamp = 0;
+  function loop(timestamp) {
+    if (!isActive.value)
+      return;
+    const delta = previousTimestamp ? timestamp - previousTimestamp : 0;
+    previousTimestamp = timestamp;
+    fn({ delta, timestamp });
+    rafId = requestAnimationFrame(loop);
+  }
+  function resume() {
+    if (isActive.value)
+      return;
+    if (typeof requestAnimationFrame > "u")
+      return;
+    isActive.value = !0;
+    previousTimestamp = 0;
+    rafId = requestAnimationFrame(loop);
+  }
+  function pause() {
+    if (!isActive.value)
+      return;
+    isActive.value = !1;
+    if (rafId !== null && typeof cancelAnimationFrame < "u") {
+      cancelAnimationFrame(rafId);
+      rafId = null;
+    }
+  }
+  if (immediate)
+    resume();
+  try {
+    onUnmounted(pause);
+  } catch {}
+  return { pause, resume, isActive };
+}

package/dist/useRefHistory.d.ts

@@ -0,0 +1,28 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Auto-tracked ref history with undo/redo.
+ * Automatically commits a snapshot on every change to the source ref.
+ *
+ * @param source - The reactive source to track
+ * @param options - Capacity limit, deep watching, and clone behavior
+ */
+export declare function useRefHistory<T>(source: Ref<T>, options?: UseRefHistoryOptions): UseRefHistoryReturn<T>;
+export declare interface UseRefHistoryRecord<T> {
+  snapshot: T
+  timestamp: number
+}
+export declare interface UseRefHistoryOptions {
+  capacity?: number
+  deep?: boolean
+  clone?: boolean
+}
+export declare interface UseRefHistoryReturn<T> {
+  history: Ref<UseRefHistoryRecord<T>[]>
+  commit: () => void
+  undo: () => void
+  redo: () => void
+  canUndo: Ref<boolean>
+  canRedo: Ref<boolean>
+  clear: () => void
+  last: Ref<UseRefHistoryRecord<T>>
+}

package/dist/useRefHistory.js

@@ -0,0 +1,72 @@
+import { computed, ref, watch } from "@stacksjs/stx";
+function cloneValue(val, shouldClone) {
+  if (!shouldClone)
+    return val;
+  if (typeof structuredClone === "function")
+    return structuredClone(val);
+  return JSON.parse(JSON.stringify(val));
+}
+export function useRefHistory(source, options = {}) {
+  const { capacity = 1 / 0, deep = !1, clone = !1 } = options, undoStack = ref([
+    { snapshot: cloneValue(source.value, clone), timestamp: Date.now() }
+  ]), redoStack = ref([]);
+  let isUndoRedoing = !1;
+  const canUndo = computed(() => undoStack.value.length > 1), canRedo = computed(() => redoStack.value.length > 0), last = computed(() => {
+    return undoStack.value[undoStack.value.length - 1];
+  });
+  function commit() {
+    const record = {
+      snapshot: cloneValue(source.value, clone),
+      timestamp: Date.now()
+    };
+    undoStack.value = [...undoStack.value, record];
+    if (capacity !== 1 / 0 && undoStack.value.length > capacity)
+      undoStack.value = undoStack.value.slice(undoStack.value.length - capacity);
+    redoStack.value = [];
+  }
+  function undo() {
+    if (undoStack.value.length <= 1)
+      return;
+    isUndoRedoing = !0;
+    const current = undoStack.value[undoStack.value.length - 1], newUndoStack = undoStack.value.slice(0, -1);
+    undoStack.value = newUndoStack;
+    if (current)
+      redoStack.value = [...redoStack.value, current];
+    const previous = newUndoStack[newUndoStack.length - 1];
+    if (previous)
+      source.value = cloneValue(previous.snapshot, clone);
+    isUndoRedoing = !1;
+  }
+  function redo() {
+    if (redoStack.value.length === 0)
+      return;
+    isUndoRedoing = !0;
+    const next = redoStack.value[redoStack.value.length - 1];
+    redoStack.value = redoStack.value.slice(0, -1);
+    if (next) {
+      undoStack.value = [...undoStack.value, next];
+      source.value = cloneValue(next.snapshot, clone);
+    }
+    isUndoRedoing = !1;
+  }
+  function clear() {
+    undoStack.value = [
+      { snapshot: cloneValue(source.value, clone), timestamp: Date.now() }
+    ];
+    redoStack.value = [];
+  }
+  watch(source, () => {
+    if (!isUndoRedoing)
+      commit();
+  }, { deep });
+  return {
+    history: undoStack,
+    commit,
+    undo,
+    redo,
+    canUndo,
+    canRedo,
+    clear,
+    last
+  };
+}

package/dist/useResizeObserver.d.ts

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

package/dist/useResizeObserver.js

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

package/dist/useScreenOrientation.d.ts

@@ -0,0 +1,13 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive Screen Orientation API.
+ */
+export declare function useScreenOrientation(): UseScreenOrientationReturn;
+export declare interface UseScreenOrientationReturn {
+  isSupported: Ref<boolean>
+  orientation: Ref<string | undefined>
+  angle: Ref<number>
+  lockOrientation: (type: ScreenOrientationLockType) => Promise<void>
+  unlockOrientation: () => void
+}
+declare type ScreenOrientationLockType = 'any' | 'natural' | 'landscape' | 'portrait' | 'portrait-primary' | 'portrait-secondary' | 'landscape-primary' | 'landscape-secondary';