@yggy-tech/graphraum 0.36.0 → 0.37.0

package/dist/index.d.ts

@@ -80,6 +80,16 @@ interface GraphraumSetDataOptions {
    */
   fit?: boolean;
 }
+type GraphraumNodeDragPhase = "start" | "move" | "end" | "cancel";
+/** One step of a node drag. `cancel` carries the position the node was restored to (or left at). */
+interface GraphraumNodeDragEvent {
+  nodeId: string;
+  phase: GraphraumNodeDragPhase;
+  position: GraphraumPosition;
+}
+interface GraphraumNodeDragOptions {
+  enabled: boolean;
+}
 interface GraphraumCameraPoint3d {
   x: number;
   y: number;
@@ -618,6 +628,8 @@ declare class Graphraum<NodeAttributes = undefined, EdgeAttributes = undefined>
   private gpuTimer;
   private readonly viewListeners;
   private readonly focusListeners;
+  private readonly nodeDragListeners;
+  private readonly nodeDrag;
   private lastHoveredNodeId;
   private readonly antialias;
   private depthOfField;
@@ -715,6 +727,16 @@ declare class Graphraum<NodeAttributes = undefined, EdgeAttributes = undefined>
   createOverlay(options?: GraphraumOverlayOptions): GraphraumOverlay<NodeAttributes, EdgeAttributes>;
   /** Subscribes to camera and viewport changes. Returns an unsubscribe function. */
   onViewChange(listener: () => void): () => boolean;
+  /**
+   * Turns node dragging on or off (default off). A drag starts when the pointer moves past a small
+   * tolerance after a press on a node (a finger must rest on the node first, so a swipe still pans
+   * the camera), moves the node on a plane facing the camera, and ends on release. Escape or a
+   * cancelled pointer put the node back. Not available while the density LOD shows clusters.
+   */
+  setNodeDrag(options: GraphraumNodeDragOptions): void;
+  /** Subscribes to node drag steps (`start`, `move`, `end`, `cancel`). Returns an unsubscribe function. */
+  onNodeDrag(listener: (event: GraphraumNodeDragEvent) => void): () => boolean;
+  private createNodeDragHost;
   /** Subscribes to selection and hover changes that affect overlay focus chrome. */
   onFocusChange(listener: () => void): () => boolean;
   private notifyFocusChange;
@@ -983,4 +1005,4 @@ declare function isTransparentGraphraumBackground(background: GraphraumBackgroun
 /** Defines typed, serializable graph visuals without coupling application data to the render loop. */
 declare function defineVisuals<NodeAttributes = undefined, EdgeAttributes = undefined>(visuals: GraphraumVisualMapper<NodeAttributes, EdgeAttributes>): GraphraumVisualMapper<NodeAttributes, EdgeAttributes>;
 //#endregion
-export { type CompiledGraphraumPresentation, DEFAULT_ENDPOINT_ATTACH, DEFAULT_ENDPOINT_CLEARANCE, DEFAULT_FORCE_SETTINGS, type EndpointAttach, type EndpointOutline, type ForceLayoutRequest, type ForceSettings, type GraphologyEdgeAttributes, type GraphologyNodeAttributes, type GraphologyRenderer, Graphraum, type GraphraumAutoOrbitOptions, type GraphraumAutoOrbitStatus, type GraphraumBackground, type GraphraumCameraPoint3d, type GraphraumCameraState, type GraphraumCameraState2d, type GraphraumCameraState3d, type GraphraumColor, type GraphraumData, type GraphraumDataPatch, type GraphraumDepthOfFieldOptions, type GraphraumDepthOfFieldStatus, type GraphraumDepthOfFieldTransition, type GraphraumDepthOfFieldUpdate, type GraphraumDiagnostics, type GraphraumEasing, type GraphraumEdge, type GraphraumEdgeEncoding, type GraphraumEdgeMarker, type GraphraumEdgeMarkerEnd, type GraphraumEdgePath, type GraphraumEdgeState, type GraphraumEdgeStyle, type GraphraumEdgeVisual, type GraphraumFlyToOptions, type GraphraumLabelCandidate, type GraphraumLayoutPositions, type GraphraumMode, type GraphraumNode, type GraphraumNodeEncoding, type GraphraumNodeGeometry, type GraphraumNodeShape, type GraphraumNodeState, type GraphraumNodeUpdate, type GraphraumNodeVisual, type GraphraumOptions, GraphraumOverlay, type GraphraumOverlayNode, type GraphraumOverlayOptions, type GraphraumPatternBackground, type GraphraumPickHit, type GraphraumPosition, type GraphraumPresentation, type GraphraumPresentationAction, type GraphraumPresentationProperty, type GraphraumPropertyValue, type GraphraumScreenPosition, type GraphraumSetDataOptions, type GraphraumTheme, type GraphraumThemeName, type GraphraumVisualMapper, type LabelBudgetCandidate, type RichNodePolicy, type SelectBudgetedLabelIdsInput, type SelectFocusLabelIdsInput, attachPointOnOutline, bindGraphology, boundOverlayIds, computeClusteredForcePositions, computeForcePositions, createForceSimulation, defineVisuals, forceIterationCount, graphraumEdgePaths, graphraumNodeShapes, graphraumTheme, graphraumThemeDark, graphraumThemeLight, graphraumThemes, isTransparentGraphraumBackground, normalizeGraphraumBackground, orderFocusNodeIds, resolveGraphraumTheme, selectBudgetedLabelIds, selectFocusLabelIds, selectRichNodeIds, trimEdgeEndpoints };
+export { type CompiledGraphraumPresentation, DEFAULT_ENDPOINT_ATTACH, DEFAULT_ENDPOINT_CLEARANCE, DEFAULT_FORCE_SETTINGS, type EndpointAttach, type EndpointOutline, type ForceLayoutRequest, type ForceSettings, type GraphologyEdgeAttributes, type GraphologyNodeAttributes, type GraphologyRenderer, Graphraum, type GraphraumAutoOrbitOptions, type GraphraumAutoOrbitStatus, type GraphraumBackground, type GraphraumCameraPoint3d, type GraphraumCameraState, type GraphraumCameraState2d, type GraphraumCameraState3d, type GraphraumColor, type GraphraumData, type GraphraumDataPatch, type GraphraumDepthOfFieldOptions, type GraphraumDepthOfFieldStatus, type GraphraumDepthOfFieldTransition, type GraphraumDepthOfFieldUpdate, type GraphraumDiagnostics, type GraphraumEasing, type GraphraumEdge, type GraphraumEdgeEncoding, type GraphraumEdgeMarker, type GraphraumEdgeMarkerEnd, type GraphraumEdgePath, type GraphraumEdgeState, type GraphraumEdgeStyle, type GraphraumEdgeVisual, type GraphraumFlyToOptions, type GraphraumLabelCandidate, type GraphraumLayoutPositions, type GraphraumMode, type GraphraumNode, type GraphraumNodeDragEvent, type GraphraumNodeDragOptions, type GraphraumNodeDragPhase, type GraphraumNodeEncoding, type GraphraumNodeGeometry, type GraphraumNodeShape, type GraphraumNodeState, type GraphraumNodeUpdate, type GraphraumNodeVisual, type GraphraumOptions, GraphraumOverlay, type GraphraumOverlayNode, type GraphraumOverlayOptions, type GraphraumPatternBackground, type GraphraumPickHit, type GraphraumPosition, type GraphraumPresentation, type GraphraumPresentationAction, type GraphraumPresentationProperty, type GraphraumPropertyValue, type GraphraumScreenPosition, type GraphraumSetDataOptions, type GraphraumTheme, type GraphraumThemeName, type GraphraumVisualMapper, type LabelBudgetCandidate, type RichNodePolicy, type SelectBudgetedLabelIdsInput, type SelectFocusLabelIdsInput, attachPointOnOutline, bindGraphology, boundOverlayIds, computeClusteredForcePositions, computeForcePositions, createForceSimulation, defineVisuals, forceIterationCount, graphraumEdgePaths, graphraumNodeShapes, graphraumTheme, graphraumThemeDark, graphraumThemeLight, graphraumThemes, isTransparentGraphraumBackground, normalizeGraphraumBackground, orderFocusNodeIds, resolveGraphraumTheme, selectBudgetedLabelIds, selectFocusLabelIds, selectRichNodeIds, trimEdgeEndpoints };

package/dist/index.js

@@ -2493,6 +2493,231 @@ function prepareLayoutPositions(nodes, nodeIndices, layout) {
 		};
 	});
 }
