dr-widget 0.2.0__tar.gz → 0.2.2__tar.gz

{dr_widget-0.2.0 → dr_widget-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dr-widget
-Version: 0.2.0
+Version: 0.2.2
 Summary: Widgets to use with marimo notebooks
 Author: Danielle Rothermel
 Author-email: Danielle Rothermel <danielle.rothermel@gmail.com>
@@ -22,35 +22,18 @@ The top-level `dr_widget` package is intentionally empty so importing from one t
 
 ## Quick Start
 
-```bash
-# Install JS dependencies (root + workspace)
-bun install
-
-# Live-reload the Config File Manager widget in a browser
-bun run dev:config-file-manager
-
-# Produce the optimized bundle used by AnyWidget
-bun run build
-
-# Build the Python distributions (wheel + sdist)
-uv build
-
-# Launch the Marimo demo notebook
-marimo run notebooks/config_file_manager_widget.py
-```
-
-Prerequisites: Bun ≥ 1.0, Node-compatible environment, Python ≥ 3.11 with `uv`, and Marimo ≥ 0.23.
+See [Development Workflow](docs/development.md) for install, build, packaging, and
+notebook commands.
 
 ## Repository Layout
 
 - `src/dr_widget/` – Python package with two widget tiers.
-  - `inline/` – pure-Python AnyWidgets (e.g., `ActiveHtml`) with `_esm` as a string literal.
-  - `bundled/config_file_manager/` – bundled widget workspace (Svelte source in `src/`, build output in `static/`).
-    - `src/ConfigFileManager.svelte` – orchestration layer wiring bindings into the panel components.
-    - `src/lib/hooks/use-file-bindings.ts` – shared logic for syncing AnyWidget traitlets.
-    - `src/lib/components/` – shadcn-style UI primitives and panels, including a config viewer card with both a tree view and graph view for JSON payloads.
+  - `inline/` – pure-Python AnyWidgets (e.g., `ActiveHtml`, `load_dr_runtime()`).
+  - `bundled/config_file_manager/` – Svelte widget workspace (source in `src/`, build output in `static/`).
+  - `bundled/runtime/` – React custom-element runtime (`static/runtime.js`); proof element `<dr-hello>`.
 - `docs/` – additional reference material (architecture, development workflows).
-- `notebooks/config_file_manager_widget.py` – Marimo notebook that exercises the Config File Manager widget.
+- `notebooks/config_file_manager_widget.py` – Marimo notebook for the Config File Manager widget.
+- `notebooks/runtime_hello_widget.py` – Marimo notebook for `load_dr_runtime()` + `<dr-hello>`.
 
 ## Documentation
 
@@ -61,8 +44,7 @@ Prerequisites: Bun ≥ 1.0, Node-compatible environment, Python ≥ 3.11 with `u
 ## Contributing
 
 1. Work inside a dedicated branch.
-2. Run `bun run build`, `npx svelte-check`, and `uv build` before opening a PR.
-3. Update the notebook and docs when you add or change widget behaviour.
-4. Follow the commit and PR practices outlined in `AGENTS.md`.
+2. Follow [docs/development.md](docs/development.md) and [AGENTS.md](AGENTS.md) before opening a PR.
+3. Update notebooks and docs when you add or change widget behaviour.
 
 Please open an issue if you hit build problems or want to discuss new widgets.

{dr_widget-0.2.0 → dr_widget-0.2.2}/README.md

@@ -9,35 +9,18 @@ The top-level `dr_widget` package is intentionally empty so importing from one t
 
 ## Quick Start
 
-```bash
-# Install JS dependencies (root + workspace)
-bun install
-
-# Live-reload the Config File Manager widget in a browser
-bun run dev:config-file-manager
-
-# Produce the optimized bundle used by AnyWidget
-bun run build
-
-# Build the Python distributions (wheel + sdist)
-uv build
-
-# Launch the Marimo demo notebook
-marimo run notebooks/config_file_manager_widget.py
-```
-
-Prerequisites: Bun ≥ 1.0, Node-compatible environment, Python ≥ 3.11 with `uv`, and Marimo ≥ 0.23.
+See [Development Workflow](docs/development.md) for install, build, packaging, and
+notebook commands.
 
 ## Repository Layout
 
 - `src/dr_widget/` – Python package with two widget tiers.
-  - `inline/` – pure-Python AnyWidgets (e.g., `ActiveHtml`) with `_esm` as a string literal.
-  - `bundled/config_file_manager/` – bundled widget workspace (Svelte source in `src/`, build output in `static/`).
-    - `src/ConfigFileManager.svelte` – orchestration layer wiring bindings into the panel components.
-    - `src/lib/hooks/use-file-bindings.ts` – shared logic for syncing AnyWidget traitlets.
-    - `src/lib/components/` – shadcn-style UI primitives and panels, including a config viewer card with both a tree view and graph view for JSON payloads.
+  - `inline/` – pure-Python AnyWidgets (e.g., `ActiveHtml`, `load_dr_runtime()`).
+  - `bundled/config_file_manager/` – Svelte widget workspace (source in `src/`, build output in `static/`).
+  - `bundled/runtime/` – React custom-element runtime (`static/runtime.js`); proof element `<dr-hello>`.
 - `docs/` – additional reference material (architecture, development workflows).
-- `notebooks/config_file_manager_widget.py` – Marimo notebook that exercises the Config File Manager widget.
+- `notebooks/config_file_manager_widget.py` – Marimo notebook for the Config File Manager widget.
+- `notebooks/runtime_hello_widget.py` – Marimo notebook for `load_dr_runtime()` + `<dr-hello>`.
 
 ## Documentation
 
@@ -48,8 +31,7 @@ Prerequisites: Bun ≥ 1.0, Node-compatible environment, Python ≥ 3.11 with `u
 ## Contributing
 
 1. Work inside a dedicated branch.
-2. Run `bun run build`, `npx svelte-check`, and `uv build` before opening a PR.
-3. Update the notebook and docs when you add or change widget behaviour.
-4. Follow the commit and PR practices outlined in `AGENTS.md`.
+2. Follow [docs/development.md](docs/development.md) and [AGENTS.md](AGENTS.md) before opening a PR.
+3. Update notebooks and docs when you add or change widget behaviour.
 
 Please open an issue if you hit build problems or want to discuss new widgets.

{dr_widget-0.2.0 → dr_widget-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dr-widget"
-version = "0.2.0"
+version = "0.2.2"
 description = "Widgets to use with marimo notebooks"
 readme = "README.md"
 authors = [
@@ -19,10 +19,15 @@ requires = ["uv_build>=0.9.7,<0.10.0"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]
-source-include = ["src/dr_widget/bundled/config_file_manager/static/**"]
+source-include = [
+    "src/dr_widget/bundled/config_file_manager/static/**",
+    "src/dr_widget/bundled/runtime/static/**",
+]
 source-exclude = [
     "src/dr_widget/bundled/config_file_manager/node_modules",
     "src/dr_widget/bundled/config_file_manager/node_modules/**",
+    "src/dr_widget/bundled/runtime/node_modules",
+    "src/dr_widget/bundled/runtime/node_modules/**",
 ]
 
 [dependency-groups]

dr_widget-0.2.2/src/dr_widget/bundled/runtime/.gitignore

@@ -0,0 +1,2 @@
+node_modules
+*.local

dr_widget-0.2.2/src/dr_widget/bundled/runtime/index.html

@@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>dr-hello runtime demo</title>
+  </head>
+  <body>
+    <h1>dr_widget runtime demo</h1>
+    <p>
+      <dr-hello id="hello" name="World"></dr-hello>
+    </p>
+    <label>
+      Name
+      <input id="name-input" type="text" value="World" />
+    </label>
+    <button id="apply-name" type="button">Apply name attribute</button>
+
+    <script type="module" src="/src/index.tsx"></script>
+    <script type="module">
+      const hello = document.getElementById('hello');
+      const input = document.getElementById('name-input');
+      const button = document.getElementById('apply-name');
+
+      button.addEventListener('click', () => {
+        hello.setAttribute('name', input.value);
+      });
+    </script>
+  </body>
+</html>

dr_widget-0.2.2/src/dr_widget/bundled/runtime/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@dr-widget/runtime",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite dev",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "18.2.0",
+    "react-dom": "18.2.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "18.2.74",
+    "@types/react-dom": "18.2.25",
+    "@vitejs/plugin-react-swc": "3.7.0",
+    "vite": "^5.4.11"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

dr_widget-0.2.2/src/dr_widget/bundled/runtime/parity.html

@@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>dr-hello built runtime parity</title>
+  </head>
+  <body>
+    <h1>Built runtime parity</h1>
+    <p>
+      <dr-hello id="hello" name="World"></dr-hello>
+    </p>
+    <label>
+      Name
+      <input id="name-input" type="text" value="World" />
+    </label>
+    <button id="apply-name" type="button">Apply name attribute</button>
+
+    <script src="./static/runtime.js"></script>
+    <script>
+      const hello = document.getElementById('hello');
+      const input = document.getElementById('name-input');
+      const button = document.getElementById('apply-name');
+
+      button.addEventListener('click', () => {
+        hello.setAttribute('name', input.value);
+      });
+    </script>
+  </body>
+</html>

dr_widget-0.2.2/src/dr_widget/bundled/runtime/src/components/Hello.tsx

@@ -0,0 +1,8 @@
+type HelloProps = {
+  name?: string;
+};
+
+export function Hello({ name }: HelloProps) {
+  const label = name?.trim() || 'World';
+  return <span>Hello, {label}!</span>;
+}

dr_widget-0.2.2/src/dr_widget/bundled/runtime/src/components/PropsPanel.tsx

@@ -0,0 +1,30 @@
+type PropsPanelProps = {
+  title?: string;
+  items?: string[];
+  __dataRef?: string;
+};
+
+export function PropsPanel({ title, items }: PropsPanelProps) {
+  const heading =
+    typeof title === 'string' && title.trim().length > 0
+      ? title.trim()
+      : 'Props panel';
+  const rows = Array.isArray(items)
+    ? items.filter((item): item is string => typeof item === 'string')
+    : [];
+
+  return (
+    <div>
+      <strong>{heading}</strong>
+      {rows.length > 0 ? (
+        <ul>
+          {rows.map((item) => (
+            <li key={item}>{item}</li>
+          ))}
+        </ul>
+      ) : (
+        <p>No items.</p>
+      )}
+    </div>
+  );
+}

dr_widget-0.2.2/src/dr_widget/bundled/runtime/src/data-channel.ts

@@ -0,0 +1,52 @@
+export type DataChannelListener = (payload: unknown) => void;
+
+export type DataChannel = {
+  set: (id: string, payload: unknown) => void;
+  get: (id: string) => unknown;
+  delete: (id: string) => void;
+  subscribe: (id: string, listener: DataChannelListener) => () => void;
+};
+
+export function createDataChannel(): DataChannel {
+  const payloads = new Map<string, unknown>();
+  const listeners = new Map<string, Set<DataChannelListener>>();
+
+  function notify(id: string, payload: unknown): void {
+    const subs = listeners.get(id);
+    if (!subs) {
+      return;
+    }
+    for (const listener of subs) {
+      listener(payload);
+    }
+  }
+
+  return {
+    set(id, payload) {
+      payloads.set(id, payload);
+      notify(id, payload);
+    },
+    get(id) {
+      return payloads.get(id);
+    },
+    delete(id) {
+      payloads.delete(id);
+      notify(id, undefined);
+    },
+    subscribe(id, listener) {
+      let subs = listeners.get(id);
+      if (!subs) {
+        subs = new Set();
+        listeners.set(id, subs);
+      }
+      subs.add(listener);
+      const currentSubs = subs;
+      return () => {
+        currentSubs.delete(listener);
+        if (currentSubs.size === 0 && listeners.get(id) === currentSubs) {
+          listeners.delete(id);
+        }
+      };
+    },
+  };
+}

dr_widget-0.2.2/src/dr_widget/bundled/runtime/src/define-element.tsx

@@ -0,0 +1,127 @@
+import {
+  createRoot,
+  type ComponentType,
+  type Root,
+} from 'react-dom/client';
+
+import type { DataChannel } from './data-channel';
+import {
+  DEFAULT_DATA_REF_ATTRIBUTE,
+  DEFAULT_PROPS_ATTRIBUTE,
+  parseElementProps,
+  readDataRef,
+  type ParsePropsOptions,
+} from './parse-props';
+
+export type DrElementOptions<P extends Record<string, unknown>> =
+  ParsePropsOptions & {
+    parseProps?: (
+      element: HTMLElement,
+      dataChannel: DataChannel,
+    ) => P;
+  };
+
+function isOptions<P extends Record<string, unknown>>(
+  value: readonly string[] | DrElementOptions<P>,
+): value is DrElementOptions<P> {
+  return !Array.isArray(value);
+}
+
+function resolveOptions<P extends Record<string, unknown>>(
+  observedAttributesOrOptions: readonly string[] | DrElementOptions<P>,
+): DrElementOptions<P> {
+  if (isOptions(observedAttributesOrOptions)) {
+    return observedAttributesOrOptions;
+  }
+  return { observedAttributes: observedAttributesOrOptions };
+}
+
+export function defineDrElement<P extends Record<string, unknown>>(
+  tag: string,
+  Component: ComponentType<P>,
+  observedAttributesOrOptions: readonly string[] | DrElementOptions<P>,
+  dataChannel: DataChannel,
+): void {
+  if (customElements.get(tag)) {
+    return;
+  }
+
+  const options = resolveOptions(observedAttributesOrOptions);
+  const propsAttribute = options.propsAttribute ?? DEFAULT_PROPS_ATTRIBUTE;
+  const dataRefAttribute = options.dataRefAttribute ?? DEFAULT_DATA_REF_ATTRIBUTE;
+
+  const readProps = (element: HTMLElement): P => {
+    if (options.parseProps) {
+      return options.parseProps(element, dataChannel);
+    }
+    return parseElementProps(element, dataChannel, options) as P;
+  };
+
+  class DrElement extends HTMLElement {
+    static get observedAttributes() {
+      const attrs = new Set<string>(options.observedAttributes ?? []);
+      attrs.add(propsAttribute);
+      attrs.add(dataRefAttribute);
+      return [...attrs];
+    }
+
+    #root: Root | null = null;
+    #unsubscribeData: (() => void) | null = null;
+
+    connectedCallback() {
+      this.#root = createRoot(this);
+      this.#bindDataChannel();
+      this.#render();
+    }
+
+    attributeChangedCallback(
+      name: string,
+      oldValue: string | null,
+      newValue: string | null,
+    ) {
+      if (oldValue === newValue) {
+        return;
+      }
+      if (!this.isConnected) {
+        return;
+      }
+      if (name === dataRefAttribute) {
+        this.#bindDataChannel();
+      }
+      this.#render();
+    }
+
+    disconnectedCallback() {
+      this.#unsubscribeData?.();
+      this.#unsubscribeData = null;
+      this.#root?.unmount();
+      this.#root = null;
+    }
+
+    #bindDataChannel() {
+      this.#unsubscribeData?.();
+      this.#unsubscribeData = null;
+
+      const dataRef = readDataRef(this, dataRefAttribute);
+      if (!dataRef) {
+        return;
+      }
+
+      this.#unsubscribeData = dataChannel.subscribe(dataRef, () => {
+        this.#render();
+      });
+    }
+
+    #render() {
+      if (!this.#root) {
+        return;
+      }
+      this.#root.render(<Component {...readProps(this)} />);
+    }
+  }
+
+  customElements.define(tag, DrElement);
+}
+
+export { whenLayoutReady } from './layout';
+export type { LayoutReadyCallback } from './layout';

