jswidget 0.1.0__tar.gz

jswidget-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Build artifacts
+dist/
+build/
+*.egg-info/
+src/*.egg-info/
+
+# Python
+__pycache__/
+*.py[cod]
+*.so
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Environment
+.venv/
+venv/

jswidget-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DannyRuijters
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

jswidget-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: jswidget
+Version: 0.1.0
+Summary: A lightweight anywidget-based IPython widget that renders arbitrary JavaScript inside Jupyter notebooks
+Project-URL: Homepage, https://github.com/DannyRuijters/JSWidget
+Project-URL: Repository, https://github.com/DannyRuijters/JSWidget
+Author: DannyRuijters
+License: BSD 3-Clause License
+        
+        Copyright (c) 2026, DannyRuijters
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its
+           contributors may be used to endorse or promote products derived from
+           this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+License-File: LICENSE
+Keywords: anywidget,ipython,javascript,jupyter,widget
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Jupyter
+Classifier: Framework :: Jupyter :: JupyterLab
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: JavaScript
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.8
+Requires-Dist: anywidget
+Requires-Dist: numpy
+Requires-Dist: traitlets
+Description-Content-Type: text/markdown
+
+# JSWidget
+
+A lightweight [anywidget](https://anywidget.dev/)-based IPython widget that renders arbitrary JavaScript (Canvas 2D, WebGL, etc.) inside Jupyter notebooks. It passes JSON data and binary buffers (mesh vertices, normals, indices) over the ipywidgets comm API, with live-update callbacks so Python can push new data without re-executing the cell.
+
+Works in **VS Code**, **JupyterLab**, and **classic Jupyter notebooks** — no extra frontend build step required.
+
+## Installation
+
+```bash
+pip install jswidget
+```
+
+Or install from source in development mode:
+
+```bash
+git clone https://github.com/DannyRuijters/JSWidget.git
+cd JSWidget
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from jswidget import JSWidget
+
+w = JSWidget(width=600, height=400)
+w.js_code = '''
+    const canvas = document.createElement("canvas");
+    canvas.width = opts.width;
+    canvas.height = opts.height;
+    el.appendChild(canvas);
+    const ctx = canvas.getContext("2d");
+    ctx.fillStyle = "#e94560";
+    ctx.font = "24px sans-serif";
+    ctx.fillText("Hello from JSWidget!", 20, 50);
+'''
+w.show()
+```
+
+## JavaScript API
+
+The JavaScript code passed to `js_code` receives the following variables:
+
+| Variable | Description |
+|---|---|
+| `el` | Container DOM element to render into |
+| `data` | JSON data dict set from Python via `w.data` |
+| `getBuffer(name)` | Returns a named binary buffer as an `ArrayBuffer` |
+| `opts` | `{width, height}` of the widget |
+| `setState(obj)` | Save state that persists across re-renders |
+| `getState()` | Retrieve previously saved state |
+| `onData(fn)` | Register a callback for live `data` updates from Python |
+| `onBuffers(fn)` | Register a callback for live buffer updates from Python |
+
+## Passing Data
+
+### JSON data
+
+```python
+w.data = {'values': [10, 40, 80], 'color': '#4ecdc4'}
+# Update later (triggers onData callbacks in JS):
+w.send_data({'values': [90, 20, 55], 'color': '#ff6b6b'})
+```
+
+### Binary buffers
+
+```python
+import numpy as np
+
+vertices = np.array([[0,0,0],[1,0,0],[0,1,0]], dtype=np.float32)
+normals  = np.array([[0,0,1],[0,0,1],[0,0,1]], dtype=np.float32)
+indices  = np.array([0, 1, 2], dtype=np.uint32)
+
+w.set_buffers(vertices=vertices, normals=normals, indices=indices)
+```
+
+Buffers are accessible in JavaScript via `getBuffer('vertices')`, etc., and return an `ArrayBuffer` that can be wrapped in a typed array (e.g. `new Float32Array(getBuffer('vertices'))`).
+
+## Demo Notebook
+
+See [JSWidget_demo.ipynb](JSWidget_demo.ipynb) for full examples including:
+
+1. **Canvas 2D drawing** — gradient backgrounds and text rendering
+2. **Bar chart with live updates** — pass data from Python via `send_data()` and re-draw with `onData()`
+3. **Interactive WebGL mesh viewer** — sphere and torus rendering with mouse-drag rotation and scroll zoom, using binary buffers for mesh data
+
+## Files
+
+| File | Description |
+|---|---|
+| `jswidget.py` | The `JSWidget` class (anywidget-based DOMWidget with ESM frontend) |
+| `JSWidget_demo.ipynb` | Demo notebook with Canvas 2D, bar chart, and WebGL examples |
+| `LICENSE` | BSD 3-Clause License |
+
+## License
+
+BSD 3-Clause — see [LICENSE](LICENSE).

jswidget-0.1.0/README.md

@@ -0,0 +1,97 @@
+# JSWidget
+
+A lightweight [anywidget](https://anywidget.dev/)-based IPython widget that renders arbitrary JavaScript (Canvas 2D, WebGL, etc.) inside Jupyter notebooks. It passes JSON data and binary buffers (mesh vertices, normals, indices) over the ipywidgets comm API, with live-update callbacks so Python can push new data without re-executing the cell.
+
+Works in **VS Code**, **JupyterLab**, and **classic Jupyter notebooks** — no extra frontend build step required.
+
+## Installation
+
+```bash
+pip install jswidget
+```
+
+Or install from source in development mode:
+
+```bash
+git clone https://github.com/DannyRuijters/JSWidget.git
+cd JSWidget
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from jswidget import JSWidget
+
+w = JSWidget(width=600, height=400)
+w.js_code = '''
+    const canvas = document.createElement("canvas");
+    canvas.width = opts.width;
+    canvas.height = opts.height;
+    el.appendChild(canvas);
+    const ctx = canvas.getContext("2d");
+    ctx.fillStyle = "#e94560";
+    ctx.font = "24px sans-serif";
+    ctx.fillText("Hello from JSWidget!", 20, 50);
+'''
+w.show()
+```
+
+## JavaScript API
+
+The JavaScript code passed to `js_code` receives the following variables:
+
+| Variable | Description |
+|---|---|
+| `el` | Container DOM element to render into |
+| `data` | JSON data dict set from Python via `w.data` |
+| `getBuffer(name)` | Returns a named binary buffer as an `ArrayBuffer` |
+| `opts` | `{width, height}` of the widget |
+| `setState(obj)` | Save state that persists across re-renders |
+| `getState()` | Retrieve previously saved state |
+| `onData(fn)` | Register a callback for live `data` updates from Python |
+| `onBuffers(fn)` | Register a callback for live buffer updates from Python |
+
+## Passing Data
+
+### JSON data
+
+```python
+w.data = {'values': [10, 40, 80], 'color': '#4ecdc4'}
+# Update later (triggers onData callbacks in JS):
+w.send_data({'values': [90, 20, 55], 'color': '#ff6b6b'})
+```
+
+### Binary buffers
+
+```python
+import numpy as np
+
+vertices = np.array([[0,0,0],[1,0,0],[0,1,0]], dtype=np.float32)
+normals  = np.array([[0,0,1],[0,0,1],[0,0,1]], dtype=np.float32)
+indices  = np.array([0, 1, 2], dtype=np.uint32)
+
+w.set_buffers(vertices=vertices, normals=normals, indices=indices)
+```
+
+Buffers are accessible in JavaScript via `getBuffer('vertices')`, etc., and return an `ArrayBuffer` that can be wrapped in a typed array (e.g. `new Float32Array(getBuffer('vertices'))`).
+
+## Demo Notebook
+
+See [JSWidget_demo.ipynb](JSWidget_demo.ipynb) for full examples including:
+
+1. **Canvas 2D drawing** — gradient backgrounds and text rendering
+2. **Bar chart with live updates** — pass data from Python via `send_data()` and re-draw with `onData()`
+3. **Interactive WebGL mesh viewer** — sphere and torus rendering with mouse-drag rotation and scroll zoom, using binary buffers for mesh data
+
+## Files
+
+| File | Description |
+|---|---|
+| `jswidget.py` | The `JSWidget` class (anywidget-based DOMWidget with ESM frontend) |
+| `JSWidget_demo.ipynb` | Demo notebook with Canvas 2D, bar chart, and WebGL examples |
+| `LICENSE` | BSD 3-Clause License |
+
+## License
+
+BSD 3-Clause — see [LICENSE](LICENSE).

jswidget-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "jswidget"
+version = "0.1.0"
+description = "A lightweight anywidget-based IPython widget that renders arbitrary JavaScript inside Jupyter notebooks"
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.8"
+authors = [
+    {name = "DannyRuijters"},
+]
+keywords = ["jupyter", "widget", "javascript", "anywidget", "ipython"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: Jupyter",
+    "Framework :: Jupyter :: JupyterLab",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: JavaScript",
+    "Topic :: Multimedia :: Graphics",
+]
+dependencies = [
+    "anywidget",
+    "numpy",
+    "traitlets",
+]
+
+[project.urls]
+Homepage = "https://github.com/DannyRuijters/JSWidget"
+Repository = "https://github.com/DannyRuijters/JSWidget"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jswidget"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/jswidget/",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]

jswidget-0.1.0/src/jswidget/__init__.py

@@ -0,0 +1,21 @@
+"""
+JSWidget - A lightweight anywidget-based IPython widget that renders
+arbitrary JavaScript inside Jupyter notebooks.
+
+Usage:
+    from jswidget import JSWidget
+
+    w = JSWidget(width=800, height=600)
+    w.js_code = '''
+        const canvas = document.createElement("canvas");
+        canvas.width = opts.width;
+        canvas.height = opts.height;
+        el.appendChild(canvas);
+    '''
+    w.show()
+"""
+
+from jswidget.jswidget import JSWidget
+
+__all__ = ["JSWidget"]
+__version__ = "0.1.0"

jswidget-0.1.0/src/jswidget/jswidget.py

@@ -0,0 +1,233 @@
+"""
+Custom DOMWidget that renders arbitrary JavaScript and passes data
+(including user-defined binary buffers) over the ipywidgets comm API.
+
+Uses anywidget for reliable rendering in VS Code, JupyterLab, and classic notebooks.
+No external dependencies beyond anywidget and numpy.
+
+Usage:
+    from jswidget import JSWidget
+    import numpy as np
+
+    w = JSWidget(width=800, height=600)
+
+    # Set binary buffers (any name, created dynamically)
+    vertices = np.array([[0,0,0],[1,0,0],[0,1,0]], dtype=np.float32)
+    indices = np.array([0,1,2], dtype=np.uint32)
+    w.set_buffers(vertices=vertices, normals=normals, indices=indices)
+
+    # Set JSON data
+    w.data = {'opacity': 0.8, 'color': [1, 0, 0]}
+
+    # Set JavaScript code and display
+    w.js_code = '''
+        const canvas = document.createElement('canvas');
+        canvas.width = opts.width;
+        canvas.height = opts.height;
+        el.appendChild(canvas);
+        const ctx = canvas.getContext('2d');
+
+        // Access binary buffers
+        const verts = new Float32Array(getBuffer('vertices'));
+
+        // Access JSON data
+        const opacity = data.opacity;
+
+        // Register for live updates from Python
+        onData((newData) => { ... });
+        onBuffers((newMeta) => { ... });
+
+        // Save state to survive re-renders
+        setState({rotX: 0.3, rotY: 0.5});
+    '''
+    w.show()
+"""
+
+import numpy as np
+import traitlets
+import anywidget
+
+# The ESM frontend module - provides the same JS API as jswidget.py
+_ESM = """
+function render({ model, el }) {
+    // Create container
+    const container = document.createElement('div');
+    container.style.width = model.get('width') + 'px';
+    container.style.height = model.get('height') + 'px';
+    container.style.overflow = 'hidden';
+    container.style.position = 'relative';
+    el.appendChild(container);
+
+    let cleanupFn = null;
+    const _id = Math.random().toString(36).slice(2, 14);
+
+    function executeCode() {
+        const code = model.get('js_code');
+        if (!code) return;
+
+        // Cleanup previous execution
+        if (cleanupFn) {
+            try { cleanupFn(); } catch(e) {}
+            cleanupFn = null;
+        }
+        container.innerHTML = '';
+
+        // State management
+        window.__jsw_state = window.__jsw_state || {};
+        function setState(obj) { window.__jsw_state[_id] = Object.assign(window.__jsw_state[_id] || {}, obj); }
+        function getState() { return window.__jsw_state[_id] || {}; }
+
+        // opts
+        const opts = { width: model.get('width'), height: model.get('height') };
+
+        // data
+        let currentData = model.get('data') || {};
+
+        // getBuffer
+        function getBuffer(name) {
+            const raw = model.get('_buf_' + name);
+            if (!raw) return null;
+            if (raw instanceof DataView) {
+                if (raw.byteLength === 0) return null;
+                return raw.buffer.slice(raw.byteOffset, raw.byteOffset + raw.byteLength);
+            }
+            if (raw instanceof ArrayBuffer) {
+                return raw.byteLength === 0 ? null : raw;
+            }
+            if (raw.buffer instanceof ArrayBuffer) {
+                if (raw.byteLength === 0) return null;
+                return raw.buffer.slice(raw.byteOffset, raw.byteOffset + raw.byteLength);
+            }
+            return null;
+        }
+
+        // Callback registries
+        const _dataCallbacks = [];
+        const _bufferCallbacks = [];
+        function onData(fn) { _dataCallbacks.push(fn); }
+        function onBuffers(fn) { _bufferCallbacks.push(fn); }
+
+        // Wire up model change events to callbacks
+        function _onDataChange() {
+            currentData = model.get('data') || {};
+            _dataCallbacks.forEach(fn => fn(currentData));
+        }
+        function _onBuffersChange() {
+            const meta = model.get('_buffers_metadata') || [];
+            _bufferCallbacks.forEach(fn => fn(meta));
+        }
+        model.on('change:data', _onDataChange);
+        model.on('change:_buffers_metadata', _onBuffersChange);
+
+        // Register cleanup to remove listeners
+        cleanupFn = () => {
+            model.off('change:data', _onDataChange);
+            model.off('change:_buffers_metadata', _onBuffersChange);
+        };
+
+        try {
+            const fn = new Function('el', 'data', 'getBuffer', 'opts', 'setState', 'getState', 'onData', 'onBuffers', code);
+            fn(container, currentData, getBuffer, opts, setState, getState, onData, onBuffers);
+        } catch(e) {
+            const errDiv = document.createElement('pre');
+            errDiv.style.color = 'red';
+            errDiv.style.padding = '10px';
+            errDiv.textContent = 'JS Error: ' + e.message + '\\n' + e.stack;
+            container.appendChild(errDiv);
+            console.error('JSWidget execution error:', e);
+        }
+    }
+
+    // Execute initial code
+    executeCode();
+
+    // Re-execute when js_code changes
+    model.on('change:js_code', executeCode);
+
+    // Update container size
+    model.on('change:width', () => {
+        container.style.width = model.get('width') + 'px';
+    });
+    model.on('change:height', () => {
+        container.style.height = model.get('height') + 'px';
+    });
+
+    return () => {
+        if (cleanupFn) {
+            try { cleanupFn(); } catch(e) {}
+        }
+    };
+}
+export default { render };
+"""
+
+
+class JSWidget(anywidget.AnyWidget):
+    """A DOMWidget that renders arbitrary JavaScript with binary data.
+    Uses anywidget for reliable comm-based rendering in all environments.
+
+    The JavaScript code receives:
+        el            - the container DOM element
+        data          - the JSON data dict
+        getBuffer(n)  - get named buffer as ArrayBuffer
+        opts          - {width, height}
+        setState(obj) - save state that persists across re-renders
+        getState()    - retrieve previously saved state
+        onData(fn)    - register callback for data updates
+        onBuffers(fn) - register callback for buffer updates
+    """
+
+    _esm = _ESM
+
+    # User-provided JavaScript code to execute in the widget
+    js_code = traitlets.Unicode('').tag(sync=True)
+
+    # JSON-serializable data dict passed to JavaScript
+    data = traitlets.Dict({}).tag(sync=True)
+
+    # Widget dimensions
+    width = traitlets.Int(800).tag(sync=True)
+    height = traitlets.Int(600).tag(sync=True)
+
+    # Metadata about binary buffers (triggers onBuffers callback in JS)
+    # Binary buffer traits (_buf_<name>) are created dynamically by set_buffers().
+    _buffers_metadata = traitlets.List([]).tag(sync=True)
+
+    def set_buffers(self, **named_buffers):
+        """Set binary data buffers for the JavaScript frontend.
+
+        Each keyword argument should be a numpy array, bytes, or bytearray.
+
+        Example:
+            w.set_buffers(vertices=vertices, normals=normals, indices=indices)
+        """
+        metadata = []
+        with self.hold_sync():
+            for name, buf in named_buffers.items():
+                trait_name = f'_buf_{name}'
+                if not self.has_trait(trait_name):
+                    self.add_traits(**{trait_name: traitlets.Bytes(b'').tag(sync=True)})
+
+                if isinstance(buf, np.ndarray):
+                    metadata.append({'name': name, 'dtype': str(buf.dtype), 'shape': list(buf.shape)})
+                    setattr(self, trait_name, buf.tobytes())
+                elif isinstance(buf, (bytes, bytearray, memoryview)):
+                    metadata.append({'name': name, 'dtype': 'bytes', 'shape': [len(buf)]})
+                    setattr(self, trait_name, bytes(buf))
+                else:
+                    raise TypeError(f"Buffer '{name}' must be numpy array, bytes, or bytearray")
+
+            self._buffers_metadata = metadata
+
+    def send_data(self, data_dict):
+        """Update the data dict and push to JavaScript."""
+        self.data = data_dict
+
+    def execute(self, js_code):
+        """Update the JavaScript code and re-render."""
+        self.js_code = js_code
+
+    def show(self):
+        """Display the widget."""
+        from IPython.display import display
+        display(self)