@vizejs/composable 0.426.2 → 0.427.0

package/registry/files/on-long-press.ts

@@ -0,0 +1,188 @@
+import { watch } 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";
+
+/** Event modifiers applied to the pointer events handled by {@link onLongPress}. */
+export interface LongPressModifiers {
+  /** Call `stopPropagation()`. */
+  readonly stop?: boolean;
+  /** Fire at most once. */
+  readonly once?: boolean;
+  /** Call `preventDefault()`. */
+  readonly prevent?: boolean;
+  /** Listen in the capture phase. */
+  readonly capture?: boolean;
+  /** Only start when the element itself (not a descendant) is pressed. */
+  readonly self?: boolean;
+}
+
+/** Summary passed to {@link OnLongPressOptions.onRelease}. */
+export interface LongPressRelease {
+  /** Milliseconds between press and release. */
+  readonly duration: number;
+  /** Pointer travel in CSS pixels. */
+  readonly distance: number;
+  /** Whether the long-press handler fired. */
+  readonly isLongPress: boolean;
+}
+
+/** Options for {@link onLongPress}. */
+export interface OnLongPressOptions {
+  /**
+   * Hold time in milliseconds.
+   *
+   * @default 500
+   */
+  readonly delay?: number;
+
+  /**
+   * Maximum pointer travel before the press is cancelled.
+   *
+   * @default 10
+   */
+  readonly distanceThreshold?: number;
+
+  /**
+   * Event modifiers.
+   *
+   * @default {}
+   */
+  readonly modifiers?: LongPressModifiers;
+
+  /**
+   * Called on every release with timing details.
+   *
+   * @default undefined
+   */
+  readonly onRelease?: (release: LongPressRelease, event: PointerEvent) => void;
+
+  /**
+   * Clock for durations.
+   *
+   * @default Date.now
+   */
+  readonly now?: () => number;
+
+  /**
+   * Owns the hold 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>);
+  },
+};
+
+/**
+ * Call a handler when an element is pressed and held.
+ *
+ * Uses Pointer Events, so mouse, touch, and pen behave alike. Moving more than
+ * `distanceThreshold` or releasing early cancels the press. Nothing is
+ * registered during server rendering; listeners and the timer are released
+ * with the owning scope or the returned stop function.
+ *
+ * @param target Reactive element target.
+ * @param handler Called with the initiating `pointerdown` event.
+ * @param options Delay, threshold, modifiers, and callbacks.
+ * @default options {}
+ * @returns Stop function.
+ */
+export function onLongPress(
+  target: MaybeElementTarget,
+  handler: (event: PointerEvent) => void,
+  options: OnLongPressOptions = {},
+): () => void {
+  const {
+    delay = 500,
+    distanceThreshold = 10,
+    modifiers = {},
+    now = Date.now,
+    scheduler = defaultScheduler,
+  } = options;
+  let handle: unknown;
+  let pending = false;
+  let fired = false;
+  let used = false;
+  let start: { readonly x: number; readonly y: number; readonly time: number } | null = null;
+
+  const clear = (): void => {
+    if (pending) scheduler.clearTimeout(handle);
+    pending = false;
+  };
+  const apply = (event: PointerEvent): void => {
+    if (modifiers.prevent && event.cancelable) event.preventDefault();
+    if (modifiers.stop) event.stopPropagation();
+  };
+
+  const stopWatch = watch(
+    () => resolveElement(target),
+    (element, _previous, onCleanup) => {
+      if (!element) return;
+      const onDown = (event: Event): void => {
+        if (!isPointerEvent(event) || (modifiers.once && used)) return;
+        if (modifiers.self && event.target !== element) return;
+        apply(event);
+        clear();
+        fired = false;
+        start = { x: event.clientX, y: event.clientY, time: now() };
+        pending = true;
+        handle = scheduler.setTimeout(() => {
+          pending = false;
+          fired = true;
+          used = true;
+          handler(event);
+        }, delay);
+      };
+      const onMove = (event: Event): void => {
+        if (!isPointerEvent(event) || !start || !pending) return;
+        if (Math.hypot(event.clientX - start.x, event.clientY - start.y) > distanceThreshold) {
+          clear();
+        }
+      };
+      const onUp = (event: Event): void => {
+        if (!isPointerEvent(event) || !start) return;
+        apply(event);
+        const release: LongPressRelease = {
+          duration: now() - start.time,
+          distance: Math.hypot(event.clientX - start.x, event.clientY - start.y),
+          isLongPress: fired,
+        };
+        clear();
+        start = null;
+        options.onRelease?.(release, event);
+      };
+      const listenerOptions: AddEventListenerOptions = { capture: modifiers.capture ?? false };
+      element.addEventListener("pointerdown", onDown, listenerOptions);
+      element.addEventListener("pointermove", onMove, listenerOptions);
+      element.addEventListener("pointerup", onUp, listenerOptions);
+      element.addEventListener("pointerleave", onUp, listenerOptions);
+      element.addEventListener("pointercancel", onUp, listenerOptions);
+      onCleanup(() => {
+        const removeOptions: EventListenerOptions = { capture: modifiers.capture ?? false };
+        element.removeEventListener("pointerdown", onDown, removeOptions);
+        element.removeEventListener("pointermove", onMove, removeOptions);
+        element.removeEventListener("pointerup", onUp, removeOptions);
+        element.removeEventListener("pointerleave", onUp, removeOptions);
+        element.removeEventListener("pointercancel", onUp, removeOptions);
+        clear();
+        start = null;
+      });
+    },
+    { immediate: true, flush: "post" },
+  );
+  const stop = (): void => stopWatch.stop();
+  tryOnScopeDispose(stop);
+  return stop;
+}
+
+function isPointerEvent(event: Event): event is PointerEvent {
+  return "pointerId" in event && "clientX" in event;
+}

package/registry/files/on-start-typing.ts

@@ -0,0 +1,88 @@
+import { toValue, watch } from "vue";
+import type { MaybeRefOrGetter } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Document-like capability observed by {@link onStartTyping}. */
+export interface StartTypingHost extends EventTarget {
+  /** Currently focused element. */
+  readonly activeElement: Element | null;
+}
+
+/** Options for {@link onStartTyping}. */
+export interface OnStartTypingOptions {
+  /**
+   * Reactive document capability for alternate runtimes and tests.
+   *
+   * @default globalThis.document when available
+   */
+  readonly host?: MaybeRefOrGetter<StartTypingHost | null | undefined>;
+}
+
+/**
+ * Whether a keyboard event would type a printable character.
+ *
+ * Single-character keys (letters, digits, punctuation; not space) without
+ * `ctrl`/`meta`/`alt` qualify.
+ *
+ * @param event Keyboard event.
+ * @returns Whether the event starts typing.
+ */
+export function isTypingKeystroke(event: KeyboardEvent): boolean {
+  if (event.ctrlKey || event.metaKey || event.altKey) return false;
+  return event.key.length === 1 && event.key !== " ";
+}
+
+/**
+ * Call a handler when the user starts typing while no editable element has
+ * focus — typically to focus a search field.
+ *
+ * Editable means `input`, `textarea`, `select`, or any element with
+ * `isContentEditable`, and elements with `role="textbox"`/`"searchbox"`/`"combobox"`.
+ * Nothing is registered during server rendering; the listener is removed with
+ * the owning scope or the returned stop function.
+ *
+ * @param handler Called with the initiating `keydown` event.
+ * @param options Document capability.
+ * @default options {}
+ * @returns Stop function.
+ */
+export function onStartTyping(
+  handler: (event: KeyboardEvent) => void,
+  options: OnStartTypingOptions = {},
+): () => void {
+  const stop = watch(
+    () => (options.host === undefined ? browserTypingHost() : toValue(options.host)),
+    (host, _previous, onCleanup) => {
+      if (!host) return;
+      const onKeyDown = (event: Event): void => {
+        if (!isKeyboardEvent(event) || event.defaultPrevented) return;
+        if (isEditable(host.activeElement) || !isTypingKeystroke(event)) return;
+        handler(event);
+      };
+      host.addEventListener("keydown", onKeyDown, { passive: true });
+      onCleanup(() => host.removeEventListener("keydown", onKeyDown));
+    },
+    { immediate: true },
+  );
+  const dispose = (): void => stop.stop();
+  tryOnScopeDispose(dispose);
+  return dispose;
+}
+
+function isEditable(element: Element | null): boolean {
+  if (!element) return false;
+  const tag = element.tagName;
+  if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return true;
+  if ("isContentEditable" in element && element.isContentEditable === true) return true;
+  const role = element.getAttribute?.("role");
+  return role === "textbox" || role === "searchbox" || role === "combobox";
+}
+
+function isKeyboardEvent(event: Event): event is KeyboardEvent {
+  return "key" in event && "code" in event;
+}
+
+function browserTypingHost(): StartTypingHost | undefined {
+  return typeof document !== "undefined" ? document : undefined;
+}

package/registry/files/page-leave.ts

@@ -0,0 +1,57 @@
+import { readonly, ref, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, Ref } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Options for {@link usePageLeave}. */
+export interface UsePageLeaveOptions {
+  /**
+   * Window-like target that receives `mouseout`/`mouseover`.
+   *
+   * @default globalThis.window when available
+   */
+  readonly host?: MaybeRefOrGetter<EventTarget | null | undefined>;
+}
+
+/**
+ * Detect when the mouse leaves the page (for exit-intent UI).
+ *
+ * A `mouseout` without a `relatedTarget` means the pointer left the
+ * document; any `mouseover` means it came back. Server renders report
+ * `false`; listeners are removed with the owning reactive scope.
+ *
+ * @param options Window capability.
+ * @default options {}
+ * @returns Readonly ref that is `true` while the pointer is outside the page.
+ */
+export function usePageLeave(options: UsePageLeaveOptions = {}): Readonly<Ref<boolean>> {
+  const left = ref(false);
+  const onOut = (event: Event): void => {
+    const related = "relatedTarget" in event ? event.relatedTarget : null;
+    left.value = related === null || related === undefined;
+  };
+  const onOver = (): void => {
+    left.value = false;
+  };
+
+  const stop = watch(
+    () => (options.host === undefined ? browserPageHost() : toValue(options.host)),
+    (host, _previous, onCleanup) => {
+      if (!host) return;
+      host.addEventListener("mouseout", onOut, { passive: true });
+      host.addEventListener("mouseover", onOver, { passive: true });
+      onCleanup(() => {
+        host.removeEventListener("mouseout", onOut);
+        host.removeEventListener("mouseover", onOver);
+      });
+    },
+    { immediate: true },
+  );
+  tryOnScopeDispose(() => stop.stop());
+
+  return readonly(left);
+}
+
+function browserPageHost(): EventTarget | undefined {
+  return typeof window !== "undefined" ? window : undefined;
+}

package/registry/files/parent-element.ts

@@ -0,0 +1,29 @@
+import { shallowRef, watch } from "vue";
+import type { ShallowRef } from "vue";
+
+import { isElementNode, resolveElement } from "./element-target.ts";
+import type { MaybeElementTarget } from "./element-target.ts";
+import { tryOnScopeDispose } from "./scope.ts";
+
+/**
+ * Track the parent element of a reactive element target.
+ *
+ * Re-reads `parentElement` whenever the target resolves or changes (after
+ * the DOM update). Server renders expose `null`.
+ *
+ * @param target Reactive element target.
+ * @returns Readonly shallow ref of the parent element.
+ */
+export function useParentElement(target: MaybeElementTarget): Readonly<ShallowRef<Element | null>> {
+  const parent = shallowRef<Element | null>(null);
+  const stop = watch(
+    () => resolveElement(target),
+    (element) => {
+      const candidate: unknown = element?.parentElement ?? null;
+      parent.value = isElementNode(candidate) ? candidate : null;
+    },
+    { immediate: true, flush: "post" },
+  );
+  tryOnScopeDispose(() => stop.stop());
+  return parent;
+}

package/registry/files/pinch.ts

@@ -0,0 +1,187 @@
+import { readonly, ref, shallowReactive, shallowReadonly, watch } from "vue";
+import type { Ref } from "vue";
+
+import { resolveElement } from "./element-target.ts";
+import type { MaybeElementTarget } from "./element-target.ts";
+import type { Point } from "./mouse.ts";
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** Snapshot passed to pinch callbacks. */
+export interface PinchSnapshot {
+  /** Scale relative to the start of the gesture (`1` = unchanged). */
+  readonly scale: number;
+  /** Rotation relative to the start of the gesture, in degrees. */
+  readonly rotation: number;
+  /** Midpoint between the two pointers in client coordinates. */
+  readonly origin: Point;
+  /** Current distance between the two pointers. */
+  readonly distance: number;
+}
+
+/** Options for {@link usePinch}. */
+export interface UsePinchOptions {
+  /**
+   * Called when a second pointer starts a pinch.
+   *
+   * @default undefined
+   */
+  readonly onPinchStart?: (snapshot: PinchSnapshot) => void;
+
+  /**
+   * Called on every move while pinching.
+   *
+   * @default undefined
+   */
+  readonly onPinch?: (snapshot: PinchSnapshot) => void;
+
+  /**
+   * Called when one of the two pointers lifts.
+   *
+   * @default undefined
+   */
+  readonly onPinchEnd?: (snapshot: PinchSnapshot) => void;
+}
+
+/** Reactive gesture state returned by {@link usePinch}. */
+export interface PinchControls {
+  /** Whether two pointers are currently pinching. */
+  readonly isPinching: Readonly<Ref<boolean>>;
+  /** Scale relative to the gesture start; stays at the final value after the gesture. */
+  readonly scale: Readonly<Ref<number>>;
+  /** Rotation relative to the gesture start in degrees. */
+  readonly rotation: Readonly<Ref<number>>;
+  /** Distance between the pointers when the gesture started. */
+  readonly initialDistance: Readonly<Ref<number>>;
+  /** Current distance between the pointers. */
+  readonly distance: Readonly<Ref<number>>;
+  /** Midpoint between the pointers. */
+  readonly origin: Readonly<Point>;
+  /** Restore scale `1` and rotation `0`. */
+  readonly reset: () => void;
+  /** Remove listeners. Idempotent. */
+  readonly stop: () => void;
+}
+
+/**
+ * Recognize two-pointer pinch/rotate gestures on an element.
+ *
+ * Tracks active pointers with Pointer Events (touch, pen, or mouse chords).
+ * The first two pointers define the gesture; additional pointers are
+ * ignored. Pair it with `touch-action: none` on the element so the browser
+ * does not claim the gesture for zooming. Server renders expose scale `1`,
+ * rotation `0`, and `isPinching: false`.
+ *
+ * @param target Reactive element target.
+ * @param options Gesture lifecycle callbacks.
+ * @default options {}
+ * @returns Reactive gesture state plus reset/stop controls.
+ */
+export function usePinch(target: MaybeElementTarget, options: UsePinchOptions = {}): PinchControls {
+  const isPinching = ref(false);
+  const scale = ref(1);
+  const rotation = ref(0);
+  const initialDistance = ref(0);
+  const distance = ref(0);
+  const origin = shallowReactive({ x: 0, y: 0 });
+  const pointers = new Map<number, Point>();
+  let initialAngle = 0;
+
+  const pair = (): readonly [Point, Point] | null => {
+    const [first, second] = pointers.values();
+    return first && second ? [first, second] : null;
+  };
+  const snapshot = (): PinchSnapshot => ({
+    scale: scale.value,
+    rotation: rotation.value,
+    origin: { x: origin.x, y: origin.y },
+    distance: distance.value,
+  });
+  const measure = (first: Point, second: Point): { distance: number; angle: number } => {
+    origin.x = (first.x + second.x) / 2;
+    origin.y = (first.y + second.y) / 2;
+    return {
+      distance: Math.hypot(second.x - first.x, second.y - first.y),
+      angle: (Math.atan2(second.y - first.y, second.x - first.x) * 180) / Math.PI,
+    };
+  };
+
+  const onDown = (event: Event): void => {
+    if (!isPointerEvent(event) || pointers.size >= 2) return;
+    pointers.set(event.pointerId, { x: event.clientX, y: event.clientY });
+    const points = pair();
+    if (!points) return;
+    const measured = measure(...points);
+    initialDistance.value = measured.distance;
+    distance.value = measured.distance;
+    initialAngle = measured.angle;
+    scale.value = 1;
+    rotation.value = 0;
+    isPinching.value = true;
+    options.onPinchStart?.(snapshot());
+  };
+  const onMove = (event: Event): void => {
+    if (!isPointerEvent(event) || !pointers.has(event.pointerId)) return;
+    pointers.set(event.pointerId, { x: event.clientX, y: event.clientY });
+    const points = pair();
+    if (!points || !isPinching.value) return;
+    const measured = measure(...points);
+    distance.value = measured.distance;
+    scale.value = initialDistance.value === 0 ? 1 : measured.distance / initialDistance.value;
+    rotation.value = normalizeDegrees(measured.angle - initialAngle);
+    options.onPinch?.(snapshot());
+  };
+  const onUp = (event: Event): void => {
+    if (!isPointerEvent(event) || !pointers.delete(event.pointerId)) return;
+    if (!isPinching.value) return;
+    isPinching.value = false;
+    options.onPinchEnd?.(snapshot());
+  };
+
+  const stopWatch = watch(
+    () => resolveElement(target),
+    (element, _previous, onCleanup) => {
+      if (!element) return;
+      const listenerOptions: AddEventListenerOptions = { passive: true };
+      element.addEventListener("pointerdown", onDown, listenerOptions);
+      element.addEventListener("pointermove", onMove, listenerOptions);
+      for (const type of ["pointerup", "pointercancel", "pointerleave"] as const) {
+        element.addEventListener(type, onUp, listenerOptions);
+      }
+      onCleanup(() => {
+        element.removeEventListener("pointerdown", onDown);
+        element.removeEventListener("pointermove", onMove);
+        for (const type of ["pointerup", "pointercancel", "pointerleave"] as const) {
+          element.removeEventListener(type, onUp);
+        }
+        pointers.clear();
+        isPinching.value = false;
+      });
+    },
+    { immediate: true, flush: "post" },
+  );
+  const stop = (): void => stopWatch.stop();
+  tryOnScopeDispose(stop);
+
+  return {
+    isPinching: readonly(isPinching),
+    scale: readonly(scale),
+    rotation: readonly(rotation),
+    initialDistance: readonly(initialDistance),
+    distance: readonly(distance),
+    origin: shallowReadonly(origin),
+    reset: () => {
+      scale.value = 1;
+      rotation.value = 0;
+    },
+    stop,
+  };
+}
+
+function normalizeDegrees(value: number): number {
+  const wrapped = ((((value + 180) % 360) + 360) % 360) - 180;
+  return wrapped === -180 ? 180 : wrapped;
+}
+
+function isPointerEvent(event: Event): event is PointerEvent {
+  return "pointerId" in event && "clientX" in event;
+}