+/**
+* Drags one node with the pointer. A press on a node arms a gesture; once the pointer leaves the
+* click tolerance (a finger must rest on the node first) the node follows it until release.
+* Camera controls are switched off for the gesture and restored when it ends, so a press that stays
+* a click behaves as before. Escape, a cancelled pointer or lost pointer capture put the node back.
+*/
+var NodeDragController = class {
+	host;
+	holdMs;
+	enabled = false;
+	gesture = null;
+	unlisten;
+	unlistenKeys = null;
+	constructor(host, holdMs = 350) {
+		this.host = host;
+		this.holdMs = holdMs;
+		this.unlisten = [
+			listen(host.element, "pointerdown", this.handleDown, { capture: true }),
+			listen(host.element, "pointermove", this.handleMove),
+			listen(host.element, "pointerup", this.handleUp),
+			listen(host.element, "pointercancel", this.handleCancel),
+			listen(host.element, "lostpointercapture", this.handleCancel)
+		];
+	}
+	/** True from the first drag step until the node is dropped or the drag is cancelled. */
+	get active() {
+		return this.gesture?.phase === "dragging";
+	}
+	setEnabled(enabled) {
+		if (!enabled) this.cancel({ restore: true });
+		this.enabled = enabled;
+	}
+	/** Ends a running gesture as cancelled. `restore` puts the node back where it was grabbed. */
+	cancel({ restore }) {
+		const gesture = this.gesture;
+		if (!gesture) return;
+		if (gesture.phase === "dragging") {
+			const restored = restore && this.host.nodePosition(gesture.nodeId) !== null;
+			if (restored) this.host.moveNode(gesture.nodeId, gesture.origin);
+			this.finish(gesture);
+			this.host.emit({
+				nodeId: gesture.nodeId,
+				phase: "cancel",
+				position: restored ? gesture.origin : gesture.last
+			});
+			return;
+		}
+		this.finish(gesture);
+	}
+	dispose() {
+		this.cancel({ restore: false });
+		this.enabled = false;
+		for (const stop of this.unlisten) stop();
+	}
+	handleDown = (event) => {
+		if (!this.enabled || this.gesture || event.button !== 0 || !this.host.canStart()) return;
+		const nodeId = this.host.pickNode(event.clientX, event.clientY);
+		if (nodeId === null) return;
+		const origin = this.host.nodePosition(nodeId);
+		if (!origin) return;
+		const surface = this.host.createSurface(origin);
+		const grabbed = surface?.(event.clientX, event.clientY);
+		if (!surface || !grabbed) return;
+		const touch = event.pointerType === "touch";
+		const gesture = {
+			controlsHeld: false,
+			holdTimer: null,
+			last: origin,
+			nodeId,
+			offset: {
+				x: origin.x - grabbed.x,
+				y: origin.y - grabbed.y,
+				z: (origin.z ?? 0) - (grabbed.z ?? 0)
+			},
+			origin,
+			phase: "pressed",
+			pointerId: event.pointerId,
+			startX: event.clientX,
+			startY: event.clientY,
+			surface,
+			touch
+		};
+		this.gesture = gesture;
+		this.unlistenKeys = listen(this.host.document, "keydown", this.handleKey);
+		if (touch) {
+			gesture.holdTimer = setTimeout(() => this.beginDrag(gesture), this.holdMs);
+			return;
+		}
+		this.holdControls(gesture);
+		capture(this.host.element, event.pointerId);
+	};
+	handleMove = (event) => {
+		const gesture = this.gesture;
+		if (!gesture || event.pointerId !== gesture.pointerId) return;
+		if (gesture.phase === "pressed") {
+			if (Math.hypot(event.clientX - gesture.startX, event.clientY - gesture.startY) <= 5) return;
+			if (gesture.touch) {
+				this.finish(gesture);
+				return;
+			}
+			this.beginDrag(gesture);
+		}
+		this.follow(gesture, event.clientX, event.clientY);
+	};
+	handleUp = (event) => {
+		const gesture = this.gesture;
+		if (!gesture || event.pointerId !== gesture.pointerId) return;
+		this.finish(gesture);
+		if (gesture.phase === "dragging") this.host.emit({
+			nodeId: gesture.nodeId,
+			phase: "end",
+			position: gesture.last
+		});
+	};
+	handleCancel = (event) => {
+		if (this.gesture && event.pointerId === this.gesture.pointerId) this.cancel({ restore: true });
+	};
+	handleKey = (event) => {
+		if (event.key === "Escape") this.cancel({ restore: true });
+	};
+	beginDrag(gesture) {
+		if (this.gesture !== gesture || gesture.phase === "dragging") return;
+		gesture.phase = "dragging";
+		clearHold(gesture);
+		this.holdControls(gesture);
+		if (gesture.touch) capture(this.host.element, gesture.pointerId);
+		this.host.emit({
+			nodeId: gesture.nodeId,
+			phase: "start",
+			position: gesture.origin
+		});
+	}
+	follow(gesture, clientX, clientY) {
+		if (!this.host.nodePosition(gesture.nodeId)) {
+			this.cancel({ restore: false });
+			return;
+		}
+		const point = gesture.surface(clientX, clientY);
+		if (!point) return;
+		const z = point.z === void 0 ? gesture.origin.z : point.z + gesture.offset.z;
+		const position = {
+			x: point.x + gesture.offset.x,
+			y: point.y + gesture.offset.y,
+			...z === void 0 ? {} : { z }
+		};
+		gesture.last = position;
+		this.host.moveNode(gesture.nodeId, position);
+		this.host.emit({
+			nodeId: gesture.nodeId,
+			phase: "move",
+			position
+		});
+	}
+	holdControls(gesture) {
+		if (gesture.controlsHeld) return;
+		gesture.controlsHeld = true;
+		this.host.setControlsEnabled(false);
+	}
+	/** Drops the gesture and everything it held: timer, pointer capture, key listener, camera controls. */
+	finish(gesture) {
+		if (this.gesture !== gesture) return;
+		this.gesture = null;
+		clearHold(gesture);
+		this.unlistenKeys?.();
+		this.unlistenKeys = null;
+		release(this.host.element, gesture.pointerId);
+		if (gesture.controlsHeld) this.host.setControlsEnabled(true);
+	}
+};
+/** Typed `addEventListener` for the pointer and key events this module handles; returns the unsubscribe. */
+function listen(target, type, handler, options) {
+	const listener = handler;
+	target.addEventListener(type, listener, options);
+	return () => target.removeEventListener(type, listener, options);
+}
+function clearHold(gesture) {
+	if (gesture.holdTimer === null) return;
+	clearTimeout(gesture.holdTimer);
+	gesture.holdTimer = null;
+}
+function capture(element, pointerId) {
+	try {
+		element.setPointerCapture(pointerId);
+	} catch {}
+}
+function release(element, pointerId) {
+	try {
+		element.releasePointerCapture(pointerId);
+	} catch {}
+}
+//#endregion
+//#region src/node-drag-surface.ts
+/**
+* Where the pointer is in world space on the plane a dragged node moves in. 2D unprojects onto the
+* view plane and reports no depth. 3D intersects the pointer ray with a plane through the anchor
+* that faces the camera as it was at the press, so the node keeps its depth and follows the pointer
+* across the screen. Returns `null` for an empty canvas, and from the surface when the ray misses.
+*/
+function createNodeDragSurface({ anchor, bounds, camera, raycaster }) {
+	const initial = bounds();
+	if (initial.width === 0 || initial.height === 0) return null;
+	const ndc = new Vector2();
+	const toNdc = (clientX, clientY) => {
+		const { height, left, top, width } = bounds();
+		return ndc.set((clientX - left) / width * 2 - 1, -((clientY - top) / height) * 2 + 1);
+	};
+	if (camera.type === "OrthographicCamera") return (clientX, clientY) => {
+		const point = toNdc(clientX, clientY);
+		const world = new Vector3(point.x, point.y, 0).unproject(camera);
+		return {
+			x: world.x,
+			y: world.y
+		};
+	};
+	const plane = new Plane().setFromNormalAndCoplanarPoint(camera.getWorldDirection(new Vector3()), new Vector3(anchor.x, anchor.y, anchor.z ?? 0));
+	const hit = new Vector3();
+	return (clientX, clientY) => {
+		raycaster.setFromCamera(toNdc(clientX, clientY), camera);
+		return raycaster.ray.intersectPlane(plane, hit) ? {
+			x: hit.x,
+			y: hit.y,
+			z: hit.z
+		} : null;
+	};
+}
 const vertexShader$1 = `
 attribute float instanceGlowOpacity;
 varying vec3 glowColor;
@@ -3386,6 +3611,8 @@ var Graphraum = class {
 	gpuTimer = null;
 	viewListeners = /* @__PURE__ */ new Set();
 	focusListeners = /* @__PURE__ */ new Set();
+	nodeDragListeners = /* @__PURE__ */ new Set();
+	nodeDrag;
 	lastHoveredNodeId = null;
 	antialias;
 	depthOfField = DEPTH_OF_FIELD_DEFAULTS;
@@ -3433,6 +3660,7 @@ var Graphraum = class {
 		this.renderer.domElement.addEventListener("pointermove", this.handlePointerMove);
 		this.renderer.domElement.addEventListener("pointerleave", this.handlePointerLeave);
 		for (const type of FLIGHT_CANCEL_EVENTS) this.renderer.domElement.addEventListener(type, this.cancelFlight);
+		this.nodeDrag = new NodeDragController(this.createNodeDragHost());
 		this.camera = this.createCamera();
 		this.controls = this.createControls();
 		this.resizeObserver = new ResizeObserver(() => this.resize());
@@ -3586,6 +3814,7 @@ var Graphraum = class {
 		this.requestRender();
 	}
 	replaceData(data, fitView) {
+		this.nodeDrag.cancel({ restore: false });
 		const compiled = compileGraph(data, this.visuals);
 		this.disposeGraphObjects();
 		this.data = {
@@ -3903,6 +4132,7 @@ var Graphraum = class {
 	setMode(mode) {
 		if (mode === this.mode) return;
 		this.cancelFlight();
+		this.nodeDrag.cancel({ restore: true });
 		this.stopAutoOrbit();
 		this.mode = mode;
 		this.controls.removeEventListener("change", this.handleViewChange);
@@ -4030,6 +4260,51 @@ var Graphraum = class {
 		listener();
 		return () => this.viewListeners.delete(listener);
 	}
+	/**
+	* Turns node dragging on or off (default off). A drag starts when the pointer moves past a small
+	* tolerance after a press on a node (a finger must rest on the node first, so a swipe still pans
+	* the camera), moves the node on a plane facing the camera, and ends on release. Escape or a
+	* cancelled pointer put the node back. Not available while the density LOD shows clusters.
+	*/
+	setNodeDrag(options) {
+		if (typeof options?.enabled !== "boolean") throw new Error("setNodeDrag option enabled must be a boolean.");
+		this.nodeDrag.setEnabled(options.enabled);
+	}
+	/** Subscribes to node drag steps (`start`, `move`, `end`, `cancel`). Returns an unsubscribe function. */
+	onNodeDrag(listener) {
+		this.nodeDragListeners.add(listener);
+		return () => this.nodeDragListeners.delete(listener);
+	}
+	createNodeDragHost() {
+		const element = this.renderer.domElement;
+		return {
+			canStart: () => !this.destroyed && this.nodeMesh !== null && !this.densityLodActive,
+			createSurface: (anchor) => createNodeDragSurface({
+				anchor,
+				bounds: () => element.getBoundingClientRect(),
+				camera: this.camera,
+				raycaster: this.raycaster
+			}),
+			document: element.ownerDocument,
+			element,
+			emit: (event) => {
+				for (const listener of this.nodeDragListeners) listener(event);
+			},
+			moveNode: (nodeId, position) => this.updateNodes([{
+				id: nodeId,
+				position
+			}]),
+			nodePosition: (nodeId) => {
+				const index = this.nodeIndices.get(nodeId);
+				const node = index === void 0 ? void 0 : this.data.nodes[index];
+				return node ? { ...node.position } : null;
+			},
+			pickNode: (clientX, clientY) => this.pickNode(clientX, clientY),
+			setControlsEnabled: (enabled) => {
+				this.controls.enabled = enabled;
+			}
+		};
+	}
 	/** Subscribes to selection and hover changes that affect overlay focus chrome. */
 	onFocusChange(listener) {
 		this.focusListeners.add(listener);
@@ -4040,6 +4315,7 @@ var Graphraum = class {
 		for (const listener of this.focusListeners) listener();
 	}
 	handlePointerMove = (event) => {
+		if (this.nodeDrag.active) return;
 		const nodeId = this.pickNode(event.clientX, event.clientY);
 		if (nodeId === this.lastHoveredNodeId) return;
 		this.lastHoveredNodeId = nodeId;
@@ -4396,6 +4672,7 @@ var Graphraum = class {
 	destroy() {
 		this.destroyed = true;
 		this.cancelFlight();
+		this.nodeDrag.dispose();
 		this.stopAutoOrbit();
 		this.resizeObserver.disconnect();
 		this.renderer.domElement.removeEventListener("pointermove", this.handlePointerMove);
@@ -4540,6 +4817,7 @@ var Graphraum = class {
 	* without a loop.
 	*/
 	stepAutoOrbit = (deltaSeconds) => {
+		if (this.nodeDrag.active) return;
 		try {
 			this.controls.autoRotate = true;
 			this.orbitUpdating = true;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@yggy-tech/graphraum",
-	"version": "0.36.0",
+	"version": "0.37.0",
 	"description": "yggy's WebGL engine for interactive graphs in 2D and 3D",
 	"type": "module",
 	"license": "Apache-2.0",