manywidgets 0.1.0__py3-none-any.whl

manywidgets/__init__.py

@@ -0,0 +1,49 @@
+"""manywidgets — a composable set of anywidget-based widgets for notebooks.
+
+Widgets are plain anywidgets: they work in a live Jupyter kernel and are
+authored to also render correctly when statically exported (no kernel) via the
+``myst-anywidget-static-export`` plugin. Link them with ``ipywidgets.jslink`` /
+``jsdlink`` for the simple cases, or the :class:`~manywidgets.Binder` widget for
+transforms and nested-path targets that jslink can't express.
+
+The optional ``manywidgets.lonboard`` subpackage adds control widgets for lonboard
+maps; install it with ``pip install "manywidgets[lonboard]"``.
+"""
+
+from ._base import BaseWidget
+from ._version import __version__
+from .binder import Binder
+from .button import Button
+from .chart import Chart
+from .column import Column
+from .dropdown import Dropdown
+from .grid import Grid
+from .legend import Legend
+from .number_display import NumberDisplay
+from .number_input import NumberInput
+from .range_slider import RangeSlider
+from .row import Row
+from .slider import Slider
+from .stat import Stat
+from .text import Text
+from .toggle import Toggle
+
+__all__ = [
+    "BaseWidget",
+    "Binder",
+    "Button",
+    "Chart",
+    "Column",
+    "Dropdown",
+    "Grid",
+    "Legend",
+    "NumberDisplay",
+    "NumberInput",
+    "RangeSlider",
+    "Row",
+    "Slider",
+    "Stat",
+    "Text",
+    "Toggle",
+    "__version__",
+]

manywidgets/__main__.py

@@ -0,0 +1,107 @@
+"""``manywidgets`` command-line entry point.
+
+Currently exposes a single subcommand, ``install-skill``, which copies the
+bundled agent skill (``manywidgets/skill/``) into a location your coding agent
+discovers. Claude Code looks in ``.claude/skills/`` (project) and
+``~/.claude/skills/`` (personal), but the skill is plain Markdown — use
+``--path`` to drop it wherever another agent expects it.
+
+    manywidgets install-skill                 # ./.claude/skills/manywidgets/
+    manywidgets install-skill --user          # ~/.claude/skills/manywidgets/
+    manywidgets install-skill --path DIR      # DIR/manywidgets/
+    manywidgets install-skill --force         # overwrite an existing copy
+"""
+
+from __future__ import annotations
+
+import argparse
+import pathlib
+import shutil
+import sys
+from importlib import resources
+
+
+def _bundled_skill_dir() -> pathlib.Path:
+    """Path to the skill files shipped inside the installed package."""
+    return pathlib.Path(str(resources.files("manywidgets") / "skill"))
+
+
+def _resolve_target(args: argparse.Namespace) -> pathlib.Path:
+    """Where the ``manywidgets/`` skill folder should be written."""
+    if args.path:
+        base = pathlib.Path(args.path).expanduser()
+    elif args.user:
+        base = pathlib.Path.home() / ".claude" / "skills"
+    else:
+        base = pathlib.Path.cwd() / ".claude" / "skills"
+    return base / "manywidgets"
+
+
+def install_skill(args: argparse.Namespace) -> int:
+    src = _bundled_skill_dir()
+    if not (src / "SKILL.md").is_file():
+        print(
+            f"error: bundled skill not found at {src}. "
+            "Reinstall manywidgets, or run from a source checkout after "
+            "`npm run skill:gen`.",
+            file=sys.stderr,
+        )
+        return 1
+
+    dest = _resolve_target(args)
+    if dest.exists():
+        if not args.force:
+            print(
+                f"error: {dest} already exists. Re-run with --force to overwrite.",
+                file=sys.stderr,
+            )
+            return 1
+        shutil.rmtree(dest)
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    # Copy only the skill content (SKILL.md + references/*.md), not stray files.
+    shutil.copytree(
+        src,
+        dest,
+        ignore=shutil.ignore_patterns("__pycache__", "*.pyc"),
+    )
+    print(f"Installed manywidgets skill to {dest}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="manywidgets")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser(
+        "install-skill",
+        help="Copy the bundled agent skill into a discoverable location.",
+        description=install_skill.__doc__,
+    )
+    where = p.add_mutually_exclusive_group()
+    where.add_argument(
+        "--user",
+        action="store_true",
+        help="Install to ~/.claude/skills/ instead of the current project.",
+    )
+    where.add_argument(
+        "--path",
+        metavar="DIR",
+        help="Install under an arbitrary directory (for agents other than Claude).",
+    )
+    p.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite an existing installation.",
+    )
+    p.set_defaults(func=install_skill)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

