@vizejs/composable 0.426.2 → 0.427.0

package/registry/files/media-query.ts

@@ -0,0 +1,102 @@
+import { computed, hasInjectionContext, readonly, ref, toValue, watchEffect } from "vue";
+import type { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+
+/** Capability required to evaluate media queries. */
+export interface MediaQueryHost {
+  /** Create an observable result for a media query. */
+  readonly matchMedia: (query: string) => MediaQueryList;
+}
+
+/** Options for {@link useMediaQuery}. */
+export interface UseMediaQueryOptions {
+  /**
+   * Value exposed when no media-query capability is available.
+   *
+   * @default false
+   */
+  readonly ssrValue?: boolean;
+
+  /**
+   * Reactive media-query capability for alternate runtimes and tests.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<MediaQueryHost | null | undefined>;
+}
+
+/**
+ * Evaluate a reactive media query without requiring browser globals.
+ *
+ * During server rendering (or whenever no capability host resolves) the ref
+ * holds the configured server value and no subscription is created. Inside a
+ * component the first match is read after mounting, so hydration renders the
+ * server value first and never mismatches. The
+ * change subscription follows the reactive query and host: each
+ * re-evaluation removes the previous listener, and the final listener is
+ * removed when the owning reactive scope stops. Call inside an active scope
+ * so the subscription is released. A host whose matcher throws propagates
+ * the error to the active effect run; the browser default never throws.
+ *
+ * @param query Reactive media-query source.
+ * @param options Runtime capability and server-rendered fallback.
+ * @default options {}
+ * @returns Readonly ref that is `true` while the query matches.
+ */
+export function useMediaQuery(
+  query: MaybeRefOrGetter<string>,
+  options: UseMediaQueryOptions = {},
+): Readonly<Ref<boolean>> {
+  const matches = ref(options.ssrValue ?? false);
+
+  // Inside a component the first read waits for the post-render flush, so a
+  // hydrating client renders the same `ssrValue` the server did and then
+  // switches to the live result. Outside components the read is synchronous.
+  const flush = hasInjectionContext() ? "post" : "pre";
+  watchEffect(
+    (onCleanup) => {
+      const host = options.host === undefined ? browserMediaQueryHost() : toValue(options.host);
+      if (!host) {
+        matches.value = options.ssrValue ?? false;
+        return;
+      }
+
+      const media = host.matchMedia(toValue(query));
+      const update = (): void => {
+        matches.value = media.matches;
+      };
+      update();
+      media.addEventListener("change", update);
+      onCleanup(() => media.removeEventListener("change", update));
+    },
+    { flush },
+  );
+
+  return readonly(matches);
+}
+
+/** User motion preference exposed by {@link useReducedMotion}. */
+export type MotionPreference = "reduce" | "no-preference";
+
+/**
+ * Return the reactive user motion preference.
+ *
+ * Shares {@link useMediaQuery} semantics: during server rendering the
+ * preference is `"no-preference"` unless `ssrValue` is `true`, and the
+ * underlying subscription is removed when the owning reactive scope stops.
+ *
+ * @param options Runtime capability and server-rendered fallback.
+ * @default options {}
+ * @returns Computed preference for `(prefers-reduced-motion: reduce)`.
+ */
+export function useReducedMotion(
+  options: UseMediaQueryOptions = {},
+): ComputedRef<MotionPreference> {
+  const reduced = useMediaQuery("(prefers-reduced-motion: reduce)", options);
+  return computed(() => (reduced.value ? "reduce" : "no-preference"));
+}
+
+function browserMediaQueryHost(): MediaQueryHost | undefined {
+  return typeof window !== "undefined" && typeof window.matchMedia === "function"
+    ? window
+    : undefined;
+}

package/registry/files/mouse-in-element.ts

@@ -0,0 +1,107 @@
+import { computed, readonly, ref, watch } from "vue";
+import type { Ref } from "vue";
+
+import { resolveElement } from "./element-target.ts";
+import type { MaybeElementTarget } from "./element-target.ts";
+import { useMouse } from "./mouse.ts";
+import type { MouseControls, UseMouseOptions } from "./mouse.ts";
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Options for {@link useMouseInElement}. */
+export interface UseMouseInElementOptions extends Omit<UseMouseOptions, "type"> {
+  /**
+   * Keep updating element-relative coordinates while the pointer is outside
+   * the element. When `false`, they freeze at the last inside position.
+   *
+   * @default true
+   */
+  readonly handleOutside?: boolean;
+}
+
+/** Reactive state returned by {@link useMouseInElement}. */
+export interface MouseInElementControls extends MouseControls {
+  /** Pointer position relative to the element's left edge. */
+  readonly elementX: Readonly<Ref<number>>;
+  /** Pointer position relative to the element's top edge. */
+  readonly elementY: Readonly<Ref<number>>;
+  /** Element left edge in viewport coordinates at the latest update. */
+  readonly elementPositionX: Readonly<Ref<number>>;
+  /** Element top edge in viewport coordinates at the latest update. */
+  readonly elementPositionY: Readonly<Ref<number>>;
+  /** Element width at the latest update. */
+  readonly elementWidth: Readonly<Ref<number>>;
+  /** Element height at the latest update. */
+  readonly elementHeight: Readonly<Ref<number>>;
+  /** Whether the pointer is outside the element. `true` during server rendering. */
+  readonly isOutside: Readonly<Ref<boolean>>;
+  /** Stop updating element-relative state. Idempotent. */
+  readonly stop: () => void;
+}
+
+/**
+ * Track the pointer position relative to an element.
+ *
+ * Built on {@link useMouse} in client coordinates: every move re-reads the
+ * element rectangle, so transforms and scrolling are reflected. Server
+ * renders report zero geometry and `isOutside: true`.
+ *
+ * @param target Reactive element target.
+ * @param options Outside handling plus {@link useMouse} options.
+ * @default options {}
+ * @returns Pointer, element-relative, and geometry refs.
+ */
+export function useMouseInElement(
+  target: MaybeElementTarget,
+  options: UseMouseInElementOptions = {},
+): MouseInElementControls {
+  const handleOutside = options.handleOutside ?? true;
+  const mouse = useMouse({ ...options, type: "client" });
+  const elementX = ref(0);
+  const elementY = ref(0);
+  const elementPositionX = ref(0);
+  const elementPositionY = ref(0);
+  const elementWidth = ref(0);
+  const elementHeight = ref(0);
+  const isOutside = ref(true);
+  const element = computed(() => resolveElement(target));
+
+  const stopWatch = watch(
+    [element, mouse.x, mouse.y, mouse.sourceType],
+    ([currentElement, x, y, source]) => {
+      if (!currentElement || source === null) return;
+      const rect = currentElement.getBoundingClientRect();
+      elementPositionX.value = rect.left;
+      elementPositionY.value = rect.top;
+      elementWidth.value = rect.width;
+      elementHeight.value = rect.height;
+      const relativeX = x - rect.left;
+      const relativeY = y - rect.top;
+      isOutside.value =
+        rect.width === 0 ||
+        rect.height === 0 ||
+        relativeX < 0 ||
+        relativeY < 0 ||
+        relativeX > rect.width ||
+        relativeY > rect.height;
+      if (handleOutside || !isOutside.value) {
+        elementX.value = relativeX;
+        elementY.value = relativeY;
+      }
+    },
+    { flush: "sync" },
+  );
+  const stop = (): void => stopWatch.stop();
+  tryOnScopeDispose(stop);
+
+  return {
+    ...mouse,
+    elementX: readonly(elementX),
+    elementY: readonly(elementY),
+    elementPositionX: readonly(elementPositionX),
+    elementPositionY: readonly(elementPositionY),
+    elementWidth: readonly(elementWidth),
+    elementHeight: readonly(elementHeight),
+    isOutside: readonly(isOutside),
+    stop,
+  };
+}

package/registry/files/mouse.ts

@@ -0,0 +1,167 @@
+import { readonly, ref, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, Ref } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Coordinate space reported by {@link useMouse}. */
+export type MouseCoordinateType = "page" | "client" | "screen" | "movement";
+
+/** Input device that produced the latest coordinates. */
+export type MouseSourceType = "mouse" | "touch";
+
+/** Two-dimensional coordinate in CSS pixels. */
+export interface Point {
+  /** Horizontal coordinate. */
+  readonly x: number;
+  /** Vertical coordinate. */
+  readonly y: number;
+}
+
+/**
+ * Custom coordinate extractor. Return `null` to ignore an event.
+ *
+ * Receives the mouse event, or the first touch point for touch input.
+ */
+export type MouseCoordinateExtractor = (input: MouseEvent | Touch) => Point | null;
+
+/** Options for {@link useMouse}. */
+export interface UseMouseOptions {
+  /**
+   * Coordinate space, or a custom extractor.
+   *
+   * @default "page"
+   */
+  readonly type?: MouseCoordinateType | MouseCoordinateExtractor;
+
+  /**
+   * Event target to listen on.
+   *
+   * @default globalThis.window when available
+   */
+  readonly target?: MaybeRefOrGetter<EventTarget | null | undefined>;
+
+  /**
+   * Track touch input in addition to mouse input.
+   *
+   * @default true
+   */
+  readonly touch?: boolean;
+
+  /**
+   * Restore `initialValue` when a touch ends.
+   *
+   * @default false
+   */
+  readonly resetOnTouchEnds?: boolean;
+
+  /**
+   * Coordinates exposed before any input and during server rendering.
+   *
+   * @default { x: 0, y: 0 }
+   */
+  readonly initialValue?: Point;
+}
+
+/** Reactive pointer position returned by {@link useMouse}. */
+export interface MouseControls {
+  /** Latest horizontal coordinate. */
+  readonly x: Readonly<Ref<number>>;
+  /** Latest vertical coordinate. */
+  readonly y: Readonly<Ref<number>>;
+  /** Device that produced the latest coordinates; `null` before any input. */
+  readonly sourceType: Readonly<Ref<MouseSourceType | null>>;
+}
+
+/**
+ * Track the mouse (and optionally touch) position.
+ *
+ * Listens passively for `mousemove`, `dragover`, and touch events on the
+ * target; listeners follow the reactive target and are removed with the
+ * owning reactive scope. Server renders expose `initialValue` with a `null`
+ * source type.
+ *
+ * @param options Coordinate space, target, touch handling, and initial value.
+ * @default options {}
+ * @returns Reactive coordinates and input source.
+ */
+export function useMouse(options: UseMouseOptions = {}): MouseControls {
+  const { touch = true, resetOnTouchEnds = false } = options;
+  const initial = options.initialValue ?? { x: 0, y: 0 };
+  const extract = extractorFor(options.type ?? "page");
+  const x = ref(initial.x);
+  const y = ref(initial.y);
+  const sourceType = ref<MouseSourceType | null>(null);
+
+  const apply = (point: Point | null, source: MouseSourceType): void => {
+    if (!point) return;
+    x.value = point.x;
+    y.value = point.y;
+    sourceType.value = source;
+  };
+  const onMouse = (event: Event): void => {
+    if (isMouseEvent(event)) apply(extract(event), "mouse");
+  };
+  const onTouch = (event: Event): void => {
+    if (!isTouchEvent(event)) return;
+    const first = event.touches[0];
+    if (first) apply(extract(first), "touch");
+  };
+  const onTouchEnd = (): void => {
+    x.value = initial.x;
+    y.value = initial.y;
+  };
+
+  const stop = watch(
+    () => (options.target === undefined ? browserWindow() : toValue(options.target)),
+    (target, _previous, onCleanup) => {
+      if (!target) return;
+      const listenerOptions: AddEventListenerOptions = { passive: true };
+      target.addEventListener("mousemove", onMouse, listenerOptions);
+      target.addEventListener("dragover", onMouse, listenerOptions);
+      if (touch) {
+        target.addEventListener("touchstart", onTouch, listenerOptions);
+        target.addEventListener("touchmove", onTouch, listenerOptions);
+        if (resetOnTouchEnds) target.addEventListener("touchend", onTouchEnd, listenerOptions);
+      }
+      onCleanup(() => {
+        target.removeEventListener("mousemove", onMouse);
+        target.removeEventListener("dragover", onMouse);
+        target.removeEventListener("touchstart", onTouch);
+        target.removeEventListener("touchmove", onTouch);
+        target.removeEventListener("touchend", onTouchEnd);
+      });
+    },
+    { immediate: true },
+  );
+  tryOnScopeDispose(() => stop.stop());
+
+  return { x: readonly(x), y: readonly(y), sourceType: readonly(sourceType) };
+}
+
+function extractorFor(
+  type: MouseCoordinateType | MouseCoordinateExtractor,
+): MouseCoordinateExtractor {
+  if (typeof type === "function") return type;
+  switch (type) {
+    case "page":
+      return (input) => ({ x: input.pageX, y: input.pageY });
+    case "client":
+      return (input) => ({ x: input.clientX, y: input.clientY });
+    case "screen":
+      return (input) => ({ x: input.screenX, y: input.screenY });
+    case "movement":
+      return (input) => ("movementX" in input ? { x: input.movementX, y: input.movementY } : null);
+  }
+}
+
+function isMouseEvent(event: Event): event is MouseEvent {
+  return "clientX" in event && "button" in event;
+}
+
+function isTouchEvent(event: Event): event is TouchEvent {
+  return "touches" in event;
+}
+
+function browserWindow(): EventTarget | undefined {
+  return typeof window !== "undefined" ? window : undefined;
+}

package/registry/files/mutation-observer.ts

@@ -0,0 +1,183 @@
+import { hasInjectionContext, onMounted, readonly, ref, shallowRef, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, Ref, WatchHandle } from "vue";
+
+import { resolveElements } from "./element-target.ts";
+import type { MaybeElementTargets } from "./element-target.ts";
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Runtime capability that supplies the `MutationObserver` constructor. */
+export interface MutationObserverHost {
+  /** `MutationObserver` constructor, absent in unsupported runtimes. */
+  readonly MutationObserver?: new (callback: MutationCallback) => MutationObserver;
+}
+
+/** Options for {@link useMutationObserver}. */
+export interface UseMutationObserverOptions {
+  /**
+   * Observe attribute changes.
+   *
+   * @default false (implicitly `true` when `attributeFilter` or `attributeOldValue` is set)
+   */
+  readonly attributes?: boolean;
+
+  /**
+   * Observe child-list changes.
+   *
+   * @default false
+   */
+  readonly childList?: boolean;
+
+  /**
+   * Extend observation to the whole subtree.
+   *
+   * @default false
+   */
+  readonly subtree?: boolean;
+
+  /**
+   * Observe text-content changes.
+   *
+   * @default false (implicitly `true` when `characterDataOldValue` is set)
+   */
+  readonly characterData?: boolean;
+
+  /**
+   * Record the previous attribute value.
+   *
+   * @default false
+   */
+  readonly attributeOldValue?: boolean;
+
+  /**
+   * Record the previous text value.
+   *
+   * @default false
+   */
+  readonly characterDataOldValue?: boolean;
+
+  /**
+   * Restrict attribute observation to these local names.
+   *
+   * @default undefined (all attributes)
+   */
+  readonly attributeFilter?: readonly string[];
+
+  /**
+   * Reactive constructor capability for alternate runtimes and tests.
+   *
+   * @default globalThis when it provides `MutationObserver`
+   */
+  readonly host?: MaybeRefOrGetter<MutationObserverHost | null | undefined>;
+
+  /**
+   * Target resolution timing. `"post"` observes template refs after mount.
+   *
+   * @default "post"
+   */
+  readonly flush?: "pre" | "post" | "sync";
+}
+
+/** Controls returned by {@link useMutationObserver}. */
+export interface MutationObserverControls {
+  /** Whether the host provides `MutationObserver`. `false` during server rendering. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+
+  /**
+   * Drain the records queued by the active observer without invoking the
+   * callback.
+   *
+   * @returns Pending records, or an empty list without an active observer.
+   */
+  readonly takeRecords: () => MutationRecord[];
+
+  /** Disconnect permanently. Idempotent. */
+  readonly stop: () => void;
+}
+
+/**
+ * Observe DOM mutations of reactive elements.
+ *
+ * The observer is recreated when the resolved targets or host change and is
+ * disconnected when the owning reactive scope stops. At least one of
+ * `attributes`, `childList`, or `characterData` must be enabled (directly or
+ * implicitly), mirroring the platform contract. No work happens during
+ * server rendering.
+ *
+ * @param targets Reactive element target or list of targets.
+ * @param callback Native `MutationObserver` callback.
+ * @param options Observation filter, capability, and timing.
+ * @default options {}
+ * @returns Support flag, record draining, and stop control.
+ */
+export function useMutationObserver(
+  targets: MaybeElementTargets,
+  callback: MutationCallback,
+  options: UseMutationObserverOptions = {},
+): MutationObserverControls {
+  const isSupported = ref(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 init = observerInit(options);
+  let active: MutationObserver | undefined;
+  let stopWatch: WatchHandle | undefined = watch(
+    () =>
+      [
+        !mounted.value
+          ? undefined
+          : options.host === undefined
+            ? browserMutationObserverHost()
+            : toValue(options.host),
+        resolveElements(targets),
+      ] as const,
+    ([host, elements], _previous, onCleanup) => {
+      const Observer = host?.MutationObserver;
+      isSupported.value = Observer !== undefined;
+      if (!Observer || elements.length === 0) return;
+      const observer = new Observer(callback);
+      for (const element of elements) observer.observe(element, init);
+      active = observer;
+      onCleanup(() => {
+        observer.disconnect();
+        if (active === observer) active = undefined;
+      });
+    },
+    { immediate: true, flush: options.flush ?? "post" },
+  );
+
+  const stop = (): void => {
+    stopWatch?.stop();
+    stopWatch = undefined;
+  };
+  tryOnScopeDispose(stop);
+
+  return {
+    isSupported: readonly(isSupported),
+    takeRecords: () => active?.takeRecords() ?? [],
+    stop,
+  };
+}
+
+function observerInit(options: UseMutationObserverOptions): MutationObserverInit {
+  const init: MutationObserverInit = {};
+  if (options.attributes !== undefined) init.attributes = options.attributes;
+  if (options.childList !== undefined) init.childList = options.childList;
+  if (options.subtree !== undefined) init.subtree = options.subtree;
+  if (options.characterData !== undefined) init.characterData = options.characterData;
+  if (options.attributeOldValue !== undefined) init.attributeOldValue = options.attributeOldValue;
+  if (options.characterDataOldValue !== undefined) {
+    init.characterDataOldValue = options.characterDataOldValue;
+  }
+  if (options.attributeFilter !== undefined) init.attributeFilter = [...options.attributeFilter];
+  return init;
+}
+
+function browserMutationObserverHost(): MutationObserverHost | undefined {
+  return typeof MutationObserver === "function" ? globalThis : undefined;
+}