Merge pull request #275 from OskarDamkjaer/react-viz

Move the GraphVisualization wrapper

Author: FlorentinD

.github/workflows/code-style.yml

@@ -33,7 +33,7 @@ jobs:
           python-version: "3.11"
           enable-cache: true
       - run: uv venv
-      - run: uv sync --group dev --extra pandas --extra gds --extra snowflake
+      - run: uv sync --group dev --extra pandas --extra neo4j --extra gds --extra snowflake
 
       - name: Check code style
         run: source .venv/bin/activate && cd ${GITHUB_WORKSPACE} && ./scripts/checkstyle.sh

.github/workflows/nvl-entrypoint-test.yml

@@ -5,24 +5,18 @@ name: Build JS Applet and check for changes
 on:
   # Triggers the workflow on push or pull request events but only for the "main" branch
   push:
-    branches: [ "main" ]
+    branches: ["main"]
   pull_request:
     paths:
-      - "js-applet/src/nvl_entrypoint/**" # JS sources
-      - "js-applet/webpack.config.js"
-      - "js-applet/babel.config.js"
-      - "js-applet/package.json"
-      - "js-applet/tsconfig.json"
-    branches: [ "main" ]
+      - "js-applet/**"
+    branches: ["main"]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
 # A workflow run is made up of one or more jobs that can run sequentially or in parallel
 jobs:
-
   tests:
-
     # The type of runner that the job will run on
     runs-on: "ubuntu-latest"
 
@@ -34,7 +28,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: '23.x'
+          node-version: "24.x"
       - name: Setup
         run: yarn
       - name: Build

.github/workflows/snowflake-integration-tests.yml

@@ -43,4 +43,4 @@ jobs:
           SNOWFLAKE_PASSWORD: ${{ secrets.SNOWFLAKE_PASSWORD }}
           SNOWFLAKE_ROLE: ACCOUNTADMIN
           SNOWFLAKE_WAREHOUSE: ${{ secrets.SNOWFLAKE_WAREHOUSE }}
-        run: pytest tests/ --include-snowflake
+        run: uv run pytest tests/ --include-snowflake

.gitignore

