pxd 0.0.64 → 0.1.2

package/dist/composables/index.js

@@ -1,4 +1,4 @@
-export * from "./use-browser-observer.js";
+export * from "./use-backoff-retry.js";
 export * from "./use-client-online.js";
 export * from "./use-color-scheme.js";
 export * from "./use-copy-click.js";
@@ -7,20 +7,17 @@ export * from "./use-deferred-value.js";
 export * from "./use-delay-change.js";
 export * from "./use-delay-destroy.js";
 export * from "./use-document-hidden.js";
-export * from "./use-focus-trap.js";
-export * from "./use-forward-ref-expose.js";
-export * from "./use-list-filter.js";
-export * from "./use-list-navigation.js";
+export * from "./use-intersection-observer.js";
 export * from "./use-loading-bar.js";
-export * from "./use-lock-scroll.js";
 export * from "./use-media-query.js";
 export * from "./use-message.js";
-export * from "./use-model-value.js";
+export * from "./use-mutation-observer.js";
 export * from "./use-outside-click.js";
-export * from "./use-overlay-manager.js";
-export * from "./use-popover-responsive.js";
 export * from "./use-repeat-action.js";
-export * from "./use-swipe-gesture.js";
+export * from "./use-resize-observer.js";
+export * from "./use-scrollspy.js";
+export * from "./use-stick-to-bottom.js";
 export * from "./use-toggle-value.js";
+export * from "./use-view-transition.js";
 export * from "./use-virtual-list.js";
 export * from "./use-window-size.js";

package/dist/composables/use-backoff-retry.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Exponential backoff retry configuration.
+ */
+export interface BackoffRetryConfig {
+    /** Maximum number of retries. @default 3 */
+    maxRetries?: number;
+    /** Base delay in milliseconds. @default 500 */
+    baseDelay?: number;
+    /** Maximum delay cap in milliseconds. @default 10000 */
+    maxDelay?: number;
+    /** AbortSignal used to cancel in-flight work and backoff waits. */
+    signal?: AbortSignal;
+    /**
+     * Decide whether an error is worth retrying.
+     * Return `true` to retry (e.g. 429, 5xx, network errors),
+     * or `false` to rethrow immediately.
+     *
+     * Note: native `fetch` does not reject on 4xx/5xx. Callers must check
+     * `response.ok` / status and throw for status-based rules to apply.
+     */
+    retryable?: (error: unknown) => boolean;
+    /** Called before each retry wait; useful for logging / metrics. */
+    onRetry?: (attempt: number, delay: number, error: unknown) => void;
+}
+/**
+ * Default retryable-error rules.
+ */
+export declare function isRetryableError(error: unknown): boolean;
+export interface UseBackoffRetryReturn {
+    signal: AbortSignal;
+    abort: (reason?: any) => void;
+    retry: <T>(fn: (signal: AbortSignal) => Promise<T>, config?: BackoffRetryConfig) => Promise<T>;
+}
+/**
+ * Exponential backoff retry helper scoped to the current effect scope.
+ *
+ * - Exponential backoff with full jitter
+ * - Maximum delay cap
+ * - Customizable retryable-error predicate
+ * - AbortSignal applies to both `fn(signal)` and backoff waits
+ * - Auto-aborts on scope dispose; exhausted errors get an `attempts` property
+ *
+ * @example
+ * const { retry } = useBackoffRetry({ maxRetries: 3, baseDelay: 500 })
+ * await retry(async (signal) => {
+ *   const res = await fetch('https://api.example.com', { signal })
+ *   if (!res.ok) throw Object.assign(new Error(res.statusText), { status: res.status })
+ *   return res.json()
+ * })
+ */
+export declare function useBackoffRetry(defaultConfig?: BackoffRetryConfig): UseBackoffRetryReturn;

package/dist/composables/use-backoff-retry.js

