@vizejs/composable 0.426.3 → 0.427.0

package/registry/files/event-listener.ts

@@ -0,0 +1,188 @@
+import { hasInjectionContext, onMounted, readonly, ref, shallowRef, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, Ref, WatchHandle } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Options for {@link useEventListener}. */
+export interface UseEventListenerOptions {
+  /**
+   * Invoke the listener during the capture phase.
+   *
+   * @default false
+   */
+  readonly capture?: boolean;
+
+  /**
+   * Stop listening after the first event.
+   *
+   * @default false
+   */
+  readonly once?: boolean;
+
+  /**
+   * Declare that the listener does not cancel the event's default action.
+   *
+   * @default false
+   */
+  readonly passive?: boolean;
+
+  /**
+   * Stop listening when this signal is aborted. An already-aborted signal
+   * prevents listening from ever starting.
+   *
+   * @default undefined
+   */
+  readonly signal?: AbortSignal;
+
+  /**
+   * Start listening during composable creation.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+
+  /**
+   * Reactive target update timing.
+   *
+   * @default "pre"
+   */
+  readonly flush?: "pre" | "post" | "sync";
+}
+
+/** Reactive controls returned by {@link useEventListener}. */
+export interface EventListenerControls {
+  /** Whether a concrete target currently owns the listener. */
+  readonly isListening: Readonly<Ref<boolean>>;
+
+  /**
+   * Begin listening.
+   *
+   * @returns Whether a new reactive watcher was started. `false` while the
+   * watcher is already active (including a null-target watcher with no
+   * listener attached), after the abort signal has fired, and after the
+   * owning reactive scope has been disposed.
+   */
+  readonly start: () => boolean;
+
+  /** Stop listening. Repeated calls are safe. */
+  readonly stop: () => void;
+}
+
+/**
+ * Attach an event listener to a reactive target and clean it up with the
+ * current reactive scope. Missing targets are valid during server rendering:
+ * a `null`/`undefined` target keeps the listener detached until a concrete
+ * target appears, so no browser globals are required.
+ *
+ * The listener is re-attached whenever the reactive target changes and is
+ * removed when the owning reactive scope stops, when
+ * {@link EventListenerControls.stop} is called, or when the abort signal
+ * fires. Outside an active scope, teardown ownership stays with the caller,
+ * who must call `stop` explicitly. Errors thrown by a custom target's
+ * add/remove methods propagate to the active watcher run.
+ *
+ * @param target Reactive event target.
+ * @param event Event name.
+ * @param listener Typed event listener.
+ * @param options Listener lifecycle and scheduling options.
+ * @default options {}
+ * @returns Controls to observe and change the listening state.
+ */
+export function useEventListener<Key extends keyof WindowEventMap>(
+  target: MaybeRefOrGetter<Window | null | undefined>,
+  event: Key,
+  listener: (event: WindowEventMap[Key]) => void,
+  options?: UseEventListenerOptions,
+): EventListenerControls;
+export function useEventListener<Key extends keyof DocumentEventMap>(
+  target: MaybeRefOrGetter<Document | null | undefined>,
+  event: Key,
+  listener: (event: DocumentEventMap[Key]) => void,
+  options?: UseEventListenerOptions,
+): EventListenerControls;
+export function useEventListener<Key extends keyof HTMLElementEventMap>(
+  target: MaybeRefOrGetter<HTMLElement | null | undefined>,
+  event: Key,
+  listener: (event: HTMLElementEventMap[Key]) => void,
+  options?: UseEventListenerOptions,
+): EventListenerControls;
+export function useEventListener(
+  target: MaybeRefOrGetter<EventTarget | null | undefined>,
+  event: string,
+  listener: EventListener,
+  options?: UseEventListenerOptions,
+): EventListenerControls;
+export function useEventListener(
+  target: MaybeRefOrGetter<EventTarget | null | undefined>,
+  event: string,
+  listener: EventListener,
+  options: UseEventListenerOptions = {},
+): EventListenerControls {
+  const {
+    capture = false,
+    once = false,
+    passive = false,
+    signal,
+    immediate = true,
+    flush = "pre",
+  } = options;
+  const isListening = ref(false);
+  const eventOptions: AddEventListenerOptions = {
+    capture,
+    passive,
+    ...(signal ? { signal } : {}),
+  };
+  let disposed = false;
+  // Inside a component the target is attached once it has mounted, so a hydrating
+  // client renders `isListening: false` exactly like the server. `hasInjectionContext`
+  // also detects Vapor components (unlike `getCurrentInstance`).
+  const mounted = shallowRef(!hasInjectionContext());
+  if (!mounted.value) {
+    onMounted(() => {
+      mounted.value = true;
+    });
+  }
+  let stopWatch: WatchHandle | undefined;
+
+  const stop = (): void => {
+    stopWatch?.stop();
+    stopWatch = undefined;
+    isListening.value = false;
+  };
+  const start = (): boolean => {
+    if (disposed || stopWatch || signal?.aborted) return false;
+
+    stopWatch = watch(
+      () => (mounted.value ? toValue(target) : null),
+      (next, _previous, onCleanup) => {
+        isListening.value = false;
+        if (!next || signal?.aborted) return;
+
+        const invoke: EventListener = (nativeEvent) => {
+          if (once) stop();
+          listener(nativeEvent);
+        };
+        const onAbort = (): void => stop();
+        next.addEventListener(event, invoke, eventOptions);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        isListening.value = true;
+
+        onCleanup(() => {
+          next.removeEventListener(event, invoke, { capture });
+          signal?.removeEventListener("abort", onAbort);
+          isListening.value = false;
+        });
+      },
+      { flush, immediate: true },
+    );
+    return true;
+  };
+
+  tryOnScopeDispose(() => {
+    disposed = true;
+    stop();
+  });
+  if (immediate) start();
+
+  return { isListening: readonly(isListening), start, stop };
+}

