@neo4j-nvl/base 1.2.2 → 2.0.0-1e695738

package/dist/types/utils/hitTest.d.ts

@@ -0,0 +1,84 @@
+import { Point } from "./geometry.js";
+import { Node, Relationship } from "../types/graph-element.js";
+import { Cluster, NvlState } from "../modules/state/types.js";
+import { ClusterHitRegion } from "./clusterHitRegions.js";
+/**
+ * A node that has been hit by a pointer event
+ */
+export interface HitTargetNode {
+  /** The node that was hit */
+  data: Node;
+  /** The coordinates of the node that was hit */
+  targetCoordinates: Point;
+  /** The coordinates of the pointer event */
+  pointerCoordinates: Point;
+  /** The distance vector between the node and the pointer event */
+  distanceVector: Point;
+  /** The distance between the node and the pointer event */
+  distance: number;
+  /** Whether the pointer event is inside the node */
+  insideNode: boolean;
+}
+/**
+ * A relationship that has been hit by a pointer event
+ */
+export interface HitTargetRelationship {
+  /** The relationship that was hit */
+  data: Relationship;
+  /** The coordinates of the source node of the relationship that was hit */
+  fromTargetCoordinates: Point;
+  /** The coordinates of the target node of the relationship that was hit */
+  toTargetCoordinates: Point;
+  /** The coordinates of the pointer event */
+  pointerCoordinates: Point;
+  /** The distance between the relationship and the pointer event */
+  distance: number;
+}
+/**
+ * A {@link ClusteringOptions.clusterBy} cluster hull that has been hit by a pointer event
+ */
+export interface HitTargetCluster {
+  /** The cluster that was hit */
+  data: Cluster;
+  /** The coordinates of the pointer event */
+  pointerCoordinates: Point;
+  /** The convex hull used for the hit test */
+  hull: Point[];
+}
+/**
+ * A collection of nodes, relationships and clusters that have been hit by a pointer event
+ * Part of the result of a {@link NVL}.{@link NVL.getHits} call
+ */
+export type HitTargets = {
+  /** The nodes that have been hit by the pointer event. */
+  nodes: HitTargetNode[];
+  /** The relationships that have been hit by the pointer event. */
+  relationships: HitTargetRelationship[];
+  /** The cluster hulls that have been hit by the pointer event. */
+  clusters: HitTargetCluster[];
+};
+export type HitTestTarget = 'node' | 'relationship' | 'cluster';
+/**
+ * Finds all cluster hulls that contain the given point.
+ * Overlapping hulls are returned smallest-first (most specific).
+ * @param x - X coordinate.
+ * @param y - Y coordinate.
+ * @param regions - Fitted cluster hit regions.
+ * @returns Cluster hits sorted by ascending hull area.
+ */
+export declare const hitClusterTest: (x: number, y: number, regions: ClusterHitRegion[]) => HitTargetCluster[];
+export declare const hitTest: (x: number, y: number, state: NvlState, targets?: HitTestTarget[], options?: {
+  hitNodeMarginWidth?: number;
+  clusterRegions?: ClusterHitRegion[];
+}) => HitTargets;
+export declare const hitTestCanvas: (x: number, y: number, parentHandler: {
+  getCanvasNodesAt: (c: Point, m: number) => HitTargetNode[];
+  getCanvasRelsAt: (c: Point) => HitTargetRelationship[];
+}, targets?: readonly HitTestTarget[], options?: {
+  hitNodeMarginWidth?: number;
+  clusterRegions?: ClusterHitRegion[];
+}) => HitTargets;
+export declare const hitTestBox: (x1: number, y1: number, x2: number, y2: number, state: NvlState, targets?: string[]) => {
+  nodes: Node[];
+  rels: Relationship[];
+};

package/dist/types/utils/jsDriverResultTransformer.d.ts

@@ -1,42 +1,44 @@
-import type { Node as DriverNode, Relationship as DriverRelationship, Path, Record } from 'neo4j-driver';
-import type { Node as NvlNode, Relationship as NvlRelationship } from '../types/graph-element';
+import { Node as Node$1, Relationship as Relationship$1 } from "../types/graph-element.js";
+import { Node, Path, Record, Relationship } from "neo4j-driver";
 export declare const recordMapper: (record: Record) => any[];
