@neo4j-nvl/base 1.2.2 → 2.0.0-2b04269b

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

@@ -0,0 +1,42 @@
+import { type CoarsenedGraph, type Sun } from '../layouts/forcedirectedlayout/clustering/types';
+import type { Cluster, ClusterId } from '../modules/state/types';
+import type { Node } from '../types/graph-element';
+import { type ClusterMemberDisk } from './clusterGeometry';
+import { type Point } from './geometry';
+/**
+ * A fitted cluster hull region used for decoration and hit-testing.
+ */
+export type ClusterHitRegion = Cluster & {
+    /** Convex hull used for picking / decoration. */
+    hull: Point[];
+    /** Layout sun original id (e.g. `synth-sun:${id}`). */
+    sunOriginalId: string;
+};
+export type MultiMemberCluster = {
+    sun: Sun;
+    nodeIds: string[];
+};
+/**
+ * Returns each multi-member first-level sun system in a coarsening hierarchy.
+ * @param firstSubGraphLevel - `subGraphs[1]` from the current layout coarsening hierarchy.
+ * @returns Suns paired with their original member node ids.
+ */
+export declare const getMultiMemberClusters: (firstSubGraphLevel: CoarsenedGraph) => MultiMemberCluster[];
+/**
+ * Collects member disks with usable positions for hull fitting.
+ * @param nodeIds - Member node ids.
+ * @param idToPosition - Node id to position map.
+ * @param idToItem - Node id to graph node map.
+ * @returns Member disks for {@link fitClusterHull}.
+ */
+export declare const collectMemberDisks: (nodeIds: string[], idToPosition: Readonly<Record<string, Point>>, idToItem: Record<string, Node>) => ClusterMemberDisk[];
+/**
+ * Builds hit regions for {@link ClusteringOptions.clusterBy} multi-member clusters.
+ * Structural {@link SolarMerger} suns are skipped, as they have no entry in `clusterIdsBySun`.
+ * @param subGraphs - Layout coarsening hierarchy.
+ * @param idToPosition - Node id to position map.
+ * @param idToItem - Node id to graph node map.
+ * @param clusterIdsBySun - Cluster id per synthetic cluster sun, keyed by sun `originalId`.
+ * @returns Fitted cluster hit regions.
+ */
+export declare const buildClusterByHitRegions: (subGraphs: CoarsenedGraph[], idToPosition: Readonly<Record<string, Point>>, idToItem: Record<string, Node>, clusterIdsBySun: ReadonlyMap<string, ClusterId>) => ClusterHitRegion[];

package/dist/types/utils/clusterHitRegions.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -5,6 +5,12 @@ export declare const MinRelLength = 100;
 export declare const Gravity = 25;
 export declare const SimulationStopVelocity = 0.25;
 export declare const MappingEnd = 999999;
+export declare const LayoutStepIntervalMs = 13;
+export declare const MaxLayoutStepsPerFrame = 20;
+export declare const DefaultMaxFps = 30;
+export declare const DefaultMinFps = 3;
+export declare const MinAllowedFps = 1;
+export declare const MaxAllowedFps = 120;
 export declare const ActiveAnimDuration = 1000;
 export declare const DefaultNodeSize = 25;
 export declare const DefaultNodeColor = "#FFDF81";

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

@@ -8,11 +8,11 @@ export interface Point {
     /** The y coordinate of the point. */
     y: number;
 }
-export declare const isPointDefined: (point: Point | Node) => boolean;
 /**
  * Returns true when value is a finite number (not NaN or Infinity).
  */
 export declare const isValidFiniteNumber: (value: unknown) => value is number;
+export declare const isPointDefined: (point: Point | Node | null | undefined) => point is Point;
 /**
  * This function checks if the coordinates are defined.
  * @param from - The {@link Node} the edge starts from.
@@ -126,3 +126,46 @@ export declare const getIntersection: (p0: Point, p1: Point, p2: Point, p3: Poin
  * @returns The distance between the point and the curve.
  */
 export declare const getDistanceToQuadratic: (fromCoordinates: Point, toCoordinates: Point, control: Point, point: Point) => number;
