@stacksjs/composables 0.70.88 → 0.70.90

package/dist/useElementSize.js

@@ -0,0 +1,34 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { unref, noop } from "./_shared";
+export function useElementSize(target, options) {
+  const width = ref(options?.initialSize?.width ?? 0), height = ref(options?.initialSize?.height ?? 0), isSupported = typeof window < "u" && "ResizeObserver" in window;
+  let cleanup = noop;
+  if (isSupported) {
+    const el = unref(target);
+    if (el) {
+      const observer = new ResizeObserver((entries) => {
+        for (const entry of entries)
+          if (entry.contentBoxSize) {
+            const boxSize = Array.isArray(entry.contentBoxSize) ? entry.contentBoxSize[0] : entry.contentBoxSize;
+            width.value = boxSize.inlineSize;
+            height.value = boxSize.blockSize;
+          } else {
+            width.value = entry.contentRect.width;
+            height.value = entry.contentRect.height;
+          }
+      });
+      observer.observe(el);
+      cleanup = () => {
+        observer.disconnect();
+        cleanup = noop;
+      };
+    }
+  }
+  const stop = () => {
+    cleanup();
+  };
+  try {
+    onUnmounted(stop);
+  } catch {}
+  return { width, height, stop };
+}

package/dist/useElementVisibility.d.ts