dr_widget-0.2.2/src/dr_widget/bundled/runtime/src/globals.d.ts

@@ -0,0 +1,23 @@
+import type { ComponentType } from 'react';
+
+import type { DataChannel } from './data-channel';
+import type { DrElementOptions } from './define-element';
+
+export type DrRuntime = {
+  defineDrElement: <P extends Record<string, unknown>>(
+    tag: string,
+    Component: ComponentType<P>,
+    observedAttributesOrOptions: readonly string[] | DrElementOptions<P>,
+  ) => void;
+  data: DataChannel;
+  version: string;
+};
+
+declare global {
+  interface Window {
+    __drRuntime?: DrRuntime;
+    __drRuntimeLoaded?: boolean;
+  }
+}
+
+export {};

dr_widget-0.2.2/src/dr_widget/bundled/runtime/src/index.tsx

@@ -0,0 +1,17 @@
+import { Hello } from './components/Hello';
+import { PropsPanel } from './components/PropsPanel';
+import { createDataChannel } from './data-channel';
+import { defineDrElement } from './define-element';
+
+const RUNTIME_VERSION = '0.2.0';
+const dataChannel = createDataChannel();
+
+defineDrElement('dr-hello', Hello, ['name'], dataChannel);
+defineDrElement('dr-props-panel', PropsPanel, [], dataChannel);
+
+window.__drRuntime = {
+  defineDrElement: (tag, Component, observedAttributesOrOptions) =>
+    defineDrElement(tag, Component, observedAttributesOrOptions, dataChannel),
+  data: dataChannel,
+  version: RUNTIME_VERSION,
+};

