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

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

@@ -0,0 +1,296 @@
+---
+name: neo4j-nvl-skill
+metadata:
+  package: '@neo4j-nvl/base'
+  version: '2.0.0-1e695738'
+description: Neo4j Visualization Library (NVL) — framework-agnostic graph rendering for the browser.
+  Covers @neo4j-nvl/base (NVL class, nodes/relationships, Canvas vs WebGL renderer),
+  @neo4j-nvl/interaction-handlers (zoom, pan, drag, click, hover, box/lasso select, keyboard) and
+  @neo4j-nvl/react (InteractiveNvlWrapper, BasicNvlWrapper, StaticPictureWrapper). Use when rendering
+  a Neo4j graph in a browser, feeding driver results through nvlResultTransformer, choosing Canvas vs
+  WebGL, clustering or laying out nodes, wiring node/relationship/cluster interactions, or embedding
+  NVL in React, Vite or vanilla JS apps.
+  Does NOT handle Cypher authoring — use neo4j-cypher-skill.
+  Does NOT handle driver lifecycle, sessions or executeQuery setup — use neo4j-driver-javascript-skill.
+  Does NOT handle the pre-styled GraphVisualization embed — use @neo4j-ndl/react.
+compatibility: '@neo4j-nvl packages 2.x; React 19 for @neo4j-nvl/react; browsers with Canvas2D and WebGL2'
+---
+
+[//]: # (This file is auto-generated by scripts/docs/generate-skills.mjs, do not edit it manually)
+
+# Neo4j Visualization Library (@neo4j-nvl/base)
+
+> Shipped with `@neo4j-nvl/base` v2.0.0-1e695738. Once installed into a project this folder is detached from the
+> package: the installed types in `node_modules/@neo4j-nvl/*` are the source of truth. If the project's
+> `@neo4j-nvl/base` is a different version and `node_modules/@neo4j-nvl/base/skills/neo4j-nvl-skill/SKILL.md`
+> exists, read that copy instead.
+
+## When to use
+
+- Rendering a Neo4j graph in the browser with custom interactions, rendering or data shapes
+- Visualizing `driver.executeQuery` results as an interactive graph
+- Zoom, pan, drag, click, hover, lasso or box-select interactions; clustering; custom layouts
+
+Not for: a pre-styled graph view with default behaviour (`GraphVisualization` from `@neo4j-ndl/react` wraps
+NVL for that), Python notebooks (`neo4j/python-graph-visualization`), Cypher, driver setup, GDS or GraphQL.
+
+## Rules
+
+- **Types win.** Confirm every option, callback and method against this skill or the `.d.ts` files in
+  `node_modules/@neo4j-nvl/*` before using it. If they disagree, trust the types and say so.
+- **Never invent options.** NVL options and callbacks are flat, named keys. If a key is not in the API
+  reference below or the types, it does not exist.
+- **Do not reverse-engineer from compiled `dist/` or `lib/` output.** Use the types and these docs.
+- **Symptom first.** When something does not work, check the table below before changing code.
+
+## Before you code
+
+1. The container has explicit `width` **and** `height`; otherwise the graph is invisible.
+2. React wrappers: `layout`, `layoutOptions` and every other option go inside `nvlOptions`.
+3. Wheel zoom in `<InteractiveNvlWrapper>` is enabled by `mouseEventCallbacks.onZoomAndPan`; there is no `onZoom`.
+4. `fit()` needs explicit node ids. `fit([])` fits nothing.
+5. The WebGL renderer draws no captions. Use `'canvas'` when labels matter, or `html` / `icon` overlays.
+6. If the hierarchical layout never finishes under the Vite dev server, add `optimizeDeps: { include: ['bin-pack'] }`. Vite 7.3 pre-bundles it on its own, so only apply it when the symptom appears.
+7. `nvlResultTransformer` returns bare `{ id }` elements; labels and properties are in `recordObjectMap`.
+8. React: `nvlCallbacks` are captured once; use refs or stable functions. `interactionOptions` replaces
+   the defaults, so pass every option you need.
+9. Destroy interaction handlers, then `nvl.destroy()`, on teardown. The React wrappers do this for you.
+
+## Symptom → cause → fix
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Graph invisible / blank | Container has no height | Explicit `width` and `height` on the container |
+| Wheel does not zoom (React) | Zoom handler only wired from `onZoomAndPan` | `mouseEventCallbacks={{ onZoomAndPan: true }}` → [react-wrappers](references/react-wrappers.md) |
+| Hierarchical layout never finishes (Vite dev) | Layout `SharedWorker` imports CJS `bin-pack`; seen on older Vite, not on 7.3 | `optimizeDeps: { include: ['bin-pack'] }` → [vite-and-bundlers](references/vite-and-bundlers.md) |
+| No text on nodes with WebGL | Captions are Canvas-only | `html` / `icon`, own overlay, or `setRenderer('canvas')` → [labels-and-overlays](references/labels-and-overlays.md) |
+| `fit([])` does nothing | Empty array = no nodes | `fit(nvl.getNodes().map((n) => n.id))` |
+| `fit()` stops zoomed in on a huge graph | `minZoom` clamp (default `0.075`) | `fit(ids, { minZoom })` or lower the `minZoom` option |
+| Clicking a cluster selects all its nodes | `selectOnClick` selects `cluster.nodeIds` | `selectOnClick: false` and select in `onNodeClick` → [clustering](references/clustering.md) |
+| No cluster outlines / halos | Not force-directed, or mixed colours (halo) | Force-directed with `layoutOptions.clustering`; one colour per cluster → [clustering](references/clustering.md) |
+| Pinned nodes move when clustering is on | Cluster forces ignore pins | Do not combine → [clustering](references/clustering.md) |
+| Changing circle options does nothing | Layout is not re-run on option change | Bounce via `setLayout('free')` → [layouts-and-positions](references/layouts-and-positions.md) |
+| Un-pinned nodes stay frozen | Settled simulation is not restarted | `setNodePositions(current, true)` → [layouts-and-positions](references/layouts-and-positions.md) |
+| Node `x`/`y` props do not move existing nodes | Positions apply on insert only | `setNodePositions` → [layouts-and-positions](references/layouts-and-positions.md) |
+| Callbacks see stale state (React) | `nvlCallbacks` captured at creation | Refs or stable functions → [react-wrappers](references/react-wrappers.md) |
+| Minimap empty (React) | Container did not exist at creation | Keep the element in state → [react-wrappers](references/react-wrappers.md) |
+| Hover / shadow defaults lost | `interactionOptions` replaces defaults | Pass every option → [react-wrappers](references/react-wrappers.md) |
+| Many icons not drawn | Too many distinct icon images | Fewer distinct icons → [labels-and-overlays](references/labels-and-overlays.md) |
+| Layout looks hung in headless Chrome | Software WebGL | Hardware-GL flags → [verifying-nvl-apps](references/verifying-nvl-apps.md) |
+| Raw `executeQuery` result passed to NVL | Records are not graph elements | `resultTransformer: nvlResultTransformer` → [data-from-neo4j](references/data-from-neo4j.md) |
+
+## Choose
+
+**NVL or Needle?** Default Neo4j styling and no custom interaction → `GraphVisualization` from `@neo4j-ndl/react`.
+Anything custom → NVL.
+
+| Need | Use |
+|---|---|
+| React, default interactions | `<InteractiveNvlWrapper>` from `@neo4j-nvl/react` |
+| React, custom interaction logic | `<BasicNvlWrapper>` + `ref` to the `NVL` instance |
+| Vanilla, standard interactions | `NVL` + `@neo4j-nvl/interaction-handlers` |
+| Vanilla, custom events | `NVL` + `container.addEventListener` + `nvl.getHits()` |
+| Static PNG / SVG | `<StaticPictureWrapper>` or `nvl.saveToFile()` / `nvl.saveToSvg()` |
+
+| Renderer | Nodes | Notes |
+|---|---|---|
+| `'canvas'` (default) | up to ~1,000 | Captions, icons, arrows, exact hit-testing |
+| `'webgl'` | 100,000+ | WebGL2 only; no captions; icons and arrowheads supported |
+
+`disableWebGL: true` forces Canvas rendering and non-GPU layouts.
+
+## Install
+
+```bash
+npm install @neo4j-nvl/base                  # required
+npm install @neo4j-nvl/interaction-handlers  # vanilla interactions
+npm install @neo4j-nvl/react                 # React wrappers (React 19)
+```
+
+`@neo4j-nvl/layout-workers` is transitive; never install it directly. `neo4j-driver` is only needed for
+`nvlResultTransformer`. License: Neo4j Visualization Library License, for use with Neo4j products.
+Starters: https://github.com/neo4j-devtools/nvl-boilerplates
+
+## Minimal examples
+
+```javascript
+import { NVL } from '@neo4j-nvl/base'
+import { ClickInteraction, ZoomInteraction, PanInteraction, DragNodeInteraction } from '@neo4j-nvl/interaction-handlers'
+
+const nodes = [{ id: '1', caption: 'A' }, { id: '2', caption: 'B' }]
+const rels = [{ id: '12', from: '1', to: '2', type: 'KNOWS' }]
+const nvl = new NVL(container, nodes, rels, { layout: 'forceDirected' }, {
+  onLayoutDone: () => nvl.fit(nodes.map((n) => n.id))
+})
+const handlers = [new ZoomInteraction(nvl), new PanInteraction(nvl), new DragNodeInteraction(nvl),
+  new ClickInteraction(nvl, { selectOnClick: true })]
+handlers[3].updateCallback('onNodeClick', (node) => console.log(node.id))
+// teardown: handlers.forEach((h) => h.destroy()); nvl.destroy()
+```
+
+```tsx
+import { InteractiveNvlWrapper } from '@neo4j-nvl/react'
+import type { NVL } from '@neo4j-nvl/base'
+import { useRef } from 'react'
+
+export function Graph({ nodes, rels }) {
+  const nvlRef = useRef<NVL>(null)
+  return (
+    <div style={{ width: '100%', height: 600 }}>
+      <InteractiveNvlWrapper
+        ref={nvlRef}
+        nodes={nodes}
+        rels={rels}
+        nvlOptions={{ layout: 'forceDirected', renderer: 'canvas' }}
+        interactionOptions={{ selectOnClick: true, drawShadowOnHover: true }}
+        mouseEventCallbacks={{
+          onNodeClick: (node) => console.log(node.id),
+          onZoomAndPan: true,
+          onPan: true,
+          onDrag: true
+        }}
+        nvlCallbacks={{ onLayoutDone: () => nvlRef.current?.fit(nodes.map((n) => n.id)) }}
+      />
+    </div>
+  )
+}
+```
+
+## Topic guides
+
+Read the one that matches the task before writing code.
+
+- [references/data-from-neo4j.md](references/data-from-neo4j.md) — `nvlResultTransformer` output, `recordObjectMap`, enriching nodes, Integer and temporal values
+- [references/react-wrappers.md](references/react-wrappers.md) — callback-to-handler mapping, stale callbacks, live vs creation-time options, minimap container
+- [references/clustering.md](references/clustering.md) — `clusterBy` per layout, outlines and halos, cluster click and hover, pins
+- [references/layouts-and-positions.md](references/layouts-and-positions.md) — when layouts re-run, `setNodePositions`, pinning, layout callbacks
+- [references/labels-and-overlays.md](references/labels-and-overlays.md) — captions vs `html` / `icon` / `overlayIcon`, coordinates for custom overlays
+- [references/vite-and-bundlers.md](references/vite-and-bundlers.md) — worker setup per bundler, dev vs production, `disableWebWorkers`
+- [references/verifying-nvl-apps.md](references/verifying-nvl-apps.md) — `window.__Nvl_*` hooks, headless Chrome flags, detecting a settled layout
+- [references/lifecycle-and-updates.md](references/lifecycle-and-updates.md) — add/update/remove methods, `restart`, teardown, context loss, telemetry, `onError`
+- [references/migrating-1x-to-2.md](references/migrating-1x-to-2.md) — removed options and renamed callbacks
+
+## API reference
+
+Generated from the installed version's type declarations. Open the page for the symbol you need; do not
+load all of them.
+
+### `@neo4j-nvl/base`
+
+NVL class, options, callbacks, graph element types, hit testing, nvlResultTransformer.
+
+**Classes**
+
+- [NVL](references/api/base/classes/NVL.md) — Class for a NVL instance.
+
+**Functions**
+
+- [getZoomTargetForNodePositions](references/api/base/functions/getZoomTargetForNodePositions.md) — Gets the zoom target to fit the given node positions into the scene.
+
+**Interfaces**
+
+- [CircularOptions](references/api/base/interfaces/CircularOptions.md) — The options for the circular layout.
+- [ClusteringOptions](references/api/base/interfaces/ClusteringOptions.md) — Options that control physical clustering and cluster decorations for the force-directed layout.
+- [ExternalCallbacks](references/api/base/interfaces/ExternalCallbacks.md) — An object specifying the required callback functions for certain actions
+- [ForceDirectedOptions](references/api/base/interfaces/ForceDirectedOptions.md) — The options for the force directed layout
+- [HierarchicalOptions](references/api/base/interfaces/HierarchicalOptions.md) — The options for the hierarchical layout
+- [HitTargetCluster](references/api/base/interfaces/HitTargetCluster.md) — A ClusteringOptions.clusterBy cluster hull that has been hit by a pointer event
+- [HitTargetNode](references/api/base/interfaces/HitTargetNode.md) — A node that has been hit by a pointer event
+- [HitTargetRelationship](references/api/base/interfaces/HitTargetRelationship.md) — A relationship that has been hit by a pointer event
+- [Node](references/api/base/interfaces/Node.md) — A node inside the graph visualization.
+- [NvlMouseEvent](references/api/base/interfaces/NvlMouseEvent.md) — The result of a NVL.getHits call.
+- [NvlOptions](references/api/base/interfaces/NvlOptions.md) — Configurations for a NVL instance
+- [Point](references/api/base/interfaces/Point.md) — An object representing a point in 2D space.
+- [Relationship](references/api/base/interfaces/Relationship.md) — A relationship inside the graph visualization.
+
+**Types**
+
+- [CanvasRendererType](references/api/base/type-aliases/CanvasRendererType.md) — A renderer using canvas.
+- [Cluster](references/api/base/type-aliases/Cluster.md) — A physical cluster produced by ClusteringOptions.clusterBy.
+- [ClusterByFn](references/api/base/type-aliases/ClusterByFn.md) — Function that maps a node id to a ClusterId for force-directed clustering.
+- [ClusterId](references/api/base/type-aliases/ClusterId.md) — Identifier returned by ClusterByFn to group nodes into physical clusters.
+- [HitTargets](references/api/base/type-aliases/HitTargets.md) — A collection of nodes, relationships and clusters that have been hit by a pointer event
+- [HitTestTarget](references/api/base/type-aliases/HitTestTarget.md)
+- [Layout](references/api/base/type-aliases/Layout.md) — The different types of layouts available
+- [LayoutOptions](references/api/base/type-aliases/LayoutOptions.md) — The options for the layout.
+- [NodeWithClientPosition](references/api/base/type-aliases/NodeWithClientPosition.md) — A node returned by NVL.getNodes with layout coordinates and screen position.
+- [PartialNode](references/api/base/type-aliases/PartialNode.md) — A node with only a subset of its properties.
+- [PartialRelationship](references/api/base/type-aliases/PartialRelationship.md) — A relationship with only a subset of its properties.
+- [Renderer](references/api/base/type-aliases/Renderer.md) — The different types of renderers available
+- [StyledCaption](references/api/base/type-aliases/StyledCaption.md) — The caption text and its text style.
+- [WebGLRendererType](references/api/base/type-aliases/WebGLRendererType.md) — A WebGL2 renderer that uses the GPU for rendering.
+- [ZoomOptions](references/api/base/type-aliases/ZoomOptions.md) — Options that influence how fit-to-zoom should behave
+
+**Variables**
+
+- [CircularLayoutType](references/api/base/variables/CircularLayoutType.md) — A basic circular layout.
+- [d3ForceLayoutType](references/api/base/variables/d3ForceLayoutType.md) — The commonly used d3-force layout.
+- [ForceDirectedLayoutType](references/api/base/variables/ForceDirectedLayoutType.md) — NVL's main force directed layout.
+- [FreeLayoutType](references/api/base/variables/FreeLayoutType.md) — A free layout that allows for arbitrary positioning of elements using NVL's setPosition method.
+- [GridLayoutType](references/api/base/variables/GridLayoutType.md) — A basic grid layout.
+- [HierarchicalLayoutType](references/api/base/variables/HierarchicalLayoutType.md) — A hierarchical layout using the dagre algorithm.
+- [nvlResultTransformer](references/api/base/variables/nvlResultTransformer.md) — Result transformer for the Neo4j JavaScript driver results to NVL graph elements.
+
+### `@neo4j-nvl/interaction-handlers`
+
+Zoom, pan, drag, click, hover, box/lasso select, keyboard handlers and their callbacks.
+
+**Classes**
+
+- [BoxSelectInteraction](references/api/interaction-handlers/classes/BoxSelectInteraction.md) — An interaction handler for multi-selecting nodes and relationships.
+- [ClickInteraction](references/api/interaction-handlers/classes/ClickInteraction.md) — Click interaction handler that handles click, double click and right click events on
+- [DragNodeInteraction](references/api/interaction-handlers/classes/DragNodeInteraction.md) — Interaction handler for dragging nodes,
+- [HoverInteraction](references/api/interaction-handlers/classes/HoverInteraction.md) — Interaction handler for hovering nodes and relationships.
+- [KeyboardInteraction](references/api/interaction-handlers/classes/KeyboardInteraction.md) — Opinionated interaction handler for keyboard-driven focus navigation
+- [LassoInteraction](references/api/interaction-handlers/classes/LassoInteraction.md) — An interaction handler that lets you select nodes and relationships by drawing a lasso around them.
+- [PanInteraction](references/api/interaction-handlers/classes/PanInteraction.md) — Interaction handler for panning the scene, which is achieved by clicking and moving the scene.
+- [ZoomInteraction](references/api/interaction-handlers/classes/ZoomInteraction.md) — Interaction handler for zooming the canvas, which is achieved by:
+
+**Types**
+
+- [BoxSelectInteractionCallbacks](references/api/interaction-handlers/type-aliases/BoxSelectInteractionCallbacks.md) — Callbacks for the box select interaction handler.
+- [BoxSelectInteractionOptions](references/api/interaction-handlers/type-aliases/BoxSelectInteractionOptions.md) — Options for the multi-select interaction handler to customize its behavior.
+- [ClickInteractionCallbacks](references/api/interaction-handlers/type-aliases/ClickInteractionCallbacks.md) — Callbacks for the click interaction handler.
+- [ClickInteractionOptions](references/api/interaction-handlers/type-aliases/ClickInteractionOptions.md) — Options for the click interaction handler to customize its behavior.
+- [DragNodeInteractionCallbacks](references/api/interaction-handlers/type-aliases/DragNodeInteractionCallbacks.md) — Callbacks for the drag node interaction handler.
+- [DrawInteractionOptions](references/api/interaction-handlers/type-aliases/DrawInteractionOptions.md) — Options for the draw interaction handler.
+- [HoverInteractionCallbacks](references/api/interaction-handlers/type-aliases/HoverInteractionCallbacks.md) — Callbacks for the hover interaction handler.
+- [HoverInteractionOptions](references/api/interaction-handlers/type-aliases/HoverInteractionOptions.md) — Options for the hover interaction handler to customize its behavior.
+- [KeyboardInteractionCallbacks](references/api/interaction-handlers/type-aliases/KeyboardInteractionCallbacks.md) — Callbacks for the keyboard interaction handler.
+- [KeyboardInteractionOptions](references/api/interaction-handlers/type-aliases/KeyboardInteractionOptions.md) — Options for the keyboard interaction handler.
+- [LassoInteractionCallbacks](references/api/interaction-handlers/type-aliases/LassoInteractionCallbacks.md) — Callbacks for the lasso interaction handler.
+- [LassoInteractionOptions](references/api/interaction-handlers/type-aliases/LassoInteractionOptions.md) — Options for the lasso interaction handler to customize its behavior.
+- [PanInteractionCallbacks](references/api/interaction-handlers/type-aliases/PanInteractionCallbacks.md) — Callbacks for the pan interaction handler.
+- [PanInteractionOptions](references/api/interaction-handlers/type-aliases/PanInteractionOptions.md) — Options for the pan interaction handler to customize its behavior.
+- [ZoomInteractionCallbacks](references/api/interaction-handlers/type-aliases/ZoomInteractionCallbacks.md) — Callbacks for the zoom interaction handler.
+- [ZoomInteractionOptions](references/api/interaction-handlers/type-aliases/ZoomInteractionOptions.md) — Options for the zoom interaction handler to customize its behavior.
+
+### `@neo4j-nvl/react`
+
+InteractiveNvlWrapper, BasicNvlWrapper, StaticPictureWrapper and their props.
+
+**Functions**
+
+- [StaticPictureWrapper](references/api/react/functions/StaticPictureWrapper.md) — A React component that creates a static picture of a graph using NVL.
+
+**Interfaces**
+
+- [BasicReactWrapperProps](references/api/react/interfaces/BasicReactWrapperProps.md) — The properties that can be passed to the BasicNvlWrapper component.
+- [InteractiveNvlWrapperProps](references/api/react/interfaces/InteractiveNvlWrapperProps.md) — The properties that can be passed to the InteractiveNvlWrapper component.
+
+**Types**
+
+- [InteractionOptions](references/api/react/type-aliases/InteractionOptions.md) — Collection of interaction options that can be used with
+- [KeyboardEvent](references/api/react/type-aliases/KeyboardEvent.md)
+- [KeyboardEventCallbacks](references/api/react/type-aliases/KeyboardEventCallbacks.md) — Collection of keyboard event callbacks that can be used with
+- [MouseEvent](references/api/react/type-aliases/MouseEvent.md) — The events that can be passed to the MouseEventCallbacks object
+- [MouseEventCallbacks](references/api/react/type-aliases/MouseEventCallbacks.md) — Collection of mouse event callbacks that can be used with
+- [StaticPictureWrapperProps](references/api/react/type-aliases/StaticPictureWrapperProps.md) — The properties that can be passed to the StaticPictureWrapper component.
+
+**Variables**
+
+- [BasicNvlWrapper](references/api/react/variables/BasicNvlWrapper.md) — A basic React wrapper that wraps the NVL base library within a React component.
+- [InteractiveNvlWrapper](references/api/react/variables/InteractiveNvlWrapper.md) — The interactive React wrapper component contains a collection of interaction handlers by default
+
+Web: user guide https://neo4j.com/docs/nvl/current/ · API https://neo4j.com/docs/api/nvl/current/ ·
+examples https://neo4j.com/docs/api/nvl/current/examples.html