@stacksjs/composables 0.70.88 → 0.70.90

package/dist/useBreakpoints.js

@@ -0,0 +1,97 @@
+import { computed, ref, onUnmounted } from "@stacksjs/stx";
+import { defaultWindow } from "./_shared";
+export function useBreakpoints(breakpoints) {
+  const win = defaultWindow(), width = ref(win ? win.innerWidth : 0);
+  function updateWidth() {
+    if (win)
+      width.value = win.innerWidth;
+  }
+  if (win) {
+    win.addEventListener("resize", updateWidth);
+    try {
+      onUnmounted(() => {
+        win.removeEventListener("resize", updateWidth);
+      });
+    } catch {}
+  }
+  function getValue(k) {
+    return breakpoints[k];
+  }
+  function greaterOrEqual(k) {
+    return computed(() => width.value >= getValue(k));
+  }
+  function smallerOrEqual(k) {
+    return computed(() => width.value <= getValue(k));
+  }
+  function between(a, b) {
+    return computed(() => width.value >= getValue(a) && width.value < getValue(b));
+  }
+  function isGreater(k) {
+    return computed(() => width.value > getValue(k));
+  }
+  function isSmaller(k) {
+    return computed(() => width.value < getValue(k));
+  }
+  function current() {
+    return computed(() => {
+      return Object.keys(breakpoints).sort((a, b) => breakpoints[a] - breakpoints[b]).filter((k) => width.value >= breakpoints[k]);
+    });
+  }
+  return {
+    greaterOrEqual,
+    smallerOrEqual,
+    between,
+    isGreater,
+    isSmaller,
+    current
+  };
+}
+export const breakpointsTailwind = {
+  sm: 640,
+  md: 768,
+  lg: 1024,
+  xl: 1280,
+  "2xl": 1536
+}, breakpointsBootstrap = {
+  sm: 576,
+  md: 768,
+  lg: 992,
+  xl: 1200,
+  xxl: 1400
+}, breakpointsBootstrapV5 = breakpointsBootstrap, breakpointsAntDesign = {
+  xs: 480,
+  sm: 576,
+  md: 768,
+  lg: 992,
+  xl: 1200,
+  xxl: 1600
+}, breakpointsVuetify = {
+  xs: 600,
+  sm: 960,
+  md: 1264,
+  lg: 1904
+}, breakpointsQuasar = {
+  xs: 600,
+  sm: 1024,
+  md: 1440,
+  lg: 1920
+}, breakpointsMasterCss = {
+  "3xs": 360,
+  "2xs": 480,
+  xs: 600,
+  sm: 768,
+  md: 1024,
+  lg: 1280,
+  xl: 1440,
+  "2xl": 1600,
+  "3xl": 1920,
+  "4xl": 2560
+}, breakpointsSematic = {
+  mobileS: 320,
+  mobileM: 375,
+  mobileL: 425,
+  tablet: 768,
+  laptop: 1024,
+  laptopL: 1440,
+  desktop: 2560
+};

package/dist/useBroadcastChannel.d.ts

@@ -0,0 +1,14 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive BroadcastChannel API for cross-tab communication.
+ */
+export declare function useBroadcastChannel(name: string): UseBroadcastChannelReturn;
+export declare interface UseBroadcastChannelReturn {
+  isSupported: Ref<boolean>
+  channel: Ref<BroadcastChannel | undefined>
+  data: Ref<any>
+  error: Ref<any>
+  post: (data: any) => void
+  close: () => void
+  isClosed: Ref<boolean>
+}

package/dist/useBroadcastChannel.js

@@ -0,0 +1,31 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+export function useBroadcastChannel(name) {
+  const isSupported = ref(typeof BroadcastChannel < "u"), channel = ref(void 0), data = ref(null), error = ref(null), isClosed = ref(!1);
+  if (isSupported.value) {
+    const bc = new BroadcastChannel(name);
+    channel.value = bc;
+    bc.onmessage = (e) => {
+      data.value = e.data;
+    };
+    bc.onmessageerror = (e) => {
+      error.value = e;
+    };
+    try {
+      onUnmounted(() => {
+        bc.close();
+        isClosed.value = !0;
+      });
+    } catch {}
+  }
+  function post(message) {
+    if (channel.value && !isClosed.value)
+      channel.value.postMessage(message);
+  }
+  function close() {
+    if (channel.value && !isClosed.value) {
+      channel.value.close();
+      isClosed.value = !0;
+    }
+  }
+  return { isSupported, channel, data, error, post, close, isClosed };
+}

