@vizejs/composable 0.426.3 → 0.427.0

package/registry/files/watch-throttled.ts

@@ -0,0 +1,201 @@
+import { toValue, watch } from "vue";
+import type { MaybeRefOrGetter, WatchCallback, WatchOptions } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+import type { TimeoutScheduler } from "./timeout-scheduler.ts";
+import type { TimedWatchHandle } from "./watch-debounced.ts";
+import type { WatchCleanupRegistrar, WatchHelperCallback, WatchSources } from "./watch-source.ts";
+
+/** Options for {@link watchThrottled}. */
+export interface WatchThrottledOptions<
+  Immediate extends boolean = false,
+> extends WatchOptions<Immediate> {
+  /**
+   * Cooldown window in milliseconds. Reactive; read whenever a window opens.
+   *
+   * @default 0
+   */
+  readonly throttle?: MaybeRefOrGetter<number>;
+
+  /**
+   * Run the first change of a window immediately.
+   *
+   * @default true
+   */
+  readonly leading?: boolean;
+
+  /**
+   * Run the newest change collected during a window when it closes.
+   *
+   * @default true
+   */
+  readonly trailing?: boolean;
+
+  /**
+   * Applies the timing policy when no browser `window` is available. When
+   * disabled, the callback runs synchronously on the server.
+   *
+   * @default false
+   */
+  readonly runOnServer?: boolean;
+
+  /**
+   * Owns the cooldown 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 resolveThrottleMs(value: number): number {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(
+      `[VIZE_COMPOSE_WATCH_THROTTLED_INVALID_DELAY] throttle must be finite and at least zero; received ${String(value)}`,
+    );
+  }
+  return Math.trunc(value);
+}
+
+/**
+ * Watch sources like Vue's `watch`, but run the callback at most once per
+ * cooldown window.
+ *
+ * With the defaults (`leading` and `trailing` both on) the first change runs
+ * immediately and the newest change inside the window runs when it closes,
+ * which opens a new window. Every call receives, as its old value, the value
+ * of the previously delivered call, so consecutive calls chain without gaps. Source
+ * typing mirrors `watch`.
+ *
+ * Without a browser `window` (and without `runOnServer`) the callback runs
+ * synchronously. Timers are cleared when the watcher stops or the owning
+ * scope is disposed.
+ *
+ * @example
+ * ```ts
+ * watchThrottled(scrollY, (y) => report(y), { throttle: 100 });
+ * ```
+ *
+ * @param source Ref, getter, reactive object, or tuple of those.
+ * @param callback Throttled watch callback.
+ * @param options Watch options plus the throttle policy.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_WATCH_THROTTLED_INVALID_DELAY`
+ * when `throttle` resolves to a negative or non-finite value.
+ * @returns Stop, flush, and cancel controls.
+ */
+export function watchThrottled<
+  const Sources extends WatchSources,
+  Immediate extends Readonly<boolean> = false,
+>(
+  source: Sources,
+  callback: WatchHelperCallback<Sources, Immediate>,
+  options?: WatchThrottledOptions<Immediate>,
+): TimedWatchHandle;
+export function watchThrottled(
+  source: WatchSources,
+  callback: WatchCallback<unknown, unknown>,
+  options: WatchThrottledOptions<boolean> = {},
+): TimedWatchHandle {
+  const {
+    throttle = 0,
+    leading = true,
+    trailing = true,
+    runOnServer = false,
+    scheduler = defaultScheduler,
+    ...watchOptions
+  } = options;
+  resolveThrottleMs(toValue(throttle));
+
+  let timer: unknown;
+  let pending: (() => void) | undefined;
+  let lastDelivered: unknown;
+  let pendingOld: unknown;
+  let delivered = false;
+  let cleanup: (() => void) | undefined;
+
+  const invoke = (value: unknown, oldValue: unknown): void => {
+    const runCleanup = cleanup;
+    cleanup = undefined;
+    runCleanup?.();
+    lastDelivered = value;
+    delivered = true;
+    const onCleanup: WatchCleanupRegistrar = (fn) => {
+      cleanup = fn;
+    };
+    callback(value, oldValue, onCleanup);
+  };
+
+  const closeWindow = (): void => {
+    timer = undefined;
+    const run = pending;
+    pending = undefined;
+    if (run === undefined) return;
+    run();
+    openWindow();
+  };
+
+  function openWindow(): void {
+    timer = scheduler.setTimeout(closeWindow, resolveThrottleMs(toValue(throttle)));
+  }
+
+  const cancel = (): boolean => {
+    if (timer !== undefined) scheduler.clearTimeout(timer);
+    timer = undefined;
+    const hadPending = pending !== undefined;
+    pending = undefined;
+    return hadPending;
+  };
+
+  const flush = (): boolean => {
+    const run = pending;
+    if (run === undefined) return false;
+    pending = undefined;
+    run();
+    return true;
+  };
+
+  const schedule = (value: unknown, previous: unknown): void => {
+    pending = () => {
+      invoke(value, previous);
+    };
+    pendingOld = previous;
+  };
+
+  const handle = watch(
+    source,
+    (value, oldValue) => {
+      if (typeof window === "undefined" && !runOnServer) {
+        invoke(value, oldValue);
+        return;
+      }
+      const previous = pending === undefined ? (delivered ? lastDelivered : oldValue) : pendingOld;
+      if (timer === undefined) {
+        if (leading) invoke(value, previous);
+        else if (trailing) schedule(value, previous);
+        openWindow();
+        return;
+      }
+      if (trailing) schedule(value, previous);
+    },
+    watchOptions,
+  );
+
+  const stop = (): void => {
+    handle.stop();
+    cancel();
+    const runCleanup = cleanup;
+    cleanup = undefined;
+    runCleanup?.();
+  };
+
+  tryOnScopeDispose(stop);
+
+  return { stop, flush, cancel };
+}

package/registry/files/whenever.ts

@@ -0,0 +1,70 @@
+import { watch } from "vue";
+import type { WatchHandle, WatchOptions, WatchSource } from "vue";
+
+import type { WatchCleanupRegistrar } from "./watch-source.ts";
+
+/** Values treated as "not yet" by {@link whenever}. */
+export type Falsy = false | 0 | 0n | "" | null | undefined;
+
+/** Options for {@link whenever}. */
+export type WheneverOptions = Omit<WatchOptions<boolean>, "once"> & {
+  /**
+   * Stop after the first truthy delivery instead of after the first change.
+   *
+   * @default false
+   */
+  readonly once?: boolean;
+};
+
+/**
+ * Run a callback whenever a source becomes (or changes while) truthy.
+ *
+ * The callback's value is narrowed with `Exclude<Value, Falsy>`, so a
+ * `Ref<User | null>` delivers `User`. With `once`, the watcher stops after
+ * the first truthy delivery, not after the first change (unlike Vue's
+ * `once`). With `immediate`, an already-truthy source is delivered right
+ * away. Safe during server rendering and bound to the owning scope.
+ *
+ * @example
+ * ```ts
+ * whenever(currentUser, (user) => greet(user.name), { immediate: true, once: true });
+ * ```
+ *
+ * @param source Ref or getter.
+ * @param callback Receives the truthy value, the previous value, and
+ * `onCleanup`.
+ * @param options Vue watch options; `once` counts truthy deliveries only.
+ * @default options {}
+ * @returns Vue's watch handle.
+ */
+export function whenever<Value>(
+  source: WatchSource<Value>,
+  callback: (
+    value: Exclude<Value, Falsy>,
+    oldValue: Value | undefined,
+    onCleanup: WatchCleanupRegistrar,
+  ) => void,
+  options: WheneverOptions = {},
+): WatchHandle {
+  const { once = false, ...watchOptions } = options;
+  let handle: WatchHandle | undefined;
+  let stopRequested = false;
+  handle = watch(
+    source,
+    (value, oldValue, onCleanup) => {
+      if (!isTruthy(value)) return;
+      if (once) {
+        if (handle === undefined) stopRequested = true;
+        else handle.stop();
+      }
+      callback(value, oldValue, onCleanup);
+    },
+    watchOptions,
+  );
+  if (stopRequested) handle.stop();
+  return handle;
+}
+
+function isTruthy<Value>(value: Value): value is Exclude<Value, Falsy> {
+  return Boolean(value);
+}

package/registry/files/window-size.ts

@@ -0,0 +1,151 @@
+import { hasInjectionContext, onMounted, readonly, ref, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, Ref } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Window-like capability observed by {@link useWindowSize}. */
+export interface WindowSizeHost extends EventTarget {
+  /** Viewport width including the vertical scrollbar. */
+  readonly innerWidth: number;
+  /** Viewport height including the horizontal scrollbar. */
+  readonly innerHeight: number;
+  /** Outer browser window width. */
+  readonly outerWidth: number;
+  /** Outer browser window height. */
+  readonly outerHeight: number;
+  /** Document whose root element reports the scrollbar-free viewport. */
+  readonly document: {
+    readonly documentElement: { readonly clientWidth: number; readonly clientHeight: number };
+  };
+}
+
+/** Which window dimensions {@link useWindowSize} reports. */
+export type WindowSizeKind = "inner" | "outer";
+
+/** Options for {@link useWindowSize}. */
+export interface UseWindowSizeOptions {
+  /**
+   * Width exposed during server rendering and before hydration.
+   *
+   * @default 0
+   */
+  readonly initialWidth?: number;
+
+  /**
+   * Height exposed during server rendering and before hydration.
+   *
+   * @default 0
+   */
+  readonly initialHeight?: number;
+
+  /**
+   * Include scrollbars in the inner dimensions. When `false`, the root
+   * element's `clientWidth`/`clientHeight` are reported instead.
+   *
+   * @default true
+   */
+  readonly includeScrollbar?: boolean;
+
+  /**
+   * Report inner (viewport) or outer (browser window) dimensions.
+   *
+   * @default "inner"
+   */
+  readonly type?: WindowSizeKind;
+
+  /**
+   * Also re-measure on `orientationchange` for engines that resize late.
+   *
+   * @default true
+   */
+  readonly listenOrientation?: boolean;
+
+  /**
+   * Reactive window capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<WindowSizeHost | null | undefined>;
+}
+
+/** Reactive size returned by {@link useWindowSize}. */
+export interface WindowSizeControls {
+  /** Current width in CSS pixels. */
+  readonly width: Readonly<Ref<number>>;
+  /** Current height in CSS pixels. */
+  readonly height: Readonly<Ref<number>>;
+  /** Whether a window capability is attached. `false` during server rendering. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+}
+
+/**
+ * Track the window size reactively.
+ *
+ * Server renders expose `initialWidth`/`initialHeight` (default `0`), so the
+ * first client render matches; the real size is applied as soon as a window
+ * resolves (after mounting when called inside a component). Resize (and orientation) listeners are passive and removed with
+ * the owning reactive scope.
+ *
+ * @param options Initial size, measurement kind, and capability.
+ * @default options {}
+ * @returns Reactive width/height plus a support flag.
+ */
+export function useWindowSize(options: UseWindowSizeOptions = {}): WindowSizeControls {
+  const {
+    initialWidth = 0,
+    initialHeight = 0,
+    includeScrollbar = true,
+    type = "inner",
+    listenOrientation = true,
+  } = options;
+  const width = ref(initialWidth);
+  const height = ref(initialHeight);
+  const isSupported = ref(false);
+
+  let stopWatch: { stop(): void } | undefined;
+  const start = (): void => {
+    stopWatch = watch(
+      () => (options.host === undefined ? browserWindowSizeHost() : toValue(options.host)),
+      (host, _previous, onCleanup) => {
+        isSupported.value = Boolean(host);
+        if (!host) {
+          width.value = initialWidth;
+          height.value = initialHeight;
+          return;
+        }
+        const update = (): void => {
+          if (type === "outer") {
+            width.value = host.outerWidth;
+            height.value = host.outerHeight;
+          } else if (includeScrollbar) {
+            width.value = host.innerWidth;
+            height.value = host.innerHeight;
+          } else {
+            width.value = host.document.documentElement.clientWidth;
+            height.value = host.document.documentElement.clientHeight;
+          }
+        };
+        update();
+        const listenerOptions: AddEventListenerOptions = { passive: true };
+        host.addEventListener("resize", update, listenerOptions);
+        if (listenOrientation) host.addEventListener("orientationchange", update, listenerOptions);
+        onCleanup(() => {
+          host.removeEventListener("resize", update);
+          if (listenOrientation) host.removeEventListener("orientationchange", update);
+        });
+      },
+      { immediate: true },
+    );
+  };
+  // Inside a component the real size is read after mounting, so a hydrating
+  // client renders the initial size exactly like the server did.
+  if (hasInjectionContext()) onMounted(start);
+  else start();
+  tryOnScopeDispose(() => stopWatch?.stop());
+
+  return { width: readonly(width), height: readonly(height), isSupported: readonly(isSupported) };
+}
+
+function browserWindowSizeHost(): WindowSizeHost | undefined {
+  return typeof window !== "undefined" ? window : undefined;
+}