-type GraphElement = DriverNode | DriverRelationship | Path;
+type GraphElement = Node | Relationship | Path;
 type NestedGraphElements = GraphElement | NestedGraphElements[];
 export declare const recordCollector: (graphElements: NestedGraphElements[]) => {
-    /** The nodes of the graph. */
-    nodes: NvlNode[];
-    /** The relationships of the graph. */
-    relationships: NvlRelationship[];
-    /** A map from element id to the driver graph element. */
-    recordObjectMap: Map<string, DriverNode | DriverRelationship | Path>;
+  /** The nodes of the graph. */
+  nodes: Node$1[];
+  /** The relationships of the graph. */
+  relationships: Relationship$1[];
+  /** A map from element id to the driver graph element. */
+  recordObjectMap: Map<string, Node | Relationship | Path>;
 };
 /**
  * Result transformer for the Neo4j JavaScript driver results to NVL graph elements.
  * @example
  *
  * ```ts
- * import neo4j from "neo4j-driver";
- * import { nvlResultTransformer, NVL } from "@neo4j-nvl/base";
+ * import * as neo4j from 'neo4j-driver'
+ * import { nvlResultTransformer, NVL } from '@neo4j-nvl/base'
  *
- * const driver = neo4j.driver("{uri}", neo4j.auth.basic("{user}", "{password}"));
- * const nvlGraph = await driver.executeQuery(
- *   "MATCH (a)-[r]-(b) RETURN a,r,b LIMIT 25",
- *   {},
- *   { resultTransformer: nvlResultTransformer }
- * );
+ * const run = async () => {
+ *   const driver = neo4j.driver('{uri}', neo4j.auth.basic('{user}', '{password}'))
+ *   const nvlGraph = await driver.executeQuery(
+ *     'MATCH (a)-[r]-(b) RETURN a,r,b LIMIT 25',
+ *     {},
+ *     { resultTransformer: nvlResultTransformer }
+ *   )
  *
- * const nvl = new NVL(document.getElementById('viz'), nvlGraph.nodes, nvlGraph.relationships);
+ *   const nvl = new NVL(document.getElementById('viz'), nvlGraph.nodes, nvlGraph.relationships)
+ * }
  * ```
  *
  * @see {@link https://neo4j.com/docs/api/javascript-driver/current/class/lib6/result-transformers.js~ResultTransformers.html|ResultTransformers on Neo4j JS Driver API Docs}
  */
 export declare const nvlResultTransformer: import("neo4j-driver-core").ResultTransformer<{
-    /** The nodes of the graph. */
-    nodes: NvlNode[];
-    /** The relationships of the graph. */
-    relationships: NvlRelationship[];
-    /** A map from element id to the driver graph element. */
-    recordObjectMap: Map<string, DriverNode | DriverRelationship | Path>;
+  /** The nodes of the graph. */
+  nodes: Node$1[];
+  /** The relationships of the graph. */
+  relationships: Relationship$1[];
+  /** A map from element id to the driver graph element. */
+  recordObjectMap: Map<string, Node | Relationship | Path>;
 }>;
-export {};
+export {};

package/dist/types/utils/layoutSeeding.d.ts

@@ -0,0 +1,7 @@
+import { Point } from "./geometry.js";
+export type SeedingMethod = 'box' | 'circle';
+export declare const getCircleSeedRadius: (nodeCount: number, seedSpacing: number) => number;
+export declare const getBoxStartSize: (nodeCount: number) => number;
+export declare const getCirclePositionsForNodeCount: (nodeCount: number, center: Point, radius: number) => Point[];
+export declare const getBoxPositionsForNodeCount: (nodeCount: number, center: Point) => Point[];
+export declare const getSeedPositions: (nodeCount: number, seedingMethod: SeedingMethod, center?: Point) => Point[];

package/dist/types/utils/mouseUtils.d.ts

@@ -1,9 +1,9 @@
 export declare const getMouseElementCoordinates: (evt: MouseEvent, element: HTMLElement) => {
-    offsetX: number;
-    offsetY: number;
+  offsetX: number;
+  offsetY: number;
 };
 export declare const getMousePosition: (evt: MouseEvent, canvas: HTMLElement, zoom?: number, panX?: number, panY?: number) => {
-    x: number;
-    y: number;
+  x: number;
+  y: number;
 };
-export declare const getNewZoom: (evt: WheelEvent, currentZoom?: number) => number;
+export declare const getNewZoom: (evt: WheelEvent, currentZoom?: number) => number;