package/registry/files/focus.ts

@@ -0,0 +1,181 @@
+import { computed, readonly, ref, watch } from "vue";
+import type { Ref, WritableComputedRef } from "vue";
+
+import { resolveElement } from "./element-target.ts";
+import type { MaybeElementTarget } from "./element-target.ts";
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Element that can receive programmatic focus (`HTMLElement`, `SVGElement`, `MathMLElement`). */
+export type FocusableElement = Element & HTMLOrSVGElement;
+
+/** Options for {@link useFocus}. */
+export interface UseFocusOptions {
+  /**
+   * Focus the element as soon as it resolves.
+   *
+   * @default false
+   */
+  readonly initialValue?: boolean;
+
+  /**
+   * Only report focus when the user agent would show a focus ring
+   * (`:focus-visible`).
+   *
+   * @default false
+   */
+  readonly focusVisible?: boolean;
+
+  /**
+   * Avoid scrolling the element into view when focusing programmatically.
+   *
+   * @default false
+   */
+  readonly preventScroll?: boolean;
+}
+
+/** Reactive focus state returned by {@link useFocus}. */
+export interface FocusControls {
+  /** Whether the element is focused. Assign `true`/`false` to focus/blur it. */
+  readonly focused: WritableComputedRef<boolean>;
+  /** Stop tracking. Idempotent. */
+  readonly stop: () => void;
+}
+
+/**
+ * Track and control focus of a single element.
+ *
+ * Listens for `focus`/`blur` on the resolved element and re-syncs when the
+ * target changes. Assigning `focused` calls `focus()`/`blur()`. Server renders
+ * always report `false`; `initialValue` is applied only after the element
+ * resolves on the client, so hydration output is unaffected.
+ *
+ * @param target Reactive element target.
+ * @param options Initial focus, focus-visible filtering, and scroll behavior.
+ * @default options {}
+ * @returns Writable focus ref and stop control.
+ */
+export function useFocus(target: MaybeElementTarget, options: UseFocusOptions = {}): FocusControls {
+  const inner = ref(false);
+  const element = computed(() => {
+    const resolved = resolveElement(target);
+    return resolved && isFocusable(resolved) ? resolved : null;
+  });
+
+  const read = (el: FocusableElement): boolean => {
+    const active = el.ownerDocument.activeElement === el;
+    if (!active || !options.focusVisible) return active;
+    return safeMatches(el, ":focus-visible");
+  };
+
+  const stopWatch = watch(
+    element,
+    (el, _previous, onCleanup) => {
+      if (!el) {
+        inner.value = false;
+        return;
+      }
+      const onFocus = (): void => {
+        inner.value = read(el);
+      };
+      const onBlur = (): void => {
+        inner.value = false;
+      };
+      el.addEventListener("focus", onFocus);
+      el.addEventListener("blur", onBlur);
+      inner.value = read(el);
+      if (options.initialValue && !inner.value) {
+        el.focus({ preventScroll: options.preventScroll ?? false });
+      }
+      onCleanup(() => {
+        el.removeEventListener("focus", onFocus);
+        el.removeEventListener("blur", onBlur);
+      });
+    },
+    { immediate: true, flush: "post" },
+  );
+  const stop = (): void => stopWatch.stop();
+  tryOnScopeDispose(stop);
+
+  const focused = computed({
+    get: () => inner.value,
+    set: (next: boolean) => {
+      const el = element.value;
+      if (!el) return;
+      if (next) el.focus({ preventScroll: options.preventScroll ?? false });
+      else el.blur();
+    },
+  });
+
+  return { focused, stop };
+}
+
+/** Reactive state returned by {@link useFocusWithin}. */
+export interface FocusWithinControls {
+  /** Whether the element or any descendant has focus. */
+  readonly focused: Readonly<Ref<boolean>>;
+  /** Stop tracking. Idempotent. */
+  readonly stop: () => void;
+}
+
+/**
+ * Track whether focus is inside an element (the `:focus-within` state).
+ *
+ * Uses bubbling `focusin`/`focusout` and checks the `relatedTarget` so moving
+ * focus between descendants never flickers to `false`. Server renders report
+ * `false`.
+ *
+ * @param target Reactive element target.
+ * @returns Readonly focus-within ref and stop control.
+ */
+export function useFocusWithin(target: MaybeElementTarget): FocusWithinControls {
+  const focused = ref(false);
+  const stopWatch = watch(
+    () => resolveElement(target),
+    (el, _previous, onCleanup) => {
+      if (!el) {
+        focused.value = false;
+        return;
+      }
+      const onFocusIn = (): void => {
+        focused.value = true;
+      };
+      const onFocusOut = (event: Event): void => {
+        const next = "relatedTarget" in event ? event.relatedTarget : null;
+        focused.value = isNode(next) && el.contains(next);
+      };
+      el.addEventListener("focusin", onFocusIn);
+      el.addEventListener("focusout", onFocusOut);
+      const active = el.ownerDocument.activeElement;
+      focused.value = active !== null && el.contains(active);
+      onCleanup(() => {
+        el.removeEventListener("focusin", onFocusIn);
+        el.removeEventListener("focusout", onFocusOut);
+      });
+    },
+    { immediate: true, flush: "post" },
+  );
+  const stop = (): void => stopWatch.stop();
+  tryOnScopeDispose(stop);
+  return { focused: readonly(focused), stop };
+}
+
+function isFocusable(element: Element): element is FocusableElement {
+  return (
+    "focus" in element &&
+    typeof element.focus === "function" &&
+    "blur" in element &&
+    typeof element.blur === "function"
+  );
+}
+
+function isNode(value: unknown): value is Node {
+  return typeof value === "object" && value !== null && "nodeType" in value;
+}
+
+function safeMatches(element: Element, selector: string): boolean {
+  try {
+    return element.matches(selector);
+  } catch {
+    return true;
+  }
+}

