dr-widget 0.1.3__py3-none-any.whl

dr_widget/__init__.py

@@ -0,0 +1,5 @@
+"""Top-level package for dr_widget."""
+
+from .widgets.config_file_manager import ConfigFileManager
+
+__all__ = ["ConfigFileManager"]

dr_widget/widgets/__init__.py

@@ -0,0 +1,5 @@
+"""Widget exports for dr_widget."""
+
+from .config_file_manager import ConfigFileManager
+
+__all__ = ["ConfigFileManager"]

dr_widget/widgets/config_file_manager/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

dr_widget/widgets/config_file_manager/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["svelte.svelte-vscode"]
+}

dr_widget/widgets/config_file_manager/README.md

@@ -0,0 +1,89 @@
+# Config File Manager Widget
+
+The `dr_widget` package ships an AnyWidget-powered config file manager so notebooks can load, inspect, edit, and save JSON configuration blobs without leaving the browser. The frontend lives under `src/dr_widget/widgets/config_file_manager`, is built with Svelte + Vite via Bun, and syncs its state to Python traitlets.
+
+## Repository Layout
+
+- `src/dr_widget/widgets/config_file_manager/__init__.py` – AnyWidget class with initialization helpers and traitlet contracts.
+- `src/dr_widget/widgets/config_file_manager/src/` – Svelte workspace (components live under `lib/`).
+- `src/dr_widget/widgets/config_file_manager/static/` – Built bundle consumed by AnyWidget.
+- `notebooks/config_file_manager_widget.py` – Marimo demo that exercises the widget end-to-end.
+
+## Traitlets
+
+| Traitlet | Direction | Description |
+| --- | --- | --- |
+| `current_state` | ↔ | JSON string representing **user data only** (no metadata). |
+| `baseline_state` | ↔ | Last saved value of `current_state`, used for dirty detection/diffs. |
+| `version` | ↔ | String metadata displayed in the UI and written to disk alongside `current_state` (now nested under `metadata.version`). |
+| `config_file` | ↔ | Path to the backing file (may be relative today). |
+| `config_file_display` | ↔ | UI-friendly label derived from `config_file`. |
+| `files` | ↔ | JSON array of uploaded files (`{ name, size, type }`). |
+| `file_count` | ← | Derived from `files.length`; read-only in the UI. |
+| `error` | ↔ | User-facing error message cleared automatically on recovery. |
+
+Python helper properties (`current_data`, `baseline_data`, `is_dirty`) expose parsed state for notebooks.
+
+## Initialization Patterns
+
+```python
+ConfigFileManager()  # empty widget, user loads file via UI
+
+ConfigFileManager(config_dict={"orchard": ["Basin"]}, version="exp_v1")
+# - current_state populated with data dict
+# - baseline_state empty → dirty until saved
+# - config_file defaults to "exp_v1.json"
+
+ConfigFileManager(config_file="/path/to/existing.json")
+# - loads and migrates the file into new format
+# - baseline_state matches current_state (clean)
+# - version pulled from file metadata
+
+ConfigFileManager(
+    config_file="/tmp/new.json",
+    config_dict={"selections": {"foo": True}},
+    version="v2",
+)
+# - writes wrapped payload {metadata:{version,saved_at},data}
+# - baseline_state matches current_state
+```
+
+Files saved through the UI (or via `config_file` + `config_dict`) are always written as:
+
+```json
+{
+  "metadata": {
+    "version": "v1",
+    "saved_at": "2025-11-12T10:30:00Z"
+  },
+  "data": { ... user data ... }
+}
+```
+
+Older files that only contain `selections` or embed metadata at the top level are migrated into this structure when loaded, with legacy `version`/`saved_at` values relocated under `metadata`.
+
+## Frontend Behavior
+
+- `use-file-bindings.ts` manages read/write loops for every synced traitlet so Marimo reactivity stays intact.
+- `ConfigFileManager.svelte` derives dirty state by comparing `current_state` vs `baseline_state`, shows the currently loaded file name/version, and exposes Browse + Save panels.
+- `SaveConfigPanel.svelte` wraps the current data with metadata before writing to disk (File System Access API when available, otherwise download).
+
+## Build & Test
+
+```bash
+bun install
+npx svelte-check --tsconfig src/dr_widget/widgets/config_file_manager/tsconfig.json
+bun run build:config-file-manager
+bun run build  # aggregates widgets (currently same as line above)
+uv build       # packages the Python wheel with fresh static assets
+```
+
+Manual validation: run `marimo run notebooks/config_file_manager_widget.py`, load/upload JSON configs (including legacy "selections" files), edit values, and save to disk. Confirm dirty badge toggles correctly and version changes propagate between the sidebar and save panel.
+
+## Contributing Tips
+
+- Shared UI lives in `src/dr_widget/widgets/config_file_manager/src/lib/{components,hooks}`; prefer reusing hooks like `use-file-bindings`.
+- Keep Tailwind utility classes grouped logically (layout → spacing → color → effects).
+- Treat `node_modules/` as generated; never edit or commit them.
+- Run `bunx prettier --write src/dr_widget/widgets/config_file_manager/src` before opening a PR.
+- Document new traitlets or metadata fields in `docs/architecture.md` and notebook demos to keep Python + Svelte in sync.