package/dist/types/utils/segmentAnalytics.d.ts

@@ -1,51 +1,51 @@
-import * as SegmentJS from '@segment/analytics-next';
+import * as SegmentJS from "@segment/analytics-next";
 type AnalyticsTrackPayload = {
-    eventPrefix: string;
-    event: string;
-    properties?: Record<string, unknown>;
+  eventPrefix: string;
+  event: string;
+  properties?: Record<string, unknown>;
 };
 export declare abstract class AnalyticsFunction {
-    /**
-     * Perform asynchronous bootstrapping.
-     */
-    abstract init(apiKey: string): void;
-    /**
-     * Associate session with known user identifier.
-     */
-    abstract identify(): void;
-    /**
-     * Load unique segment Id in the localstorage.
-     */
-    abstract loadSavedSegmentId(): string;
-    /**
-     * Save unique segment Id in the localstorage.
-     */
-    abstract saveTrackingId(segmentId: string): void;
-    /**
-     * Get/fetch unique segment Id from the localstorage.
-     */
-    abstract getSegmentTrackingId(): string;
-    /**
-     * Track arbitrary event.
-     */
-    abstract trackEvent(payload: AnalyticsTrackPayload): Promise<void>;
+  /**
+   * Perform asynchronous bootstrapping.
+   */
+  abstract init(apiKey: string): void;
+  /**
+   * Associate session with known user identifier.
+   */
+  abstract identify(): void;
+  /**
+   * Load unique segment Id in the localstorage.
+   */
+  abstract loadSavedSegmentId(): string;
+  /**
+   * Save unique segment Id in the localstorage.
+   */
+  abstract saveTrackingId(segmentId: string): void;
+  /**
+   * Get/fetch unique segment Id from the localstorage.
+   */
+  abstract getSegmentTrackingId(): string;
+  /**
+   * Track arbitrary event.
+   */
+  abstract trackEvent(payload: AnalyticsTrackPayload): Promise<void>;
 }
 /**
  * Analytics adapter for Segment Analytics.js.
  */
 export declare class SegmentAnalytics implements AnalyticsFunction {
-    private analytics;
-    constructor();
-    init(apiKey: string): void;
-    trackEvent(payload: {
-        eventPrefix: string;
-        event: string;
-        properties: SegmentJS.EventProperties;
-    }): Promise<void>;
-    identify(): void;
-    loadSavedSegmentId(): string;
-    getSegmentTrackingId(): string;
-    saveTrackingId(segmentId: string): void;
-    private ready;
+  private analytics;
+  constructor();
+  init(apiKey: string): void;
+  trackEvent(payload: {
+    eventPrefix: string;
+    event: string;
+    properties: SegmentJS.EventProperties;
+  }): Promise<void>;
+  identify(): void;
+  loadSavedSegmentId(): string;
+  getSegmentTrackingId(): string;
+  saveTrackingId(segmentId: string): void;
+  private ready;
 }
-export {};
+export {};

package/dist/types/utils/webWorkerUtils.d.ts

@@ -1,3 +1,3 @@
-type Layouts = 'CoseBilkentLayout' | 'HierarchicalLayout';
+type Layouts = 'HierarchicalLayout';
 export declare const initializeWorker: (workerName: Layouts, workersDisabled?: boolean) => SharedWorker;
-export {};
+export {};

package/dist/types/utils/zoomFunctions.d.ts