package/dist/useBrowserLocation.d.ts

@@ -0,0 +1,18 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive browser location.
+ * Returns reactive refs for each part of window.location.
+ * Listens for popstate events to keep refs updated.
+ */
+export declare function useBrowserLocation(): UseBrowserLocationReturn;
+export declare interface UseBrowserLocationReturn {
+  href: Ref<string>
+  protocol: Ref<string>
+  host: Ref<string>
+  hostname: Ref<string>
+  port: Ref<string>
+  pathname: Ref<string>
+  search: Ref<string>
+  hash: Ref<string>
+  origin: Ref<string>
+}

package/dist/useBrowserLocation.js

@@ -0,0 +1,64 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { defaultWindow } from "./_shared";
+export function useBrowserLocation() {
+  const win = defaultWindow();
+  function readLocation() {
+    if (!win)
+      return {
+        href: "",
+        protocol: "",
+        host: "",
+        hostname: "",
+        port: "",
+        pathname: "",
+        search: "",
+        hash: "",
+        origin: ""
+      };
+    return {
+      href: win.location.href,
+      protocol: win.location.protocol,
+      host: win.location.host,
+      hostname: win.location.hostname,
+      port: win.location.port,
+      pathname: win.location.pathname,
+      search: win.location.search,
+      hash: win.location.hash,
+      origin: win.location.origin
+    };
+  }
+  const initial = readLocation(), href = ref(initial.href), protocol = ref(initial.protocol), host = ref(initial.host), hostname = ref(initial.hostname), port = ref(initial.port), pathname = ref(initial.pathname), search = ref(initial.search), hash = ref(initial.hash), origin = ref(initial.origin);
+  function update() {
+    const loc = readLocation();
+    href.value = loc.href;
+    protocol.value = loc.protocol;
+    host.value = loc.host;
+    hostname.value = loc.hostname;
+    port.value = loc.port;
+    pathname.value = loc.pathname;
+    search.value = loc.search;
+    hash.value = loc.hash;
+    origin.value = loc.origin;
+  }
+  if (win) {
+    win.addEventListener("popstate", update);
+    win.addEventListener("hashchange", update);
+    try {
+      onUnmounted(() => {
+        win.removeEventListener("popstate", update);
+        win.removeEventListener("hashchange", update);
+      });
+    } catch {}
+  }
+  return {
+    href,
+    protocol,
+    host,
+    hostname,
+    port,
+    pathname,
+    search,
+    hash,
+    origin
+  };
+}

package/dist/useClipboard.d.ts

@@ -0,0 +1,17 @@
+import type { MaybeRefOrGetter } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive Clipboard API.
+ * Read and write to the clipboard reactively.
+ */
+export declare function useClipboard(options?: UseClipboardOptions): UseClipboardReturn;
+export declare interface UseClipboardOptions {
+  source?: MaybeRefOrGetter<string>
+  copiedDuring?: number
+}
+export declare interface UseClipboardReturn {
+  text: Ref<string>
+  isSupported: Ref<boolean>
+  copied: Ref<boolean>
+  copy: (text?: string) => Promise<void>
+}

package/dist/useClipboard.js

@@ -0,0 +1,32 @@
+import { ref } from "@stacksjs/stx";
+import { defaultNavigator, toValue } from "./_shared";
+export function useClipboard(options) {
+  const {
+    source,
+    copiedDuring = 1500
+  } = options ?? {}, nav = defaultNavigator(), isSupported = ref(!!nav && "clipboard" in nav), text = ref(""), copied = ref(!1);
+  let copiedTimer;
+  async function copy(value) {
+    if (!isSupported.value)
+      return;
+    const valueToCopy = value ?? (source !== void 0 ? toValue(source) : void 0);
+    if (valueToCopy === void 0)
+      return;
+    try {
+      await nav.clipboard.writeText(valueToCopy);
+      text.value = valueToCopy;
+      copied.value = !0;
+      if (copiedTimer)
+        clearTimeout(copiedTimer);
+      copiedTimer = setTimeout(() => {
+        copied.value = !1;
+      }, copiedDuring);
+    } catch {}
+  }
+  return {
+    text,
+    isSupported,
+    copied,
+    copy
+  };
+}

package/dist/useClipboardItems.d.ts