dr_widget/widgets/config_file_manager/__init__.py

@@ -0,0 +1,283 @@
+"""AnyWidget bindings for the config file manager widget."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import anywidget
+import traitlets
+
+__all__ = ["ConfigFileManager"]
+
+_STATIC_DIR = Path(__file__).parent / "static"
+
+
+def _normalize_version(value: Optional[str]) -> str:
+    if value is None:
+        return "default_v0"
+    value = str(value).strip()
+    return value or "default_v0"
+
+
+def _default_config_name(version: str) -> str:
+    safe = ''.join(ch if ch.isalnum() or ch in {"-", "_"} else "_" for ch in version)
+    safe = safe or "default_v0"
+    return f"{safe}.json"
+
+
+def _resolve_config_path(value: str | Path | None) -> str:
+    if value is None:
+        return ""
+
+    raw = str(value).strip()
+    if not raw:
+        return ""
+
+    candidate = Path(raw).expanduser()
+    if not candidate.is_absolute():
+        candidate = Path.cwd() / candidate
+
+    return str(candidate.resolve())
+
+
+def _serialize_user_state(data: Dict[str, Any]) -> str:
+    """Return a JSON string for the user-facing state or an empty string."""
+
+    if not data:
+        return ""
+
+    try:
+        return json.dumps(data, sort_keys=True, separators=(",", ":"))
+    except (TypeError, ValueError) as exc:  # pragma: no cover - defensive
+        raise ValueError("Config state must be JSON serializable") from exc
+
+
+def _ensure_mapping(value: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise TypeError("config_dict must be a mapping of keys to values")
+    return value
+
+
+def _utc_timestamp() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _normalize_payload(payload: Dict[str, Any]) -> Dict[str, Any]:
+    """Ensure the payload follows the new metadata/data contract."""
+
+    normalized: Dict[str, Any] = dict(payload)
+    data = normalized.get("data")
+
+    metadata_candidate = normalized.get("metadata")
+    if isinstance(metadata_candidate, dict):
+        metadata: Dict[str, Any] = dict(metadata_candidate)
+    else:
+        metadata = {}
+
+    for legacy_key in ("version", "saved_at"):
+        if legacy_key in normalized and legacy_key not in metadata:
+            metadata[legacy_key] = normalized.pop(legacy_key)
+
+    if not isinstance(data, dict):
+        user_data: Dict[str, Any] = {}
+
+        selections = normalized.pop("selections", None)
+        if isinstance(selections, dict):
+            user_data.setdefault("selections", selections)
+
+        for key in list(normalized.keys()):
+            if key in {"version", "saved_at", "data", "metadata"}:
+                continue
+            user_data[key] = normalized.pop(key)
+
+        data = user_data
+
+    normalized["metadata"] = metadata
+    normalized["data"] = data if isinstance(data, dict) else {}
+    return normalized
+
+
+def _load_config_from_file(path: Path) -> Dict[str, Any]:
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        raise
+    except OSError as exc:  # pragma: no cover - filesystem specific
+        raise IOError(f"Unable to read config file: {path}") from exc
+
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Config file must contain valid JSON: {path}") from exc
+
+    if not isinstance(parsed, dict):
+        raise ValueError("Config file root must be a JSON object")
+
+    return _normalize_payload(parsed)
+
+
+def _write_config_to_file(path: Path, *, data: Dict[str, Any], version: str) -> str:
+    saved_at = _utc_timestamp()
+    payload = {
+        "metadata": {
+            "version": version,
+            "saved_at": saved_at,
+            "save_path": str(path),
+        },
+        "data": data,
+    }
+
+    serialized = json.dumps(payload, indent=2, sort_keys=True)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(serialized + "\n", encoding="utf-8")
+    return saved_at
+
+
+def _file_binding_entry(path: Path) -> Dict[str, Any]:
+    try:
+        size = path.stat().st_size
+    except OSError:
+        size = 0
+
+    return {
+        "name": path.name,
+        "size": size,
+        "type": "application/json",
+    }
+
+
+class ConfigFileManager(anywidget.AnyWidget):
+    """Config file manager widget for notebooks."""
+
+    # AnyWidget expects module references pointing at the built assets on disk.
+    _esm = _STATIC_DIR / "index.js"
+    _css = _STATIC_DIR / "style.css"
+
+    current_state = traitlets.Unicode("").tag(sync=True)
+    baseline_state = traitlets.Unicode("").tag(sync=True)
+    config_file = traitlets.Unicode("").tag(sync=True)
+    config_file_display = traitlets.Unicode("").tag(sync=True)
+    version = traitlets.Unicode("default_v0").tag(sync=True)
+    saved_at = traitlets.Unicode("").tag(sync=True)
+    files = traitlets.Unicode("[]").tag(sync=True)
+    file_count = traitlets.Int(0).tag(sync=True)
+    error = traitlets.Unicode("").tag(sync=True)
+
+    def __init__(
+        self,
+        config_file: str | Path | None = None,
+        config_dict: Optional[Dict[str, Any]] = None,
+        version: str = "default_v0",
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+
+        normalized_version = _normalize_version(version)
+        self.version = normalized_version
+        self.current_state = ""
+        self.baseline_state = ""
+        self.config_file = ""
+        self.saved_at = ""
+
+        if config_file is None and config_dict is None:
+            return
+
+        if config_file is None:
+            user_data = _ensure_mapping(config_dict)
+            self.current_state = _serialize_user_state(user_data)
+            # No baseline until the data is persisted via the UI.
+            self.baseline_state = ""
+            default_name = _default_config_name(self.version)
+            default_path = _resolve_config_path(default_name)
+            self.config_file = default_path
+            return
+
+        resolved_path = _resolve_config_path(config_file)
+        path = Path(resolved_path)
+
+        if config_dict is not None:
+            if path.exists():
+                raise FileExistsError(
+                    f"Config file already exists: {path}. Refusing to overwrite."
+                )
+
+            user_data = _ensure_mapping(config_dict)
+            _write_config_to_file(path, data=user_data, version=self.version)
+        elif not path.exists():
+            raise FileNotFoundError(f"Config file does not exist: {path}")
+
+        payload = _load_config_from_file(path)
+        file_data = payload.get("data")
+        user_state = file_data if isinstance(file_data, dict) else {}
+        serialized_state = _serialize_user_state(user_state)
+
+        metadata = payload.get("metadata")
+        if not isinstance(metadata, dict):
+            metadata = {}
+
+        payload_version = metadata.get("version")
+        if payload_version is not None:
+            version_str = _normalize_version(str(payload_version))
+            self.version = version_str
+
+        self.config_file = str(path)
+        self.current_state = serialized_state
+        self.baseline_state = serialized_state
+        saved_at_value = metadata.get("saved_at")
+        if saved_at_value:
+            self.saved_at = str(saved_at_value)
+        else:
+            self.saved_at = ""
+
+        file_entry = _file_binding_entry(path)
+        self.files = json.dumps([file_entry])
+        self.file_count = 1
+
+    def _parse_state(self, value: str) -> Dict[str, Any]:
+        if not value:
+            return {}
+
+        try:
+            parsed = json.loads(value)
+        except json.JSONDecodeError:
+            return {}
+
+        if isinstance(parsed, dict):
+            return parsed
+
+        return {}
+
+    @property
+    def current_data(self) -> Dict[str, Any]:
+        """Return the parsed current_state JSON payload as a dict."""
+
+        return self._parse_state(self.current_state)
+
+    @property
+    def baseline_data(self) -> Dict[str, Any]:
+        """Return the parsed baseline_state JSON payload as a dict."""
+
+        return self._parse_state(self.baseline_state)
+
+    @property
+    def is_dirty(self) -> bool:
+        """True if the current state differs from the last saved baseline."""
+
+        return self.current_data != self.baseline_data
+
+    @traitlets.validate("config_file")
+    def _validate_config_file(self, proposal: traitlets.Bunch) -> str:
+        return _resolve_config_path(proposal["value"])
+
+    @traitlets.observe("config_file")
+    def _observe_config_file(self, change: traitlets.Bunch) -> None:
+        value = change["new"]
+        if value:
+            self.config_file_display = Path(value).name
+        else:
+            self.config_file_display = ""

dr_widget/widgets/config_file_manager/components.json

@@ -0,0 +1,16 @@
+{
+	"$schema": "https://shadcn-svelte.com/schema.json",
+	"tailwind": {
+		"css": "src/app.css",
+		"baseColor": "slate"
+	},
+	"aliases": {
+		"components": "$lib/components",
+		"utils": "$lib/utils",
+		"ui": "$lib/components/ui",
+		"hooks": "$lib/hooks",
+		"lib": "$lib"
+	},
+	"typescript": true,
+	"registry": "https://shadcn-svelte.com/registry"
+}

dr_widget/widgets/config_file_manager/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>File Drop Widget - Dev Preview</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>

dr_widget/widgets/config_file_manager/jsrepo.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://unpkg.com/jsrepo@2.5.1/schemas/project-config.json",
+  "repos": ["@ieedan/shadcn-svelte-extras"],
+  "includeTests": false,
+  "includeDocs": false,
+  "watermark": true,
+  "formatter": "prettier",
+  "configFiles": {
+    "Shadcn Svelte Extras Cursor Rules": "./../../../../.cursor/rules/shadcn-svelte-extras.mdc"
+  },
+  "paths": {
+    "*": "./src/lib",
+    "ui": "./src/lib/components/ui",
+    "actions": "./src/lib/actions",
+    "hooks": "./src/lib/hooks",
+    "utils": "./src/lib/utils"
+  }
+}

dr_widget/widgets/config_file_manager/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@dr-widget/config-file-manager",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite dev",
+    "preview": "vite preview",
+    "check": "svelte-check --watch --tsconfig ./tsconfig.json"
+  },
+  "dependencies": {
+    "@anywidget/svelte": "^0.1.0",
+    "@zerodevx/svelte-json-view": "^1.0.11",
+    "elkjs": "^0.11.0",
+    "lucide-svelte": "^0.552.0",
+    "react": "18.2.0",
+    "react-dom": "18.2.0",
+    "react-zoom-pan-pinch": "^3.7.0",
+    "reaflow": "^5.4.1",
+    "svelte": "^5.43.2"
+  },
+  "devDependencies": {
+    "@internationalized/date": "^3.8.1",
+    "@lucide/svelte": "^0.544.0",
+    "@sveltejs/vite-plugin-svelte": "^4.0.0",
+    "@tailwindcss/postcss": "^4.0.9",
+    "@types/bun": "latest",
+    "@types/react": "18.2.74",
+    "@types/react-dom": "18.2.25",
+    "@vitejs/plugin-react-swc": "3.7.0",
+    "autoprefixer": "^10.4.20",
+    "bits-ui": "^2.11.0",
+    "clsx": "^2.1.1",
+    "postcss": "^8.4.49",
+    "prettier": "^3.6.2",
+    "runed": "^0.31.1",
+    "svelte-check": "^4.3.3",
+    "tailwind-merge": "^3.3.1",
+    "tailwind-variants": "^3.1.1",
+    "tailwindcss": "^4.1.16",
+    "tw-animate-css": "^1.4.0",
+    "vaul-svelte": "1.0.0-next.7",
+    "vite": "^5.4.11"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

dr_widget/widgets/config_file_manager/postcss.config.js

@@ -0,0 +1,6 @@
+import tailwindcss from '@tailwindcss/postcss';
+import autoprefixer from 'autoprefixer';
+
+export default {
+  plugins: [tailwindcss(), autoprefixer()]
+};

dr_widget/widgets/config_file_manager/public/vite.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>

dr_widget/widgets/config_file_manager/src/App.svelte

@@ -0,0 +1,62 @@
+<script>
+  import { Separator } from "./lib/components/ui/separator/";
+  import ConfigFileManager from "./ConfigFileManager.svelte";
+
+  // Simulate anywidget bindings for testing
+  let bindings = $state({
+    files: "",
+    file_count: 0,
+    error: "",
+  });
+</script>
+
+<main class="mx-auto max-w-5xl p-8 font-sans">
+  <div class="flex flex-col gap-8">
+    <div class="space-y-2">
+      <h1 class="text-3xl font-semibold text-zinc-900 dark:text-zinc-100">
+        Widget
+      </h1>
+    </div>
+
+    <ConfigFileManager {bindings} />
+
+    <div
+      class="mt-4 rounded-lg border border-zinc-200 bg-zinc-50 p-6 dark:border-zinc-700 dark:bg-zinc-900"
+    >
+      <h2 class="text-lg font-medium text-zinc-800 dark:text-zinc-100">
+        Debug Output
+      </h2>
+
+      <div
+        class="mt-4 rounded-md bg-white p-3 text-sm shadow-sm dark:bg-zinc-800"
+      >
+        <strong class="font-semibold text-zinc-700 dark:text-zinc-200"
+          >File Count:</strong
+        >
+        <span class="ml-2 text-zinc-600 dark:text-zinc-300"
+          >{bindings.file_count}</span
+        >
+      </div>
+
+      <div
+        class="mt-4 rounded-md bg-white p-3 text-sm shadow-sm dark:bg-zinc-800"
+      >
+        <strong class="font-semibold text-zinc-700 dark:text-zinc-200"
+          >Files Data:</strong
+        >
+        <pre
+          class="mt-2 overflow-x-auto rounded-md bg-zinc-900/10 p-2 font-mono text-xs dark:bg-zinc-50/10">
+{bindings.files || "(empty)"}</pre>
+      </div>
+
+      {#if bindings.error}
+        <div
+          class="mt-4 rounded-md border border-red-200 bg-red-50 p-3 text-sm text-red-600 dark:border-red-500/40 dark:bg-red-950/40 dark:text-red-300"
+        >
+          <strong class="font-semibold">Error:</strong>
+          <span class="ml-2">{bindings.error}</span>
+        </div>
+      {/if}
+    </div>
+  </div>
+</main>