@neo4j-nvl/base 2.0.0-c8e499dc → 2.0.0-ec6fdba7

package/skills/neo4j-nvl-skill/references/react-wrappers.md

@@ -0,0 +1,88 @@
+# React wrappers
+
+When you need this: you use `<InteractiveNvlWrapper>` or `<BasicNvlWrapper>` from `@neo4j-nvl/react` and something does not react to a prop change, a callback sees stale state, or an interaction does not start.
+
+Verification tags: **source** = `packages/react/src` in the NVL repository, **types** = shipped `.d.ts`, **runtime** = observed in a running app.
+
+## Which wrapper
+
+- `<InteractiveNvlWrapper>`: `<BasicNvlWrapper>` plus every interaction handler, toggled through `mouseEventCallbacks` and `keyboardEventCallbacks`.
+- `<BasicNvlWrapper>`: NVL only. Use it when you wire interactions yourself through the `ref`.
+
+Both forward a `ref` to the `NVL` instance (`useRef<NVL>(null)`) and pass unknown props to the container `<div>`. The container is `height: 100%`, so the **parent** needs an explicit height. *source*
+
+## `mouseEventCallbacks` → handler
+
+A key set to a function enables the handler and registers the callback; `true` enables the handler with no callback; `false` destroys the handler; omitted means off. *source*
+
+| Handler | Keys |
+|---|---|
+| Hover | `onHover` |
+| Click | `onNodeClick`, `onRelationshipClick`, `onCanvasClick`, `onClusterClick`, and the `...DoubleClick` / `...RightClick` variants |
+| Pan | `onPan` |
+| Zoom (wheel) | `onZoomAndPan` |
+| Drag nodes | `onDrag`, `onDragStart`, `onDragEnd` |
+| Draw | `onHoverNodeMargin`, `onDrawStarted`, `onDrawEnded` |
+| Box select | `onBoxStarted`, `onBoxSelect` |
+| Lasso | `onLassoStarted`, `onLassoSelect` |
+| Keyboard (`keyboardEventCallbacks`) | `onKeyDown`, `onKeyUp`, `onNodeFocus`, `onNodeBlur` |
+
+There is no `onZoom` key. `{ onZoom: true }` is ignored and wheel zoom stays off. *source*
+
+Interaction callbacks are re-registered whenever the function identity changes, so they are **not** subject to the stale-closure problem below. *source*
+
+## `nvlCallbacks` are captured once
+
+`BasicNvlWrapper` passes `nvlCallbacks` to the `NVL` constructor and never updates them. A callback that closes over state sees the state from the first render. *source*
+
+```tsx
+const selectedRef = useRef(selected)
+selectedRef.current = selected
+
+const nvlCallbacks = useMemo(() => ({
+  onLayoutDone: () => console.log('layout done, selected:', selectedRef.current)
+}), [])
+```
+
+## Which `nvlOptions` update after creation
+
+Only these are watched by effects: `layout` (`setLayout`), `layoutOptions` (deep-compared, `setLayoutOptions`), `renderer` (`setRenderer`), `disableWebGL` (`setDisableWebGL`). Everything else (`styling`, `minZoom`, `initialZoom`, `disableTelemetry`, `disableWebWorkers`, ...) is read at construction. *source*
+
+Separate props with live effects: `positions` (`setNodePositions`), `zoom` and `pan` (`setZoom` / `setPan` / `setZoomAndPan`). *source*
+
+To change a creation-time option, call `nvlRef.current.restart(newOptions, true)` or remount the wrapper with a `key`.
+
+## `nodes` / `rels` diffing
+
+On every render the wrapper diffs the new arrays against the previous ones by `id`, then calls `addAndUpdateElementsInGraph` for added and changed elements and `removeNodesWithIds` / `removeRelationshipsWithIds` for removed ones. *source*
+
+- Only keys whose value changed are sent, so updates are partial. A key set to `undefined` is sent (and clears the attribute); a key that is omitted is not. *source*
+- Changing `x` / `y` on an existing node does **not** move it; positions are only read on insert. Use the `positions` prop or `setNodePositions`. *source*
+- `pinned` does apply through the diff. *runtime*
+- Keep the arrays referentially stable between renders (`useMemo`) or the diff runs on every render.
+
+## `minimapContainer` must exist first
+
+If `nvlOptions.minimapContainer` is present, NVL is not created until it is non-null. With a plain `useRef` the element is `null` on the first render and NVL never starts; hold the element in state via a callback ref. *source*
+
+```tsx
+const [minimapEl, setMinimapEl] = useState<HTMLDivElement | null>(null)
+const nvlOptions = useMemo(() => ({ minimapContainer: minimapEl }), [minimapEl])
+
+<div ref={setMinimapEl} style={{ width: 200, height: 150 }} />
+<InteractiveNvlWrapper nvlOptions={nvlOptions} ... />
+```
+
+## `interactionOptions` replaces the defaults
+
+The default is `{ selectOnClick: false, drawShadowOnHover: true, selectOnRelease: false, excludeNodeMargin: true }`. Passing the prop replaces this object, so `interactionOptions={{ selectOnClick: true }}` turns the hover shadow off. Pass every option you want. *source*
+
+Keep the object stable (`useMemo`); a new object each render re-runs every interaction effect.
+
+## Selection toggles twice / handlers duplicated
+
+Flipping `selectOnClick` or other `interactionOptions` across renders, or registering your own `container.addEventListener('click')` next to the wrapper's `ClickInteraction`, produces double handling. Set the options once and use the wrapper's callbacks.
+
+## Teardown
+
+The wrappers call `nvl.destroy()` on unmount and destroy their handlers. Only manual `new NVL(...)` in a `useEffect` needs an explicit `return () => nvl.destroy()`.

