@vizejs/composable 0.426.3 → 0.428.0

package/dist/on-long-press.mjs

@@ -0,0 +1,105 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { resolveElement } from "./element-target.mjs";
+import { watch } from "vue";
+//#region src/on-long-press.ts
+const defaultScheduler = {
+	setTimeout: (callback, delayMs) => globalThis.setTimeout(callback, delayMs),
+	clearTimeout: (handle) => {
+		globalThis.clearTimeout(handle);
+	}
+};
+/**
+* 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.
+*/
+function onLongPress(target, handler, options = {}) {
+	const { delay = 500, distanceThreshold = 10, modifiers = {}, now = Date.now, scheduler = defaultScheduler } = options;
+	let handle;
+	let pending = false;
+	let fired = false;
+	let used = false;
+	let start = null;
+	const clear = () => {
+		if (pending) scheduler.clearTimeout(handle);
+		pending = false;
+	};
+	const apply = (event) => {
+		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) => {
+			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) => {
+			if (!isPointerEvent(event) || !start || !pending) return;
+			if (Math.hypot(event.clientX - start.x, event.clientY - start.y) > distanceThreshold) clear();
+		};
+		const onUp = (event) => {
+			if (!isPointerEvent(event) || !start) return;
+			apply(event);
+			const release = {
+				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 = { 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 = { 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 = () => stopWatch.stop();
+	tryOnScopeDispose(stop);
+	return stop;
+}
+function isPointerEvent(event) {
+	return "pointerId" in event && "clientX" in event;
+}
+//#endregion
+export { onLongPress };

package/dist/on-start-typing.d.mts

@@ -0,0 +1,44 @@
+import { MaybeRefOrGetter } from "vue";
+
+//#region src/on-start-typing.d.ts
+/** Document-like capability observed by {@link onStartTyping}. */
+interface StartTypingHost extends EventTarget {
+  /** Currently focused element. */
+  readonly activeElement: Element | null;
+}
+/** Options for {@link onStartTyping}. */
+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.
+ */
+declare function isTypingKeystroke(event: KeyboardEvent): boolean;
+/**
+ * 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.
+ */
+declare function onStartTyping(handler: (event: KeyboardEvent) => void, options?: OnStartTypingOptions): () => void;
+//#endregion
+export { OnStartTypingOptions, StartTypingHost, isTypingKeystroke, onStartTyping };

package/dist/on-start-typing.mjs

@@ -0,0 +1,61 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { toValue, watch } from "vue";
+//#region src/on-start-typing.ts
+/**
+* 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.
+*/
+function isTypingKeystroke(event) {
+	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.
+*/
+function onStartTyping(handler, options = {}) {
+	const stop = watch(() => options.host === void 0 ? browserTypingHost() : toValue(options.host), (host, _previous, onCleanup) => {
+		if (!host) return;
+		const onKeyDown = (event) => {
+			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 = () => stop.stop();
+	tryOnScopeDispose(dispose);
+	return dispose;
+}
+function isEditable(element) {
+	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) {
+	return "key" in event && "code" in event;
+}
+function browserTypingHost() {
+	return typeof document !== "undefined" ? document : void 0;
+}
+//#endregion
+export { isTypingKeystroke, onStartTyping };

package/dist/page-leave.d.mts

@@ -0,0 +1,26 @@
+import { MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/page-leave.d.ts
+/** Options for {@link usePageLeave}. */
+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.
+ */
+declare function usePageLeave(options?: UsePageLeaveOptions): Readonly<Ref<boolean>>;
+//#endregion
+export { UsePageLeaveOptions, usePageLeave };

package/dist/page-leave.mjs

@@ -0,0 +1,40 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { readonly, ref, toValue, watch } from "vue";
+//#region src/page-leave.ts
+/**
+* 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.
+*/
+function usePageLeave(options = {}) {
+	const left = ref(false);
+	const onOut = (event) => {
+		const related = "relatedTarget" in event ? event.relatedTarget : null;
+		left.value = related === null || related === void 0;
+	};
+	const onOver = () => {
+		left.value = false;
+	};
+	const stop = watch(() => options.host === void 0 ? 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() {
+	return typeof window !== "undefined" ? window : void 0;
+}
+//#endregion
+export { usePageLeave };

package/dist/parent-element.d.mts

@@ -0,0 +1,16 @@
+import { n as MaybeElementTarget } from "./element-target-Crpxl4D9.mjs";
+import { ShallowRef } from "vue";
+
+//#region src/parent-element.d.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.
+ */
+declare function useParentElement(target: MaybeElementTarget): Readonly<ShallowRef<Element | null>>;
+//#endregion
+export { useParentElement };

package/dist/parent-element.mjs

@@ -0,0 +1,27 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { isElementNode, resolveElement } from "./element-target.mjs";
+import { shallowRef, watch } from "vue";
+//#region src/parent-element.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.
+*/
+function useParentElement(target) {
+	const parent = shallowRef(null);
+	const stop = watch(() => resolveElement(target), (element) => {
+		const candidate = element?.parentElement ?? null;
+		parent.value = isElementNode(candidate) ? candidate : null;
+	}, {
+		immediate: true,
+		flush: "post"
+	});
+	tryOnScopeDispose(() => stop.stop());
+	return parent;
+}
+//#endregion
+export { useParentElement };

package/dist/pinch.d.mts

@@ -0,0 +1,73 @@
+import { n as MaybeElementTarget } from "./element-target-Crpxl4D9.mjs";
+import { Point } from "./mouse.mjs";
+import { Ref } from "vue";
+
+//#region src/pinch.d.ts
+/** Snapshot passed to pinch callbacks. */
+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}. */
+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}. */
+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.
+ */
+declare function usePinch(target: MaybeElementTarget, options?: UsePinchOptions): PinchControls;
+//#endregion
+export { PinchControls, PinchSnapshot, UsePinchOptions, usePinch };

package/dist/pinch.mjs

@@ -0,0 +1,138 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { resolveElement } from "./element-target.mjs";
+import { readonly, ref, shallowReactive, shallowReadonly, watch } from "vue";
+//#region src/pinch.ts
+/**
+* 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.
+*/
+function usePinch(target, options = {}) {
+	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 = /* @__PURE__ */ new Map();
+	let initialAngle = 0;
+	const pair = () => {
+		const [first, second] = pointers.values();
+		return first && second ? [first, second] : null;
+	};
+	const snapshot = () => ({
+		scale: scale.value,
+		rotation: rotation.value,
+		origin: {
+			x: origin.x,
+			y: origin.y
+		},
+		distance: distance.value
+	});
+	const measure = (first, second) => {
+		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) => {
+		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) => {
+		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) => {
+		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 = { passive: true };
+		element.addEventListener("pointerdown", onDown, listenerOptions);
+		element.addEventListener("pointermove", onMove, listenerOptions);
+		for (const type of [
+			"pointerup",
+			"pointercancel",
+			"pointerleave"
+		]) element.addEventListener(type, onUp, listenerOptions);
+		onCleanup(() => {
+			element.removeEventListener("pointerdown", onDown);
+			element.removeEventListener("pointermove", onMove);
+			for (const type of [
+				"pointerup",
+				"pointercancel",
+				"pointerleave"
+			]) element.removeEventListener(type, onUp);
+			pointers.clear();
+			isPinching.value = false;
+		});
+	}, {
+		immediate: true,
+		flush: "post"
+	});
+	const stop = () => 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) {
+	const wrapped = ((value + 180) % 360 + 360) % 360 - 180;
+	return wrapped === -180 ? 180 : wrapped;
+}
+function isPointerEvent(event) {
+	return "pointerId" in event && "clientX" in event;
+}
+//#endregion
+export { usePinch };

package/dist/pointer-lock.d.mts

@@ -0,0 +1,79 @@
+import { n as MaybeElementTarget } from "./element-target-Crpxl4D9.mjs";
+import { MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+//#region src/pointer-lock.d.ts
+/** Document-like capability used by {@link usePointerLock}. */
+interface PointerLockHost extends EventTarget {
+  /** Element that currently holds the pointer lock. */
+  readonly pointerLockElement: Element | null;
+  /** Release the pointer lock. */
+  exitPointerLock(): void;
+}
+/** Stable error codes rejected by {@link PointerLockControls.lock} and `unlock`. */
+type PointerLockErrorCode = "VIZE_COMPOSE_POINTER_LOCK_UNSUPPORTED" | "VIZE_COMPOSE_POINTER_LOCK_NO_TARGET" | "VIZE_COMPOSE_POINTER_LOCK_FAILED";
+/** Error thrown when pointer lock cannot be acquired or released. */
+declare class PointerLockError extends Error {
+  /** Machine-readable failure code. */
+  readonly code: PointerLockErrorCode;
+  /**
+   * @param code Machine-readable failure code.
+   * @param message Human-readable explanation.
+   */
+  constructor(code: PointerLockErrorCode, message: string);
+}
+/** Options for {@link usePointerLock}. */
+interface UsePointerLockOptions {
+  /**
+   * Request raw (unaccelerated) movement deltas where supported.
+   *
+   * @default false
+   */
+  readonly unadjustedMovement?: boolean;
+  /**
+   * Reactive document capability for alternate runtimes and tests.
+   *
+   * @default globalThis.document when available
+   */
+  readonly host?: MaybeRefOrGetter<PointerLockHost | null | undefined>;
+}
+/** Reactive state and actions returned by {@link usePointerLock}. */
+interface PointerLockControls {
+  /** Whether the host supports pointer lock. `false` during server rendering. */
+  readonly isSupported: Readonly<Ref<boolean>>;
+  /** Element currently holding the lock (any element, not only the target). */
+  readonly element: Readonly<ShallowRef<Element | null>>;
+  /** Whether the composable's own target holds the lock. */
+  readonly isLocked: Readonly<Ref<boolean>>;
+  /**
+   * Lock the pointer to `target` (or the composable target).
+   *
+   * @returns The locked element once `pointerlockchange` confirms the lock.
+   */
+  readonly lock: (target?: MaybeElementTarget) => Promise<Element>;
+  /**
+   * Release the lock.
+   *
+   * @returns Whether a lock was held and released.
+   */
+  readonly unlock: () => Promise<boolean>;
+}
+/**
+ * Reactive wrapper around the Pointer Lock API.
+ *
+ * Tracks `pointerlockchange` on the document and exposes promise-based lock
+ * and unlock actions that settle on the platform confirmation events.
+ * Rejections are {@link PointerLockError}s with stable codes. Nothing runs
+ * during server rendering; listeners are removed with the owning scope.
+ *
+ * Inside a component the host is read after mounting, so hydration renders
+ * the server fallback first and never mismatches.
+ *
+ * @param target Default reactive element to lock.
+ * @param options Movement mode and document capability.
+ * @default target undefined
+ * @default options {}
+ * @returns Support flag, lock state, and actions.
+ */
+declare function usePointerLock(target?: MaybeElementTarget, options?: UsePointerLockOptions): PointerLockControls;
+//#endregion
+export { PointerLockControls, PointerLockError, PointerLockErrorCode, PointerLockHost, UsePointerLockOptions, usePointerLock };