@@ -0,0 +1,116 @@
+import { onScopeDispose } from "vue";
+const NETWORK_ERROR_CODES = /* @__PURE__ */ new Set([
+  "ECONNRESET",
+  "ETIMEDOUT",
+  "ENOTFOUND",
+  "ECONNABORTED",
+  "EAI_AGAIN"
+]);
+export function isRetryableError(error) {
+  if (typeof error !== "object" || error === null) {
+    return false;
+  }
+  const err = error;
+  const status = err.status ?? err.statusCode ?? err.response?.status;
+  if (typeof status === "number") {
+    return status === 429 || status === 408 || status >= 500 && status < 600;
+  }
+  const seen = /* @__PURE__ */ new WeakSet();
+  for (let e = err; e && typeof e === "object"; e = e.cause) {
+    if (seen.has(e)) {
+      break;
+    }
+    seen.add(e);
+    if (typeof e.code === "string" && NETWORK_ERROR_CODES.has(e.code)) {
+      return true;
+    }
+  }
+  if (err.code === "ERR_NETWORK" || err.code === "ERR_BAD_RESPONSE") {
+    return true;
+  }
+  const msg = typeof err.message === "string" ? err.message : "";
+  if (err instanceof TypeError && /failed to fetch|networkerror|network error|load failed/i.test(msg)) {
+    return true;
+  }
+  return false;
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort);
+  });
+}
+function attachAttempts(error, attempts) {
+  if (error instanceof Error) {
+    ;
+    error.attempts = attempts;
+    return;
+  }
+  if (error !== null && typeof error === "object") {
+    ;
+    error.attempts = attempts;
+  }
+}
+async function withBackoffRetry(fn, config = {}) {
+  const { baseDelay = 500, maxDelay = 1e4, retryable = isRetryableError, onRetry } = config;
+  const maxRetries = Math.max(0, config.maxRetries ?? 3);
+  const signal = config.signal ?? new AbortController().signal;
+  let lastError;
+  let attempts = 0;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    signal.throwIfAborted();
+    try {
+      return await fn(signal);
+    } catch (error) {
+      lastError = error;
+      attempts = attempt + 1;
+      if (attempt === maxRetries) {
+        break;
+      }
+      if (!retryable(error)) {
+        throw error;
+      }
+      const exponential = Math.min(baseDelay * 2 ** attempt, maxDelay);
+      const delay = Math.round(Math.random() * exponential);
+      try {
+        onRetry?.(attempt + 1, delay, error);
+      } catch {
+      }
+      await sleep(delay, signal);
+    }
+  }
+  attachAttempts(lastError, attempts);
+  throw lastError;
+}
+export function useBackoffRetry(defaultConfig = {}) {
+  const controller = new AbortController();
+  onScopeDispose(() => {
+    controller.abort();
+  });
+  function abort(reason) {
+    controller.abort(reason);
+  }
+  function retry(fn, config = {}) {
+    return withBackoffRetry(fn, {
+      ...defaultConfig,
+      ...config,
+      signal: config.signal ?? defaultConfig.signal ?? controller.signal
+    });
+  }
+  return {
+    retry,
+    abort,
+    signal: controller.signal
+  };
+}

package/dist/composables/use-color-scheme.js

@@ -1,15 +1,15 @@
 import { computed, onScopeDispose, shallowRef, watchEffect } from "vue";
 import { cachedOn } from "../utils/event.js";
