@neo4j-nvl/base 2.0.0-8a6da460 → 2.0.0-c8e499dc

package/skills/neo4j-nvl-skill/references/api-surface.md

@@ -0,0 +1,596 @@
+# NVL — API Surface Reference
+
+Source: `@neo4j-nvl/base@2.0`, `@neo4j-nvl/interaction-handlers@2.0`, `@neo4j-nvl/react@2.0`.
+
+## Packages
+
+| Package | Main export | Notes |
+|---|---|---|
+| `@neo4j-nvl/base` | `NVL` (also default), types, `nvlResultTransformer`, layout constants | Framework-agnostic core |
+| `@neo4j-nvl/interaction-handlers` | `ZoomInteraction`, `PanInteraction`, `ClickInteraction`, `HoverInteraction`, `DragNodeInteraction`, `BoxSelectInteraction`, `LassoInteraction`, `KeyboardInteraction` | Compose onto an `NVL` instance |
+| `@neo4j-nvl/react` | `InteractiveNvlWrapper`, `BasicNvlWrapper`, `StaticPictureWrapper` | React 19 |
+| `@neo4j-nvl/layout-workers` | (transitive) | Force-directed + hierarchical workers |
+
+---
+
+## `NVL` Class
+
+### Constructor
+
+```typescript
+new NVL(
+  frame: HTMLElement,
+  nvlNodes?: Node[],                  // default []
+  nvlRels?:  Relationship[],          // default []
+  options?:  NvlOptions,              // default {}
+  callbacks?: ExternalCallbacks       // default {}
+)
+```
+
+### Element CRUD
+
+| Method | Signature | Purpose |
+|---|---|---|
+| `addAndUpdateElementsInGraph` | `(nodes: Node[] \| PartialNode[], rels: Relationship[] \| PartialRelationship[]) => void` | Insert new; update existing by id |
+| `addElementsToGraph` | `(nodes: Node[], rels: Relationship[]) => void` | Insert only |
+| `updateElementsInGraph` | `(nodes: PartialNode[], rels: PartialRelationship[]) => void` | Update existing only; ignores unknown ids |
+| `removeNodesWithIds` | `(ids: string[]) => void` | Remove nodes + adjacent relationships |
+| `removeRelationshipsWithIds` | `(ids: string[]) => void` | Remove relationships |
+
+### Element Read
+
+| Method | Signature |
+|---|---|
+| `getNodes` | `() => NodeWithClientPosition[]` |
+| `getRelationships` | `() => Relationship[]` |
+| `getNodeById` | `(id: string) => Node` |
+| `getRelationshipById` | `(id: string) => Relationship` |
+| `getPositionById` | `(id: string) => Node` |
+| `getNodesOnScreen` | `() => { nodes: Node[]; rels: Relationship[] }` |
+| `getNodePositions` | `() => (Node & Point)[]` |
+| `setNodePositions` | `(data: Node[], updateLayout?: boolean) => void` |
+| `getSelectedNodes` | `() => (Node & Point)[]` |
+| `getSelectedRelationships` | `() => Relationship[]` |
+| `deselectAll` | `() => void` |
+
+### Viewport
+
+| Method | Signature |
+|---|---|
+| `fit` | `(nodeIds: string[], zoomOptions?: ZoomOptions) => void` (empty array = fit all) |
+| `resetZoom` | `() => void` |
+| `setZoom` | `(zoom: number) => void` |
+| `setPan` | `(panX: number, panY: number) => void` |
+| `setZoomAndPan` | `(zoom: number, panX: number, panY: number) => void` |
+| `getScale` | `() => number` |
+| `getPan` | `() => Point` |
+| `getZoomLimits` | `() => { minZoom: number; maxZoom: number }` |
+
+### Layout / Renderer / Pin
+
+| Method | Signature |
+|---|---|
+| `setLayout` | `(layout: Layout) => void` |
+| `setLayoutOptions` | `(options: LayoutOptions) => void` |
+| `isLayoutMoving` | `() => boolean` |
+| `setRenderer` | `(renderer: 'canvas' \| 'webgl') => void` |
+| `setDisableWebGL` | `(disabled?: boolean) => void` |
+| `pinNode` | `(nodeId: string) => void` |
+| `unPinNode` | `(nodeIds: string[]) => void` |
+
+### Export / Save
+
+| Method | Signature |
+|---|---|
+| `saveToFile` | `(opts?: { filename?: string; backgroundColor?: string }) => void` (PNG of current view) |
+| `saveFullGraphToLargeFile` | `(opts?: { filename?: string; backgroundColor?: string }) => void` (PNG of full graph) |
+| `saveToSvg` | `(opts?: { filename?: string; backgroundColor?: string }) => void` (experimental) |
+| `getImageDataUrl` | `(opts?: { backgroundColor?: string }) => string` |
+| `getSvgDataUrl` | `(opts?: { backgroundColor?: string }) => Promise<string>` |
+
+### Hit Testing
+
+```typescript
+getHits(
+  evt: MouseEvent,
+  targets?: ('node' | 'relationship' | 'cluster')[], // default: all three
+  hitOptions?: { hitNodeMarginWidth: number } // default 0
+): NvlMouseEvent
+```
+
+### Lifecycle / Misc
+
+| Method | Signature |
+|---|---|
+| `getCurrentOptions` | `() => NvlOptions` |
+| `getContainer` | `() => HTMLElement` |
+| `restart` | `(options?: NvlOptions, retainPositions?: boolean) => void` |
+| `destroy` | `() => void` |
+
+---
+
+## Core Types
+
+### `Node`
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | `string` | Required; unique across nodes AND relationships |
+| `caption` | `string` | Single caption (superseded by `captions`) |
+| `captions` | `StyledCaption[]` | Multi-line captions with styles |
+| `captionSize` | `number` | Text size |
+| `captionAlign` | `'top' \| 'bottom' \| 'center'` | |
+| `color` | `string` | Fill color |
+| `size` | `number` | Radius |
+| `pinned` | `boolean` | Excluded from layout forces |
+| `x` / `y` | `number` | Position |
+| `selected` | `boolean` | |
+| `hovered` | `boolean` | |
+| `activated` | `boolean` | |
+| `disabled` | `boolean` | |
+| `icon` | `string` | URL to image inside node |
+| `html` | `HTMLElement` | DOM overlay |
+| `overlayIcon` | `{ url: string; position?: number[]; size?: number }` | |
+
+`getNodes()` and `onLayoutStep` use:
+
+```typescript
+type NodeWithClientPosition = Node & Point & {
+  clientPosition: Point
+}
+```
+
+`x` and `y` are canvas/layout coordinates. `clientPosition` is relative to the canvas element.
+
+### `Relationship`
+
+| Field | Type | Notes |
+|---|---|---|
+| `id` | `string` | Required; unique across nodes AND relationships |
+| `from` | `string` | Source node id |
+| `to` | `string` | Target node id |
+| `type` | `string` | Relationship type label |
+| `width` | `number` | |
+| `color` | `string` | |
+| `caption` / `captions` / `captionSize` / `captionAlign` | (same as Node) | |
+| `captionHtml` | `HTMLElement` | DOM overlay on caption |
+| `selected` / `hovered` / `disabled` | `boolean` | |
+
+### Partial types
+
+```typescript
+type PartialNode         = Partial<Node>         & { id: string }
+type PartialRelationship = Partial<Relationship> & { id: string }
+```
+
+---
+
+## `NvlOptions`
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `instanceId` | `string` | — | |
+| `layout` | `Layout` | `'forceDirected'` | See Layout enum below |
+| `layoutOptions` | `LayoutOptions` | — | Layout-specific |
+| `layoutTimeLimit` | `number` | — | ms cap for layout iteration |
+| `minFps` | `number` | `3` | Minimum presentation target while layout is active; capped to `1..120` |
+| `maxFps` | `number` | `30` | Maximum presentation target while layout is active; capped to `1..120` |
+| `minZoom` | `number` | `0.075` | |
+| `maxZoom` | `number` | `10` | |
+| `allowDynamicMinZoom` | `boolean` | `true` | Permits going below `minZoom` to fit |
+| `initialZoom` | `number` | — | |
+| `panX` / `panY` | `number` | — | |
+| `renderer` | `'canvas' \| 'webgl'` | `'canvas'` | WebGL is WebGL2-only and does not render captions |
+| `disableWebGL` | `boolean` | `false` | Force-off WebGL even if requested |
+| `disableWebWorkers` | `boolean` | `false` | Use synchronous layout fallback |
+| `disableTelemetry` | `boolean` | `false` | |
+| `disableAria` | `boolean` | `false` | |
+| `minimapContainer` | `HTMLElement \| null` | — | |
+| `styling` | `StylingOptions` | — | |
+| `callbacks` | `ExternalCallbacks` | — | (also passable as 5th constructor arg) |
+| `logging` | `{ level: LogLevelDesc }` | — | |
+
+### `StylingOptions`
+
+| Field | Type |
+|---|---|
+| `defaultNodeColor` | `string` |
+| `defaultRelationshipColor` | `string` |
+| `nodeDefaultBorderColor` | `string` |
+| `selectedBorderColor` | `string` |
+| `selectedInnerBorderColor` | `string` |
+| `dropShadowColor` | `string` |
+| `disabledItemColor` | `string` |
+| `disabledItemFontColor` | `string` |
+| `overlayLineColor` | `string` |
+| `minimapViewportBoxColor` | `string` (deprecated; use `overlayLineColor`) |
+
+### Layout enum + constants
+
+```typescript
+type Layout = 'forceDirected' | 'hierarchical' | 'grid' | 'free' | 'd3Force' | 'circular'
+
+// Exported constants (string literals):
+ForceDirectedLayoutType   // 'forceDirected'
+HierarchicalLayoutType    // 'hierarchical'
+GridLayoutType            // 'grid'
+FreeLayoutType            // 'free'
+d3ForceLayoutType         // 'd3Force'
+CircularLayoutType        // 'circular'
+```
+
+### `LayoutOptions` union
+
+```typescript
+type LayoutOptions = ForceDirectedOptions | HierarchicalOptions | CircularOptions
+
+interface ForceDirectedOptions {
+  seedingMethod?: 'box' | 'circle'
+  clustering?: ClusteringOptions
+}
+
+type ClusterId = string | number
+type ClusterByFn = (nodeId: string) => ClusterId | undefined
+
+interface ClusteringOptions {
+  clusterBy?: ClusterByFn
+  drawOutline?: boolean
+  drawHalo?: boolean
+  crossClusterRelationshipMultiplier?: number // experimental, capped to 0..1
+}
+
+interface HierarchicalOptions {
+  direction?: 'up' | 'down' | 'left' | 'right'
+  packing?:   'bin' | 'stack'
+  clusterBy?: ClusterByFn // experimental
+}
+
+interface CircularOptions {
+  sortFunction?: (nodes: Node[]) => Node[]
+}
+```
+
+### `ZoomOptions`
+
+| Field | Type | Purpose |
+|---|---|---|
+| `noPan` | `boolean` | Zoom without changing pan |
+| `outOnly` | `boolean` | Only zoom out to fit |
+| `minZoom` | `number` | Override for this op |
+| `maxZoom` | `number` | Override for this op |
+| `animated` | `boolean` | Animate transition |
+
+### Renderer constants
+
+```typescript
+type Renderer = 'webgl' | 'canvas'
+
+WebGLRendererType   // 'webgl'
+CanvasRendererType  // 'canvas'
+```
+
+### `StyledCaption`
+
+```typescript
+type StyledCaption = {
+  styles: string[]   // e.g. ['bold','italic']
+  value:  string
+  key:    string
+}
+```
+
+### `Point`
+
+```typescript
+type Point = { x: number; y: number }
+```
+
+---
+
+## `ExternalCallbacks`
+
+| Callback | Signature |
+|---|---|
+| `onInitialization` | `() => void` |
+| `onLayoutDone` | `() => void` |
+| `onLayoutStep` | `(nodes: NodeWithClientPosition[]) => void` |
+| `onLayoutComputing` | `(isComputing: boolean) => void` |
+| `onError` | `(error: Error) => void` |
+| `onWebGLContextLost` | `(event: WebGLContextEvent) => void` |
+| `onZoomTransitionDone` | `() => void` |
+| `restart` | `() => void` |
+
+---
+
+## Hit Testing Types
+
+```typescript
+interface NvlMouseEvent extends MouseEvent {
+  nvlTargets: HitTargets
+}
+
+type HitTargets = {
+  nodes:         HitTargetNode[]
+  relationships: HitTargetRelationship[]
+  clusters:      HitTargetCluster[]
+}
+
+interface HitTargetNode {
+  data:               Node
+  targetCoordinates:  Point
+  pointerCoordinates: Point
+  distanceVector:     Point
+  distance:           number
+  insideNode:         boolean
+}
+
+interface HitTargetRelationship {
+  data:                   Relationship
+  fromTargetCoordinates:  Point
+  toTargetCoordinates:    Point
+  pointerCoordinates:     Point
+  distance:               number
+}
+
+type Cluster = {
+  id: string | number
+  nodeIds: string[]
+}
+
+interface HitTargetCluster {
+  data:               Cluster
+  pointerCoordinates: Point
+  hull:                Point[]
+}
+```
+
+---
+
+## `nvlResultTransformer`
+
+```typescript
+import type { ResultTransformer, EagerResult } from 'neo4j-driver'
+
+const nvlResultTransformer: ResultTransformer<
+  EagerResult,
+  { nodes: Node[]; relationships: Relationship[] }
+>
+```
+
+Usage: `driver.executeQuery(cypher, params, { database: 'neo4j', resultTransformer: nvlResultTransformer })`. Returns deduplicated `{ nodes, relationships }`.
+
+---
+
+## Named Exports — `@neo4j-nvl/base`
+
+```typescript
+// values
+export {
+  NVL,                         // also default export
+  nvlResultTransformer,
+  colorMapperFunctions,
+  CompatibilityError,
+  drawCircleBand,
+  getZoomTargetForNodePositions,
+  ForceDirectedLayoutType,
+  HierarchicalLayoutType,
+  GridLayoutType,
+  FreeLayoutType,
+  d3ForceLayoutType,
+  CircularLayoutType
+}
+
+// types
+export type {
+  NvlOptions, Renderer, Node, NodeWithClientPosition, Relationship,
+  PartialNode, PartialRelationship,
+  Layout, LayoutOptions, ForceDirectedOptions, ClusteringOptions,
+  Cluster, ClusterByFn, ClusterId, HierarchicalOptions, CircularOptions,
+  ExternalCallbacks, HitTargets, HitTargetNode, HitTargetRelationship,
+  HitTargetCluster, HitTestTarget,
+  Point, NvlMouseEvent, ZoomOptions, StyledCaption,
+  WebGLRendererType, CanvasRendererType
+}
+```
+
+---
+
+## Interaction Handlers
+
+All extend `BaseInteraction<P>`:
+
+```typescript
+class BaseInteraction<P> {
+  constructor(nvl: NVL, options?: P)
+  updateCallback(name: string, callback: ((...args: unknown[]) => void) | boolean): void
+  removeCallback(name: string): void
+  destroy(): void
+  readonly currentOptions: P
+}
+```
+
+Callback semantics: `function` = enable + invoke; `true` = enable as no-op; omitted/removed = disable.
+
+### `ZoomInteraction`
+
+```typescript
+new ZoomInteraction(nvl, options?: { controlledZoom?: boolean })
+```
+
+| Event | Signature |
+|---|---|
+| `onZoomAndPan` | `(zoomLevel: number, panX: number, panY: number, event: WheelEvent) => void` |
+
+### `PanInteraction`
+
+```typescript
+new PanInteraction(nvl, options?: { excludeNodeMargin?: boolean; controlledPan?: boolean })
+panInteraction.updateTargets(targets: ('node'|'relationship')[], excludeNodeMargin: boolean): void
+```
+
+| Event | Signature |
+|---|---|
+| `onPan` | `(panning: { x: number; y: number }, event: MouseEvent) => void` |
+
+### `ClickInteraction`
+
+```typescript
+new ClickInteraction(nvl, options?: { selectOnClick?: boolean })
+```
+
+| Event | Signature |
+|---|---|
+| `onNodeClick` | `(node: Node, hits: HitTargets, event: MouseEvent) => void` |
+| `onRelationshipClick` | `(rel: Relationship, hits: HitTargets, event: MouseEvent) => void` |
+| `onClusterClick` | `(cluster: Cluster, hits: HitTargets, event: MouseEvent) => void` |
+| `onCanvasClick` | `(event: MouseEvent) => void` |
+| `onNodeDoubleClick` | `(node, hits, event) => void` |
+| `onRelationshipDoubleClick` | `(rel, hits, event) => void` |
+| `onClusterDoubleClick` | `(cluster, hits, event) => void` |
+| `onCanvasDoubleClick` | `(event) => void` |
+| `onNodeRightClick` | `(node, hits, event) => void` |
+| `onRelationshipRightClick` | `(rel, hits, event) => void` |
+| `onClusterRightClick` | `(cluster, hits, event) => void` |
+| `onCanvasRightClick` | `(event) => void` |
+
+### `HoverInteraction`
+
+```typescript
+new HoverInteraction(nvl, options?: { drawShadowOnHover?: boolean })
+```
+
+| Event | Signature |
+|---|---|
+| `onHover` | `(element: Node \| Relationship \| undefined, hits: HitTargets, event: MouseEvent) => void` |
+
+### `DragNodeInteraction`
+
+```typescript
+new DragNodeInteraction(nvl)
+```
+
+| Event | Signature |
+|---|---|
+| `onDragStart` | `(nodes: Node[], event: MouseEvent) => void` |
+| `onDrag` | `(nodes: Node[], event: MouseEvent) => void` |
+| `onDragEnd` | `(nodes: Node[], event: MouseEvent) => void` |
+
+### `BoxSelectInteraction`
+
+```typescript
+new BoxSelectInteraction(nvl, options?: { selectOnRelease?: boolean })
+```
+
+| Event | Signature |
+|---|---|
+| `onBoxStarted` | `(event: MouseEvent) => void` |
+| `onBoxSelect` | `(selection: { nodes: Node[]; rels: Relationship[] }, event: MouseEvent) => void` |
+
+### `LassoInteraction`
+
+```typescript
+new LassoInteraction(nvl, options?: { selectOnRelease?: boolean })
+```
+
+| Event | Signature |
+|---|---|
+| `onLassoStarted` | `(event: MouseEvent) => void` |
+| `onLassoSelect` | `(selection: { nodes: Node[]; rels: Relationship[] }, event: MouseEvent) => void` |
+
+### `KeyboardInteraction`
+
+```typescript
+new KeyboardInteraction(nvl, options?: {
+  enterGraphKey?:      string[]
+  navigateForwardKey?: string[]
+  navigateBackwardKey?:string[]
+  exitGraphKey?:       string[]
+  contextMenuKey?:     string[]
+})
+keyboard.getFocused(): Node | Relationship | undefined
+```
+
+| Event | Signature |
+|---|---|
+| `onKeyDown` | `(event: KeyboardEvent, focused?: Node \| Relationship) => void` |
+| `onKeyUp` | `(event: KeyboardEvent, focused?: Node \| Relationship) => void` |
+| `onNodeFocus` / `onNodeBlur` | `(node: Node, event: KeyboardEvent) => void` |
+| `onRelationshipFocus` / `onRelationshipBlur` | `(rel: Relationship, event: KeyboardEvent) => void` |
+| `onCanvasFocus` / `onCanvasBlur` | `(event: FocusEvent) => void` |
+| `onContextMenu` | `(element: Node \| Relationship \| undefined, event: KeyboardEvent) => void` |
+
+---
+
+## React Components
+
+### `<InteractiveNvlWrapper>`
+
+| Prop | Type | Notes |
+|---|---|---|
+| `nodes` | `Node[]` | |
+| `rels` | `Relationship[]` | |
+| `nvlOptions` | `NvlOptions` | |
+| `nvlCallbacks` | `ExternalCallbacks` | |
+| `positions` | `Node[]` | |
+| `zoom` | `number` | |
+| `pan` | `{ x: number; y: number }` | |
+| `mouseEventCallbacks` | `MouseEventCallbacks` | See below |
+| `keyboardEventCallbacks` | `KeyboardEventCallbacks` | See below |
+| `interactionOptions` | `InteractionOptions` | Defaults: `{ selectOnClick: false, drawShadowOnHover: true, selectOnRelease: false, excludeNodeMargin: true }` |
+| `onInitializationError` | `(error: unknown) => void` | |
+| `ref` | `Ref<NVL>` | Underlying NVL instance |
+| (plus `HTMLProps<HTMLDivElement>`) | | |
+
+### `<BasicNvlWrapper>`
+
+Same prop set EXCEPT no `mouseEventCallbacks` / `keyboardEventCallbacks` / `interactionOptions`. `ref` resolves to `IncludeMethods<NVL>` — exposes all NVL public methods.
+
+### `<StaticPictureWrapper>`
+
+| Prop | Type | Default |
+|---|---|---|
+| `nodes` | `Node[]` | — |
+| `rels` | `Relationship[]` | — |
+| `nvlOptions` | `NvlOptions` | — |
+| `width` | `number` | `500` |
+| `height` | `number` | `500` |
+| `format` | `'png' \| 'svg'` | `'png'` |
+
+Renders an ephemeral NVL, fits viewport, captures, destroys. Returns `<img />`.
+
+### `MouseEventCallbacks`
+
+Union of all handler callbacks. Each value can be a function (with the signature above), `true` (enabled, no callback), or omitted / `false` (disabled):
+
+```
+onNodeClick, onRelationshipClick, onCanvasClick,
+onClusterClick,
+onNodeDoubleClick, onRelationshipDoubleClick, onClusterDoubleClick, onCanvasDoubleClick,
+onNodeRightClick, onRelationshipRightClick, onClusterRightClick, onCanvasRightClick,
+onHover,
+onPan, onZoomAndPan,
+onDragStart, onDrag, onDragEnd,
+onBoxStarted, onBoxSelect,
+onLassoStarted, onLassoSelect,
+onHoverNodeMargin, onDrawStarted, onDrawEnded
+```
+
+### `KeyboardEventCallbacks`
+
+```
+onKeyDown, onKeyUp,
+onNodeFocus, onNodeBlur,
+onRelationshipFocus, onRelationshipBlur,
+onCanvasFocus, onCanvasBlur,
+onContextMenu
+```
+
+### `InteractionOptions`
+
+Merged union of every handler's options:
+
+```
+{ selectOnClick?, drawShadowOnHover?, selectOnRelease?, excludeNodeMargin?, controlledZoom?,
+  controlledPan?, enterGraphKey?, navigateForwardKey?, navigateBackwardKey?, exitGraphKey?,
+  contextMenuKey?, ghostGraphStyling? }
+```