anyjsonviewer 0.1.0__tar.gz

anyjsonviewer-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# JS
+node_modules/

anyjsonviewer-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: anyjsonviewer
+Version: 0.1.0
+Summary: An anywidget wrapper for @textea/json-viewer
+Requires-Python: >=3.12
+Requires-Dist: anywidget>=0.10.0
+Requires-Dist: traitlets>=5.14.3
+Description-Content-Type: text/markdown
+
+# anyjsonviewer
+
+An [anywidget](https://anywidget.dev) wrapper around
+[`@textea/json-viewer`](https://github.com/TexteaInc/json-viewer), giving you an
+interactive, collapsible JSON viewer inside Jupyter, JupyterLab, VS Code,
+Marimo, or any other frontend that supports Jupyter widgets.
+
+## Installation
+
+```sh
+pip install anyjsonviewer
+```
+
+Or with uv:
+
+```sh
+uv add anyjsonviewer
+```
+
+## Usage
+
+```python
+from anyjsonviewer import JsonViewer
+
+JsonViewer(
+    value={
+        "name": "anyjsonviewer",
+        "tags": ["json", "viewer", "anywidget"],
+        "nested": {"count": 3, "ok": True},
+    },
+    theme="dark",
+)
+```
+
+### Traits
+
+All props are synced traits, so you can update them from Python and the view
+re-renders live:
+
+| Trait | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | any JSON-serializable | `None` | The data to display. |
+| `root_name` | `str \| None` | `"root"` | Label for the root node. `None` hides it. |
+| `theme` | `str` | `"light"` | `"light"`, `"dark"`, or `"auto"`. |
+| `class_name` | `str \| None` | `None` | Custom CSS class on the root element. |
+| `style` | `dict \| None` | `None` | Inline CSS styles for the root element. |
+| `indent_width` | `int` | `3` | Indentation width for nested objects. |
+| `default_inspect_depth` | `int` | `5` | Depth to auto-expand on first render. Set to `0` to fully collapse. |
+| `max_display_length` | `int` | `30` | Hide items in arrays/objects past this count. |
+| `group_arrays_after_length` | `int` | `100` | Group arrays into bracketed chunks after this length. |
+| `collapse_strings_after_length` | `int` | `50` | Truncate long strings; click to expand. |
+| `object_sort_keys` | `bool` | `False` | Sort object keys alphabetically. |
+| `quotes_on_keys` | `bool` | `True` | Wrap keys in quotes. |
+| `display_data_types` | `bool` | `True` | Show type annotations next to values. |
+| `display_size` | `bool` | `True` | Show length of arrays/objects. |
+| `display_comma` | `bool` | `True` | Show trailing commas. |
+| `highlight_updates` | `bool` | `True` | Briefly highlight values when they change. |
+| `enable_clipboard` | `bool` | `False` | Show copy-to-clipboard buttons. |
+| `enable_add` | `bool` | `False` | Show "add" buttons on objects/arrays. |
+| `enable_delete` | `bool` | `False` | Show "delete" buttons on items. |
+| `editable` | `bool` | `False` | Allow inline editing of values. |
+
+When `editable`, `enable_add`, or `enable_delete` are on, edits round-trip
+through the `value` trait — change something in the UI and the new value
+becomes visible from Python.
+
+```python
+w = JsonViewer(value={"a": 1})
+w.theme = "dark"         # live update
+w.value = {"a": 1, "b": 2}
+```
+
+## Development
+
+The widget's JavaScript lives in `js/index.jsx` and is bundled with
+[`esbuild`](https://esbuild.github.io/) into `src/anyjsonviewer/static/widget.js`.
+
+```sh
+# Install Python deps
+uv sync
+
+# Install JS deps
+npm install
+
+# One-off build
+npm run build
+
+# Watch mode (pair with ANYWIDGET_HMR=1 in your notebook)
+npm run dev
+```
+
+Building the wheel automatically runs the JS build via a custom Hatch hook:
+
+```sh
+uv build
+```
+
+To skip the JS build step (e.g. in CI where you've already built the bundle),
+set `ANYJSONVIEWER_SKIP_JS_BUILD=1`.
+
+## License
+
+MIT

anyjsonviewer-0.1.0/README.md

@@ -0,0 +1,103 @@
+# anyjsonviewer
+
+An [anywidget](https://anywidget.dev) wrapper around
+[`@textea/json-viewer`](https://github.com/TexteaInc/json-viewer), giving you an
+interactive, collapsible JSON viewer inside Jupyter, JupyterLab, VS Code,
+Marimo, or any other frontend that supports Jupyter widgets.
+
+## Installation
+
+```sh
+pip install anyjsonviewer
+```
+
+Or with uv:
+
+```sh
+uv add anyjsonviewer
+```
+
+## Usage
+
+```python
+from anyjsonviewer import JsonViewer
+
+JsonViewer(
+    value={
+        "name": "anyjsonviewer",
+        "tags": ["json", "viewer", "anywidget"],
+        "nested": {"count": 3, "ok": True},
+    },
+    theme="dark",
+)
+```
+
+### Traits
+
+All props are synced traits, so you can update them from Python and the view
+re-renders live:
+
+| Trait | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | any JSON-serializable | `None` | The data to display. |
+| `root_name` | `str \| None` | `"root"` | Label for the root node. `None` hides it. |
+| `theme` | `str` | `"light"` | `"light"`, `"dark"`, or `"auto"`. |
+| `class_name` | `str \| None` | `None` | Custom CSS class on the root element. |
+| `style` | `dict \| None` | `None` | Inline CSS styles for the root element. |
+| `indent_width` | `int` | `3` | Indentation width for nested objects. |
+| `default_inspect_depth` | `int` | `5` | Depth to auto-expand on first render. Set to `0` to fully collapse. |
+| `max_display_length` | `int` | `30` | Hide items in arrays/objects past this count. |
+| `group_arrays_after_length` | `int` | `100` | Group arrays into bracketed chunks after this length. |
+| `collapse_strings_after_length` | `int` | `50` | Truncate long strings; click to expand. |
+| `object_sort_keys` | `bool` | `False` | Sort object keys alphabetically. |
+| `quotes_on_keys` | `bool` | `True` | Wrap keys in quotes. |
+| `display_data_types` | `bool` | `True` | Show type annotations next to values. |
+| `display_size` | `bool` | `True` | Show length of arrays/objects. |
+| `display_comma` | `bool` | `True` | Show trailing commas. |
+| `highlight_updates` | `bool` | `True` | Briefly highlight values when they change. |
+| `enable_clipboard` | `bool` | `False` | Show copy-to-clipboard buttons. |
+| `enable_add` | `bool` | `False` | Show "add" buttons on objects/arrays. |
+| `enable_delete` | `bool` | `False` | Show "delete" buttons on items. |
+| `editable` | `bool` | `False` | Allow inline editing of values. |
+
+When `editable`, `enable_add`, or `enable_delete` are on, edits round-trip
+through the `value` trait — change something in the UI and the new value
+becomes visible from Python.
+
+```python
+w = JsonViewer(value={"a": 1})
+w.theme = "dark"         # live update
+w.value = {"a": 1, "b": 2}
+```
+
+## Development
+
+The widget's JavaScript lives in `js/index.jsx` and is bundled with
+[`esbuild`](https://esbuild.github.io/) into `src/anyjsonviewer/static/widget.js`.
+
+```sh
+# Install Python deps
+uv sync
+
+# Install JS deps
+npm install
+
+# One-off build
+npm run build
+
+# Watch mode (pair with ANYWIDGET_HMR=1 in your notebook)
+npm run dev
+```
+
+Building the wheel automatically runs the JS build via a custom Hatch hook:
+
+```sh
+uv build
+```
+
+To skip the JS build step (e.g. in CI where you've already built the bundle),
+set `ANYJSONVIEWER_SKIP_JS_BUILD=1`.
+
+## License
+
+MIT

anyjsonviewer-0.1.0/hatch_build.py

@@ -0,0 +1,33 @@
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+ROOT = Path(__file__).parent
+BUNDLE = ROOT / "src" / "anyjsonviewer" / "static" / "widget.js"
+
+
+class JsBuildHook(BuildHookInterface):
+    PLUGIN_NAME = "anyjsonviewer-js"
+
+    def initialize(self, version, build_data):
+        if os.environ.get("ANYJSONVIEWER_SKIP_JS_BUILD"):
+            return
+        if shutil.which("npm") is None:
+            if BUNDLE.exists():
+                self.app.display_warning(
+                    "npm not found; using existing bundled widget.js"
+                )
+                return
+            raise RuntimeError(
+                "npm is required to build the JS bundle and no prebuilt "
+                "widget.js was found. Install Node.js or set "
+                "ANYJSONVIEWER_SKIP_JS_BUILD=1 if you know what you're doing."
+            )
+        if not (ROOT / "node_modules").exists():
+            subprocess.run(["npm", "install"], cwd=ROOT, check=True)
+        subprocess.run(["npm", "run", "build"], cwd=ROOT, check=True)
+        if not BUNDLE.exists():
+            raise RuntimeError(f"JS build did not produce {BUNDLE}")

anyjsonviewer-0.1.0/js/index.jsx

@@ -0,0 +1,196 @@
+import * as React from "react";
+import { createRoot } from "react-dom/client";
+import { JsonViewer } from "@textea/json-viewer";
+
+// Mirrors src/jsonview/__init__.py:_TAG. Tagged dicts coming from Python
+// represent values that don't survive a JSON round-trip and need to be
+// rehydrated into real JS objects so @textea/json-viewer's built-in type
+// handlers (dateType, the Set renderer, etc.) can display them properly.
+const TAG = "__jsonview_type__";
+
+function encodeValue(node) {
+  if (node === null || node === undefined) return node;
+  if (node instanceof Date) {
+    return { [TAG]: "datetime", iso: node.toISOString() };
+  }
+  if (node instanceof Set) {
+    return { [TAG]: "set", items: [...node].map(encodeValue) };
+  }
+  if (node instanceof Uint8Array) {
+    let bin = "";
+    for (let i = 0; i < node.length; i++) bin += String.fromCharCode(node[i]);
+    return { [TAG]: "bytes", b64: btoa(bin) };
+  }
+  if (Array.isArray(node)) return node.map(encodeValue);
+  if (typeof node === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(node)) out[k] = encodeValue(v);
+    return out;
+  }
+  return node;
+}
+
+function decodeValue(node) {
+  if (node === null || typeof node !== "object") return node;
+  if (Array.isArray(node)) return node.map(decodeValue);
+  if (typeof node[TAG] === "string") {
+    switch (node[TAG]) {
+      case "datetime":
+      case "date":
+        return new Date(node.iso);
+      case "set":
+        return new Set(node.items.map(decodeValue));
+      case "bytes": {
+        const bin = atob(node.b64);
+        const arr = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++) arr[i] = bin.charCodeAt(i);
+        return arr;
+      }
+    }
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(node)) out[k] = decodeValue(v);
+  return out;
+}
+
+const PROPS = [
+  "value",
+  "root_name",
+  "theme",
+  "class_name",
+  "style",
+  "indent_width",
+  "default_inspect_depth",
+  "max_display_length",
+  "group_arrays_after_length",
+  "collapse_strings_after_length",
+  "object_sort_keys",
+  "quotes_on_keys",
+  "display_data_types",
+  "display_size",
+  "display_comma",
+  "highlight_updates",
+  "enable_clipboard",
+  "enable_add",
+  "enable_delete",
+  "editable",
+];
+
+// Apply an edit/add/delete operation to a JSON value at the given path.
+function applyChange(root, path, newValue, op) {
+  // Clone along the path so React/traitlets sees a new object identity.
+  if (path.length === 0) return newValue;
+  const cloneStep = (node) => (Array.isArray(node) ? [...node] : { ...node });
+  const newRoot = cloneStep(root);
+  let parent = newRoot;
+  for (let i = 0; i < path.length - 1; i++) {
+    const key = path[i];
+    parent[key] = cloneStep(parent[key]);
+    parent = parent[key];
+  }
+  const lastKey = path[path.length - 1];
+  if (op === "delete") {
+    if (Array.isArray(parent)) parent.splice(lastKey, 1);
+    else delete parent[lastKey];
+  } else {
+    parent[lastKey] = newValue;
+  }
+  return newRoot;
+}
+
+// Props that @textea/json-viewer bakes into its internal Zustand store on
+// first mount and never re-reads (see createJsonViewerStore in
+// node_modules/@textea/json-viewer/dist/index.mjs — the useMemo there has an
+// empty deps array). Changing any of these requires remounting the component
+// via a different React `key`. The remaining props (value, theme, class_name,
+// style) are read directly from props on every render and update live.
+const STORE_BAKED_PROPS = [
+  "root_name",
+  "indent_width",
+  "default_inspect_depth",
+  "max_display_length",
+  "group_arrays_after_length",
+  "collapse_strings_after_length",
+  "object_sort_keys",
+  "quotes_on_keys",
+  "display_data_types",
+  "display_size",
+  "display_comma",
+  "highlight_updates",
+  "enable_clipboard",
+  "enable_add",
+  "enable_delete",
+  "editable",
+];
+
+function Widget({ model }) {
+  const [, force] = React.useReducer((x) => x + 1, 0);
+
+  React.useEffect(() => {
+    for (const p of PROPS) model.on(`change:${p}`, force);
+    return () => {
+      for (const p of PROPS) model.off(`change:${p}`, force);
+    };
+  }, [model]);
+
+  const remountKey = STORE_BAKED_PROPS.map((p) => JSON.stringify(model.get(p))).join("|");
+  const decodedValue = React.useMemo(() => decodeValue(model.get("value")), [model.get("value")]);
+
+  const handleChange = React.useCallback(
+    (path, _oldVal, newVal) => {
+      const current = decodeValue(model.get("value"));
+      const next = applyChange(current, path, newVal, "set");
+      model.set("value", encodeValue(next));
+      model.save_changes();
+    },
+    [model],
+  );
+
+  const handleDelete = React.useCallback(
+    (path) => {
+      const current = decodeValue(model.get("value"));
+      const next = applyChange(current, path, undefined, "delete");
+      model.set("value", encodeValue(next));
+      model.save_changes();
+    },
+    [model],
+  );
+
+  return (
+    <JsonViewer
+      key={remountKey}
+      value={decodedValue}
+      rootName={model.get("root_name") ?? false}
+      theme={model.get("theme")}
+      className={model.get("class_name") ?? undefined}
+      style={model.get("style") ?? undefined}
+      indentWidth={model.get("indent_width")}
+      defaultInspectDepth={model.get("default_inspect_depth")}
+      maxDisplayLength={model.get("max_display_length")}
+      groupArraysAfterLength={model.get("group_arrays_after_length")}
+      collapseStringsAfterLength={model.get("collapse_strings_after_length")}
+      objectSortKeys={model.get("object_sort_keys")}
+      quotesOnKeys={model.get("quotes_on_keys")}
+      displayDataTypes={model.get("display_data_types")}
+      displaySize={model.get("display_size")}
+      displayComma={model.get("display_comma")}
+      highlightUpdates={model.get("highlight_updates")}
+      enableClipboard={model.get("enable_clipboard")}
+      enableAdd={model.get("enable_add")}
+      enableDelete={model.get("enable_delete")}
+      editable={model.get("editable")}
+      onChange={handleChange}
+      onDelete={handleDelete}
+    />
+  );
+}
+
+function render({ model, el }) {
+  const container = document.createElement("div");
+  el.appendChild(container);
+  const root = createRoot(container);
+  root.render(<Widget model={model} />);
+  return () => root.unmount();
+}
+
+export default { render };