@vizejs/composable 0.426.2 → 0.427.0

package/dist/draggable.d.mts

@@ -0,0 +1,121 @@
+import { n as MaybeElementTarget } from "./element-target-Crpxl4D9.mjs";
+import { Point } from "./mouse.mjs";
+import { PointerKind } from "./pointer.mjs";
+import { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/draggable.d.ts
+/** Axis constraint for {@link useDraggable}. */
+type DragAxis = "x" | "y" | "both";
+/** Rectangle (in the same coordinate space as the position) that bounds dragging. */
+interface DragBounds {
+  /** Minimum x. */
+  readonly left: number;
+  /** Minimum y. */
+  readonly top: number;
+  /** Maximum x of the dragged element's right edge. */
+  readonly right: number;
+  /** Maximum y of the dragged element's bottom edge. */
+  readonly bottom: number;
+}
+/** Options for {@link useDraggable}. */
+interface UseDraggableOptions {
+  /**
+   * Element that starts the drag. Defaults to the dragged element itself.
+   *
+   * @default undefined (the target)
+   */
+  readonly handle?: MaybeElementTarget;
+  /**
+   * Restrict movement to one axis.
+   *
+   * @default "both"
+   */
+  readonly axis?: MaybeRefOrGetter<DragAxis>;
+  /**
+   * Keep the element inside these bounds, or inside a container element's
+   * client rectangle.
+   *
+   * @default undefined (unbounded)
+   */
+  readonly bounds?: MaybeRefOrGetter<DragBounds | null | undefined> | MaybeElementTarget;
+  /**
+   * Position before the first drag and during server rendering.
+   *
+   * @default { x: 0, y: 0 }
+   */
+  readonly initialValue?: Point;
+  /**
+   * Device kinds that may start a drag.
+   *
+   * @default ["mouse", "touch", "pen"]
+   */
+  readonly pointerTypes?: readonly PointerKind[];
+  /**
+   * Only start when the pointer goes down on the handle itself, not a descendant.
+   *
+   * @default false
+   */
+  readonly exact?: boolean;
+  /**
+   * Call `preventDefault()` on pointer events while dragging.
+   *
+   * @default false
+   */
+  readonly preventDefault?: boolean;
+  /**
+   * Temporarily disable dragging.
+   *
+   * @default false
+   */
+  readonly disabled?: MaybeRefOrGetter<boolean>;
+  /**
+   * Called before a drag starts. Return `false` to cancel it.
+   *
+   * @default undefined
+   */
+  readonly onStart?: (position: Point, event: PointerEvent) => boolean | void;
+  /**
+   * Called after every position update.
+   *
+   * @default undefined
+   */
+  readonly onMove?: (position: Point, event: PointerEvent) => void;
+  /**
+   * Called when the drag ends.
+   *
+   * @default undefined
+   */
+  readonly onEnd?: (position: Point, event: PointerEvent) => void;
+}
+/** Reactive drag state returned by {@link useDraggable}. */
+interface DraggableControls {
+  /** Horizontal position (the element's left edge in client coordinates). */
+  readonly x: Ref<number>;
+  /** Vertical position (the element's top edge in client coordinates). */
+  readonly y: Ref<number>;
+  /** Current position snapshot. */
+  readonly position: ComputedRef<Point>;
+  /** Whether a drag is in progress. */
+  readonly isDragging: Readonly<Ref<boolean>>;
+  /** `left`/`top` declaration for `position: fixed` or `absolute` placement. */
+  readonly style: ComputedRef<string>;
+  /** Remove listeners. Idempotent. */
+  readonly stop: () => void;
+}
+/**
+ * Make an element draggable with Pointer Events.
+ *
+ * `pointerdown` on the handle records the offset between the pointer and the
+ * element; moves are tracked on the owner document (so fast drags that leave
+ * the element keep working) and constrained by `axis` and `bounds`. `x`/`y`
+ * are writable for programmatic placement. Server renders expose
+ * `initialValue`; listeners are removed with the owning reactive scope.
+ *
+ * @param target Reactive element being dragged.
+ * @param options Handle, axis, bounds, device filter, and lifecycle callbacks.
+ * @default options {}
+ * @returns Writable position, drag flag, inline style, and stop control.
+ */
+declare function useDraggable(target: MaybeElementTarget, options?: UseDraggableOptions): DraggableControls;
+//#endregion
+export { DragAxis, DragBounds, DraggableControls, UseDraggableOptions, useDraggable };

package/dist/draggable.mjs

@@ -0,0 +1,153 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { isElementNode, resolveElement } from "./element-target.mjs";
+import { toPointerKind } from "./pointer.mjs";
+import { computed, readonly, ref, toValue, watch } from "vue";
+//#region src/draggable.ts
+/**
+* Make an element draggable with Pointer Events.
+*
+* `pointerdown` on the handle records the offset between the pointer and the
+* element; moves are tracked on the owner document (so fast drags that leave
+* the element keep working) and constrained by `axis` and `bounds`. `x`/`y`
+* are writable for programmatic placement. Server renders expose
+* `initialValue`; listeners are removed with the owning reactive scope.
+*
+* @param target Reactive element being dragged.
+* @param options Handle, axis, bounds, device filter, and lifecycle callbacks.
+* @default options {}
+* @returns Writable position, drag flag, inline style, and stop control.
+*/
+function useDraggable(target, options = {}) {
+	const initial = options.initialValue ?? {
+		x: 0,
+		y: 0
+	};
+	const x = ref(initial.x);
+	const y = ref(initial.y);
+	const isDragging = ref(false);
+	const pointerTypes = options.pointerTypes ?? [
+		"mouse",
+		"touch",
+		"pen"
+	];
+	const position = computed(() => ({
+		x: x.value,
+		y: y.value
+	}));
+	let offset = null;
+	let activePointer = null;
+	const constrain = (element, next) => {
+		const bounds = readBounds(options.bounds);
+		if (!bounds) return next;
+		const rect = element.getBoundingClientRect();
+		return {
+			x: clamp(next.x, bounds.left, Math.max(bounds.left, bounds.right - rect.width)),
+			y: clamp(next.y, bounds.top, Math.max(bounds.top, bounds.bottom - rect.height))
+		};
+	};
+	const accepts = (event) => {
+		if (!isPointerEvent(event)) return false;
+		const kind = toPointerKind(event.pointerType);
+		return kind !== null && pointerTypes.includes(kind);
+	};
+	const handleEvent = (event) => {
+		if (options.preventDefault && event.cancelable) event.preventDefault();
+	};
+	const stopWatch = watch(() => [resolveElement(target), options.handle === void 0 ? void 0 : resolveElement(options.handle)], ([element, handleOverride], _previous, onCleanup) => {
+		const handle = handleOverride === void 0 ? element : handleOverride;
+		if (!element || !handle) return;
+		const document = element.ownerDocument;
+		const onMove = (event) => {
+			if (!accepts(event) || event.pointerId !== activePointer || !offset) return;
+			const axis = toValue(options.axis) ?? "both";
+			const next = constrain(element, {
+				x: axis === "y" ? x.value : event.clientX - offset.x,
+				y: axis === "x" ? y.value : event.clientY - offset.y
+			});
+			x.value = next.x;
+			y.value = next.y;
+			handleEvent(event);
+			options.onMove?.(next, event);
+		};
+		const onUp = (event) => {
+			if (!accepts(event) || event.pointerId !== activePointer) return;
+			activePointer = null;
+			offset = null;
+			isDragging.value = false;
+			document.removeEventListener("pointermove", onMove);
+			document.removeEventListener("pointerup", onUp);
+			document.removeEventListener("pointercancel", onUp);
+			handleEvent(event);
+			options.onEnd?.(position.value, event);
+		};
+		const onDown = (event) => {
+			if (!accepts(event) || toValue(options.disabled) || activePointer !== null) return;
+			if (event.pointerType === "mouse" && event.button !== 0) return;
+			if (options.exact && event.target !== handle) return;
+			const rect = element.getBoundingClientRect();
+			const start = {
+				x: rect.left,
+				y: rect.top
+			};
+			if (options.onStart?.(start, event) === false) return;
+			activePointer = event.pointerId;
+			offset = {
+				x: event.clientX - rect.left,
+				y: event.clientY - rect.top
+			};
+			isDragging.value = true;
+			document.addEventListener("pointermove", onMove);
+			document.addEventListener("pointerup", onUp);
+			document.addEventListener("pointercancel", onUp);
+			handleEvent(event);
+		};
+		handle.addEventListener("pointerdown", onDown);
+		onCleanup(() => {
+			handle.removeEventListener("pointerdown", onDown);
+			document.removeEventListener("pointermove", onMove);
+			document.removeEventListener("pointerup", onUp);
+			document.removeEventListener("pointercancel", onUp);
+			activePointer = null;
+			offset = null;
+			isDragging.value = false;
+		});
+	}, {
+		immediate: true,
+		flush: "post"
+	});
+	const stop = () => stopWatch.stop();
+	tryOnScopeDispose(stop);
+	return {
+		x,
+		y,
+		position,
+		isDragging: readonly(isDragging),
+		style: computed(() => `left:${x.value}px;top:${y.value}px;`),
+		stop
+	};
+}
+function readBounds(source) {
+	if (source === void 0) return null;
+	const value = toValue(source);
+	if (isDragBounds(value)) return value;
+	const root = typeof value === "object" && value !== null && "$el" in value ? value.$el : value;
+	if (!isElementNode(root)) return null;
+	const rect = root.getBoundingClientRect();
+	return {
+		left: rect.left,
+		top: rect.top,
+		right: rect.right,
+		bottom: rect.bottom
+	};
+}
+function isDragBounds(value) {
+	return typeof value === "object" && value !== null && !("nodeType" in value) && !("$el" in value) && "left" in value && "right" in value;
+}
+function clamp(value, minimum, maximum) {
+	return Math.min(Math.max(value, minimum), maximum);
+}
+function isPointerEvent(event) {
+	return "pointerId" in event && "pointerType" in event;
+}
+//#endregion
+export { useDraggable };

package/dist/element-bounding.d.mts

@@ -0,0 +1,87 @@
+import { n as MaybeElementTarget } from "./element-target-Crpxl4D9.mjs";
+import { ResizeObserverHost } from "./resize-observer.mjs";
+import { MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/element-bounding.d.ts
+/**
+ * Window-like capability observed by {@link useElementBounding}: scroll and
+ * resize events plus the optional `ResizeObserver` constructor.
+ */
+interface ElementBoundingHost extends EventTarget, ResizeObserverHost {}
+/** Viewport-relative element geometry in CSS pixels. */
+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}. */
+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}. */
+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;
+};
+/**
+ * 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`.
+ */
+declare function useElementBounding(target: MaybeElementTarget, options?: UseElementBoundingOptions): ElementBoundingControls;
+//#endregion
+export { ElementBoundingControls, ElementBoundingHost, ElementBoundingRect, UseElementBoundingOptions, useElementBounding };