+import { getUniqueId } from "../utils/helper.js";
 import { isServer } from "../utils/is.js";
 import { PRESET_MEDIA_QUERIES, useMediaQuery } from "./use-media-query.js";
 export function useColorScheme(options = {}) {
-  const RANDOM_KEY = Math.random();
+  const uniqueId = getUniqueId();
   const EVENT_NAME = "#toggle-color-scheme";
   const STORAGE_KEY = "fe.system.color-scheme";
   const colorScheme = shallowRef("auto");
   const preferredDark = useMediaQuery(PRESET_MEDIA_QUERIES.COLOR_SCHEME_DARK);
-  let removeStyleTimer = null;
-  let disableTransitionStyleEl = null;
+  const styleHandles = { removeStyleTimer: null, disableTransitionStyleEl: null };
   const DISABLE_TRANSITION_CSS = `*,*::before,*::after{-webkit-transition:none!important;-moz-transition:none!important;-o-transition:none!important;-ms-transition:none!important;transition:none!important}`;
   const isDark = computed(() => {
     if (colorScheme.value === "dark") {
@@ -24,38 +24,41 @@ export function useColorScheme(options = {}) {
     localStorage.setItem(STORAGE_KEY, colorScheme.value);
   }
   function createDisableTransitionStyle() {
-    if (removeStyleTimer) {
-      clearTimeout(removeStyleTimer);
-      removeStyleTimer = null;
+    if (styleHandles.removeStyleTimer) {
+      clearTimeout(styleHandles.removeStyleTimer);
+      styleHandles.removeStyleTimer = null;
     }
-    if (!disableTransitionStyleEl) {
-      disableTransitionStyleEl = document.createElement("style");
-      disableTransitionStyleEl.appendChild(document.createTextNode(DISABLE_TRANSITION_CSS));
+    if (!styleHandles.disableTransitionStyleEl) {
+      const styleEl = document.createElement("style");
+      styleEl.appendChild(document.createTextNode(DISABLE_TRANSITION_CSS));
+      styleHandles.disableTransitionStyleEl = styleEl;
     }
-    if (disableTransitionStyleEl.parentElement !== document.head) {
-      document.head.appendChild(disableTransitionStyleEl);
+    if (styleHandles.disableTransitionStyleEl.parentElement !== document.head) {
+      document.head.appendChild(styleHandles.disableTransitionStyleEl);
     }
   }
   function removeDisableTransitionStyle() {
-    if (removeStyleTimer) {
-      clearTimeout(removeStyleTimer);
+    if (styleHandles.removeStyleTimer) {
+      clearTimeout(styleHandles.removeStyleTimer);
     }
-    removeStyleTimer = setTimeout(() => {
-      if (disableTransitionStyleEl && disableTransitionStyleEl.parentElement === document.head) {
-        document.head.removeChild(disableTransitionStyleEl);
+    styleHandles.removeStyleTimer = setTimeout(() => {
+      const styleEl = styleHandles.disableTransitionStyleEl;
+      if (styleEl && styleEl.parentElement === document.head) {
+        document.head.removeChild(styleEl);
       }
-      removeStyleTimer = null;
+      styleHandles.removeStyleTimer = null;
     }, 0);
   }
   function cleanupStyleElements() {
-    if (removeStyleTimer) {
-      clearTimeout(removeStyleTimer);
-      removeStyleTimer = null;
+    if (styleHandles.removeStyleTimer) {
+      clearTimeout(styleHandles.removeStyleTimer);
+      styleHandles.removeStyleTimer = null;
     }
-    if (disableTransitionStyleEl && disableTransitionStyleEl.parentElement === document.head) {
-      document.head.removeChild(disableTransitionStyleEl);
+    const styleEl = styleHandles.disableTransitionStyleEl;
+    if (styleEl && styleEl.parentElement === document.head) {
+      document.head.removeChild(styleEl);
     }
-    disableTransitionStyleEl = null;
+    styleHandles.disableTransitionStyleEl = null;
   }
   function toggleDarkMode() {
     createDisableTransitionStyle();
@@ -67,12 +70,12 @@ export function useColorScheme(options = {}) {
     updateStorages();
     removeDisableTransitionStyle();
     if (options.syncStatus) {
-      const payload = { id: RANDOM_KEY, mode: colorScheme.value };
+      const payload = { id: uniqueId, mode: colorScheme.value };
       window.dispatchEvent(new CustomEvent(EVENT_NAME, { detail: payload }));
     }
   }
   function onToggleModeType({ detail }) {
-    if (detail.id === RANDOM_KEY) {
+    if (detail.id === uniqueId) {
       return;
     }
     colorScheme.value = detail.mode;

package/dist/composables/use-copy-click.d.ts

@@ -1,4 +1,5 @@
+import type { Nullable } from '../types/shared/utils';
 export declare function useCopyClick(): {
     isCopied: import("vue").ShallowRef<boolean, boolean>;
-    copyText: (text?: string | undefined) => Promise<void>;
+    copyText: (text?: Nullable<string>) => Promise<void>;
 };

package/dist/composables/use-copy-click.js

@@ -1,38 +1,41 @@
-import { shallowRef } from "vue";
+import { onScopeDispose, shallowRef } from "vue";
+import { withResolvers } from "../utils/helper.js";
 import { isServer } from "../utils/is.js";
 export function useCopyClick() {
   let copiedTimer;
-  let copyPromise = null;
+  let copyResolvers = null;
   const isCopied = shallowRef(false);
   async function copyText(text = "") {
-    if (isServer()) {
+    if (isServer() || !text) {
       return;
     }
-    if (copyPromise) {
-      return copyPromise;
-    }
     try {
       await navigator.clipboard.writeText(text);
     } catch {
-      legacyCopyText(text);
+      copyTextCompat(text);
+    }
+    if (!copyResolvers) {
+      copyResolvers = withResolvers();
+      copyResolvers.resolve();
     }
-    copyPromise = new Promise((resolve) => {
-      isCopied.value = true;
-      resolve();
-      clearTimeout(copiedTimer);
-      copiedTimer = setTimeout(() => {
-        isCopied.value = false;
-        copyPromise = null;
-      }, 1500);
-    });
-    return copyPromise;
+    isCopied.value = true;
+    clearTimeout(copiedTimer);
+    copiedTimer = setTimeout(() => {
+      isCopied.value = false;
+      copyResolvers = null;
+    }, 1500);
+    return copyResolvers.promise;
   }
+  onScopeDispose(() => {
+    clearTimeout(copiedTimer);
+    copyResolvers = null;
+  });
   return {
     isCopied,
     copyText
   };
 }
-function legacyCopyText(text) {
+function copyTextCompat(text) {
   const textarea = document.createElement("textarea");
   textarea.value = text;
   document.body.appendChild(textarea);

package/dist/composables/use-countdown.d.ts

@@ -1,53 +1,44 @@
 import type { EmitFn, Ref } from 'vue';
 export interface CountdownOptions {
     /**
-     * 是否启用正计时
      * Whether to enable count up mode.
      * @default false
      */
     invert?: boolean;
     /**
-     * 是否激活
      * Whether the countdown is active.
      * @default false
      */
     active?: boolean;
     /**
-     * 开始时间于
      * The start time of the countdown.
      */
     startAt?: number;
     /**
-     * 结束时间
      * The end time of the countdown.
      */
     endTime?: number;
     /**
-     * 是否自动重置
      * Whether to automatically reset.
      * @default true
      */
     autoReset?: boolean;
     /**
-     * 倒计时时间
      * The duration of the countdown.
      * @default 0
      */
     durations?: number;
     /**
-     * 精度
      * The precision of the countdown.
      * @default 0
      */
     precision?: number;
     /**
-     * 是否使用毫秒
      * Whether the time stamp is in milliseconds.
      * @default true
      */
     millisecond?: boolean;
     /**
-     * 是否启用人性化时间显示（向上取整到秒）
      * Whether to enable human-friendly time display (ceil to seconds).
      * @default false
      */

package/dist/composables/use-countdown.js

@@ -1,11 +1,12 @@
-import { computed, shallowRef, watch } from "vue";
-import { raf } from "../utils/event.js";
+import { computed, onScopeDispose, shallowRef, watch } from "vue";
+import { caf, raf } from "../utils/event.js";
 const UPDATE_INTERVAL = 100;
 export function useCountdown(props, emits) {
   let startTimestamp = -1;
   let isFinished = false;
   let isPaused = false;
   let previousFrameTime = 0;
+  let rafId = 0;
   const timeRef = shallowRef(0);
   const totalDuration = computed(() => {
     const { endTime, durations } = props;
@@ -81,7 +82,8 @@ export function useCountdown(props, emits) {
       }
     }
     if (now - previousFrameTime < UPDATE_INTERVAL && !isLastFrame) {
-      raf(frame);
+      caf(rafId);
+      rafId = raf(frame);
       return;
     }
     previousFrameTime = now;
@@ -94,7 +96,8 @@ export function useCountdown(props, emits) {
     } else {
       timeRef.value = Math.max(0, current);
     }
-    raf(frame);
+    caf(rafId);
+    rafId = raf(frame);
   }
   const unwatchActive = watch(
     () => props.active,
@@ -132,9 +135,14 @@ export function useCountdown(props, emits) {
     { immediate: true }
   );
   function stop() {
+    caf(rafId);
+    rafId = 0;
     unwatchTimes();
     unwatchActive();
   }
+  onScopeDispose(() => {
+    stop();
+  });
   return {
     stop,
     reset,

package/dist/composables/use-deferred-value.js

@@ -1,5 +1,5 @@
 import { onScopeDispose, ref, watch } from "vue";
-import { toValue } from "../utils/ref.js";
+import { toValue } from "../utils/helper.js";
 export function useDeferredValue(defaultValue, options = {}) {
   const { deep, delay = 300, valueChange } = options;
   const syncValue = ref(toValue(defaultValue));

package/dist/composables/use-delay-change.js

@@ -1,8 +1,9 @@
-import { shallowRef } from "vue";
+import { onScopeDispose, shallowRef } from "vue";
+import { toValue } from "../utils/helper.js";
 export function useDelayChange(value, options = {}) {
   const { delay = 300, valueChange } = options;
   let timerId;
-  const delayValue = shallowRef(value);
+  const delayValue = shallowRef(toValue(value));
   function setValue(newValue, immediate = false) {
     clearTimeout(timerId);
     if (immediate) {
@@ -15,6 +16,9 @@ export function useDelayChange(value, options = {}) {
       valueChange?.(delayValue.value);
     }, delay);
   }
+  onScopeDispose(() => {
+    clearTimeout(timerId);
+  });
   return {
     value: delayValue,
     setValue

package/dist/composables/use-delay-destroy.d.ts

@@ -1,7 +1,7 @@
 import type { Nullable } from '../types/shared';
 import type { MaybeRefOrGetter, Ref } from 'vue';
 interface Options {
-    delay?: number;
+    delay?: MaybeRefOrGetter<number>;
     renderChange?: (v: boolean) => void;
     visibleChange?: (v: boolean) => void;
 }

package/dist/composables/use-delay-destroy.js

@@ -1,12 +1,15 @@
-import { shallowRef } from "vue";
+import { onScopeDispose, shallowRef } from "vue";
 import { doubleRaf, caf } from "../utils/event.js";
-import { toValue } from "../utils/ref.js";
+import { toValue } from "../utils/helper.js";
 export function useDelayDestroy(value, options = {}) {
-  const { delay = 300, renderChange, visibleChange } = options;
+  const { delay, renderChange, visibleChange } = options;
   const render = shallowRef(toValue(value));
   const visible = shallowRef(toValue(value));
   let destroyTimeoutId;
   let visibleRafId = 0;
+  function getDelay() {
+    return toValue(delay) ?? 1e3;
+  }
   async function show() {
     return new Promise((resolve) => {
       clearTimeout(destroyTimeoutId);
@@ -35,16 +38,20 @@ export function useDelayDestroy(value, options = {}) {
         visible.value = false;
         visibleChange?.(visible.value);
       }
-      if (render.value) {
-        clearTimeout(destroyTimeoutId);
-        destroyTimeoutId = setTimeout(() => {
+      clearTimeout(destroyTimeoutId);
+      destroyTimeoutId = setTimeout(() => {
+        if (render.value) {
           render.value = false;
-          resolve(render.value);
           renderChange?.(render.value);
-        }, delay);
-      }
+        }
+        resolve(render.value);
+      }, getDelay());
     });
   }
+  onScopeDispose(() => {
+    clearTimeout(destroyTimeoutId);
+    caf(visibleRafId);
+  });
   return {
     show,
     hide,

package/dist/composables/use-intersection-observer.d.ts

@@ -0,0 +1,6 @@
+import type { ObserverResults, TargetRef } from '../utils/observer.js';
+import type { MaybeRefOrGetter } from 'vue';
+export declare const useIntersectionObserver: (target: TargetRef, callback: (items: Array<{
+    entry: IntersectionObserverEntry;
+    target: HTMLElement;
+}>) => void, options?: MaybeRefOrGetter<IntersectionObserverInit>) => ObserverResults<IntersectionObserver>;

package/dist/composables/use-intersection-observer.js

@@ -0,0 +1,38 @@
+import { isServer } from "../utils/is.js";
+import { createObserver } from "../utils/observer.js";
+const rootIds = /* @__PURE__ */ new WeakMap();
+let rootFallbackId = 0;
+function getRootId(root) {
+  if (!root) {
+    return "null";
+  }
+  let id = rootIds.get(root);
+  if (id === void 0) {
+    rootIds.set(root, id = rootFallbackId++);
+  }
+  return String(id);
+}
+function normalize(options) {
+  if (!options) {
+    return "null|0px|0";
+  }
+  const threshold = Array.isArray(options.threshold) ? [...options.threshold].sort((a, b) => a - b).join(",") : String(options.threshold ?? 0);
+  return `${getRootId(options.root)}|${options.rootMargin ?? "0px"}|${threshold}`;
+}
+const spec = {
+  normalize,
+  create(callback, options) {
+    if (isServer() || typeof globalThis.IntersectionObserver === "undefined") {
+      return void 0;
+    }
+    return new globalThis.IntersectionObserver(callback, options);
+  },
+  sync(observer, prev, next) {
+    prev.filter((el) => !next.includes(el)).forEach((el) => observer.unobserve(el));
+    next.filter((el) => !prev.includes(el)).forEach((el) => observer.observe(el));
+  },
+  resolveTarget: (entry) => entry.target,
+  pooled: true
+};
+const observerWrapper = createObserver(spec);
+export const useIntersectionObserver = (target, callback, options) => observerWrapper(target, callback, options);

package/dist/composables/use-media-query.d.ts

@@ -1,8 +1,5 @@
 import type { Ref } from 'vue';
 export declare const PRESET_MEDIA_QUERIES: {
-    MOTION_NO_PREFERENCE: string;
-    MOTION_NO_REDUCE: string;
-    MOTION_REDUCE: string;
     COLOR_SCHEME_DARK: string;
     COLOR_SCHEME_LIGHT: string;
     COLOR_SCHEME_NO_PREFERENCE: string;