dr_widget-0.2.2/src/dr_widget/bundled/runtime/src/layout.ts

@@ -0,0 +1,41 @@
+export type LayoutReadyCallback = (element: HTMLElement) => void;
+
+/**
+ * Run `callback` once the element has non-zero layout dimensions.
+ *
+ * Design rule 2: never read geometry in `connectedCallback` — layout may not
+ * be ready yet. Prefer this helper (rAF + ResizeObserver) for sizing work.
+ */
+export function whenLayoutReady(
+  element: HTMLElement,
+  callback: LayoutReadyCallback,
+): () => void {
+  let cancelled = false;
+  let completed = false;
+  let observer: ResizeObserver | null = null;
+
+  const run = () => {
+    if (cancelled || completed) {
+      return;
+    }
+    if (element.clientWidth > 0 || element.clientHeight > 0) {
+      completed = true;
+      callback(element);
+      observer?.disconnect();
+      observer = null;
+      return;
+    }
+    requestAnimationFrame(run);
+  };
+
+  observer = new ResizeObserver(() => {
+    run();
+  });
+  observer.observe(element);
+  requestAnimationFrame(run);
+
+  return () => {
+    cancelled = true;
+    observer?.disconnect();
+  };
+}

dr_widget-0.2.2/src/dr_widget/bundled/runtime/src/parse-props.ts