@@ -0,0 +1,11 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive ClipboardItems API for rich content (images, etc.).
+ */
+export declare function useClipboardItems(): UseClipboardItemsReturn;
+export declare interface UseClipboardItemsReturn {
+  isSupported: Ref<boolean>
+  content: Ref<ClipboardItems>
+  copy: (items: ClipboardItems) => Promise<void>
+  read: () => Promise<void>
+}

package/dist/useClipboardItems.js

@@ -0,0 +1,15 @@
+import { ref } from "@stacksjs/stx";
+export function useClipboardItems() {
+  const isSupported = ref(typeof navigator < "u" && "clipboard" in navigator && typeof ClipboardItem < "u"), content = ref([]);
+  async function copy(items) {
+    if (isSupported.value) {
+      await navigator.clipboard.write(items);
+      content.value = items;
+    }
+  }
+  async function read() {
+    if (isSupported.value)
+      content.value = await navigator.clipboard.read();
+  }
+  return { isSupported, content, copy, read };
+}

package/dist/useCloned.d.ts

@@ -0,0 +1,15 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Deep clone a ref value. Returns a cloned ref that syncs when the source changes.
+ *
+ * @param source - The source ref to clone
+ * @param options - Optional custom clone function
+ */
+export declare function useCloned<T>(source: Ref<T>, options?: UseClonedOptions<T>): UseClonedReturn<T>;
+export declare interface UseClonedOptions<T> {
+  clone?: (val: T) => T
+}
+export declare interface UseClonedReturn<T> {
+  cloned: Ref<T>
+  sync: () => void
+}

package/dist/useCloned.js

@@ -0,0 +1,16 @@
+import { ref, watch } from "@stacksjs/stx";
+function defaultClone(val) {
+  if (typeof structuredClone === "function")
+    return structuredClone(val);
+  return JSON.parse(JSON.stringify(val));
+}
+export function useCloned(source, options = {}) {
+  const cloneFn = options.clone ?? defaultClone, cloned = ref(cloneFn(source.value));
+  function sync() {
+    cloned.value = cloneFn(source.value);
+  }
+  watch(source, () => {
+    sync();
+  });
+  return { cloned, sync };
+}

package/dist/useColorMode.d.ts

@@ -0,0 +1,18 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive color mode (dark / light / custom) with auto-detection and persistence.
+ */
+export declare function useColorMode(options?: UseColorModeOptions): UseColorModeReturn;
+export declare interface UseColorModeOptions {
+  attribute?: string
+  initialValue?: ColorMode
+  modes?: Record<string, string>
+  storageKey?: string
+  selector?: string
+}
+export declare interface UseColorModeReturn {
+  mode: Ref<ColorMode>
+  system: Ref<'dark' | 'light'>
+  store: Ref<ColorMode>
+}
+export type ColorMode = 'dark' | 'light' | 'auto' | (string & {});

package/dist/useColorMode.js

@@ -0,0 +1,60 @@
+import { onUnmounted, ref, watch } from "@stacksjs/stx";
+export function useColorMode(options = {}) {
+  const {
+    attribute = "class",
+    initialValue = "auto",
+    modes = {},
+    storageKey = "color-mode",
+    selector
+  } = options, system = ref("light");
+  if (typeof window < "u" && window.matchMedia) {
+    const mq = window.matchMedia("(prefers-color-scheme: dark)");
+    system.value = mq.matches ? "dark" : "light";
+    const onChange = (e) => {
+      system.value = e.matches ? "dark" : "light";
+    };
+    mq.addEventListener("change", onChange);
+    try {
+      onUnmounted(() => {
+        mq.removeEventListener("change", onChange);
+      });
+    } catch {}
+  }
+  let stored = initialValue;
+  if (typeof localStorage < "u") {
+    const val = localStorage.getItem(storageKey);
+    if (val)
+      stored = val;
+  }
+  const store = ref(stored), mode = ref(store.value === "auto" ? system.value : store.value);
+  function applyMode(m) {
+    if (typeof document > "u")
+      return;
+    const el = selector ? document.querySelector(selector) : document.documentElement;
+    if (!el)
+      return;
+    const value = modes[m] ?? m;
+    if (attribute === "class") {
+      const allModes = ["dark", "light", ...Object.keys(modes), ...Object.values(modes)];
+      for (const cls of allModes)
+        el.classList.remove(cls);
+      if (value)
+        el.classList.add(value);
+    } else
+      el.setAttribute(attribute, value);
+  }
+  watch(store, (val) => {
+    if (typeof localStorage < "u")
+      localStorage.setItem(storageKey, val);
+    mode.value = val === "auto" ? system.value : val;
+  });
+  watch(system, (val) => {
+    if (store.value === "auto")
+      mode.value = val;
+  });
+  watch(mode, (val) => {
+    applyMode(val);
+  });
+  applyMode(mode.value);
+  return { mode, system, store };
+}

