plotjs 0.0.3__tar.gz → 0.0.5__tar.gz

{plotjs-0.0.3 → plotjs-0.0.5}/.github/workflows/lint.yaml

@@ -2,8 +2,9 @@ name: Check Code Formatting
 
 on:
   pull_request:
-    branches:
-      - main
+    branches: [main]
+  push:
+    branches: [main]
 
 jobs:
   check-formatting:

plotjs-0.0.5/.github/workflows/tests-js.yaml

@@ -0,0 +1,18 @@
+name: Tests JavaScript
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install
+      - run: npm test

plotjs-0.0.3/.github/workflows/tests.yaml → plotjs-0.0.5/.github/workflows/tests-python.yaml

@@ -1,8 +1,10 @@
-name: Unit tests
+name: Tests Python
 
 on:
   pull_request:
     branches: [main]
+  push:
+    branches: [main]
 
 jobs:
   build:

{plotjs-0.0.3 → plotjs-0.0.5}/.github/workflows/type.yaml

@@ -2,8 +2,9 @@ name: Check Static Typing
 
 on:
   pull_request:
-    branches:
-      - main
+    branches: [main]
+  push:
+    branches: [main]
 
 jobs:
   check-formatting:

{plotjs-0.0.3 → plotjs-0.0.5}/.gitignore

@@ -32,3 +32,5 @@ sandbox/
 scripts/release.sh
 
 /.quarto/
+
+node_modules

{plotjs-0.0.3 → plotjs-0.0.5}/.pre-commit-config.yaml

@@ -13,7 +13,6 @@ repos:
       - id: check-yaml
       - id: trailing-whitespace
       - id: end-of-file-fixer
-      - id: check-added-large-files
   - repo: https://github.com/python-jsonschema/check-jsonschema
     rev: 0.28.2
     hooks:

{plotjs-0.0.3 → plotjs-0.0.5}/Makefile

@@ -1,4 +1,4 @@
-.PHONY: all examples coverage
+.PHONY: all examples gallery
 
 examples:
 	quarto render docs/index.qmd
@@ -16,5 +16,12 @@ coverage:
 	uv run genbadge coverage -i coverage.xml
 	rm coverage.xml
 
+preview:
+	uv run mkdocs serve
+
+jsdoc:
+	npm run docs:js
+
 test:
-	uv run pytest
+	uv run pytest    # run python tests
+	npm test         # run javascript tests