@@ -1,5 +1,12 @@
-import type { Node } from '../index';
-import type { Point } from './geometry';
+import { Point } from "./geometry.js";
+import { Node } from "../types/graph-element.js";
+import "../index.js";
+/**
+ * Gets padding for fitting nodes, which is twice the largest node radius.
+ * @param maxNodeRadius - The largest node radius.
+ * @returns The padding for fitting nodes.
+ */
+declare const getFitNodesPadding: (maxNodeRadius?: number) => number;
 declare const getExtremeLimits: (nodePositions: Point[]) => Point[];
 declare const getMaxDistance: (extremeLimits?: Point[]) => number;
 /**
@@ -9,10 +16,10 @@ declare const getMaxDistance: (extremeLimits?: Point[]) => number;
  * @returns An object with the center x and y coordinates and the width and height.
  */
 declare const getPositionBoundaries: (nodePositions?: Point[] | Node[], maxNodeRadius?: number) => {
-    centerX: number;
-    centerY: number;
-    nodesWidth: number;
-    nodesHeight: number;
+  centerX: number;
+  centerY: number;
+  nodesWidth: number;
+  nodesHeight: number;
 };
 /**
  * Gets the required zoom level for the given view and scene dimensions to fit the scene into the view.
@@ -23,8 +30,8 @@ declare const getPositionBoundaries: (nodePositions?: Point[] | Node[], maxNodeR
  * @returns An object with the zoom level for the x and y axis.
  */
 declare const getZoomLevel: (viewWidth: number, viewHeight: number, sceneWidth: number, sceneHeight: number) => {
-    zoomX: number;
-    zoomY: number;
+  zoomX: number;
+  zoomY: number;
 };
 /**
  * Creates a zoom target based on the given zoom levels and the min and max zoom level.
@@ -40,19 +47,20 @@ declare const createZoomTarget: (zoomX: number, zoomY: number, minZoom?: number,
  * @param nodePositions - The node positions.
  * @param containerWidth - The width of the container NVL is displayed in.
  * @param containerHeight - The height of the container NVL is displayed in.
- * @param maxNodeRadius - The maximum node radius, which is added as margin to the scene (defaults to `50`).
+ * @param maxNodeRadius - The maximum node radius, which is added as margin to the scene
+ * (defaults to 2 * {@link DefaultNodeSize}).
  * @returns The zoom and pan targets.
  */
 declare const getZoomTargetForNodePositions: (nodePositions: Point[], containerWidth: number, containerHeight: number, maxNodeRadius?: number) => {
-    /** The zoom level. */
-    zoom: number;
-    /** The x-coordinate of the pan. */
-    panX: number;
-    /** The y-coordinate of the pan. */
-    panY: number;
+  /** The zoom level. */
+  zoom: number;
+  /** The x-coordinate of the pan. */
+  panX: number;
+  /** The y-coordinate of the pan. */
+  panY: number;
 };
 declare const getFlexibleZoomLimit: (nodePositions: Point[], rect: HTMLCanvasElement, maxNodeRadius: number) => number;
 declare const getNewZoomWithinLimits: (newZoom: number, oldZoom: number, minZoom: number, maxZoom: number) => number;
 declare const isZoomOutAtLimit: (newZoom: number, oldZoom: number, zoomOutLimit: number) => boolean;
 declare const getDynamicZoom: (nodePositions: Point[] & Node[], minZoom: number, maxZoom: number, rect: HTMLCanvasElement, newZoom: number, currentZoom: number) => number;
-export { getFlexibleZoomLimit, getZoomTargetForNodePositions, isZoomOutAtLimit, getNewZoomWithinLimits, getExtremeLimits, getMaxDistance, getPositionBoundaries, getZoomLevel, createZoomTarget, getDynamicZoom };
+export { createZoomTarget, getDynamicZoom, getExtremeLimits, getFitNodesPadding, getFlexibleZoomLimit, getMaxDistance, getNewZoomWithinLimits, getPositionBoundaries, getZoomLevel, getZoomTargetForNodePositions, isZoomOutAtLimit };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neo4j-nvl/base",
-  "version": "1.2.2",
+  "version": "2.0.0-1e695738",
   "license": "SEE LICENSE IN 'LICENSE.txt'",
   "homepage": "https://neo4j.com/docs/nvl/current/",
   "description": "Base library for the Neo4j Visualization Library",
@@ -12,16 +12,19 @@
   "bugs": {
     "url": "https://community.neo4j.com/c/neo4j-graph-platform/neo4j-bloom"
   },
