plotjs 0.0.7__tar.gz → 0.0.9__tar.gz

{plotjs-0.0.7 → plotjs-0.0.9}/.github/workflows/tests-python.yaml

@@ -28,3 +28,5 @@ jobs:
 
       - name: Run unit tests (excluding browser tests)
         run: uv run pytest tests/test-python/ -v
+        env:
+          MPLBACKEND: Agg

plotjs-0.0.7/AGENTS.md → plotjs-0.0.9/AGENT.md

@@ -12,17 +12,23 @@ PlotJS is a Python package that transforms static matplotlib charts into interac
 Matplotlib Figure → SVG Export (Python) → HTML Template (Jinja2) → Interactive Browser
 ```
 
-### Workflow:
-
 1. **Python (PlotJS class):** Captures matplotlib figure as SVG string, collects tooltip/styling metadata
 2. **Jinja2 Template:** Injects SVG + CSS + JavaScript parser + configuration into HTML
 3. **Browser (PlotSVGParser):** Parses SVG structure to identify plot elements, attaches hover interactivity
 
+## How to run command
+
+Always use `uv` and/or `just` for running commands:
+
+- `uv run pytest tests/test-python`
+- `uv run pytest tests/test-python`
+- `uv run python -c "import matplotlib"`
+
 ## Key Components
 
 ### Python Module (`/plotjs/`)
 
-**`main.py`** - Core `PlotJS` class with method chaining
+**`plotjs.py`** - Core `PlotJS` class with method chaining
 
 - `__init__(fig, **savefig_kws)` - Converts matplotlib figure to SVG
 - `add_tooltip(labels, groups, hover_nearest, ax)` - Configure hover tooltips
@@ -125,17 +131,17 @@ Optional `seed` parameter ensures deterministic UUID generation for consistent o
 ```
 plotjs/
 ├── __init__.py              # Package exports
-├── main.py                  # Core PlotJS class (330 lines)
-├── css.py                   # CSS utilities (100 lines)
-├── javascript.py            # JavaScript utilities (23 lines)
-├── utils.py                 # Internal helpers (43 lines)
+├── plotjs.py                  # Core PlotJS class
+├── css.py                   # CSS utilities
+├── javascript.py            # JavaScript utilities
+├── utils.py                 # Internal helpers
 ├── data/
 │   ├── datasets.py          # Sample datasets with Narwhals
 │   └── *.csv                # Data files
 └── static/
-    ├── template.html        # Jinja2 HTML template (104 lines)
-    ├── plotparser.js        # SVG parser class (229 lines)
-    └── default.css          # Default styles (41 lines)
+    ├── template.html        # Jinja2 HTML template
+    ├── plotparser.js        # SVG parser class
+    └── default.css          # Default styles
 
 tests/
 ├── test-python/             # Python unit tests