{plotjs-0.0.3/plotjs.egg-info → plotjs-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plotjs
-Version: 0.0.3
+Version: 0.0.5
 Summary: Turn static matplotlib charts into interactive web visualizations
 Author-email: Joseph Barbier <joseph.barbierdarnal@mail.com>
 License-Expression: MIT
@@ -41,7 +41,7 @@ Dynamic: license-file
 
 ## Installation
 
-From PyPI:
+From PyPI (recommended):
 
 ```
 pip install plotjs

{plotjs-0.0.3 → plotjs-0.0.5}/README.md

@@ -19,7 +19,7 @@
 
 ## Installation
 
-From PyPI:
+From PyPI (recommended):
 
 ```
 pip install plotjs

{plotjs-0.0.3 → plotjs-0.0.5}/coverage-badge.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 92.19%"><title>coverage: 92.19%</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#4c1"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="315" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="510">coverage</text><text x="315" y="140" transform="scale(.1)" fill="#fff" textLength="510">coverage</text><text aria-hidden="true" x="865" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="430">92.19%</text><text x="865" y="140" transform="scale(.1)" fill="#fff" textLength="430">92.19%</text></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 93.92%"><title>coverage: 93.92%</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#4c1"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="315" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="510">coverage</text><text x="315" y="140" transform="scale(.1)" fill="#fff" textLength="510">coverage</text><text aria-hidden="true" x="865" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="430">93.92%</text><text x="865" y="140" transform="scale(.1)" fill="#fff" textLength="430">93.92%</text></g></svg>

{plotjs-0.0.3 → plotjs-0.0.5}/docs/developers/contributing.md

@@ -2,16 +2,22 @@
 
 The best way to help the development is to:
 
-- list the bugs you found by opening [GitHub issues](https://github.com/y-sunflower/plotjs/issues){target="_blank"}
-- list the features you'd like to see by opening [GitHub issues](https://github.com/y-sunflower/plotjs/issues){target="_blank"}
+- list the bugs you found by opening [GitHub issues](https://github.com/y-sunflower/plotjs/issues){target="\_blank"}
+- list the features you'd like to see by opening [GitHub issues](https://github.com/y-sunflower/plotjs/issues){target="\_blank"}
 
 ## Setting up your environment
 
+You need to have the following installed on your machine:
+
+- [uv](https://docs.astral.sh/uv/getting-started/installation/)
+- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+- [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
+
 ### Install for development
 
 - Fork the repository to your own GitHub account.
 
-- Clone your forked repository to your local machine (ensure you have [Git installed](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)):
+- Clone your forked repository to your local machine:
 
 ```bash
 git clone https://github.com/github_user_name/plotjs.git
@@ -25,7 +31,7 @@ git remote add upstream https://github.com/y-sunflower/plotjs.git
 git checkout -b my-feature
 ```
 
-- Set up your Python environment (ensure you have [uv installed](https://docs.astral.sh/uv/getting-started/installation/)):
+- Set up your Python environment:
 
 ```bash
 uv sync --all-groups --dev
@@ -33,6 +39,12 @@ uv run pre-commit install
 uv pip install -e .
 ```
 
+- Install npm dependencies:
+
+```bash
+npm install
+```
+
 ## Code
 
 You can now make changes to the package and start coding!
@@ -42,13 +54,13 @@ You can now make changes to the package and start coding!
 - Test that everything works correctly by running:
 
 ```bash
-uv run pytest
+make test
 ```
 
 ### Preview documentation locally
 
 ```bash
-uv run mkdocs serve
+make preview
 ```
 
 ## Push changes

plotjs-0.0.5/docs/developers/overview.md

@@ -0,0 +1,27 @@
+The core idea behind `plotjs` is that since you can natively save a matplotlib plot as [SVG](https://developer.mozilla.org/en-US/docs/Web/SVG), it's possible to manipulate that SVG from the browser.
+
+![](../img/overview.png)
+
+In practice, the saved HTML file from `plotjs` is just:
+
+- the SVG output from matplotlib
+- some CSS styling (default and from user)
+- a parser for the SVG (in javascript) and javascript from user
+
+## Core issues
+
+There are 2 things important things to solve at this point:
+
+- communicate info from Python to JavaScript
+- parse the SVG with JavaScript
+
+The first point is important because the SVG file is not enough for us to parse it correctly. We need some info from the original matplotlib `Figure`. This is mainly solved using [`jinja2`](https://jinja.palletsprojects.com/en/stable/), often used in web development. This allows us to pass variables from Python to an HTML template (e.g., simple HTML file with placeholders that we'll fill). The core things we want to pass are:
+
+- the SVG of the plot
+- the JavaScript parser (kept in its own js file)
+- additional CSS/JS from the user
+- a dictionnary with custom info (named `plot_data_json` in the codebase)
+
+`plot_data_json` is passed directly to JavaScript and is then parsed with `JSON.parse()`. This works because Python dictionnaries can be (assuming a few rules that we respect here) valid JSON and be considered as such.
+
+Then we "just" have to parse the SVG and apply the effects the user want: hover, onclick effects, etc. You can learn more about how the SVG is parsed [here](./parsing-matplotlib-svg.md).

plotjs-0.0.3/docs/developers/how-it-works.md → plotjs-0.0.5/docs/developers/parsing-matplotlib-svg.md

@@ -21,7 +21,7 @@ But it means we don't have full control over how the plot is structured (from th
 For the moment, we just take the user's matplotlib figure and save it as SVG. This is just:
 
 ```python
-fig.savefig("plot.svg")
+plt.savefig("plot.svg")
 ```
 
 Now, let's say the figure contains a scatter plot and we want to add a tooltip: when someone hovers their mouse over a point, it displays a label.
@@ -156,3 +156,7 @@ The idea is basically:
 This gives us a `lines` variable that only contains the lines of interest!
 
 The logic is the same for other plot elements: bars, points, polygons, etc.
+
+<br>
+
+You can find the **reference page** of the parser [here](./svg-parser-reference.md)

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

@@ -0,0 +1,117 @@
+## Functions
+
+<dl>
+<dt><a href="#findBars">findBars(svg, axes_class)</a> ⇒ <code>d3.Selection</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>d3.Selection</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>d3.Selection</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>d3.Selection</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="findBars"></a>
+
+## findBars(svg, axes_class) ⇒ <code>d3.Selection</code>
+Find bar elements (`patch` groups with clipping) inside a given axes.
+
+**Kind**: global function
+**Returns**: <code>d3.Selection</code> - D3 selection of bar elements.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| svg | <code>d3.Selection</code> | D3 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>d3.Selection</code>
+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>d3.Selection</code> - D3 selection of point elements.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| svg | <code>d3.Selection</code> | D3 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>d3.Selection</code>
+Find line elements (`line2d` paths) inside a given axes,
+excluding axis grid lines.
+
+**Kind**: global function
+**Returns**: <code>d3.Selection</code> - D3 selection of line elements.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| svg | <code>d3.Selection</code> | D3 selection of the SVG element. |
+| axes_class | <code>string</code> | ID of the axes group. |
+
+<a name="findAreas"></a>
+
+## findAreas(svg, axes_class) ⇒ <code>d3.Selection</code>
+Find filled area elements (`FillBetweenPolyCollection` paths) inside a given axes.
+
+**Kind**: global function
+**Returns**: <code>d3.Selection</code> - D3 selection of area elements.
+
+| Param | Type | Description |
+| --- | --- | --- |
+| svg | <code>d3.Selection</code> | D3 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>d3.Selection</code> | 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>d3.Selection</code> | 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.3 → plotjs-0.0.5}/docs/gallery/index.md

@@ -18,11 +18,11 @@ This page contains all the `plotjs` examples from this website.
 
 <div style="display: flex;">
 
-<iframe width="100%" height="300" src="../iframes/quickstart4.html" style="flex: 1; border: none;">
+<iframe width="100%" height="300" src="../iframes/area-natural-disasters.html" style="flex: 1; border: none;">
 
 </iframe>
 
-<iframe width="100%" height="300" src="../iframes/quickstart5.html" style="flex: 1; border: none;">
+<iframe width="100%" height="300" src="../iframes/quickstart4.html" style="flex: 1; border: none;">
 
 </iframe>
 
@@ -30,11 +30,11 @@ This page contains all the `plotjs` examples from this website.
 
 <div style="display: flex;">
 
-<iframe width="100%" height="300" src="../iframes/quickstart9.html" style="flex: 1; border: none;">
+<iframe width="100%" height="300" src="../iframes/quickstart5.html" style="flex: 1; border: none;">
 
 </iframe>
 
-<iframe width="100%" height="300" src="../iframes/CSS.html" style="flex: 1; border: none;">
+<iframe width="100%" height="300" src="../iframes/quickstart9.html" style="flex: 1; border: none;">
 
 </iframe>
 
@@ -42,19 +42,43 @@ This page contains all the `plotjs` examples from this website.
 
 <div style="display: flex;">
 
+<iframe width="100%" height="300" src="../iframes/CSS.html" style="flex: 1; border: none;">
+
+</iframe>
+
 <iframe width="100%" height="300" src="../iframes/quickstart2.html" style="flex: 1; border: none;">
 
 </iframe>
 
+</div>
+
+<div style="display: flex;">
+
 <iframe width="100%" height="300" src="../iframes/javascript.html" style="flex: 1; border: none;">
 
 </iframe>
 
+<iframe width="100%" height="300" src="../iframes/quickstart3.html" style="flex: 1; border: none;">
+
+</iframe>
+
 </div>
 
 <div style="display: flex;">
 
-<iframe width="100%" height="300" src="../iframes/quickstart3.html" style="flex: 1; border: none;">
+<iframe width="100%" height="300" src="../iframes/quickstart10.html" style="flex: 1; border: none;">
+
+</iframe>
+
+<iframe width="100%" height="300" src="../iframes/quickstart11.html" style="flex: 1; border: none;">
+
+</iframe>
+
+</div>
+
+<div style="display: flex;">
+
+<iframe width="100%" height="300" src="../iframes/random-walk-1.html" style="flex: 1; border: none;">
 
 </iframe>
 
@@ -66,11 +90,11 @@ This page contains all the `plotjs` examples from this website.
 
 <div style="display: flex;">
 
-<iframe width="100%" height="300" src="../iframes/CSS-2.html" style="flex: 1; border: none;">
+<iframe width="100%" height="300" src="../iframes/bug.html" style="flex: 1; border: none;">
 
 </iframe>
 
-<iframe width="100%" height="300" src="../iframes/quickstart6.html" style="flex: 1; border: none;">
+<iframe width="100%" height="300" src="../iframes/CSS-2.html" style="flex: 1; border: none;">
 
 </iframe>
 
@@ -78,6 +102,10 @@ This page contains all the `plotjs` examples from this website.
 
 <div style="display: flex;">
 
+<iframe width="100%" height="300" src="../iframes/quickstart6.html" style="flex: 1; border: none;">
+
+</iframe>
+
 <iframe width="100%" height="300" src="../iframes/quickstart7.html" style="flex: 1; border: none;">
 
 </iframe>