package/dist/element-bounding.mjs

@@ -0,0 +1,95 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { resolveElement } from "./element-target.mjs";
+import { useEventListener } from "./event-listener.mjs";
+import { useResizeObserver } from "./resize-observer.mjs";
+import { readonly, ref, toValue, watch } from "vue";
+//#region src/element-bounding.ts
+const boundingKeys = [
+	"x",
+	"y",
+	"top",
+	"right",
+	"bottom",
+	"left",
+	"width",
+	"height"
+];
+/**
+* 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`.
+*/
+function useElementBounding(target, options = {}) {
+	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 = () => options.host === void 0 ? browserBoundingHost() : toValue(options.host);
+	const update = () => {
+		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
+	}) : void 0;
+	const scroll = windowScroll ? useEventListener(host, "scroll", update, {
+		capture: true,
+		passive: true,
+		flush
+	}) : void 0;
+	const stop = () => {
+		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() {
+	return typeof window !== "undefined" ? window : void 0;
+}
+//#endregion
+export { useElementBounding };

package/dist/element-by-point.d.mts

@@ -0,0 +1,70 @@
+import { MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+//#region src/element-by-point.d.ts
+/** Document-like capability used by {@link useElementByPoint}. */
+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. */
+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}. */
+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}. */
+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.
+ */
+declare function useElementByPoint(options: UseElementByPointOptions): ElementByPointControls;
+//#endregion
+export { ElementByPointControls, ElementByPointFrameHost, ElementByPointHost, UseElementByPointOptions, useElementByPoint };