+/**
+ * Converts a polar coordinate (radius + angle around a centre) to a cartesian point.
+ * @param centre - The centre of the circle.
+ * @param radius - The radius of the circle.
+ * @param angle - The angle around the circle, in radians.
+ * @returns The point at that angle and radius from the centre.
+ */
+export declare const pointOnCircle: (centre: Point, radius: number, angle: number) => Point;
+/**
+ * Returns the point halfway between two points.
+ * @param a - The first point.
+ * @param b - The second point.
+ * @returns The midpoint of the segment from a to b.
+ */
+export declare const getMidPoint: (a: Point, b: Point) => Point;
+/**
+ * Places child points evenly spaced around a circle centred on a point.
+ * @param centre - The centre of the circle.
+ * @param radius - The radius of the circle.
+ * @param noOfChildren - The number of points to place around the circle.
+ * @returns The evenly spaced points.
+ */
+export declare const calculateCirclePositions: (centre: Point, radius: number, noOfChildren: number) => Point[];
+/**
+ * Andrew's monotone-chain convex hull.
+ * @param points - The points to get the convex hull of.
+ * @returns The convex hull of the points.
+ */
+export declare const getConvexHull: (points: Point[]) => Point[];
+/**
+ * Returns true when the point lies inside or on the boundary of a convex polygon.
+ * Works for both clockwise and counter-clockwise vertex order.
+ * @param point - The point to test.
+ * @param polygon - Convex polygon vertices in order around the boundary.
+ * @returns True when the point is inside or on the polygon.
+ */
+export declare const isPointInConvexPolygon: (point: Point, polygon: Point[]) => boolean;
+/**
+ * Absolute area of a simple polygon via the shoelace formula.
+ * @param polygon - Polygon vertices in order around the boundary.
+ * @returns The absolute area of the polygon.
+ */
+export declare const getPolygonArea: (polygon: Point[]) => number;

package/dist/types/utils/{hittest.d.ts → hitTest.d.ts}

@@ -1,5 +1,6 @@
-import type { NvlState } from '../modules/state/types';
+import type { Cluster, NvlState } from '../modules/state/types';
 import type { Node, Relationship } from '../types/graph-element';
+import type { ClusterHitRegion } from './clusterHitRegions';
 import type { Point } from './geometry';
 /**
  * A node that has been hit by a pointer event
@@ -34,7 +35,18 @@ export interface HitTargetRelationship {
     distance: number;
 }
 /**
- * A collection of nodes and relationships that have been hit by a pointer event
+ * 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 = {
@@ -42,15 +54,29 @@ export type HitTargets = {
     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 declare const hitTest: (x: number, y: number, state: NvlState, targets?: string[], options?: {
+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?: string[], options?: {
+}, 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[];

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

@@ -0,0 +1 @@
+export {};

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

@@ -16,17 +16,19 @@ export declare const recordCollector: (graphElements: NestedGraphElements[]) =>
  * @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}

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

@@ -0,0 +1,7 @@
+import type { Point } from './geometry';
+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/layoutSeeding.test.d.ts

@@ -0,0 +1 @@
+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 {};

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

@@ -1,5 +1,11 @@
 import type { Node } from '../index';
 import type { Point } from './geometry';
+/**
+ * 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;
 /**
@@ -40,7 +46,8 @@ 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) => {
@@ -55,4 +62,4 @@ declare const getFlexibleZoomLimit: (nodePositions: Point[], rect: HTMLCanvasEle
 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 { getFitNodesPadding, getFlexibleZoomLimit, getZoomTargetForNodePositions, isZoomOutAtLimit, getNewZoomWithinLimits, getExtremeLimits, getMaxDistance, getPositionBoundaries, getZoomLevel, createZoomTarget, getDynamicZoom };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neo4j-nvl/base",
-  "version": "1.2.2",
+  "version": "2.0.0-2b04269b",
   "license": "SEE LICENSE IN 'LICENSE.txt'",
   "homepage": "https://neo4j.com/docs/nvl/current/",
   "description": "Base library for the Neo4j Visualization Library",
@@ -16,12 +16,13 @@
   "types": "dist/types/index.d.ts",
   "files": [
     "LICENSE.txt",
-    "dist"
+    "dist",
+    "skills"
   ],
   "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",
+    "build:dev": "yarn global:tsc && vite build --mode development",
+    "watch": "concurrently 'tsc -w' 'vite build --watch --mode development' -k -n 'tsc,vite' -c 'cyan,magenta'",
     "test": "yarn global:jest",
     "test:perf": "yarn global:jest --testPathPattern='.bench.' --testPathIgnorePatterns=",
     "eslint": "yarn global:eslint ./src/",
@@ -30,7 +31,7 @@
     "postpack": "rm LICENSE.txt && rm CHANGELOG.md"
   },
   "dependencies": {
-    "@neo4j-nvl/layout-workers": "1.2.2",
+    "@neo4j-nvl/layout-workers": "2.0.0-2b04269b",
     "@segment/analytics-next": "1.81.1",
     "color-string": "1.9.1",
     "d3-force": "3.0.0",
@@ -38,26 +39,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.2"
   },
   "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"
+    "vite": "7.3.5",
+    "vite-plugin-static-copy": "4.1.1"
   },
   "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
+```