@vizejs/composable 0.426.3 → 0.428.0

package/registry/files/ref-auto-reset.ts

@@ -0,0 +1,102 @@
+import { customRef, toValue } from "vue";
+import type { MaybeRefOrGetter, Ref } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+import type { TimeoutScheduler } from "./timeout-scheduler.ts";
+
+/** Options for {@link refAutoReset}. */
+export interface RefAutoResetOptions {
+  /**
+   * Applies the reset timer when no browser `window` is available. When
+   * disabled, written values persist on the server (a render is a snapshot).
+   *
+   * @default false
+   */
+  readonly runOnServer?: boolean;
+
+  /**
+   * Owns the reset timer.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+}
+
+const defaultScheduler: TimeoutScheduler = {
+  setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+  clearTimeout: (handle) => {
+    globalThis.clearTimeout(handle as ReturnType<typeof setTimeout>);
+  },
+};
+
+function resolveResetMs(value: number): number {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_REF_AUTO_RESET_INVALID_DELAY] afterMs must be finite and at least zero; received ${String(value)}`,
+    );
+  }
+  return Math.trunc(value);
+}
+
+/**
+ * Writable ref that falls back to a default value `afterMs` milliseconds
+ * after each write.
+ *
+ * Typical for transient UI state such as "Copied!" labels. Every write
+ * restarts the timer; the default (itself possibly reactive) is read when the
+ * reset happens, and the ref reads the current default until the first write.
+ * The pending reset is cancelled when the owning reactive scope stops.
+ * Without a browser `window` (and without `runOnServer`) no timer starts.
+ *
+ * @example
+ * ```ts
+ * const message = refAutoReset("", 2_000);
+ * message.value = "Copied!"; // back to "" after two seconds
+ * ```
+ *
+ * @param defaultValue Reactive value restored after the delay.
+ * @param afterMs Reactive delay in milliseconds, finite and at least zero.
+ * @param options Server and scheduler policy.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_REF_AUTO_RESET_INVALID_DELAY` for
+ * invalid delays, synchronously at creation and on every write.
+ * @returns A writable ref.
+ */
+export function refAutoReset<Value>(
+  defaultValue: MaybeRefOrGetter<Value>,
+  afterMs: MaybeRefOrGetter<number>,
+  options: RefAutoResetOptions = {},
+): Ref<Value> {
+  const scheduler = options.scheduler ?? defaultScheduler;
+  resolveResetMs(toValue(afterMs));
+  let handle: unknown;
+  let written = false;
+  let current = toValue(defaultValue);
+
+  const cancel = (): void => {
+    if (handle !== undefined) scheduler.clearTimeout(handle);
+    handle = undefined;
+  };
+
+  tryOnScopeDispose(cancel);
+
+  return customRef<Value>((track, trigger) => ({
+    get: () => {
+      track();
+      return written ? current : toValue(defaultValue);
+    },
+    set: (next) => {
+      const delay = resolveResetMs(toValue(afterMs));
+      current = next;
+      written = true;
+      trigger();
+      cancel();
+      if (typeof window === "undefined" && !(options.runOnServer ?? false)) return;
+      handle = scheduler.setTimeout(() => {
+        handle = undefined;
+        written = false;
+        trigger();
+      }, delay);
+    },
+  }));
+}

package/registry/files/ref-debounced.ts

@@ -0,0 +1,34 @@
+import type { MaybeRefOrGetter, ShallowRef } from "vue";
+
+import { useDebounced } from "./use-debounced.ts";
+import type { UseDebouncedOptions } from "./use-debounced.ts";
+
+/**
+ * Readonly ref that follows `source` after it stayed quiet for `waitMs`.
+ *
+ * Shorthand for `useDebounced(source, waitMs, options).debounced` when the
+ * pending flag and cancel/flush controls are not needed. Inherits every rule
+ * of {@link useDebounced}: synchronous mirroring on the server, reactive
+ * wait, and scope-bound cleanup.
+ *
+ * @example
+ * ```ts
+ * const query = ref("");
+ * const debouncedQuery = refDebounced(query, 300);
+ * ```
+ *
+ * @param source Reactive source.
+ * @param waitMs Reactive quiet period in milliseconds.
+ * @param options Server and scheduler policy.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_DEBOUNCE_INVALID_WAIT` for invalid
+ * waits (see {@link useDebounced}).
+ * @returns The debounced readonly ref.
+ */
+export function refDebounced<Value>(
+  source: MaybeRefOrGetter<Value>,
+  waitMs: MaybeRefOrGetter<number>,
+  options: UseDebouncedOptions = {},
+): Readonly<ShallowRef<Value>> {
+  return useDebounced(source, waitMs, options).debounced;
+}

package/registry/files/ref-default.ts

@@ -0,0 +1,35 @@
+import { computed, toValue } from "vue";
+import type { MaybeRefOrGetter, Ref, WritableComputedRef } from "vue";
+
+/**
+ * View a nullable ref through a default value.
+ *
+ * Reads return the source value, or the (possibly reactive) default while the
+ * source holds `null` or `undefined`, so the read type drops those members.
+ * Writes go straight to the source and accept its full type, including
+ * `null`/`undefined` to fall back to the default again. Pure derived state:
+ * SSR-safe and nothing to dispose.
+ *
+ * @example
+ * ```ts
+ * const raw = ref<string | undefined>();
+ * const name = refDefault(raw, "Anonymous");
+ * name.value; // "Anonymous"
+ * name.value = "Ada"; // raw.value === "Ada"
+ * ```
+ *
+ * @param source Writable nullable ref.
+ * @param defaultValue Reactive fallback.
+ * @returns A writable computed ref whose reads never yield `null`/`undefined`.
+ */
+export function refDefault<Value>(
+  source: Ref<Value>,
+  defaultValue: MaybeRefOrGetter<NonNullable<Value>>,
+): WritableComputedRef<NonNullable<Value>, Value> {
+  return computed<NonNullable<Value>, Value>({
+    get: () => source.value ?? toValue(defaultValue),
+    set: (value) => {
+      source.value = value;
+    },
+  });
+}

package/registry/files/resize-observer.ts

@@ -0,0 +1,220 @@
+import {
+  computed,
+  hasInjectionContext,
+  readonly,
+  ref,
+  shallowRef,
+  toValue,
+  watch,
+  watchPostEffect,
+} from "vue";
+import type { MaybeRefOrGetter, Ref, WatchHandle } from "vue";
+
+import { resolveElement, resolveElements } from "./element-target.ts";
+import type { MaybeElementTarget, MaybeElementTargets } from "./element-target.ts";
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Runtime capability that supplies the `ResizeObserver` constructor. */
+export interface ResizeObserverHost {
+  /** `ResizeObserver` constructor, absent in unsupported runtimes. */
+  readonly ResizeObserver?: new (callback: ResizeObserverCallback) => ResizeObserver;
+}
+
+/** Options for {@link useResizeObserver}. */
+export interface UseResizeObserverOptions {
+  /**
+   * Box model reported by the observer.
+   *
+   * @default "content-box"
+   */
+  readonly box?: ResizeObserverBoxOptions;
+
+  /**
+   * Reactive constructor capability for alternate runtimes and tests.
+   *
+   * @default window when it provides `ResizeObserver`
+   */
+  readonly host?: MaybeRefOrGetter<ResizeObserverHost | null | undefined>;
+
+  /**
+   * Target resolution timing. `"post"` observes template refs after mount.
+   *
+   * @default "post"
+   */
+  readonly flush?: "pre" | "post" | "sync";
+}
+
+/** Controls returned by {@link useResizeObserver}. */
+export interface ResizeObserverControls {
+  /** Whether the host provides `ResizeObserver`. `false` during server rendering. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+
+  /** Disconnect the observer and stop following the reactive targets. Idempotent. */
+  readonly stop: () => void;
+}
+
+/**
+ * Observe size changes of one or more reactive elements.
+ *
+ * A single observer is (re)created whenever the resolved targets, the box
+ * option, or the host change; unresolved targets are skipped. The observer is
+ * disconnected when the owning reactive scope stops or `stop` is called.
+ * During server rendering no host resolves, `isSupported` stays `false`, and
+ * the callback never runs.
+ *
+ * Inside a component the host is read after mounting, so hydration renders
+ * the server fallback first and never mismatches.
+ *
+ * @param targets Reactive element target or list of targets.
+ * @param callback Native `ResizeObserver` callback.
+ * @param options Box model, runtime capability, and watcher timing.
+ * @default options {}
+ * @returns Support flag and stop control.
+ */
+export function useResizeObserver(
+  targets: MaybeElementTargets,
+  callback: ResizeObserverCallback,
+  options: UseResizeObserverOptions = {},
+): ResizeObserverControls {
+  const isSupported = ref(false);
+  // Inside a component the host is attached by a post-flush job (after the
+  // component mounted), so a hydrating client first renders the same server
+  // fallback. Outside components it is attached synchronously.
+  const hydrated = shallowRef(!hasInjectionContext());
+  if (!hydrated.value) {
+    watchPostEffect(() => {
+      hydrated.value = true;
+    });
+  }
+  let stopWatch: WatchHandle | undefined = watch(
+    () =>
+      [
+        hydrated.value
+          ? options.host === undefined
+            ? browserResizeObserverHost()
+            : toValue(options.host)
+          : undefined,
+        resolveElements(targets),
+      ] as const,
+    ([host, elements], _previous, onCleanup) => {
+      const Observer = host?.ResizeObserver;
+      isSupported.value = Observer !== undefined;
+      if (!Observer || elements.length === 0) return;
+      const observer = new Observer(callback);
+      const observeOptions: ResizeObserverOptions = { box: options.box ?? "content-box" };
+      for (const element of elements) observer.observe(element, observeOptions);
+      onCleanup(() => observer.disconnect());
+    },
+    { immediate: true, flush: options.flush ?? "post" },
+  );
+
+  const stop = (): void => {
+    stopWatch?.stop();
+    stopWatch = undefined;
+  };
+  tryOnScopeDispose(stop);
+  return { isSupported: readonly(isSupported), stop };
+}
+
+/** Element dimensions reported by {@link useElementSize}. */
+export interface ElementSize {
+  /** Inline size in CSS pixels. */
+  readonly width: number;
+  /** Block size in CSS pixels. */
+  readonly height: number;
+}
+
+/** Options for {@link useElementSize}. */
+export interface UseElementSizeOptions extends UseResizeObserverOptions {
+  /**
+   * Size exposed before the first observation and during server rendering.
+   * Keep it identical on server and client to avoid hydration mismatches.
+   *
+   * @default { width: 0, height: 0 }
+   */
+  readonly initialSize?: ElementSize;
+}
+
+/** Reactive size returned by {@link useElementSize}. */
+export interface ElementSizeControls extends ResizeObserverControls {
+  /** Observed inline size in CSS pixels. */
+  readonly width: Readonly<Ref<number>>;
+  /** Observed block size in CSS pixels. */
+  readonly height: Readonly<Ref<number>>;
+}
+
+/**
+ * Track the rendered size of a reactive element.
+ *
+ * Reads the requested box from `contentBoxSize`/`borderBoxSize` (summing
+ * fragments) and falls back to `contentRect` for older engines. When the
+ * target unmounts the size resets to the initial value so stale geometry never
+ * leaks into the next render. Server renders expose `initialSize`.
+ *
+ * @param target Reactive element target.
+ * @param options Initial size, box model, capability, and watcher timing.
+ * @default options {}
+ * @returns Reactive width/height plus observer controls.
+ */
+export function useElementSize(
+  target: MaybeElementTarget,
+  options: UseElementSizeOptions = {},
+): ElementSizeControls {
+  const initial = options.initialSize ?? { width: 0, height: 0 };
+  const width = ref(initial.width);
+  const height = ref(initial.height);
+  const box = options.box ?? "content-box";
+
+  const controls = useResizeObserver(
+    target,
+    (entries) => {
+      const entry = entries.at(-1);
+      if (!entry) return;
+      const sizes =
+        box === "border-box"
+          ? entry.borderBoxSize
+          : box === "content-box"
+            ? entry.contentBoxSize
+            : entry.devicePixelContentBoxSize;
+      if (sizes && sizes.length > 0) {
+        let inline = 0;
+        let block = 0;
+        for (const size of sizes) {
+          inline += size.inlineSize;
+          block += size.blockSize;
+        }
+        width.value = inline;
+        height.value = block;
+        return;
+      }
+      width.value = entry.contentRect.width;
+      height.value = entry.contentRect.height;
+    },
+    options,
+  );
+
+  const mounted = computed(() => resolveElement(target) !== null);
+  const stopReset = watch(mounted, (isMounted) => {
+    if (isMounted) return;
+    width.value = initial.width;
+    height.value = initial.height;
+  });
+  const stop = (): void => {
+    stopReset.stop();
+    controls.stop();
+  };
+  tryOnScopeDispose(stop);
+
+  return {
+    width: readonly(width),
+    height: readonly(height),
+    isSupported: controls.isSupported,
+    stop,
+  };
+}
+
+function browserResizeObserverHost(): ResizeObserverHost | undefined {
+  return typeof window !== "undefined" && typeof window.ResizeObserver === "function"
+    ? window
+    : undefined;
+}

package/registry/files/retry-async.ts

@@ -0,0 +1,261 @@
+import { timeoutAbortSignal } from "./abort-signal.ts";
+import { calculateRetryDelay, type RetryDelayOptions } from "./retry-delay.ts";
+import type { TimeoutScheduler } from "./timeout-scheduler.ts";
+
+/** Context supplied to every invocation of a retried operation. */
+export interface RetryAttemptContext {
+  /** One-based operation attempt, including the initial call. */
+  readonly attempt: number;
+
+  /** Shared cancellation signal for the complete retry execution. */
+  readonly signal: AbortSignal;
+}
+
+/** Context supplied after an operation fails and before retry policy runs. */
+export interface RetryFailureContext extends RetryAttemptContext {
+  /** Exact value thrown or rejected by the failed operation. */
+  readonly error: unknown;
+
+  /** One-based retry that would follow this failure. */
+  readonly retryAttempt: number;
+}
+
+/** Context supplied when an approved retry is about to wait. */
+export interface RetryScheduledContext extends RetryFailureContext {
+  /** One-based operation attempt that will run after the wait. */
+  readonly nextAttempt: number;
+
+  /** Calculated backoff delay in integer milliseconds. */
+  readonly delayMs: number;
+}
+
+/** Options for {@link retryAsync}. */
+export interface RetryAsyncOptions extends RetryDelayOptions {
+  /**
+   * Maximum retries after the initial operation attempt.
+   *
+   * @default 3
+   */
+  readonly maximumRetries?: number;
+
+  /**
+   * Cancels the active operation, policy hook, notification hook, or backoff
+   * wait. The returned promise rejects with the signal's exact reason.
+   *
+   * @default a private non-aborting signal
+   */
+  readonly signal?: AbortSignal;
+
+  /**
+   * Deterministic or host-specific scheduler used for backoff waits.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+
+  /**
+   * Decide whether an operation failure is retryable. Returning `false`
+   * rejects with the original operation error without calculating a delay.
+   * The decision may be asynchronous and remains abortable.
+   *
+   * @default every failure is retryable while retries remain
+   */
+  readonly shouldRetry?: (context: RetryFailureContext) => boolean | PromiseLike<boolean>;
+
+  /**
+   * Observe an approved retry before its backoff wait begins. The hook may be
+   * asynchronous and remains abortable; a hook failure is propagated exactly
+   * and the next operation attempt is not started.
+   *
+   * @default undefined
+   */
+  readonly onRetry?: (context: RetryScheduledContext) => void | PromiseLike<void>;
+}
+
+/**
+ * Execute an operation with bounded, abortable retries and deterministic delay policy.
+ *
+ * Synchronous throws and asynchronous rejections follow the same path. A
+ * successful value is returned unchanged. Exhaustion rejects with the final
+ * operation error, a negative retry decision rejects with the error that was
+ * evaluated, and cancellation rejects with the signal's exact reason. These
+ * values are deliberately not wrapped.
+ *
+ * Cancellation races every asynchronous stage, so callers are not forced to
+ * wait for an operation or hook that ignores its signal. Late settlements are
+ * still observed internally and cannot become unhandled rejections. Backoff
+ * options and entropy are evaluated lazily only after a failure is approved
+ * for retry.
+ *
+ * @typeParam Value Value produced by the operation.
+ * @param operation Work to invoke with a one-based attempt and shared signal.
+ * @param options Retry count, cancellation, policy, hooks, and delay options.
+ * @default options {}
+ * @throws {RangeError} A tagged error when `maximumRetries` or inherited delay
+ * options are outside their documented ranges.
+ * @throws {TypeError} A tagged error when `options` is not an object, a
+ * callback is not callable, or a retry decision does not resolve to a boolean.
+ * @returns The first successful operation value.
+ */
+export async function retryAsync<Value>(
+  operation: (context: RetryAttemptContext) => Value | PromiseLike<Value>,
+  options: RetryAsyncOptions = {},
+): Promise<Value> {
+  if (typeof operation !== "function") {
+    throw new TypeError(
+      `[VIZE_COMPOSE_RETRY_INVALID_OPERATION] operation must be a function; received ${typeof operation}`,
+    );
+  }
+  if (options === null || typeof options !== "object") {
+    throw new TypeError(
+      `[VIZE_COMPOSE_RETRY_INVALID_OPTIONS] options must be an object; received ${options === null ? "null" : typeof options}`,
+    );
+  }
+  const maximumRetries = options.maximumRetries === undefined ? 3 : options.maximumRetries;
+  if (
+    !Number.isSafeInteger(maximumRetries) ||
+    maximumRetries < 0 ||
+    maximumRetries >= Number.MAX_SAFE_INTEGER
+  ) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_RETRY_INVALID_MAXIMUM_RETRIES] maximumRetries must be an integer from 0 through ${String(Number.MAX_SAFE_INTEGER - 1)}; received ${String(maximumRetries)}`,
+    );
+  }
+  const shouldRetryPolicy = options.shouldRetry;
+  const retryObserver = options.onRetry;
+  if (shouldRetryPolicy !== undefined && typeof shouldRetryPolicy !== "function") {
+    throw new TypeError(
+      `[VIZE_COMPOSE_RETRY_INVALID_CALLBACK] shouldRetry must be a function; received ${typeof shouldRetryPolicy}`,
+    );
+  }
+  if (retryObserver !== undefined && typeof retryObserver !== "function") {
+    throw new TypeError(
+      `[VIZE_COMPOSE_RETRY_INVALID_CALLBACK] onRetry must be a function; received ${typeof retryObserver}`,
+    );
+  }
+
+  const signal = options.signal === undefined ? new AbortController().signal : options.signal;
+  let attempt = 1;
+  while (true) {
+    throwIfAborted(signal);
+    const outcome = await capture(
+      raceWithAbort(
+        Promise.resolve().then(() => operation({ attempt, signal })),
+        signal,
+      ),
+    );
+    if (outcome.status === "success") return outcome.value;
+    if (signal.aborted) throw signal.reason;
+    if (attempt > maximumRetries) throw outcome.error;
+
+    const failure: RetryFailureContext = {
+      attempt,
+      error: outcome.error,
+      retryAttempt: attempt,
+      signal,
+    };
+    if (shouldRetryPolicy !== undefined) {
+      const shouldRetry = await raceWithAbort(
+        Promise.resolve().then(() => shouldRetryPolicy(failure)),
+        signal,
+      );
+      if (typeof shouldRetry !== "boolean") {
+        throw new TypeError(
+          `[VIZE_COMPOSE_RETRY_INVALID_DECISION] shouldRetry must resolve to a boolean; received ${typeof shouldRetry}`,
+        );
+      }
+      if (!shouldRetry) throw outcome.error;
+    }
+    throwIfAborted(signal);
+
+    const delayMs = calculateRetryDelay(attempt, options);
+    const scheduled: RetryScheduledContext = {
+      ...failure,
+      delayMs,
+      nextAttempt: attempt + 1,
+    };
+    if (retryObserver !== undefined) {
+      await raceWithAbort(
+        Promise.resolve().then(() => retryObserver(scheduled)),
+        signal,
+      );
+    }
+    await waitForRetry(delayMs, signal, options.scheduler);
+    attempt += 1;
+  }
+}
+
+type Captured<Value> =
+  | { readonly status: "success"; readonly value: Value }
+  | { readonly status: "error"; readonly error: unknown };
+
+async function capture<Value>(promise: Promise<Value>): Promise<Captured<Value>> {
+  try {
+    return { status: "success", value: await promise };
+  } catch (error) {
+    return { status: "error", error };
+  }
+}
+
+function raceWithAbort<Value>(promise: Promise<Value>, signal: AbortSignal): Promise<Value> {
+  if (signal.aborted) return Promise.reject(signal.reason);
+
+  return new Promise((resolve, reject) => {
+    let listening = false;
+    let settled = false;
+    const cleanup = () => {
+      if (!listening) return;
+      listening = false;
+      try {
+        signal.removeEventListener("abort", onAbort);
+      } catch {
+        // A broken adapter cannot be allowed to strand the primary promise.
+        // Native AbortSignal removal is non-throwing.
+      }
+    };
+    const settle = (callback: () => void) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      callback();
+    };
+    const onAbort = () => settle(() => reject(signal.reason));
+
+    // Attach handlers before registering with a potentially non-standard
+    // signal so the work remains observed even if registration throws.
+    void promise.then(
+      (value) => settle(() => resolve(value)),
+      (error: unknown) => settle(() => reject(error)),
+    );
+    try {
+      listening = true;
+      signal.addEventListener("abort", onAbort, { once: true });
+      if (settled) cleanup();
+      else if (signal.aborted) onAbort();
+    } catch (error) {
+      settle(() => reject(error));
+    }
+  });
+}
+
+async function waitForRetry(
+  delayMs: number,
+  signal: AbortSignal,
+  scheduler: TimeoutScheduler | undefined,
+): Promise<void> {
+  const elapsed = {};
+  const delaySignal = timeoutAbortSignal(
+    delayMs,
+    scheduler === undefined ? { reason: elapsed, signal } : { reason: elapsed, scheduler, signal },
+  );
+  try {
+    await raceWithAbort(new Promise<never>(() => undefined), delaySignal);
+  } catch (reason) {
+    if (reason === elapsed) return;
+    throw reason;
+  }
+}
+
+function throwIfAborted(signal: AbortSignal): void {
+  if (signal.aborted) throw signal.reason;
+}