metaframe-widget 0.1.0__tar.gz

metaframe_widget-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+dist/
+*.egg-info/
+__pycache__/

metaframe_widget-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Metapages
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

metaframe_widget-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: metaframe-widget
+Version: 0.1.0
+Summary: anywidget for embedding metaframe URLs in Jupyter and marimo notebooks
+Project-URL: Homepage, https://github.com/metapages/metaframe-js
+Project-URL: Repository, https://github.com/metapages/metaframe-js
+Project-URL: Issues, https://github.com/metapages/metaframe-js/issues
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: Jupyter
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.8
+Requires-Dist: anywidget>=0.9.0
+Requires-Dist: traitlets>=5.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: jupyter
+Requires-Dist: jupyterlab; extra == 'jupyter'
+Provides-Extra: marimo
+Requires-Dist: marimo; extra == 'marimo'
+Description-Content-Type: text/markdown
+
+# metaframe-widget
+
+An [anywidget](https://anywidget.dev/) for embedding [metaframe](https://metapages.org/) URLs in Jupyter and marimo notebooks.
+
+## Install
+
+```bash
+pip install metaframe-widget
+```
+
+With environment extras:
+
+```bash
+pip install "metaframe-widget[jupyter]"   # includes jupyterlab
+pip install "metaframe-widget[marimo]"    # includes marimo
+```
+
+## Quick start
+
+### Jupyter
+
+```python
+from metaframe_widget import MetaframeWidget
+
+w = MetaframeWidget(url="https://js.mtfm.io/#?js=...", height="300px")
+w
+```
+
+### marimo
+
+```python
+import marimo as mo
+from metaframe_widget import MetaframeWidget
+
+w = MetaframeWidget(url="https://js.mtfm.io/#?js=...", height="300px")
+mo.ui.anywidget(w)
+```
+
+## Create from inline JavaScript
+
+```python
+w = MetaframeWidget.from_code("""
+  setOutput("result", getInput("data") * 2);
+""", height="300px")
+```
+
+## API reference
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `url` | `str` | `""` | Full metaframe URL (including hash params) |
+| `inputs` | `dict` | `{}` | Dict of inputs to push to the metaframe |
+| `outputs` | `dict` | `{}` | Dict of outputs received from the metaframe (read-only) |
+| `width` | `str` | `"100%"` | CSS width for the widget container |
+| `height` | `str` | `"400px"` | CSS height for the widget container |
+| `allow` | `str` | `""` | iframe `allow` attribute (e.g. `"camera; microphone"`) |
+
+### Methods
+
+- **`set_inputs(d)`** — merge a dict into current inputs
+- **`set_input(key, value)`** — set a single input key
+- **`on_outputs_change(callback)`** — register a callback for output changes
+- **`from_code(js_code, **kwargs)`** — class method to create a widget from inline JS
+- **`pipe_to(target, output_key, input_key=None)`** — connect an output to another widget's input
+
+## Piping widgets
+
+```python
+source = MetaframeWidget(url="...")
+sink = MetaframeWidget(url="...")
+source.pipe_to(sink, output_key="result", input_key="data")
+```
+
+## Links
+
+- [GitHub](https://github.com/metapages/metaframe-js)
+- [Jupyter examples](https://github.com/metapages/metaframe-js/tree/main/examples/jupyter)
+- [marimo examples](https://github.com/metapages/metaframe-js/tree/main/examples/marimo)

metaframe_widget-0.1.0/README.md

@@ -0,0 +1,78 @@
+# metaframe-widget
+
+An [anywidget](https://anywidget.dev/) for embedding [metaframe](https://metapages.org/) URLs in Jupyter and marimo notebooks.
+
+## Install
+
+```bash
+pip install metaframe-widget
+```
+
+With environment extras:
+
+```bash
+pip install "metaframe-widget[jupyter]"   # includes jupyterlab
+pip install "metaframe-widget[marimo]"    # includes marimo
+```
+
+## Quick start
+
+### Jupyter
+
+```python
+from metaframe_widget import MetaframeWidget
+
+w = MetaframeWidget(url="https://js.mtfm.io/#?js=...", height="300px")
+w
+```
+
+### marimo
+
+```python
+import marimo as mo
+from metaframe_widget import MetaframeWidget
+
+w = MetaframeWidget(url="https://js.mtfm.io/#?js=...", height="300px")
+mo.ui.anywidget(w)
+```
+
+## Create from inline JavaScript
+
+```python
+w = MetaframeWidget.from_code("""
+  setOutput("result", getInput("data") * 2);
+""", height="300px")
+```
+
+## API reference
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `url` | `str` | `""` | Full metaframe URL (including hash params) |
+| `inputs` | `dict` | `{}` | Dict of inputs to push to the metaframe |
+| `outputs` | `dict` | `{}` | Dict of outputs received from the metaframe (read-only) |
+| `width` | `str` | `"100%"` | CSS width for the widget container |
+| `height` | `str` | `"400px"` | CSS height for the widget container |
+| `allow` | `str` | `""` | iframe `allow` attribute (e.g. `"camera; microphone"`) |
+
+### Methods
+
+- **`set_inputs(d)`** — merge a dict into current inputs
+- **`set_input(key, value)`** — set a single input key
+- **`on_outputs_change(callback)`** — register a callback for output changes
+- **`from_code(js_code, **kwargs)`** — class method to create a widget from inline JS
+- **`pipe_to(target, output_key, input_key=None)`** — connect an output to another widget's input
+
+## Piping widgets
+
+```python
+source = MetaframeWidget(url="...")
+sink = MetaframeWidget(url="...")
+source.pipe_to(sink, output_key="result", input_key="data")
+```
+
+## Links
+
+- [GitHub](https://github.com/metapages/metaframe-js)
+- [Jupyter examples](https://github.com/metapages/metaframe-js/tree/main/examples/jupyter)
+- [marimo examples](https://github.com/metapages/metaframe-js/tree/main/examples/marimo)

metaframe_widget-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "metaframe-widget"
+version = "0.1.0"
+description = "anywidget for embedding metaframe URLs in Jupyter and marimo notebooks"
+license = "MIT"
+requires-python = ">=3.8"
+readme = "README.md"
+dependencies = [
+    "anywidget>=0.9.0",
+    "traitlets>=5.0.0",
+]
+classifiers = [
+    "Framework :: Jupyter",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+]
+
+[project.urls]
+Homepage = "https://github.com/metapages/metaframe-js"
+Repository = "https://github.com/metapages/metaframe-js"
+Issues = "https://github.com/metapages/metaframe-js/issues"
+
+[project.optional-dependencies]
+jupyter = ["jupyterlab"]
+marimo = ["marimo"]
+dev = ["pytest"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/metaframe_widget"]

metaframe_widget-0.1.0/src/metaframe_widget/__init__.py

@@ -0,0 +1,3 @@
+from ._widget import MetaframeWidget
+
+__all__ = ["MetaframeWidget"]

metaframe_widget-0.1.0/src/metaframe_widget/_esm.py

@@ -0,0 +1,111 @@
+ESM = """
+const CDN_URL = "https://cdn.jsdelivr.net/npm/@metapages/metapage@1.10.6/+esm";
+
+let _renderMetapage = null;
+
+async function loadRenderMetapage() {
+    if (!_renderMetapage) {
+        const mod = await import(CDN_URL);
+        _renderMetapage = mod.renderMetapage;
+    }
+    return _renderMetapage;
+}
+
+export default {
+    async render({ model, el }) {
+        // Size el explicitly so marimo and Jupyter honour width/height
+        el.style.display = "block";
+        el.style.boxSizing = "border-box";
+        el.style.width = model.get("width") || "100%";
+        el.style.height = model.get("height") || "400px";
+
+        // Inject CSS to remove iframe borders and inline gaps
+        const style = document.createElement("style");
+        style.textContent = ".metaframe-widget-container { box-sizing: border-box; width: 100%; height: 100%; } .metaframe-widget-container iframe { border: none; display: block; margin: 0; padding: 0; box-sizing: border-box; width: 100%; height: 100%; }";
+        el.appendChild(style);
+
+        const container = document.createElement("div");
+        container.className = "metaframe-widget-container";
+        container.style.width = "100%";
+        container.style.height = "100%";
+        el.appendChild(container);
+
+        const renderMetapage = await loadRenderMetapage();
+
+        let currentResult = null;
+
+        function applyAllowToIframes() {
+            const allow = model.get("allow") || "";
+            if (allow) {
+                container.querySelectorAll("iframe").forEach(iframe => {
+                    iframe.allow = allow;
+                });
+            }
+        }
+
+        async function createMetapage() {
+            if (currentResult) {
+                currentResult.dispose();
+                currentResult = null;
+            }
+            container.innerHTML = "";
+
+            const url = model.get("url");
+            if (!url) return;
+
+            const definition = {
+                version: "0.3",
+                metaframes: {
+                    mf: { url },
+                },
+            };
+
+            const result = await renderMetapage({
+                definition,
+                rootDiv: container,
+                onOutputs: (outputs) => {
+                    const mfOutputs = outputs.mf || {};
+                    model.set("outputs", JSON.parse(JSON.stringify(mfOutputs)));
+                    model.save_changes();
+                },
+            });
+            currentResult = result;
+
+            applyAllowToIframes();
+
+            // Push current inputs if any
+            const inputs = model.get("inputs");
+            if (inputs && Object.keys(inputs).length > 0) {
+                result.setInputs({ mf: inputs });
+            }
+        }
+
+        model.on("change:url", createMetapage);
+
+        model.on("change:inputs", () => {
+            if (currentResult) {
+                const inputs = model.get("inputs");
+                currentResult.setInputs({ mf: inputs });
+            }
+        });
+
+        model.on("change:width", () => {
+            el.style.width = model.get("width") || "100%";
+        });
+
+        model.on("change:height", () => {
+            el.style.height = model.get("height") || "400px";
+        });
+
+        model.on("change:allow", applyAllowToIframes);
+
+        await createMetapage();
+
+        return () => {
+            if (currentResult) {
+                currentResult.dispose();
+            }
+        };
+    },
+};
+"""

metaframe_widget-0.1.0/src/metaframe_widget/_widget.py

@@ -0,0 +1,83 @@
+import base64
+import urllib.parse
+
+import anywidget
+import traitlets
+
+from ._esm import ESM
+
+
+class MetaframeWidget(anywidget.AnyWidget):
+    """Widget that renders a metaframe iframe (works in Jupyter and marimo).
+
+    Args:
+        url: Full metaframe URL (including hash params).
+        inputs: Dict of inputs to push to the metaframe.
+        outputs: Dict of outputs received from the metaframe (read-only).
+        width: CSS width for the widget container (default "100%").
+        height: CSS height for the widget container (default "400px").
+        allow: iframe allow attribute string (e.g. "camera; microphone").
+    """
+
+    _esm = ESM
+
+    url = traitlets.Unicode("").tag(sync=True)
+    inputs = traitlets.Dict({}).tag(sync=True)
+    outputs = traitlets.Dict({}).tag(sync=True)
+    width = traitlets.Unicode("100%").tag(sync=True)
+    height = traitlets.Unicode("400px").tag(sync=True)
+    allow = traitlets.Unicode("").tag(sync=True)
+
+    def set_inputs(self, d: dict):
+        """Merge a dict into the current inputs."""
+        self.inputs = {**self.inputs, **d}
+
+    def set_input(self, key: str, value):
+        """Set a single input key."""
+        self.inputs = {**self.inputs, key: value}
+
+    def on_outputs_change(self, callback):
+        """Register a callback for when outputs change.
+
+        The callback receives a change dict with 'old' and 'new' keys.
+        """
+        self.observe(callback, names=["outputs"])
+
+    @classmethod
+    def from_code(
+        cls,
+        js_code: str,
+        width: str = "100%",
+        height: str = "400px",
+        allow: str = "",
+        **kwargs,
+    ) -> "MetaframeWidget":
+        """Create a MetaframeWidget from raw JavaScript code.
+
+        Encodes the code into a js.mtfm.io URL with the code in the hash.
+
+        Args:
+            js_code: JavaScript source for the metaframe.
+            width: CSS width for the widget container (default "100%").
+            height: CSS height for the widget container (default "400px").
+            allow: iframe allow attribute string (e.g. "camera; microphone").
+        """
+        encoded = base64.b64encode(js_code.encode()).decode()
+        url = f"https://js.mtfm.io/#?js={urllib.parse.quote(encoded)}"
+        return cls(url=url, width=width, height=height, allow=allow, **kwargs)
+
+    def pipe_to(self, target: "MetaframeWidget", output_key: str, input_key: str = None):
+        """Connect an output of this widget to an input of another.
+
+        When this widget's output_key changes, push the value to
+        target's input_key (defaults to output_key if not specified).
+        """
+        if input_key is None:
+            input_key = output_key
+
+        def _forward(change):
+            new_outputs = change.get("new", {})
+            if output_key in new_outputs:
+                target.set_input(input_key, new_outputs[output_key])
+
+        self.observe(_forward, names=["outputs"])

metaframe_widget-0.1.0/tests/test_widget.py

@@ -0,0 +1,105 @@
+import base64
+import urllib.parse
+
+from metaframe_widget import MetaframeWidget
+
+
+def test_create_widget():
+    w = MetaframeWidget(url="https://js.mtfm.io/#?js=abc")
+    assert w.url == "https://js.mtfm.io/#?js=abc"
+    assert w.inputs == {}
+    assert w.outputs == {}
+    assert w.height == "400px"
+
+
+def test_set_inputs():
+    w = MetaframeWidget()
+    w.set_inputs({"a": 1, "b": 2})
+    assert w.inputs == {"a": 1, "b": 2}
+    w.set_inputs({"b": 3, "c": 4})
+    assert w.inputs == {"a": 1, "b": 3, "c": 4}
+
+
+def test_set_input():
+    w = MetaframeWidget()
+    w.set_input("x", 42)
+    assert w.inputs == {"x": 42}
+    w.set_input("y", "hello")
+    assert w.inputs == {"x": 42, "y": "hello"}
+
+
+def test_from_code():
+    code = 'console.log("hello");'
+    w = MetaframeWidget.from_code(code)
+    encoded = base64.b64encode(code.encode()).decode()
+    expected_url = f"https://js.mtfm.io/#?js={urllib.parse.quote(encoded)}"
+    assert w.url == expected_url
+
+
+def test_from_code_with_kwargs():
+    w = MetaframeWidget.from_code("code", height="600px")
+    assert w.height == "600px"
+    assert "js.mtfm.io" in w.url
+
+
+def test_on_outputs_change():
+    w = MetaframeWidget()
+    changes = []
+    w.on_outputs_change(lambda change: changes.append(change))
+    w.outputs = {"key": "value"}
+    assert len(changes) == 1
+    assert changes[0]["new"] == {"key": "value"}
+
+
+def test_pipe_to():
+    source = MetaframeWidget()
+    sink = MetaframeWidget()
+    source.pipe_to(sink, output_key="doubled", input_key="data")
+    source.outputs = {"doubled": [2, 4, 6]}
+    assert sink.inputs == {"data": [2, 4, 6]}
+
+
+def test_pipe_to_default_key():
+    source = MetaframeWidget()
+    sink = MetaframeWidget()
+    source.pipe_to(sink, output_key="result")
+    source.outputs = {"result": 42}
+    assert sink.inputs == {"result": 42}
+
+
+def test_pipe_to_ignores_unrelated_keys():
+    source = MetaframeWidget()
+    sink = MetaframeWidget()
+    source.pipe_to(sink, output_key="x")
+    source.outputs = {"y": 99}
+    assert sink.inputs == {}
+
+
+def test_pipe_chain_five_widgets():
+    """Five widgets piped in a chain propagate data end-to-end."""
+    w1 = MetaframeWidget()
+    w2 = MetaframeWidget()
+    w3 = MetaframeWidget()
+    w4 = MetaframeWidget()
+    w5 = MetaframeWidget()
+
+    w1.pipe_to(w2, output_key="data")
+    w2.pipe_to(w3, output_key="data")
+    w3.pipe_to(w4, output_key="data")
+    w4.pipe_to(w5, output_key="data")
+
+    # Simulate w1 producing output
+    w1.outputs = {"data": [1, 2, 3]}
+    assert w2.inputs == {"data": [1, 2, 3]}
+
+    # Simulate w2 producing output
+    w2.outputs = {"data": [2, 4, 6]}
+    assert w3.inputs == {"data": [2, 4, 6]}
+
+    # Simulate w3 producing output
+    w3.outputs = {"data": [6, 12, 18]}
+    assert w4.inputs == {"data": [6, 12, 18]}
+
+    # Simulate w4 producing output
+    w4.outputs = {"data": [16, 22, 28]}
+    assert w5.inputs == {"data": [16, 22, 28]}