package/registry/files/fps.ts

@@ -0,0 +1,133 @@
+import { hasInjectionContext, onMounted, readonly, ref, shallowRef, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, Ref } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Frame scheduling capability used by {@link useFps}. */
+export interface AnimationFrameHost {
+  /** Schedule a callback before the next repaint. */
+  readonly requestAnimationFrame: (callback: FrameRequestCallback) => number;
+  /** Cancel a scheduled frame. */
+  readonly cancelAnimationFrame: (handle: number) => void;
+}
+
+/** Options for {@link useFps}. */
+export interface UseFpsOptions {
+  /**
+   * Number of frames averaged per update.
+   *
+   * @default 10
+   */
+  readonly every?: number;
+
+  /**
+   * Start measuring during composable creation.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+
+  /**
+   * Reactive frame-scheduling capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<AnimationFrameHost | null | undefined>;
+}
+
+/** Reactive frame-rate state returned by {@link useFps}. */
+export interface FpsControls {
+  /** Frames per second averaged over the last `every` frames; `0` until measured. */
+  readonly fps: Readonly<Ref<number>>;
+  /** Whether a frame-scheduling capability is attached. `false` during server rendering. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+  /** Whether the frame loop is running. */
+  readonly isActive: Readonly<Ref<boolean>>;
+  /** Stop the frame loop. */
+  readonly pause: () => void;
+  /** Restart the frame loop. */
+  readonly resume: () => void;
+}
+
+/**
+ * Measure the rendering frame rate with `requestAnimationFrame`.
+ *
+ * Uses the frame timestamps passed to the callback (no extra clock) and
+ * publishes a rounded average every `every` frames. No frames are requested
+ * during server rendering (`fps` stays `0`), and the pending frame is
+ * cancelled when paused or when the owning reactive scope stops.
+ *
+ * @param options Averaging window, start mode, and frame capability.
+ * @default options {}
+ * @returns Reactive frame rate plus pause/resume controls.
+ */
+export function useFps(options: UseFpsOptions = {}): FpsControls {
+  const every = Math.max(1, Math.floor(options.every ?? 10));
+  const fps = ref(0);
+  const isSupported = ref(false);
+  const isActive = ref(options.immediate ?? true);
+  // 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 stop = watch(
+    [
+      () =>
+        !mounted.value
+          ? undefined
+          : options.host === undefined
+            ? browserFrameHost()
+            : toValue(options.host),
+      isActive,
+    ],
+    ([host, active], _previous, onCleanup) => {
+      isSupported.value = Boolean(host);
+      if (!host || !active) return;
+      let handle = 0;
+      let first: number | undefined;
+      let frames = 0;
+      const tick = (time: number): void => {
+        if (first === undefined) {
+          first = time;
+        } else {
+          frames += 1;
+          if (frames >= every) {
+            const elapsed = time - first;
+            if (elapsed > 0) fps.value = Math.round((1000 * frames) / elapsed);
+            first = time;
+            frames = 0;
+          }
+        }
+        handle = host.requestAnimationFrame(tick);
+      };
+      handle = host.requestAnimationFrame(tick);
+      onCleanup(() => host.cancelAnimationFrame(handle));
+    },
+    { immediate: true },
+  );
+  tryOnScopeDispose(() => stop.stop());
+
+  return {
+    fps: readonly(fps),
+    isSupported: readonly(isSupported),
+    isActive: readonly(isActive),
+    pause: () => {
+      isActive.value = false;
+    },
+    resume: () => {
+      isActive.value = true;
+    },
+  };
+}
+
+function browserFrameHost(): AnimationFrameHost | undefined {
+  return typeof window !== "undefined" && typeof window.requestAnimationFrame === "function"
+    ? window
+    : undefined;
+}