package/skills/neo4j-nvl-skill/references/verifying-nvl-apps.md

@@ -0,0 +1,52 @@
+# Verifying NVL apps
+
+When you need this: you want to check from a test, a script or a headless browser that the graph rendered, the layout finished, or nodes are where you expect.
+
+Verification tags: **source**, **types**, **runtime** (see `SKILL.md`).
+
+## Window hooks
+
+Every NVL instance registers these on `window` (declared in `nvl-window-functions.d.ts`). They are read-only test hooks; `instanceId` is the `nvlOptions.instanceId` you gave (default `'default'`). With several instances and no id, the most recently created one answers. *source*
+
+| Hook | Returns |
+|---|---|
+| `__Nvl_dumpNodes(instanceId?)` | `NodeWithClientPosition[]`: every node with `x`, `y` and `clientPosition` |
+| `__Nvl_dumpRelationships(instanceId?)` | `Relationship[]` |
+| `__Nvl_getNodesOnScreen(instanceId?)` | `{ nodes, rels }` currently inside the viewport |
+| `__Nvl_getZoomLevel(instanceId?)` | current zoom |
+| `__Nvl_registerDoneCallback(cb, instanceId)` | registers `cb` for `onLayoutDone`; note the argument order |
+
+Playwright example (the pattern used by this repository's build-tool tests): *source*
+
+```typescript
+await expect.poll(() => page.evaluate('window.__Nvl_dumpNodes !== undefined')).toBeTruthy()
+await expect.poll(() => page.evaluate(() => window.__Nvl_dumpNodes().length)).toBe(42)
+await page.evaluate(() => new Promise<void>((resolve) => window.__Nvl_registerDoneCallback(resolve, 'default')))
+```
+
+## Detecting a settled layout
+
+- Preferred: `onLayoutDone` (or `__Nvl_registerDoneCallback`).
+- Alternative: poll `__Nvl_dumpNodes()` and compare positions between two polls.
+- `onLayoutComputing(false)` fires when a computation ends; the force-directed layout may compute again after interactions.
+
+## What a screenshot can and cannot show
+
+- The WebGL canvas is not inspectable through the DOM; pixels are the only evidence. Captions are absent with WebGL (see [labels-and-overlays](labels-and-overlays.md)), so a text-based check needs the Canvas renderer or `html` overlays.
+- `getImageDataUrl()` returns the main canvas as PNG for in-process comparisons. *types*
+
+## Headless Chrome and WebGL2
+
+Headless Chrome uses software GL by default. The force-directed GPU simulation then runs so slowly that it looks hung. Launch with hardware GL: *runtime*
+
+```
+--use-angle=gl --use-gl=angle --enable-gpu --ignore-gpu-blocklist --disable-gpu-sandbox
+```
+
+Playwright: pass them in `launchOptions.args`. Allow long timeouts for the first layout. If no GPU is available, set `disableWebGL: true` in the test build so NVL uses the Canvas renderer and CPU layouts.
+
+## Checklist
+
+- Wait for `__Nvl_dumpNodes` to exist, then for the expected node count, then for `onLayoutDone`.
+- Set `instanceId` when a page has more than one graph.
+- Set `disableTelemetry: true` in test builds.

package/skills/neo4j-nvl-skill/references/vite-and-bundlers.md

@@ -0,0 +1,62 @@
+# Vite and other bundlers
+
+When you need this: a layout never finishes in development, the console mentions a worker script, or you set up a new project.
+
+Verification tags: **source**, **types**, **runtime** (see `SKILL.md`).
+
+## What runs in a worker
+
+Only the **hierarchical** layout uses a worker: a `SharedWorker` (`type: 'module'`, name `HierarchicalLayout`) created by `@neo4j-nvl/layout-workers` with `new URL('./HierarchicalLayout.worker.js', import.meta.url)`. The worker imports the CommonJS package `bin-pack`. Force-directed, circular, grid, free and d3Force run on the main thread or the GPU. *source*
+
+If the worker constructor throws, NVL logs a warning and falls back to the synchronous implementation automatically. A worker that is created but fails to **load** does not throw, so there is no fallback and the layout never completes. *source*
+
+## Vite dev server
+
+With Vite 7.3 the hierarchical layout works in `vite` dev without configuration: Vite discovers `bin-pack` from the worker graph and pre-bundles it. *runtime*
+
+**Symptom (reported with older Vite versions and npm-installed packages, not reproduced in this repository):** switching to `hierarchical` fires `onLayoutComputing(true)` and nothing else. The page console is clean; the worker's console (DevTools → Sources → Threads, or `chrome://inspect/#workers`) shows "Failed to fetch a worker script" or a CJS resolution error. `vite build` + `vite preview` works.
+
+**Cause:** Vite pre-bundles CommonJS dependencies found from the main module graph. If the worker graph is not scanned, `bin-pack` reaches the worker un-bundled.
+
+**Fix:**
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  optimizeDeps: { include: ['bin-pack'] }
+})
+```
+
+Restart `vite` after editing `optimizeDeps`; delete `node_modules/.vite` if the change does not take.
+
+With pnpm or other strict hoisting, `bin-pack` is a transitive dependency and not resolvable from the app root. Use Vite's nested syntax (documented by Vite, not exercised in this repository):
+
+```typescript
+optimizeDeps: {
+  include: ['@neo4j-nvl/base > @neo4j-nvl/layout-workers > bin-pack']
+}
+```
+
+## Webpack
+
+Webpack 5 handles `new SharedWorker(new URL(..., import.meta.url))` natively; no configuration is needed. The repository's build-tool tests cover webpack and Vite production builds. *source*
+
+## Other bundlers
+
+Not tested in this repository. Check that the bundler supports `new URL(..., import.meta.url)` in `SharedWorker` constructors and bundles CJS dependencies into worker chunks. If it does not, use `disableWebWorkers`.
+
+## `disableWebWorkers`
+
+```javascript
+new NVL(container, nodes, rels, { disableWebWorkers: true })
+```
+
+Runs the hierarchical layout synchronously on the main thread: same result, blocks the UI for large graphs. Use it when workers are blocked (CSP `worker-src 'none'`, sandboxed iframes) or a bundler cannot be configured. For the Vite dev case prefer `optimizeDeps`. *types, source*
+
+## Telling a worker failure from a slow layout
+
+- `onLayoutComputing(true)` followed by nothing for more than a few seconds on a small graph is a failure, not slowness.
+- `window.__Nvl_registerDoneCallback(cb)` never fires (see [verifying-nvl-apps](verifying-nvl-apps.md)).
+- Switch to `disableWebWorkers: true`: if the layout now completes, the worker is the problem.

package/dist/types/layouts/animatedlayout/AnimatedLayout.test.d.ts

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

package/dist/types/layouts/animatedlayout/animationUtils.test.d.ts

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

package/dist/types/layouts/d3forcelayout/__mocks__/d3ForceLayout.d.ts

@@ -1,10 +0,0 @@
-export declare class D3ForceLayout {
-    update(): void;
-    getNodePositions(items: unknown[]): unknown[];
-    getShouldUpdate(): boolean;
-    getComputing(): boolean;
-    destroy(): void;
-    setOptions(): void;
-    updateNodes(): void;
-    terminateUpdate(): void;
-}

package/dist/types/layouts/d3forcelayout/circularLayout.test.d.ts

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

package/dist/types/layouts/d3forcelayout/d3ForceLayout.test.d.ts

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

package/dist/types/layouts/forcedirectedlayout/PhysLayout.test.d.ts

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

package/dist/types/layouts/forcedirectedlayout/clustering/ClusterByMerger.test.d.ts

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

package/dist/types/layouts/forcedirectedlayout/clustering/SolarMerger.bench.d.ts

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

package/dist/types/layouts/forcedirectedlayout/clustering/SolarMerger.test.d.ts

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

package/dist/types/layouts/forcedirectedlayout/clustering/clustering-utils.test.d.ts

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

package/dist/types/modules/NvlController.test.d.ts

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

package/dist/types/modules/ZoomTransitionHandler.test.d.ts

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

package/dist/types/modules/dataset.test.d.ts

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

package/dist/types/modules/state/state.test.d.ts

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

package/dist/types/modules/state/utils.test.d.ts

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

package/dist/types/renderers/ClusterOverlay.test.d.ts

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

package/dist/types/renderers/domrenderer/BaseRenderer.test.d.ts

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

package/dist/types/renderers/domrenderer/canvasrenderer/Animation.test.d.ts

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

package/dist/types/renderers/domrenderer/canvasrenderer/CanvasRenderer.test.d.ts

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

package/dist/types/renderers/domrenderer/canvasrenderer/arrowDrawing.test.d.ts

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

package/dist/types/renderers/domrenderer/canvasrenderer/nodeDrawing.test.d.ts

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

package/dist/types/renderers/domrenderer/shared/ImageCache.test.d.ts

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

package/dist/types/renderers/domrenderer/shared/arrows/ArrowBundle.test.d.ts

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

package/dist/types/renderers/domrenderer/shared/arrows/ArrowBundler.test.d.ts

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

package/dist/types/renderers/domrenderer/shared/arrows/arrows.test.d.ts

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

package/dist/types/renderers/domrenderer/shared/nodes/nodes.test.d.ts

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

package/dist/types/renderers/domrenderer/shared/util.test.d.ts

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

package/dist/types/renderers/domrenderer/shared/wordwrap.test.d.ts

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

package/dist/types/renderers/domrenderer/svgrenderer/SvgRenderer.test.d.ts

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

package/dist/types/renderers/domrenderer/svgrenderer/arrowDrawing.test.d.ts

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

package/dist/types/renderers/domrenderer/svgrenderer/nodeDrawing.test.d.ts

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

package/dist/types/renderers/domrenderer/svgrenderer/svgUtils.test.d.ts

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

package/dist/types/renderers/webglrenderer/Controller.test.d.ts

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

package/dist/types/renderers/webglrenderer/IconLayerRegistry.test.d.ts

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

package/dist/types/renderers/webglrenderer/Renderer.test.d.ts

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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