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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dr-widget
-Version: 0.2.1
+Version: 0.2.2
 Summary: Widgets to use with marimo notebooks
 Author: Danielle Rothermel
 Author-email: Danielle Rothermel <danielle.rothermel@gmail.com>

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

@@ -1,6 +1,6 @@
 [project]
 name = "dr-widget"
-version = "0.2.1"
+version = "0.2.2"
 description = "Widgets to use with marimo notebooks"
 readme = "README.md"
 authors = [

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;
+}