+  "type": "module",
   "main": "dist/base.mjs",
   "types": "dist/types/index.d.ts",
   "files": [
     "LICENSE.txt",
-    "dist"
+    "dist",
+    "skills",
+    "!skills/*/evals"
   ],
   "scripts": {
-    "build": "yarn global:tsc && webpack",
-    "build:dev": "yarn global:tsc && webpack --mode development",
-    "watch": "concurrently 'tsc -w' 'webpack -w --mode development' -k -n 'tsc,webpack' -c 'cyan,magenta'",
+    "build": "yarn global:tsc && vite build && tsdown",
+    "build:dev": "yarn global:tsc && vite build --mode development && tsdown",
+    "watch": "concurrently 'tsc -w' 'vite build --watch --mode development' 'tsdown --watch' -k -n 'tsc,vite,dts' -c 'cyan,magenta,yellow'",
     "test": "yarn global:jest",
     "test:perf": "yarn global:jest --testPathPattern='.bench.' --testPathIgnorePatterns=",
     "eslint": "yarn global:eslint ./src/",
@@ -30,7 +33,7 @@
     "postpack": "rm LICENSE.txt && rm CHANGELOG.md"
   },
   "dependencies": {
-    "@neo4j-nvl/layout-workers": "1.2.2",
+    "@neo4j-nvl/layout-workers": "2.0.0-1e695738",
     "@segment/analytics-next": "1.81.1",
     "color-string": "1.9.1",
     "d3-force": "3.0.0",
@@ -38,26 +41,23 @@
     "glsl-inject-defines": "1.0.3",
     "lodash": "4.18.1",
     "loglevel": "1.9.2",
-    "mobx": "3.6.2",
+    "mobx": "6.15.0",
     "node-pid-controller": "1.0.1",
-    "resizelistener": "1.1.0",
     "tinycolor2": "1.6.0",
-    "uuid": "14.0.1"
+    "uuid": "14.0.3"
   },
   "devDependencies": {
-    "@babel/core": "7.29.7",
     "@types/color-string": "1.5.5",
     "@types/d3-force": "3.0.10",
     "@types/lodash": "4.17.21",
     "@types/segment-analytics": "0.0.38",
     "@types/tinycolor2": "1.4.6",
-    "babel-loader": "8.4.1",
-    "copy-webpack-plugin": "11.0.0",
     "neo4j-driver": "5.28.2",
-    "webpack": "5.104.1",
-    "webpack-cli": "5.1.4"
+    "tsdown": "0.23.1",
+    "vite": "8.3.5"
   },
   "peerDependencies": {
     "neo4j-driver": "*"
-  }
+  },
+  "stableVersion": "2.0.0"
 }

package/skills/neo4j-nvl-skill/README.md

@@ -0,0 +1,39 @@
+# neo4j-nvl-skill
+
+Skill for the Neo4j Visualization Library (NVL) — covering:
+
+- `@neo4j-nvl/base` — `NVL` class, nodes/relationships, options, callbacks, hit testing, image export
+- `@neo4j-nvl/interaction-handlers` — `ZoomInteraction`, `PanInteraction`, `DragNodeInteraction`, `ClickInteraction`, `HoverInteraction`, `BoxSelectInteraction`, `LassoInteraction`, `KeyboardInteraction`
+- `@neo4j-nvl/react` — `InteractiveNvlWrapper`, `BasicNvlWrapper`, `StaticPictureWrapper`
+- `nvlResultTransformer` for piping `driver.executeQuery` results straight into NVL
+- Canvas vs WebGL renderer selection (~1k vs 100k+ nodes)
+- Layout selection (`forceDirected`, `hierarchical`, `circular`, `grid`, `free`, `d3Force`)
+- force-directed and hierarchical `clusterBy`, cluster decorations, hit testing, and callbacks
+- Container setup, Web Worker fallback, telemetry opt-out
+
+**Not covered** (see sibling tools / skills):
+- Out-of-the-box embedded graph view with default styling → `GraphVisualization` component in `@neo4j-ndl/react` (Neo4j Needle design system) — wraps NVL with defaults
+- Python / Jupyter graph visualization → `neo4j/python-graph-visualization` (Python port of NVL)
+- Cypher query authoring → `neo4j-cypher-skill`
+- Driver lifecycle, sessions, `executeQuery` setup → `neo4j-driver-javascript-skill`
+- GDS algorithms → `neo4j-gds-skill` / `neo4j-aura-graph-analytics-skill`
+
+**Compatibility:** `@neo4j-nvl` packages 2.0.x; React 19 for `@neo4j-nvl/react`; modern browsers with Canvas2D and WebGL2.
+
+**Install:**
+
+```bash
+npm install @neo4j-nvl/base
+npm install @neo4j-nvl/interaction-handlers   # optional, for vanilla JS interactions
+npm install @neo4j-nvl/react                  # optional, for React apps
+```
+
+Starter templates: https://github.com/neo4j-devtools/nvl-boilerplates
+
+**Install skill:**
+
+This skill ships inside `@neo4j-nvl/base`. After installing the package, sync it into your agent's skills directory:
+
+```bash
+npx skills experimental_sync
+```