{plotjs-0.0.7 → plotjs-0.0.9}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Joseph Barbier
+Copyright (c) 2026 Joseph Barbier
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{plotjs-0.0.7 → plotjs-0.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plotjs
-Version: 0.0.7
+Version: 0.0.9
 Summary: Turn static matplotlib charts into interactive web visualizations
 Author-email: Joseph Barbier <joseph.barbierdarnal@mail.com>
 License-Expression: MIT
@@ -20,8 +20,6 @@ Requires-Dist: matplotlib>=3.10.0
 Requires-Dist: narwhals>=2.0.0
 Dynamic: license-file
 
-![](./coverage-badge.svg)
-
 # `plotjs`: Turn static matplotlib charts into interactive web visualizations
 
 <img src="https://github.com/JosephBARBIERDARNAL/static/blob/main/python-libs/plotjs/image.png?raw=true" alt="plotjs logo" align="right" width="150px"/>

{plotjs-0.0.7 → plotjs-0.0.9}/README.md

@@ -1,5 +1,3 @@
-![](./coverage-badge.svg)
-
 # `plotjs`: Turn static matplotlib charts into interactive web visualizations
 
 <img src="https://github.com/JosephBARBIERDARNAL/static/blob/main/python-libs/plotjs/image.png?raw=true" alt="plotjs logo" align="right" width="150px"/>

plotjs-0.0.9/docs/developers/svg-parser-reference.md

@@ -0,0 +1,164 @@
+## Classes
+
+<dl>
+<dt><a href="#Selection">Selection</a></dt>
+<dd><p>Lightweight Selection wrapper that mimics d3-selection&#39;s chainable API.
+Provides basic DOM manipulation methods for working with SVG elements.</p>
+</dd>
+</dl>
+
+## Functions
+
+<dl>
+<dt><a href="#select">select(selector)</a> ⇒ <code><a href="#Selection">Selection</a></code></dt>
+<dd><p>Create a Selection from a DOM element or selector string.</p>
+</dd>
+<dt><a href="#getPointerPosition">getPointerPosition(event, svgElement)</a> ⇒ <code>Array.&lt;number&gt;</code></dt>
+<dd><p>Get mouse position relative to an SVG element.</p>
+</dd>
+<dt><a href="#findBars">findBars(svg, axes_class)</a> ⇒ <code><a href="#Selection">Selection</a></code></dt>
+<dd><p>Find bar elements (<code>patch</code> groups with clipping) inside a given axes.</p>
+</dd>
+<dt><a href="#findPoints">findPoints(svg, axes_class, tooltip_groups)</a> ⇒ <code><a href="#Selection">Selection</a></code></dt>
+<dd><p>Find scatter plot points inside a given axes.
+Handles both <code>&lt;use&gt;</code> and <code>&lt;path&gt;</code> fallback cases,
+and assigns <code>data-group</code> attributes based on tooltip groups.</p>
+</dd>
+<dt><a href="#findLines">findLines(svg, axes_class)</a> ⇒ <code><a href="#Selection">Selection</a></code></dt>
+<dd><p>Find line elements (<code>line2d</code> paths) inside a given axes,
+excluding axis grid lines.</p>
+</dd>
+<dt><a href="#findAreas">findAreas(svg, axes_class)</a> ⇒ <code><a href="#Selection">Selection</a></code></dt>
+<dd><p>Find filled area elements (<code>FillBetweenPolyCollection</code> paths) inside a given axes.</p>
+</dd>
+<dt><a href="#nearestElementFromMouse">nearestElementFromMouse(mouseX, mouseY, elements)</a> ⇒ <code>Element</code> | <code>null</code></dt>
+<dd><p>Compute the nearest element to the mouse cursor from a set of elements.
+Uses bounding box centers for distance.
+This function is used when the <code>hover_nearest</code> argument is true.</p>
+</dd>
+<dt><a href="#setHoverEffect">setHoverEffect(plot_element, axes_class, tooltip_labels, tooltip_groups, show_tooltip, hover_nearest)</a></dt>
+<dd><p>Attach hover interaction and tooltip display to plot elements.
+Can highlight nearest element (if enabled) or hovered element directly.</p>
+</dd>
+</dl>
+
+<a name="Selection"></a>
+
+## Selection
+Lightweight Selection wrapper that mimics d3-selection's chainable API.
+Provides basic DOM manipulation methods for working with SVG elements.
+
+**Kind**: global class
+<a name="select"></a>
+
+## select(selector) ⇒ [<code>Selection</code>](#Selection)
+Create a Selection from a DOM element or selector string.
+
+**Kind**: global function
+**Returns**: [<code>Selection</code>](#Selection) - New Selection instance
+
+| Param | Type | Description |
+| --- | --- | --- |
+| selector | <code>string</code> \| <code>Element</code> | CSS selector string or DOM element |
+
+<a name="getPointerPosition"></a>
+
+## getPointerPosition(event, svgElement) ⇒ <code>Array.&lt;number&gt;</code>
+Get mouse position relative to an SVG element.
+
+**Kind**: global function
+**Returns**: <code>Array.&lt;number&gt;</code> - [x, y] coordinates relative to the SVG
+
+| Param | Type | Description |
+| --- | --- | --- |
+| event | <code>MouseEvent</code> | The mouse event |
+| svgElement | <code>Element</code> \| [<code>Selection</code>](#Selection) | The SVG element or Selection |
+
+<a name="findBars"></a>
+
+## findBars(svg, axes_class) ⇒ [<code>Selection</code>](#Selection)
+Find bar elements (`patch` groups with clipping) inside a given axes.
+
+**Kind**: global function
+**Returns**: [<code>Selection</code>](#Selection) - Selection of bar elements.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| svg | [<code>Selection</code>](#Selection) | Selection of the SVG element. |
+| axes_class | <code>string</code> | ID of the axes group (e.g. "axes_1"). |
+
+<a name="findPoints"></a>
+
+## findPoints(svg, axes_class, tooltip_groups) ⇒ [<code>Selection</code>](#Selection)
+Find scatter plot points inside a given axes.
+Handles both `<use>` and `<path>` fallback cases,
+and assigns `data-group` attributes based on tooltip groups.
+
+**Kind**: global function
+**Returns**: [<code>Selection</code>](#Selection) - Selection of point elements.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| svg | [<code>Selection</code>](#Selection) | Selection of the SVG element. |
+| axes_class | <code>string</code> | ID of the axes group (e.g. "axes_1"). |
+| tooltip_groups | <code>Array.&lt;string&gt;</code> | Group identifiers for tooltips, parallel to points. |
+
+<a name="findLines"></a>
+
+## findLines(svg, axes_class) ⇒ [<code>Selection</code>](#Selection)
+Find line elements (`line2d` paths) inside a given axes,
+excluding axis grid lines.
+
+**Kind**: global function
+**Returns**: [<code>Selection</code>](#Selection) - Selection of line elements.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| svg | [<code>Selection</code>](#Selection) | Selection of the SVG element. |
+| axes_class | <code>string</code> | ID of the axes group. |
+
+<a name="findAreas"></a>
+
+## findAreas(svg, axes_class) ⇒ [<code>Selection</code>](#Selection)
+Find filled area elements (`FillBetweenPolyCollection` paths) inside a given axes.
+
+**Kind**: global function
+**Returns**: [<code>Selection</code>](#Selection) - Selection of area elements.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| svg | [<code>Selection</code>](#Selection) | Selection of the SVG element. |
+| axes_class | <code>string</code> | ID of the axes group. |
+
+<a name="nearestElementFromMouse"></a>
+
+## nearestElementFromMouse(mouseX, mouseY, elements) ⇒ <code>Element</code> \| <code>null</code>
+Compute the nearest element to the mouse cursor from a set of elements.
+Uses bounding box centers for distance.
+This function is used when the `hover_nearest` argument is true.
+
+**Kind**: global function
+**Returns**: <code>Element</code> \| <code>null</code> - The nearest DOM element or `null`.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| mouseX | <code>number</code> | X coordinate of the mouse relative to SVG. |
+| mouseY | <code>number</code> | Y coordinate of the mouse relative to SVG. |
+| elements | [<code>Selection</code>](#Selection) | Selection of candidate elements. |
+
+<a name="setHoverEffect"></a>
+
+## setHoverEffect(plot_element, axes_class, tooltip_labels, tooltip_groups, show_tooltip, hover_nearest)
+Attach hover interaction and tooltip display to plot elements.
+Can highlight nearest element (if enabled) or hovered element directly.
+
+**Kind**: global function
+
+| Param | Type | Description |
+| --- | --- | --- |
+| plot_element | [<code>Selection</code>](#Selection) | Selection of plot elements (points, lines, etc.). |
+| axes_class | <code>string</code> | ID of the axes group. |
+| tooltip_labels | <code>Array.&lt;string&gt;</code> | Tooltip labels for each element. |
+| tooltip_groups | <code>Array.&lt;string&gt;</code> | Group identifiers for each element. |
+| show_tooltip | <code>&quot;block&quot;</code> \| <code>&quot;none&quot;</code> | Whether to display tooltips. |
+| hover_nearest | <code>boolean</code> | If true, highlight nearest element instead of hovered one. |

{plotjs-0.0.7 → plotjs-0.0.9}/docs/guides/css/index.md

@@ -36,7 +36,7 @@ You can directly apply a CSS string to your plot:
 
 ## Using a Python dictionary
 
-For better readability and reusability, you can define CSS as a dictionary using `plotjs.css.from_dict()`:
+For better readability and reusability, you can define CSS as a dictionary:
 
 ```python
 from plotjs import css
@@ -44,12 +44,12 @@ from plotjs import css
 (
     PlotJS()
     .add_tooltip(labels=df["tooltip"])
-    .add_css(css.from_dict({
+    .add_css(from_dict = {
         ".tooltip": {
             "background": "red",
             "color": "blue"
         }
-    }))
+    })
 )
 ```
 
@@ -59,8 +59,8 @@ Method chaining also works if you want to split styles:
 (
     PlotJS()
     .add_tooltip(labels=df["tooltip"])
-    .add_css(css.from_dict({".tooltip": {"color": "blue"}}))
-    .add_css(css.from_dict({".tooltip": {"background": "red"}}))
+    .add_css(from_dict = {".tooltip": {"color": "blue"}})
+    .add_css(from_dict = {".tooltip": {"background": "red"}})
 )
 ```
 
@@ -83,7 +83,7 @@ from plotjs import css
 (
     PlotJS()
     .add_tooltip(labels=df["tooltip"])
-    .add_css(css.from_file("docs/static/style.css"))
+    .add_css(from_file = "docs/static/style.css")
 )
 ```
 
@@ -114,7 +114,7 @@ You can combine with `.hovered` or `.not-hovered`, e.g., `.point.hovered`.
 
 ## Default CSS
 
-You can find the default CSS applied by plotjs [here](https://github.com/y-sunflower/plotjs/blob/main/plotjs/static/default.css)
+You can find the default CSS applied by plotjs [here](https://github.com/y-sunflower/plotjs/blob/main/plotjs/static/default.css).
 
 ## Appendix
 

{plotjs-0.0.7 → plotjs-0.0.9}/docs/guides/javascript/index.md

@@ -23,6 +23,7 @@ ax.scatter(
 (
     PlotJS(fig=fig)
     .add_tooltip(labels=df["species"])
+    .add_d3js()  # import D3.js library
     .add_javascript(
         """
 d3.selectAll(".point").on("click", () =>
@@ -39,32 +40,34 @@ Relevant code here is:
 
 ```js
 d3.selectAll(".point").on("click", () =>
-  alert("I wish cookies were 0 calories...")
+  alert("I wish cookies were 0 calories..."),
 );
 ```
 
-Here’s what it does:
+Here's what it does:
 
 - selects all points (e.g., from the scatter plot)
 - sets that when clicking one of the points
 - it displays a message
 
+???+ info
+
+    We need to call the `add_d3js()` method in order to use the `d3` object here. This method just import D3.js and let us use D3.js functions.
+
 ## Loading JavaScript from file
 
-`plotjs` requires the JavaScript to be in a string, but it's far from being a comfortable way of coding. So there is a convenient function to load JavaScript from a file:
+`plotjs` requires the JavaScript to be in a string, but it's far from being a comfortable way of coding. So there is a convenient argument to load JavaScript from a file:
 
 ```python
-from plotjs import javascript
-
-PlotJS(fig=fig).add_javascript(
-    javascript.from_file("my_script.js"),
-)
+PlotJS(fig=fig).add_javascript(from_file="my_script.js")
 ```
 
 This allows you to write JavaScript in a separate file so that you can have a code formatter (prettier, etc.), code completion, syntax highlighting, and so on. This is what is recommended to do if you're writing a significant amount of code.
 
 ## Advanced usage
 
+With JavaScript, we can do pretty much anything we want, so be creative! Here, we can force the dots to remain highlighted once we click on them:
+
 ```python
 import matplotlib.pyplot as plt
 from plotjs import PlotJS, data
@@ -84,7 +87,7 @@ for specie in df["species"].unique():
     )
 ax.legend()
 
-custom_js: str = """
+custom_js = """
 document.querySelectorAll('.point').forEach(el => {
 el.addEventListener('click', function() {
     const group = this.getAttribute('data-group');
@@ -108,7 +111,7 @@ el.addEventListener('click', function() {
 });
 """
 
-custom_css: str = """
+custom_css = """
 .point.dimmed {
     opacity: 0.2;
 }
@@ -119,10 +122,7 @@ custom_css: str = """
 
 (
     PlotJS(fig=fig)
-    .add_tooltip(
-        labels=df["species"],
-        groups=df["species"],
-    )
+    .add_tooltip(labels=df["species"], groups=df["species"])
     .add_css(custom_css)
     .add_javascript(custom_js)
 )

{plotjs-0.0.7 → plotjs-0.0.9}/docs/guides/javascript/javascript.py

@@ -16,6 +16,7 @@ ax.scatter(
 (
     PlotJS(fig=fig)
     .add_tooltip(labels=df["species"])
+    .add_d3js()  # import D3.js library
     .add_javascript(
         """
 d3.selectAll(".point").on("click", () =>