@@ -0,0 +1,85 @@
+import type { DataChannel } from './data-channel';
+
+export const DEFAULT_PROPS_ATTRIBUTE = 'data-props';
+export const DEFAULT_DATA_REF_ATTRIBUTE = 'data-ref';
+
+export type ParsePropsOptions = {
+  observedAttributes?: readonly string[];
+  propsAttribute?: string;
+  dataRefAttribute?: string;
+};
+
+export type ParsedProps = Record<string, unknown>;
+
+function parseJsonAttribute(
+  element: HTMLElement,
+  attributeName: string,
+): ParsedProps | undefined {
+  const raw = element.getAttribute(attributeName);
+  if (raw === null) {
+    return undefined;
+  }
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+      return parsed as ParsedProps;
+    }
+  } catch {
+    console.warn(
+      `[dr-runtime] Invalid JSON in ${attributeName} on <${element.tagName.toLowerCase()}>`,
+    );
+  }
+  return undefined;
+}
+
+function mergeChannelPayload(
+  props: ParsedProps,
+  payload: unknown,
+): ParsedProps {
+  if (payload === undefined) {
+    return props;
+  }
+  if (
+    typeof payload === 'object' &&
+    payload !== null &&
+    !Array.isArray(payload)
+  ) {
+    return { ...props, ...(payload as ParsedProps) };
+  }
+  return { ...props, data: payload };
+}
+
+export function parseElementProps(
+  element: HTMLElement,
+  dataChannel: DataChannel,
+  options: ParsePropsOptions = {},
+): ParsedProps {
+  const props: ParsedProps = {};
+  const observedAttributes = options.observedAttributes ?? [];
+
+  for (const name of observedAttributes) {
+    props[name] = element.getAttribute(name) ?? undefined;
+  }
+
+  const propsAttribute = options.propsAttribute ?? DEFAULT_PROPS_ATTRIBUTE;
+  const jsonProps = parseJsonAttribute(element, propsAttribute);
+  if (jsonProps) {
+    Object.assign(props, jsonProps);
+  }
+
+  const dataRefAttribute = options.dataRefAttribute ?? DEFAULT_DATA_REF_ATTRIBUTE;
+  const dataRef = element.getAttribute(dataRefAttribute);
+  if (dataRef) {
+    props.__dataRef = dataRef;
+    return mergeChannelPayload(props, dataChannel.get(dataRef));
+  }
+
+  return props;
+}
+
+export function readDataRef(
+  element: HTMLElement,
+  dataRefAttribute: string = DEFAULT_DATA_REF_ATTRIBUTE,
+): string | undefined {
+  return element.getAttribute(dataRefAttribute) ?? undefined;
+}