package/dist/useConfirmDialog.d.ts

@@ -0,0 +1,14 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Create a confirm dialog composable with reveal/confirm/cancel flow.
+ */
+export declare function useConfirmDialog<T = any, C = any>(): UseConfirmDialogReturn<T, C>;
+export declare interface UseConfirmDialogReturn<T = any, C = any> {
+  isRevealed: Ref<boolean>
+  reveal: (data?: T) => Promise<{ data?: C, isCanceled: boolean }>
+  confirm: (data?: C) => void
+  cancel: () => void
+  onConfirm: (fn: (data?: C) => void) => { off: () => void }
+  onCancel: (fn: () => void) => { off: () => void }
+  onReveal: (fn: (data?: T) => void) => { off: () => void }
+}

package/dist/useConfirmDialog.js

@@ -0,0 +1,34 @@
+import { ref } from "@stacksjs/stx";
+import { createEventHook } from "./createEventHook";
+export function useConfirmDialog() {
+  const isRevealed = ref(!1), confirmHook = createEventHook(), cancelHook = createEventHook(), revealHook = createEventHook();
+  let resolvePromise = null;
+  function reveal(data) {
+    isRevealed.value = !0;
+    revealHook.trigger(data);
+    return new Promise((resolve) => {
+      resolvePromise = resolve;
+    });
+  }
+  function confirm(data) {
+    isRevealed.value = !1;
+    confirmHook.trigger(data);
+    resolvePromise?.({ data, isCanceled: !1 });
+    resolvePromise = null;
+  }
+  function cancel() {
+    isRevealed.value = !1;
+    cancelHook.trigger(void 0);
+    resolvePromise?.({ isCanceled: !0 });
+    resolvePromise = null;
+  }
+  return {
+    isRevealed,
+    reveal,
+    confirm,
+    cancel,
+    onConfirm: confirmHook.on,
+    onCancel: cancelHook.on,
+    onReveal: revealHook.on
+  };
+}

package/dist/useCounter.d.ts

@@ -0,0 +1,20 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive counter with increment, decrement, set, reset, and min/max bounds.
+ *
+ * @param initialValue - Starting value (default 0)
+ * @param options - Optional min/max bounds
+ */
+export declare function useCounter(initialValue?: number, options?: UseCounterOptions): UseCounterReturn;
+export declare interface UseCounterOptions {
+  min?: number
+  max?: number
+}
+export declare interface UseCounterReturn {
+  count: Ref<number>
+  inc: (delta?: number) => number
+  dec: (delta?: number) => number
+  set: (val: number) => number
+  reset: (val?: number) => number
+  get: () => number
+}

package/dist/useCounter.js

@@ -0,0 +1,28 @@
+import { ref } from "@stacksjs/stx";
+export function useCounter(initialValue = 0, options = {}) {
+  const { min = -1 / 0, max = 1 / 0 } = options;
+  function clamp(val) {
+    return Math.min(max, Math.max(min, val));
+  }
+  const count = ref(clamp(initialValue));
+  function inc(delta = 1) {
+    count.value = clamp(count.value + delta);
+    return count.value;
+  }
+  function dec(delta = 1) {
+    count.value = clamp(count.value - delta);
+    return count.value;
+  }
+  function set(val) {
+    count.value = clamp(val);
+    return count.value;
+  }
+  function reset(val = initialValue) {
+    count.value = clamp(val);
+    return count.value;
+  }
+  function get() {
+    return count.value;
+  }
+  return { count, inc, dec, set, reset, get };
+}

package/dist/useCssVar.d.ts

