@rainbow-robotics/plugin-ui 1.10.1-dev.1 → 1.10.2-dev.0

package/src/host.tsx

@@ -1,277 +1,277 @@
-/**
- * Host mounting (nexus only). A plugin renders directly in the host document —
- * no iframe. Two strategies, per `PluginModuleSource.kind` (see ./pluginData):
- *
- * - "esm" (built plugin / robot runtime): dynamic `import()` of the plugin's
- *   built entry. react / react-dom / rb-components / plugin-ui are external bare
- *   specifiers, resolved by the host page's import map to the host's own loaded
- *   instances (see ./viteHost.ts). So the plugin shares the host's React,
- *   rb-components, and RbContext, with no duplicate React instance.
- *
- * - "dev" (`muscat-pk dev`): the plugin's Vite dev server serves a bootstrap
- *   module exposing `mount(container, opts)`, mounted as an independent React
- *   root using the plugin's own deps. HostServices passed in are plain
- *   functions (see ./host-ui), so they cross the React-instance boundary safely.
- */
-import {
-  useCallback,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-  type ComponentType,
-} from "react";
-// Import shared modules via the package specifier, NOT relative paths. This
-// file ships as source (exports "./host" -> src/host.tsx), while /sdk, /ws,
-// /host-ui ship as dist/*.js. A relative "./sdk" would bundle src/sdk.ts,
-// whereas the plugin (and nexus's pluginShared) load dist/sdk.js via the
-// import map — two RbContext instances, so the host's <RbContext.Provider>
-// and the plugin's useRb() would read different contexts and every rb.* call
-// would hit the no-op "outside of a host context" fallback.
-import type { RbSdk } from "@rainbow-robotics/plugin-ui/sdk";
-import { RbContext } from "@rainbow-robotics/plugin-ui/sdk";
-import { RbWs, createLazyRbSdk } from "@rainbow-robotics/plugin-ui/ws";
-import { getHostServices } from "@rainbow-robotics/plugin-ui/host-ui";
-import { usePluginData, type PluginModuleSource } from "./pluginData";
-
-function pluginRootAttrs(pluginId: string) {
-  return {
-    "data-muscat-plugin-root": "",
-    "data-muscat-plugin-id": pluginId,
-  };
-}
-
-/* -------------------------------------------------------------------------- */
-/* rb sdk — pub/sub/action/serve over the plugin's Zenoh WebSocket             */
-/* -------------------------------------------------------------------------- */
-
-/** Per-mount host-provided bits (initial data + save registration). */
-type PluginMount = {
-  data?: unknown;
-  onSave: (getPayload: () => unknown) => () => void;
-};
-
-function useRbSdk(
-  socketUrl: string,
-  pluginId: string,
-  mount: PluginMount,
-): RbSdk {
-  const wsRef = useRef<Promise<RbWs> | null>(null);
-  const keyRef = useRef("");
-  const key = `${socketUrl}::${pluginId}`;
-  if (keyRef.current !== key) {
-    keyRef.current = key;
-    wsRef.current = RbWs.connect(socketUrl, pluginId);
-  }
-
-  return useMemo<RbSdk>(
-    // `mount.data` is captured at first render (stable for a form's lifetime);
-    // `mount.onSave` is a stable callback. Both intentionally out of deps.
-    () => createLazyRbSdk(wsRef.current!, getHostServices(), mount),
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [key],
-  );
-}
-
-/* -------------------------------------------------------------------------- */
-/* ESM mount (prod / robot runtime — import map resolves shared externals)      */
-/* -------------------------------------------------------------------------- */
-
-function EsmPluginHost({
-  source,
-  socketUrl,
-  pluginId,
-  mount,
-}: {
-  source: Extract<PluginModuleSource, { kind: "esm" }>;
-  socketUrl: string;
-  pluginId: string;
-  mount: PluginMount;
-}) {
-  const rb = useRbSdk(socketUrl, pluginId, mount);
-  const [App, setApp] = useState<ComponentType | null>(null);
-  const [error, setError] = useState<Error | null>(null);
-
-  useEffect(() => {
-    let cancelled = false;
-    setApp(null);
-    setError(null);
-    import(/* @vite-ignore */ source.entryUrl)
-      .then((mod: { default?: ComponentType }) => {
-        if (cancelled) return;
-        if (!mod.default) {
-          throw new Error(
-            `plugin entry ${source.entryUrl} has no default export`,
-          );
-        }
-        setApp(() => mod.default!);
-      })
-      .catch((e: unknown) => {
-        if (!cancelled) setError(e instanceof Error ? e : new Error(String(e)));
-      });
-    return () => {
-      cancelled = true;
-    };
-  }, [source.entryUrl]);
-
-  if (error) {
-    return (
-      <div className="text-fg-danger p-4 text-sm">
-        Failed to load plugin: {error.message}
-      </div>
-    );
-  }
-  if (!App) {
-    return (
-      <div className="flex items-center justify-center p-4">
-        <div className="border-default size-5 animate-spin rounded-full border-2 border-t-transparent" />
-      </div>
-    );
-  }
-  return (
-    <div {...pluginRootAttrs(pluginId)}>
-      <RbContext.Provider value={rb}>
-        <App />
-      </RbContext.Provider>
-    </div>
-  );
-}
-
-/* -------------------------------------------------------------------------- */
-/* Dev mount (muscat-pk dev)                                                    */
-/* -------------------------------------------------------------------------- */
-
-interface DevBootstrapModule {
-  mount: (
-    container: HTMLElement,
-    opts: {
-      socketUrl: string;
-      pluginId: string;
-      hostServices: ReturnType<typeof getHostServices>;
-      data?: unknown;
-      onSave: PluginMount["onSave"];
-    },
-  ) => () => void;
-}
-
-function DevPluginHost({
-  source,
-  socketUrl,
-  pluginId,
-  mount,
-}: {
-  source: Extract<PluginModuleSource, { kind: "dev" }>;
-  socketUrl: string;
-  pluginId: string;
-  mount: PluginMount;
-}) {
-  const containerRef = useRef<HTMLDivElement>(null);
-  const [error, setError] = useState<Error | null>(null);
-
-  useEffect(() => {
-    const container = containerRef.current;
-    if (!container) return;
-    let unmount: (() => void) | undefined;
-    let cancelled = false;
-    const deferUnmount = () => queueMicrotask(() => unmount?.());
-
-    import(/* @vite-ignore */ source.bootstrapUrl)
-      .then((mod: DevBootstrapModule) => {
-        if (cancelled) return;
-        unmount = mod.mount(container, {
-          socketUrl,
-          pluginId,
-          hostServices: getHostServices(),
-          data: mount.data,
-          onSave: mount.onSave,
-        });
-      })
-      .catch((e: unknown) => {
-        if (!cancelled) setError(e instanceof Error ? e : new Error(String(e)));
-      });
-
-    return () => {
-      cancelled = true;
-      deferUnmount();
-    };
-  }, [source.bootstrapUrl, socketUrl, pluginId]);
-
-  if (error) {
-    return (
-      <div className="text-fg-danger p-4 text-sm">
-        Failed to load plugin (dev): {error.message}
-      </div>
-    );
-  }
-  return <div ref={containerRef} {...pluginRootAttrs(pluginId)} />;
-}
-
-/* -------------------------------------------------------------------------- */
-/* Entry point                                                                  */
-/* -------------------------------------------------------------------------- */
-
-/** Renders a plugin's UI. Requires a `PluginDataProvider` above. */
-export function PluginHost({
-  pluginId,
-  ui,
-  data,
-  onRegisterSave,
-}: {
-  pluginId: string;
-  ui: string;
-  /** Initial data handed to the plugin (e.g. previously-saved form values). */
-  data?: unknown;
-  /**
-   * Called once with a getter the host can invoke (e.g. from a Save button) to
-   * collect the plugin's current payload — `undefined` until the plugin
-   * registers via `useRbSave`, or if it never does.
-   */
-  onRegisterSave?: (getPayload: () => unknown) => void;
-}) {
-  const { getModuleSource, getSocketUrl } = usePluginData();
-  const source = useMemo(
-    () => getModuleSource(pluginId, ui),
-    [getModuleSource, pluginId, ui],
-  );
-  const socketUrl = getSocketUrl(pluginId);
-
-  // The plugin registers its payload getter here; the host reads it back
-  // through the stable getter handed to `onRegisterSave`.
-  const saveRef = useRef<(() => unknown) | null>(null);
-  const registerSave = useCallback((getPayload: () => unknown) => {
-    saveRef.current = getPayload;
-    return () => {
-      if (saveRef.current === getPayload) saveRef.current = null;
-    };
-  }, []);
-
-  useEffect(() => {
-    onRegisterSave?.(() => saveRef.current?.());
-  }, [onRegisterSave]);
-
-  const mount = useMemo<PluginMount>(
-    // data captured once (stable per form lifetime); registerSave is stable.
-    () => ({ data, onSave: registerSave }),
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [registerSave],
-  );
-
-  if (source.kind === "dev") {
-    return (
-      <DevPluginHost
-        source={source}
-        socketUrl={socketUrl}
-        pluginId={pluginId}
-        mount={mount}
-      />
-    );
-  }
-  return (
-    <EsmPluginHost
-      source={source}
-      socketUrl={socketUrl}
-      pluginId={pluginId}
-      mount={mount}
-    />
-  );
-}
+/**
+ * Host mounting (nexus only). A plugin renders directly in the host document —
+ * no iframe. Two strategies, per `PluginModuleSource.kind` (see ./pluginData):
+ *
+ * - "esm" (built plugin / robot runtime): dynamic `import()` of the plugin's
+ *   built entry. react / react-dom / rb-components / plugin-ui are external bare
+ *   specifiers, resolved by the host page's import map to the host's own loaded
+ *   instances (see ./viteHost.ts). So the plugin shares the host's React,
+ *   rb-components, and RbContext, with no duplicate React instance.
+ *
+ * - "dev" (`muscat-pk dev`): the plugin's Vite dev server serves a bootstrap
+ *   module exposing `mount(container, opts)`, mounted as an independent React
+ *   root using the plugin's own deps. HostServices passed in are plain
+ *   functions (see ./host-ui), so they cross the React-instance boundary safely.
+ */
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentType,
+} from "react";
+// Import shared modules via the package specifier, NOT relative paths. This
+// file ships as source (exports "./host" -> src/host.tsx), while /sdk, /ws,
+// /host-ui ship as dist/*.js. A relative "./sdk" would bundle src/sdk.ts,
+// whereas the plugin (and nexus's pluginShared) load dist/sdk.js via the
+// import map — two RbContext instances, so the host's <RbContext.Provider>
+// and the plugin's useRb() would read different contexts and every rb.* call
+// would hit the no-op "outside of a host context" fallback.
+import type { RbSdk } from "@rainbow-robotics/plugin-ui/sdk";
+import { RbContext } from "@rainbow-robotics/plugin-ui/sdk";
+import { RbWs, createLazyRbSdk } from "@rainbow-robotics/plugin-ui/ws";
+import { getHostServices } from "@rainbow-robotics/plugin-ui/host-ui";
+import { usePluginData, type PluginModuleSource } from "./pluginData";
+
+function pluginRootAttrs(pluginId: string) {
+  return {
+    "data-muscat-plugin-root": "",
+    "data-muscat-plugin-id": pluginId,
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/* rb sdk — pub/sub/action/serve over the plugin's Zenoh WebSocket             */
+/* -------------------------------------------------------------------------- */
+
+/** Per-mount host-provided bits (initial data + save registration). */
+type PluginMount = {
+  data?: unknown;
+  onSave: (getPayload: () => unknown) => () => void;
+};
+
+function useRbSdk(
+  socketUrl: string,
+  pluginId: string,
+  mount: PluginMount,
+): RbSdk {
+  const wsRef = useRef<Promise<RbWs> | null>(null);
+  const keyRef = useRef("");
+  const key = `${socketUrl}::${pluginId}`;
+  if (keyRef.current !== key) {
+    keyRef.current = key;
+    wsRef.current = RbWs.connect(socketUrl, pluginId);
+  }
+
+  return useMemo<RbSdk>(
+    // `mount.data` is captured at first render (stable for a form's lifetime);
+    // `mount.onSave` is a stable callback. Both intentionally out of deps.
+    () => createLazyRbSdk(wsRef.current!, getHostServices(), mount),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [key],
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/* ESM mount (prod / robot runtime — import map resolves shared externals)      */
+/* -------------------------------------------------------------------------- */
+
+function EsmPluginHost({
+  source,
+  socketUrl,
+  pluginId,
+  mount,
+}: {
+  source: Extract<PluginModuleSource, { kind: "esm" }>;
+  socketUrl: string;
+  pluginId: string;
+  mount: PluginMount;
+}) {
+  const rb = useRbSdk(socketUrl, pluginId, mount);
+  const [App, setApp] = useState<ComponentType | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    setApp(null);
+    setError(null);
+    import(/* @vite-ignore */ source.entryUrl)
+      .then((mod: { default?: ComponentType }) => {
+        if (cancelled) return;
+        if (!mod.default) {
+          throw new Error(
+            `plugin entry ${source.entryUrl} has no default export`,
+          );
+        }
+        setApp(() => mod.default!);
+      })
+      .catch((e: unknown) => {
+        if (!cancelled) setError(e instanceof Error ? e : new Error(String(e)));
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [source.entryUrl]);
+
+  if (error) {
+    return (
+      <div className="text-fg-danger p-4 text-sm">
+        Failed to load plugin: {error.message}
+      </div>
+    );
+  }
+  if (!App) {
+    return (
+      <div className="flex items-center justify-center p-4">
+        <div className="border-default size-5 animate-spin rounded-full border-2 border-t-transparent" />
+      </div>
+    );
+  }
+  return (
+    <div {...pluginRootAttrs(pluginId)}>
+      <RbContext.Provider value={rb}>
+        <App />
+      </RbContext.Provider>
+    </div>
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/* Dev mount (muscat-pk dev)                                                    */
+/* -------------------------------------------------------------------------- */
+
+interface DevBootstrapModule {
+  mount: (
+    container: HTMLElement,
+    opts: {
+      socketUrl: string;
+      pluginId: string;
+      hostServices: ReturnType<typeof getHostServices>;
+      data?: unknown;
+      onSave: PluginMount["onSave"];
+    },
+  ) => () => void;
+}
+
+function DevPluginHost({
+  source,
+  socketUrl,
+  pluginId,
+  mount,
+}: {
+  source: Extract<PluginModuleSource, { kind: "dev" }>;
+  socketUrl: string;
+  pluginId: string;
+  mount: PluginMount;
+}) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+    let unmount: (() => void) | undefined;
+    let cancelled = false;
+    const deferUnmount = () => queueMicrotask(() => unmount?.());
+
+    import(/* @vite-ignore */ source.bootstrapUrl)
+      .then((mod: DevBootstrapModule) => {
+        if (cancelled) return;
+        unmount = mod.mount(container, {
+          socketUrl,
+          pluginId,
+          hostServices: getHostServices(),
+          data: mount.data,
+          onSave: mount.onSave,
+        });
+      })
+      .catch((e: unknown) => {
+        if (!cancelled) setError(e instanceof Error ? e : new Error(String(e)));
+      });
+
+    return () => {
+      cancelled = true;
+      deferUnmount();
+    };
+  }, [source.bootstrapUrl, socketUrl, pluginId]);
+
+  if (error) {
+    return (
+      <div className="text-fg-danger p-4 text-sm">
+        Failed to load plugin (dev): {error.message}
+      </div>
+    );
+  }
+  return <div ref={containerRef} {...pluginRootAttrs(pluginId)} />;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Entry point                                                                  */
+/* -------------------------------------------------------------------------- */
+
+/** Renders a plugin's UI. Requires a `PluginDataProvider` above. */
+export function PluginHost({
+  pluginId,
+  ui,
+  data,
+  onRegisterSave,
+}: {
+  pluginId: string;
+  ui: string;
+  /** Initial data handed to the plugin (e.g. previously-saved form values). */
+  data?: unknown;
+  /**
+   * Called once with a getter the host can invoke (e.g. from a Save button) to
+   * collect the plugin's current payload — `undefined` until the plugin
+   * registers via `useRbSave`, or if it never does.
+   */
+  onRegisterSave?: (getPayload: () => unknown) => void;
+}) {
+  const { getModuleSource, getSocketUrl } = usePluginData();
+  const source = useMemo(
+    () => getModuleSource(pluginId, ui),
+    [getModuleSource, pluginId, ui],
+  );
+  const socketUrl = getSocketUrl(pluginId);
+
+  // The plugin registers its payload getter here; the host reads it back
+  // through the stable getter handed to `onRegisterSave`.
+  const saveRef = useRef<(() => unknown) | null>(null);
+  const registerSave = useCallback((getPayload: () => unknown) => {
+    saveRef.current = getPayload;
+    return () => {
+      if (saveRef.current === getPayload) saveRef.current = null;
+    };
+  }, []);
+
+  useEffect(() => {
+    onRegisterSave?.(() => saveRef.current?.());
+  }, [onRegisterSave]);
+
+  const mount = useMemo<PluginMount>(
+    // data captured once (stable per form lifetime); registerSave is stable.
+    () => ({ data, onSave: registerSave }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [registerSave],
+  );
+
+  if (source.kind === "dev") {
+    return (
+      <DevPluginHost
+        source={source}
+        socketUrl={socketUrl}
+        pluginId={pluginId}
+        mount={mount}
+      />
+    );
+  }
+  return (
+    <EsmPluginHost
+      source={source}
+      socketUrl={socketUrl}
+      pluginId={pluginId}
+      mount={mount}
+    />
+  );
+}

package/src/index.d.ts

@@ -1 +1 @@
-/// <reference types="@repo/typescript-config" />
+/// <reference types="@repo/typescript-config" />