@vizejs/composable 0.426.3 → 0.427.0

package/registry/files/element-bounding.ts

@@ -0,0 +1,175 @@
+import { readonly, ref, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, Ref } from "vue";
+
+import { resolveElement } from "./element-target.ts";
+import type { MaybeElementTarget } from "./element-target.ts";
+import { useEventListener } from "./event-listener.ts";
+import { useResizeObserver } from "./resize-observer.ts";
+import type { ResizeObserverHost } from "./resize-observer.ts";
+import { tryOnScopeDispose } from "./scope.ts";
+
+/**
+ * Window-like capability observed by {@link useElementBounding}: scroll and
+ * resize events plus the optional `ResizeObserver` constructor.
+ */
+export interface ElementBoundingHost extends EventTarget, ResizeObserverHost {}
+
+/** Viewport-relative element geometry in CSS pixels. */
+export interface ElementBoundingRect {
+  /** Horizontal position of the border box origin. */
+  readonly x: number;
+  /** Vertical position of the border box origin. */
+  readonly y: number;
+  /** Distance from the viewport top edge to the border box top edge. */
+  readonly top: number;
+  /** Distance from the viewport left edge to the border box right edge. */
+  readonly right: number;
+  /** Distance from the viewport top edge to the border box bottom edge. */
+  readonly bottom: number;
+  /** Distance from the viewport left edge to the border box left edge. */
+  readonly left: number;
+  /** Border box width. */
+  readonly width: number;
+  /** Border box height. */
+  readonly height: number;
+}
+
+/** Options for {@link useElementBounding}. */
+export interface UseElementBoundingOptions {
+  /**
+   * Reset every value to zero when the target unmounts.
+   *
+   * @default true
+   */
+  readonly reset?: boolean;
+
+  /**
+   * Re-measure when the window resizes.
+   *
+   * @default true
+   */
+  readonly windowResize?: boolean;
+
+  /**
+   * Re-measure when any ancestor (or the window) scrolls. Uses a capturing,
+   * passive listener so nested scroll containers are covered.
+   *
+   * @default true
+   */
+  readonly windowScroll?: boolean;
+
+  /**
+   * Reactive window capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<ElementBoundingHost | null | undefined>;
+
+  /**
+   * Target resolution timing. `"post"` measures template refs after mount.
+   *
+   * @default "post"
+   */
+  readonly flush?: "pre" | "post" | "sync";
+}
+
+/** Reactive geometry returned by {@link useElementBounding}. */
+export type ElementBoundingControls = {
+  /** Reactive geometry field; zero during server rendering. */
+  readonly [Key in keyof ElementBoundingRect]: Readonly<Ref<number>>;
+} & {
+  /** Measure the target immediately. Does nothing while it is unresolved. */
+  readonly update: () => void;
+
+  /** Stop observing resize, scroll, and target changes. Idempotent. */
+  readonly stop: () => void;
+};
+
+const boundingKeys = [
+  "x",
+  "y",
+  "top",
+  "right",
+  "bottom",
+  "left",
+  "width",
+  "height",
+] as const satisfies readonly (keyof ElementBoundingRect)[];
+
+/**
+ * Track an element's `getBoundingClientRect()` reactively.
+ *
+ * Measures when the target resolves, when it resizes (via `ResizeObserver`),
+ * and — unless disabled — when the window resizes or anything scrolls. Every
+ * value is `0` during server rendering and before the first measurement, so
+ * the initial render is hydration-stable. Listeners and the observer are
+ * released with the owning reactive scope.
+ *
+ * @param target Reactive element target.
+ * @param options Reset, listener, capability, and timing options.
+ * @default options {}
+ * @returns One readonly ref per geometry field plus `update`/`stop`.
+ */
+export function useElementBounding(
+  target: MaybeElementTarget,
+  options: UseElementBoundingOptions = {},
+): ElementBoundingControls {
+  const { reset = true, windowResize = true, windowScroll = true } = options;
+  const flush = options.flush ?? "post";
+  const state = {
+    x: ref(0),
+    y: ref(0),
+    top: ref(0),
+    right: ref(0),
+    bottom: ref(0),
+    left: ref(0),
+    width: ref(0),
+    height: ref(0),
+  };
+  const host = (): ElementBoundingHost | null | undefined =>
+    options.host === undefined ? browserBoundingHost() : toValue(options.host);
+
+  const update = (): void => {
+    const element = resolveElement(target);
+    if (!element) {
+      if (reset) for (const key of boundingKeys) state[key].value = 0;
+      return;
+    }
+    const rect = element.getBoundingClientRect();
+    for (const key of boundingKeys) state[key].value = rect[key];
+  };
+
+  const observer = useResizeObserver(target, update, { host, flush });
+  const stopTarget = watch(() => resolveElement(target), update, { immediate: true, flush });
+  const resize = windowResize
+    ? useEventListener(host, "resize", update, { passive: true, flush })
+    : undefined;
+  const scroll = windowScroll
+    ? useEventListener(host, "scroll", update, { capture: true, passive: true, flush })
+    : undefined;
+
+  const stop = (): void => {
+    observer.stop();
+    stopTarget.stop();
+    resize?.stop();
+    scroll?.stop();
+  };
+  tryOnScopeDispose(stop);
+
+  return {
+    x: readonly(state.x),
+    y: readonly(state.y),
+    top: readonly(state.top),
+    right: readonly(state.right),
+    bottom: readonly(state.bottom),
+    left: readonly(state.left),
+    width: readonly(state.width),
+    height: readonly(state.height),
+    update,
+    stop,
+  };
+}
+
+function browserBoundingHost(): ElementBoundingHost | undefined {
+  return typeof window !== "undefined" ? window : undefined;
+}

