1.8 release

.github/dependabot.yml

@@ -5,10 +5,13 @@
 
 version: 2
 updates:
-  - package-ecosystem: "pip"
+  - package-ecosystem: "uv"
     directory: "/python-wrapper"
     schedule:
       interval: "weekly"
+    open-pull-requests-limit: 10
+    cooldown:
+      default-days: 3
     groups:
       python-patch-and-minor:
         update-types:
@@ -21,6 +24,9 @@ updates:
     directory: "/js-applet"
     schedule:
       interval: "weekly"
+    cooldown:
+      default-day: 3
+      enabled: true
     groups:
       js-patch-and-minor:
         update-types:
@@ -29,3 +35,18 @@ updates:
       js-major:
         update-types:
           - "major"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-day: 3
+      enabled: true
+    groups:
+      github-actions-patch-and-minor:
+        update-types:
+          - "patch"
+          - "minor"
+      github-actions-major:
+        update-types:
+          - "major"

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

@@ -20,22 +20,22 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        gds-version: ["1.22", "2.0.0a1"]
+        gds-version: ["1.22", "2.0.0a4"]
     defaults:
       run:
         working-directory: python-wrapper
 
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Install uv and set the Python version
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
         with:
           python-version: "3.11"
           enable-cache: true
       - name: Install just
-        uses: extractions/setup-just@v2
+        uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
 
       - name: Run tests
         env:

.github/workflows/code-style.yml → .github/workflows/js-code-style.yml

@@ -1,4 +1,4 @@
-name: Check code style
+name: Check JS code style
 
 # Controls when the workflow will run
 on:
@@ -7,33 +7,39 @@ on:
     branches: ["main"]
   pull_request:
     paths:
-      - "python-wrapper/**" # python code + its resources
+      - "js-applet/**" # js/ts code + its resources
     branches: ["main"]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 # A workflow run is made up of one or more jobs that can run sequentially or in parallel
 jobs:
-  code-style:
+  js-code-style:
     # The type of runner that the job will run on
     runs-on: ubuntu-latest
 
     defaults:
       run:
-        working-directory: python-wrapper
+        working-directory: js-applet
 
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - name: Install uv and set the Python version
-        uses: astral-sh/setup-uv@v6
+      - name: Set up Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
-          python-version: "3.11"
-          enable-cache: true
-      - run: uv venv
-      - run: uv sync --group dev --extra pandas --extra neo4j --extra gds --extra snowflake
+          node-version: "lts/*"
+
+      - name: Install dependencies
+        run: yarn
+
+      - name: Lint
+        run: yarn lint
 
-      - name: Check code style
-        run: source .venv/bin/activate && cd ${GITHUB_WORKSPACE} && ./scripts/checkstyle.sh
+      - name: Check formatting
+        run: yarn format:check

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

@@ -25,8 +25,8 @@ jobs:
         working-directory: js-applet
 
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: "lts/*"
       - name: Setup

.github/workflows/publish_pypi.yml

@@ -16,9 +16,9 @@ jobs:
         working-directory: python-wrapper
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.x"
 

.github/workflows/py-code-style.yml

@@ -0,0 +1,69 @@
+name: Python - Check code style
+
+# Controls when the workflow will run
+on:
+  # Triggers the workflow on push or pull request events but only for the "main" branch
+  push:
+    branches: ["main"]
+  pull_request:
+    paths:
+      - "python-wrapper/**" # python code + its resources
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  code-style:
+    # The type of runner that the job will run on
+    runs-on: ubuntu-latest
+
+    defaults:
+      run:
+        working-directory: python-wrapper
+
+    # Steps represent a sequence of tasks that will be executed as part of the job
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install uv and set the Python version
+        uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
+        with:
+          python-version: "3.11"
+          enable-cache: true
+      - run: uv venv
+      - 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
+
+  # Type-check the v1 (1.22) side of the GDS compat surface.
+  code-style-gds-v1:
+    runs-on: ubuntu-latest
+
+    defaults:
+      run:
+        working-directory: python-wrapper
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install uv and set the Python version
+        uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
+        with:
+          python-version: "3.11"
+          enable-cache: true
+      - run: uv venv
+      - run: uv sync --group dev --extra pandas --extra neo4j --extra gds --extra snowflake
+      - run: uv pip install --python .venv/bin/python "graphdatascience==1.22"
+
+      - name: Check code style (GDS 1.22)
+        env:
+          UV_NO_SYNC: "1"
+          MYPY_TARGETS: "python-wrapper/src"
+        run: source .venv/bin/activate && cd ${GITHUB_WORKSPACE} && ./scripts/checkstyle.sh
+

.github/workflows/render-docs.yml

@@ -26,17 +26,17 @@ jobs:
 
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Install uv and set the Python version
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
         with:
           python-version: "3.11"
           enable-cache: true
       - run: uv sync --group dev --group docs --extra pandas --extra neo4j --extra gds --extra snowflake
 
       - name: Setup pandoc
-        uses: pandoc/actions/setup@v1
+        uses: pandoc/actions/setup@86321b6dd4675f5014c611e05088e10d4939e09e # v1
         with:
           version: 3.6.2
 

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

@@ -27,10 +27,10 @@ jobs:
 
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Install uv and set the Python version
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
         with:
           python-version: "3.11"
           enable-cache: true