manywidgets/_base.py

@@ -0,0 +1,73 @@
+"""Shared base class and small helpers for every manywidgets widget.
+
+``BaseWidget`` is a thin ``anywidget.AnyWidget`` subclass — no magic; widgets
+remain plain anywidgets. Its one job is to give every widget a stable, unique
+``widget_id`` trait, which is the handle that ``Binder`` and the shared
+``@manywidgets/core`` registry use to find a widget across the live-kernel /
+static-export boundary.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import threading
+from collections import defaultdict
+
+import anywidget
+import traitlets
+
+# Per-class monotonic counters so auto-generated ids are stable and readable
+# (``chart_1``, ``chart_2``, ``slider_1``, …) within a kernel session.
+_id_counters: dict[str, int] = defaultdict(int)
+_id_lock = threading.Lock()
+
+
+def _next_id(prefix: str) -> str:
+    with _id_lock:
+        _id_counters[prefix] += 1
+        return f"{prefix}_{_id_counters[prefix]}"
+
+
+def _flatten(children) -> list:
+    """Flatten one level of list/tuple args into a flat list of children.
+
+    Lets layout widgets accept a mix of widgets and lists of widgets, e.g.
+    ``Column(slider, binders, m)`` where ``binders`` is itself a list.
+    """
+    flat: list = []
+    for child in children:
+        if isinstance(child, (list, tuple)):
+            flat.extend(child)
+        else:
+            flat.append(child)
+    return flat
+
+
+def asset(module_file: str, *parts: str) -> pathlib.Path:
+    """Resolve a path next to a widget's ``widget.py``.
+
+    Usage inside a widget module::
+
+        _esm = asset(__file__, "dist", "widget.js")
+        _css = asset(__file__, "style.css")
+    """
+    return pathlib.Path(module_file).parent.joinpath(*parts)
+
+
+class BaseWidget(anywidget.AnyWidget):
+    """Base class for all manywidgets widgets.
+
+    Adds an auto-populated ``widget_id`` (``f"{classname_lower}_{n}"``) used for
+    cross-widget linking. Subclasses set their own ``_esm`` / ``_css`` (relative
+    to their own file, via :func:`asset`) exactly like the golden-example
+    structure.
+    """
+
+    widget_id = traitlets.Unicode(
+        help="Stable unique id used for cross-widget linking (auto-assigned)."
+    ).tag(sync=True)
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        if not self.widget_id:
+            self.widget_id = _next_id(type(self).__name__.lower())

manywidgets/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

manywidgets/binder/__init__.py

@@ -0,0 +1,3 @@
+from .widget import Binder
+
+__all__ = ["Binder"]

manywidgets/binder/dist/widget.js

@@ -0,0 +1,171 @@
+// packages/core/src/index.ts
+function safeSaveChanges(model) {
+  try {
+    model?.save_changes?.();
+  } catch {
+  }
+}
+function stripIpy(id) {
+  return id ? String(id).replace(/^IPY_MODEL_/, "") : "";
+}
+function asNumber(value, fallback = 0) {
+  const n = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+function setByPath(model, path, value) {
+  const parts = path.split(".");
+  if (parts.length === 1) {
+    model.set(parts[0], value);
+    return;
+  }
+  const topKey = parts[0];
+  const existing = model.get(topKey);
+  const next = existing && typeof existing === "object" ? { ...existing } : {};
+  let cursor = next;
+  for (let i = 1; i < parts.length - 1; i++) {
+    const k = parts[i];
+    const child = cursor[k];
+    cursor[k] = child && typeof child === "object" ? { ...child } : {};
+    cursor = cursor[k];
+  }
+  cursor[parts[parts.length - 1]] = value;
+  model.set(topKey, next);
+}
+function deliverCustomMessage(model, content, buffers = []) {
+  if (typeof model.receiveCustomMessage === "function") {
+    model.receiveCustomMessage(content, buffers);
+  } else if (typeof model.trigger === "function") {
+    model.trigger("msg:custom", content, buffers);
+  }
+}
+function getStaticRegistry() {
+  const hosts = globalThis.__myst_anywidget_hosts;
+  if (!hosts || typeof hosts.values !== "function") return null;
+  for (const v of hosts.values()) return v;
+  return null;
+}
+function findAllInRegistry(reg, id) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const push = (m) => {
+    if (m && !seen.has(m)) {
+      seen.add(m);
+      out.push(m);
+    }
+  };
+  if (typeof reg.get === "function") push(reg.get(id));
+  const all = typeof reg.filter === "function" ? reg.filter((w) => !!w && w.model_id === id) : typeof reg.all === "function" ? reg.all().filter((w) => !!w && w.model_id === id) : [];
+  for (const m of all) push(m);
+  return out;
+}
+function makeHandle(getModels) {
+  return {
+    get models() {
+      return getModels();
+    },
+    get(field) {
+      const ms = getModels();
+      return ms.length ? ms[0].get(field) : void 0;
+    },
+    set(field, value) {
+      for (const m of getModels()) m.set(field, value);
+    },
+    setByPath(path, value) {
+      for (const m of getModels()) setByPath(m, path, value);
+    },
+    save() {
+      for (const m of getModels()) safeSaveChanges(m);
+    },
+    on(field, fn) {
+      for (const m of getModels()) m.on?.(`change:${field}`, () => fn(m.get(field)));
+    },
+    sendCustom(content, buffers = []) {
+      for (const m of getModels()) deliverCustomMessage(m, content, buffers);
+    }
+  };
+}
+async function resolveModel(model, ref, { timeout = 5e3 } = {}) {
+  const id = stripIpy(ref);
+  const reg = getStaticRegistry();
+  if (reg) {
+    return makeHandle(() => findAllInRegistry(reg, id));
+  }
+  if (model.widget_manager?.get_model) {
+    const resolved = await withTimeout(model.widget_manager.get_model(id), timeout);
+    let current = resolved ?? null;
+    return makeHandle(() => current ? [current] : []);
+  }
+  throw new Error(`[manywidgets] cannot resolve model "${id}": no host registry and no widget_manager`);
+}
+function withTimeout(promise, ms) {
+  return new Promise((resolve, reject) => {
+    const t = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
+    promise.then(
+      (v) => {
+        clearTimeout(t);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(t);
+        reject(e);
+      }
+    );
+  });
+}
+
+// src/manywidgets/binder/src/index.ts
+var POLL_MS = 100;
+var MAX_RUN_MS = 30 * 60 * 1e3;
+async function render({ model, el }) {
+  const sourceId = model.get("source_widget_id");
+  const sourceField = model.get("source_field") || "value";
+  const targetId = model.get("target_widget_id");
+  const targetField = model.get("target_field");
+  const multiplier = model.get("multiplier");
+  const offset = model.get("offset");
+  const label = model.get("label") || `${sourceId}.${sourceField} \u2192 ${targetId}.${targetField}`;
+  el.className = "manywidgets-binder";
+  el.style.cssText = "font:12px/1.4 ui-monospace,SFMono-Regular,monospace;color:#24292e;padding:6px 10px;border:1px solid #e1e4e8;border-radius:6px;background:#f6f8fa;max-width:fit-content;margin:6px 0;";
+  const status = document.createElement("div");
+  status.textContent = `\u{1F517} binder: connecting\u2026  (${label})`;
+  el.appendChild(status);
+  let source;
+  let target;
+  try {
+    [source, target] = await Promise.all([
+      resolveModel(model, sourceId),
+      resolveModel(model, targetId)
+    ]);
+  } catch (err) {
+    status.textContent = `\u274C binder failed: ${err.message}`;
+    console.error("[manywidgets:binder] resolve failed", err, { sourceId, targetId });
+    return;
+  }
+  let lastKey = null;
+  const apply = () => {
+    const raw = source.get(sourceField);
+    const next = typeof raw === "number" ? asNumber(raw) * multiplier + offset : raw;
+    const key = JSON.stringify(next ?? null);
+    if (key === lastKey) return;
+    lastKey = key;
+    target.setByPath(targetField, next);
+    target.save();
+  };
+  source.on(sourceField, apply);
+  apply();
+  status.textContent = `\u2705 ${label}`;
+  const stopAt = Date.now() + MAX_RUN_MS;
+  const loop = () => {
+    try {
+      apply();
+    } catch (err) {
+      console.warn("[manywidgets:binder] tick error", err);
+    }
+    if (Date.now() < stopAt) setTimeout(loop, POLL_MS);
+  };
+  setTimeout(loop, POLL_MS);
+}
+var index_default = { render };
+export {
+  index_default as default
+};

manywidgets/binder/doc.md

@@ -0,0 +1,38 @@
+# Binder
+
+Link a source widget's trait into a target's, with an optional linear transform
+(`multiplier`/`offset`) or a nested dotted-path target.
+
+## Import
+
+```python
+from manywidgets import Binder
+```
+
+## Example
+
+Drag the slider — the chart's `width` follows `value × 100`:
+
+```{code-cell} python
+import numpy as np
+from manywidgets import Slider, Chart, Binder
+
+x = np.linspace(0, 10, 100)
+chart = Chart(title="sin")
+chart.add_series(x=x, y=np.sin(x), name="sin")
+
+width = Slider(label="Width", min=4, max=12, value=8)
+binder = Binder(source=width, source_field="value",
+                target=chart, target_field="width", multiplier=100)
+
+display(width, chart, binder)
+```
+
+## API
+
+{api-table}
+
+`Binder` covers what `jslink`/`jsdlink` can't: a linear transform on the value, or
+writing a nested **dotted-path** target (e.g. `target_field="view_state.zoom"`),
+merged into the parent dict. For plain pass-through links, prefer `jslink` — see the
+[linking guide](../guides/linking.md).

manywidgets/binder/src/index.ts

@@ -0,0 +1,81 @@
+import type { RenderProps } from "@anywidget/types";
+import { asNumber, resolveModel, type ModelHandle } from "@manywidgets/core";
+
+interface BinderModel {
+  source_widget_id: string;
+  source_field: string;
+  target_widget_id: string;
+  target_field: string;
+  multiplier: number;
+  offset: number;
+  label: string;
+}
+
+const POLL_MS = 100;
+const MAX_RUN_MS = 30 * 60 * 1000;
+
+async function render({ model, el }: RenderProps<BinderModel>): Promise<void> {
+  const sourceId = model.get("source_widget_id");
+  const sourceField = model.get("source_field") || "value";
+  const targetId = model.get("target_widget_id");
+  const targetField = model.get("target_field");
+  const multiplier = model.get("multiplier");
+  const offset = model.get("offset");
+  const label =
+    model.get("label") ||
+    `${sourceId}.${sourceField} → ${targetId}.${targetField}`;
+
+  el.className = "manywidgets-binder";
+  el.style.cssText =
+    "font:12px/1.4 ui-monospace,SFMono-Regular,monospace;color:#24292e;" +
+    "padding:6px 10px;border:1px solid #e1e4e8;border-radius:6px;" +
+    "background:#f6f8fa;max-width:fit-content;margin:6px 0;";
+  const status = document.createElement("div");
+  status.textContent = `🔗 binder: connecting…  (${label})`;
+  el.appendChild(status);
+
+  let source: ModelHandle;
+  let target: ModelHandle;
+  try {
+    [source, target] = await Promise.all([
+      resolveModel(model, sourceId),
+      resolveModel(model, targetId),
+    ]);
+  } catch (err) {
+    status.textContent = `❌ binder failed: ${(err as Error).message}`;
+    console.error("[manywidgets:binder] resolve failed", err, { sourceId, targetId });
+    return;
+  }
+
+  let lastKey: string | null = null;
+  const apply = (): void => {
+    const raw = source.get(sourceField);
+    const next = typeof raw === "number" ? asNumber(raw) * multiplier + offset : raw;
+    const key = JSON.stringify(next ?? null);
+    if (key === lastKey) return;
+    lastKey = key;
+    target.setByPath(targetField, next);
+    target.save();
+  };
+
+  // Live kernel: change events fire on the canonical source model.
+  source.on(sourceField, apply);
+  // Apply once so the target reflects the current source state immediately.
+  apply();
+  status.textContent = `✅ ${label}`;
+
+  // Static export (and a safety net live): proxies may not emit change events
+  // and the target proxy can register late, so poll and re-apply on change.
+  const stopAt = Date.now() + MAX_RUN_MS;
+  const loop = (): void => {
+    try {
+      apply();
+    } catch (err) {
+      console.warn("[manywidgets:binder] tick error", err);
+    }
+    if (Date.now() < stopAt) setTimeout(loop, POLL_MS);
+  };
+  setTimeout(loop, POLL_MS);
+}
+
+export default { render };

manywidgets/binder/widget.py

@@ -0,0 +1,81 @@
+"""Binder — a tiny widget that wires one widget's trait to another's, in JS.
+
+The cleaned-up successor to the ``widget_binder`` experiment. ``jslink`` /
+``jsdlink`` is the canonical way to link manywidgets (see the linking guide);
+``Binder`` covers the cases jslink can't express:
+
+* a linear transform on the value (``multiplier`` / ``offset``), and
+* writing a **nested / dotted-path** target (e.g. lonboard ``view_state.zoom``),
+  which is merged into the parent dict so listeners see one coherent update.
+
+For ergonomics it accepts widget **instances** and reads their ``widget_id``::
+
+    Binder(source=slider, source_field="value",
+           target=chart, target_field="x_max",
+           multiplier=1000)
+
+It works in a live kernel and in static export — the JS side resolves both
+widgets through ``@manywidgets/core``'s ``resolveModel`` (which handles the
+multi-proxy / late-registration hazards).
+"""
+
+from __future__ import annotations
+
+import traitlets
+
+from .._base import BaseWidget, asset
+
+
+def _id_of(widget_or_id):
+    """Accept a widget instance (read its ``widget_id``) or a raw id string."""
+    if widget_or_id is None:
+        return ""
+    if isinstance(widget_or_id, str):
+        return widget_or_id
+    wid = getattr(widget_or_id, "widget_id", None)
+    if not wid:
+        raise TypeError(
+            f"{widget_or_id!r} has no 'widget_id'; pass a manywidgets widget "
+            "instance or an explicit id string."
+        )
+    return wid
+
+
+class Binder(BaseWidget):
+    """Link a source widget's trait to a target widget's trait, in the browser."""
+
+    _esm = asset(__file__, "dist", "widget.js")
+
+    source_widget_id = traitlets.Unicode("", help="widget_id of the source widget.").tag(sync=True)
+    source_field = traitlets.Unicode("value", help="Source trait to read.").tag(sync=True)
+    target_widget_id = traitlets.Unicode("", help="widget_id of the target widget.").tag(sync=True)
+    target_field = traitlets.Unicode(
+        "", help="Target trait/dotted-path to write (e.g. 'view_state.zoom')."
+    ).tag(sync=True)
+    multiplier = traitlets.Float(1.0, help="Linear transform multiplier.").tag(sync=True)
+    offset = traitlets.Float(0.0, help="Linear transform offset.").tag(sync=True)
+    label = traitlets.Unicode("", help="Optional status label.").tag(sync=True)
+
+    def __init__(
+        self,
+        source=None,
+        target=None,
+        *,
+        source_field="value",
+        target_field=None,
+        multiplier=1.0,
+        offset=0.0,
+        **kwargs,
+    ):
+        if source is not None and "source_widget_id" not in kwargs:
+            kwargs["source_widget_id"] = _id_of(source)
+        if target is not None and "target_widget_id" not in kwargs:
+            kwargs["target_widget_id"] = _id_of(target)
+        kwargs.setdefault("source_field", source_field)
+        if target_field is not None:
+            kwargs.setdefault("target_field", target_field)
+        kwargs.setdefault("multiplier", multiplier)
+        kwargs.setdefault("offset", offset)
+        super().__init__(**kwargs)
+        if not self.target_field:
+            raise ValueError("Binder requires a 'target_field'.")

manywidgets/button/__init__.py

@@ -0,0 +1,3 @@
+from .widget import Button
+
+__all__ = ["Button"]

manywidgets/button/dist/widget.js

@@ -0,0 +1,31 @@
+// packages/core/src/index.ts
+function safeSaveChanges(model) {
+  try {
+    model?.save_changes?.();
+  } catch {
+  }
+}
+function asNumber(value, fallback = 0) {
+  const n = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+// src/manywidgets/button/src/index.ts
+function render({ model, el }) {
+  const button = document.createElement("button");
+  button.className = "manywidgets-button";
+  button.type = "button";
+  button.textContent = model.get("label");
+  el.appendChild(button);
+  button.addEventListener("click", () => {
+    model.set("clicks", asNumber(model.get("clicks")) + 1);
+    safeSaveChanges(model);
+  });
+  model.on("change:label", () => {
+    button.textContent = model.get("label");
+  });
+}
+var index_default = { render };
+export {
+  index_default as default
+};

manywidgets/button/doc.md

@@ -0,0 +1,46 @@
+# Button
+
+A click button with a `clicks` counter and Python `on_click` callbacks.
+
+## Import
+
+```python
+from manywidgets import Button
+```
+
+## Example
+
+```{code-cell} python
+from manywidgets import Button
+
+btn = Button(label="Run")
+btn
+```
+
+## API
+
+{api-table}
+
+`on_click(callback, remove=False)` registers/removes a `callback(button)` fired
+when `clicks` increases (live kernel only).
+
+```python
+btn = Button(label="Run")
+
+@btn.on_click
+def _(b):
+    print("clicked", b.clicks, "times")
+```
+
+## Linking
+
+Link `clicks` like any trait (see the [linking guide](../guides/linking.md)):
+
+```python
+from ipywidgets import jsdlink
+from manywidgets import Button, NumberDisplay
+
+btn = Button(label="+1")
+count = NumberDisplay(label="Clicks", duration=0)
+jsdlink((btn, "clicks"), (count, "value"))
+```