package/registry/files/element-by-point.ts

@@ -0,0 +1,149 @@
+import { hasInjectionContext, onMounted, readonly, ref, shallowRef, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Document-like capability used by {@link useElementByPoint}. */
+export interface ElementByPointHost {
+  /** Topmost element at a point. */
+  elementFromPoint(x: number, y: number): Element | null;
+  /**
+   * Every element at a point, topmost first. Optional: when missing, only
+   * the topmost element is reported.
+   */
+  elementsFromPoint?(x: number, y: number): Element[];
+}
+
+/** Frame scheduler used for continuous polling. */
+export interface ElementByPointFrameHost {
+  /** Schedule a callback before the next repaint. */
+  readonly requestAnimationFrame: (callback: FrameRequestCallback) => number;
+  /** Cancel a scheduled frame. */
+  readonly cancelAnimationFrame: (handle: number) => void;
+}
+
+/** Options for {@link useElementByPoint}. */
+export interface UseElementByPointOptions {
+  /** Horizontal client coordinate. */
+  readonly x: MaybeRefOrGetter<number>;
+
+  /** Vertical client coordinate. */
+  readonly y: MaybeRefOrGetter<number>;
+
+  /**
+   * Also re-query every animation frame (the element under a fixed point can
+   * change when the page scrolls or animates).
+   *
+   * @default false
+   */
+  readonly poll?: boolean;
+
+  /**
+   * Reactive document capability for alternate runtimes and tests.
+   *
+   * @default globalThis.document when available
+   */
+  readonly host?: MaybeRefOrGetter<ElementByPointHost | null | undefined>;
+
+  /**
+   * Frame scheduler used when `poll` is enabled.
+   *
+   * @default globalThis.window when available
+   */
+  readonly frameHost?: MaybeRefOrGetter<ElementByPointFrameHost | null | undefined>;
+}
+
+/** Reactive state returned by {@link useElementByPoint}. */
+export interface ElementByPointControls {
+  /** Whether a document capability is attached. `false` during server rendering. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+  /** Topmost element at the point. */
+  readonly element: Readonly<ShallowRef<Element | null>>;
+  /** Every element at the point, topmost first. */
+  readonly elements: Readonly<ShallowRef<readonly Element[]>>;
+  /** Re-query immediately. */
+  readonly update: () => void;
+}
+
+/**
+ * Track the element(s) under a client coordinate.
+ *
+ * Re-queries whenever `x`/`y` change and, with `poll`, on every animation
+ * frame until the owning scope stops. Server renders expose `null` and an
+ * empty list.
+ *
+ * @param options Coordinates, polling, and capabilities.
+ * @returns Reactive topmost element, element stack, and a manual update.
+ */
+export function useElementByPoint(options: UseElementByPointOptions): ElementByPointControls {
+  const isSupported = ref(false);
+  const element = shallowRef<Element | null>(null);
+  const elements = shallowRef<readonly Element[]>([]);
+  // 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 = (): ElementByPointHost | null | undefined =>
+    !mounted.value
+      ? undefined
+      : options.host === undefined
+        ? browserPointHost()
+        : toValue(options.host);
+
+  const update = (): void => {
+    const current = host();
+    isSupported.value = Boolean(current);
+    if (!current) {
+      element.value = null;
+      elements.value = [];
+      return;
+    }
+    const x = toValue(options.x);
+    const y = toValue(options.y);
+    element.value = current.elementFromPoint(x, y);
+    elements.value = current.elementsFromPoint
+      ? current.elementsFromPoint(x, y)
+      : element.value
+        ? [element.value]
+        : [];
+  };
+
+  const stopWatch = watch(() => [host(), toValue(options.x), toValue(options.y)] as const, update, {
+    immediate: true,
+  });
+  const stopPolling = options.poll
+    ? watch(
+        () => (options.frameHost === undefined ? browserFrameHost() : toValue(options.frameHost)),
+        (frames, _previous, onCleanup) => {
+          if (!frames) return;
+          let handle = 0;
+          const tick = (): void => {
+            update();
+            handle = frames.requestAnimationFrame(tick);
+          };
+          handle = frames.requestAnimationFrame(tick);
+          onCleanup(() => frames.cancelAnimationFrame(handle));
+        },
+        { immediate: true },
+      )
+    : undefined;
+  tryOnScopeDispose(() => {
+    stopWatch.stop();
+    stopPolling?.stop();
+  });
+
+  return { isSupported: readonly(isSupported), element, elements, update };
+}
+
+function browserPointHost(): ElementByPointHost | undefined {
+  return typeof document !== "undefined" ? document : undefined;
+}
+
+function browserFrameHost(): ElementByPointFrameHost | undefined {
+  return typeof window !== "undefined" ? window : undefined;
+}

package/registry/files/element-hover.ts

@@ -0,0 +1,104 @@
+import { readonly, ref, watch } from "vue";
+import type { Ref } from "vue";
+
+import { resolveElement } from "./element-target.ts";
+import type { MaybeElementTarget } from "./element-target.ts";
+import { tryOnScopeDispose } from "./scope.ts";
+import type { TimeoutScheduler } from "./timeout-scheduler.ts";
+
+/** Options for {@link useElementHover}. */
+export interface UseElementHoverOptions {
+  /**
+   * Milliseconds to wait before reporting hover.
+   *
+   * @default 0
+   */
+  readonly delayEnter?: number;
+
+  /**
+   * Milliseconds to wait before reporting the end of hover.
+   *
+   * @default 0
+   */
+  readonly delayLeave?: number;
+
+  /**
+   * Owns the delay 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>);
+  },
+};
+
+/**
+ * Track whether the pointer hovers an element.
+ *
+ * Uses `pointerenter`/`pointerleave` (which ignore descendants) with optional
+ * enter/leave delays; a pending delay is cancelled by the opposite event.
+ * Server renders report `false`; listeners and timers are released with the
+ * owning reactive scope.
+ *
+ * @param target Reactive element target.
+ * @param options Enter/leave delays and timer scheduler.
+ * @default options {}
+ * @returns Readonly hover flag.
+ */
+export function useElementHover(
+  target: MaybeElementTarget,
+  options: UseElementHoverOptions = {},
+): Readonly<Ref<boolean>> {
+  const { delayEnter = 0, delayLeave = 0, scheduler = defaultScheduler } = options;
+  const hovered = ref(false);
+  let handle: unknown;
+  let pending = false;
+
+  const cancel = (): void => {
+    if (!pending) return;
+    scheduler.clearTimeout(handle);
+    pending = false;
+  };
+  const set = (next: boolean): void => {
+    cancel();
+    const delay = next ? delayEnter : delayLeave;
+    if (delay <= 0) {
+      hovered.value = next;
+      return;
+    }
+    pending = true;
+    handle = scheduler.setTimeout(() => {
+      pending = false;
+      hovered.value = next;
+    }, delay);
+  };
+  const onEnter = (): void => set(true);
+  const onLeave = (): void => set(false);
+
+  const stop = watch(
+    () => resolveElement(target),
+    (element, _previous, onCleanup) => {
+      if (!element) return;
+      element.addEventListener("pointerenter", onEnter, { passive: true });
+      element.addEventListener("pointerleave", onLeave, { passive: true });
+      onCleanup(() => {
+        element.removeEventListener("pointerenter", onEnter);
+        element.removeEventListener("pointerleave", onLeave);
+        cancel();
+        hovered.value = false;
+      });
+    },
+    { immediate: true, flush: "post" },
+  );
+  tryOnScopeDispose(() => {
+    stop.stop();
+    cancel();
+  });
+
+  return readonly(hovered);
+}

package/registry/files/element-ref.ts

@@ -0,0 +1,58 @@
+import { hasInjectionContext, onMounted, shallowRef } from "vue";
+import type { ComponentPublicInstance, ShallowRef } from "vue";
+
+import { resolveElement } from "./element-target.ts";
+
+/** Function ref accepted by `:ref` on elements and components. */
+export type ElementRefSetter = (value: Element | ComponentPublicInstance | null) => void;
+
+/** State returned by {@link useElementRef}. */
+export interface ElementRefControls<TargetElement extends Element> {
+  /** Resolved element (component roots are unwrapped); `null` while unmounted. */
+  readonly element: Readonly<ShallowRef<TargetElement | null>>;
+  /** Bind with `:ref="setRef"` on an element or component. */
+  readonly setRef: ElementRefSetter;
+}
+
+/**
+ * Capture a template element through a function ref.
+ *
+ * An instance-free alternative to "current element" helpers: it never reads
+ * `getCurrentInstance()`, so it works in Vapor components, render functions,
+ * and plain effect scopes. Inside a component the element is published after
+ * mounting (Vapor sets function refs during render), keeping hydration stable. Component refs are unwrapped to their root
+ * element, and an optional guard narrows the element type (elements failing
+ * it resolve to `null`). The ref is `null` during server rendering.
+ *
+ * @returns Reactive element plus the function ref to bind.
+ */
+export function useElementRef(): ElementRefControls<Element>;
+/**
+ * Capture a template element narrowed by a type guard.
+ *
+ * @param guard Type guard; elements failing it resolve to `null`.
+ * @returns Reactive narrowed element plus the function ref to bind.
+ */
+export function useElementRef<TargetElement extends Element>(
+  guard: (element: Element) => element is TargetElement,
+): ElementRefControls<TargetElement>;
+export function useElementRef(guard?: (element: Element) => boolean): ElementRefControls<Element> {
+  const element = shallowRef<Element | null>(null);
+  // Vapor assigns function refs while rendering, VDOM after patching; inside
+  // a component the element is published once it has mounted so both
+  // renderers hydrate the same (server) state first.
+  let mounted = !hasInjectionContext();
+  let pending: Element | null = null;
+  if (!mounted) {
+    onMounted(() => {
+      mounted = true;
+      element.value = pending;
+    });
+  }
+  const setRef: ElementRefSetter = (value) => {
+    const resolved = resolveElement(value);
+    pending = resolved && (!guard || guard(resolved)) ? resolved : null;
+    if (mounted) element.value = pending;
+  };
+  return { element, setRef };
+}

package/registry/files/element-target.ts

@@ -0,0 +1,99 @@
+import { toValue } from "vue";
+import type { ComponentPublicInstance, MaybeRefOrGetter } from "vue";
+
+/**
+ * A concrete value that can identify a DOM element.
+ *
+ * Template refs on native elements resolve to the element itself, while refs
+ * on components resolve to the component's public instance whose root node
+ * is exposed as `$el`. `null` and `undefined` represent a target that is not
+ * mounted yet (including every server render).
+ */
+export type ElementTargetValue<TargetElement extends Element = Element> =
+  | TargetElement
+  | ComponentPublicInstance
+  | null
+  | undefined;
+
+/**
+ * Reactive element target accepted by every element-based composable.
+ *
+ * Accepts a plain value, a ref (such as `useTemplateRef()`), or a getter.
+ */
+export type MaybeElementTarget<TargetElement extends Element = Element> = MaybeRefOrGetter<
+  ElementTargetValue<TargetElement>
+>;
+
+/**
+ * Reactive list of element targets for observers that watch several nodes.
+ *
+ * Each item follows {@link MaybeElementTarget} semantics; unresolved items
+ * are skipped.
+ */
+export type MaybeElementTargets<TargetElement extends Element = Element> =
+  | MaybeElementTarget<TargetElement>
+  | MaybeRefOrGetter<readonly ElementTargetValue<TargetElement>[]>;
+
+/**
+ * Whether a value is a DOM element node.
+ *
+ * Uses the `nodeType` contract instead of `instanceof Element`, so the check
+ * reads no browser globals and works across realms (iframes, happy-dom,
+ * jsdom).
+ *
+ * @param value Candidate value.
+ * @returns Whether `value` is an element node.
+ */
+export function isElementNode(value: unknown): value is Element {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "nodeType" in value &&
+    value.nodeType === 1 &&
+    "getBoundingClientRect" in value
+  );
+}
+
+/**
+ * Resolve a reactive element target to its concrete element.
+ *
+ * Reads the reactive source once (tracking it when called inside an effect).
+ * Component instances resolve to their root element; fragment or text roots
+ * resolve to `null`. Never throws and reads no browser globals, so it is safe
+ * during server rendering, where it always returns `null`.
+ *
+ * @param target Reactive element target.
+ * @returns The resolved element, or `null` while unresolved.
+ */
+export function resolveElement(target: MaybeElementTarget): Element | null {
+  return elementFromValue(toValue(target));
+}
+
+function elementFromValue(value: unknown): Element | null {
+  if (isElementNode(value)) return value;
+  if (typeof value === "object" && value !== null && "$el" in value) {
+    const root: unknown = value.$el;
+    return isElementNode(root) ? root : null;
+  }
+  return null;
+}
+
+/**
+ * Resolve a reactive list (or single) element target to its concrete elements.
+ *
+ * Unresolved entries are dropped and duplicates are removed while keeping the
+ * first-seen order, so observers never register the same node twice.
+ *
+ * @param targets Reactive element target or target list.
+ * @returns The resolved, de-duplicated elements.
+ */
+export function resolveElements(targets: MaybeElementTargets): Element[] {
+  const value: unknown = toValue(targets);
+  const items: readonly unknown[] = Array.isArray(value) ? value : [value];
+  const elements: Element[] = [];
+  for (const item of items) {
+    const element = elementFromValue(item);
+    if (element && !elements.includes(element)) elements.push(element);
+  }
+  return elements;
+}