package/dist/element-by-point.mjs

@@ -0,0 +1,69 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { hasInjectionContext, onMounted, readonly, ref, shallowRef, toValue, watch } from "vue";
+//#region src/element-by-point.ts
+/**
+* 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.
+*/
+function useElementByPoint(options) {
+	const isSupported = ref(false);
+	const element = shallowRef(null);
+	const elements = shallowRef([]);
+	const mounted = shallowRef(!hasInjectionContext());
+	if (!mounted.value) onMounted(() => {
+		mounted.value = true;
+	});
+	const host = () => !mounted.value ? void 0 : options.host === void 0 ? browserPointHost() : toValue(options.host);
+	const update = () => {
+		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)
+	], update, { immediate: true });
+	const stopPolling = options.poll ? watch(() => options.frameHost === void 0 ? browserFrameHost() : toValue(options.frameHost), (frames, _previous, onCleanup) => {
+		if (!frames) return;
+		let handle = 0;
+		const tick = () => {
+			update();
+			handle = frames.requestAnimationFrame(tick);
+		};
+		handle = frames.requestAnimationFrame(tick);
+		onCleanup(() => frames.cancelAnimationFrame(handle));
+	}, { immediate: true }) : void 0;
+	tryOnScopeDispose(() => {
+		stopWatch.stop();
+		stopPolling?.stop();
+	});
+	return {
+		isSupported: readonly(isSupported),
+		element,
+		elements,
+		update
+	};
+}
+function browserPointHost() {
+	return typeof document !== "undefined" ? document : void 0;
+}
+function browserFrameHost() {
+	return typeof window !== "undefined" ? window : void 0;
+}
+//#endregion
+export { useElementByPoint };

package/dist/element-hover.d.mts

@@ -0,0 +1,42 @@
+import { t as TimeoutScheduler } from "./timeout-scheduler-CI8RVLZs.mjs";
+import { n as MaybeElementTarget } from "./element-target-Crpxl4D9.mjs";
+import { Ref } from "vue";
+
+//#region src/element-hover.d.ts
+/** Options for {@link useElementHover}. */
+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;
+}
+/**
+ * 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.
+ */
+declare function useElementHover(target: MaybeElementTarget, options?: UseElementHoverOptions): Readonly<Ref<boolean>>;
+//#endregion
+export { UseElementHoverOptions, useElementHover };