@@ -27,4 +27,6 @@ out/*
 .idea
 
 .dmypy.json
-python-wrapper/uv.lock
+.virtual_documents
+# ignore top-level yarn files, the js-applet files are relevant
+yarn.lock

CONTRIBUTING.md

@@ -9,7 +9,6 @@ If you're not already a member, sign up!
 
 We love our community and wouldn't be where we are without you.
 
-
 ## Need to raise an issue?
 
 Where you raise an issue depends largely on the nature of the problem.
@@ -34,7 +33,6 @@ Include as much information as you can in any request you make:
 - What errors are you seeing?
 - What solutions have you tried already?
 
-
 ## Want to contribute?
 
 If you want to contribute a pull request, we have a little bit of process you'll need to follow:
@@ -50,102 +48,87 @@ We can't guarantee that we'll accept pull requests and may ask you to make some
 Occasionally, we might also have logistical, commercial, or legal reasons why we can't accept your work but we'll try to find an alternative way for you to contribute in that case.
 Remember that many community members have become regular contributors and some are now even Neo employees!
 
-
-## Building the project locally
-
-To build the Python packages, run inside the `python-wrapper` folder:
+## Quick start
 
 ```sh
-pip install . # run with --editable for development mode
+just js-dev
 ```
 
-To rebuild the JavaScript applet, run inside the `js-applet` folder:
+This starts Vite watch builds and Jupyter Lab with hot module reloading. Changes to `js-applet/src/` will auto-reload in active widget cells.
+
+If you want to modify the python code, run:
 
 ```sh
-yarn          # Install JavaScript dependencies
-yarn build    # Build JavaScript resources to be used by Python code
+just py-sync
 ```
 
-This will build the app and copy the relevant files to the python wrapper
+This will install all required dev dependencies and install the package in editable mode.
 
 
 ## Specifically for this project
 
 In this section, we will provide some more specific information about how to work with this particular project.
 
-
 ### Python development environment
 
- * Install Python 3.9+
- * [Install pip](https://pip.pypa.io/en/stable/installation/)
- * Install the project's Python dependencies:
-   ```bash
-   pip install -e .
-   pip install ".[dev]"
-   ```
+- Install Python 3.10+
+- We recommend installing [just](https://github.com/casey/just) for running commands
+
+Install the project's Python dependencies:
+  ```bash
+  just py-sync
+  ```
+
+Apply and check python styling:
+```sh
+just py-style
+```
+
 
 ### Testing
 
 To run unit tests, execute:
 
 ```sh
-pytest python-wrapper/tests
+just py-test
 ```
 
 Additionally, there are integration tests that require an external data source.
 These require additional setup and configuration, such as environment variables specifying connection details.
 
-
-For a local Neo4j instance with GDS installed, execute:
+To test the Neo4j and GDS related tests, execute:
 ```sh
-cd test-envs/neo4j-gds
-docker compose up -d
-```
-
-To run tests requiring a Neo4j DB instance with GDS installed, execute:
-```sh
-export NEO4J_URI=localhost:7687 # or credentials for Aura API
-cd python-wrapper/
-pytest tests --include-neo4j-and-gds
+just py-test-gds
 ```
+This will spinup a Neo4j container with the GDS plugin installed.
 
 To run tests requiring a Snowflake connection, execute:
-
 ```sh
 cd python-wrapper/
 pytest tests/ --include-snowflake
 ```
 
-
 ### Project structure
 
 The project contains of three parts:
 
-- a JavaScript applet whith a basic NVL implementation under the `js-applect` folder
+- a JavaScript applet under the `js-applet` folder
 - a Python package which loads the applet and offers convenience functions to pass data to the applet
-- Jupyter notebooks to test the NVL Python wrapper
-
+- Jupyter notebooks to test the Python wrapper
 
-### JavaScipts configs
-
-* `babel.config.js` - Config for the JavaScript compiler
-* `tsconfig.json` - Configuration for TypeScript code
-* `package.json` - For yarn, define dependencies and `build` target
-* `webpack.config.js` - Config for bundling JS parts
+### JavaScript configs
 
+- `vite.config.ts` - Vite config for the lib build (widget.js + style.css for anywidget)
+- `vite.config.html.ts` - Vite config for the HTML singlefile build (self-contained index.html)
+- `tsconfig.json` - Configuration for TypeScript code
+- `package.json` - For yarn, define dependencies and `build` target
 
 ### Python
 
 Everything is configured inside `pyproject.toml`
 
 To keep a consistent code-style, we use `ruff` and `mypy`.
-For convenience there are a couple of scripts:
-
-```sh
-./scripts/makestyle.sh # try to fix linting violations and format code
-./scripts/checkstyle.sh # check for linting, format or typing issues
-
-```
+For convenience there are a couple of just targets under `justfile`:
 
 
 ## Got an idea for a new project?
@@ -155,7 +138,6 @@ Chances are that someone has a similar idea or may have already started working
 The best software comes from getting like minds together to solve a problem.
 And we'll do our best to help you promote and co-ordinate your Neo4j ecosystem projects.
 
-
 ## Further reading
 
 If you want to find out more about how you can contribute, head over to our website for [more information](http://neo4j.com/developer/contributing-code/).

MANIFEST.in

@@ -1 +1 @@
-include examples/example_cora_graph.png
+include examples/example_graph.png

README.md

@@ -10,12 +10,13 @@
 
 `neo4j-viz` is a Python package for creating interactive graph visualizations.
 
-The output is of type `IPython.display.HTML` and can be viewed directly in a Jupyter Notebook or Streamlit application.
+The `render` method returns an `IPython.display.HTML` object that can be viewed directly in a Jupyter Notebook or Streamlit application.
+For an interactive widget experience, use `render_widget()` which returns an anywidget-based `GraphWidget` with two-way data sync.
 Alternatively, you can export the output to a file and view it in a web browser.
 
 The package wraps the [Neo4j Visualization JavaScript library (NVL)](https://neo4j.com/docs/nvl/current/).
 
-![Example Graph](examples/example_cora_graph.png)
+![Example Graph](examples/example_graph.png)
 
 ## Some notable features
 
@@ -102,7 +103,8 @@ VG = VisualizationGraph(nodes=nodes, relationships=relationships)
 VG.render()
 ```
 
-This will return a `IPython.display.HTML` object that can be rendered in a Jupyter Notebook or streamlit application.
+This will return an `IPython.display.HTML` object that can be rendered in a Jupyter Notebook or Streamlit application.
+For an interactive Jupyter widget, use `VG.render_widget()` instead.
 
 Please refer to the [documentation](https://neo4j.com/docs/nvl-python/preview/) for more details on the API and usage.
 

changelog.md

@@ -2,12 +2,22 @@
 
 ## Breaking changes
 
+- Removed the `show_hover_tooltip` parameter from `render()`. The visualization now shows a detail side panel for selected nodes and relationships, replacing the previous hover tooltip.
+- Nodes are colored by default by their caption. Use `VG.color_nodes(field="caption", colors=[neo4j_viz.colors.NEO4J_COLORS_DISCRETE[0]])` to apply the previous coloring.
+
 
 ## New features
 
+- Nodes are now automatically colored by their caption (label) in the JavaScript visualization. This works out of the box without needing to call `color_nodes()`, and applies regardless of how the graph was created. Explicit colors set via `color_nodes()` or directly on nodes take precedence. There is no longer a limit on the number of unique labels for auto-coloring.
+- New `Zoom to fit` button in the visualization.
+- New `render_widget()` method on `VisualizationGraph` returns a `GraphWidget` (anywidget) for interactive two-way data sync in Jupyter environments (JupyterLab, Notebook 7, VS Code, Colab).
+
 ## Bug fixes
 
 ## Improvements
 
+- Migrated JavaScript visualization from `@neo4j-nvl/base` to `@neo4j-ndl/react-graph` React component.
+- Migrated build system from Webpack to Vite.
+- Added anywidget integration as the primary rendering path for Jupyter environments.
 
 ## Other changes

docs/antora/modules/ROOT/pages/customizing.adoc

@@ -55,6 +55,8 @@ Nodes and relationships can be colored directly by providing them with a color f
 This can be done by passing a color as a string to the `color` parameter of the
 link:{api-docs-uri}/node[Node] or link:{api-docs-uri}/relationship[Relationship] object.
 
+By default, the nodes will be colored based on their caption. The colors are the same as in other Neo4j tools, such as Neo4j Console and Neo4j Browser.
+
 Alternatively, you can color nodes or relationships based on a field or property after a `VisualizationGraph` object has been
 created.
 
@@ -258,4 +260,4 @@ for relationship in VG.relationships:
     relationship.caption_size = 15
 ----
 
-Any changes made to the nodes and relationships will be reflected in the next rendering of the graph.
+Any changes made to the nodes and relationships will be reflected in the next rendering of the graph.