@@ -0,0 +1,10 @@
+import type { MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive CSS variable binding.
+ *
+ * @param name - The CSS variable name (e.g., '--color')
+ * @param target - The target element (defaults to document.documentElement)
+ * @param defaultValue - Default value if the variable is not set
+ */
+export declare function useCssVar(name: MaybeRef<string>, target?: MaybeRef<HTMLElement | null | undefined>, defaultValue?: string): Ref<string>;

package/dist/useCssVar.js

@@ -0,0 +1,23 @@
+import { onUnmounted, ref, watch } from "@stacksjs/stx";
+import { unref } from "./_shared";
+export function useCssVar(name, target, defaultValue) {
+  const variable = ref(defaultValue ?? ""), getEl = () => {
+    const t = unref(target);
+    if (t)
+      return t;
+    if (typeof document < "u")
+      return document.documentElement;
+    return null;
+  }, el = getEl();
+  if (el) {
+    const current = getComputedStyle(el).getPropertyValue(unref(name)).trim();
+    if (current)
+      variable.value = current;
+  }
+  watch(variable, (val) => {
+    const element = getEl();
+    if (element)
+      element.style.setProperty(unref(name), val);
+  });
+  return variable;
+}

package/dist/useCycleList.d.ts

@@ -0,0 +1,18 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Cycle through a list of values with wrap-around.
+ *
+ * @param list - Array of values to cycle through
+ * @param options - Optional initial value
+ */
+export declare function useCycleList<T>(list: T[], options?: UseCycleListOptions<T>): UseCycleListReturn<T>;
+export declare interface UseCycleListOptions<T> {
+  initialValue?: T
+}
+export declare interface UseCycleListReturn<T> {
+  state: Ref<T>
+  index: Ref<number>
+  next: (n?: number) => T
+  prev: (n?: number) => T
+  go: (i: number) => T
+}

package/dist/useCycleList.js

@@ -0,0 +1,27 @@
+import { computed, ref } from "@stacksjs/stx";
+export function useCycleList(list, options = {}) {
+  const length = list.length;
+  if (length === 0)
+    throw Error("useCycleList requires a non-empty list");
+  const initialIndex = options.initialValue !== void 0 ? list.indexOf(options.initialValue) : 0, index = ref(initialIndex >= 0 ? initialIndex : 0);
+  function at(i) {
+    return list[i];
+  }
+  const state = computed(() => at(index.value));
+  function normalizeIndex(i) {
+    return (i % length + length) % length;
+  }
+  function next(n = 1) {
+    index.value = normalizeIndex(index.value + n);
+    return at(index.value);
+  }
+  function prev(n = 1) {
+    index.value = normalizeIndex(index.value - n);
+    return at(index.value);
+  }
+  function go(i) {
+    index.value = normalizeIndex(i);
+    return at(index.value);
+  }
+  return { state, index, next, prev, go };
+}

package/dist/useDark.d.ts

@@ -0,0 +1,11 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive preferred color scheme detection.
+ * Returns a ref that tracks the user's OS-level dark mode preference.
+ */
+export declare function usePreferredDark(): Ref<boolean>;
+/**
+ * Reactive dark mode with localStorage persistence.
+ * Adds/removes the 'dark' class on document.documentElement.
+ */
+export declare function useDark(): Ref<boolean>;

package/dist/useDark.js

@@ -0,0 +1,38 @@
+import { onUnmounted, ref, watch } from "@stacksjs/stx";
+export function usePreferredDark() {
+  const matches = ref(!1);
+  if (typeof window < "u" && window.matchMedia) {
+    const mq = window.matchMedia("(prefers-color-scheme: dark)");
+    matches.value = mq.matches;
+    const onChange = (e) => {
+      matches.value = e.matches;
+    };
+    mq.addEventListener("change", onChange);
+    try {
+      onUnmounted(() => {
+        mq.removeEventListener("change", onChange);
+      });
+    } catch {}
+  }
+  return matches;
+}
+export function useDark() {
+  let initial = usePreferredDark().value;
+  if (typeof localStorage < "u") {
+    const stored = localStorage.getItem("color-scheme");
+    if (stored === "dark")
+      initial = !0;
+    else if (stored === "light")
+      initial = !1;
+  }
+  const isDark = ref(initial);
+  watch(isDark, (val) => {
+    if (typeof document < "u")
+      document.documentElement.classList.toggle("dark", val);
+    if (typeof localStorage < "u")
+      localStorage.setItem("color-scheme", val ? "dark" : "light");
+  });
+  if (typeof document < "u")
+    document.documentElement.classList.toggle("dark", isDark.value);
+  return isDark;
+}

package/dist/useDateFormat.d.ts

@@ -0,0 +1,10 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive date formatting composable.
+ * Returns a ref containing the formatted date string.
+ * Uses @stacksjs/datetime format() under the hood.
+ *
+ * @param date - Date value (or ref) to format
+ * @param formatStr - Token-based format string (e.g. 'YYYY-MM-DD HH:mm:ss')
+ */
+export declare function useDateFormat(date: Ref<Date | string | number> | Date | string | number, formatStr: string): Ref<string>;