.github/workflows/unit-tests.yml

@@ -31,10 +31,10 @@ jobs:
 
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Install uv and set the Python version
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
         with:
           python-version: ${{ matrix.python-version }}
           enable-cache: true

.gitignore

@@ -30,3 +30,4 @@ out/*
 .virtual_documents
 # ignore top-level yarn files, the js-applet files are relevant
 yarn.lock
+

changelog.md

@@ -4,13 +4,8 @@
 
 ## New features
 
-* Added a color legend overlay to the visualization. It is captured automatically from `color_nodes`/`color_relationships`, can be set explicitly via `set_legend`, and toggled via `show_legend`.
-* Added `neo4j_viz.streamlit.display_widget` to embed an interactive `GraphWidget` in a Streamlit app with two-way state sync (selection and options flow back to Python), following the Streamlit light/dark theme. Install with the `streamlit` extra (`pip install neo4j-viz[streamlit]`).
-
 ## Bug fixes
 
-* Fixed a bug where nodes and relationships could not be selected on using `VG.render()`.
-
 ## Improvements
 
 ## Other changes

docs/.gitignore

@@ -2,4 +2,5 @@ build
 
 # Antora docs
 antora/package-lock.json
-antora/node_modules/
+antora/node_modules/
+source/tutorials/*.png

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

@@ -288,6 +288,55 @@ widget.on_selection_change(on_selection_change)
 `on_selection_change` returns the registered handler, which you can pass to `widget.unobserve(handler, names=["selected"])`
 to stop reacting. You can also read `widget.selected` directly at any point for the current selection.
 
+== Reacting to interaction events
+
+Beyond reading the selection, the widget also exposes interaction events whenever the user clicks, double-clicks,
+or right-clicks a node, a relationship, or the canvas.
+The most recent event is available on the widget's `last_event` attribute, a typed
+link:{api-docs-uri}/widget[`InteractionEvent`] with a `type` and an `id`.
+
+To react to a specific event, register a callback with one of `widget.on_node_event(...)`,
+`widget.on_relationship_event(...)`, or `widget.on_canvas_event(...)`, depending on what was
+interacted with.
+Each takes a `MouseEvent` (one of `"click"`, `"double_click"`, `"right_click"` -- the category
+node/relationship/canvas is implied by the method) and a callback.
+The node and relationship callbacks receive the resolved link:{api-docs-uri}/node[Node] or
+link:{api-docs-uri}/relationship[Relationship] directly (matched by id from the widget's current
+`nodes`/`relationships`), or `None` if that id is no longer in the graph.
+Canvas events target the empty graph background rather than an entity, so the canvas callback takes
+no arguments.
+An unknown `MouseEvent` string raises `ValueError` when the callback is registered, so typos are
+caught early.
+
+One use case is growing the graph on demand -- for example fetching a node's neighborhood from a database when it
+is double-clicked:
+
+[source, python]
+----
+# VG is a VisualizationGraph object
+widget = VG.render_widget()
+
+
+def expand_neighborhood(node):
+    if node is None:
+        return
+    # ... fetch the double-clicked node's neighbors, then widget.add_data(...)
+
+
+widget.on_node_event("double_click", expand_neighborhood)
+----
+
+These methods return the registered handler, which you can pass to `widget.unobserve(handler, names=["last_event"])`
+to stop reacting.
+You can also read `widget.last_event` directly at any point for the most recent event.
+
+Note that firing the *same* event on the *same* entity twice in a row calls the callback only once, because the
+underlying `last_event` value does not change.
+For the raw event (`type` and `id`) on every occurrence, observe `last_event` directly instead.
+
+In a Streamlit app, callbacks are not run live; instead read `widget.last_event` after `display_widget` returns on each
+rerun, the same way you read `widget.selected` (see xref:rendering.adoc[Using with Streamlit]).
+
 == Direct modification of nodes and relationships
 
 Nodes and relationships can also be modified directly by accessing the `nodes` and `relationships` fields of an

docs/antora/modules/ROOT/pages/integration/snowflake.adoc

@@ -26,12 +26,13 @@ The nodes will be colored so that nodes from the same table have the same color,
 
 == Example
 
-In this small example, we import a toy graph representing a social network from two tables in Snowflake.
+In this small example, we import a toy graph representing a social network from two tables in Snowflake, and display it
+as an interactive widget using link:{api-docs-uri}/visualization-graph/#neo4j_viz.VisualizationGraph.render_widget[`render_widget`].
 
 [source, python]
 ----
 from snowflake.snowpark import Session
-from neo4j_viz.snowflake import from_dfs
+from neo4j_viz.snowflake import from_snowflake
 
 # Configure according to your own setup
 connection_parameters = {
@@ -82,6 +83,8 @@ VG = from_snowflake(
         },
     },
 )
+
+VG.render_widget()
 ----
 
 For a full example of the `from_snowflake` importer in action, please see the link:{tutorials-docs-uri}/snowflake-example/[Visualizing Snowflake Tables tutorial].

docs/source/api-reference/widget.rst

@@ -4,3 +4,7 @@
 .. autoclass:: neo4j_viz.GraphSelection
     :members:
     :exclude-members: model_config
+
+.. autoclass:: neo4j_viz.InteractionEvent
+    :members:
+    :exclude-members: model_config