@vizejs/composable 0.426.3 → 0.427.0

package/registry/files/idle.ts

@@ -0,0 +1,176 @@
+import { hasInjectionContext, onMounted, readonly, ref, shallowRef, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, Ref } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+import type { TimeoutScheduler } from "./timeout-scheduler.ts";
+
+/** Window-like capability observed by {@link useIdle}. */
+export interface IdleHost extends EventTarget {
+  /** Document whose visibility changes count as activity when it becomes visible. */
+  readonly document?: EventTarget & { readonly hidden?: boolean };
+}
+
+/** Default activity events. */
+export const DEFAULT_IDLE_EVENTS = [
+  "mousemove",
+  "mousedown",
+  "resize",
+  "keydown",
+  "touchstart",
+  "wheel",
+] as const;
+
+/** Options for {@link useIdle}. */
+export interface UseIdleOptions {
+  /**
+   * Window events that count as activity.
+   *
+   * @default DEFAULT_IDLE_EVENTS
+   */
+  readonly events?: readonly string[];
+
+  /**
+   * Treat the document becoming visible again as activity.
+   *
+   * @default true
+   */
+  readonly listenForVisibilityChange?: boolean;
+
+  /**
+   * Idle state exposed during server rendering and before the timer starts.
+   *
+   * @default false
+   */
+  readonly initialState?: boolean;
+
+  /**
+   * Clock used for `lastActive`.
+   *
+   * @default Date.now
+   */
+  readonly now?: () => number;
+
+  /**
+   * Owns the idle timer.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+
+  /**
+   * Reactive window capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<IdleHost | null | undefined>;
+}
+
+/** Reactive idle state returned by {@link useIdle}. */
+export interface IdleControls {
+  /** Whether no activity happened within the timeout. */
+  readonly idle: Readonly<Ref<boolean>>;
+  /** Epoch milliseconds of the latest activity; `null` until tracking starts on the client. */
+  readonly lastActive: Readonly<Ref<number | null>>;
+  /** Record activity now and restart the timer. No-op until tracking starts on the client. */
+  readonly reset: () => void;
+}
+
+const defaultScheduler: TimeoutScheduler = {
+  setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+  clearTimeout: (handle) => {
+    globalThis.clearTimeout(handle as ReturnType<typeof setTimeout>);
+  },
+};
+
+/**
+ * Detect user inactivity.
+ *
+ * Any configured activity event resets a single timer; when it fires, `idle`
+ * becomes `true` until the next activity. No timer runs during server
+ * rendering (`idle` is `initialState`, `lastActive` is `null`), so the
+ * output is hydration-stable. Listeners and the timer are released with the
+ * owning reactive scope.
+ *
+ * @param timeout Inactivity window in milliseconds.
+ * @param options Activity events, clock, scheduler, and window capability.
+ * @default timeout 60000
+ * @default options {}
+ * @returns Reactive idle flag, last activity time, and a reset action.
+ */
+export function useIdle(timeout = 60_000, options: UseIdleOptions = {}): IdleControls {
+  const {
+    events = DEFAULT_IDLE_EVENTS,
+    listenForVisibilityChange = true,
+    initialState = false,
+    now = Date.now,
+    scheduler = defaultScheduler,
+  } = options;
+  const idle = ref(initialState);
+  const lastActive = ref<number | null>(null);
+  let handle: unknown;
+  let hasTimer = false;
+  let tracking = false;
+  // Inside a component the host is read once it has mounted, so a hydrating
+  // client first renders the same fallback as the server. `hasInjectionContext`
+  // also detects Vapor components (unlike `getCurrentInstance`).
+  const mounted = shallowRef(!hasInjectionContext());
+  if (!mounted.value) {
+    onMounted(() => {
+      mounted.value = true;
+    });
+  }
+
+  const clear = (): void => {
+    if (!hasTimer) return;
+    scheduler.clearTimeout(handle);
+    hasTimer = false;
+  };
+  const reset = (): void => {
+    if (!tracking) return;
+    idle.value = false;
+    lastActive.value = now();
+    clear();
+    handle = scheduler.setTimeout(() => {
+      hasTimer = false;
+      idle.value = true;
+    }, timeout);
+    hasTimer = true;
+  };
+
+  const stop = watch(
+    () =>
+      !mounted.value
+        ? undefined
+        : options.host === undefined
+          ? browserIdleHost()
+          : toValue(options.host),
+    (host, _previous, onCleanup) => {
+      if (!host) return;
+      tracking = true;
+      const listenerOptions: AddEventListenerOptions = { passive: true };
+      for (const event of events) host.addEventListener(event, reset, listenerOptions);
+      const document = host.document;
+      const onVisibility = (): void => {
+        if (!document?.hidden) reset();
+      };
+      if (listenForVisibilityChange) {
+        document?.addEventListener("visibilitychange", onVisibility, listenerOptions);
+      }
+      reset();
+      onCleanup(() => {
+        tracking = false;
+        clear();
+        for (const event of events) host.removeEventListener(event, reset);
+        document?.removeEventListener("visibilitychange", onVisibility);
+      });
+    },
+    { immediate: true },
+  );
+  tryOnScopeDispose(() => stop.stop());
+
+  return { idle: readonly(idle), lastActive: readonly(lastActive), reset };
+}
+
+function browserIdleHost(): IdleHost | undefined {
+  return typeof window !== "undefined" ? window : undefined;
+}

package/registry/files/infinite-scroll.ts

@@ -0,0 +1,135 @@
+import { nextTick, readonly, ref, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, Ref } from "vue";
+
+import { useScroll } from "./scroll.ts";
+import type { ScrollTargetValue, UseScrollOptions } from "./scroll.ts";
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Edge that triggers loading in {@link useInfiniteScroll}. */
+export type InfiniteScrollDirection = "top" | "bottom" | "left" | "right";
+
+/** Options for {@link useInfiniteScroll}. */
+export interface UseInfiniteScrollOptions extends Omit<UseScrollOptions, "offset"> {
+  /**
+   * Distance in CSS pixels from the edge that triggers loading.
+   *
+   * @default 0
+   */
+  readonly distance?: number;
+
+  /**
+   * Edge that triggers loading.
+   *
+   * @default "bottom"
+   */
+  readonly direction?: InfiniteScrollDirection;
+
+  /**
+   * Return `false` to stop loading (for example once every page is loaded).
+   *
+   * @default () => true
+   */
+  readonly canLoadMore?: MaybeRefOrGetter<boolean>;
+}
+
+/** Reactive state returned by {@link useInfiniteScroll}. */
+export interface InfiniteScrollControls {
+  /** Whether `onLoadMore` is running. */
+  readonly isLoading: Readonly<Ref<boolean>>;
+  /**
+   * Re-check the edge and load when it is still within `distance` (call after
+   * the list was replaced).
+   */
+  readonly reset: () => void;
+}
+
+/**
+ * Load more content when a scroll container reaches an edge.
+ *
+ * Built on `useScroll`: when the configured edge is within `distance`,
+ * `onLoadMore` runs; concurrent calls are prevented, and after each load the
+ * edge is re-measured so short pages keep loading until the container
+ * overflows or `canLoadMore` returns `false`. Loader errors propagate to the
+ * returned promise of the internal run but never leave `isLoading` stuck.
+ * No loading happens during server rendering.
+ *
+ * @param target Reactive scroll container (element, component, or window).
+ * @param onLoadMore Loader invoked at the edge.
+ * @param options Edge, distance, gating, and {@link useScroll} options.
+ * @default options {}
+ * @returns Loading flag and a manual re-check.
+ */
+export function useInfiniteScroll(
+  target: MaybeRefOrGetter<ScrollTargetValue>,
+  onLoadMore: () => unknown,
+  options: UseInfiniteScrollOptions = {},
+): InfiniteScrollControls {
+  const { distance = 0, direction = "bottom", canLoadMore = true, ...scrollOptions } = options;
+  const isLoading = ref(false);
+  const scroll = useScroll(target, { ...scrollOptions, offset: { [direction]: distance } });
+  let disposed = false;
+
+  const check = async (): Promise<void> => {
+    if (disposed || isLoading.value || !toValue(canLoadMore)) return;
+    if (!scroll.arrivedState[direction] || !hasContainer(target)) return;
+    isLoading.value = true;
+    const before = contentSize(target);
+    try {
+      await onLoadMore();
+    } finally {
+      isLoading.value = false;
+    }
+    await nextTick();
+    if (disposed) return;
+    scroll.measure();
+    // Only keep filling while loads actually grow the content: a loader that
+    // adds nothing (or content that cannot be measured) would otherwise spin
+    // forever at the edge. The next edge change or `reset()` re-checks.
+    const after = contentSize(target);
+    if (after === undefined || after !== before) void check();
+  };
+
+  const stop = watch(
+    () => [scroll.arrivedState[direction], toValue(canLoadMore)] as const,
+    () => void check(),
+    { immediate: true },
+  );
+  tryOnScopeDispose(() => {
+    disposed = true;
+    stop.stop();
+  });
+
+  return {
+    isLoading: readonly(isLoading),
+    reset: () => {
+      scroll.measure();
+      void check();
+    },
+  };
+}
+
+function hasContainer(target: MaybeRefOrGetter<ScrollTargetValue>): boolean {
+  const value = toValue(target);
+  return value !== null && value !== undefined;
+}
+
+function contentSize(target: MaybeRefOrGetter<ScrollTargetValue>): string | undefined {
+  const value: unknown = toValue(target);
+  if (typeof value !== "object" || value === null) return undefined;
+  const element: unknown =
+    "scrollHeight" in value
+      ? value
+      : "documentElement" in value
+        ? value.documentElement
+        : "document" in value && typeof value.document === "object" && value.document !== null
+          ? Reflect.get(value.document, "documentElement")
+          : "$el" in value
+            ? value.$el
+            : undefined;
+  if (typeof element !== "object" || element === null) return undefined;
+  const height: unknown = Reflect.get(element, "scrollHeight");
+  const width: unknown = Reflect.get(element, "scrollWidth");
+  return typeof height === "number" && typeof width === "number"
+    ? `${String(height)}x${String(width)}`
+    : undefined;
+}

package/registry/files/intersection-observer.ts

@@ -0,0 +1,261 @@
+import { hasInjectionContext, onMounted, readonly, ref, shallowRef, toValue, watch } from "vue";
+import type { ComponentPublicInstance, 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 `IntersectionObserver` constructor. */
+export interface IntersectionObserverHost {
+  /** `IntersectionObserver` constructor, absent in unsupported runtimes. */
+  readonly IntersectionObserver?: new (
+    callback: IntersectionObserverCallback,
+    options?: IntersectionObserverInit,
+  ) => IntersectionObserver;
+}
+
+/**
+ * Intersection root: an element target, a document, or `null`/`undefined`
+ * for the top-level viewport.
+ */
+export type IntersectionRoot = MaybeRefOrGetter<
+  Element | Document | ComponentPublicInstance | null | undefined
+>;
+
+/** Options for {@link useIntersectionObserver}. */
+export interface UseIntersectionObserverOptions {
+  /**
+   * Ancestor (or document) whose box is used as the viewport.
+   *
+   * @default undefined (the top-level viewport)
+   */
+  readonly root?: IntersectionRoot;
+
+  /**
+   * Margin grown or shrunk around the root box, in CSS margin syntax.
+   *
+   * @default "0px"
+   */
+  readonly rootMargin?: MaybeRefOrGetter<string>;
+
+  /**
+   * Visible-ratio thresholds that trigger the callback.
+   *
+   * @default 0
+   */
+  readonly threshold?: MaybeRefOrGetter<number | readonly number[]>;
+
+  /**
+   * Start observing during composable creation. When `false`, call `resume`.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+
+  /**
+   * Reactive constructor capability for alternate runtimes and tests.
+   *
+   * @default globalThis when it provides `IntersectionObserver`
+   */
+  readonly host?: MaybeRefOrGetter<IntersectionObserverHost | null | undefined>;
+
+  /**
+   * Target resolution timing. `"post"` observes template refs after mount.
+   *
+   * @default "post"
+   */
+  readonly flush?: "pre" | "post" | "sync";
+}
+
+/** Controls returned by {@link useIntersectionObserver}. */
+export interface IntersectionObserverControls {
+  /** Whether the host provides `IntersectionObserver`. `false` during server rendering. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+
+  /** Whether observation is currently requested (not paused or stopped). */
+  readonly isActive: Readonly<Ref<boolean>>;
+
+  /** Disconnect the observer while keeping the ability to `resume`. */
+  readonly pause: () => void;
+
+  /** Reconnect after `pause` (or start when created with `immediate: false`). */
+  readonly resume: () => void;
+
+  /** Disconnect permanently. Later `resume` calls are ignored. Idempotent. */
+  readonly stop: () => void;
+}
+
+/**
+ * Observe the intersection of reactive elements with a root.
+ *
+ * One observer is created per combination of resolved targets, root,
+ * margin, and threshold; changing any of them disconnects the previous
+ * observer first. During server rendering `isSupported` is `false` and the
+ * callback never runs. The observer is disconnected when the owning scope
+ * stops.
+ *
+ * @param targets Reactive element target or list of targets.
+ * @param callback Native `IntersectionObserver` callback.
+ * @param options Root, margin, thresholds, capability, and timing.
+ * @default options {}
+ * @returns Support/activity flags and pause/resume/stop controls.
+ */
+export function useIntersectionObserver(
+  targets: MaybeElementTargets,
+  callback: IntersectionObserverCallback,
+  options: UseIntersectionObserverOptions = {},
+): IntersectionObserverControls {
+  const isSupported = ref(false);
+  const isActive = ref(options.immediate ?? true);
+  let stopped = false;
+  let stopWatch: WatchHandle | undefined;
+
+  // Inside a component the host is read once it has mounted, so a hydrating
+  // client first renders the same fallback as the server. `hasInjectionContext`
+  // also detects Vapor components (unlike `getCurrentInstance`).
+  const mounted = shallowRef(!hasInjectionContext());
+  if (!mounted.value) {
+    onMounted(() => {
+      mounted.value = true;
+    });
+  }
+  const host = (): IntersectionObserverHost | null | undefined =>
+    !mounted.value
+      ? undefined
+      : options.host === undefined
+        ? browserIntersectionObserverHost()
+        : toValue(options.host);
+  isSupported.value = host()?.IntersectionObserver !== undefined;
+
+  const connect = (): void => {
+    stopWatch = watch(
+      () =>
+        [
+          host(),
+          resolveElements(targets),
+          resolveRoot(options.root),
+          toValue(options.rootMargin) ?? "0px",
+          toValue(options.threshold) ?? 0,
+        ] as const,
+      ([currentHost, elements, root, rootMargin, threshold], _previous, onCleanup) => {
+        const Observer = currentHost?.IntersectionObserver;
+        isSupported.value = Observer !== undefined;
+        if (!Observer || elements.length === 0) return;
+        const observer = new Observer(callback, {
+          root,
+          rootMargin,
+          threshold: typeof threshold === "number" ? threshold : [...threshold],
+        });
+        for (const element of elements) observer.observe(element);
+        onCleanup(() => observer.disconnect());
+      },
+      { immediate: true, flush: options.flush ?? "post" },
+    );
+  };
+
+  const pause = (): void => {
+    stopWatch?.stop();
+    stopWatch = undefined;
+    isActive.value = false;
+  };
+  const resume = (): void => {
+    if (stopped || stopWatch) return;
+    isActive.value = true;
+    connect();
+  };
+  const stop = (): void => {
+    stopped = true;
+    pause();
+  };
+
+  if (isActive.value) connect();
+  tryOnScopeDispose(stop);
+
+  return {
+    isSupported: readonly(isSupported),
+    isActive: readonly(isActive),
+    pause,
+    resume,
+    stop,
+  };
+}
+
+/** Options for {@link useElementVisibility}. */
+export interface UseElementVisibilityOptions extends Omit<
+  UseIntersectionObserverOptions,
+  "immediate"
+> {
+  /**
+   * Visibility exposed before the first observation and during server
+   * rendering. Keep it identical on server and client.
+   *
+   * @default false
+   */
+  readonly initialValue?: boolean;
+
+  /**
+   * Stop observing after the element becomes visible for the first time.
+   *
+   * @default false
+   */
+  readonly once?: boolean;
+}
+
+/** Reactive state returned by {@link useElementVisibility}. */
+export interface ElementVisibilityControls {
+  /** Whether the element currently intersects the root. */
+  readonly isVisible: Readonly<Ref<boolean>>;
+
+  /** Whether the host provides `IntersectionObserver`. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+
+  /** Stop observing. Idempotent. */
+  readonly stop: () => void;
+}
+
+/**
+ * Track whether an element is visible inside the viewport (or a root).
+ *
+ * Uses the latest intersection entry, so rapid enter/leave sequences settle
+ * on the final state. With `once`, the observer disconnects after the first
+ * visible entry and `isVisible` stays `true`.
+ *
+ * @param target Reactive element target.
+ * @param options Initial value, one-shot mode, and observer options.
+ * @default options {}
+ * @returns Reactive visibility plus controls.
+ */
+export function useElementVisibility(
+  target: MaybeElementTarget,
+  options: UseElementVisibilityOptions = {},
+): ElementVisibilityControls {
+  const isVisible = ref(options.initialValue ?? false);
+  const controls = useIntersectionObserver(
+    target,
+    (entries) => {
+      let latest: IntersectionObserverEntry | undefined;
+      for (const entry of entries) {
+        if (!latest || entry.time >= latest.time) latest = entry;
+      }
+      if (!latest) return;
+      isVisible.value = latest.isIntersecting;
+      if (options.once && latest.isIntersecting) controls.stop();
+    },
+    options,
+  );
+  return { isVisible: readonly(isVisible), isSupported: controls.isSupported, stop: controls.stop };
+}
+
+function resolveRoot(root: IntersectionRoot | undefined): Element | Document | null {
+  if (root === undefined) return null;
+  const value = toValue(root);
+  return isDocumentNode(value) ? value : resolveElement(value);
+}
+
+function isDocumentNode(value: unknown): value is Document {
+  return typeof value === "object" && value !== null && "nodeType" in value && value.nodeType === 9;
+}
+
+function browserIntersectionObserverHost(): IntersectionObserverHost | undefined {
+  return typeof IntersectionObserver === "function" ? globalThis : undefined;
+}