@@ -0,0 +1,10 @@
+import { type MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive element visibility.
+ * Uses IntersectionObserver to track whether the target element is visible in the viewport.
+ *
+ * @param target - The element to observe (or a Ref to one)
+ * @returns A ref that is true when the element is visible
+ */
+export declare function useElementVisibility(target: MaybeRef<HTMLElement | null>): Ref<boolean>;

package/dist/useElementVisibility.js

@@ -0,0 +1,10 @@
+import { ref } from "@stacksjs/stx";
+import { useIntersectionObserver } from "./useIntersectionObserver";
+export function useElementVisibility(target) {
+  const isVisible = ref(!1);
+  useIntersectionObserver(target, (entries) => {
+    for (const entry of entries)
+      isVisible.value = entry.isIntersecting;
+  }, { threshold: 0 });
+  return isVisible;
+}

package/dist/useEventBus.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A reactive event bus for cross-component communication.
+ *
+ * @param key - A unique key identifying the event bus channel
+ */
+export declare function useEventBus<T = any>(key: string | symbol): UseEventBusReturn<T>;
+export declare interface UseEventBusReturn<T = any> {
+  on: (listener: EventBusListener<T>) => () => void
+  once: (listener: EventBusListener<T>) => () => void
+  emit: (event: T) => void
+  off: (listener: EventBusListener<T>) => void
+  reset: () => void
+}
+export type EventBusListener<T = any> = (_event: T) => void;

package/dist/useEventBus.js

@@ -0,0 +1,41 @@
+import { onUnmounted } from "@stacksjs/stx";
+const buses = new Map;
+export function useEventBus(key) {
+  if (!buses.has(key))
+    buses.set(key, new Set);
+  const listeners = buses.get(key), localListeners = [];
+  function on(listener) {
+    listeners.add(listener);
+    localListeners.push(listener);
+    return () => off(listener);
+  }
+  function once(listener) {
+    const wrapper = (event) => {
+      listener(event);
+      off(wrapper);
+    };
+    return on(wrapper);
+  }
+  function emit(event) {
+    for (const listener of listeners)
+      listener(event);
+  }
+  function off(listener) {
+    listeners.delete(listener);
+    const idx = localListeners.indexOf(listener);
+    if (idx !== -1)
+      localListeners.splice(idx, 1);
+  }
+  function reset() {
+    listeners.clear();
+    localListeners.length = 0;
+  }
+  try {
+    onUnmounted(() => {
+      for (const listener of localListeners)
+        listeners.delete(listener);
+      localListeners.length = 0;
+    });
+  } catch {}
+  return { on, once, emit, off, reset };
+}

package/dist/useEventListener.d.ts

@@ -0,0 +1,14 @@
+import { type MaybeRef } from './_shared';
+/**
+ * Auto-cleanup event listener.
+ * Registers an event listener on the target and automatically removes it on unmount.
+ * Supports reactive targets via MaybeRef.
+ *
+ * @param target - The event target (Window, Document, HTMLElement, or a Ref to one)
+ * @param event - The event name
+ * @param handler - The event handler
+ * @param options - AddEventListenerOptions
+ * @returns A cleanup function to manually remove the listener
+ */
+export declare function useEventListener(target: MaybeRef<EventTarget | null | undefined> | EventTarget, event: string, handler: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): () => void;
+declare type EventTarget = Window | Document | HTMLElement | Element;

package/dist/useEventListener.js

@@ -0,0 +1,29 @@
+import { onUnmounted, watch } from "@stacksjs/stx";
+import { isRef, unref, noop, defaultWindow } from "./_shared";
+export function useEventListener(target, event, handler, options) {
+  let cleanup = noop;
+  const register = (el) => {
+    if (!el)
+      return noop;
+    el.addEventListener(event, handler, options);
+    return () => {
+      el.removeEventListener(event, handler, options);
+    };
+  };
+  if (isRef(target)) {
+    watch(target, (_newTarget, _oldTarget) => {
+      cleanup();
+      cleanup = register(unref(target));
+    });
+    cleanup = register(target.value);
+  } else
+    cleanup = register(target);
+  const stop = () => {
+    cleanup();
+    cleanup = noop;
+  };
+  try {
+    onUnmounted(stop);
+  } catch {}
+  return stop;
+}

package/dist/useEventSource.d.ts

@@ -0,0 +1,32 @@
+import type { MaybeRefOrGetter } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive Server-Sent Events (EventSource) connection.
+ *
+ * @param url - The EventSource URL (can be a ref, getter, or raw string)
+ * @param events - Array of event names to listen for (in addition to 'message')
+ * @param options - Configuration options
+ * @returns Reactive EventSource state and control methods
+ *
+ * @example
+ * ```ts
+ * const { data, event, status, close } = useEventSource('/api/events', ['update', 'delete'], {
+ *   withCredentials: true,
+ * })
+ * ```
+ */
+export declare function useEventSource(url: MaybeRefOrGetter<string>, events?: string[], options?: UseEventSourceOptions): UseEventSourceReturn;
+export declare interface UseEventSourceOptions {
+  withCredentials?: boolean
+  immediate?: boolean
+}
+export declare interface UseEventSourceReturn {
+  data: Ref<string | null>
+  event: Ref<string | null>
+  status: Ref<EventSourceStatus>
+  error: Ref<Event | null>
+  eventSource: Ref<EventSource | null>
+  close: () => void
+  open: () => void
+}
+export type EventSourceStatus = 'CONNECTING' | 'OPEN' | 'CLOSED';

package/dist/useEventSource.js

@@ -0,0 +1,72 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { toValue } from "./_shared";
+export function useEventSource(url, events = [], options = {}) {
+  const {
+    withCredentials = !1,
+    immediate = !0
+  } = options, data = ref(null), event = ref(null), status = ref("CLOSED"), error = ref(null), eventSourceRef = ref(null);
+  let listeners = [];
+  function close() {
+    const es = eventSourceRef.value;
+    if (es) {
+      for (const { eventName, handler } of listeners)
+        es.removeEventListener(eventName, handler);
+      listeners = [];
+      es.close();
+      eventSourceRef.value = null;
+      status.value = "CLOSED";
+    }
+  }
+  function open() {
+    if (typeof EventSource > "u")
+      return;
+    close();
+    const resolvedUrl = toValue(url);
+    status.value = "CONNECTING";
+    const es = new EventSource(resolvedUrl, { withCredentials });
+    eventSourceRef.value = es;
+    es.onopen = () => {
+      status.value = "OPEN";
+      error.value = null;
+    };
+    es.onerror = (e) => {
+      error.value = e;
+      if (es.readyState === EventSource.CLOSED)
+        status.value = "CLOSED";
+      else
+        status.value = "CONNECTING";
+    };
+    const messageHandler = (e) => {
+      const messageEvent = e;
+      data.value = messageEvent.data;
+      event.value = "message";
+    };
+    es.addEventListener("message", messageHandler);
+    listeners.push({ eventName: "message", handler: messageHandler });
+    for (const eventName of events) {
+      const handler = (e) => {
+        const messageEvent = e;
+        data.value = messageEvent.data;
+        event.value = eventName;
+      };
+      es.addEventListener(eventName, handler);
+      listeners.push({ eventName, handler });
+    }
+  }
+  if (immediate)
+    open();
+  try {
+    onUnmounted(() => {
+      close();
+    });
+  } catch {}
+  return {
+    data,
+    event,
+    status,
+    error,
+    eventSource: eventSourceRef,
+    close,
+    open
+  };
+}

package/dist/useEyeDropper.d.ts

@@ -0,0 +1,10 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive EyeDropper API.
+ */
+export declare function useEyeDropper(): UseEyeDropperReturn;
+export declare interface UseEyeDropperReturn {
+  isSupported: Ref<boolean>
+  sRGBHex: Ref<string>
+  open: () => Promise<{ sRGBHex: string } | undefined>
+}

package/dist/useEyeDropper.js

@@ -0,0 +1,17 @@
+import { ref } from "@stacksjs/stx";
+export function useEyeDropper() {
+  const isSupported = ref(typeof window < "u" && "EyeDropper" in window), sRGBHex = ref("");
+  async function open() {
+    if (!isSupported.value)
+      return;
+    const dropper = new window.EyeDropper;
+    try {
+      const result = await dropper.open();
+      sRGBHex.value = result.sRGBHex;
+      return result;
+    } catch {
+      return;
+    }
+  }
+  return { isSupported, sRGBHex, open };
+}

package/dist/useFavicon.d.ts

@@ -0,0 +1,8 @@
+import type { MaybeRefOrGetter } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive favicon.
+ *
+ * @param newIcon - URL of the favicon or a reactive ref/getter
+ */
+export declare function useFavicon(newIcon?: MaybeRefOrGetter<string | null | undefined>): Ref<string | null>;

package/dist/useFavicon.js

@@ -0,0 +1,22 @@
+import { ref, watch } from "@stacksjs/stx";
+import { toValue } from "./_shared";
+export function useFavicon(newIcon) {
+  const favicon = ref(toValue(newIcon ?? null));
+  function applyIcon(icon) {
+    if (typeof document > "u" || !icon)
+      return;
+    let link = document.querySelector('link[rel*="icon"]');
+    if (!link) {
+      link = document.createElement("link");
+      link.rel = "icon";
+      link.type = "image/x-icon";
+      document.head.appendChild(link);
+    }
+    link.href = icon;
+  }
+  watch(favicon, (val) => {
+    applyIcon(val);
+  });
+  applyIcon(favicon.value);
+  return favicon;
+}

package/dist/useFetch.d.ts

@@ -0,0 +1,35 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Chainable reactive fetch composable. Pass the expected success body
+ * shape as the type argument to get a typed `data.value`.
+ *
+ * @example
+ * ```ts
+ * interface Post { id: number, title: string }
+ * const { error, data } = await useFetch<Post[]>('/api/posts').get().json()
+ * //      data: Ref<Post[] | null>
+ * const { data } = await useFetch<Post>('/api/posts').post(JSON.stringify(body)).json()
+ * const { error } = await useFetch('/api/posts/1').delete().json()
+ * ```
+ */
+export declare function useFetch<T = unknown>(url: string): FetchBuilder<T>;
+/**
+ * Result of a terminal `.json()` call. Generic over the success body
+ * `T` (stacksjs/stacks#1924) so `data.value` is typed instead of
+ * `any`. `error` stays `unknown` — it can be a parsed error body OR a
+ * thrown network error, so the caller should narrow before use.
+ */
+export declare interface UseFetchResult<T = unknown> {
+  data: Ref<T | null>
+  error: Ref<unknown>
+  isFetching: Ref<boolean>
+  then: (resolve: (value: { data: Ref<T | null>, error: Ref<unknown> }) => void) => Promise<void>
+}
+export declare interface FetchBuilder<T = unknown> {
+  get: () => FetchBuilder<T>
+  post: (body?: string) => FetchBuilder<T>
+  patch: (body?: string) => FetchBuilder<T>
+  put: (body?: string) => FetchBuilder<T>
+  delete: () => FetchBuilder<T>
+  json: () => UseFetchResult<T>
+}

package/dist/useFetch.js

@@ -0,0 +1,61 @@
+import { ref } from "@stacksjs/stx";
+export function useFetch(url) {
+  let method = "GET", body;
+  const builder = {
+    get() {
+      method = "GET";
+      body = void 0;
+      return builder;
+    },
+    post(b) {
+      method = "POST";
+      body = b;
+      return builder;
+    },
+    patch(b) {
+      method = "PATCH";
+      body = b;
+      return builder;
+    },
+    put(b) {
+      method = "PUT";
+      body = b;
+      return builder;
+    },
+    delete() {
+      method = "DELETE";
+      body = void 0;
+      return builder;
+    },
+    json() {
+      const data = ref(null), error = ref(null), isFetching = ref(!0), init = {
+        method,
+        headers: { Accept: "application/json" }
+      };
+      if (body && method !== "GET" && method !== "DELETE") {
+        init.headers = { ...init.headers, "Content-Type": "application/json" };
+        init.body = body;
+      }
+      const result = { data, error }, fetchPromise = fetch(url, init).then(async (response) => {
+        const json = await response.json();
+        if (response.ok)
+          data.value = json;
+        else
+          error.value = json;
+      }).catch((e) => {
+        error.value = e;
+      }).finally(() => {
+        isFetching.value = !1;
+      });
+      return {
+        data,
+        error,
+        isFetching,
+        then(resolve) {
+          return fetchPromise.then(() => resolve(result));
+        }
+      };
+    }
+  };
+  return builder;
+}

package/dist/useFileDialog.d.ts

@@ -0,0 +1,15 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Open a file selection dialog programmatically.
+ */
+export declare function useFileDialog(options?: UseFileDialogOptions): UseFileDialogReturn;
+export declare interface UseFileDialogOptions {
+  accept?: string
+  multiple?: boolean
+  capture?: string
+}
+export declare interface UseFileDialogReturn {
+  files: Ref<FileList | null>
+  open: (options?: UseFileDialogOptions) => void
+  reset: () => void
+}

package/dist/useFileDialog.js

@@ -0,0 +1,24 @@
+import { ref } from "@stacksjs/stx";
+export function useFileDialog(options = {}) {
+  const files = ref(null);
+  function open(overrideOptions) {
+    if (typeof document > "u")
+      return;
+    const opts = { ...options, ...overrideOptions }, input = document.createElement("input");
+    input.type = "file";
+    if (opts.accept)
+      input.accept = opts.accept;
+    if (opts.multiple)
+      input.multiple = !0;
+    if (opts.capture)
+      input.setAttribute("capture", opts.capture);
+    input.onchange = () => {
+      files.value = input.files;
+    };
+    input.click();
+  }
+  function reset() {
+    files.value = null;
+  }
+  return { files, open, reset };
+}

package/dist/useFocus.d.ts

@@ -0,0 +1,13 @@
+import type { MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive element focus state.
+ * Setting `focused.value = true` will focus the element, and vice versa.
+ */
+export declare function useFocus(target: MaybeRef<HTMLElement | null | undefined>, options?: UseFocusOptions): UseFocusReturn;
+export declare interface UseFocusOptions {
+  initialValue?: boolean
+}
+export declare interface UseFocusReturn {
+  focused: Ref<boolean>
+}

package/dist/useFocus.js

@@ -0,0 +1,42 @@
+import { onUnmounted, ref, watch } from "@stacksjs/stx";
+import { unref } from "./_shared";
+export function useFocus(target, options = {}) {
+  const { initialValue = !1 } = options, focused = ref(initialValue);
+  let cleanup = () => {};
+  function setup(el) {
+    cleanup();
+    if (!el)
+      return;
+    const onFocus = () => {
+      focused.value = !0;
+    }, onBlur = () => {
+      focused.value = !1;
+    };
+    el.addEventListener("focus", onFocus, { passive: !0 });
+    el.addEventListener("blur", onBlur, { passive: !0 });
+    cleanup = () => {
+      el.removeEventListener("focus", onFocus);
+      el.removeEventListener("blur", onBlur);
+      cleanup = () => {};
+    };
+    if (document.activeElement === el)
+      focused.value = !0;
+    if (initialValue)
+      el.focus();
+  }
+  const el = unref(target);
+  setup(el);
+  watch(focused, (val) => {
+    const element = unref(target);
+    if (!element)
+      return;
+    if (val)
+      element.focus();
+    else
+      element.blur();
+  });
+  try {
+    onUnmounted(() => cleanup());
+  } catch {}
+  return { focused };
+}

package/dist/useFocusWithin.d.ts

@@ -0,0 +1,9 @@
+import type { MaybeRef } from './_shared';
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive state of whether focus is contained within the target element.
+ *
+ * @param target - The target element or a ref to one
+ * @returns focused - true when focus is within the element or its descendants
+ */
+export declare function useFocusWithin(target: MaybeRef<HTMLElement | null | undefined>): { focused: Ref<boolean> };

package/dist/useFocusWithin.js

@@ -0,0 +1,29 @@
+import { onUnmounted, ref } from "@stacksjs/stx";
+import { unref } from "./_shared";
+export function useFocusWithin(target) {
+  const focused = ref(!1);
+  let cleanup = () => {};
+  function setup(el) {
+    cleanup();
+    if (!el)
+      return;
+    const onFocusIn = () => {
+      focused.value = !0;
+    }, onFocusOut = (e) => {
+      if (!el.contains(e.relatedTarget))
+        focused.value = !1;
+    };
+    el.addEventListener("focusin", onFocusIn, { passive: !0 });
+    el.addEventListener("focusout", onFocusOut);
+    cleanup = () => {
+      el.removeEventListener("focusin", onFocusIn);
+      el.removeEventListener("focusout", onFocusOut);
+      cleanup = () => {};
+    };
+  }
+  setup(unref(target));
+  try {
+    onUnmounted(() => cleanup());
+  } catch {}
+  return { focused };
+}

package/dist/useForm.d.ts

@@ -0,0 +1,97 @@
+import type { Ref } from '@stacksjs/stx';
+/**
+ * Reactive form primitive with schema validation + submit orchestration.
+ *
+ * @example
+ * ```ts
+ * const form = useForm({
+ *   initialValues: { email: '', password: '' },
+ *   schema: {
+ *     email: schema.string().email().required(),
+ *     password: schema.string().min(6).required(),
+ *   },
+ *   onSubmit: async (values) => {
+ *     const r = await authStore.login(values)
+ *     if (!r.ok) form.setError('form', r.error)
+ *   },
+ * })
+ * ```
+ */
+export declare function useForm<TValues extends Record<string, unknown>>(opts: UseFormOptions<TValues>): UseFormResult<TValues>;
+/**
+ * useForm (stacksjs/stacks#1940 — Phase 1).
+ *
+ * Per-field state + schema validation + submit orchestration.
+ * Builds on `@stacksjs/validation`'s ts-validation surface — pass any
+ * field-keyed bag of `schema.string()...` etc. and the composable
+ * runs `.validate(value)` to surface the first message.
+ *
+ * Phase 1 deliberately ships the primitive only; the `<Field>` /
+ * `<SubmitButton>` / `<ErrorMessage>` companion components, field
+ * arrays, server-error auto-surfacing on 422, and progressive HTML
+ * fallback are scoped to Phases 2-5 of the issue.
+ */
+/** Minimal Validator surface this composable depends on. */
+export declare interface FormValidator {
+  validate: (value: unknown) => { valid: boolean, errors: Array<{ message: string }> | Record<string, Array<{ message: string }>> }
+}
+export declare interface UseFormOptions<TValues extends Record<string, unknown>> {
+  initialValues: TValues
+  schema?: Partial<Record<keyof TValues, FormValidator>>
+  onSubmit: (values: TValues) => Promise<void> | void
+  onError?: (error: Error | Record<string, string>) => void
+  validateOn?: ValidationMode
+}
+/**
+ * A ready-to-spread bag of input attributes + handlers for one field
+ * (stacksjs/stacks#1940 Phase 2). Encodes the a11y wiring a `<Field>`
+ * component would otherwise re-derive by hand: `aria-invalid` flips on a
+ * surfaced error, and `aria-describedby` points at the error element's
+ * stable id so screen readers announce the message.
+ */
+export declare interface FieldInputProps<T> {
+  name: string
+  value: T
+  onInput: (eventOrValue: unknown) => void
+  onBlur: () => void
+  'aria-invalid': boolean
+  'aria-describedby': string | undefined
+}
+export declare interface FormFieldAccessor<T> {
+  value: T
+  error: string
+  touched: boolean
+  dirty: boolean
+  errorId: string
+  setValue: (next: T) => void
+  onBlur: () => void
+  validate: () => boolean
+  inputProps: () => FieldInputProps<T>
+}
+export declare interface UseFormResult<TValues extends Record<string, unknown>> {
+  values: Ref<TValues>
+  errors: Ref<Record<string, string>>
+  touched: Ref<Record<string, boolean>>
+  dirty: Ref<Record<string, boolean>>
+  isSubmitting: Ref<boolean>
+  isValid: Ref<boolean>
+  isDirty: Ref<boolean>
+  field: <K extends keyof TValues>(name: K) => FormFieldAccessor<TValues[K]>
+  setValue: <K extends keyof TValues>(name: K, value: TValues[K]) => void
+  setError: (name: keyof TValues | 'form', message: string) => void
+  setErrors: (errorMap: Partial<Record<keyof TValues | 'form', string | string[]>>) => void
+  clearErrors: (name?: keyof TValues | 'form') => void
+  setTouched: (name: keyof TValues, touched?: boolean) => void
+  validate: () => boolean
+  handleSubmit: () => Promise<void>
+  reset: () => void
+  submitButtonProps: () => { type: 'submit', disabled: boolean, 'aria-busy': boolean }
+  firstErrorField: () => keyof TValues | null
+}
+/**
+ * Trigger that causes a field to validate.
+ * - 'change' — every time the value changes (eager — best for password strength meters)
+ * - 'blur'   — when the user moves focus away from the field (default — most natural)
+ * - 'submit' — only at submit time (lazy — best for short forms with required-only checks)
+ */
+export type ValidationMode = 'change' | 'blur' | 'submit';